DOCKET
Evidence-backed Dispute Operations
AI understands the evidence. Deterministic policies verify it. Merchants remain in control.
PayPal AI Hackathon 2026 · Gemini 2.5 Flash · PayPal Sandbox · FastAPI + React · SQLite
Inspiration
A shipping label is printed. The buyer says the package never arrived. The merchant is under pressure to respond.
In that moment, a generic AI assistant might turn “label created” into “package delivered”—a confident sentence with no delivery proof behind it.
We wanted to solve a more important problem than writing faster dispute responses:
How can AI help merchants understand messy evidence without letting it invent facts or make unchecked financial decisions?
That question became Docket. Our design principle is simple: Deterministic Refusal Over Probabilistic Defense.
What it does
Docket is an AI-assisted operations desk for PayPal disputes. It brings dispute information together with merchant order records, available shipment data and buyer communications—then shows what the evidence actually supports.
| Docket does | Why it matters |
|---|---|
| Extracts claims from unstructured buyer messages with Gemini, with an offline deterministic mode available. | Turns free text into information an operations team can inspect. |
| Checks citations against the source text and validates source references. | A plausible sentence is not treated as proof. |
| Reconciles records across PayPal, merchant orders and carrier information. | Surfaces missing links and discrepancies instead of hiding them. |
Enforces policy in code with ALLOW, REVIEW and BLOCK outcomes. |
The LLM cannot override deterministic policy checks. |
| Requires merchant authorization for sensitive actions. | A human approves the exact action and evidence payload. |
| Records an audit trail in SQLite with SHA-256 parent-hash chaining. | Important events can be inspected and the chain can be verified for tampering. |
How we built it
We built Docket with Python, FastAPI, Pydantic, React, TypeScript, Vite, AG Grid and SQLite. It integrates with the PayPal Sandbox Disputes API and Orders API.
The decision pipeline
The boundary between each stage is intentional:
- Treat buyer communication as untrusted input. Inspect it for prompt-injection attempts before processing.
- Extract structured claims. Gemini 2.5 Flash performs semantic extraction; offline mode remains available without an external model call.
- Validate provenance. Source IDs must come from the supplied source set, and quoted text is checked against the original record.
- Compare evidence. Docket identifies discrepancies across the buyer's account, merchant records and carrier signals.
- Apply deterministic rules. The policy engine—not the LLM—produces
ALLOW,REVIEWorBLOCK. - Put the merchant in control. Authenticated approval is bound to the intended action and payload before a sensitive dispatch can proceed.
Persistent by design
SQLite in WAL mode stores dispute state, source records, claims, evaluations, approvals and audit events. Webhook idempotency and restart recovery help preserve operational state. SQLite is the canonical audit store; the JSONL file is a recoverable export.
The audit ledger uses a deterministic event representation and SHA-256 parent-hash chaining. Verification can detect in-scope changes to recorded events. It is tamper-evident, not a claim that a local database is physically immutable or independently anchored against every possible attack.
Challenges we ran into
A claim is not the same as a verified fact
If a buyer says, “The courier told me the parcel was left at another address,” the source proves that the buyer reported that conversation. It does not independently prove the courier confirmed misdelivery. We built source attribution and verbatim citation checks to preserve that distinction.
A delivery scan is not the whole story
DELIVERED is a carrier status. Whether it establishes delivery to the right destination depends on the available tracking and address evidence. We had to make policy outcomes reflect exactly what was checked—and return REVIEW when evidence is incomplete.
Safe actions need more than an available API link
A PayPal action can be technically available while the facts still need review. We therefore separate factual readiness, API action eligibility and the merchant recommendation.
Reliability lives in the failure paths
Webhook retries, duplicate deliveries, approval replay, interrupted writes and server restarts forced us to design beyond the happy path. We added persistent idempotency, transactional approval consumption, restart recovery and a recoverable audit export.
Accomplishments that we're proud of
- Retrieved a genuine dispute from the PayPal Sandbox through the Disputes API.
- Verified a real Google Gemini 2.5 Flash API extraction request through Docket's semantic extraction and policy-verification workflow, using synthetic dispute input.
- Built a deterministic policy engine that remains authoritative over AI-generated claims.
- Implemented authenticated merchant sessions and payload-bound, single-use approval controls.
- Added persistent SQLite storage, webhook idempotency, restart recovery and a tamper-evident audit trail.
- Built a 20-scenario synthetic benchmark suite, with 20/20 scenarios passing in the reported evaluation.
- Recorded 340 passing backend tests in the reported full test run and a successful frontend production build.
Our proudest accomplishment is not simply that Docket uses an LLM. It is that the system can benefit from AI while keeping evidence verification, policy decisions and authorization in separate, enforceable boundaries.
What we learned
We learned that responsible AI is not just a better prompt. It is an architecture.
A statement, a citation, a verified fact, a policy outcome and an authorized action are five different things. Treating them as interchangeable creates risk. Keeping them separate made Docket more explainable, testable and resilient to incorrect or adversarial model output.
We also learned to take idempotency, durable state, transaction boundaries and recovery testing seriously. In a financial workflow, the failure path is part of the product—not an edge case to postpone.
What's next for Docket
We want to take Docket beyond the current Sandbox demonstration by:
- Expanding merchant ERP and carrier integrations.
- Supporting more dispute categories and jurisdiction-aware policy contexts.
- Strengthening audit verification with independently stored integrity checkpoints.
- Improving operational monitoring, recovery and deployment practices.
- Exercising the complete evidence-preparation, merchant-approval and PayPal submission journey across more Sandbox scenarios.
- Exploring production-ready multi-merchant identity and access management.
**Docket doesn't ask merchants to trust AI blindly.** It gives them evidence they can inspect, decisions they can understand, and actions they remain in control of.
