Case Companion — Lawhive Hackathon

A conversational legal intake-and-triage agent for non-lawyers. The user chats their situation and forwards messy evidence; the agent actively runs the intake and builds a live case picture:

1. Guided intake — actively asks for what's missing ("do you have proof you cancelled?") instead of waiting
2. Case Readiness score — a live 0-100 gauge of how ready the case is to hand to a lawyer (+ a "raise your score" checklist)
3. ⭐ Damage assessment — what the user already did that may have hurt their case (signed form, missed deadline, covert recording…) and how to fix it
4. Clauses that matter to this user, with per-evidence provenance (every finding links to the source item, e.g. E3)
5. Prioritised action plan + deadline timeline, grounded in a curated UK-law corpus with citations
6. Lawyer-ready handoff brief + escalation signal — when to "talk to a real person"
7. Memory / resume — conversation + evidence persist to SQLite; "Save & resume later" makes a gist and a resume link

Hero demo: Case 09 (unfair dismissal + sex discrimination). Differentiator vs ChatGPT: grounded-with-citations, per-message provenance, proactive damage detection, and persistent multi-session memory.

Why Case 09 is the hero demo

Of the 10 synthetic case packs, Case 09 (employment · unfair dismissal + sex discrimination, tagged "Messy — Severe") shows off every feature of this app at once:

• ⏰ A ticking deadline. The ACAS certificate expires in ~5 days, so the readiness gauge, timeline, and escalation all light up with real urgency — a gripping live demo ("🛑 5 days to file").
• ⚠️ Two non-obvious damage items. A covert recording (admissibility risk) and an emotive email to the CEO (could be used against her) give the damage-assessment feature two clear, lawyer-grade flags — not one generic note.
• 📎 Rich, varied evidence. Contract, grievance, redundancy notice, appeal, ACAS cert, CEO email, payslips — perfect for adaptive intake ("you've sent the grievance and redundancy notice — do you have the ACAS certificate?") and per-evidence provenance (E1…En).
• ⚖️ Strong, citable legal grounding. Victimisation under Equality Act 2010 s.27 (no qualifying period) — exactly the "grounded in real UK law, unlike ChatGPT" story, and it's already covered by the curated corpus.
• 🟥 "Severe" = more impressive. It's the hardest tier, so handling it well is a stronger signal than an easy case.
• ✅ Lowest demo risk. The employment/discrimination corpus, the pre-filled Case 09 scenario, and the synthetic docs in backend/sample_docs/case09_*.txt are all already in place and tested — nothing to set up on the day.

The engine handles every domain; Case 09 is simply the scenario that makes the most features visible in one short, high-stakes walkthrough.

Architecture

Next.js chat UI ──►  FastAPI  ──►  LangGraph (per-turn, checkpointed to SQLite)  ──►  Gemini / Claude
                                       │
                                       └─► BM25 retrieval over corpus/*.md (UK law)

Per-turn graph: ingest_turn → intake_step (facts+classify+readiness+decide) → (ask next question | full_triage). State is checkpointed per session_id, so a conversation survives tab-close and server restart.

A legacy one-shot pipeline (/api/analyze) + the zero-build static UI are kept as a demo fallback.

Run it (tonight)

1. Backend (required — does all the work):

cd backend
# add a key in .env. Provider is switchable (both are sponsors):
#   LLM_PROVIDER=google      + GOOGLE_API_KEY=AIza...        (default)
#   LLM_PROVIDER=anthropic   + ANTHROPIC_API_KEY=sk-ant-...
./run.sh

2a. Quickest demo — no build: open http://localhost:8000 (the backend serves a single-page demo UI). Click a Quick Demo Scenario (Case 07 damp/mould or Case 09 dismissal), or upload your own PDFs/txt, and hit Crush the Paperwork.

2b. Full Next.js frontend (the real UI, in a second terminal):

cd frontend
npm run dev          # → http://localhost:3000

It reads NEXT_PUBLIC_API_URL (default http://localhost:8000) from .env.local.

Try the samples in backend/sample_docs/ (drag them in) while the real case PDFs aren't released yet.

⚠ API quota (read this if you see a 503 / "quota" message)

The agent makes a few model calls per turn. Google AI Studio free-tier keys have very low caps (e.g. ~20 requests/day on gemini-2.5-flash, and some keys show 0 on other models) — you'll burn through it in a couple of conversations and get a 429 RESOURCE_EXHAUSTED. The app catches this and shows a friendly message instead of crashing. To get a reliably working demo, pick one:

• Enable billing on the Google Cloud project behind the key (removes the cap), or
• Use a standard AI Studio key (AIza…) on a project with free tier, or
• Switch to Anthropic: set LLM_PROVIDER=anthropic + ANTHROPIC_API_KEY in .env, or
• Wait for the daily reset (the optimized per-turn call count makes ~20/day stretch to a couple of full runs).

Tech

• Backend: FastAPI + LangGraph + langchain-anthropic (Python 3.12)
• LLM: switchable via LLM_PROVIDER — Google Gemini (gemini-2.5-flash) or Claude (Sonnet/Haiku); set in .env
• Retrieval: rank-bm25 over corpus/*.md (curated UK-law summaries)
• Frontend: hand-built Next.js 16 (App Router, TypeScript) in frontend/; plus a zero-build static UI served by the backend for instant demos

Talking points for the team

• The damage assessment node is the wedge — demo it on Case 07 (signed completion form) and Case 09 (expiring ACAS deadline + covert recording).
• Every legal claim is grounded in the corpus and cited; the agent is told not to invent law. That's the credibility gap vs ChatGPT.
• The graph structure means we can add domain-specific retrieval branches and a re-plan loop after damage findings without rewriting anything.

Next steps / fast-follows

• Real vector RAG (pgvector/Chroma) + a bigger corpus pulled from legislation.gov.uk
• Claude native PDF/vision input for scanned documents (current MVP needs text PDFs)
• Streaming node-by-node progress to the UI (the trace is already produced)
• Deadline export to .ics calendar

lawhive-2