Skip to content
terbium

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
  1. First principles
  2. Auto-classification
  3. Transaction lane
  4. What to check in transaction output
  5. Transaction AI fill
  6. Resume lane
  7. Output for any lane
  8. Image files

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: value on 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-8891 became a line item with description Receipt No: R and amount 8891. Keep line items whose amount has a currency symbol, or review them.
  • The same total line can produce two total records.
  • 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 description read 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) with name, email, phone and links found on the first page;
  • one record per line under each recognized section, with section and content fields 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, SQL starts the skills section and the text after the colon is dropped, and “Experienced Python developer” starts an experience section.
  • 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-4567 comes out as 555) 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), with sku and confidence first 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