Documentation
How Rating Variance produces RATE_VARIANCE claims from contract rate tables.
Overview
LangGraph orchestration of deterministic tools (condata-rating-variance) — not a ReAct agent. Compares billed linehaul to expected linehaul from the imported contract rate table only. It never invents CPMs. Optional Grok may rewrite explanations or suppress FPs. Orchestrator mirrors claims; unauditable bills become unprocessed transactions there — not guessed rates here.
Inputs
- Bills: LHAMT/linehaul, miles, O-D geo, SCAC, ship date, invoice/PRO; accessorials only to isolate LH.
- Contract: SCAC, effective window, rate_table (CPM/flat/min/discount/lane).
- Bill-level contract_rate is not used by the current matcher.
Architecture (LangGraph orchestration)
One StateGraph via RatingVarianceAgent — a hybrid pipeline: fixed linear nodes call deterministic tools in hard-coded order (not LLM-selected). No sub-agents, subgraphs, conditional edges, or HITL interrupts. Optional Grok may rewrite explanations or suppress FPs but cannot invent rates or branch the graph.
Entry: analyze_shipment → RatingVarianceState ( shipment, contract, thresholds, emit_claim=false) → graph.invoke. Batch then filter_duplicate_clone_findings.
| Tool | Purpose | Key I/O |
|---|---|---|
| extract_linehaul_amount | Isolate billed LH | In: shipment → Out: linehaul, source, ok |
| lookup_contract_rate | Imported rate row only | In: contract + SCAC/date/geo → Out: matched, rate_record, lane_score |
| calculate_expected_linehaul | Expected LH | In: rate_record, miles → Out: expected, formula |
| compare_linehaul_variance | Material overcharge gate | In: billed, expected, thresholds → Out: variance_*, material_overcharge |
- Claim: material overcharge + matched rate + llm_review not suppressed → RATE_VARIANCE with evidence-bound rate_line_citation and scored confidence (not a skip gate).
- Skip/cannot-audit: no_valid_contract_rate, linehaul_amount_missing, undercharge_not_emitted, variance_not_actionable, llm_suppressed_false_positive, duplicate_charge_clone.
- Accuracy: tools never invent CPM; LLM is facts-only / suppress-only; evidence binds SCAC, lane, CPM, dates, formula.
How it works
Graph: parse → retrieve_contract → match (lookup_contract_rate) → calculate_differences → explanation → confidence → llm_review → emit. Tools are deterministic Python.
Rate matching & math
lookup_contract_rate never invents a CPM. It requires a present contract, a parseable ship date inside the effective window, a non-empty rate table, and a lane match with min_lane_score=70. SCAC is a hard reject only when both the bill and the contract have a SCAC and they disagree (scac_mismatch); it is not used to pick among rate_table rows—those are chosen by ship date and lane score. (Upstream, the Orchestrator usually requires bill SCAC to select which contract to pass in.)
| Topic | Rule |
|---|---|
| SCAC | Reject only if both bill + contract SCAC present and differ; blank SCAC skips this gate |
| Lane score | ZIP +40, city +35, state +5; min_lane_score=70; nationwide fallback score 70 |
| Expected LH | max(CPM×miles, min)×(1−discount) or flat×(1−discount) |
| Material overcharge | variance > 0 AND abs(pct) > 5% AND abs($) ≥ $5 |
| Undercharges | skip_reason undercharge_not_emitted |
| Linehaul isolation | LHAMT preferred; else billed−accessorials; never bare invoice total |
Confidence
Base 0.60 (material only) + lane/LH/variance/identity bonuses, cap 0.98. Confidence is attached to every qualifying claim — not used as a hard skip floor. Lane score ≥ 70 remains a rate-match quality gate (no inventing rates). Optional Grok may rewrite explanations or suppress; cannot invent amounts.
Evidence
- claim_type RATE_VARIANCE; method billed_minus_expected; FSC/accessorials excluded.
- Evidence: matched_rates, comparison, contract_context, expected_calculation, rate_line_citation, confidence_breakdown.
Accuracy & non-goals
- Decimal money; prefer zero false claims over recovery.
- Never invent CPM or linehaul from invoice total alone.
- Does not rate fuel/accessorials (see Accessorial Overcharges).
- Cannot-audit → skip_reason; Orchestrator tracks unprocessed.
Example
DET→CHI CPM $2.10, min $450; bill LHAMT $820 / 280 mi → expected $588, variance $232 (~39%), confidence ≈ 0.96 → RATE_VARIANCE $232 with rate line citation.