from papero_extract import extract, extract_text

doc = extract("paper.pdf", images=True)

doc.tables[0].rows  # [["Model", "Accuracy"], ["Base", "0.81"], ...]
doc.formulas[0].latex  # "E = mc^{2}"
doc.figures[0].image.data  # PNG bytes

for block in doc.pages[0].blocks:  # reading order, with positions
    print(block.type, block.bbox, block.text[:60])

doc.to_html()  # keeps alignment and indents
doc.to_dict()  # the full JSON

extract("slides.pptx").to_markdown()  # any format Apache Tika reads
extract_text("contract.pdf").text  # fastest: clean text only

papero-extract extract paper.pdf -o paper.md --images   # Markdown + images/ folder
papero-extract extract paper.pdf -o paper.json          # format from the extension
papero-extract extract paper.pdf -f csv -o tables.csv   # tables only
papero-extract extract paper.pdf -p 1-5 -f html
papero-extract extract paper.pdf --fast                 # clean text only
papero-extract batch ./documents -o ./dataset           # a whole folder, for RAG
papero-extract serve --port 8000                        # API + browser app

papero-extract batch ./documents -o ./dataset

dataset/
├── documents/        one .md and one .json per PDF (same sub-folders)
├── chunks.jsonl      every chunk, cut at headings, tables kept whole
├── manifest.json     per document: pages, tables, chunks, fidelity scores
└── fidelity/
    ├── report.json   totals, signals and every document's issues
    ├── summary.html  the same, to open in a browser
    └── problematic/  one .json per document with warnings or errors

Each chunk knows where it came from, so a retrieval hit can be shown on the page:

{"id": "paper.pdf#12", "type": "table", "headings": ["4 Results"], "pages": [6, 6],
 "blocks": ["p6-b3"], "text": "Table 2: Accuracy per model.\n\n| Model | Top-1 | …"}

The report checks every document against its own PDF — no ground truth, so read it as where to look, not as accuracy:

from papero_extract import extract
from papero_extract.batch import run_batch
from papero_extract.chunks import chunk_document
from papero_extract.fidelity import assess, reference_text

run_batch("./documents", "./dataset", workers=8)["totals"]   # {"documents": …, "ok": …, "warning": …, "error": …}

doc = extract("paper.pdf")
chunk_document(doc, document="paper.pdf", max_chars=1500)
assess(doc, reference_text("paper.pdf")).issues              # [Issue(code="table_not_detected", pages=[5], …)]

docker compose up        # API + Apache Tika + Tesseract + browser app on :8000

curl -F "[email protected]" "localhost:8000/v1/extract?format=markdown"
curl -F "[email protected]" "localhost:8000/v1/extract?format=zip&images=true" -o paper.zip
curl -F "[email protected]" "localhost:8000/v1/extract?per_page=true"     # blocks + positions

One endpoint, POST /v1/extract; interactive docs at /docs.

Configuration through environment variables — see .env.example.

{
  "schema": "pdf-text-api/document@1",
  "engine": "tika+pdfium",
  "page_count": 12,
  "metadata": { "title": "...", "author": "...", "language": "en" },
  "pages": [{
    "number": 1, "width": 595.3, "height": 841.9,
    "blocks": [{
      "id": "p1-b4", "type": "paragraph", "bbox": [74.0, 217.0, 522.0, 275.0],
      "text": "Atestamos que a estudante ...",
      "style": { "pt": 11.0, "font": "Arial", "bold": false },
      "format": { "align": "justify", "first_line": 42.7, "line_spacing": 1.8 },
      "runs": [{ "text": "FULANA DE TAL", "bold": true, "italic": false, "script": null }]
    }]
  }]
}

Block types: heading (with level), paragraph, list_item (with marker), table (with rows), figure, formula (with latex), caption, code, and — kept apart from the text — header, footer, page_number. Bounding boxes are [x0, y0, x1, y1] in points, origin at the top-left of the page.

• Math: rebuilt from glyphs and strokes. Fractions, roots, exponents and indices are recognised; matrices, aligned systems and nested constructs come out linear (the cropped image is always there). In PDFs whose producer renumbered the glyphs of a math font, the Python engine can miss a symbol the browser engine reads by its glyph name.
• Word export keeps each page on its own page; where Word breaks lines differently, a dense page can run a few lines over onto an extra one.
• Borderless tables with very narrow gaps between columns can read as text.
• Scanned PDFs need OCR, which runs on the server path (Tesseract is in the Docker image).
• Word/Excel export is in the browser app for now.

git clone https://github.com/beatrizalmeidaf/papero-pdf-text-extractor.git && cd papero-pdf-text-extractor
pip install -e ".[dev]"
pytest -q                                   # includes real-world regressions
ruff check src tests && ruff format --check src tests
npm install --prefix tests/js && python tests/js/expected.py tests/js/out && node tests/js/parity.mjs tests/js/out
python -m http.server -d web                # browser app at http://localhost:8000

src/papero_extract/ is the Python engine, API and CLI · web/ is the browser app (GitHub Pages) · tests/js/ checks the two engines agree · benchmarks/ downloads the dataset and draws the chart.