Skip to content
terbium

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
  1. Parsing
  2. parse
  3. build_catalog
  4. classify
  5. supported_extensions
  6. Images and vision
  7. export_images
  8. read_vision
  9. AI
  10. AI
  11. enrich_products
  12. Output
  13. to_catalog_csv
  14. records_to_csv
  15. render_html
  16. render_terminal_table
  17. to_shopify_csv and to_pim_json
  18. Result types
  19. ParsedDocument
  20. Record
  21. Stats
  22. ExtractedTable
  23. Constants and version
  24. Extension points

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, csv or image)
  • pages: the adapted pages
  • records: list of Record
  • stats: Stats
  • escalation: message string or None
  • used_ai: bool
  • doc_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 or None
  • fields: dict of schema-specific values; keys are also readable as attributes
  • source_page: 0-based page index
  • confidence: float from 0.05 to 1.0
  • reasons: list of strings
  • origin: "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_THRESHOLD is 0.72. It is importable from terbium but not listed in __all__.
  • terbium.__version__ is "2.0.0".

Extension points

  • New formats: subclass terbium.documents.base.DocumentAdapter and decorate with terbium.documents.base.register. See File formats.
  • New schemas: subclass terbium.schema.Schema and decorate with terbium.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 rows build_catalog returns have that text removed, so calling it on them reports every photo page as unreadable.