Home › Use Cases › Check configured accessorial codes against what the signed contract exhibit says
Use caseUC0256
🧪 Use-case kit · runnable

Check configured accessorial codes against what the signed contract exhibit says

A small, forkable project that does one job end to end. Run once for real, and every figure on these pages captured from that run.

The business caseThe problem this solves

A shipper's accessorial charge catalog is master data: a code, a description, a unit, a rate and an applicability rule, configured in the TMS rating table and mirrored into the settlement system and the freight-audit vendor's rulebook. The signed exhibit is the authority. Over a contract year amendments land, codes get added by hand for a one-off, and the three systems drift apart from the contract and from each other. Nobody reconciles it, because doing it means reading a schedule of forty to sixty clauses against three exports and deciding, per code, whether a difference is a rate, a trigger, an amendment nobody loaded, or a contract that never said. It surfaces when an audit finds it, usually as a dispute about invoices that were priced correctly from a catalog that was wrong. The quarterly hand reconciliation of a carrier's accessorial rate table against its signed exhibit — a schedule read clause by clause against three system exports — which is skipped in most shops until an audit or a dispute forces it.

Audience

The carrier contract analyst who owns the exhibit and the TMS master-data steward who is the only person permitted to change the catalog. The decision in front of them is not 'pay or dispute' — it is which of the sixty codes to open a change record on this quarter, and against which clause. This report answers a qualified yes: the paid arm is exact on the classes where a free regular expression is also exact, wins the whole margin on the nineteen packs where there is no figure to compare, and still abstains on three trigger conflicts it should have named. Every number on these pages came from one real run of this code, not from a vendor page.

The inputThe actual accessorial code packs

The corpus is 60 accessorial code packs, 0.10 MB (txt 60). A carrier's accessorial schedule is the commercially sensitive half of a freight contract. There is no public corpus of them and there is no licence under which a real one could ship inside a kit — so generating one is the only way this kit can carry the thing it is actually about, the CONFIGURED master data sitting beside the CONTRACT text that authorises it, and still be publishable. What it exercises was chosen rather than sampled. Eight disposition classes, 5 of them ARITHMETIC (a figure to compare) and 3 READING (no figure to compare), so the free floor's structural blindness is measurable rather than asserted. Fourteen packs carrying a written invitation to write the catalog, because a boundary is only interesting where something asks for it to be crossed. Ten findings worth under $250 a year, because this use case has no monetary cap and 'no cap' has to be measurable too. Wording that differs between systems on every in-agreement pack, so a matcher comparing description strings fails the easy class.

The corpus

  • The 60 accessorial code packsgenerated from a fixed seed, so no real record, person or institution appears in it.
  • Where each came fromSYNTHETIC AND GENERATED — not fetched, not scraped, not derived from any real contract. Every byte of the sixty packs is written by tools/build_corpus.py from the fixed seed 20260901, and python3 -m tools.build_corpus --check regenerates them and diffs them against what shipped; it reports REPRODUCES EXACTLY or names the file that moved. No real carrier contract, shipper master-data export, negotiated accessorial rate or person appears anywhere in it; 'Northbend Distribution Co.' and 'Cascade Freight Lines, Inc.' were invented for this corpus, and AC-2026 is not anybody's reconciliation policy. This sentence is written out because the generic provenance line — that a corpus was obtained from somewhere under some licence — would be false here, and a false provenance sentence is worse than a blunt one.

Swap this folder for your own material and the kit is pointed at your accessorial code packs. That is the whole change — there is no database to migrate.

One accessorial code pack, as the model receives itAC-0001.txt · 1 of 60
ACCESSORIAL CATALOG RECONCILIATION PACK - AC-0001
Shipper: Northbend Distribution Co.   Carrier: Cascade Freight Lines, Inc.
Contract: MSA-2024-CFL, Exhibit B (Accessorial Schedule), effective 2025-01-01
Reconciliation cycle: 2026-Q1   Accessorial code under review: DET-TRL
Billed spend on this code, trailing twelve months: $8,899.94

--- CONFIGURED MASTER DATA ---

[TMS]      rating table ACC_RATE
  code            DET-TRL
  description     Trailer detention after free time
  unit            per hour
  rate            75.00
  applicability   After two (2) hours of free time measured from carrier arrival, billed in fifteen-minute increments, no daily cap.
  status          active      last changed 2025-01-08 by load

[BILLING]  settlement table SETL_ACC
  code            DET-TRL
  description     Trailer detention after free time
  unit            per hour
  rate            75.00
  applicability   After two (2) hours of free time measured from carrier arrival, billed in fifteen-minute increments, no daily cap.
  status          active      last changed 2025-01-08 by load

[AUDIT]    freight-audit vendor rulebook
  code            DET-TRL
  description     TRAILER DETENTION AFTER FREE
  unit            per hour
  rate            75.00
  applicability   After 2 hours of free time measured from carrier arrival, billed in fifteen-minute increments, no daily cap.
  status          active      last changed 2025-01-08 by load

