Documentation
How Accessorial Overcharges compares billed charges to contract rules and CRRCT corrects.
Overview
Deterministic LangGraph pipeline (not a ReAct agent) evaluates billed accessorials against imported contract rules and optional CRRCT corrects. No industry default rates and no LLM on the live path. Emits one ACCESSORIAL claim per PRO. Missing rules → skip here; Orchestrator records unprocessed (NO_ACCESSORIAL_RULE / NO_FSC_RULE).
Inputs
- Bills / PAYMENT rows: accessorial amounts, optional CRRCT_*, PRO/invoice/SCAC/ship date, linehaul for FSC.
- Contract from Clients MS: SCAC, window, accessorial rule rows.
Architecture (LangGraph orchestration)
One StateGraph via AccessorialOverchargeAgent — LangGraph is a workflow runner only. No sub-agents, subgraphs, conditional edges, HITL interrupts, or LLM tool selection. Tools load rules and evaluate overcharges; explanations are templates. LLM modules exist but are not wired into the live graph.
Entry: run → AccessorialAgentState (freight_bills, contract, llm_used=false) → single graph.invoke for the batch.
| Tool | Purpose | Key I/O |
|---|---|---|
| get_accessorial_rules | Imported rules for SCAC + date | In: contract, scac, ship_date → Out: ok, rules, reason (never invents defaults) |
| evaluate_accessorial_charges | CRRCT or contract vs billed lines | In: bill, rules → Out: component overcharges only (claim > 0) with evidence |
- Claim: component overcharge + amount ≥ $5 → one ACCESSORIAL per PRO with component_findings[] and scored confidence (not a skip gate).
- Skip/cannot-audit: no contract rules without CRRCT; type without rule/CRRCT skipped; below $5 dollar gate → suppressed_claims.
- Accuracy: only imported limits or CRRCT; DEFAULT_ACCESSORIAL_RULES is shape-only (all None); evidence binds method/allowed/billed.
How it works
parse → load_rules (get_accessorial_rules) → evaluate_accessorial_charges → template explanations → confidence → emit. LLM is not wired into the live graph.
Claim criteria
| Gate | Default |
|---|---|
| Methods | crrct_correct_value, flat_threshold, hourly_with_free_time, pct_of_linehaul, absolute_cap, daily_with_free_days |
| Confidence | Scored and attached — not a hard skip floor |
| Min amount | ≥ $5.00 |
| Aggregation | One ACCESSORIAL claim per PRO |
| No rule for type | Skip (not full-billed unauthorized claim) |
Confidence: base 0.70 +0.12 method +0.08 contract/crrct +0.04 if ≥$50, cap 0.98. Decimal half-up money.
Evidence
- component_findings with method/allowed/billed; rule_source contract|crrct.
- claim_calculation.method aggregated_accessorial_lines.
Accuracy & non-goals
- Never invents industry default rates.
- Prefer miss over guess when type has no rule.
- No llm_review in live graph.
- Cannot-audit → Orchestrator unprocessed, not $0 claims.
Example
Liftgate allowed $50 billed $95; fuel 30% of $900 LH allowed $270 billed $400 → components $45 + $130 → one PRO claim $175.