The business caseThe problem this solves

Reconciling one item/location/period's inventory roll-forward means taking every raw, unclassified transaction line for the period and sorting it by hand into receipts, markdowns, shrink write-offs, vendor allowances or inter-location transfers, summing each bucket to a dollar total, and sizing whatever residual is left against the account's stated materiality threshold -- for every cycle, every close, with a transfer-out line and a shrink write-off sometimes reading almost identically in the raw feed. Cost accounting reading every raw, unclassified transaction line for one item/location/period roll-forward by hand -- sorting each into receipts, markdowns, shrink, allowances or transfers, summing each bucket, and sizing whatever residual is left against the account's materiality threshold -- for every cycle, every close.

The inputThe actual roll-forward cycles

The corpus is 34 roll-forward cycles, 0.10 MB (jsonl 1). A real inventory valuation roll-forward names real SKUs, real store/DC locations and real dollar movements a retailer would not let leave the building -- this repo has never held one and is not able to. There is no public corpus of paired (raw unclassified transaction feed, cost-accounting-reconciled bucket decomposition) records, for the same reason no public corpus of month-end close packages or supplier agreements exists: the interesting cases are exactly the ones nobody can publish. Nothing in the corpus refers to a real company -- item names, location codes, transaction references and memo narratives are all invented.

