Skip to content
terbium

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
  1. Two entry points, and why
  2. Build a catalog table
  3. Parse any document into records
  4. The result
  5. From the command line
  6. When it asks for a key
  7. Next steps

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_catalog anchors one row on each photo and returns plain dicts.
  • Everywhere else, the data sits in tables, forms or sections. terbium.parse rebuilds 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 from terbium.supported_extensions()).
  • schema: "generic", "product", "furniture", "transaction", "resume", the name of a schema you registered, or a Schema instance. When left as None, terbium picks one from the detected document type (see below).
  • doc_type: "auto" (default) to classify the document, or one of catalog, lookbook, transaction, resume, table, deck, unknown.
  • ai: a terbium.AI(...), True to build one from environment keys, or None (default, off).
  • threshold: the confidence below which a record counts as ambiguous. Default 0.72.
  • announce: print the escalation message to stderr when a key would help. Default True.
  • ocr: "auto" (default) runs local Tesseract optical character recognition (OCR) on image-only Portable Document Format (PDF) pages when Tesseract is installed; False turns that off. True behaves 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, so r.finish works like r.fields["finish"].
  • doc.confident_records and doc.ambiguous_records: the records split at the threshold.
  • doc.stats: totals (total, confident, ambiguous).
  • doc.escalation: the “add a key” message, or None.
  • doc.doc_type and doc.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 include doc_type or class_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