docs/PLAN.md

# Team Plan v2 — Contract Obligation & Risk Extractor (Challenge 03)

Supersedes the original TEAM_PLAN.md. Same strategy, four amendments — and a
**walking skeleton already built in this repo**, so hackathon day starts from a
running end-to-end system, not a blank page.

## What already works (pre-hackathon skeleton)

- ✅ Full pipeline: PDF → clauses → categories → obligations → key dates →
  ranked risks (`backend/app/pipeline.py`, CLI + FastAPI).
- ✅ Click-to-source: ingestion records word-level offset→bbox index; the React
  + pdf.js UI highlights the exact clause on click. Verified live.
- ✅ Derived deadlines: "90 days prior to term end" → notice-by **2029-04-01**
  with countdown + urgency tiers.
- ✅ Risk engine with baseline library (`baselines.json`): uncapped liability,
  auto-renewal traps, one-sided termination, slow breach notice, exclusivity,
  sole-remedy SLA, high late interest, assignment asymmetry.
- ✅ CUAD eval harness with real numbers: keyword classifier baseline =
  **0.50 macro-F1 over 8 categories on 50 contracts** (audit 0.66, assignment
  0.64, insurance 0.59; termination precision is the known weak spot).
- ✅ Open-source-only LLM layer (`CORE_LLM_BACKEND=ollama|rules`), LLM
  obligations grounded back to source sentences. Entire dependency tree is
  MIT/BSD/Apache — commercially safe.
- ✅ Demo MSA generator seeded with every risk pattern.
- ✅ **Hosted-product layer**: single Docker image (backend + built frontend +
  Tesseract OCR), `docker compose up` deploy, shared-password login
  (`APP_PASSWORD`), analyses persist across restarts.
- ✅ **Real database backend**: normalized SQLAlchemy schema (contracts,
  clauses, obligations, key_dates, risks, defined_terms) with PDFs as blobs.
  PostgreSQL in compose (pg8000 driver — BSD, not LGPL psycopg), SQLite
  zero-config fallback. Portfolio queries are SQL. `pg_dump` = full backup.
- ✅ **Scanned-PDF OCR**: no text layer → automatic Tesseract pass; word boxes
  come from the OCR engine so click-to-source still works on scans. Verified:
  the rasterized demo MSA yields identical results (26 obligations, 10 risks).
- ✅ **Exports**: Excel register (Summary/Obligations/Key dates/Risks sheets)
  and .ics calendar of computed deadlines with 7-day reminders.
- ✅ **Portfolio dashboard**: all deadlines + worst risks across every uploaded
  contract, each row deep-linking to the source clause. The roadmap slide's
  first item, already working.

## Amendments to the original plan

1. **Open-source only — this is a commercial product.** No proprietary model
   APIs at all. Extraction runs on `rules` (always works, zero models) or
   `ollama` with Apache-2.0 weights (default `qwen2.5:7b`; `mistral:7b` also
   Apache-2.0 — avoid Llama-family weights, the Meta licence has commercial
   conditions). The PDF stack is pdfplumber (MIT) + reportlab (BSD) —
   **deliberately not PyMuPDF, which is AGPL** and would poison a commercial
   product. Full licence audit in README. The rule engine is the demo safety
   net: if the local model is slow on venue hardware, `CORE_LLM_BACKEND=rules`
   still produces the entire register + risk list. **Pre-pull Ollama models
   before the day — venue Wi-Fi will not download 5 GB.**
2. **CUAD models are extractive QA, not classifiers.** The HF "CUAD model" asks
   one question per category and returns spans. Plan the upgrade as either
   (a) per-category QA over chunks (spans double as traceability), or
   (b) a LEDGAR-trained classifier. Whoever owns classification should
   prototype this BEFORE the hackathon. The interface to swap is one function:
   `classification.classify_clause`.
3. **No character offsets in the frontend.** Ingestion ships
   `{page, rects[]}` per span; the viewer draws overlay divs. Already built —
   don't reintroduce offset math in the UI.
4. **Walking skeleton first.** Done (this repo). Hackathon-day "integration"
   means each owner replacing their module behind `schema.py`, which stays
   frozen after the kickoff huddle.

## Hackathon-day work split (on top of the skeleton)

| Owner | Upgrade path |
|---|---|
| Tech Lead / Integrator | repo, model serving, `schema.py` freeze, end-to-end runs every hour, demo runner |
| Extraction core | LLM extraction quality: prompts, few-shot from CUAD, condition/trigger splitting, confidence calibration |
| Classification | replace keyword classifier with CUAD-QA or LEDGAR model; target macro-F1 ≥ 0.7 on the harness |
| Risk engine | extend `baselines.json` from CUAD norms; severity calibration; explanation quality |
| Segmentation/defined-terms | harden on 10 real CUAD PDFs (messy numbering, definitions cross-refs) |
| Date logic | more derivation patterns (cure periods, payment cycles, milestone chains) |
| Eval | raise category coverage, tune threshold, produce the accuracy slide (before/after classifier swap) |
| Data/demo/story | pick 5–10 CUAD demo contracts (need: auto-renewal + uncapped liability), broken-input tests, "who built what" slide, rehearse 3+ presenters |

## Day-of timeline (revised)

| Time | Phase |
|---|---|
| 0:00–0:45 | Huddle: freeze `schema.py`, assign modules, pick demo contracts, verify models pulled |
| 0:45–2:30 | Module upgrades in parallel — skeleton keeps running throughout |
| 2:30–3:00 | **Checkpoint: full end-to-end on a real CUAD contract; ollama vs rules call** |
| 3:00–5:00 | Quality push: classifier swap, risk library, extraction prompts |
| 5:00–6:30 | Eval numbers final; UI polish; multi-contract demo set loaded |
| 6:30–7:30 | Demo hardening, slides, 3+ presenter dry run |
| 7:30–8:00 | Buffer + final rehearsal |

## Definition of Done (unchanged, all already ✅ on the skeleton)

- [x] Pipeline runs on a real contract → register + ranked risks + traced spans
- [x] UI: upload → click an item → correct clause highlights in the PDF
- [x] Eval prints precision/recall/F1 against CUAD labels
- [x] Broken input (corrupt/empty/scanned PDF) → graceful error
- [ ] Full demo dry-run in the time box, 3+ presenters

## Post-hackathon product roadmap (the Deployability slide)

Portfolio view across hundreds of contracts → calendar/email alerts on computed
deadlines → confidence-driven human review queue (lawyer corrections feed the
baseline library) → amendments/versioning → audit log → SSO/RBAC.