terbium / Guides
Invoices, receipts and resumes
How terbium classifies a document and reads invoices, bills, receipts and resumes, plus CSV, HTML and terminal output for any lane.
On this page
Beyond catalogues, terbium reads invoices, receipts, resumes and image files, with shared comma-separated values (CSV), HyperText Markup Language (HTML) and terminal output. These lanes arrived in 0.10.0 and are part of 2.0.0, the current release. 0.9.7, the release the Python Package Index (PyPI) served before 2.0.0, has none of them; see Installation.
First principles
Each kind of document anchors its data on something different, and the anchor decides how terbium reads it:
- A catalogue anchors on the photo. The text about a product sits next to its picture.
- An invoice or receipt anchors on the label. A value sits to the right of its label (
Total: $151.20), under it, or at the end of a description line, and the line items usually form one table. - A resume anchors on the heading. Everything under “Experience” belongs to experience until the next heading.
So terbium first decides which kind of document it has, and then runs the reader built for that anchor. The decision is a scored guess, which is why it can always be overridden.
Auto-classification
After adapting a file to pages, terbium scores page-level signals and picks a document type. The signals are keyword hits, amount and date counts, invoice numbers, colon-terminated key-value lines, email addresses and phone numbers, bold or large section headings, photo count and image density, tokens that look like stock keeping unit (SKU) codes, native tables, and whether the file is a PowerPoint (PPTX) file.
| Type | Typical input |
|---|---|
catalog |
row-per-product price list, SKU tables |
lookbook |
image grid with product names |
transaction |
invoice, bill, receipt, purchase order, quote |
resume |
curriculum vitae (CV) with experience and education |
table |
financial or data tables |
deck |
PPTX presentation |
unknown |
fallback when no type scores at least 0.5 |
A PPTX file is classified as deck unless its transaction score is higher than its deck score.
Override the result with --type on the command line or doc_type= in Python:
import terbium
doc = terbium.parse("invoice.pdf") # auto: transaction schema
doc = terbium.parse("resume.pdf", doc_type="resume")
print(doc.doc_type, doc.class_scores)
On the command line, a file detected as catalog, lookbook, table, deck or unknown goes to the catalog table. A file detected as transaction or resume goes to the records view. --records always shows the records view.
Transaction lane
One schema, transaction, covers invoices, bills, receipts, purchase orders and quotes. Column headers and form labels are mapped to canonical fields by synonym lists (FIELD_SYNONYMS in schema/transaction.py), the same pattern the product schema uses. The longest matching synonym wins.
- Header fields:
number,date,due_date,vendor,customer,tax_id,payment_method. - Totals:
subtotal,tax,total. - Line items:
description,quantity,unit_price,amount.
Values come from tables and from key-value geometry on the page (layout/forms.py):
Label: valueon one line;- a label stacked above its value, when the value line sits less than 2.5 times the label’s font size below it and starts within 40 points of the label’s left edge;
- a description on the left paired with an amount on the right (dot leaders are tolerated).
Invoice numbers, tax identifiers (IDs) and dates are also picked up by pattern.
Each record carries a record_type:
summary: one record with the header fields and totals;line_item: one per item row, with the header fields copied in;total: a subtotal, tax or total line, when records are built from the page layout rather than a table.
If the table records plus the summary still number fewer than two, terbium rebuilds the records from the page layout instead: a summary, one total record per total line, and one line_item per description-and-amount line.
terbium invoice.pdf --type transaction --csv invoice.csv
terbium receipt.pdf --records --schema transaction
Output from a small generated invoice looks like this (columns trimmed to fit the terminal):
terbium 2.0.0 · pdf · transaction · 5 records
followed by one summary record and one line_item record per row.
What to check in transaction output
These were observed on small generated invoices and receipts with 0.10.0. 2.0.0 does not change the transaction code, and its changelog still lists the first two as known issues:
- Page-layout line items take any line that ends in a number. On a receipt,
Receipt No: R-8891became a line item with descriptionReceipt No: Rand amount8891. Keep line items whose amount has a currency symbol, or review them. - The same total line can produce two
totalrecords. - Page-layout records score 0.7 and 0.65, below the default threshold of 0.72, so they count as ambiguous. That is expected; no escalation message is printed for them.
- The summary collects every label and value it finds, so it can carry a stray field, such as a
descriptionread from a table header line.
Transaction AI fill
With the artificial intelligence (AI) lane on (--ai or ai=), terbium sends up to the first 4,000 characters of the document text to the text provider (Claude first, Sonnet tier unless pinned) and asks for the header fields and line items as JavaScript Object Notation (JSON). It fills only what is missing:
- missing summary fields are filled; if there is no summary record, an AI summary record is added with confidence 0.85;
- AI line items, with confidence 0.8, are added only when the parser found none;
- the call is skipped entirely when there is a summary record and every summary record already has a
total.
doc.used_ai is True only when a model call returned a response.
Resume lane
The resume schema produces:
- a header record (
section=header) withname,email,phoneandlinksfound on the first page; - one record per line under each recognized section, with
sectionandcontentfields plus the header fields.
The name is the largest short line (five words or fewer, at least 1.1 times the median font size) among the first eight lines, else the first line. Up to three links are kept.
Recognized sections: experience (also “work history”, “employment”, “professional experience”), education (also “academic”, “qualifications”), skills (also “technical skills”, “core competencies”, “expertise”), projects (also “portfolio”) and certifications (also “certificates”, “licenses”). A heading that is exactly summary or objective also starts a section.
A line starts a section when it is a heading (_map_section in schema/resume.py):
- a line that is exactly a section word, with or without a trailing colon; or
- a line of at most four words in which a word starts with a section word or phrase, such as “Work Experience”, “Academics” or “Educational Background”.
A section word inside another word, as in “Inexperienced”, does not count, and a line that starts with a bullet character is always content. Every other line is content of the current section, so “Led a team with deep Python experience” stays under its section. Before 2.0.0, a section word anywhere in a line made the line a heading.
The section field on every row keeps a flat CSV readable.
terbium resume.pdf --type resume --html resume.html --open
Limits to know:
- A short line that names a section is still a heading.
Skills: Python, SQLstarts theskillssection and the text after the colon is dropped, and “Experienced Python developer” starts anexperiencesection. - A heading of five words or more, such as “Education, Training and Professional Development”, is read as a content line of the section before it.
- When the resume’s tables produce two or more records, those table records (with
section=table) are returned instead of the section records. - A phone number written
(555) 123-4567comes out as555) 123-4567.
Output for any lane
Every document type shares the render package:
render/terminal.py: a bordered table drawn with+,-and|, falling back to a lighter American Standard Code for Information Interchange (ASCII) table, then plain columns, then raw CSV, so printing never raises. Columns are narrowed to fit the terminal width and long cells end in....render/html.py: a self-contained HTML table. It loads the Inter font from Google Fonts and falls back to the system font stack.render/csv_out.py:to_csv(records), withskuandconfidencefirst and then the union of field keys in first-seen order.
terbium report.pdf --csv out.csv
terbium report.pdf --html out.html --open
terbium report.pdf --limit 0 # show every row in the terminal
In Python, the same helpers are terbium.records_to_csv, terbium.render_html and terbium.render_terminal_table. See the Python API reference.
Image files
PNG, JPG, JPEG, WEBP, TIFF and TIF files become a single page holding the image. Words come from the local Tesseract optical character recognition (OCR) bridge (layout/ocr.py) when Tesseract is installed.
Those words feed classification and the transaction and resume lanes, which read words directly. Table reconstruction and label grids run only on Portable Document Format (PDF) pages, so a photo of a receipt can yield records but a photo of a price list cannot. Without Tesseract, the page has no words, no records come out, and no message is printed. See Troubleshooting and limits.
terbium scan.png
terbium receipt.png --csv out.csv