#23 feature/Invoice-currency-lines · L-261107-0c6dcb

TL;DR

• invoice_extraction now returns each invoice's currency, as an ISO 4217 code, and its purchase line by line, so a page built on its result can print "$9.96" and list what was bought.
• A wrong currency is worse than a missing one, so the currency is read only from what the document shows for its own totals and lines, and left empty when nothing settles it.
• vat_rates now always reads as percentages (20 for 20 %): a caller that computed with fractions must divide by 100, so the release that carries this is a minor.

Behaviour changes

• Invoice had no currency → currency, the ISO 4217 code of the currency its totals and lines are expressed in. It is taken from a code given for those amounts, then from a symbol naming one currency only (€, ₹), then, for a shared symbol ($, £, ¥, kr), from where the document was issued. A converted amount or a card payment in another currency is never used, and the field stays empty when nothing settles it.
• The purchase was one free-text description → line_items, a list of the new InvoiceLineItem (label required; quantity, unit_price and amount as printed). It holds every priced line in the order printed: fees, surcharges and discounts are included wherever they are printed, and the subtotal, tax, total, payment and per-category subtotal lines are never included.
• description was a free description of the goods → a one-line summary of the purchase.
• vat_rates was left to the model, 0.2 or 20 → percentages, 20 for 20 %.

Breaking changes

• vat_rates keeps its type and changes its meaning for a caller who received fractions. A caller that moves its address from v0.2.0 and multiplies an amount by a rate must divide the rate by 100 first. The changelog marks it "(Breaking)", and the next release is v0.3.0.

Changes

• methods/invoice_extraction/invoice_extraction.mthds:
  • the new InvoiceLineItem concept;
  • currency and line_items on Invoice;
  • the amounts' descriptions say they are in the invoice's currency;
  • vat_rates and description redefined;
  • the extract_invoice_data prompt gains a currency rule, a line-item rule and a one-line description rule. The model alias and the inputs are unchanged.
• methods/invoice_extraction/README.md, the library's first package README: what the method takes and returns, every field, how the currency is determined, which lines are line items.
• The root README.md's method table row and CHANGELOG.md's [Unreleased] section.

How it was verified

• plxt fmt --check and plxt lint over the package, and pipelex validate bundle methods/invoice_extraction/ on Pipelex 0.95.1 and 0.97.0 with the README in the package directory.
• Python types generated with pipelex codegen types … -t python-pydantic: InvoiceLineItem is its own model with label: str, line_items is list[InvoiceLineItem] | None, and currency is str | None.
• Live runs on the hosted API, from the cookbook's assets at v0.18.0, repeated after each round of fixes:
  • the package's own sample, the JFK 5B Food Hall receipt, which prints no address: USD, and three lines (3.99, 4.89, and the 0.27 surcharge printed below the subtotal);
  • a Johnny Rockets receipt: USD, two lines, with its "Food" and "NA Bev" category subtotals left out;
  • a House of Blues card slip: USD from its printed code, no lines, and its suggested-tip table not read as lines.

Documentation

The package README, the concept's field descriptions (which reach codegen's docstrings and every form descriptor), the root README's method row, and the changelog.

Not done

• A multi-page invoice still returns one Invoice per page, as the method always has. Grouping pages is a change to the output's multiplicity, left until a consumer needs it.
• No live run covered a euro document or a shared symbol with nothing to settle it: no cookbook asset is one.
• The consumers move separately: the cookbook's CSV batch recipe once v0.3.0 is tagged (L-261107-9ac36b), and mthds-form's invoice result fixture (L-261107-a285d0).

Closes L-261107-0c6dcb

🤖 Generated with Claude Code

https://claude.ai/code/session_019TF9N18ABj9hxXJX1vChAU

---

Summary by cubic

invoice_extraction now returns each invoice's currency as an ISO 4217 code and lists the purchase line by line, so a page built on its result can print "$9.96" and list what was bought.

Behavior changes

• currency is read only from what the document shows for its own totals and lines, in this order: a code, then a one-currency symbol like € or ₹, then, for shared symbols like $, £ or kr, where the document was issued; it is left empty when nothing settles it, and a converted amount or card payment in another currency is never used.
• line_items holds every priced line in printed order, fees and discounts included, as the new InvoiceLineItem; the subtotal, tax, total and payment lines are never included.
• description becomes a one-line summary, and the package gains a README describing its output.

Breaking change

• vat_rates now reads as percentages (20 for 20 %); a caller that computed with fractions must divide the rate by 100 first, and the next release is v0.3.0.