How ReturnPilot works under the hood.

Key design decisions

• 01

  The LLM proposes, deterministic code disposes

  Eligibility, refund limits and whether a human must approve come from a pure-Python policy engine with exhaustive tests. Write tools only return proposals.

• 02

  interrupt() + Postgres checkpoints

  Risky actions pause the LangGraph run at an approval gate. State is checkpointed, so a reviewer can decide hours later and the run resumes exactly where it stopped.

• 03

  customer_id comes from the token

  The web server signs a 5-minute ES256 JWT per request. The agent runtime injects the customer id into every tool call — it isn't in the tool schema, so the model can't be talked into reading another customer's data.

• 04

  Idempotent jobs

  Refunds and labels run as Celery jobs keyed by sha256(action + target + approval). Double clicks, retries or a restarted worker can't refund twice.

• 05

  Trajectory evals, not vibes

  30 scenarios assert the tools called (in order), tools never called, approval routing and zero policy violations — deterministic tier on every PR, live tier nightly.

• 06

  Two free providers + a quota guard

  Groq Llama 3.3 for tool use and 3.1-8B for routing, Gemini as fallback. Usage is counted per day; at 90% the router switches, and when both run out the demo degrades to read-only.

• 07

  Per-visitor demo sandboxes

  Each browser gets a workspace id cookie; the backend clones the demo store for it. Customer and reviewer personas share it, so one person can play both sides privately.

• 08

  The browser never holds a backend token

  Auth.js keeps an httpOnly session; every API call goes through the Next.js proxy, which re-checks the role, mints the JWT and streams SSE through unbuffered.