terbium / Get started
Quickstart
Parse your first document with terbium from Python and from the shell, read the result object, and see when it asks for an AI key.
On this page
This page assumes terbium 2.0.0 is installed (pip install terbium-parse). See Installation.
Two entry points, and why
terbium has two main functions because documents anchor their data in two different ways:
- In a photo catalogue, every product has a photo, and the text about it sits next to the photo.
terbium.build_cataloganchors one row on each photo and returns plain dicts. - Everywhere else, the data sits in tables, forms or sections.
terbium.parserebuilds those, scores each one, and returns records that carry a confidence.
The command line picks between them for you based on the detected document type.
Build a catalog table
import terbium
rows = terbium.build_catalog("catalogue.pdf", images_dir="images/") # no key needed
terbium.to_catalog_csv(rows, "catalogue.csv")
Each row is a dict with sku, name, materials, dimensions, image and page. The product photos are written to images/. The full workflow is in The catalog table.
Parse any document into records
import terbium
doc = terbium.parse("catalogue.pdf")
print(doc.stats) # Stats(total=..., confident=..., ambiguous=...)
print(doc.doc_type) # catalog, lookbook, transaction, resume, table, deck or unknown
for r in doc.records:
print(r.sku, r.confidence, r.fields)
terbium.parse accepts:
path: the file to read (any extension fromterbium.supported_extensions()).schema:"generic","product","furniture","transaction","resume", the name of a schema you registered, or aSchemainstance. When left asNone, terbium picks one from the detected document type (see below).doc_type:"auto"(default) to classify the document, or one ofcatalog,lookbook,transaction,resume,table,deck,unknown.ai: aterbium.AI(...),Trueto build one from environment keys, orNone(default, off).threshold: the confidence below which a record counts as ambiguous. Default0.72.announce: print the escalation message to stderr when a key would help. DefaultTrue.ocr:"auto"(default) runs local Tesseract optical character recognition (OCR) on image-only Portable Document Format (PDF) pages when Tesseract is installed;Falseturns that off.Truebehaves like"auto", because the OCR step checks for Tesseract itself. Image files are always read with Tesseract when it is installed.
When schema is None, the detected type decides it: catalog, lookbook and table use product; transaction uses transaction; resume uses resume; deck and unknown use generic.
The result
terbium.parse returns a ParsedDocument:
doc.records: every record. Each has.sku,.fields,.confidence,.reasons,.origin("algorithmic"or"ai") and.source_page(0-based). Field keys are also readable as attributes, sor.finishworks liker.fields["finish"].doc.confident_recordsanddoc.ambiguous_records: the records split at the threshold.doc.stats: totals (total,confident,ambiguous).doc.escalation: the “add a key” message, orNone.doc.doc_typeanddoc.class_scores: the detected type and the per-type scores.doc.used_ai: whether a model call returned a response.doc.to_json(): serialize the document and its records. The JavaScript Object Notation (JSON) output does not includedoc_typeorclass_scores.
From the command line
terbium catalogue.pdf # auto-classify, print a table, extract photos
terbium catalogue.pdf --csv out.csv # also write CSV
terbium catalogue.pdf --records --schema furniture
terbium report.xlsx --records --json out.json
terbium invoice.pdf --type transaction # force the transaction lane
terbium invoice.pdf --csv rows.csv --html report.html
terbium resume.pdf --html out.html --open
terbium deck.pptx --ai --tier opus # enable AI and pin the tier
terbium lookbook.pdf --images out/ # put the extracted photos in out/
terbium scan.png # image file, read through Tesseract OCR
Every flag is described in the CLI reference.
When it asks for a key
If some tables score below the threshold and no artificial intelligence (AI) provider is configured, terbium prints a message to stderr and stores it in doc.escalation:
terbium: 712/725 records parsed confidently.
3 table(s) on page(s) 15, 26, 30 are ambiguous (no product title found above the table; ...).
-> set ANTHROPIC_API_KEY (Claude, preferred), OPENAI_API_KEY, MOONSHOT_API_KEY (Kimi),
XAI_API_KEY (Grok), or GEMINI_API_KEY or pass ai=terbium.AI(...) recommended tier: Sonnet
The last line is wrapped here for width; terbium prints it as one line. To let terbium resolve those tables, opt in:
doc = terbium.parse("catalogue.pdf", ai=terbium.AI()) # reads provider keys from the env
The provider’s package must be installed too, for example pip install "terbium-parse[anthropic]".
Next steps
- How it works, for the reasoning behind each step
- The catalog table and Pulling out images
- Invoices, receipts and resumes
- Worked examples and Confidence and escalation