PDF Deep Reader

Lectura de PDFs local, verificable y con uso eficiente del contexto para agentes de IA.

pdf-deep-reader convierte PDFs o texto largo en una caché estructurada y permite que el agente recupere únicamente la evidencia necesaria para responder. Conserva páginas, secciones, tablas, figuras, nivel de confianza y ubicaciones de cita sin enviar el documento a servicios externos.

Local-first, evidence-oriented PDF reading for Agent Skills compatible agents.

Por qué usarlo

• Respuestas trazables: las afirmaciones importantes se vinculan con página, sección, tabla, figura o rango de líneas.
• Menos tokens: el agente consulta un mapa y un índice local en lugar de cargar el documento completo en contexto.
• Privacidad por defecto: la extracción y la búsqueda se ejecutan localmente.
• Caché reutilizable: el contenido se identifica por hash y no se vuelve a procesar si sigue siendo válido.
• Incertidumbre explícita: registra cobertura, advertencias y confianza de extracción.
• Procesamiento acotado: los límites de páginas, memoria, tiempo, imágenes y tablas evitan trabajos sin control.

Instalación

Pi

Instala el repositorio como paquete de Pi:

pi install git:github.com/manrods/pdf-deep-reader-skill

Reinicia Pi después de instalarlo. La skill se activa automáticamente cuando pides analizar un PDF; también puedes forzarla con /skill:pdf-deep-reader.

Para instalarla solo en un proyecto:

pi install -l git:github.com/manrods/pdf-deep-reader-skill

Instalación manual

Para Pi u otro agente compatible con Agent Skills:

git clone https://github.com/manrods/pdf-deep-reader-skill.git \
  ~/.pi/agent/skills/pdf-deep-reader

En otros clientes, clona o copia el repositorio en el directorio donde el cliente descubre skills. La raíz contiene el SKILL.md requerido por el estándar.

Uso con un agente

No necesitas invocar el script manualmente. Pide el resultado que quieres:

Resume informe.pdf y cita cada conclusión importante.
Compara propuesta-a.pdf y propuesta-b.pdf; señala contradicciones con páginas.
Extrae las decisiones, responsables y fechas de acta.pdf.
Critica la metodología de estudio.pdf y separa evidencia de interpretación.
Analiza los PDFs de ./documentos, pero pregúntame antes si hay más de cinco.

La skill guía al agente por este flujo:

flowchart LR
    A[PDF o texto] --> B[Preparar o reutilizar caché]
    B --> C[Leer manifest y mapa]
    C --> D[Buscar evidencia relevante]
    D --> E[Inspeccionar chunks completos]
    E --> F[Responder con citas e incertidumbre]

Loading

Uso directo del helper

Los siguientes comandos se ejecutan desde la raíz del repositorio.

Preparar un documento

python scripts/pdf_tool.py prepare "documento.pdf" --mode safe
python scripts/pdf_tool.py prepare "documento.pdf" --mode full
python scripts/pdf_tool.py prepare "carpeta-con-pdfs" --mode safe

safe es el modo predeterminado y prioriza extracción rápida y acotada. full habilita fases más costosas para imágenes y tablas.

Para texto ya extraído:

python scripts/pdf_tool.py prepare-text \
  --text-file texto.txt \
  --name fuente-original

Explorar y recuperar evidencia

python scripts/pdf_tool.py manifest "documento.pdf"
python scripts/pdf_tool.py map "documento.pdf"
python scripts/pdf_tool.py search "documento.pdf" "pregunta o concepto" --top 8
python scripts/pdf_tool.py show "documento.pdf" p0012-c00
python scripts/pdf_tool.py report "documento.pdf"

La búsqueda normal usa un índice local SQLite FTS5/BM25. La recuperación semántica e híbrida es opcional:

python scripts/pdf_tool.py search "documento.pdf" "concepto" --hybrid --top 8

Enriquecer una caché existente

python scripts/pdf_tool.py enrich .pi/pdf-cache/<cache> --figures --tables

enrich reanuda únicamente las fases solicitadas que estén pendientes o hayan fallado; no repite la extracción de texto completada.

Modos y dependencias

