terbium / Guides
AI lane and routing
Enable terbium's opt-in AI lane, choose providers and keys, and see how hard tables are routed to Haiku, Sonnet or Opus class models.
The artificial intelligence (AI) lane is opt-in and additive, and it only sees what the algorithmic engine could not resolve. terbium runs fully without it.
The reasoning is about cost and trust. A model call costs money and time, and a model can return a value the page does not contain. The geometry engine is free and repeatable, and its confidence score says where it struggled. So the model is used only where the score is low, and the cheapest tier that fits the difficulty is chosen.
Enabling it
import terbium
ai = terbium.AI(
anthropic_key="sk-...", # Claude, preferred when several keys are set
openai_key="sk-...", # GPT
kimi_key="...", # Moonshot Kimi
grok_key="...", # xAI Grok
gemini_key="...", # Gemini
)
doc = terbium.parse("catalogue.pdf", ai=ai)
Every key falls back to an environment variable, so terbium.AI() with no arguments picks them up:
- Claude:
ANTHROPIC_API_KEY - GPT:
OPENAI_API_KEY - Kimi:
MOONSHOT_API_KEY, thenKIMI_API_KEY - Grok:
XAI_API_KEY, thenGROK_API_KEY - Gemini:
GEMINI_API_KEY
An empty variable counts as unset. If no key is found, the AI lane is off and terbium escalates with a message instead (see Confidence and escalation).
In terbium.parse, ai=True is shorthand for terbium.AI(). build_catalog and enrich_products need the object itself: with True, build_catalog skips the AI fill for photo rows and enrich_products raises AttributeError.
On the command line, --ai builds terbium.AI() from the environment and --tier pins the tier. There is no command line flag for choosing a provider.
Choosing a provider
When several keys are set, terbium uses the first available provider in this order: Claude, GPT, Kimi, Grok, Gemini. Pin one with provider=:
terbium.AI(provider="openai") # anthropic | openai | kimi | grok | gemini
If you pin a provider whose key is missing, or pass a name that is not in that list, no model is called and no error is raised.
Each provider needs its software development kit (SDK), installed through an extra:
pip install "terbium-parse[anthropic]" # Claude
pip install "terbium-parse[openai]" # GPT
pip install "terbium-parse[kimi]" # Kimi (OpenAI-compatible client)
pip install "terbium-parse[grok]" # Grok (OpenAI-compatible client)
pip install "terbium-parse[gemini]" # Gemini (google-generativeai)
pip install "terbium-parse[ai]" # all of them
Kimi calls go to https://api.moonshot.cn/v1 and Grok calls to https://api.x.ai/v1, both through the openai package.
Inside parse and build_catalog, a failed model call is caught so the parse never crashes. That includes a missing SDK: the table or row stays as it was, and nothing is printed. Troubleshooting and limits shows how to surface the real error.
Routing
Only hard tables reach the router, and the tier scales with difficulty. Difficulty is a 0 to 1 score:
difficulty = 0.5 * (1 - confidence) + 0.3 * min(1, rows * cols / 24) + 0.2 * min(1, cols / 6)
- Opus tier if the table’s confidence is below 0.4 or its difficulty is 0.6 or more.
- Sonnet tier if its difficulty is 0.3 or more.
- Haiku tier otherwise.
Pin a tier when you want to:
terbium.AI(force_tier="opus") # haiku | sonnet | opus
The tier names map to a model per provider. These are the model identifiers (IDs) in the source (harness/router.py and harness/providers/). The changelog lists as a known issue, from 0.10.0 and still in 2.0.0, that they are not verified against the provider application programming interfaces (APIs), and there is no setting to change them:
Claude:
- Haiku:
claude-haiku-4-5 - Sonnet:
claude-sonnet-5 - Opus:
claude-opus-4-8
GPT:
- Haiku:
gpt-4o-mini - Sonnet:
gpt-4o - Opus:
o3-mini
OpenAI o-series models get max_completion_tokens. Image input to o3-mini is unverified.
Kimi:
- Haiku:
kimi-k2-turbo-preview - Sonnet and Opus:
kimi-k2-0711-preview
Grok:
- Haiku:
grok-3-mini-fast - Sonnet:
grok-3-mini - Opus:
grok-3
Gemini:
- Haiku and Sonnet:
gemini-2.5-flash - Opus:
gemini-2.5-pro
Arrange
Each hard table is sent to the routed model with the page’s raw text, terbium’s best-effort version of the table and, for Portable Document Format (PDF) pages, an image of the page rendered at 120 dots per inch (DPI). The model returns the corrected table as JavaScript Object Notation (JSON): a title, column headers, rows with a row header and cells, and attributes. Claude and the OpenAI-compatible providers allow up to 4,096 output tokens per request; the Gemini request sets no limit. terbium rebuilds the table from it, sets its confidence to 0.92, and marks its records origin="ai". A table whose call fails or returns no usable JSON is left as it was.
Set terbium.AI(enable_vision=False) to skip sending the page image.
Other AI steps
- Catalog fill.
build_catalog(..., ai=...)sends each incomplete product’s photo and nearby text to the model to fill a missing name, stock keeping unit (SKU) code or materials. See The catalog table. - Transaction fill. For invoices and receipts,
parse(..., ai=...)asks the model for missing header fields and line items. See Invoices, receipts and resumes. - Product enrichment.
terbium.enrich_products(records, ai)infers a category and category-specific attributes, normalizes price and dimensions, and can read a product photo if you supply one. See Normalization and feeds.
These steps use the Sonnet tier unless you pin a tier with force_tier. Unlike the arrange step, they do not use the difficulty score.
Vision
Some metadata lives only in the pixels: material and care icons (Forest Stewardship Council (FSC), oiled, varnished) and finish swatches. Read them from a rendered PDF page:
info = terbium.read_vision("catalogue.pdf", 58, ai) # page index is 0-based: page 59
# {"icons": ["FSC", "varnished"], "finishes": ["off white", "ginger", ...]}
The signature is read_vision(path, page_index, ai, dpi=130). It always uses the Sonnet tier, whatever force_tier says. It returns None when no provider is available, the page cannot be rendered, or the reply is not JSON. Errors from the model call itself, such as a missing SDK, are raised. It is not part of the default parse path.
To extract the product photos themselves as files, use terbium.export_images, which needs no AI. See Pulling out images.
A note on Nano Banana
Gemini 2.5 Flash Image (“Nano Banana”) is an image generation and editing model, not an extraction model. terbium reads imagery with the selected provider’s multimodal chat model. Nano Banana is not wired into the parse path.