{"cycle_id": "IVR-00001", "item_id": "SKU-14588", "item_label": "Insulated Lunch Bag", "location_id": "DC-NORTH", "period": "2026-06", "opening_balance": 56248.78, "closing_balance": 53301.33, "materiality_threshold_usd": 750.0, "lines": [{"line_id": "IVR-00001-L01", "date": "2026-06-19", "qty": 305, "amount_usd": 3003.27, "memo": "Inbound shipment received against purchase order PO-59265 (ref TXN-10001)."}, {"line_id": "IVR-00001-L10", "date": "2026-06-24", "qty": 46, "amount_usd": -473.69, "memo": "Return-to-vendor allowance posted against inventory (ref TXN-10010)."}, {"line_id": "IVR-00001-L13", "date": "2026-06-28", "qty": 31, "amount_usd": 76.05, "memo": "Inbound transfer received from STR-221 (ref TXN-10013)."}, {"line_id": "IVR-00001-L07", "date": "2026-06-08", "qty": 69, "amount_usd": -954.22, "memo": "Units removed from location, ref TXN-10007. Reason: cycle count discrepancy, written off as shrink."}, {"line_id": "IVR-00001-L17", "date": "2026-06-02", "qty": null, "amount_usd": 1316.88, "memo": "Adjustment posted per ticket reference, ref TXN-10017. No further detail on file."}, {"line_id": "IVR-00001-L08", "date": "2026-06-23", "qty": 47, "amount_usd": -840.21, "memo": "Physical inventory count shortage at this location, written off as shrink (ref TXN-10008)."}, {"line_id": "IVR-00001-L11", "date": "2026-06-11", "qty": 130, "amount_usd": -446.24, "memo": "Vendor damage allowance credited against inventory value (ref TXN-10011)."}, {"line_id": "IVR-00001-L06", "date": "2026-06-18", "qty": 73, "amount_usd": -794.83, "memo": "Units removed from location, ref TXN-10006. Reason: cycle count discrepancy, written off as shrink."}, {"line_id": "IVR-00001-L14", "date": "2026-06-04", "qty": 246, "amount_usd": 114.9, "memo": "Inbound transfer received from STR-517 (ref

The outcomeWhat a good result looks like

A bucket per raw line (receipts, markdowns, shrink, allowances, transfers, or an honest unknown when the memo genuinely does not support any of the five), the five bucket totals, and a residual sized and characterized against the account's stated materiality threshold -- for cost accounting to review before close. Decision-free by design: this kit never books an inventory adjustment or closes the valuation period itself.

Where it fitsWhat did work

Every line below is a measured result from this kit's own runs, with the figure that supports it. The headline above is not softened by any of them.

• Bucketing a period's raw transaction lines and sizing the residual for cost accounting to pre-check before close — the fast tier, over the free keyword floor
  100% line accuracy and 0% transfer<->shrink confusion this run, against the floor's 94.7% and 26.3% confusion on the exact lines written to be confusable.
• Deciding whether a real, above-threshold inventory movement gets escalated — the fast tier's residual_status verdict, read alongside its bucket totals
  0 of 13 gold above-threshold cycles this run were called within_threshold (false_fully_explained) -- the expensive-direction error this kit's guardrail exists to catch.
• What this kit is not — a draft for cost accounting to review before close -- never an approval
  src/invval.py and src/app.py have no function anywhere that books an inventory adjustment or marks the valuation period closed; every decomposition is for a human to act on.

At a glanceHow the whole thing runs

Run once, for real, on 2026-08-19. Every figure on these pages was captured from that run — nothing is written from intent.

14 steps, grouped by the question that sends you to them rather than by build order. Each tile carries the one figure that step is about, and opens the page behind it.

Should you use this?What you bring, where it stops, and when not to use it

Before you commit an afternoon to this, these are the answers that decide it. Each one is rendered from the record it lives in — and links the page that holds it in full.

Not asked of this kit — 2 questions: clone (a fresh clone of this kit runs with nothing fetched); judge (nothing here is graded by a model).

Last verified 2026-08-19 — r001-fin-invval. Every figure on these pages was captured from that run.

Run itHow this reaches your data

Every result on this page was produced by pure code over checked-in files, with no API key — which is why you can read the numbers before anyone spends anything.

Checked before this shipped — A fresh clone with no key configured renders the whole panel -- every roll-forward cycle and its raw lines -- since data/cycles.jsonl and data/gold.jsonl are committed, not fetched (python -m src.app). Clicking Decompose with no API_KEY returns a calm 200 explaining nothing was called (src/app.py's /api/check). It cannot reproduce a live decomposition, a score, or a dollar figure without a key -- those are what results/eval-r001-fin-invval.json already committed.

Step 01 of 14Business case

Written for: product manager · Measured during the eval run. Never estimated, never quoted from a vendor page.

In brief

What the clock covers. END-TO-END per roll-forward cycle: one HTTP request carrying the cycle's opening balance, closing balance, materiality threshold and every raw transaction line, parsed to a bucket per line plus the bucket totals and residual. No retrieval step -- loading a cycle from disk is pure code and costs no network time. This run left provider-side reasoning ('thinking') at its documented default (on) rather than disabling it, so p50/p95 include a hidden reasoning pass on every call, not only the JSON-formatting cost -- see not_good_enough.

Current processWhat it replaces

Cost accounting reading every raw, unclassified transaction line for one item/location/period roll-forward by hand -- sorting each into receipts, markdowns, shrink, allowances or transfers, summing each bucket, and sizing whatever residual is left against the account's materiality threshold -- for every cycle, every close.

Step 02 of 14Architecture

Written for: solutions architect · Component map derived from the real code, not drawn from intent.

In brief

CorpusCorpusArchitectureArchitecturePromptPromptPromptPromptApp UIApp UIEvalsEvalsBusiness caseUnit cost

• 1stations numbered in run order
• jsonl
• 1 of 7 stations carry a recorded failure

scroll → 7 stations

One question, end to end. Colour on the fan-in is the corpus format; a red hook marks every station with a recorded failure, and the words — every sub line, failure and report field — are in the ledger beneath. Every station is a link — click one to jump to its row, and each row links to the lens that explains it.

The swap seams

Components

Step 03 of 14App UI

Written for: anyone, in 5 seconds · Screenshots of the running app taken during the run.

SuccessesWhen it works

LimitsWhen it does not

A report showing only wins is an advert. This one is required, and the validator now refuses a kit that omits it.

Step 04 of 14Corpus

Written for: "can I point this at mine?" · Measured off the corpus the run actually used.

In brief

How it is cutWhat one raw transaction lines per cycle is

One cycle, every raw line included whole -- no train/test split, every cycle is decomposed once, in one call.

SetupWhat the setup figure measured

No index is built. src/app.py finds a cycle by scanning C.cycles() for a matching cycle_id -- 34 rows, a linear scan, not a search structure -- and src/invval.py sends that cycle's raw lines whole into the one call. build_seconds and build_cost_usd are both zero because there is no index-build step, not because one ran for free.

LicenceLicence

MIT (this repository's own licence)

Bring your ownBring your own roll-forward cycles

Point tools/build_corpus.py at your own items, locations and transaction-memo phrasing, or write your own data/cycles.jsonl in the same shape -- src/invval.py and src/prompt.py read a cycle by its own fields (opening_balance, closing_balance, materiality_threshold_usd, lines[]) and do not care where the numbers came from. The five-bucket taxonomy in src/prompt.py assumes receipts/markdowns/shrink/allowances/transfers specifically; a different bucket set is a prompt.py change, not a data change.

⚠︎ And what stops being true when you do: The measured 100% line accuracy, 0% transfer<->shrink confusion and 100% residual-status accuracy are THIS corpus's memo phrasing variety (a handful of hand-written templates per bucket, with 45% of shrink and transfer-out lines deliberately written in the confusable shared opening) and THIS corpus's one-defect-family-per-cycle design (a cycle's residual is exactly the signed sum of its unknown lines, never a genuinely disputed judgment call). A real transaction feed's own memo language, and a feed that does not post at a matching item/location grain (see breaks_on), are both unmeasured by this run.

Step 05 of 14Prompt

Written for: engineer · Logged from the run, verbatim.

In brief

The assembled prompt in full, and its real decomposition. Every part below occurs in the prompt that was actually sent, and the token counts sum to the recorded input total — but they are the input total apportioned by each part’s share of the characters, not a per-part reading from the provider’s counter. The total is measured; the split is arithmetic, and a part carrying denser text really costs more of it than this says.

AssemblyHow the prompt is assembled

This is the cost lesson as arithmetic: of the 1,751 tokens assembled, 1,012 are instructions — 58% of the prompt, the largest single part. A per-request bill follows whichever part is biggest, and on this kit that is the one named here.

Logged verbatim by importing src.prompt and src.invval directly and calling prompt.build(cycle) for IVR-00001 (not retyped) -- the literal system and user content src/invval.py::check() sends. Per-part token counts are a proportional estimate over character share (system 3269 / cycle 176 / lines 2209 chars, 5654 total) applied to this call's own total of 1751 input tokens -- the provider reports only the call's total, matching lenses.LLM.tokens.input exactly, never a per-segment split.

Full promptThe prompt in full

You are drafting an inventory valuation roll-forward decomposition for one item/location/period, for cost accounting to review before close. You are given the opening balance, the closing balance (both from the perpetual/GL system -- trusted, not disputed), a materiality threshold in dollars, and every RAW, UNCLASSIFIED transaction line for the period.

For EACH raw line, classify it into exactly one of these five buckets, or `unknown` if the memo genuinely does not support any of them:

  receipts     inbound stock received against a purchase order or vendor shipment. Increases the balance.
  markdowns    a permanent price/value reduction posted against inventory (clearance, promotional revaluation). Decreases the balance.
  shrink       a write-off from a cycle count variance, damage, spoilage or loss -- inventory leaves the books with no receiving location on the other end. Decreases the balance.
  allowances   a vendor damage/return allowance or similar credit posted against inventory value, not a physical unit movement. Decreases the balance.
  transfers    a movement of the SAME item to or from another location -- transfers-in increase the balance, transfers-out decrease it. Always names or implies a counterparty location or a transfer reference.
  unknown      the memo does not name or clearly support any of the five buckets above. Do not force a line into a bucket to avoid saying unknown -- an unsupported guess is graded worse than an honest unknown.

⚠︎ THE FAILURE MODE THIS TASK EXISTS TO CATCH: a transfer-out line and a shrink write-off line can open with nearly identical language -- both are often phrased as "units removed from location". Do not classify from the opening clause alone. A transfer names or implies a counterparty location and/or a transfer reference; a shrink write-off states a count variance, damage or loss reason and no destination. Read the WHOLE memo before deciding between these two.

SIGN CONVENTION -- state your bucket totals this way, exactly:
  receipts, markdowns, shrink and allowances are each a POSITIVE dollar magnitude (the size of that movement, regardless of direction).
  transfers is a SIGNED net figure: transfers-in positive, transfers-out negative, netted together.
  receipts and transfers-in increase the balance; markdowns, shrink, allowances and transfers-out decrease it.

Sum each bucket's classified lines to that bucket's total (lines you called `unknown` are excluded from every bucket total). Then compute:
  residual = (closing_balance - opening_balance) - (receipts - markdowns - shrink - allowances + transfers)

State whether the residual is within or above the stated materiality threshold, using the absolute value of the residual. An above-threshold residual is NEVER `within_threshold` -- do not round it down or describe it as fully explained. If every line is confidently classified and the residual is still above threshold, say so: that is a real unexplained movement for cost accounting to chase, not a rounding error to wave through.

You are drafting this decomposition for cost accounting to review. You never book an inventory adjustment and you never close the valuation period yourself -- you only classify, total and size the residual for a human to act on.

CYCLE IVR-00001 -- item SKU-14588 (Insulated Lunch Bag), location DC-NORTH, period 2026-06
Opening balance: $56248.78
Closing balance: $53301.33
Materiality threshold: $750.00

RAW TRANSACTION LINES (17)
--------------------------
- IVR-00001-L01 | 2026-06-19 | qty 305 | $3003.27 | Inbound shipment received against purchase order PO-59265 (ref TXN-10001).
- IVR-00001-L10 | 2026-06-24 | qty 46 | $-473.69 | Return-to-vendor allowance posted against inventory (ref TXN-10010).
- IVR-00001-L13 | 2026-06-28 | qty 31 | $76.05 | Inbound transfer received from STR-221 (ref TXN-10013).
- IVR-00001-L07 | 2026-06-08 | qty 69 | $-954.22 | Units removed from location, ref TXN-10007. Reason: cycle count discrepancy, written off as shrink.
- IVR-00001-L17 | 2026-06-02 | qty n/a | $1316.88 | Adjustment posted per ticket reference, ref TXN-10017. No further detail on file.
- IVR-00001-L08 | 2026-06-23 | qty 47 | $-840.21 | Physical inventory count shortage at this location, written off as shrink (ref TXN-10008).
- IVR-00001-L11 | 2026-06-11 | qty 130 | $-446.24 | Vendor damage allowance credited against inventory value (ref TXN-10011).
- IVR-00001-L06 | 2026-06-18 | qty 73 | $-794.83 | Units removed from location, ref TXN-10006. Reason: cycle count discrepancy, written off as shrink.
- IVR-00001-L14 | 2026-06-04 | qty 246 | $114.90 | Inbound transfer received from STR-517 (ref TXN-10014).
- IVR-00001-L04 | 2026-06-10 | qty 113 | $-1705.82 | Clearance markdown, unit value reduced and inventory revalued (ref TXN-10004).
- IVR-00001-L15 | 2026-06-03 | qty -175 | $-8711.25 | Transfer-out to STR-517 (ref TXN-10015).
- IVR-00001-L02 | 2026-06-17 | qty 220 | $7023.89 | Vendor receipt posted, purchase order PO-43736 (ref TXN-10002).
- IVR-00001-L16 | 2026-06-03 | qty 47 | $1262.29 | Adjustment posted per ticket reference, ref TXN-10016. No further detail on file.
- IVR-00001-L05 | 2026-06-25 | qty 45 | $-590.61 | Inventory removed from floor stock, ref TXN-10005 -- count adjustment, expensed to shrink.
- IVR-00001-L12 | 2026-06-21 | qty 116 | $67.23 | Inter-location transfer, units received from STR-221 (ref TXN-10012).
- IVR-00001-L09 | 2026-06-13 | qty n/a | $-455.78 | Vendor chargeback allowance applied to inventory value (ref TXN-10009).
- IVR-00001-L03 | 2026-06-10 | qty 143 | $-839.31 | Clearance markdown, unit value reduced and inventory revalued (ref TXN-10003).

Return a JSON object with these keys:
  "lines": a list with exactly 17 entries, one per raw line above in the same order, each {"line_id": <id>, "bucket": <one of: receipts, markdowns, shrink, allowances, transfers, unknown>}.
  "bucket_totals": {"receipts": <number>, "markdowns": <number>, "shrink": <number>, "allowances": <number>, "transfers": <number>} -- per the sign convention stated above.
  "residual_usd": <number, the signed residual computed per the formula above>.
  "residual_status": <one of: within_threshold, above_threshold>.
Answer with the JSON object only.

Raw responseThe raw response

{
  "lines": [
    {"line_id": "IVR-00001-L01", "bucket": "receipts"},
    {"line_id": "IVR-00001-L10", "bucket": "allowances"},
    {"line_id": "IVR-00001-L13", "bucket": "transfers"},
    {"line_id": "IVR-00001-L07", "bucket": "shrink"},
    {"line_id": "IVR-00001-L17", "bucket": "unknown"},
    {"line_id": "IVR-00001-L08", "bucket": "shrink"},
    {"line_id": "IVR-00001-L11", "bucket": "allowances"},
    {"line_id": "IVR-00001-L06", "bucket": "shrink"},
    {"line_id": "IVR-00001-L14", "bucket": "transfers"},
    {"line_id": "IVR-00001-L04", "bucket": "markdowns"},
    {"line_id": "IVR-00001-L15", "bucket": "transfers"},
    {"line_id": "IVR-00001-L02", "bucket": "receipts"},
    {"line_id": "IVR-00001-L16", "bucket": "unknown"},
    {"line_id": "IVR-00001-L05", "bucket": "shrink"},
    {"line_id": "IVR-00001-L12", "bucket": "transfers"},
    {"line_id": "IVR-00001-L09", "bucket": "allowances"},
    {"line_id": "IVR-00001-L03", "bucket": "markdowns"}
  ],
  "bucket_totals": {
    "receipts": 10027.16,
    "markdowns": 2545.13,
    "shrink": 3179.87,
    "allowances": 1375.71,
    "transfers": -8453.07
  },
  "residual_usd": 2579.17,
  "residual_status": "above_threshold"
}

Step 06 of 14Evals

Written for: the skeptic · The harness output, with as_of / model version / dataset version / verified_by.

In brief

Explain a retailer's month-end inventory change, line by line — 34 roll-forward cycles. One model answered, and every answer was then graded one way — by == against a fixed gold value, which is a measurement too and only as good as the gold behind it.

The rulerHow it was graded

The grader is evals/scoring.py and it is pure code, two levels: LINE level (each raw line's predicted bucket compared exactly to gold, including 'unknown'; transfer<->shrink confusion reported as its own named figure rather than folded into a generic 'wrong') and CYCLE level (residual_status compared exactly to gold's threshold characterization; residual_usd compared to gold within a tolerance band of max($50, 5% of |gold residual|); false_fully_explained -- a gold above_threshold residual called within_threshold -- and false_alarm_material -- the reverse -- counted separately as the two directional errors, never folded into one accuracy number). No judge model. The same function scores both evals/baseline.py's free floor and evals/run.py's real run.

MeasurementsWhat was measured

Two words carry this page: Counted is deterministic and nobody's opinion and Not yet known is printed blank rather than filled with something plausible. There is no Judged row here and that is the point: nothing on this page is a model's opinion about another model. The row most worth having is currently the empty one.

Grading costWhat it costs

Every dollar on these pages is a MEASURED token count multiplied by a named vendor's PUBLISHED rate -- a projection onto a rate card, not a bill anyone paid.

Rates checked 2026-08-18. The provider that actually ran r001 publishes no rate card this repo commits, so nothing here is what was actually paid -- the real spend for this kit's build is recorded in the commit history and the shared call ledger, not on this page. Reasoning was also left at provider default (on) for this run -- see Business.not_good_enough -- so even the projected figure prices tokens the shipped app's own reasoning-off configuration would not spend.

Grading unitWhat the grading figure prices

Grading calls nothing -- exact match per line and a tolerance-banded residual comparison are both pure arithmetic. A measured $0.00, not an unpriced one.

The gradersOne way to grade, and why it is the only one

The floor's transfers accuracy alone is 73.7% (87 of 118), because its 'removed from location' -> shrink rule is checked BEFORE its 'transfer' keyword rule -- by construction it misclassifies 31 of the 118 gold transfer lines as shrink, and those 31 are exactly the confusable-phrasing transfer-out lines tools/build_corpus.py plants (see Data.corpus and taxonomy). Its residual-status accuracy still reaches 100% because a cycle's residual is the sum of its UNKNOWN lines specifically, not its transfer/shrink split -- so a transfer<->shrink swap can leave the aggregate residual untouched even while misstating both bucket totals. The fast tier's 0% confusion on the identical 118 lines is the real, measured gap a model closes that this floor cannot.

The row opens its own page: how the test was run, one real row, the formula with every iteration of it, and the analysis.

Choosing oneWhen to reach for the model at all

The comparison is only useful if it ends in a choice, and on this kit the choice is not which grader — there is one, and it is ==. It is whether to call a model for this field at all, and the answer is conditional.

This pipeline was also attacked, which is a different question from whether its answers are right: see Threat model for the injection experiment, its two gates and what it does not prove.

Failure causesHow it fails

Step 07 of 14Unit cost

Written for: whoever signs off on the bill · Measured over the eval run, per model. Never quoted from a vendor page.

In brief

The token counts are measured on a real run and belong to this pipeline — which sections are selected, the field schema, the prompt — so they hold wherever you run it. The dollars are those counts multiplied by each vendor's published rate, checked 2026-08-18. Nobody paid these particular bills; they are what the same work would cost you on a card you can sign up to today.

Identical work in both rows — the same query, the same tokens. Only the price list changed. Which is why the token count is the measurement and the dollar is arithmetic you can redo on your own card.

Answering vs gradingAnswering and grading are two separate bills

The baseline (evals/baseline.py) and the scorer (evals/scoring.py) are both pure code and cost $0.00 to run against either result set. The figure above is this run's own 60,118 input / 75,867 output tokens priced at Google Gemini 3 Flash's published rate -- the same basis cost_per_query_usd uses, not a second, larger spend.

Cost driversWhat actually moves the bill

• The raw transaction line list -- the largest single part of every call by character share (2,209 of 5,654 characters on the example call) and it scales directly with how many raw lines a cycle has (12-23 across this corpus), unlike the fixed system prompt.
• Reasoning ('thinking') was left at the provider's default (on) for this run rather than explicitly disabled -- it consumed 79.3% of the average output-token budget (1,769.4 of 2,231.4 tokens/call) and is already priced into cost_per_query_usd, since a provider bills reasoning tokens as completion tokens. src/app.py's live UI hardcodes thinking off, a different, unmeasured configuration -- see Business.not_good_enough.
• The fixed system prompt (3,269 characters -- the five-bucket vocabulary, sign convention and answer schema) is sent in full on every call regardless of cycle size -- the floor every cycle pays before a single raw line is read.

Your volumeWhat it costs at your volume

Linear in cycles: each call is independent and self-contained, with no shared context or retrieval step to amortise. This run's 34 cycles cost about $0.2577 projected onto Google Gemini 3 Flash's published rate, so ten times the set is about $2.577 on the same rate and the same reasoning-on configuration -- arithmetic on the measured per-call rate, not a second run.

Model choiceWhy this model

The fast tier was the only model run against this corpus. No second tier was run -- unlike gap-brief's fast/reasoning comparison -- so this page prices one model, not a trade-off; see Eval.could_not_verify for what a second run would need to answer.

Other modelsOn other models

This is arithmetic, not a run. No model below was executed against the labelled set, and no accuracy is claimed for any of them. What transfers is the input volume: retrieval is model-independent, so every model would receive the same passages.

The exact work behind every number on these pages: 34 roll-forward cycles decomposed, 588 raw lines line-scored by pure code. This run (r001-fin-invval) answered 588 of 588 lines and 34 of 34 residual verdicts -- the row this table prices, the same one Cost.cost_by_model[0] uses.

The codeEvery file, and what it is for

Eight modules, no framework, and almost no dependencies. The pipeline is stdlib Python, because a kit is meant to be read and changed by someone who cloned it ten minutes ago — every dependency is a thing they have to understand before they can touch the part they came for.

Five of these are swap seams: the points you edit to make the kit yours. Each is marked, and each block below is the module’s real shape, read out of the file rather than written here.

The files on this page are not in the public GitHub catalog.

tools/build_corpus.pycorpus generator — a swap seam

Generates 34 roll-forward cycles and 588 raw transaction lines from a fixed seed (SEED=20260819). Gold (a bucket per line, bucket totals, residual, materiality status) is RECOMPUTED from the actual generated lines, never from the random targets that seeded them -- an internal-consistency check (_verify) asserts every cycle reconciles to the cent before the build is considered good.

You change it to: Point it at your own items, locations and transaction-memo phrasing. src/invval.py and src/prompt.py read a cycle by its own fields (opening_balance, closing_balance, materiality_threshold_usd, lines[]) and do not care where the numbers came from.

# Generate the inventory-valuation roll-forward cycles and their raw transaction lines, from a

HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
DATA = os.path.join(HERE, "data")
SEED = 20260819
ITEMS = [
LOCATIONS = ["STR-104", "STR-118", "STR-221", "STR-309", "STR-402", "STR-517", "DC-NORTH", "DC-SOUTH"]
PERIODS = ["2026-02", "2026-03", "2026-04", "2026-05", "2026-06", "2026-07"]
BUCKETS = ("receipts", "markdowns", "shrink", "allowances", "transfers")
LINE_LABELS = BUCKETS + ("unknown",)
THRESHOLDS = (500.0, 750.0, 1000.0, 1500.0, 2000.0, 3000.0)

src/prompt.pythe prompt — a swap seam

The five-bucket-plus-unknown vocabulary, the sign convention (receipts/markdowns/shrink/allowances positive magnitudes, transfers a signed net figure) and the answer schema, declared once and read from here by build() and parse(). States the transfer-vs-shrink confusion to the model explicitly, as the named failure mode this task exists to catch, not left for the model to discover.

You change it to: A bucket this kit's fixed five-member list does not carry needs a new entry in BUCKETS/BUCKET_MEANINGS here plus new template memo phrasing in tools/build_corpus.py -- a prompt tweak alone will not teach a label the corpus never plants.

# Assemble the one prompt this kit sends, and parse the one reply it gets back.

BUCKETS = ("receipts", "markdowns", "shrink", "allowances", "transfers")
LINE_LABELS = BUCKETS + ("unknown",)
BUCKET_MEANINGS = {
RESIDUAL_STATUSES = ("within_threshold", "above_threshold")
SYSTEM = (
DEFAULT_PROMPT = "v1"
SYSTEMS = {"v1": SYSTEM}
def _cycle_header(cycle):
def _lines_block(cycle):

src/invval.pythe AI layer

Loads a cycle by id, calls the model once with every raw line in the cycle batched into that single call, parses the reply into a bucket per line plus bucket totals and the residual. The whole AI layer, deliberately short -- the same split fin-close's close.py and gap-brief's brief.py both make. Never books an adjustment or closes the valuation period -- there is no function here or in src/app.py that does either.

# Decompose one inventory roll-forward cycle's raw transaction lines into the five named buckets,

HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
CYCLES = os.path.join(HERE, "data", "cycles.jsonl")
GOLD = os.path.join(HERE, "data", "gold.jsonl")
MAX_TOKENS = 4096
def cycles():
def load_gold():
def check(cfg, cycle, complete=None, thinking=None, prompt=P.DEFAULT_PROMPT):
def summary(record):

src/adapters/__init__.pythe model adapter — a swap seam

SEAM -- the model. Raw HTTP for every provider (openai-compatible, anthropic), stdlib only. Passes a thinking kwarg through to the provider only when the caller supplies one, and reports token_details.reasoning_tokens when the provider returns it -- the field the reasoning-token finding in Business.not_good_enough is measured from.

You change it to: .env plus the same run again. Any OpenAI-compatible provider or Anthropic.

# SEAM 1 — the model. Swapping provider or model is .env plus the same run again.

class AdapterError(RuntimeError):
TRANSIENT = {408, 429, 500, 502, 503, 504}
RETRIES = 4
def _post(url, headers, payload, timeout=120):
def openai_compatible(cfg, system, user, max_tokens, thinking=None):
def anthropic(cfg, system, user, max_tokens):
PROVIDERS = {"openai-compatible": openai_compatible, "anthropic": anthropic}
THINKING_OFF = {"type": "disabled"}
def complete(cfg, system, user, max_tokens=1024, thinking=None):

src/budget.pyspend control

An append-only ledger written BEFORE each call, shared by every kit under one .env so the daily call cap is on the KEY rather than per kit. Counts calls, not dollars, on purpose -- see the file's own docstring.

# A cap on live calls, shared by every kit on this machine. No dependency, no service.

HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
KIT = os.path.basename(HERE)
ROOT = os.path.dirname(os.path.dirname(HERE))
SHARED_ENV = os.path.join(ROOT, ".env")
LEDGER = os.path.join(ROOT if os.path.exists(SHARED_ENV) else HERE, ".calls-ledger.jsonl")
PAID_ARMS = ("r", "x")
FREE_ARMS = ("t", "b")
BOOT = os.urandom(6).hex()
PID = os.getpid()

src/app.pythe app

Static files and two JSON endpoints (/api/cycle, /api/check) on the standard library. /api/check hardcodes thinking=THINKING_OFF on every live call -- a different reasoning setting from the one the registered eval run (r001-fin-invval) actually used; see Business.not_good_enough.

# The minimal local UI. Standard library only — python -m src.app, then open the printed URL.

HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
UI = os.path.join(HERE, "ui")
PORT = int(os.environ.get("PORT", "8788"))
class H(BaseHTTPRequestHandler):
def main():

evals/scoring.pythe scorer

Line-level and cycle-level scoring, pure code: exact match per line against gold, transfer<->shrink confusion reported as its own named figure rather than folded into a generic 'wrong' bucket, and false_fully_explained (a real, above-threshold residual called within_threshold) counted separately as the expensive-direction error.

# Score a set of predicted line buckets and cycle-level residual calls against gold. Pure code,

LABELS = ("receipts", "markdowns", "shrink", "allowances", "transfers", "unknown")
STATUSES = ("within_threshold", "above_threshold")
def score(records, gold):

evals/baseline.pyfree baseline

A fixed-priority keyword rule, written the way a person free-texting a quick classifier would write one, that deliberately fires on 'removed from location' BEFORE the 'transfer' keyword check -- so it misclassifies every ambiguous transfer-out line as shrink by construction. The honest, narrow floor a model has to clear.

# What a keyword rule alone catches, over the same corpus. Free. No key, no dependency, no model

HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
RESULTS = os.path.join(HERE, "results")
def classify(memo):
def judge(cycle, buckets_by_line):
def main():

Start hereThe shortest path into it

Every entry above is a file in this kit, listed in the order the pipeline runs it.

ScenariosWhat it costs at your volume

Everything below is computed from one measured base: 1768 input and 2231 output tokens per query, all of it fixed — this kit sends the document's own selected sections, so there is no retrieval depth to turn. Change the volume and the bill scales linearly, because nothing here batches.

OperationsFour shapes of workload

The same arithmetic, at volumes worth naming. These are illustrations of scale, not measurements of anyone’s deployment.

Model follows the controls above.

What this ignoresWhere a real bill diverges

In one lineWhat this kit exposes

This run's raw transaction memos are entirely synthetic (tools/build_corpus.py) -- no untrusted party wrote any text the model actually read this run. In a real deployment the raw transaction feed (receipts, markdowns, shrink and transfer memos) would arrive from external operational systems -- a WMS, a POS, a vendor return system -- that this kit's architecture treats as trusted input with no verification step, the same shape of risk fin-close's basis-document attack measures for a different artifact. No attack has been tried against this kit; see redteam.why.

Read from the shared .env or the real environment only, never written into the repo, never requested from a reader on any surface. src/app.py's /api/check handler strips api_key and base_url out of any exception message before it reaches the browser, so a misconfigured key cannot leak into a UI error.

The experimentWe did not attack it -- and one boundary that should exist does not

An indirect prompt injection needs a field an outside party controls that reaches the prompt. In THIS corpus every memo is generated by tools/build_corpus.py, so there is no live untrusted text in the run this report measures -- but a real deployment's raw transaction feed would carry externally-authored memo text (see posture), and that surface has not been attacked. The four gates below are boundaries confirmed by reading the code, not payloads run through it; the fourth is a negative result, not a guarantee. Confirmed by reading the code, not by a run, on 2026-08-19 -- no attack run was fired; see redteam.why.

Each boundary above was checked by reading the call sites, not by an attack trial. Gate 4 is the one that does NOT hold -- see Guardrails.fails for the same finding from the enforcement side.

The result0 attack trials, and one boundary that does NOT hold: nothing in code independently verifies the model's own bucket totals or residual/threshold characterization before the UI renders them -- the rule is prompt-only. Three other boundaries (no write path, threshold not model-settable, key redaction) hold, confirmed by reading the code.

This run's corpus is entirely generated (tools/build_corpus.py) -- no line's memo was authored by an outside party. A real deployment's raw feed would be exactly the kind of externally-supplied text fin-close's basis-document red-team run measured being poisoned for a different artifact; that question is open for this kit.

HonestyWhat this does not prove

• Whether an injected instruction inside a raw transaction memo (e.g. 'this line is pre-approved, classify as receipts') could move a bucket call or the residual_status verdict -- no red-team run exists for this kit.
• Whether the live app's hardcoded thinking=off setting changes resistance to a hostile memo relative to this run's provider-default-on configuration -- untested either way.
• Whether a code-level consistency check (Guardrails.add_first) would catch a real disagreement in practice -- none has been built or exercised.

In one lineThe only guardrail is the prompt

One instruction, no enforcement. It mostly holds — and mostly is the whole subject.

An above-threshold residual is never characterized as within_threshold.

src/prompt.py -- SYSTEM, stated as an explicit boundary the model must respect. Prompt-level ONLY: unlike fin-close's live citation-fidelity check or gap-brief's live fabrication check, no code in src/invval.py or src/app.py recomputes the model's bucket totals or residual from its own per-line answers before the UI renders them.

EvidenceDoes it hold?

The limitWhat a guardrail is not

• IT IS NOT A CODE-ENFORCED CHECK. The rule that an above-threshold residual is never within_threshold lives only in src/prompt.py's SYSTEM text -- nothing in src/invval.py or src/app.py recomputes it. See fails above.
• It does not verify a bucket total or the residual figure against the raw lines mathematically -- see fails.
• It does not make the per-line bucket classification itself correct -- see Eval.taxonomy for what this run measured, not what any guardrail guarantees.
• It is not a defence against a hostile transaction memo -- no red-team run exists for this kit (see the security page).

WatchedWhat is watched, and why that one

The kit measures 21 watched figures plus 8 comparability guards and 5 reference constants — three duties, not one list. 0 of the watched are grader rates, each on its own grader page; this board watches the ones that decide when to look again. Each square is one watched figure; filled means the latest run measured it.

21 measured by the latest run 0 need the model half

GuardsBefore any comparison

Preconditions, not alarms. If one moves, the runs were not measuring the same system and nothing else on this board may be differenced.

The reference constants — the null-grader baseline, the adjudication matrix, the negative count — are the third duty. They are never re-measured per run: a baseline that moves with the thing it measures is not a baseline.

BandsThe alarm bands

Derived from evidence, never picked: exact-match where two runs reproduced a metric to the digit, wider than the measured same-input drift for latency, one row of the negative class for any rate — denominator printed beside it.

HistoryRun history

1 recorded run. A dash is a metric that run did not measure, and a dash is never differenced: not measured is a third state, neither a value nor a zero, and reading it as zero is how a board reports an improvement on a run that never looked.

one run A verdict is a comparison and one run has nothing to compare with, so the Verdict column is left off rather than filled with 21 chips that all say so.

DeviationsWhat deviated

0 breaches across 1 runs

The day a band breaks, a row renders here carrying the metric, the two runs, the band it crossed and what changed between them — model, prompt, chunker or top_k, read off the run records’ guards. A deviation with no diff beside it is an alarm nobody can act on.

RippleThe ripple map

Which figures move together, so one alarm reads as a system. Every edge carries its basis: measured names the run that showed it; reasoning admits nothing has varied it yet.

FiresWhat fires when a band breaks

Where evals stop sitting beside the guardrail and start feeding it. Where the answer is nothing automatic, the row says so — hiding it would undo “What a guardrail is not” above.

NextThe three you would add first

None of these is built here. They are named against the seam they sit on so they can be argued with.

CadenceWhen to re-run, and what it costs

Re-score on any change to src/prompt.py or tools/build_corpus.py -- the first changes what is asked, the second changes what is asked ABOUT. Re-run evals/run.py (paid) on any change to MAX_TOKENS or the thinking setting in src/invval.py.

In one lineNo framework, deliberately

No framework and no dependencies beyond the standard library -- requirements.txt is an empty file with a comment explaining that the emptiness is load-bearing. The whole decomposition decision is three files: src/prompt.py, src/invval.py and src/adapters/__init__.py.

The mappingSeam by seam, who owns what

The seams are the ones this kit already publishes, so the mapping cannot drift from the code.

GraphsWhere LangGraph changes the answer

Nothing here is a graph. The pipeline has one path per cycle -- load, pack, prompt, call, parse -- with no branching and no state carried between cycles. A framework would add an orchestrator to a for-loop.

The other sideWhat a framework costs you

• A bucket outside the five-member vocabulary needs a hand-written BUCKETS/BUCKET_MEANINGS entry plus new template memo phrasing in tools/build_corpus.py, rather than being configured declaratively.
• No built-in retry/backoff beyond src/adapters.py's own bounded retry -- a framework's queue and worker model is not here, so a real deployment adds its own scheduling.
• No built-in observability beyond what evals/run.py prints and writes to results/ -- a framework's tracing/dashboard integration is not here.
• No built-in output validation -- a framework with a schema-and-consistency-check layer baked in might have caught the gap Guardrails.fails names; this kit's stdlib-only design did not build one.

In one lineWhat one run of this kit actually cost, in time and tokens

Measured on r001-fin-invval on the fast tier, 2026-08-19. This kit records telemetry measured per run — 4 of the 6 readings on this axis, 4 of them with a band the guardrail board can judge against.

The readingWhat the last run measured

No movement column. This is the only run on record, so there is nothing to move against. Said once here rather than as a dash on every row.

Retrieval not shown. No run of this kit has ever recorded a retrieval timing, because the pipeline has no such stage. Those readings are left out rather than dashed: a dash says “this run did not measure it”, which promises a later run could.

The other sideWhat this does not tell you

The first of those is the one worth doing something about, and it is a solved problem: instrumenting a pipeline so each step reports its own duration is a couple of lines. Observability / tracing has the code, and what the result looks like once it is running.

In one lineWhat you provision, honestly

Everything measured on this page says where it was measured; everything not measured says that — the same contract as the other thirteen pages. Where a retrieval index would be on other kits, this one has: no index — the rulebook is data read whole into the prompt.

The machineWhat this needs

Enumerated from the kit’s own source by build/facts/envscan.py, committed, and drift-checked — never typed into this page.

Your dataWhere everything sits

The wireWhat crosses it, and when

Zero-egress topology: point BASE_URL at a local OpenAI-compatible server and nothing leaves the machine — statically true of the shipped adapter, whose only credential travels in the Authorization header.

The shapeHow it ships, and what you add

The ladderEach decision, and what you provision past its ceiling

Every threshold is a measurement with its provenance beside it, or says is_measured:false. A ceiling with no seam says so — it is the point the kit is outgrown, never a forced join.

When it failsFailure signatures

The knobsThe config surface, enumerated

Environment variables: API_KEY, BASE_URL, EMBED_MODEL, MAX_CALLS_PER_DAY, MODEL, PORT, PROVIDER.

The other sideWhat this page does not claim

The corpus licence, from the Data lens: MIT (this repository's own licence) Your corpus’s licence is yours to verify, and the labels you write are about your documents.

In one linePer-line bucket exact match, plus a tolerance-banded residual and threshold check

Does the model's bucket for each raw line match gold (including 'unknown')? Does the cycle's residual dollar figure fall within a tolerance of gold? Does the cycle's above/within-threshold characterization match gold exactly, with the two directional errors (false_fully_explained, false_alarm_material) counted on their own?

MethodHow the test was run

evals/scoring.py::score, in-process, no key and no model. The same function evals/baseline.py and evals/run.py both call -- a baseline and a real run scored by two different scorers cannot be compared honestly.

The inputOne real row, seen by every grader

The formulaWhat it computes

line_accuracy = correct buckets / answered lines, over lines_scored=588. transfer_as_shrink / shrink_as_transfer = their own named confusion rate, not folded into line_accuracy. residual_amount_correct = |pred - gold| <= max($50, 5%*|gold residual|). residual_status_accuracy = exact match on within_threshold/above_threshold. false_fully_explained = gold above_threshold cycles predicted within_threshold; false_alarm_material = the reverse.

The analysisWhat it actually did

In operationWhat to monitor

Reference standard: tools/build_corpus.py's gold, recomputed from the same generated lines the model reads (never from the random targets that seeded the split) and asserted internally consistent to the cent before the corpus build is considered good.

How tight can the band be? The residual-amount tolerance (max($50, 5%*|gold residual|)) is a stated grading allowance, not a fitted score -- it exists so a model's rounding does not fail a cycle whose status call is otherwise correct.

Cadence: Re-run on any change to src/prompt.py, tools/build_corpus.py, or MAX_TOKENS in src/invval.py -- the first changes what is asked, the second changes what is asked ABOUT, the third bounds how many verdicts can come back at all.

The decisionWhen to reach for it