Skip to content

v1.5.0

Choose a tag to compare

@UreckChan UreckChan released this 28 Oct 14:18
· 5 commits to main since this release

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) y ale 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_ingest devuelve el índice de secciones (~200 tokens) con el costo estimado del original; si el archivo no cambió (sha256) no se reconvierte.
    • doc_read entrega secciones por id o por pregunta, nunca pasa de max_tokens y 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 PreToolUse sobre Read, toggle docs.interceptRead): la primera lectura directa de un PDF/DOCX/XLSX/CSV grande en la sesión se redirige a doc_ingest/doc_read; el segundo intento pasa, para cuando el agente de verdad necesita ver imágenes. ale doctor lo agrega solo a quien actualiza.
  • ale stats muestra el ahorro medido en documentos: tokens de los originales vs tokens realmente entregados.
  • El bloque de CLAUDE.md/AGENTS.md indica usar doc_ingest/doc_read en 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_read rankea 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é.
  • exceljs trae uuid <11 (moderado, GHSA-w5hq-g745-h8pq: falta de bounds check en v3/v5/v6 cuando se pasa buf). No es explotable aquí: exceljs solo llama uuid.v4() sin buffer. Override a ^11.1.1 en este repo (npm audit en 0); como con sharp, los overrides no se propagan a quien instala el paquete — si quieres tu npm audit limpio, agrega "overrides": { "uuid": "^11.1.1" } en tu proyecto.

Install

npm install -g @ureck/alexandria

📖 Documentation / Documentación