Skip to content
terbium

Docs / Documentation

terbium

Parse business documents into clean rows, calling AI only where geometry is unsure

pip install terbium-parse
  • v2.0.0
  • MIT
  • Python

Sponsors

Primary sponsor

The most efficient proxy provider for web scraping and automation, with the highest quality IPs on the market.

Codes for terbium users

  • TERBIUM35 35% off mobile and residential proxies
  • TERBIUM40 40% off ISP (static) proxies

Visit NodeMaven

On this page
  1. Install name and import name
  2. A minimal example
  3. Who it is for
  4. How it works
  5. What it parses
  6. What it does not do
  7. Where to go next

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 --ai on 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 unknown or returns section records rather than fabricating a table.

Where to go next

terbium is MIT licensed. Source: https://github.com/velofy/terbium