terbium / Reference
Python API reference
Every public name exported by the terbium package in 2.0.0, with signatures and return values taken from the source.
On this page
Everything below is importable from the top-level terbium package (src/terbium/__init__.py). Signatures are from version 2.0.0; none changed from 0.10.0.
Parsing
parse
terbium.parse(path, schema=None, ai=None, threshold=0.72, announce=True,
ocr="auto", doc_type="auto") -> ParsedDocument
Adapt the file, classify it, rebuild tables, score them, optionally send the hard ones to an artificial intelligence (AI) model, and build records. Arguments are described in the Quickstart. Raises ValueError for an unsupported extension or an unknown schema name.
build_catalog
terbium.build_catalog(path, images_dir=None, ai=None, announce=True,
ocr="auto", **kw) -> list[dict]
Return one dict per product with the keys sku, name, materials, dimensions, image and page (1-based). Photos are extracted only when images_dir is set and the file is a Portable Document Format (PDF) or PowerPoint (PPTX) file. For a PDF, extra keyword arguments go to export_images; the PPTX path ignores them. See The catalog table.
classify
terbium.classify(pages) -> tuple[str, dict[str, float]]
Return the document type and the per-type scores for a list of Page objects. It takes pages, not a path:
from terbium.documents import get_adapter
pages = get_adapter("invoice.pdf").parse("invoice.pdf")
doc_type, scores = terbium.classify(pages)
terbium.parse already does this and stores the results on doc.doc_type and doc.class_scores.
supported_extensions
terbium.supported_extensions() -> list[str]
The sorted file extensions with a registered adapter.
Images and vision
export_images
terbium.export_images(path, out_dir, only_photos=True, associate=True,
dedupe_repeats=True, min_side=180, max_aspect=4.0) -> list[dict]
Extract photos from a PDF into out_dir and return the manifest. See Pulling out images.
read_vision
terbium.read_vision(path, page_index, ai, dpi=130) -> dict | None
Render one Portable Document Format (PDF) page (0-based index) and ask a vision model for its icons and finishes. It always uses the Sonnet tier. It returns None when no provider is available, the page cannot be rendered, or the reply is not JavaScript Object Notation (JSON); errors from the model call itself are raised. See AI lane and routing.
AI
AI
terbium.AI(anthropic_key=None, openai_key=None, kimi_key=None, grok_key=None,
gemini_key=None, provider=None, force_tier=None, enable_vision=True)
A dataclass holding keys and policy. Missing keys are read from the environment. Properties: available (any key set) and has_vision (enable_vision and available).
enrich_products
terbium.enrich_products(records, ai, image_for=None, only_below=1.01,
tier="sonnet") -> list[Record]
AI enrichment of product records. ai must be an AI object; True raises AttributeError. Records are returned unchanged when no provider is available or a call fails. See Normalization and feeds.
Output
to_catalog_csv
terbium.to_catalog_csv(rows, path=None) -> str
The catalog table as comma-separated values (CSV) with the header SKU,Name,Materials/Ingredients,Dimensions,Image,Page.
records_to_csv
terbium.records_to_csv(rows, extra_cols=("sku", "confidence")) -> str
CSV text from a list of dicts. Columns are the union of keys in first-seen order, with any of extra_cols that are missing inserted at the front. To write Record objects, use terbium.render.to_csv(records, path=None), which converts them first and is what the command line uses.
render_html
terbium.render_html(records) -> str
A self-contained HyperText Markup Language (HTML) table from Record objects or dicts. It never raises; it falls back to a minimal page, then to preformatted CSV.
render_terminal_table
terbium.render_terminal_table(headers, rows, term_width=None) -> str
A text table fitted to the terminal width (80 columns when the width cannot be read). It tries a bordered table drawn with +, - and |, then a lighter American Standard Code for Information Interchange (ASCII) table, then plain columns, then raw CSV, and never raises. Long cells are cut to the column width and end in ....
to_shopify_csv and to_pim_json
terbium.to_shopify_csv(records, path=None) -> str
terbium.to_pim_json(records, path=None) -> str
Commerce feeds from Record objects. See Normalization and feeds.
Result types
ParsedDocument
Returned by parse. Attributes:
path,source_kind(pdf,pptx,xlsx,csvorimage)pages: the adapted pagesrecords: list ofRecordstats:Statsescalation: message string orNoneused_ai: booldoc_type,class_scores
Properties and methods: confident_records, ambiguous_records, to_dict(), to_json(indent=2).
to_dict() contains path, source_kind, stats, used_ai, escalation and records. It does not include doc_type, class_scores or pages, so neither does the --json output.
Record
Record(sku, fields, source_page, confidence, reasons=[], origin="algorithmic")
sku: string orNonefields: dict of schema-specific values; keys are also readable as attributessource_page: 0-based page indexconfidence: float from 0.05 to 1.0reasons: list of stringsorigin:"algorithmic"or"ai"
Methods: get(name, default=None) and to_dict(), which flattens the fields and adds source_page, confidence (rounded to three places) and origin.
Stats
total, confident, ambiguous and threshold. to_dict() returns the first three.
ExtractedTable
The intermediate table every adapter and detector produces, passed to schemas. Fields are listed in Schemas.
Constants and version
terbium.DEFAULT_THRESHOLDis0.72. It is importable fromterbiumbut not listed in__all__.terbium.__version__is"2.0.0".
Extension points
- New formats: subclass
terbium.documents.base.DocumentAdapterand decorate withterbium.documents.base.register. See File formats. - New schemas: subclass
terbium.schema.Schemaand decorate withterbium.schema.register_schema. See Schemas. - Catalog escalation text:
terbium.catalog.catalog_escalation(rows, ocr_ran=False, ocr_available=None). It needs the internal rows, which carry the nearby text of each photo. The rowsbuild_catalogreturns have that text removed, so calling it on them reports every photo page as unreadable.