terbium

Business documents in. Clean rows out. A god-level algorithmic parser for business documents, vendor catalogues (the flagship), invoices, receipts, resumes: it reconstructs structure from geometry, scores its own confidence, and only reaches for an AI model when the algorithm cannot be sure.

Website · Trove

---

Sponsors

---

The one thing terbium does

Point it at any vendor catalogue and get back a table of products, each with its name, its SKU, its materials or ingredients, and its image. Then a CSV.

import terbium

rows = terbium.build_catalog("vendor_catalogue.pdf", images_dir="images/")
terbium.to_catalog_csv(rows, "catalogue.csv")
# rows: {"sku": "RG-1001", "name": "Anatolia Kilim",
#        "materials": "wool", "image": "Anatolia_Kilim.jpeg", "page": 12}

Each product photo anchors a row: terbium extracts the image, names it from the label beneath it, and mines the nearby text for the SKU and the materials. Clean catalogues come out complete with no key; for a visual brochure that buries the name in a title and the material in a paragraph, pass ai=terbium.AI() and a vision model reads each photo plus the page text to fill the blanks. See docs/catalog.md.

It reads more than catalogues

Catalogues are the flagship, not the limit. The same engine reads any structured business document:

rows = terbium.parse("invoice.pdf")                  # line items, totals, vendor
cv = terbium.parse("maria_cv.pdf", schema="resume")  # sections, experience, skills

terbium receipt.png --csv out.csv                      # a receipt into rows
terbium invoice.pdf --csv rows.csv --html report.html  # CSV + self-contained report

Invoices, bills, and receipts come out as line items and totals; resumes and CVs as sections, experience, and skills. Detection is automatic; pin it with --type when a file is ambiguous. docs/TAXONOMY.md maps every document type to the file formats it can arrive in.

Underneath: structure from geometry

A document carries most of its content as text but almost none of its structure. A table in a PDF, a financial grid, a spec sheet, a schedule, a furniture catalogue's size x finish matrix, is laid out for the eye; flatten it to text and the columns collapse into a single line and the grid is gone. terbium rebuilds that structure from the raw position of every word, on any column-aligned table, and it is honest about how sure it is. The default detector is content-agnostic; furniture is the worked example, not the limit.

Most parsers do one of two things: they fail silently on the hard pages, or they throw the whole document at an LLM and bill you for the easy pages too. terbium does neither. It solves what it can algorithmically, scores every record, and when a page is genuinely ambiguous it either routes just that page to the right model tier, or, if you gave it no key, tells you so in plain words.

The loop

FILE  ->  ADAPT  ->  RECONSTRUCT  ->  SCORE  ->  [ESCALATE]
             |            |             |            |
       pdf/pptx/     columns, rows,  confidence   hard pages only:
       xlsx/csv      matrices from   per record   AI if key, else
                     geometry                      "add a key" message

Phase	What happens
Adapt	One adapter per format normalizes bytes into positioned words + images
Reconstruct	Strip repeated headers, split two-page spreads, rebuild columns/rows/matrices from word geometry
Score	Every table gets a 0-1 confidence from grid regularity, header presence, and fill
Escalate	Below threshold: route the page to Haiku/Sonnet/Opus, or announce that a key would resolve it

Quickstart

pip install terbium-parse

import terbium

rows = terbium.build_catalog("catalogue.pdf", images_dir="images/")   # no key needed
# each row: sku, name, materials, image, page

doc = terbium.parse("pricelist.xlsx", schema="product")   # raw records API
print(doc.stats)                                          # Stats(total=725, confident=712, ambiguous=13)

# opt into AI only for what the engine could not resolve
rows = terbium.build_catalog("lookbook.pdf", images_dir="images/",
                             ai=terbium.AI(anthropic_key="sk-..."))

Pull out the product images, each named after the product it sits under:

manifest = terbium.export_images("lookbook.pdf", "out/")
# out/Kyoto_Bedside_Table.jpeg, out/Meadow_Bedside_Table.jpeg, ...
# manifest rows carry: product, collection, page, pixel size, colorspace,
# format, dpi, dominant_color, bbox

Run it from the shell:

terbium catalogue.pdf --csv out.csv         # the product table + images/, no AI
terbium lookbook.pdf --images out/          # extract product photos + manifest.csv
terbium report.xlsx --records --json out.json   # raw parsed records

What it parses

Document types: catalogues and lookbooks, invoices, bills and receipts, resumes and CVs, price lists and decks (see docs/TAXONOMY.md). File formats:

Format	Engine	How
PDF	word-level geometry	rebuild columns/rows/matrices from the position of every word
PPTX	python-pptx	native slides, tables and images, straight from the deck structure
XLSX	openpyxl	cells, merged ranges propagated, wide/long layouts
CSV	stdlib	delimiter, encoding and type inference

PDF gets the full geometry engine because a PDF throws its structure away. PPTX, XLSX and CSV already carry native structure, so terbium leans on it and parses them cleanly and cheaply.

Not every PDF is a matrix. When a document is a lookbook, a grid of product photos with a name under each, terbium reconstructs the label grid instead: one record per product, grouped under its collection title. And when a page is image-only, with no text layer at all, terbium does not return an empty result: it reports exactly which pages need the vision lane.

Confidence and escalation

terbium never pretends a shaky parse is solid. When it cannot be sure and no key is set, it prints exactly what it could not do. On a records parse:

terbium: 712/725 records parsed confidently.
3 table(s) on page(s) 15, 26, 30 are ambiguous (no product title found above
the table; sparse matrix: 5/9 cells filled; 2 row(s) do not line up).
-> set ANTHROPIC_API_KEY or pass ai=terbium.AI(...)   recommended tier: Sonnet

And on a catalog build, when the data lives in the photos instead of the text:

terbium: 8/121 products have a name, 0 a SKU, 9 materials/ingredients.
82 page(s) are image-only (1, 5, 6, 7, 8, ...) - the data lives in the photos, not the text.
-> set ANTHROPIC_API_KEY or pass ai=terbium.AI(...)   recommended tier: Opus (vision)

Every record exposes its own confidence and the reasons behind it, so you can filter, sort, or route on it yourself.

The AI lane

The AI lane is opt-in and only ever sees the hard pages.

• Routing. Difficulty scales the tier: trivial to Haiku, moderate to Sonnet, hard or low-confidence to Opus. Routes across Claude (default), GPT, Kimi, Grok, and Gemini. Pin a tier with terbium.AI(force_tier="opus") or a provider with terbium.AI(provider="openai").
• Arrange. A hard table is handed to the routed model with the page's raw text and, for PDFs, a rendered image, and rebuilt into a clean matrix.
• Vision. Material icons (FSC, oiled, varnished) and finish swatches live only in the pixels; terbium.read_images(path, page, ai) reads them with a vision model. Note: Nano Banana (Gemini image) is for generation, not reading, so it is not on the parse path.

Keys come from terbium.AI(...) or environment variables: ANTHROPIC_API_KEY (Claude, preferred), OPENAI_API_KEY, MOONSHOT_API_KEY / KIMI_API_KEY, XAI_API_KEY / GROK_API_KEY, GEMINI_API_KEY.

Schemas

A schema turns reconstructed tables into typed records. Ships with three:

• product: universal, category-agnostic. Maps any table's columns to product fields by header meaning (sku/name/price/dimensions/color/material/qty/...); category-specific columns survive as attributes.
• generic (default for parse): one record per row for grids, one per cell for matrices.
• furniture: product, size, finish, and metric + imperial dimensions per SKU.

Add your own by subclassing terbium.schema.Schema and registering it.

Install from source

git clone https://github.com/anishfyi/terbium.git
cd terbium
pip install -e .

License

MIT. Built by anishfyi.

_{terbium · Tb · 65}