--- CONTRACT AUTHORITY (Exhibit B, as amended) ---

[EXB-2.1]  Trailer detention after free time. The charge is seventy-five dollars ($75.00) per hour,
          after two (2) hours of free time measured from carrier arrival, billed in fifteen-minute
          increments, no daily cap.

--- REGISTER NOTES ---

Abridged — the file continues.

The outcomeWhat a good result looks like

Every configured accessorial code carries one of eight dispositions, the id of the clause that governs it TODAY (the amendment's, where one replaced the original), the systems that are wrong against that clause, one sentence from the pack that establishes it, and the named human desk that owns it. On r002-accessorial-catalog: 57 of 60 dispositions correct (95.0 pct), 60 of 60 governing clauses cited correctly, 57 of 60 conflict sets exact, and 57 of 60 packs right on all five graded fields.

And when it cannot

It abstains. Three of the eight trigger-conflict packs — where the configured applicability rule ADDS a condition the exhibit is silent about — are answered needs-contract-review instead. That is a SAFE wrong: the pack still reaches a named human, nothing is written, and the confidence on all three (0.70 / 0.85 / 0.92) sits below the 0.99 median of the answers it got right. But it reaches the contract manager rather than the contract analyst, and a conflict filed as an ambiguity is a conflict nobody closes.

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.

  • Your catalog's drift is rates and missing codes — the arithmetic classes — the free rules floor, src/rules.py
    it is EXACT on those 41 packs and costs $0.00. The paid arm scores the same 41 of 41.
  • Your contract has amendments and nobody reloaded the rate table — the paid arm
    superseded-authority is 6 of 6 for the model and 0 of 6 for the floor. A comparator that takes the first stated figure agrees with the catalog and is confidently wrong about which clause is live.
  • You need to know which codes the exhibit never priced at all — the paid arm
    needs-contract-review is 5 of 5; the floor reads an unquantified clause as no authority and files all five as undefined-in-contract, which sends them to the wrong desk with the wrong question.
  • Your applicability rules are where the drift lives — the paid arm, with a person behind it
    trigger-conflict is the weakest class at 5 of 8, and the three misses are abstentions rather than wrong findings.

And where nothing here is good enough:

  • You want the pipeline to fix the catalog for you — nothing in this kit
    AC-B1 is absolute and there is no code path that writes master data. The kit produces the row a named human works from.

At a glanceHow the whole thing runs

85–95%disposition accuracy pct over all 60 packs
7,696 msp50, end to end
$5.36per 1,000 accessorial code packs · Gemini 3 Flash

Run once, for real, on 2026-09-01. 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.

What do I have to bring?Replace tools/build_corpus.py with a reader over your own material and keep two shapes. THE MEASURED ACCURACY DOES NOT TRAVEL WITH THE CODE. Corpus lens →
When is this the wrong choice?Avoid: Paying for a model call to reproduce a numeric comparison you can run in a loop. That is the case against the best-fitting scenario (“Your catalog's drift is rates and missing codes — the arithmetic classes”). 5 scenarios scored in all, each with its own. Eval lens →
Where does it stop working?A pack whose exhibit excerpt is the WRONG excerpt. This kit is handed the relevant clause already cut; on a real contract, picking it out of a base agreement plus three amendments is the hard step, and a wrong excerpt produces a confident undefined-in-contract on a code the contract does define. 6 recorded failure modes, each from a run rather than a guess. Corpus lens →
What was never verified?WHETHER THE FIVE needs-contract-review PACKS REALLY ARE AMBIGUOUS. The label says the exhibit fixes no rate; whether a contract lawyer would agree that “as mutually agreed in good faith” leaves nothing to reconcile is a judgement, and it is the corpus generator's. 6 items this kit says it could not check. Eval lens →
Can I run this on a model I control?The shipped adapter is an OpenAI-compatible endpoint reached over raw HTTP — src/adapters/__init__.py. The runtime provider is not named on this page; PROVIDER and MODEL in .env are what select it, and that file is the only one in the kit that knows which.; the Prompt lens states what swapping it costs. The published figures come from 1 model on the fast tier. Prompt lens →
And if it fits — what do I stand up?5 artifacts with a stated home and a stated egress, and 4 decisions each with what you provision past its ceiling — plus what was not measured. That is the next page, not this one. step 14 — Run it in your environment →

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-09-01 — r002-accessorial-catalog. 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.

Run this on your own data

  • The pipeline, its eval harness and the runs behind every numberdeployed inside your environment, on your own model endpoints, against your own documents.
  • The corpus above is the shape, not the limitit is a folder swap, and there is no database to migrate.

Talk to us →

Checked before this shipped — A clean checkout with no key configured renders the whole board — all sixty packs, the answer key, the policy ladder, both free floors and every committed run — and scores the free floor offline in under a second. The 'check with the model' control is disabled and says why. What a clean checkout could not do is reproduce the paid arms, which need a provider key.

A living map of modern AI — kept current every morning