Repository navigation
v1.5.0
Leer documentos sin pagarlos completos. Un agente que lee un PDF directo paga ~1,500–3,000 tokens por página (Claude manda cada página como imagen + texto). Ahora Alexandria convierte el documento localmente a secciones y el agente pide solo lo que necesita.
Added
doc_ingest/doc_read(tools MCP, en los 11 agentes) yale ingest/ale docs/ale docs read(CLI). Formatos: PDF, DOCX, XLSX, CSV/TSV, HTML, MD, TXT — todo en JS puro, sin binarios nativos, cargado solo al usarse.doc_ingestdevuelve el índice de secciones (~200 tokens) con el costo estimado del original; si el archivo no cambió (sha256) no se reconvierte.doc_readentrega secciones por id o por pregunta, nunca pasa demax_tokensy siempre lista lo que quedó fuera. En hojas de cálculo, una pregunta devuelve las filas que coinciden, no bloques.- Medido con documentos reales: manual técnico de 10 páginas, ~20,000 tokens leído directo → índice ~248, respuesta a una pregunta ~179. Hoja de 2,016 filas, ~1.24 M tokens → resumen ~219, filas que coinciden ~579 en 0.12 s.
- PDF: encabezados por tamaño de fuente (mediana ponderada por caracteres; títulos de varias líneas se unen), página de origen para citar, comentarios
# …de código no se confunden con encabezados. PDFs escaneados (sin capa de texto) se avisan — no hay OCR. - Hojas: resumen por columna (tipo, valores distintos, ejemplos) + bloques de 50 filas; celdas gigantes (geometrías, JSON) recortadas.
- Intercepción en Claude Code (hook
PreToolUsesobreRead, toggledocs.interceptRead): la primera lectura directa de un PDF/DOCX/XLSX/CSV grande en la sesión se redirige adoc_ingest/doc_read; el segundo intento pasa, para cuando el agente de verdad necesita ver imágenes.ale doctorlo agrega solo a quien actualiza. ale statsmuestra el ahorro medido en documentos: tokens de los originales vs tokens realmente entregados.- El bloque de
CLAUDE.md/AGENTS.mdindica usardoc_ingest/doc_readen vez de leer binarios.
Design notes
- Los documentos viven en
Alexandria/docs/fuera del índice vectorial principal: el primer intento los indexaba y una hoja real de 2,016 filas tardó más de 10 minutos en embeberse.doc_readrankea sus propias secciones (BM25 + coseno normalizados, con corte relativo al mejor); los vectores por sección se calculan una vez por versión del documento y se guardan en caché. exceljstraeuuid<11 (moderado, GHSA-w5hq-g745-h8pq: falta de bounds check en v3/v5/v6 cuando se pasabuf). No es explotable aquí: exceljs solo llamauuid.v4()sin buffer. Override a^11.1.1en este repo (npm auditen 0); como consharp, losoverridesno se propagan a quien instala el paquete — si quieres tunpm auditlimpio, agrega"overrides": { "uuid": "^11.1.1" }en tu proyecto.
Install
npm install -g @ureck/alexandria