Metadata-Version: 2.4
Name: giove-pdf
Version: 0.1.0
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Dist: pytest>=9.0,<10 ; extra == 'dev'
Requires-Dist: maturin>=1.7,<2 ; extra == 'dev'
Requires-Dist: indra-ocr>=0.3,<0.4 ; extra == 'ocr'
Provides-Extra: dev
Provides-Extra: ocr
License-File: LICENSE
Summary: Giove PDF: PDF a Markdown con motor nativo en Rust, OCR local y firma. De Giove.
Keywords: pdf,markdown,ocr,rust,document
Author: Mercu
License-Expression: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/jdecore/brain/tree/main/mercupdf
Project-URL: Issues, https://github.com/jdecore/brain/issues

# 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

| ✅ hace | ❌ **no** hace (y no promete) |
|---|---|
| Texto con CMap: Identity-H, chino, árabe, coreano | **Orden de lectura en columnas** → lo resuelve indra en el camino lento |
| Acentos y scripts mixtos | **Separación de palabras** en el camino rápido → la resuelve indra |
| Clasificación digital / escaneado / mixto, **con la confianza de cada página** | Tablas *(no implementado)* |
| OCR de lo que falta, **page a page** (14 de 284 páginas en 1984, no el libro) | HTML, Tagged PDF, PDF/UA, DOCX |
| Rango de páginas | Interfaz gráfica |
| | **Firma** *(en camino)* |

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`](docs/ODL-COMPARATIVA.md) §2.

## Instalar

```sh
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`](https://github.com/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:

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

Desde el código:

```sh
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

```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)

```sh
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

| | |
|---|---|
| *1984* (284 pág.) | **43 ms** |
| *Cien años de soledad* (173 pág., acentos) | **87 ms** |
| *1984* con OCR: 284 pág., **14 flojas** → indra solo esas | **23 s** |
| *Cien años* con OCR, 6,9 pág/s | 25,1 s |
| Contra OpenDataLoader (Java 2.5.13) | **60-140× más rápido**, y con OCR |

Comparación completa con sondas y muestras: [`docs/ODL-COMPARATIVA.md`](docs/ODL-COMPARATIVA.md).
Análisis de indra: [`docs/INDRA.md`](docs/INDRA.md).
Usar a indra como profesor para entrenar un modelo propio:
[`docs/DISTILACION.md`](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](https://github.com/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`](AGENTS.md) · [`TAREAS.md`](TAREAS.md) · `memory.md`
- [`../PLAN-ECOSISTEMA.md`](../PLAN-ECOSISTEMA.md) — el plan del ecosistema
- `../mercupdf_firma.md` → [`../mercufolio/docs/FIRMA.md`](../mercufolio/docs/FIRMA.md)
- [`docs/INDRA.md`](docs/INDRA.md) · [`docs/ODL-COMPARATIVA.md`](docs/ODL-COMPARATIVA.md) ·
  [`docs/DISTILACION.md`](docs/DISTILACION.md)