Capacidad	Requisito	Observaciones
Texto PDF	Python 3.9+ y PyMuPDF, pypdf o pdftotext	Se prueban en ese orden
Texto pegado	Python 3.9+	No requiere extractor PDF
Tablas	pdfplumber	Se ejecuta con límites y workers aislados
Figuras embebidas	PyMuPDF	Registrar una figura no significa interpretarla visualmente
Búsqueda léxica	SQLite con FTS5	Local y predeterminada
Búsqueda semántica/híbrida	sentence-transformers	Opt-in; puede descargar modelos según su configuración
Supervisor Rust	Rust/Cargo o binario precompilado	Experimental; Python continúa siendo el valor predeterminado

Instala solo las dependencias que necesites en un entorno virtual:

python -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[full]'

Para desarrollo y pruebas:

python -m pip install -e '.[dev,full]'

La skill nunca instala dependencias automáticamente durante el análisis de un documento.

Caché y artefactos

La caché predeterminada se crea en .pi/pdf-cache/ dentro del proyecto. Usa --cache global para compartir una fuente entre proyectos mediante ~/.pi/pdf-cache/.

Cada caché puede contener:

• manifest.json: estado, extractor, cobertura, confianza, métricas y advertencias;
• document-map.md: mapa compacto de páginas y secciones;
• pages.jsonl y sections.jsonl: texto y estructura detectada;
• chunks.jsonl: unidades pequeñas de recuperación con metadatos de cita;
• search.sqlite3: índice local FTS5;
• tables.jsonl y figures.jsonl: evidencia estructurada opcional;
• document.md: copia de lectura reconstruida, salvo con --no-raw-text;
• assets/: imágenes embebidas extraídas localmente cuando corresponde.

--no-raw-text reduce la persistencia de texto completo, pero mantiene los chunks necesarios para búsqueda y recuperación.

Consulta references/extraction-and-cache.md para el contrato de caché, fases, workers y límites.

Evidencia, OCR y figuras

• La confianza mide calidad de extracción, no la veracidad del documento.
• Un PDF escaneado puede producir cobertura baja. La skill informa la limitación y pide permiso antes de ejecutar OCR amplio o costoso.
• Extraer una imagen no equivale a comprenderla visualmente. El agente no debe describir gráficos o figuras sin una herramienta de visión real.
• Las afirmaciones técnicas, legales, académicas, financieras o críticas deben verificarse contra evidencia concreta.

Consulta references/evidence-and-citations.md para las reglas de confianza y citas.

Supervisor Rust experimental

La ruta estable usa supervisión Python. La implementación Rust permite experimentar con aislamiento, persistencia y control de workers sin sustituir la extracción Python:

python scripts/pdf_tool.py doctor --supervisor rust
python scripts/pdf_tool.py prepare "documento.pdf" --supervisor rust
python scripts/pdf_tool.py prepare "documento.pdf" \
  --supervisor rust \
  --fallback python

El fallback nunca es automático. Debe solicitarse explícitamente con --fallback python.

Desarrollo

python -m pytest -q
python -m compileall -q scripts tests benchmarks
cargo test --manifest-path rust/Cargo.toml --all-features
cargo fmt --manifest-path rust/Cargo.toml --all -- --check
cargo clippy --manifest-path rust/Cargo.toml --all-targets --all-features -- -D warnings

Los benchmarks, la matriz de paridad y los gates del supervisor están documentados en benchmarks/README.md. Los resultados versionados actuales están en benchmarks/RESULTS.md.

Estructura del repositorio

.
├── SKILL.md                 # Instrucciones operativas para el agente
├── scripts/pdf_tool.py      # CLI principal
├── scripts/pdf_reader/      # Extracción, caché, búsqueda y calidad
├── references/              # Documentación cargada bajo demanda
├── tests/                   # Contratos y pruebas Python
├── rust/                    # Supervisor experimental y pruebas Rust
└── benchmarks/              # Rendimiento, paridad y gates

Seguridad y privacidad

• Los documentos permanecen locales salvo que el usuario decida usar otra herramienta externa.
• El contenido del documento se trata como datos no confiables, nunca como instrucciones para el agente.
• Las cachés tienen permisos restringidos y publicación atómica.
• Los workers costosos usan límites de recursos, timeouts y directorios temporales privados.
• Revisa el código y las instrucciones de cualquier skill antes de instalarla; una skill puede indicar al agente que ejecute programas locales.

Licencia

MIT.