Docs / Documentation
terbium
Parse business documents into clean rows, calling AI only where geometry is unsure
Sponsors
The most efficient proxy provider for web scraping and automation, with the highest quality IPs on the market.
Codes for terbium users
TERBIUM3535% off mobile and residential proxiesTERBIUM4040% off ISP (static) proxies
On this page
terbium turns business documents into clean rows. Point it at a vendor catalogue, an invoice, a receipt, a resume, a price list or a slide deck, and it returns structured records you can write to comma-separated values (CSV), JavaScript Object Notation (JSON) or a self-contained HyperText Markup Language (HTML) report.
It works algorithmically first. A Portable Document Format (PDF) file keeps its words but throws away its structure, so terbium rebuilds columns, rows and matrices from the position of every word. It scores its own confidence on every table and record. Only when a table is genuinely ambiguous does it call an artificial intelligence (AI) model, and only for that table. If you have not configured a key, it tells you in plain words what it could not read and which model tier would help.
Vendor catalogues are the flagship use: one row per product with its name, stock keeping unit (SKU) code, materials or ingredients, dimensions and the extracted product photo.
Install name and import name
The distribution on the Python Package Index (PyPI) is terbium-parse. The Python package you import is terbium, and the command it installs is also terbium.
pip install terbium-parse
import terbium
Do not run pip install terbium: that name on PyPI belongs to an unrelated project. The owner sometimes writes the name as terbium_parse; pip treats terbium-parse and terbium_parse as the same distribution, and the wheel files use the underscore form. pip install terbium-parse installs 2.0.0, the version these docs describe; see Installation.
A minimal example
import terbium
rows = terbium.build_catalog("vendor_catalogue.pdf", images_dir="images/")
terbium.to_catalog_csv(rows, "catalogue.csv")
# each row: {"sku": "RG-1001", "name": "Anatolia Kilim", "materials": "wool",
# "dimensions": None, "image": "Anatolia_Kilim.jpeg", "page": 12}
The same engine reads other documents through terbium.parse:
doc = terbium.parse("invoice.pdf") # line items, totals, vendor
cv = terbium.parse("maria_cv.pdf", doc_type="resume") # sections, experience, skills
print(doc.stats) # Stats(total=..., confident=..., ambiguous=...)
From the shell:
terbium catalogue.pdf --csv out.csv # product table + photos, no AI
terbium invoice.pdf --csv rows.csv --html report.html # CSV and a self-contained report
Who it is for
- Teams that receive supplier catalogues as PDFs or decks and need product rows for a product information management (PIM) system, a Shopify import or a marketplace feed.
- Developers extracting line items and totals from invoices, bills and receipts, or sections from resumes.
- Anyone who wants a parser that reports how sure it is, instead of failing silently on hard pages or sending every page to a paid model.
How it works
FILE -> ADAPT -> RECONSTRUCT -> SCORE -> [ESCALATE]
| | | |
pdf/pptx/ columns, rows, confidence hard tables only:
xlsx/csv/ matrices from per record AI if a key is set,
images geometry otherwise a message
- Adapt. One adapter per format turns the file into positioned words, images and, where the format has them, native tables. See File formats.
- Reconstruct. Running headers and footers are stripped, two-page spreads are split at the gutter, and columns, rows and matrices are rebuilt from word positions. The detector is content-agnostic: a price list, a spec sheet, a financial grid and a furniture size by finish matrix all reconstruct the same way.
- Score. Every reconstructed table gets a confidence between 0.05 and 1.0 with the reasons behind it. See Confidence and escalation.
- Escalate. Tables below the threshold (0.72 by default) go to a routed AI model if you enabled one. Otherwise terbium attaches and prints a message naming the pages, the reasons and a recommended tier. See AI lane and routing.
The reasoning behind each step, the constants it uses and the ways it fails are on How it works.
What it parses
Document types:
- Catalogues and lookbooks (the flagship lane)
- Invoices, bills, receipts, purchase orders and quotes
- Resumes and curricula vitae (CVs)
- Price lists, data tables and slide decks
File formats: PDF, PowerPoint (PPTX), Excel (XLSX and XLSM), CSV (and tab-separated TSV), and image files with the extensions png, jpg, jpeg, webp, tiff and tif. Image files and image-only PDF pages need a local Tesseract install to yield text. The document taxonomy maps document kinds to the lane that reads them.
What it does not do
- It does not produce Markdown or text for retrieval pipelines. It produces records.
- It does not invent data. When a catalogue prints no SKU, the SKU stays blank; when names are set as artwork with no text layer, terbium reports those pages instead of guessing.
- It does not call any model unless you pass
ai=in Python or--aion the command line and a provider key is available. - It does not reconstruct tables from free text on PPTX slides or image files; table reconstruction from geometry runs on PDF pages. PPTX, XLSX and CSV tables are read from the file’s own structure.
- Flowing prose (books, essays, contracts) has no row structure. terbium classifies such input as
unknownor returns section records rather than fabricating a table.
Where to go next
- Installation, Quickstart and How it works
- The catalog table, the flagship workflow
- Invoices, receipts and resumes
- Worked examples and Troubleshooting and limits
- CLI reference and Python API reference
- Evaluation and Changelog and status
terbium is MIT licensed. Source: https://github.com/velofy/terbium
