Loss claims decided by rules, not by the model
An assessment service that takes a delivery network's loss claims, lets a model answer three narrow questions, runs every check in a fixed order, and either approves or hands a person the full list of reasons.
Context
When a parcel is lost, the shipping account files a loss claim and a claims team validates it: was it raised in time under that account’s contract, is the parcel really lost, are the goods something the network accepts liability for, what is the payout and which depot carries it. Each claim is a few fields and a free-text description of the goods, and each one used to be read by a person. The network wanted the straightforward ones decided automatically and the rest handed over with the work already done.
Constraints
- The decision had to be explainable claim by claim. “The model thought so” is not a reason a claims team or an auditor can act on.
- Contracts differ by account: claim windows and liability clauses live in free text, and they override the defaults.
- Goods descriptions are ambiguous. “Galaxy” might be a chocolate bar or a phone, and one of those is on the prohibited list.
- Anything the service could not decide with confidence had to go to a person, with the reasons, not be approximated.
- Recipient details are not needed for the decision, so they are never used.
What we built
A FastAPI service on Cloud Run that takes a claim and returns one of two outcomes, approved or manual review, together with a decision log of every check it ran. Claims arrive daily from the case system, with the recipient’s details discarded on entry, and queued claims run through Cloud Tasks with checkpoints in Cloud SQL, so a retry resumes from the failed step rather than starting over.
The facts come from two lookups, neither of them done by the model: the parcel’s history, delivery scans, customer contact, depots, reconsignment, through one MCP server, and the account’s contract terms through another. Gemini on Vertex AI is asked exactly three questions, and only when the text requires it: what the goods actually are and whether they are prohibited, with a web search when the description is ambiguous and a confidence score on the answer; how many days the contract allows for a claim, if it states a number; and whether the contract names a remittance address.
Then a LangGraph workflow runs the checks in a fixed order, and the model never chooses the next step:
- Raised in time under the contract.
- Liability accepted, with identification confidence above the threshold.
- No delivery confirmation after the claim was raised.
- No scan that suggests a cross-label.
- A settlement depot assigned.
- Not reconsigned or relabelled.
- No special remittance terms.
- Amount within the automatic payout limit.
Every check passes and the claim is approved; any check fails and it is manual review, with every failed check named and the settlement depot and cross-charge already worked out for the reviewer. Decisions land in BigQuery and every assessment is traced in LangSmith.
Outcome
Around 200 claims a day assessed since early 2026, each with a log a reviewer can read in a minute. When confidence is low the claim goes to a person, and when a service is unreachable the step is retried. Built, deployed and maintained by Jakub.
Stack
Python, FastAPI on Cloud Run, LangGraph, Gemini on Vertex AI with web search, two MCP servers for parcel and account data, Cloud Tasks, Cloud SQL, BigQuery, LangSmith.