# Verifiable Judgement Trust Dashboard

## PURPOSE
Leadership at a firm adopting AI drafting needs one screen that answers: is the output actually cited, is the citation rate improving, and where does verifiability break down by office and source type? This Streamlit and Plotly dashboard turns the provenance ledger into those answers — coverage over time, per-office breakdowns, advisor round-trip latency, and the list of unverified claims awaiting review.

## WHY THIS MATTERS
The clip ties everything to a promise to the professional: the trust delivered through Counsel Legal and HiQu is what makes "that judgement ... verifiable, becomes cited", and the fiduciary obligation is to "deliver a message that they can trust and put their name on". A promise like that needs a monitor. Without a dashboard, verifiability decays silently the first time a clause library is updated.

## HOW TO BUILD
1. `pip install -r requirements.txt` (Streamlit for the app shell, Plotly for charts, Pandas for shaping).
2. Define the expected data contract: a `claims.csv` with `claim_id, office, source_kind, verified, latency_min, created_at` — the shape produced by the provenance registry.
3. In the app: `@st.cache_data` loader that falls back to a seeded synthetic generator so the dashboard runs before any real data exists.
4. Build four visuals: (a) citation coverage over time as a line chart with a 90% target band, (b) stacked bar of verified vs unverified by office, (c) box plot of advisor round-trip minutes by `source_kind`, (d) table of the newest unverified claims with a review button placeholder.
5. Add sidebar filters for date range, office and source kind, and an `st.metric` header showing current coverage, delta vs last period and count of open unverified claims.
6. Export the filtered frame to CSV so a reviewer can escalate it.

```python
@st.cache_data
def load_claims(path: str | None = None) -> pd.DataFrame:
    if path and Path(path).exists():
        return pd.read_csv(path, parse_dates=["created_at"])
    rng = np.random.default_rng(7)                      # deterministic demo data
    n = 400
    return pd.DataFrame({
        "claim_id": [f"c{i:04d}" for i in range(n)],
        "office": rng.choice(["London", "New York", "Toronto", "Singapore"], n),
        "source_kind": rng.choice(["clause_library", "matter_file",
                                   "internal_advisor", "external_advisor"], n),
        "verified": rng.random(n) < 0.91,
        "latency_min": rng.gamma(3, 6, n).round(1),
        "created_at": pd.Timestamp("2026-09-20") + pd.to_timedelta(rng.integers(0, 30, n), unit="D"),
    })

coverage = claims["verified"].mean()
st.metric("Citation coverage", f"{coverage:.1%}", delta=f"{coverage - prev:.1%}")
```

## WHEN TO USE IN PRODUCTION
Use it as the standing quality surface for any drafting-assistant rollout: weekly trust reviews, incident triage when a source drifts, and proving governance to a risk committee. It also works for a pilot readout after the first hundred documents. Do NOT use it as a client-facing report, do not let it display privileged claim text on shared screens, and skip it if nobody owns the review queue — an unread dashboard is just decoration.

## HOW IT HELPS STUDENTS
Students learn Streamlit caching and layout, Plotly chart construction, defensive data loading with synthetic fallbacks, and how to design metrics that drive decisions rather than vanity numbers.

## STARTER CODE
`starter/main.py` contains the cached loader with seeded fallback data, the four-panel layout, sidebar filters and the export button, with `# TODO` markers for the live registry query and a write-back review action.
