# Central Matter Drafting Environment API

## PURPOSE
A lawyer drafting a document today hops between matter files, clause libraries, colleague comments and internal or external advisor memos — and a global contract multiplies that across offices. This project builds a single FastAPI service that behaves like the "one central environment" the video asks for: open a matter, attach every source, ask a drafting question, and receive an answer in which each assertion is bound to a citation.

## WHY THIS MATTERS
The clip states the goal directly: "We want to communicate through one central environment, ChatGPT Enterprise, but also use that trust that we've delivered through Counsel Legal and HiQu. So that judgement becomes verifiable, becomes cited." The engineering lesson is that retrieval without mandatory provenance is useless to a professional who must "put their name on" the output. This project makes citation a first-class, enforced field rather than an optional flourish.

## HOW TO BUILD
1. `pip install -r requirements.txt`, then define Pydantic models for `MatterCreate`, `Source`, `DraftQuery`.
2. Store matters in memory (swap for a real store later) keyed by a UUID, each holding its attached sources.
3. Write a `_retrieve(matter, question)` function that scores sources by simple keyword overlap — a deterministic stand-in for the embedding search you would run against Counsel Legal / HiQu.
4. Write `_draft_answer()` that returns proposed text plus a `citations` list of `{source_id, quote}` entries. Every sentence must map to at least one citation or be flagged as `"unverified": true`.
5. Expose `POST /matters`, `POST /matters/{id}/sources`, `POST /matters/{id}/draft-query`, so a UI can drive the whole loop.
6. Add a `verifiability_score` on the response (cited sentences / total sentences) and refuse to return drafts below a configurable floor.

```python
@app.post("/matters/{matter_id}/draft-query")
def draft(matter_id: str, q: DraftQuery) -> dict:
    matter = MATTERS.get(matter_id) or _missing(matter_id)
    claims = _draft_answer(matter, q.question)          # deterministic stub
    cited = [c for c in claims if c["citations"]]
    score = len(cited) / max(len(claims), 1)
    if q.require_citations and score < 0.8:
        raise HTTPException(422, f"Unverifiable draft ({score:.0%} cited)")
    return {"answer": claims, "verifiability_score": round(score, 3)}
```

## WHEN TO USE IN PRODUCTION
Use it when several offices and advisors must contribute to one instrument and a reviewer needs to trust each sentence: M&A diligence memos, global supply agreements, regulatory filings. Do NOT use it as a legal-advice engine — it proposes and cites, a qualified lawyer signs. Avoid it for privileged material outside your sanctioned environment, and skip it for one-off letters where a template beats an integration.

## HOW IT HELPS STUDENTS
Students practise API design, Pydantic validation, retrieval plumbing and — most valuable — designing a system where provenance cannot be skipped. That "cited or flagged" constraint is exactly the production discipline regulated industries demand.

## STARTER CODE
`starter/main.py` is a runnable FastAPI skeleton: matter creation, source attachment, deterministic retrieval and a citation-enforcing draft endpoint, with `# TODO` markers where real Counsel Legal / HiQu connectors and an LLM call belong.
