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)

• Pipeline runs on a real contract → register + ranked risks + traced spans
• UI: upload → click an item → correct clause highlights in the PDF
• Eval prints precision/recall/F1 against CUAD labels
• 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.