mercupdf

PDF → Markdown. Un motor, dos formas de llamarlo: como sidecar desde Rust (que es como lo usa mercufolio) y como rueda de Python (que es como lo usa Colab).

No es un framework de conversión. Es un motor que sabe leer una capa de texto.

Qué hace y qué no

Se enumera lo que no hace a propósito: es mejor decir que no que fingir. Cada línea de esa columna es una tarea del plan, no un olvido.

⚠️ Bug abierto y medido (2026-10-15): en el camino rápido, las ligaduras se borran. Rectified sale Rectied y fight sale ght: 167 palabras desaparecen en 1984. Es un glifo sin /ToUnicode que pdfboss no resuelve. El camino lento (indra) sí los lee. Ver docs/ODL-COMPARATIVA.md §2.

Instalar

pip install mercu-pdf            # el nombre de distribución

El nombre de distribución es mercu-pdf y el nombre de importación es mercupdf: mercupdf ya existe en PyPI y es de otro proyecto (mercupdf-project/mercupdf). Ruedas abi3 (cp38-abi3): una sola sirve para Python 3.8 en adelante, así que en Colab funciona sin compilar nada.

Con OCR:

pip install "mercu-pdf[ocr]"      # trae indra-ocr (~18 MB de modelos, la 1ª vez necesita red)

Desde el código:

maturin build --release --out dist

En Windows hace falta el enlazador de MSVC en el PATH (cmd /c 'vcvars64.bat && maturin build --release --out dist').

Usar

Python

from mercupdf import MercuPDFCore

core = MercuPDFCore()
resultado = core.convert("libro.pdf")
print(resultado["page_count"])

# Solo unas páginas, para no pagar el libro entero
resultado = core.convert("libro.pdf", pages=[1, 3, 5])

# OCR: "auto" sube a indra SOLO las páginas que no se leen bien
print(core.available_ocr_engines())        # ['indra'] o []
resultado = core.convert("libro.pdf", ocr="auto")
core.paginas_flojas("libro.pdf")           # qué páginas no se Cree: [{'page': 1, ...}]

Para procesar un corpus: examples/python/batch/. Un PDF corrupto no tumba el lote — el error queda en su documento y el resto se convierte igual.

Para trocear en chunks con página y posición (lo que necesita mercufonte para citar): examples/python/rag/.

Como sidecar (lo que hace mercufolio)

mercupdf-cli libro.pdf

Proceso aparte a propósito: el core depende de pyo3, y enlazado arrastraría Python al binario. Así el .exe de la app se queda en 9,9 MB y mercupdf se puede subir sin recompilar el casco.

Medido, no supuesto

Comparación completa con sondas y muestras: docs/ODL-COMPARATIVA.md. Análisis de indra: docs/INDRA.md. Usar a indra como profesor para entrenar un modelo propio: docs/DISTILACION.md.

De dónde viene

mercupdf_rust_core/ (22 KB) y python/mercupdf/ son nuestros. El proyecto nació de un fork de OpenDataLoader-PDF cuyo backend de Java se usó para probar rendimiento y no funcionó: solo quedó Rust. El resto del fork (Java, C++, Node, servidor híbrido, arnés de tests) se eliminó en 2026-10-15. En competencia/ queda el material de referencia por si algún día hace falta mirar.

Dependencias Rust, todas permisivas: pdfboss-text (MIT/Apache-2.0), lopdf (MIT), rayon (MIT/Apache-2.0), oar-ocr (Apache-2.0, opcional).

Licencia

Apache-2.0 (ver LICENSE). Mercufolio es MIT: compatible en una sola dirección, pero Apache obliga a conservar el aviso y otorga patente.

Ver también

• AGENTS.md · TAREAS.md · memory.md
• ../PLAN-ECOSISTEMA.md — el plan del ecosistema
• ../mercupdf_firma.md → ../mercufolio/docs/FIRMA.md
• docs/INDRA.md · docs/ODL-COMPARATIVA.md · docs/DISTILACION.md