Deploy 9aa839066bbf99a8ada733b41479a39770b3bb83 from main

.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+charset = utf-8
+
+[*.py]
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,toml,json}]
+indent_style = space
+indent_size = 2
+
+[Makefile]
+indent_style = tab

.env.example

@@ -0,0 +1,13 @@
+# Google Gemini (DeepMind) - reasoning model
+GOOGLE_API_KEY=
+
+# Tavily - public-guidance grounding only (never patient text)
+TAVILY_API_KEY=
+
+# LangSmith - tracing + evals
+LANGSMITH_API_KEY=
+LANGSMITH_TRACING=true
+LANGSMITH_PROJECT=noteguard-hackathon
+
+# optional: swap the model (any init_chat_model id, e.g. anthropic:claude-... )
+NOTEGUARD_MODEL=google_genai:gemini-2.5-flash

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,12 @@
+## Summary
+
+<!-- What does this PR do and why? -->
+
+## Checklist
+
+- [ ] The `assert_clean()` guarantee is not weakened or bypassed
+- [ ] New functions have type hints and a one-line docstring
+- [ ] Tests added or updated for any changed logic in `noteguard/`
+- [ ] `make lint` and `make test` pass locally
+- [ ] No credentials or API keys committed (check `.env` is git-ignored)
+- [ ] `CHANGELOG.md` updated if this is a user-visible change

.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    name: Lint and test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.12"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install development dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check src agent app eval tests
+
+      - name: Check formatting with ruff
+        run: ruff format --check src agent app eval tests
+
+      - name: Run tests with coverage
+        run: pytest --cov=src --cov-report=term-missing

.github/workflows/deploy-hf.yml

@@ -0,0 +1,47 @@
+name: Deploy to Hugging Face Space
+
+# Deploys main to the Hugging Face Space (chaeyoona/noteguard-agent), which then
+# rebuilds the Docker image from the Dockerfile and serves it on port 7860.
+# Requires an `HF_TOKEN` repository secret (a write-scoped Hugging Face access token).
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: hf-deploy
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    name: Push main to the Space
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out main
+        uses: actions/checkout@v4
+
+      - name: Push snapshot to Hugging Face Space
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          if [ -z "$HF_TOKEN" ]; then
+            echo "::error::HF_TOKEN secret is not set. Add a write-scoped Hugging Face token under Settings -> Secrets and variables -> Actions."
+            exit 1
+          fi
+          # The Space is a deploy target, not a source repo. Push a single fresh
+          # snapshot of the current tree (orphan commit, no history) and force it
+          # onto the Space's main branch. This keeps the Space in lockstep with
+          # main and avoids sending historical binary blobs that HF's git backend
+          # rejects (it requires such files to be stored via Git LFS / Xet).
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git checkout --orphan deploy
+          git add -A
+          git commit -q -m "Deploy ${GITHUB_SHA} from ${GITHUB_REF_NAME}"
+          git push --force \
+            "https://chaeyoona:${HF_TOKEN}@huggingface.co/spaces/chaeyoona/noteguard-agent.git" \
+            deploy:main

.gitignore

@@ -0,0 +1,25 @@
+# secrets / env
+.env
+.env.*
+!.env.example
+
+# python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+.ipynb_checkpoints/
+
+# data — never commit patient-like data (even synthetic dumps)
+data/
+*.csv
+
+# langgraph / langsmith / logs
+.langgraph_api/
+*.log
+
+# os / editor
+.DS_Store
+.vscode/
+.idea/

.pre-commit-config.yaml

@@ -0,0 +1,24 @@
+# Pre-commit hooks -- run `pre-commit install` once, then they run on every commit.
+# See https://pre-commit.com for details.
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+        args: ["--maxkb=2048"]
+      - id: detect-private-key
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: ["--fix"]
+
+  - repo: https://github.com/psf/black
+    rev: 24.10.0
+    hooks:
+      - id: black

CHANGELOG.md

@@ -0,0 +1,268 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based
+on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.2.4] - 2026-06-30
+
+### Fixed
+
+- **"Admitted [redacted]" in the discharge summary.** The de-id **shifts** every date
+  (DOB and visit dates) rather than tokenising it, so no `[DATE_n]` token exists — but
+  the 1.2.2 prompt told the model to reproduce a date *token*. Seeing dates but no token,
+  the model hallucinated a `[DATE_1]`/`[DATE_X]`, which the `redact_unresolved()` safety
+  net then turned into `[redacted]`.
+  The date shift is already **reversible** (`forward: 13/02/26 → 22/03/26`, reverse
+  restores it), so the fix is prompt-only: the model is now told to copy the
+  admission/visit date **exactly as written** in the note (a plain date, not a token);
+  it sees only the shifted date, and `reidentify_out` restores the **true** admission
+  date for the clinician (e.g. "Admitted on 13/02/26 …"). Not a single line of
+  `src/deid.py` changed; a new test guards the shift round-trip.
+
+### Changed
+
+- **The patient is no longer named in the discharge summary.** The card previously
+  rendered a `<name> — discharge summary` title (resolved from `person_id`), which both
+  duplicated the static "Discharge Summary" header and put the patient's real name on the
+  output. The patient name / `{{PATIENT}}` placeholder is removed entirely:
+  - **Prompt** — the output format drops the title line (now three elements: narrative,
+    follow-up, grounded); the model is told never to name the patient and to refer to
+    them as "the patient" throughout. Other people's surrogate tokens still restore.
+  - **`reidentify_out`** — no longer substitutes a patient name; `State.person_name` and
+    the `app/api.py` `person_id → name` lookup (`_PATIENT_NAMES`) are removed (the
+    `/process` `person_id` field is kept, accepted-but-unused, for UI compatibility).
+  - **UI** — `renderSummary()` drops any stray title line; the card's "Discharge Summary"
+    header is the only title.
+
+## [1.2.2] - 2026-06-30
+
+### Fixed
+
+- **Literal `[DATE_X]` reaching the discharge summary.** Two compounding causes: the
+  SYSTEM prompt's format example literally contained `Admitted [DATE_X] after …`, which
+  the model copied verbatim when the de-identified note had no admission-date token (the
+  date is only in the dataset's structured tables, never in the text the model sees); and
+  `reidentify_out` only recognised `[LABEL_<digits>]`, so `[DATE_X]` was never flagged or
+  redacted. Fixes:
+  - **Prompt** — the date example is now the angle-bracket fill-in `<admission date>`,
+    with an explicit rule to reproduce a `[DATE_n]` token only if present and otherwise
+    omit the date — never emit a literal placeholder.
+  - **Defense-in-depth** — new `NoteGuard.redact_unresolved()` (pattern `_ORPHAN_PAT`,
+    `[LABEL_<anything>]`) redacts and flags any surrogate-shaped token still present after
+    re-identification, including stray template placeholders like `[DATE_X]`.
+    `reidentify_out` now routes through it, so none can reach the clinician verbatim.
+
+## [1.2.1] - 2026-06-30
+
+### Fixed
+
+- **NER over-redaction of clinical terms** — the small spaCy model (`en_core_web_md`)
+  shipped in 1.2.0 mislabels abbreviations like "Subcut" as a `PERSON`, and Presidio
+  scores every spaCy entity a flat `0.85`, so a confidence threshold cannot separate
+  them from real names. Added a clinical-term allow-list (`_NER_STOPWORDS`) applied at
+  the detector boundary (`NoteGuard._detect_names`), so those terms are never redacted
+  as names while real names alongside them still are. Used in both `deidentify()` and
+  `residual_identifiers()` so the eval leak-check is consistent too.
+
+## [1.2.0] - 2026-06-29
+
+Follow-up to 1.1.0: actually **raise de-identification recall** so the residual-PII
+audit has less to catch. The 1.1.0 panel honestly reported leaked free-text names
+(e.g. "Dr Ethel Joanne Duffy") but nothing redacted them in the deployed image,
+because Presidio/spaCy NER was wired behind the `_Detector` interface yet never
+shipped. This turns it on.
+
+### Added
+
+- **Presidio + spaCy NER in the deployed image** — `Dockerfile` installs the `[nlp]`
+  extra (`presidio-analyzer`, `spacy`) and `en_core_web_md`, so free-text PERSON/
+  LOCATION names with no vault entry are now tokenised before the model sees them.
+- **`[nlp]` optional dependency** in `pyproject.toml` (`pip install -e ".[nlp]"`).
+- **`NOTEGUARD_SPACY_MODEL`** env var (default `en_core_web_md`) — switch to
+  `en_core_web_lg` for higher recall at ~14× the model size, or `en_core_web_sm`
+  for a smaller image.
+
+### Changed
+
+- `src/deid.py` `_build_detector()` now configures the spaCy model explicitly via
+  `NlpEngineProvider` (so it no longer hard-defaults to the unshipped `en_core_web_lg`)
+  and still degrades gracefully to a no-op stub when Presidio is absent (CI, local).
+- Tests pin the no-op detector by default (autouse fixture) so the suite is
+  deterministic whether or not the `[nlp]` extra is installed; a new test covers the
+  NER redaction path.
+
+### Notes
+
+- NER is a recall **boost**, not a guarantee: `en_core_web_md` misses some names
+  (recall is also lower for non-English names — see `docs/tool_card.md`). `scan_pii`
+  remains the high-precision backstop that surfaces anything still leaking, and
+  `assert_clean()` is unchanged (vault + structured patterns).
+
+## [1.1.0] - 2026-06-29
+
+The trust panel now reports **only** whether reversible pseudonymisation was done
+correctly. The previous panel could read `RE-ID RISK 0.0%` while un-redacted free-text
+names (e.g. "Dr Ethel Joanne Duffy") reached the model, because the risk number was
+computed from the *vault* — and arbitrary pasted names are never in the vault.
+
+### Added
+
+- **`NoteGuard.scan_pii(text)`** (`src/deid.py`) — a vault-independent residual-PII
+  audit of de-identified text. Flags structured identifiers that survived (NHS, GMC,
+  NMC, email, phone, postcode) and free-text person names via a high-precision
+  person-title heuristic (`Dr/Nurse/Consultant/…` + ≥2 Title-Case tokens). Surrogate
+  tokens and bare role words are never flagged. Works on notes with no ground-truth
+  vault, which is exactly where the old metric was blind.
+- **Trust-panel metrics focused on de-id correctness** — `/process` now returns
+  `deid_ok` (PASS/FAIL verdict), `residual_pii` (`[{type, text}]` the model still saw),
+  `residual_pii_count`, and `reversible`. The UI cards become **De-identification**,
+  **Identifiers replaced**, **Residual PII · model input** (with the offending snippets
+  listed), and **Reversible**.
+
+### Removed
+
+- **Faithfulness and Grounded-sources metrics** from the trust panel — answer-quality
+  signals, not de-identification correctness. Dropped the in-graph faithfulness judge
+  (`model.invoke`) and Tavily-source extraction from `compute_trust`, and the
+  `faithfulness_score` / `sources` state fields. (Tavily still grounds the answer; the
+  `eval/run_eval.py` faithfulness evaluator is unchanged — it is a separate experiment.)
+- **`metrics.residual_risk`** from `/process` — replaced by the honest `deid_ok` +
+  `residual_pii_count`. `/summarise` keeps `residual_risk`/`ok`, now derived from the
+  audit (`residual_pii` + `leaked_tokens`).
+
+## [1.0.1] - 2026-06-28
+
+### Changed
+
+- **Default model downgraded to `gemini-2.0-flash`** — `NOTEGUARD_MODEL` default in
+  `agent/graph.py` and `eval/run_eval.py` changed from `gemini-2.5-flash` to
+  `gemini-2.0-flash`; `.env.example` updated to match.
+
+### Added
+
+- **HF Space auto-deploy** (`.github/workflows/deploy-hf.yml`) — every push to `main`
+  mirrors the repo onto the HF Space `chaeyoona/noteguard-agent` as an orphan commit,
+  triggering a Docker rebuild on port 7860. Needs the `HF_TOKEN` repo secret. Orphan
+  strategy avoids the historical `docs/init.png` blob that HF's binary-in-history
+  check rejects.
+
+### Removed
+
+- `docs/CHANGELOG.md` — duplicate of the root `CHANGELOG.md`.
+- `docs/plan.md` — historical planning doc; no longer relevant post-1.0.
+- `outputs/.gitkeep` — unused placeholder directory.
+
+### Changed (CI)
+
+- GitHub Actions Python matrix trimmed to **3.10 + 3.12** (intermediate versions
+  removed).
+
+---
+
+## [1.0.0] - 2026-06-27
+
+First post-hackathon release. The codebase is pruned to exactly the components
+that ship in the deployed Hugging Face Space; sponsor-only integrations that never
+ran in the deployed image are removed.
+
+### Removed
+
+- **Superlinked retrieval** (`src/retrieve.py`, `[retrieval]` optional dependency,
+  and the `retrieve_context` graph node) — the in-memory vector index was excluded
+  from the Docker image and lazy-imported behind a graceful fallback, so it never
+  executed in the deployed app. Removing it deletes the `retrieved_context` state
+  field and the per-request demo index seeding.
+- **n8n workflow** (`workflows/noteguard.n8n.json`) — a three-node proxy
+  (Webhook → HTTP Request → Respond) to NoteGuard's own REST API. It added no logic
+  and sat off the runtime path; any automation platform can still call the REST API.
+
+### Changed
+
+- **Faithfulness judge now scores against the de-identified source note** (`deid_text`)
+  instead of Superlinked-retrieved context. The score was previously gated on retrieval,
+  so it never populated in the deployed app (which had no retrieval); it now produces a
+  live number for every request and matches the definition used by `eval/run_eval.py`.
+- `agent/graph.py`: pipeline simplified to
+  `deidentify_in → agent → reidentify_out → compute_trust`; `build_graph()` no longer
+  takes a `note_index` argument.
+- `app/api.py`: `/process` reports `faithfulness` whenever a de-identified note exists;
+  FastAPI app version bumped to `1.0.0`.
+- `Dockerfile`: dependency comment updated — the image no longer "omits" Superlinked,
+  it is simply not a dependency.
+- `Makefile`: modernised to the real toolchain — installs via `pip install -e .`
+  (no `requirements.txt`), lints/formats with `ruff` (not `black`), uses the `src`
+  package and `src/fetch_dataset.py`.
+- `pyproject.toml`: version bumped to `1.0.0`; `superlinked` removed from keywords;
+  `[retrieval]` optional-dependency group dropped.
+
+---
+
+## [0.2.0] - 2026-06-27
+
+### Added
+
+- **Clinician web UI** (`app/static/index.html`) — single-file, vanilla JS, no build
+  step. NHS dark-blue header, segmented toggle (Clinician view / What the AI sees),
+  PHI highlighted in red in the clinician view, `[TYPE_N]` monospace chips in the AI
+  view, discharge summary pane, trust-panel metric cards.
+- **`POST /process` endpoint** (`app/api.py`) — returns `clinician_note`, `ai_note`,
+  `identifiers` (original strings for highlighting), `discharge_summary`, and
+  `metrics` (`identifiers_removed`, `residual_risk`, `grounded_sources`,
+  `faithfulness`).
+- **`GET /`** — FastAPI serves `app/static/index.html` directly; no separate static
+  server needed.
+- **`StaticFiles` mount** at `/static` — allows future CSS/JS assets alongside the
+  single-page UI.
+- **n8n workflow** (`workflows/noteguard.n8n.json`) — importable three-node workflow
+  (Webhook → HTTP Request → Respond to Webhook) that routes ward notes through the
+  NoteGuard API without the model ever seeing PHI.
+
+- **Vercel deployment** (`api/index.py`, `api/requirements.txt`, `vercel.json`) —
+  the FastAPI app is deployable as a serverless Vercel function. Light dep set
+  omits superlinked/torch to stay under the 250 MB bundle limit; retrieval falls
+  back gracefully to Gemini-only mode.
+
+### Changed
+
+- `app/api.py` now also serves the clinician web UI in addition to the REST API.
+- `agent/graph.py`: `NoteIndex` import made lazy (inside try block) so the module
+  loads cleanly in environments where superlinked is unavailable (CI, Vercel).
+- `noteguard/__init__.py`: removed `NoteIndex` re-export; only `NoteGuard`,
+  `DeidResult`, and `load_known_from_csv` are exported from the package.
+- `Makefile` `run` target now starts uvicorn (`uvicorn app.api:app --reload --port 8000`)
+  instead of Streamlit.
+- `pyproject.toml` version bumped to 0.2.0; `per-file-ignores` added for E402
+  (intentional `load_dotenv()` before API-key-consuming imports).
+
+### Removed
+
+- **`app/trust_panel.py`** — Streamlit demo UI retired; superseded by the
+  single-file clinician web UI (`app/static/index.html`) served by FastAPI.
+- **`streamlit`** removed from `requirements.txt`.
+
+---
+
+## [0.1.0] - 2026-06-27
+
+### Added
+
+- **De-identification core** (`noteguard/deid.py`) — dependency-free NHS-aware
+  pipeline: NHS number, GMC/NMC, postcode, DOB, email and phone recognisers;
+  vault-from-CSV for ground-truth measurement; consistent surrogates;
+  `assert_clean()` hard guarantee; `reidentify()` for clinician-only restoration.
+- **Superlinked retrieval node** (`noteguard/retrieve.py`) — in-memory vector
+  index (`sentence-transformers/all-MiniLM-L6-v2`) with `assert_clean()` called
+  on every document in and every retrieved chunk out.
+- **LangGraph agent** (`agent/graph.py`) — full pipeline:
+  `deidentify_in → retrieve_context → agent (Gemini + Tavily) → reidentify_out → compute_trust`.
+  Trust metrics surfaced in graph state: identifiers removed, residual leakage,
+  faithfulness score, source URLs.
+- **Streamlit trust panel** (`app/trust_panel.py`) — three-way toggle
+  (raw / de-identified / clinician answer) and live trust panel; styled to the
+  NHS England identity.
+- **LangSmith evaluations** (`eval/run_eval.py`) — `zero_phi_to_model` (must
+  score 1.0) and `faithfulness` (LLM-as-judge over de-identified text only).
+- Gold RAP packaging: `pyproject.toml`, `Makefile`, `CHANGELOG.md`,
+  `CONTRIBUTING.md`, `.pre-commit-config.yaml`, `.editorconfig`, CI workflow,
+  and `docs/` (architecture, user guide, RAP compliance).

CLAUDE.md

@@ -0,0 +1,84 @@
+# NoteGuard — the trust layer for clinical AI
+
+## What this is
+NoteGuard de-identifies NHS clinical free-text so LLM agents can use it safely, and
+proves the privacy with a measured number. This repo is the **agent slice**: a
+LangGraph ReAct agent (Gemini + Tavily) wrapped so the model and tools only ever see
+de-identified text; real identifiers are restored only in the final clinician-facing
+answer.
+
+It started at the {Tech: Europe} London AI Hackathon. The `1.0` line is pruned to the
+components that actually ship in the deployed Space (see `CHANGELOG.md`).
+
+## Architecture
+`deidentify_in → agent (Gemini + Tavily) → reidentify_out → compute_trust`
+- The guarantee (non-negotiable): nothing downstream of `deidentify_in` may
+  receive PHI. `assert_clean()` raises if any identifier remains. Never weaken or
+  bypass this — it is the whole point of the project.
+- Tavily is public-guidance grounding only (NICE/NHS). Never send patient text to it.
+- `compute_trust` audits de-identification: `NoteGuard.scan_pii(deid_text)` flags PII
+  the vault/NER passes missed (vault-independent, so it works on pasted notes), plus
+  orphaned surrogate tokens for reversibility. The trust panel reports only this — no
+  answer-quality metrics (faithfulness/sources were removed).
+
+## Key files
+- `src/deid.py` — de-id core: NHS-aware rules + vault-from-CSV, consistent
+  surrogates, DOB date-shift, `reidentify`, `assert_clean`, and `scan_pii` (the
+  panel audit). Keep the rule/vault layer std-lib only. Presidio + spaCy NER sit
+  behind the `_Detector` interface (the `[nlp]` extra, `NOTEGUARD_SPACY_MODEL`,
+  default `en_core_web_md`) and now ship in the Docker image to catch free-text
+  names — but they degrade gracefully to a no-op stub when absent (CI, local).
+- `agent/graph.py` — the graph; exposed as `noteguard` for `langgraph dev`.
+- `app/api.py` — FastAPI backend: `GET /` (serves index.html), `GET /health`,
+  `POST /process` (full UI payload), `POST /summarise` (compact legacy).
+- `app/static/index.html` — single-file clinician web UI (vanilla JS, no build step).
+- `streamlit_app.py` — Streamlit demo (no API keys required; rule layer only).
+- `Dockerfile` — HF Spaces Docker config; uvicorn on port 7860.
+- `eval/run_eval.py` — LangSmith evals: `zero_phi_to_model` (must be 1.0) + `faithfulness`.
+- `langgraph.json`, `.env.example`.
+- `docs/tool_card.md` — Five Safes, bias & fairness, use cases out of scope.
+- `docs/report.md` — ATRS Tier 1 + Tier 2 record.
+
+## Commands
+- De-id demo (no keys): `python src/deid.py`
+- Install: `pip install -e ".[dev]"`
+- Clinician web UI: `uvicorn app.api:app --reload --port 8000` (or `make run`)
+  then open http://localhost:8000
+- Serve agent (Agent Chat UI): `langgraph dev`
+  then open: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024
+- Evals: `python -m eval.run_eval`
+- Deploy: push to `main` → `.github/workflows/deploy-hf.yml` mirrors it onto the HF
+  Space `chaeyoona/noteguard-agent` (needs `HF_TOKEN` repo secret); HF rebuilds from
+  `Dockerfile` (Docker SDK, `app_port: 7860`).
+- Env: copy `.env.example` → `.env`; fill `GOOGLE_API_KEY`, `TAVILY_API_KEY`,
+  `LANGSMITH_API_KEY`; set `LANGSMITH_TRACING=true`.
+
+## Components
+Gemini (reasoning) + Tavily (public-guidance grounding) are the external services.
+LangGraph orchestrates the pipeline; LangSmith provides traces + evals. Superlinked
+(retrieval) and n8n (a proxy workflow) were hackathon-era integrations that never ran
+in the deployed Space and were removed in `1.0`.
+
+## Dataset
+`NHSEDataScience/synthetic_clinical_notes` (Hugging Face, MIT, fully synthetic).
+Build the vault from `patients.csv` via `load_known_from_csv()` so leakage is
+measured against ground truth. Dataset has mojibake — `_fix_mojibake` handles it.
+
+## Conventions
+- Python 3.10+. Keep `src/deid.py` std-lib only.
+- Verify/round any number shown in the demo.
+- Model id lives in `NOTEGUARD_MODEL` (default `google_genai:gemini-2.5-flash`).
+- Versions drift: if a `langgraph`/`langsmith`/`create_react_agent` import fails,
+  adjust to the installed version rather than pinning blindly.
+- `src/__init__.py` exports only `NoteGuard`, `DeidResult`, `load_known_from_csv`.
+- `pyproject.toml` is the single dependency source; `requirements.txt` is removed.
+- Linting: `ruff check` + `ruff format` (not black).
+
+## HF Spaces notes
+- The Docker image installs only the runtime deps in `pyproject.toml`; `streamlit`
+  and `dev` extras are not part of the deployed image.
+- Set `GOOGLE_API_KEY`, `TAVILY_API_KEY`, `LANGSMITH_API_KEY` in Space Secrets.
+
+## Ethics
+Pseudonymised ≠ anonymous (still personal data under UK GDPR). Synthetic ≠ real —
+frame as methodology. Clinician stays in the loop and signs off.

CODE_OF_CONDUCT.md

@@ -0,0 +1,65 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a
+harassment-free experience for everyone, regardless of age, body size, visible or invisible
+disability, ethnicity, sex characteristics, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance, race, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive,
+and healthy community.
+
+## Our Standards
+
+Examples of behaviour that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologising to those affected by our mistakes, and learning from them
+- Focusing on what is best for the overall community
+
+Examples of unacceptable behaviour:
+
+- The use of sexualised language or imagery, and sexual attention or advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address, without their
+  explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Data-handling note
+
+This project processes clinical-note text. Even though the bundled dataset is fully synthetic,
+treat all note content as if it were real NHS PHI:
+
+- Never paste note text into issues, pull requests, or chat — reference file paths instead.
+- Never commit anything under `data/` (it is gitignored).
+- Never send patient text or surrogate tokens to external APIs — the `assert_clean()` guarantee
+  and the Tavily usage policy both enforce this technically, but contributors must not work around them.
+- If you discover a real-data leak in any test fixture, treat it as a security incident: notify the
+  maintainer privately rather than opening a public issue.
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards and will take
+appropriate and fair corrective action in response to any behaviour they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is
+officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behaviour may be reported to the project
+maintainer by opening a confidential issue or by contacting the repository owner on GitHub
+(**@chaeyoonyunakim**). All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# Contributing
+
+Thank you for considering a contribution to NoteGuard. This project follows the
+[NHS RAP Community of Practice](https://nhsdigital.github.io/rap-community-of-practice/)
+guidance and the [Government Digital Service (GDS) coding standards](https://gds-way.digital.cabinet-office.gov.uk/standards/programming-languages.html).
+
+## Getting started
+
+```bash
+git clone https://github.com/chaeyoonyunakim/noteguard-agent.git
+cd noteguard-agent
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+make install-dev          # installs dev deps and pre-commit hooks
+cp .env.example .env      # fill in GOOGLE_API_KEY, TAVILY_API_KEY, LANGSMITH_API_KEY
+```
+
+## Development workflow
+
+1. Create a feature branch from `main`.
+2. Make your change, keeping functions small and well-documented.
+3. Run the checks locally:
+   ```bash
+   make format   # auto-fix style
+   make lint     # ruff + black
+   make test     # pytest
+   ```
+4. Commit. Pre-commit hooks run ruff, black and basic hygiene checks.
+5. Open a **pull request**. CI (GitHub Actions) runs lint and tests on every PR.
+
+## Coding standards
+
+- **Python**: PEP 8, 4-space indentation, type hints, formatted with **black**
+  and linted with **ruff** (line length 110).
+- Write **tests for all new functions** (`tests/`, run with pytest).
+- Keep `noteguard/deid.py` **dependency-free** (standard library only).
+- Never weaken or bypass `assert_clean()` — it is the project's core guarantee.
+- Use **British English** in comments and documentation.
+- Never commit secrets, credentials or API keys — use environment variables
+  (see `.env.example`).
+
+## The privacy guarantee
+
+The non-negotiable invariant: nothing downstream of `deidentify_in` may receive
+PHI. `assert_clean()` must be called before any identifier-bearing text reaches
+a language model or external tool. Do not relax this check under any
+circumstances — it is the entire point of the project.
+
+## Review
+
+All changes must be **reviewed by a human** before merge. The pull request
+template includes a checklist to confirm standards are met.

Dockerfile

@@ -0,0 +1,35 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends gcc && rm -rf /var/lib/apt/lists/*
+
+# Runtime dep set — mirrors the [project] dependencies in pyproject.toml,
+# plus the [nlp] extra (Presidio + spaCy) so free-text names are de-identified.
+RUN pip install --no-cache-dir \
+    "fastapi>=0.109.0" \
+    "uvicorn[standard]>=0.27.0" \
+    "langgraph>=0.2.0" \
+    "langchain>=0.3.0" \
+    "langchain-google-genai>=2.0.0" \
+    "langchain-tavily>=0.1.0" \
+    "langsmith>=0.1.0" \
+    "python-dotenv>=1.0.0" \
+    "huggingface_hub>=0.20.0" \
+    "presidio-analyzer>=2.2.0" \
+    "spacy>=3.7.0,<4"
+
+# spaCy model for Presidio NER. _md balances recall vs image size; override with
+# NOTEGUARD_SPACY_MODEL (e.g. en_core_web_lg) if you also bake that model in.
+RUN python -m spacy download en_core_web_md
+ENV NOTEGUARD_SPACY_MODEL=en_core_web_md
+
+COPY . .
+
+# Bake the synthetic dataset into the image so /samples works without runtime downloads
+RUN python src/fetch_dataset.py
+
+ENV PYTHONUNBUFFERED=1
+EXPOSE 7860
+
+CMD ["uvicorn", "app.api:app", "--host", "0.0.0.0", "--port", "7860"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chaeyoon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,47 @@
+# NoteGuard Agent -- common developer tasks.
+# Usage: `make <target>`. Run `make help` to list targets.
+
+.DEFAULT_GOAL := help
+PYTHON ?= python
+SRC := src agent app eval
+
+.PHONY: help install install-dev lint format test coverage data run eval clean
+
+help: ## Show this help message
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) \
+		| sort \
+		| awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-14s\033[0m %s\n", $$1, $$2}'
+
+install: ## Install runtime dependencies
+	$(PYTHON) -m pip install -e .
+
+install-dev: ## Install development dependencies and pre-commit hooks
+	$(PYTHON) -m pip install -e ".[dev]"
+	pre-commit install
+
+lint: ## Run ruff lint + format checks
+	ruff check $(SRC) tests
+	ruff format --check $(SRC) tests
+
+format: ## Auto-format and fix lint with ruff
+	ruff check --fix $(SRC) tests
+	ruff format $(SRC) tests
+
+test: ## Run the unit test suite
+	$(PYTHON) -m pytest
+
+coverage: ## Run tests with a coverage report
+	$(PYTHON) -m pytest --cov=src --cov-report=term-missing
+
+data: ## Download synthetic dataset CSVs into data/ (run once)
+	$(PYTHON) src/fetch_dataset.py
+
+run: ## Run the clinician web UI locally (http://localhost:8000)
+	uvicorn app.api:app --reload --port 8000
+
+eval: ## Run LangSmith evaluations
+	$(PYTHON) -m eval.run_eval
+
+clean: ## Remove caches and build artefacts
+	rm -rf .pytest_cache .ruff_cache build dist *.egg-info
+	find . -type d -name __pycache__ -prune -exec rm -rf {} +

README.md

@@ -0,0 +1,241 @@
+---
+title: NoteGuard
+emoji: 🏥
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+[![status: experimental](https://github.com/GIScience/badges/raw/master/status/experimental.svg)](https://github.com/GIScience/badges#experimental)
+[![CI](https://github.com/chaeyoonyunakim/noteguard-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/chaeyoonyunakim/noteguard-agent/actions/workflows/ci.yml)
+[![RAP level: Gold](https://img.shields.io/badge/RAP-Gold-ffd700)](https://nhsdigital.github.io/rap-community-of-practice/introduction_to_RAP/levels_of_RAP/)
+[![code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000)](https://github.com/astral-sh/ruff)
+
+# NoteGuard — Trust Layer for Clinical AI
+
+> NHS clinical notes go in → a safe AI-drafted summary comes out → the model **provably never sees a single identifier**, with a live re-identification-risk number to prove it.
+
+NoteGuard is a LangGraph agent (Gemini + Tavily) wrapped so that the language
+model and every tool only ever receive **de-identified** text. Real identifiers
+are restored only in the final, clinician-facing answer. The guarantee is
+enforced by `assert_clean()`, which raises before any PHI can reach the model.
+
+> **Project history:** NoteGuard began at the {Tech: Europe} London AI Hackathon.
+> This is the post-hackathon `1.0` line — the codebase has been pruned to exactly
+> the components that ship in the deployed app. See [`CHANGELOG.md`](CHANGELOG.md).
+
+---
+
+## What it does
+
+```
+messy NHS note  ──►  NoteGuard de-id  ──►  de-identified text
+(synthetic)           (NHS-aware rules       + identifiers removed count
+                       + vault from CSV)     + residual leakage %
+                                │
+                  Tavily (NICE/NHS guidance) ──►│
+                                                ▼
+                                         Gemini drafts
+                                         compact eDischarge card
+                                         (sees ONLY de-identified text)
+                                                │
+                         NoteGuard re-id  ◄─────┘
+                         (surrogates → real names, clinician only)
+                                │
+                         Trust panel (de-id correctness only):
+                         de-id PASS/FAIL · identifiers replaced
+                         residual PII (model input) · reversible
+```
+
+The **key technical guarantee**: `assert_clean()` raises before Gemini or Tavily
+receive anything — the model structurally cannot leak what it never saw.
+
+---
+
+## Quickstart
+
+```bash
+# 1. Clone and create environment
+git clone https://github.com/chaeyoonyunakim/noteguard-agent.git
+cd noteguard-agent
+python -m venv .venv
+.venv\Scripts\activate          # Windows
+# source .venv/Scripts/activate # bash
+# source .venv/bin/activate     # macOS/Linux
+
+# 2. Install
+pip install -e ".[dev]"
+
+# 3. Configure
+cp .env.example .env
+# fill: GOOGLE_API_KEY  TAVILY_API_KEY  LANGSMITH_API_KEY
+
+# 4. Smoke test — no API keys needed
+python src/deid.py
+
+# 5. Interactive de-id demo — no API keys needed
+pip install -e ".[demo]"
+streamlit run streamlit_app.py
+
+# 6. Clinician web UI (full agent)
+uvicorn app.api:app --reload --port 8000
+# then open: http://localhost:8000
+
+# 7. LangGraph dev server + Agent Chat UI
+langgraph dev   # requires pip install -e ".[dev]"
+# then open: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024
+
+# 8. LangSmith evals
+python -m eval.run_eval
+```
+
+---
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `src/deid.py` | Dependency-free de-id core. `python src/deid.py` runs standalone. |
+| `src/fetch_dataset.py` | Downloads the synthetic dataset into `data/` (run once). |
+| `agent/graph.py` | LangGraph graph exposed as `noteguard` for `langgraph dev`. |
+| `app/api.py` | FastAPI backend — `/`, `/health`, `/process`, `/summarise`, `/samples`, `/sample/{id}`. |
+| `app/static/index.html` | Single-file clinician web UI (vanilla JS, no build step). |
+| `streamlit_app.py` | Interactive de-id demo — no API keys needed. |
+| `eval/run_eval.py` | LangSmith evals: `zero_phi_to_model` (must be 1.0) + faithfulness. |
+| `langgraph.json` | Graph manifest for `langgraph dev`. |
+| `.env.example` | Required environment variables. |
+| `docs/tool_card.md` | Five Safes, bias & fairness, use cases out of scope, DPIA prerequisites. |
+| `docs/report.md` | gov.uk ATRS record (Tier 1 + Tier 2). |
+
+---
+
+## The guarantee (non-negotiable)
+
+```
+deidentify_in → assert_clean() → [ONLY DE-IDENTIFIED TEXT] → Gemini / Tavily
+                                                               ↓
+                                                          reidentify_out → clinician
+```
+
+`assert_clean()` raises `ValueError` if any known identifier or regex pattern (NHS
+number, email, phone, GMC, NMC, postcode) survives de-identification. The LangSmith
+`zero_phi_to_model` evaluator verifies this on every run and must score **1.0**.
+
+---
+
+## Graph pipeline
+
+```
+deidentify_in → agent (Gemini + Tavily) → reidentify_out → compute_trust
+```
+
+| Node | Function |
+|---|---|
+| `deidentify_in` | `NoteGuard.deidentify()` + `assert_clean()` — strips PHI; raises if any identifier survives. |
+| `agent` | `create_react_agent` (Gemini + Tavily) — drafts the eDischarge card; sees only de-identified text. |
+| `reidentify_out` | `NoteGuard.reidentify()` — restores surrogates → real names for the clinician only. |
+| `compute_trust` | Audits de-id correctness — `scan_pii(deid_text)` for residual PII the model saw, plus orphaned surrogate tokens for reversibility. |
+
+---
+
+## REST API
+
+### POST /process
+
+```json
+{
+  "note": "Pt Margaret Okafor (NHS 485 777 3456) admitted post-fall.",
+  "question": "Draft a discharge summary."
+}
+```
+
+Response fields:
+
+| Field | Description |
+|---|---|
+| `clinician_note` | Verbatim input note |
+| `ai_note` | De-identified note the model saw (surrogate tokens) |
+| `identifiers` | Original identifier strings that were redacted |
+| `discharge_summary` | Gemini-drafted compact eDischarge card, re-identified for the clinician |
+| `metrics.deid_ok` | Overall verdict — `true` only when nothing leaked **and** every surrogate is reversible |
+| `metrics.identifiers_removed` | Count of PII spans pseudonymised this turn |
+| `metrics.residual_pii` | List of `{type, text}` — suspected un-redacted PII the model still saw |
+| `metrics.residual_pii_count` | Number of residual-PII findings (`0` = de-identified) |
+| `metrics.reversible` | `true` when every surrogate restores to a real value |
+| `metrics.leaked_tokens` | Orphaned/unresolved surrogate tokens (the reversibility detail) |
+
+A `422` response means `assert_clean()` detected surviving PHI — the request is
+rejected before the model sees anything.
+
+### GET /samples
+
+Paginated list of synthetic notes with optional search and `note_type` filter.
+
+```
+GET /samples?q=COPD&note_type=Discharge&limit=50
+```
+
+### GET /sample/{clinical_note_id}
+
+Returns the full note text for a given note ID (used by the note-picker UI).
+
+---
+
+## Components
+
+| Stage | Service | Role |
+|---|---|---|
+| De-identification | `src/deid.py` | Dependency-free NHS-aware recognisers; the trust boundary. |
+| Reasoning | **Google Gemini** | Drafts the discharge summary; sees only de-identified text. |
+| Grounding | **Tavily** | Pulls NICE / NHS public guidance; never receives patient text. |
+| Orchestration | **LangGraph** | Wires the de-id → agent → re-id → trust pipeline. |
+| Observability | **LangSmith** | Traces + privacy & faithfulness evals. |
+
+---
+
+## Hugging Face Spaces deployment
+
+The app ships as a Docker Space — FastAPI + vanilla JS UI, served by uvicorn on port 7860.
+The image bundles **Presidio + spaCy NER** (`en_core_web_md`, via the `[nlp]` extra) so
+free-text patient/clinician names with no vault entry are de-identified; set
+`NOTEGUARD_SPACY_MODEL=en_core_web_lg` for higher recall at a larger image size.
+
+**Required secrets** (Space → Settings → Variables and secrets):
+
+- `GOOGLE_API_KEY`
+- `TAVILY_API_KEY`
+- `LANGSMITH_API_KEY` (optional — enables tracing)
+
+**Auto-deploy:** [`.github/workflows/deploy-hf.yml`](.github/workflows/deploy-hf.yml)
+pushes a fresh snapshot of `main` onto the Space (`chaeyoona/noteguard-agent`) on
+every push, which triggers a Docker rebuild. (A snapshot — a single orphan commit —
+is used so historical binary blobs that HF's git backend rejects are never sent.)
+It needs an `HF_TOKEN` repository secret — a write-scoped
+[Hugging Face access token](https://huggingface.co/settings/tokens) added under
+**Settings → Secrets and variables → Actions**. Trigger the first deploy manually via
+the workflow's **Run workflow** button once the secret is set.
+
+---
+
+## Data
+
+`NHSEDataScience/synthetic_clinical_notes` (Hugging Face, MIT licence, fully synthetic).
+
+```bash
+python src/fetch_dataset.py   # downloads patients.csv, admissions.csv, synthetic_clinical_notes.csv into data/
+```
+
+`load_known_from_csv("data/patients.csv", "data/admissions.csv")` builds the
+identifier vault from both structured tables — patient names and clinician names —
+so residual leakage is measured against ground truth.
+
+---
+
+## Ethics
+
+- Pseudonymised ≠ anonymous — still personal data under UK GDPR; don't over-claim.
+- Synthetic ≠ real — frame as methodology, not a finished product.
+- Clinician stays in the loop and signs off every summary.
+- See [`docs/tool_card.md`](docs/tool_card.md) for the full Five Safes mapping and bias & fairness statement.

VERSION

@@ -0,0 +1 @@
+1.2.4

agent/graph.py

@@ -0,0 +1,185 @@
+"""LangGraph agent (Gemini + Tavily) wrapped by NoteGuard de-identification.
+
+Guarantee enforced in-graph: the LLM and the Tavily tool only ever receive
+DE-IDENTIFIED text. Real identifiers are restored only in the final,
+clinician-facing answer (reidentify_out).
+
+Run locally:  langgraph dev      (serves the `noteguard` graph for Agent Chat UI)
+Trace:        set LANGSMITH_TRACING=true + LANGSMITH_API_KEY (runs auto-trace)
+
+Graph flow:
+  deidentify_in -> agent -> reidentify_out -> compute_trust
+
+Version note: import names track LangGraph v1 / LangChain v0.3+. If your installed
+versions differ, adjust the two prebuilt imports and the create_react_agent call.
+"""
+
+from __future__ import annotations
+
+import os
+
+from dotenv import load_dotenv
+
+load_dotenv(override=True)  # pick up .env before any os.getenv / API-key validation
+
+from langchain.chat_models import init_chat_model
+from langchain_core.messages import AIMessage, HumanMessage
+from langgraph.graph import END, START, MessagesState, StateGraph
+from langgraph.prebuilt import create_react_agent
+
+try:
+    from langchain_tavily import TavilySearch
+except ImportError:  # older package name
+    from langchain_community.tools.tavily_search import TavilySearchResults as TavilySearch
+
+from src.deid import NoteGuard
+
+SYSTEM = """\
+You are a clinical documentation assistant for NHS clinicians.
+Your ONLY output is a compact discharge-summary card. Reproduce EXACTLY the format below — \
+no headings, no bullets, no preamble, no sign-off.
+
+## De-identification rules — NEVER violate
+You only ever see DE-IDENTIFIED text. Patient identifiers — names, NHS numbers, dates of birth,
+addresses, GP names, consultant names — have been replaced with surrogate tokens such as
+[PERSON_1], [NHS_1], [DOB_1], [ADDRESS_1], [DATE_1].
+Preserve every surrogate token exactly as given. A re-identification step restores real values
+for the clinician after you respond. Never invent, guess, or expand a surrogate into a real value.
+Do NOT name the patient anywhere in your output — no title, no real name, no patient surrogate
+token. Refer to the patient only as "the patient". (Surrogate tokens for OTHER people, e.g. a GP
+or consultant, may appear and will be restored.)
+
+## Output format — three elements, blank line between each
+
+Admitted <admission date> after <reason>. Background: <key conditions/meds>. <what was done>. <key finding>.
+
+Follow-up: <GP action> · <action 2> · <action 3>
+
+Grounded: <source name 1>, <source name 2> · via Tavily
+
+## Rules for each element
+
+**Narrative paragraph:** plain clinical prose, max 4 sentences. Include only facts stated in \
+the source note — never invent investigations, doses, dates, or diagnoses. \
+Refer to the patient as "the patient" — never write the patient's name or their surrogate token. \
+Surrogate tokens for other people ([PERSON_1], etc.) may appear here and will be restored. \
+For the admission date, copy the admission/visit date EXACTLY as it appears in the source note \
+(a date such as 13/02/26) — character-for-character, same format; the system restores it to the \
+correct value. Do NOT use the date of birth, and do NOT write a date token like [DATE_1] or any \
+placeholder. If the note states no admission/visit date, omit it and write "Admitted after <reason>". \
+Drop a sentence entirely when there is nothing to say (e.g. no imaging → omit that sentence).
+
+**Follow-up line:** items separated by " · " (middle dot U+00B7). \
+Always include the GP action as the first item.
+
+**Grounded line:** list only the public guidance sources (short readable names, not URLs) \
+actually returned by the Tavily search tool this run. \
+If Tavily returned no results, omit the Grounded line entirely — never fabricate citations.
+
+**Search tool:** use only for public NICE/NHS clinical guidance. \
+Never send patient text or surrogate tokens to the search tool.
+"""
+
+
+class State(MessagesState):
+    forward: dict
+    reverse: dict
+    clinician_answer: str
+    # --- trust panel fields (all about de-identification correctness) ---
+    deid_text: str  # de-identified note text (what the AI saw)
+    identifiers_removed: int  # identifiers replaced in this turn
+    residual_count: int  # known identifiers that survived de-id (pre-model)
+    leaked_tokens: list  # orphaned surrogate tokens in the output (reversibility)
+    residual_pii: list  # suspected un-redacted PII the model saw (de-id audit)
+
+
+def build_graph(known: dict | None = None):
+    model = init_chat_model(os.getenv("NOTEGUARD_MODEL", "google_genai:gemini-2.5-flash"))
+    tools = [TavilySearch(max_results=3)]
+    react = create_react_agent(model, tools, prompt=SYSTEM)
+
+    def deidentify_in(state: State):
+        prior_n = len(state.get("forward") or {})
+        ng = NoteGuard(known=known, forward=state.get("forward"), reverse=state.get("reverse"))
+        last = state["messages"][-1]
+        if not isinstance(last, HumanMessage):
+            return {"forward": ng.forward, "reverse": ng.reverse}
+        res = ng.deidentify(last.content)
+        ng.assert_clean(res.clean_text)  # hard guarantee before model/tool see anything
+        cleaned = HumanMessage(content=res.clean_text, id=last.id)
+        return {
+            "messages": [cleaned],
+            "forward": ng.forward,
+            "reverse": ng.reverse,
+            "deid_text": res.clean_text,
+            "identifiers_removed": len(ng.forward) - prior_n,
+            "residual_count": len(res.residual),
+        }
+
+    def run_agent(state: State):
+        out = react.invoke({"messages": state["messages"]})
+        return {"messages": out["messages"][len(state["messages"]) :]}
+
+    def reidentify_out(state: State):
+        ng = NoteGuard(reverse=state.get("reverse"))
+        last = state["messages"][-1]
+        if not isinstance(last, AIMessage):
+            return {"clinician_answer": "", "leaked_tokens": []}
+        content = last.content
+        # Gemini can return content as a list of blocks [{type, text}, ...]
+        if isinstance(content, list):
+            raw_text = " ".join(
+                block.get("text", "") if isinstance(block, dict) else str(block) for block in content
+            ).strip()
+        else:
+            raw_text = content or ""
+
+        # Restore known surrogates for the clinician (the patient is never named).
+        restored = ng.reidentify(raw_text)
+
+        # Anything surrogate-shaped still present is either an unrestored surrogate or
+        # a stray template placeholder the model echoed (e.g. [DATE_X]); redact + flag
+        # so it never reaches the clinician verbatim.
+        restored, leaked_tokens = ng.redact_unresolved(restored)
+        leaked = [f"unresolved_token:{tok}" for tok in leaked_tokens]
+
+        return {"clinician_answer": restored, "leaked_tokens": leaked}
+
+    def compute_trust(state: State):
+        """Audit de-identification quality for the trust panel.
+
+        Two independent de-id failures, neither needing PHI to compute:
+        - residual_pii: PII the vault/NER passes missed but that still reached the
+          model — scanned out of deid_text (what the model actually saw). This is
+          the failure the old residual_count was blind to (vault-only).
+        - leaked_tokens: orphaned surrogate tokens in the output that cannot be
+          reversed — the reversibility side of the pseudonymisation guarantee.
+        """
+        ng = NoteGuard(known=known, reverse=state.get("reverse"))
+        deid_text = state.get("deid_text") or ""
+        residual_pii = ng.scan_pii(deid_text) if deid_text else []
+        leaked = list(state.get("leaked_tokens") or [])
+
+        return {
+            "residual_pii": residual_pii,
+            "leaked_tokens": leaked,
+            "residual_count": state.get("residual_count", 0) + len(leaked),
+        }
+
+    g = StateGraph(State)
+    g.add_node("deidentify_in", deidentify_in)
+    g.add_node("agent", run_agent)
+    g.add_node("reidentify_out", reidentify_out)
+    g.add_node("compute_trust", compute_trust)
+    g.add_edge(START, "deidentify_in")
+    g.add_edge("deidentify_in", "agent")
+    g.add_edge("agent", "reidentify_out")
+    g.add_edge("reidentify_out", "compute_trust")
+    g.add_edge("compute_trust", END)
+    return g.compile()
+
+
+# Demo vault — seeds the known-identifier set so `langgraph dev` / the web UI
+# resolve surrogates consistently on startup.
+_DEMO_KNOWN = {"PERSON": ["Margaret Okafor"], "NHS": ["485 777 3456"]}
+graph = build_graph(known=_DEMO_KNOWN)

app/api.py

@@ -0,0 +1,279 @@
+"""NoteGuard FastAPI backend — PHI-safe REST endpoint for the LangGraph agent.
+
+Exposes:
+  GET  /              -> index.html (clinician web UI)
+  GET  /health        -> {"status": "ok"}
+  GET  /samples       -> paginated list of synthetic notes (requires data/ dir)
+  GET  /sample/random -> one random synthetic note
+  GET  /sample/{id}   -> full note by clinical_note_id
+  POST /summarise     -> {clinician_answer, identifiers_removed, residual_risk,
+                          deidentified_excerpt, ok}
+  POST /process       -> {clinician_note, ai_note, identifiers, discharge_summary, metrics}
+
+The assert_clean() guarantee is preserved: the graph raises ValueError if any
+identifier survives de-identification, which surfaces here as HTTP 422.
+
+Run:  uvicorn app.api:app --reload --port 8000
+"""
+
+from __future__ import annotations
+
+import csv
+import random
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+load_dotenv(override=True)
+
+from fastapi import FastAPI, HTTPException, Query
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+from langchain_core.messages import HumanMessage
+from pydantic import BaseModel
+from src.deid import NoteGuard, load_known_from_csv
+
+STATIC_DIR = Path(__file__).parent / "static"
+_DATA_DIR = Path(__file__).parent.parent / "data"
+
+app = FastAPI(title="NoteGuard API", version="1.2.4")
+
+# ---------------------------------------------------------------------------
+# Dataset — loaded once at startup; degrades gracefully when data/ is absent
+# ---------------------------------------------------------------------------
+
+_NOTES: list[dict] = []
+_DEFAULT_KNOWN: dict | None = None
+
+try:
+    _patients_csv = str(_DATA_DIR / "patients.csv")
+    _admissions_csv = str(_DATA_DIR / "admissions.csv")
+    _DEFAULT_KNOWN = load_known_from_csv(_patients_csv, _admissions_csv)
+
+    with open(_DATA_DIR / "synthetic_clinical_notes.csv", newline="", encoding="utf-8-sig") as _f:
+        for _row in csv.DictReader(_f):
+            _text = NoteGuard._fix_mojibake(_row["clean_note_text"])
+            _NOTES.append(
+                {
+                    "clinical_note_id": _row["clinical_note_id"],
+                    "person_id": _row["person_id"],
+                    "note_type": _row.get("note_type", ""),
+                    "note_subject": _row.get("note_subject", ""),
+                    "excerpt": _text[:120].strip(),
+                    "note_text": _text,
+                }
+            )
+except Exception:
+    pass  # data/ not present — /samples returns empty, /process still works
+
+# ---------------------------------------------------------------------------
+# Per-vault graph cache — key is a hashable snapshot of the known-identifier dict.
+# ---------------------------------------------------------------------------
+
+_graph_cache: dict = {}
+
+
+def _vault_key(known: dict | None) -> tuple | None:
+    if not known:
+        return None
+    return tuple(sorted((k, tuple(sorted(v))) for k, v in known.items()))
+
+
+def _get_graph(known: dict | None):
+    """Return a compiled NoteGuard graph, building it once per distinct vault."""
+    key = _vault_key(known)
+    if key not in _graph_cache:
+        from agent.graph import build_graph
+
+        _graph_cache[key] = build_graph(known=known)
+    return _graph_cache[key]
+
+
+# ---------------------------------------------------------------------------
+# Models
+# ---------------------------------------------------------------------------
+
+
+class SummariseRequest(BaseModel):
+    note: str
+    question: str = "Draft an NHS eDischarge summary."
+    known: dict | None = None
+
+
+class SummariseResponse(BaseModel):
+    clinician_answer: str
+    identifiers_removed: int
+    residual_risk: float
+    deidentified_excerpt: str
+    ok: bool
+
+
+class ProcessRequest(BaseModel):
+    note: str
+    question: str = "Draft an NHS eDischarge summary."
+    known: dict | None = None
+    person_id: str | None = None  # accepted for UI compatibility; unused (patient is never named)
+
+
+class ProcessResponse(BaseModel):
+    clinician_note: str
+    ai_note: str
+    identifiers: list[str]
+    discharge_summary: str
+    metrics: dict
+
+
+class SampleItem(BaseModel):
+    clinical_note_id: str
+    person_id: str
+    note_type: str
+    excerpt: str
+
+
+class SamplesResponse(BaseModel):
+    total: int
+    items: list[SampleItem]
+
+
+class SampleDetail(BaseModel):
+    clinical_note_id: str
+    person_id: str
+    note_type: str
+    note_subject: str
+    note_text: str
+
+
+# ---------------------------------------------------------------------------
+# Endpoints
+# ---------------------------------------------------------------------------
+
+
+@app.get("/")
+def index():
+    return FileResponse(STATIC_DIR / "index.html")
+
+
+@app.get("/health")
+def health():
+    """Liveness probe — no API keys required."""
+    return {"status": "ok", "notes_loaded": len(_NOTES)}
+
+
+@app.get("/samples", response_model=SamplesResponse)
+def samples(
+    limit: int = Query(50, ge=1, le=200),
+    offset: int = Query(0, ge=0),
+    q: str = Query(""),
+    note_type: str = Query(""),
+):
+    """Paginated list of synthetic notes with optional text/type filter."""
+    hits = _NOTES
+    if note_type:
+        hits = [n for n in hits if n["note_type"] == note_type]
+    if q:
+        ql = q.lower()
+        hits = [n for n in hits if ql in n["note_text"].lower() or ql in n["note_subject"].lower()]
+    page = hits[offset : offset + limit]
+    return SamplesResponse(
+        total=len(hits),
+        items=[
+            SampleItem(
+                clinical_note_id=n["clinical_note_id"],
+                person_id=n["person_id"],
+                note_type=n["note_type"],
+                excerpt=n["excerpt"],
+            )
+            for n in page
+        ],
+    )
+
+
+@app.get("/sample/random", response_model=SampleDetail)
+def sample_random():
+    """Return one random synthetic note."""
+    if not _NOTES:
+        raise HTTPException(status_code=404, detail="No notes loaded — run src/fetch_dataset.py first.")
+    note = random.choice(_NOTES)
+    return SampleDetail(**{k: note[k] for k in SampleDetail.model_fields})
+
+
+@app.get("/sample/{clinical_note_id}", response_model=SampleDetail)
+def sample_by_id(clinical_note_id: str):
+    """Return a single synthetic note by its clinical_note_id."""
+    for note in _NOTES:
+        if note["clinical_note_id"] == clinical_note_id:
+            return SampleDetail(**{k: note[k] for k in SampleDetail.model_fields})
+    raise HTTPException(status_code=404, detail=f"Note {clinical_note_id!r} not found.")
+
+
+@app.post("/summarise", response_model=SummariseResponse)
+def summarise(req: SummariseRequest):
+    """Run the NoteGuard agent and return a PHI-safe discharge summary.
+
+    Raises:
+        HTTPException 422: assert_clean() detected surviving PHI.
+        HTTPException 500: unexpected agent error.
+    """
+    known = req.known if req.known is not None else _DEFAULT_KNOWN
+    try:
+        g = _get_graph(known)
+        state = g.invoke({"messages": [HumanMessage(content=req.note + "\n\n" + req.question)]})
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    except Exception as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+    # De-id is correct iff nothing leaked to the model AND every surrogate reverses.
+    residual_pii = state.get("residual_pii") or []
+    leaked = state.get("leaked_tokens") or []
+    ok = not residual_pii and not leaked
+    return SummariseResponse(
+        clinician_answer=state.get("clinician_answer", ""),
+        identifiers_removed=len(state.get("forward", {})),
+        residual_risk=0.0 if ok else 1.0,
+        deidentified_excerpt=(state.get("deid_text") or "")[:400],
+        ok=ok,
+    )
+
+
+@app.post("/process", response_model=ProcessResponse)
+def process(req: ProcessRequest):
+    """Run NoteGuard and return rich output for the clinician UI.
+
+    When req.known is omitted, uses the pre-built vault from data/patients.csv
+    so residual-leakage is measured against ground truth identifiers.
+    """
+    known = req.known if req.known is not None else _DEFAULT_KNOWN
+    try:
+        g = _get_graph(known)
+        state = g.invoke({"messages": [HumanMessage(content=req.note + "\n\n" + req.question)]})
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    except Exception as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+    forward = state.get("forward") or {}
+    leaked = state.get("leaked_tokens") or []
+    residual_pii = state.get("residual_pii") or []
+    reversible = not leaked
+    deid_ok = not residual_pii and reversible
+
+    return ProcessResponse(
+        clinician_note=req.note,
+        ai_note=state.get("deid_text", ""),
+        identifiers=list(forward.keys()),
+        discharge_summary=state.get("clinician_answer", ""),
+        metrics={
+            # Every metric reports whether reversible pseudonymisation was done correctly.
+            "deid_ok": deid_ok,  # overall verdict: nothing leaked AND fully reversible
+            "identifiers_removed": len(forward),  # PII spans pseudonymised this turn
+            "residual_pii": residual_pii,  # [{type, text}] PII the model still saw
+            "residual_pii_count": len(residual_pii),
+            "reversible": reversible,  # every surrogate restores to a real value
+            "leaked_tokens": leaked,  # orphaned/unresolved surrogate tokens
+        },
+    )
+
+
+if STATIC_DIR.exists():
+    app.mount("/static", StaticFiles(directory=str(STATIC_DIR)), name="static")

app/static/index.html

@@ -0,0 +1,604 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>NoteGuard — the trust layer for clinical AI</title>
+  <style>
+    :root {
+      --nhs-dark-blue: #003087;
+      --nhs-blue: #005EB8;
+      --nhs-mid-blue: #0072CE;
+      --nhs-green: #007f3b;
+      --nhs-red: #d5281b;
+      --nhs-light-grey: #f0f4f5;
+      --nhs-mid-grey: #768692;
+      --radius: 8px;
+    }
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body { font-family: Arial, sans-serif; background: var(--nhs-light-grey); color: #212b32; min-height: 100vh; }
+
+    header {
+      background: var(--nhs-dark-blue); color: #fff;
+      padding: 0 32px; height: 56px;
+      display: flex; align-items: center; gap: 12px;
+    }
+    header .logo { font-size: 20px; font-weight: 700; letter-spacing: -.4px; }
+    header .tag { font-size: 13px; opacity: .65; }
+
+    .main {
+      padding: 24px 32px;
+      display: grid; grid-template-columns: 1fr 1fr; gap: 20px;
+    }
+
+    .card {
+      background: #fff; border-radius: var(--radius);
+      padding: 20px; box-shadow: 0 1px 4px rgba(0,0,0,.08);
+    }
+    .card-title {
+      font-size: 11px; font-weight: 700; color: var(--nhs-dark-blue);
+      text-transform: uppercase; letter-spacing: .7px; margin-bottom: 14px;
+    }
+
+    /* Toggle */
+    .toggle-row { display: flex; gap: 6px; margin-bottom: 14px; }
+    .toggle-btn {
+      padding: 5px 16px; border-radius: 20px;
+      border: 2px solid var(--nhs-blue); background: #fff;
+      color: var(--nhs-blue); font-size: 13px; font-weight: 600; cursor: pointer;
+      transition: background .12s, color .12s;
+    }
+    .toggle-btn.active { background: var(--nhs-blue); color: #fff; }
+
+    /* Input */
+    textarea {
+      width: 100%; min-height: 160px; resize: vertical;
+      border: 2px solid #d8dde0; border-radius: var(--radius);
+      padding: 10px 12px; font-size: 14px; font-family: inherit;
+      line-height: 1.5; outline: none; transition: border-color .12s;
+    }
+    textarea:focus { border-color: var(--nhs-blue); }
+
+    .btn-row { display: flex; gap: 8px; margin-top: 10px; flex-wrap: wrap; }
+    .btn {
+      padding: 8px 20px; border-radius: 4px; border: none;
+      font-size: 14px; font-weight: 600; cursor: pointer; transition: background .12s;
+    }
+    .btn-primary { background: var(--nhs-blue); color: #fff; }
+    .btn-primary:hover:not(:disabled) { background: var(--nhs-dark-blue); }
+    .btn-primary:disabled { background: var(--nhs-mid-grey); cursor: not-allowed; }
+    .btn-ghost { background: #e8edee; color: #212b32; font-size: 13px; }
+    .btn-ghost:hover { background: #d3d8da; }
+
+    .dataset-hint {
+      display: none; font-size: 11px; color: var(--nhs-mid-grey);
+      margin-top: 6px;
+    }
+
+    /* Note display */
+    .note-display {
+      display: none; min-height: 160px;
+      border: 2px solid #d8dde0; border-radius: var(--radius);
+      padding: 10px 12px; font-size: 14px; line-height: 1.65;
+      background: #fafbfc; white-space: pre-wrap; word-break: break-word;
+    }
+    .note-display.visible { display: block; }
+    mark.phi {
+      background: #ffe8e6; color: #900; border-radius: 3px;
+      padding: 1px 3px; font-weight: 600;
+    }
+    .chip {
+      display: inline-block; font-family: Consolas, Menlo, monospace;
+      background: #e3f2fd; color: var(--nhs-mid-blue);
+      border: 1px solid #90caf9; border-radius: 4px;
+      padding: 0 5px; font-size: 12px; line-height: 1.8;
+    }
+
+    /* Right pane */
+    .placeholder {
+      min-height: 160px; display: flex; align-items: center; justify-content: center;
+      border: 2px dashed #d8dde0; border-radius: var(--radius);
+      color: var(--nhs-mid-grey); font-size: 14px; font-style: italic;
+    }
+    .summary-text {
+      display: none; font-size: 14px; line-height: 1.7;
+      word-break: break-word;
+    }
+    .summary-text.visible { display: block; }
+    .summary-text p { margin: 0 0 10px; }
+    .summary-text p:last-child { margin-bottom: 0; }
+    .card-title {
+      font-weight: 700; font-size: 15px; color: var(--nhs-dark-blue);
+    }
+    .card-followup .fu-label {
+      font-weight: 700; color: var(--nhs-dark-blue);
+    }
+    .card-grounded {
+      font-size: 12px; color: var(--nhs-mid-grey);
+      padding-top: 8px; margin-top: 4px !important;
+      border-top: 1px solid #e5e9ec; display: flex; align-items: flex-start; gap: 5px;
+    }
+    .card-grounded svg { flex-shrink: 0; margin-top: 2px; }
+    .powered-by {
+      display: none; margin-top: 8px;
+      font-size: 11px; color: var(--nhs-mid-grey); text-align: right;
+    }
+    .powered-by.visible { display: block; }
+
+    /* Trust panel */
+    .trust-row {
+      display: grid; grid-template-columns: repeat(4, 1fr);
+      gap: 12px; padding: 0 32px 32px;
+    }
+    .metric {
+      background: #fff; border-radius: var(--radius); padding: 14px 16px;
+      box-shadow: 0 1px 4px rgba(0,0,0,.08); text-align: center;
+    }
+    .metric[hidden] { display: none; }
+    .metric .mlabel {
+      font-size: 11px; color: var(--nhs-mid-grey);
+      font-weight: 700; text-transform: uppercase; letter-spacing: .5px;
+    }
+    .metric .mvalue {
+      font-size: 26px; font-weight: 700; color: var(--nhs-dark-blue); margin-top: 4px;
+    }
+    .mvalue.ok { color: var(--nhs-green); }
+    .mvalue.risk { color: var(--nhs-red); }
+    .leak-detail {
+      font-size: 10px; color: var(--nhs-red); margin-top: 4px;
+      word-break: break-all; line-height: 1.4;
+    }
+
+    /* Spinner */
+    .spinner {
+      display: none; width: 14px; height: 14px;
+      border: 2px solid rgba(255,255,255,.4); border-top-color: #fff;
+      border-radius: 50%; animation: spin .6s linear infinite;
+      vertical-align: middle; margin-right: 5px;
+    }
+    .spinner.on { display: inline-block; }
+    @keyframes spin { to { transform: rotate(360deg); } }
+
+    .edit-link {
+      font-size: 12px; color: var(--nhs-mid-grey); cursor: pointer;
+      margin-top: 8px; display: none; text-decoration: underline; text-underline-offset: 2px;
+    }
+    .edit-link.visible { display: block; }
+
+    /* ── Note picker modal ── */
+    .picker-overlay {
+      position: fixed; inset: 0; background: rgba(0,0,0,.5);
+      display: none; align-items: center; justify-content: center; z-index: 100;
+    }
+    .picker-overlay.open { display: flex; }
+    .picker-panel {
+      background: #fff; border-radius: var(--radius);
+      width: min(620px, 95vw); max-height: 82vh;
+      display: flex; flex-direction: column; overflow: hidden;
+      box-shadow: 0 8px 32px rgba(0,0,0,.22);
+    }
+    .picker-header {
+      display: flex; justify-content: space-between; align-items: center;
+      padding: 15px 20px; border-bottom: 1px solid #e5e9ec;
+      font-weight: 700; font-size: 14px; color: var(--nhs-dark-blue);
+      flex-shrink: 0;
+    }
+    .picker-close {
+      background: none; border: none; font-size: 22px; line-height: 1;
+      cursor: pointer; color: var(--nhs-mid-grey); padding: 0 2px;
+    }
+    .picker-controls {
+      padding: 10px 14px; display: flex; gap: 8px;
+      border-bottom: 1px solid #e5e9ec; flex-shrink: 0;
+    }
+    .picker-input {
+      flex: 1; padding: 7px 10px; border: 2px solid #d8dde0; border-radius: 4px;
+      font-size: 13px; font-family: inherit; outline: none; min-width: 0;
+    }
+    .picker-input:focus { border-color: var(--nhs-blue); }
+    .picker-select {
+      padding: 7px 8px; border: 2px solid #d8dde0; border-radius: 4px;
+      font-size: 12px; font-family: inherit; background: #fff;
+      outline: none; cursor: pointer; max-width: 160px;
+    }
+    .picker-list { overflow-y: auto; flex: 1; }
+    .picker-row {
+      padding: 10px 16px; cursor: pointer;
+      border-bottom: 1px solid #f0f4f5; transition: background .1s;
+    }
+    .picker-row:hover { background: var(--nhs-light-grey); }
+    .picker-row .ptype {
+      font-size: 11px; font-weight: 700; color: var(--nhs-mid-blue);
+      text-transform: uppercase; letter-spacing: .5px;
+    }
+    .picker-row .pexcerpt { font-size: 13px; color: #212b32; margin-top: 2px; line-height: 1.45; }
+    .picker-empty {
+      padding: 36px 16px; text-align: center;
+      font-size: 13px; color: var(--nhs-mid-grey); font-style: italic;
+    }
+
+    @media (max-width: 860px) {
+      .main { grid-template-columns: 1fr; }
+      .trust-row { grid-template-columns: repeat(2, 1fr); }
+    }
+  </style>
+</head>
+<body>
+
+<header>
+  <div class="logo">NoteGuard</div>
+  <div class="tag">— the trust layer for clinical AI</div>
+</header>
+
+<div class="main">
+  <!-- LEFT: input / rendered note -->
+  <div class="card">
+    <div class="card-title">Clinical Note</div>
+
+    <div class="toggle-row">
+      <button class="toggle-btn active" id="btnClinician" onclick="setView('clinician')">Clinician view</button>
+      <button class="toggle-btn" id="btnAI" onclick="setView('ai')">What the AI sees</button>
+    </div>
+
+    <div id="inputArea">
+      <textarea id="noteInput" placeholder="Paste a ward note, discharge summary or referral letter…"></textarea>
+      <div class="btn-row">
+        <button class="btn btn-ghost" id="browseBtn" onclick="openPicker()" style="display:none">Browse notes</button>
+        <button class="btn btn-ghost" id="sampleBtn" onclick="loadSample()">Load sample note</button>
+        <button class="btn btn-primary" id="genBtn" onclick="generate()">
+          <span class="spinner" id="spinner"></span>Generate
+        </button>
+      </div>
+      <div class="dataset-hint" id="datasetHint">
+        Dataset not loaded — run <code>python scripts/fetch_dataset.py</code> to enable note browsing.
+      </div>
+    </div>
+
+    <div id="noteDisplay" class="note-display"></div>
+    <span class="edit-link" id="editLink" onclick="resetUI()">← Edit note</span>
+  </div>
+
+  <!-- RIGHT: discharge summary -->
+  <div class="card">
+    <div class="card-title">Discharge Summary</div>
+    <div class="placeholder" id="placeholder">Output will appear here after generation</div>
+    <div class="summary-text" id="summaryText"></div>
+    <div class="powered-by" id="poweredBy">powered by Gemini</div>
+  </div>
+</div>
+
+<!-- TRUST PANEL — every metric reports whether de-identification was done correctly -->
+<div class="trust-row">
+  <div class="metric" id="mDeid">
+    <div class="mlabel">De-identification</div>
+    <div class="mvalue" id="mDeidVal">—</div>
+  </div>
+  <div class="metric" id="mIds">
+    <div class="mlabel">Identifiers replaced</div>
+    <div class="mvalue" id="mIdsVal">—</div>
+  </div>
+  <div class="metric" id="mResidual">
+    <div class="mlabel">Residual PII · model input</div>
+    <div class="mvalue" id="mResidualVal">—</div>
+    <div id="residualDetail" class="leak-detail" style="display:none"></div>
+  </div>
+  <div class="metric" id="mRev">
+    <div class="mlabel">Reversible</div>
+    <div class="mvalue" id="mRevVal">—</div>
+    <div id="revDetail" class="leak-detail" style="display:none"></div>
+  </div>
+</div>
+
+<!-- NOTE PICKER MODAL -->
+<div id="pickerOverlay" class="picker-overlay" onclick="if(event.target===this)closePicker()">
+  <div class="picker-panel">
+    <div class="picker-header">
+      <span id="pickerTitle">Synthetic Note Library</span>
+      <button class="picker-close" onclick="closePicker()">&#x2715;</button>
+    </div>
+    <div class="picker-controls">
+      <input id="pickerSearch" class="picker-input" type="text"
+             placeholder="Search notes…" oninput="debouncedSearch()">
+      <select id="pickerType" class="picker-select" onchange="fetchSamples()">
+        <option value="">All types</option>
+      </select>
+      <button class="btn btn-ghost" onclick="pickerShuffle()" style="white-space:nowrap;font-size:13px">&#x1F500; Shuffle</button>
+    </div>
+    <div id="pickerList" class="picker-list"></div>
+  </div>
+</div>
+
+<script>
+const SAMPLE = `Ward 4B. Pt Margaret Okafor (NHS 485 777 3456, DOB 22/09/1958, F, 45 Elm Road SW1A 1AA). GP: Dr James Obi, Riverside Surgery, Lambeth SE1 7PB.
+
+Admitted 12 Jan 2025 via ED with acute exacerbation of COPD. PMH: COPD (GOLD stage III), T2DM on metformin, hypertension on amlodipine. NKDA. O2 sats 88% on air on admission.
+
+Managed with nebulised salbutamol 2.5 mg QDS and ipratropium 500 mcg QDS, IV hydrocortisone 100 mg TDS (switched to prednisolone 30 mg OD after 48 h), doxycycline 200 mg stat then 100 mg OD (sputum purulent). O2 titrated to 88-92%.
+
+CXR: bilateral hyperinflation, no consolidation. Bloods: WBC 11.2, CRP 78. HbA1c 58 mmol/mol. Sputum C&S pending at discharge.
+
+Discharged home 14 Jan 2025. TTO: carbocisteine 375 mg TDS, prednisolone 30 mg OD for 5 days, doxycycline 100 mg OD for 4 more days. Metformin and amlodipine continued unchanged.
+
+Responsible consultant: Dr Sarah Chen, Respiratory Medicine.`;
+
+let view = 'clinician';
+let result = null;
+let pickerTimer = null;
+let currentPersonId = null;
+let noteTypesPopulated = false;
+
+// ── Startup: check if dataset is present ──────────────────────────────────
+window.addEventListener('DOMContentLoaded', async () => {
+  try {
+    const h = await fetch('/health').then(r => r.json());
+    if (h.notes_loaded > 0) {
+      const browseBtn = document.getElementById('browseBtn');
+      browseBtn.textContent = `Browse notes (${h.notes_loaded.toLocaleString()})`;
+      browseBtn.style.display = '';
+      document.getElementById('sampleBtn').style.display = 'none';
+    } else {
+      document.getElementById('datasetHint').style.display = 'block';
+    }
+  } catch (_) {
+    // server not running yet — keep fallback button
+  }
+});
+
+// ── Picker logic ──────────────────────────────────────────────────────────
+function openPicker() {
+  document.getElementById('pickerOverlay').classList.add('open');
+  document.getElementById('pickerSearch').value = '';
+  document.getElementById('pickerType').value = '';
+  document.getElementById('pickerSearch').focus();
+  fetchSamples();
+}
+
+function closePicker() {
+  document.getElementById('pickerOverlay').classList.remove('open');
+}
+
+function debouncedSearch() {
+  clearTimeout(pickerTimer);
+  pickerTimer = setTimeout(fetchSamples, 300);
+}
+
+async function fetchSamples() {
+  const q = document.getElementById('pickerSearch').value.trim();
+  const nt = document.getElementById('pickerType').value;
+  const params = new URLSearchParams({ limit: 50 });
+  if (q) params.set('q', q);
+  if (nt) params.set('note_type', nt);
+
+  const list = document.getElementById('pickerList');
+  list.innerHTML = '<div class="picker-empty">Loading…</div>';
+
+  try {
+    const data = await fetch('/samples?' + params).then(r => r.json());
+
+    // Update header count
+    const filterLabel = (q || nt) ? ' — filtered' : '';
+    document.getElementById('pickerTitle').textContent =
+      data.total.toLocaleString() + ' synthetic notes' + filterLabel;
+
+    // Populate type dropdown once
+    if (!noteTypesPopulated && data.items.length > 0) {
+      populateTypes(data.items);
+    }
+
+    if (data.items.length === 0) {
+      list.innerHTML = '<div class="picker-empty">No notes match your search.</div>';
+      return;
+    }
+
+    list.innerHTML = data.items.map(n =>
+      `<div class="picker-row" onclick="selectNote('${n.clinical_note_id}')">` +
+        `<div class="ptype">${esc(n.note_type || 'Note')}</div>` +
+        `<div class="pexcerpt">${esc(n.excerpt)}</div>` +
+      `</div>`
+    ).join('');
+  } catch (_) {
+    list.innerHTML = '<div class="picker-empty">Failed to load notes.</div>';
+  }
+}
+
+async function populateTypes(items) {
+  // Seed from first page; also fetch a wider set to catch rarer types
+  try {
+    const all = await fetch('/samples?limit=200').then(r => r.json());
+    const types = [...new Set(all.items.map(n => n.note_type).filter(Boolean))].sort();
+    const sel = document.getElementById('pickerType');
+    types.forEach(t => {
+      const o = document.createElement('option');
+      o.value = t; o.textContent = t;
+      sel.appendChild(o);
+    });
+    noteTypesPopulated = true;
+  } catch (_) {}
+}
+
+async function pickerShuffle() {
+  try {
+    const note = await fetch('/sample/random').then(r => r.json());
+    applyPickedNote(note);
+  } catch (_) {}
+}
+
+async function selectNote(id) {
+  try {
+    const note = await fetch('/sample/' + encodeURIComponent(id)).then(r => r.json());
+    applyPickedNote(note);
+  } catch (_) {}
+}
+
+function applyPickedNote(note) {
+  closePicker();
+  resetUI();
+  currentPersonId = note.person_id || null;
+  document.getElementById('noteInput').value = note.note_text;
+}
+
+// ── Existing UI logic ─────────────────────────────────────────────────────
+function setView(v) {
+  view = v;
+  document.getElementById('btnClinician').classList.toggle('active', v === 'clinician');
+  document.getElementById('btnAI').classList.toggle('active', v === 'ai');
+  if (result) renderNote();
+}
+
+function loadSample() {
+  resetUI();
+  document.getElementById('noteInput').value = SAMPLE;
+}
+
+function resetUI() {
+  result = null;
+  currentPersonId = null;
+  document.getElementById('inputArea').style.display = '';
+  document.getElementById('noteDisplay').classList.remove('visible');
+  document.getElementById('editLink').classList.remove('visible');
+  document.getElementById('placeholder').style.display = '';
+  document.getElementById('summaryText').classList.remove('visible');
+  document.getElementById('poweredBy').classList.remove('visible');
+  for (const id of ['mDeidVal', 'mIdsVal', 'mResidualVal', 'mRevVal']) {
+    const el = document.getElementById(id);
+    el.textContent = '—';
+    el.className = 'mvalue';
+  }
+  for (const id of ['residualDetail', 'revDetail']) {
+    const el = document.getElementById(id);
+    if (el) { el.textContent = ''; el.style.display = 'none'; }
+  }
+}
+
+function esc(s) {
+  return String(s).replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');
+}
+
+const _LINK_ICON = `<svg width="11" height="11" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"/><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"/></svg>`;
+
+function renderSummary(text) {
+  const lines = (text || '').trim().split('\n').map(l => l.trim()).filter(l => l);
+  return lines.map(line => {
+    if (line.startsWith('Follow-up:')) {
+      const rest = esc(line.slice('Follow-up:'.length));
+      return `<p class="card-followup"><span class="fu-label">Follow-up:</span>${rest}</p>`;
+    }
+    if (line.startsWith('Grounded:')) {
+      const rest = esc(line.slice('Grounded:'.length));
+      return `<p class="card-grounded">${_LINK_ICON}<span>${rest}</span></p>`;
+    }
+    // Defensive: should the model ever emit a "<name> — discharge summary" title
+    // line, drop it — the patient is never named and the card already has a header.
+    if (line.includes('— discharge summary') || line.includes('- discharge summary')) {
+      return '';
+    }
+    return `<p>${esc(line)}</p>`;
+  }).join('');
+}
+
+function highlightPHI(text, ids) {
+  if (!ids || !ids.length) return esc(text);
+  const sorted = [...ids].sort((a, b) => b.length - a.length);
+  let out = '', i = 0;
+  while (i < text.length) {
+    let hit = false;
+    for (const id of sorted) {
+      if (text.startsWith(id, i)) {
+        out += `<mark class="phi">${esc(id)}</mark>`;
+        i += id.length;
+        hit = true;
+        break;
+      }
+    }
+    if (!hit) { out += esc(text[i]); i++; }
+  }
+  return out;
+}
+
+function renderAI(text) {
+  return esc(text).replace(/\[([A-Z]+)_(\d+)\]/g, m => `<span class="chip">${m}</span>`);
+}
+
+function renderNote() {
+  const el = document.getElementById('noteDisplay');
+  el.innerHTML = view === 'clinician'
+    ? highlightPHI(result.clinician_note, result.identifiers)
+    : renderAI(result.ai_note);
+}
+
+async function generate() {
+  const note = document.getElementById('noteInput').value.trim();
+  if (!note) return;
+
+  const btn = document.getElementById('genBtn');
+  const sp = document.getElementById('spinner');
+  btn.disabled = true;
+  sp.classList.add('on');
+
+  try {
+    const resp = await fetch('/process', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ note, question: 'Draft an NHS eDischarge summary.', person_id: currentPersonId || undefined })
+    });
+    if (!resp.ok) {
+      const err = await resp.json().catch(() => ({}));
+      alert('Error ' + resp.status + ': ' + (err.detail || resp.statusText));
+      return;
+    }
+    result = await resp.json();
+
+    // Switch left pane to rendered note
+    document.getElementById('inputArea').style.display = 'none';
+    document.getElementById('noteDisplay').classList.add('visible');
+    document.getElementById('editLink').classList.add('visible');
+    renderNote();
+
+    // Right pane
+    document.getElementById('placeholder').style.display = 'none';
+    const sumEl = document.getElementById('summaryText');
+    sumEl.innerHTML = renderSummary(result.discharge_summary);
+    sumEl.classList.add('visible');
+    document.getElementById('poweredBy').classList.add('visible');
+
+    // Metrics — all four report whether de-identification succeeded
+    const m = result.metrics;
+
+    // 1. Overall verdict
+    const dv = document.getElementById('mDeidVal');
+    dv.textContent = m.deid_ok ? 'PASS' : 'FAIL';
+    dv.className = 'mvalue ' + (m.deid_ok ? 'ok' : 'risk');
+
+    // 2. Identifiers replaced (pseudonymised this turn)
+    document.getElementById('mIdsVal').textContent = m.identifiers_removed;
+
+    // 3. Residual PII the model still saw — the headline failure signal
+    const rv = document.getElementById('mResidualVal');
+    rv.textContent = m.residual_pii_count;
+    rv.className = 'mvalue ' + (m.residual_pii_count === 0 ? 'ok' : 'risk');
+    const rd = document.getElementById('residualDetail');
+    if (m.residual_pii_count > 0) {
+      rd.textContent = m.residual_pii.slice(0, 4)
+        .map(p => p.type + ': ' + p.text).join('  ·  ');
+      rd.style.display = 'block';
+    }
+
+    // 4. Reversibility — every surrogate restores to a real value
+    const ev = document.getElementById('mRevVal');
+    ev.textContent = m.reversible ? '✓' : '✗';
+    ev.className = 'mvalue ' + (m.reversible ? 'ok' : 'risk');
+    const ed = document.getElementById('revDetail');
+    if (!m.reversible && m.leaked_tokens && m.leaked_tokens.length) {
+      ed.textContent = 'Unresolved: ' + m.leaked_tokens.slice(0, 3).join(', ');
+      ed.style.display = 'block';
+    }
+  } catch (e) {
+    alert('Request failed: ' + e.message);
+  } finally {
+    btn.disabled = false;
+    sp.classList.remove('on');
+  }
+}
+</script>
+</body>
+</html>

docs/architecture.md

@@ -0,0 +1,164 @@
+# Architecture
+
+## Overview
+
+NoteGuard is the trust layer for clinical AI — a LangGraph ReAct agent (Gemini +
+Tavily) where the language model structurally **cannot** see patient identifiers
+because `assert_clean()` raises before any PHI reaches it.
+
+The system has four layers:
+
+1. **De-identification core** (`src/deid.py`) — dependency-free, runnable
+   standalone. NHS-aware recognisers, vault-from-CSV, consistent surrogates,
+   DOB date-shift, `assert_clean()` hard guarantee.
+2. **Agent** (`agent/graph.py`) — LangGraph `StateGraph`. Gemini drafts the
+   answer; Tavily grounds it in NICE/NHS public guidance. Neither sees PHI.
+3. **REST API** (`app/api.py`) — FastAPI backend exposing `GET /` (web UI),
+   `GET /health`, `POST /process`, `POST /summarise`, `GET /samples`, and
+   `GET /sample/{id}`. Also serves the static clinician UI.
+4. **UI** — `app/static/index.html` (clinician web UI, vanilla JS, no build step, served by the FastAPI `GET /` handler).
+
+## Package layout
+
+```
+src/
+├── __init__.py           # exports NoteGuard, DeidResult, load_known_from_csv
+├── deid.py               # de-id core (standard library only)
+└── fetch_dataset.py      # downloads synthetic_clinical_notes to data/
+
+agent/
+└── graph.py              # LangGraph StateGraph exposed as `noteguard` for langgraph dev
+
+app/
+├── api.py                # FastAPI — GET /, GET /health, GET /samples, GET /sample/{id},
+│                         #           POST /process, POST /summarise
+└── static/
+    └── index.html        # Clinician web UI (single-file, vanilla JS, no build step)
+
+streamlit_app.py          # Interactive de-id demo — no API keys needed
+
+eval/
+└── run_eval.py           # LangSmith evals: zero_phi_to_model + faithfulness
+
+tests/                    # pytest suite (24 tests, no external deps)
+data/                     # synthetic CSV files (git-ignored; produced by src/fetch_dataset.py)
+docs/                     # architecture, user guide, RAP compliance, tool card, ATRS report
+```
+
+## Graph pipeline
+
+For every query the graph runs:
+
+```
+deidentify_in → agent → reidentify_out → compute_trust
+```
+
+| Node | Function | Description |
+|---|---|---|
+| `deidentify_in` | `NoteGuard.deidentify()` + `assert_clean()` | Strips PHI; raises if any identifier survives. |
+| `agent` | `create_react_agent` (Gemini + Tavily) | Drafts answer; sees only de-identified text. |
+| `reidentify_out` | `NoteGuard.reidentify()` | Restores surrogates → real names for the clinician only. |
+| `compute_trust` | `NoteGuard.scan_pii()` | De-id audit — residual PII the model saw + orphaned surrogate tokens (reversibility) for the trust panel. |
+
+## State fields
+
+In addition to `messages`, the graph state carries:
+
+| Field | Type | Description |
+|---|---|---|
+| `deid_text` | `str` | De-identified version of the input note. |
+| `forward` | `dict` | Original-identifier → surrogate mapping. |
+| `identifiers_removed` | `int` | Count of identifiers replaced in this turn. |
+| `residual_count` | `int` | Known identifiers that survived (target: 0). |
+| `leaked_tokens` | `list[str]` | Orphaned/unresolved surrogate tokens in the output (reversibility). |
+| `clinician_answer` | `str` | Re-identified, clinician-facing answer. |
+| `residual_pii` | `list[dict]` | `{type, text}` findings of suspected un-redacted PII in `deid_text`. |
+
+## REST API
+
+`app/api.py` exposes six endpoints:
+
+| Endpoint | Method | Description |
+|---|---|---|
+| `/` | GET | Serves `app/static/index.html` — the clinician web UI. |
+| `/health` | GET | Liveness probe; no API keys required. Returns `notes_loaded` count. |
+| `/samples` | GET | Paginated list of synthetic notes; supports `q`, `note_type`, `limit`, `offset`. |
+| `/sample/random` | GET | One random synthetic note. |
+| `/sample/{clinical_note_id}` | GET | Full note by ID (used by the note-picker modal). |
+| `/process` | POST | Full UI payload: `clinician_note`, `ai_note`, `identifiers`, `discharge_summary`, `metrics`. |
+| `/summarise` | POST | Compact payload: `clinician_answer`, `identifiers_removed`, `residual_risk`, `deidentified_excerpt`, `ok`. |
+
+`POST /process` request shape:
+
+```json
+{
+  "note": "Pt Margaret Okafor (NHS 485 777 3456) admitted post-fall.",
+  "question": "Draft a discharge summary.",
+  "person_id": "pt-001"
+}
+```
+
+`POST /process` response shape:
+
+```json
+{
+  "clinician_note": "verbatim input",
+  "ai_note": "de-identified text the model saw ([PERSON_1], [NHS_1], …)",
+  "identifiers": ["Margaret Okafor", "485 777 3456", "…"],
+  "discharge_summary": "re-identified Gemini compact eDischarge card for the clinician",
+  "metrics": {
+    "deid_ok": true,
+    "identifiers_removed": 5,
+    "residual_pii": [],
+    "residual_pii_count": 0,
+    "reversible": true,
+    "leaked_tokens": []
+  }
+}
+```
+
+`422` is returned when `assert_clean()` detects surviving PHI — the model sees nothing.
+
+Every metric reports whether reversible pseudonymisation was done correctly.
+`deid_ok` is `true` only when `residual_pii` is empty (nothing un-redacted reached the
+model) **and** `reversible` is `true` (every surrogate restores to a real value). The
+`residual_pii` audit (`NoteGuard.scan_pii`) is vault-independent — it catches free-text
+names the vault/NER passes missed, so a pasted note with no ground truth is still graded.
+
+## Clinician web UI
+
+`app/static/index.html` is a self-contained single-page application (vanilla JS, no build step):
+
+- **Note picker modal** — browse and filter synthetic notes by keyword and note type;
+  clicking a row loads the note into the textarea (the patient is never named in the output).
+- **Segmented toggle** — switches between two views without re-calling the API:
+  - *Clinician view*: original note with each redacted identifier wrapped in a red `<mark>`.
+  - *What the AI sees*: de-identified note with `[TYPE_N]` surrogate tokens displayed as blue monospace chips.
+- **Generate** — POSTs to `/process`, populates the discharge summary pane and trust panel.
+- **Trust panel** — metric cards, all reporting de-id correctness: De-identification (PASS/FAIL), Identifiers replaced, Residual PII · model input (count + the offending snippets when > 0), Reversible (✓/✗, with unresolved tokens when ✗).
+
+## External services
+
+| Concern | Service | Notes |
+|---|---|---|
+| Reasoning | Google Gemini | `google_genai:gemini-2.5-flash` (configurable via `NOTEGUARD_MODEL`). |
+| Grounding | Tavily | Public NICE/NHS guidance only — patient text never sent. |
+| Observability | LangSmith | Auto-traces when `LANGSMITH_TRACING=true`. |
+
+All credentials are read from environment variables; nothing is hard-coded.
+
+## Deployment
+
+### Local (development)
+
+```bash
+pip install -e ".[dev]"
+uvicorn app.api:app --reload --port 8000
+```
+
+### Hugging Face Spaces (production)
+
+`Dockerfile` builds a lean Docker image installing only the runtime dependencies
+declared in `pyproject.toml`, served by uvicorn on port 7860.
+
+Required secrets: `GOOGLE_API_KEY`, `TAVILY_API_KEY`, `LANGSMITH_API_KEY`.

docs/rap_compliance.md

@@ -0,0 +1,60 @@
+# RAP compliance
+
+This repository is organised to meet **Gold RAP** under the
+[NHS RAP Community of Practice maturity framework](https://nhsdigital.github.io/rap-community-of-practice/introduction_to_RAP/levels_of_RAP/).
+The levels are cumulative — Gold includes everything in Baseline and Silver.
+The structure also draws on the
+[NHS England repository template](https://github.com/nhs-england-tools/repository-template)
+and the [NHS England "package your code" workshop](https://github.com/nhsengland/package-your-code-workshop).
+
+## Baseline RAP
+
+| Criterion | Status | Evidence |
+|---|---|---|
+| Data produced by code in an open-source language | ✅ | Python pipeline (`src/`, `agent/`, `eval/`). |
+| Code is version controlled | ✅ | Git, hosted on GitHub. |
+| README details steps to reproduce | ✅ | [`README.md`](../README.md), [`docs/user_guide.md`](user_guide.md). |
+| Code has been peer reviewed | ✅ | Pull request workflow with template + required human review. |
+| Code is published in the open | ✅ | Public GitHub repository, MIT licensed. |
+
+## Silver RAP
+
+| Criterion | Status | Evidence |
+|---|---|---|
+| Outputs produced with minimal manual intervention | ✅ | `uvicorn app.api:app` / `python -m eval.run_eval`; one-command startup. |
+| Code is well-documented (guidance, structure, docstrings) | ✅ | Module + function docstrings throughout; `docs/` directory. |
+| Well-organised, standard directory format | ✅ | `src/` core, `agent/`, `app/`, `eval/`, `tests/`, `docs/`, `data/`. |
+| Reusable functions and/or classes | ✅ | `NoteGuard`, `load_known_from_csv()`, `build_graph()` — composable and parameterisable. |
+| Adheres to agreed coding standards | ✅ | PEP 8, type hints, **ruff** lint + format (see `pyproject.toml`). |
+| Pipeline includes a testing framework | ✅ | `pytest` suite in `tests/` (24 tests; de-id core covered; no external deps needed). |
+| Dependency information included | ✅ | `pyproject.toml` — single source of truth; optional extras for the demo and dev tooling. |
+| Logs automatically recorded by the pipeline | ✅ | LangSmith auto-traces every graph run (`LANGSMITH_TRACING=true`). |
+| Configuration aids reusability | ✅ | All settings from environment variables; `.env.example` provided. |
+
+## Gold RAP
+
+| Criterion | Status | Evidence |
+|---|---|---|
+| Code is fully packaged | ✅ | `pyproject.toml` (setuptools, `pip install -e ".[dev]"`, optional extras). |
+| Tests run automatically via CI/CD | ✅ | [`.github/workflows/ci.yml`](../.github/workflows/ci.yml) — ruff + pytest on 3.10–3.12. |
+| Process runs on event-based triggers or a schedule | ✅ | CI on push / pull request; agent runs on live query events. |
+| Changes clearly signposted (changelog, releases) | ✅ | [`CHANGELOG.md`](../CHANGELOG.md), `VERSION`, semantic versioning. |
+
+## Additional good practice
+
+- **Pre-commit hooks** (`.pre-commit-config.yaml`) for local quality gates.
+- **Editor configuration** (`.editorconfig`) for consistent formatting.
+- **Pull request template** and `CONTRIBUTING.md` documenting the review process.
+- **Secret hygiene**: no credentials in code; `.env` git-ignored; a
+  `detect-private-key` pre-commit hook.
+- **Hard privacy guarantee**: `assert_clean()` enforced at every PHI boundary —
+  the de-id node before the model, and the `zero_phi_to_model` LangSmith eval.
+- **Reproducible outputs via the web UI**: `GET /` + `POST /process` provide a
+  documented, versioned HTTP interface that produces the same clinician output for
+  the same input — satisfying the reproducibility intent of RAP Gold.
+- **Documented API contract**: `docs/architecture.md` specifies every endpoint,
+  request/response shape, and the `assert_clean()` guarantee; consumers can
+  reproduce the analysis without reading source code.
+- **Governance documentation**: `docs/tool_card.md` (Five Safes mapping, bias &
+  fairness statement, DPIA prerequisites) and `docs/report.md` (gov.uk ATRS record,
+  Tier 1 + Tier 2).

docs/report.md

@@ -0,0 +1,94 @@
+# Algorithmic Transparency Record — NoteGuard
+
+> **Illustrative** record following the UK government
+> [Algorithmic Transparency Recording Standard (ATRS)](https://www.gov.uk/government/collections/algorithmic-transparency-recording-standard-hub),
+> modelled on the [NHS.UK Reviews Automoderation Tool record](https://www.gov.uk/algorithmic-transparency-records/nhs-england-nhs-dot-uk-reviews-automoderation-tool).
+> NoteGuard is a hackathon **prototype** evaluated on synthetic data — this is not an official
+> published ATRS entry, but is structured so it could become one.
+
+---
+
+## Tier 1 — Summary
+
+- **Name:** NoteGuard — NHS clinical-note de-identification and discharge-summary agent
+- **Description:** Detects and removes patient/clinician PII from free-text NHS clinical notes *inside* a Trust before any LLM sees them. Passes de-identified text to a LangGraph ReAct agent (Gemini 2.5 Flash) that drafts a compact eDischarge summary grounded in public NICE/NHS guidance (Tavily). Combines pure-Python rule recognisers with a Presidio/spaCy NER layer (`en_core_web_md`, shipped in the deployed image; graceful no-op fallback). No model is trained.
+- **Website / repository:** https://github.com/chaeyoonyunakim/noteguard-agent
+- **Contact:** via GitHub issues (maintainer **@chaeyoonyunakim**)
+
+---
+
+## Tier 2
+
+### 1. Owner and responsibility
+
+- **1.1 Organisation:** {Tech: Europe} London AI Hackathon — individual project.
+- **1.2 Team:** Chaeyoon Kim (sole contributor for this prototype).
+- **1.3 Senior responsible owner:** None — prototype, not in service. An SRO would be required before deployment.
+- **1.4 External supplier involvement:** No commercial supplier. Built on open-source components (LangGraph, Google Gemini API, Tavily Search API, Presidio + spaCy `en_core_web_md`).
+
+### 2. Description and rationale
+
+- **2.1 Detailed description:** A clinical note is passed through `deidentify_in` (rule recognisers + vault match + Presidio/spaCy NER), which raises if any known identifier survives (`assert_clean()`). The clean text reaches the LangGraph ReAct agent; Tavily retrieves public NICE/NHS guidance. The agent drafts a three-element compact discharge card (narrative, follow-up, grounded) and never names the patient — there is no title line and the patient is referred to only as "the patient". `reidentify_out` restores other surrogates (e.g. clinician names) for the clinician; the model never sees the real name. `compute_trust` audits the de-identified text for residual PII (`scan_pii`, vault-independent) and checks surrogate reversibility.
+- **2.2 Scope:** Free-text English NHS clinical notes. Evaluated on the `NHSEDataScience/synthetic_clinical_notes` dataset only. Not evaluated on real Trust data, other languages, or scanned documents.
+- **2.3 Benefit:** Enables clinicians to draft eDischarge summaries from de-identified notes with a *measured* re-identification risk rather than an unverified assurance; grounds the summary in public clinical guidance.
+- **2.4 Previous process:** Manual de-identification by an analyst, or free-text notes not shared at all because re-identification risk could not be quantified.
+- **2.5 Alternatives considered:** Presidio alone (misses NHS-specific formats); a clinical transformer (`obi/deid_roberta_i2b2` — US-trained, weaker on UK names); sending raw notes to the LLM (unacceptable PHI risk). Rejected in favour of the rules-first + LLM-second pipeline.
+
+### 3. Decision-making process
+
+- **3.1 Process integration:** Sits at the Trust egress boundary and inside the clinician workflow. The clinician **reviews and signs off** the draft before it becomes a medical record.
+- **3.2 Information provided to reviewers:** The clinician sees the re-identified summary, the trust panel (de-identification PASS/FAIL, identifiers replaced, residual PII the model saw, reversibility), and the de-identified excerpt showing what the AI saw.
+- **3.3 Frequency and scale:** Prototype, per-note on demand. No batch deployment.
+- **3.4 Human decisions and review:** The clinician makes the **final** call on every summary. The system explicitly labels the output as AI-drafted.
+- **3.5 Required training:** Clinicians need training on the tool's limitations (esp. name-recall bias for non-English names, synthetic-only evaluation), the residual-risk metric, and the escalation route for missed identifiers.
+- **3.6 Appeals / redress:** Not a citizen-facing decision system. Missed identifiers found post-review are corrected and fed back into the recogniser rules/tests.
+
+### 4. Tool specification
+
+- **4.1.1 System architecture:** Python package (`src/`) deployed as a FastAPI service and Streamlit demo. The LangGraph agent runs server-side; the clinician UI is a single-page web app. Raw notes and the re-identification vault stay Trust-local and are gitignored.
+- **4.1.2 Phase:** Prototype (hackathon) — not deployed to production.
+- **4.1.3 Maintenance:** CI (`ruff` + `pytest`) on every change; residual leakage acts as a regression gate; recognisers re-evaluated when data or rules change.
+- **4.1.4 Components:** (a) pure-Python rule recognisers (`src/deid.py`); (b) Presidio + spaCy `en_core_web_md` NER (deployed; graceful no-op fallback); (c) `scan_pii` residual-PII audit; (d) LangGraph ReAct agent with Gemini 2.5 Flash; (e) Tavily public-guidance search; (f) FastAPI clinician UI.
+
+**4.2 Component specifications**
+
+| Component | Task | Method | Notes |
+|---|---|---|---|
+| Rule recognisers | NHS number, DOB, postcode, GMC/NMC, email, phone | Regex + context anchors (name-agnostic) | `src/deid.py`; std-lib only |
+| Vault match | Patient/clinician names | Exact-match from patients.csv + admissions.csv | Deterministic; demographic-agnostic for structured entities |
+| Presidio NER | `PERSON`, `LOCATION` | spaCy `en_core_web_md` (`NOTEGUARD_SPACY_MODEL`), score-thresholded | Shipped in the deployed image; no-op fallback when absent |
+| Gemini 2.5 Flash | Discharge summary drafting | LangGraph ReAct; SYSTEM prompt enforces no-PHI rules and never names the patient | `NOTEGUARD_MODEL` env var |
+| Tavily | Public-guidance grounding | Public web search for NICE/NHS sources only | Patient text never sent |
+| assert_clean() | Hard de-id guarantee | Raises `ValueError` if any identifier survives | Cannot be weakened or bypassed |
+| compute_trust | De-id audit | `scan_pii` residual-PII scan (vault-independent) + orphaned-token / reversibility check | Surfaced in clinician UI |
+
+**4.3 Data specification**
+
+- **4.3.1 Source:** `NHSEDataScience/synthetic_clinical_notes` (Hugging Face, MIT licence).
+- **4.3.2 Modality:** Text (3 linked CSVs: patients, admissions, notes).
+- **4.3.3 Description:** Synthetic clinical notes joined to synthetic patient/admission records on `person_id`/`admission_id` — the join provides free ground truth for the leakage metric.
+- **4.3.4 Quantities:** ~70 patients, ~1,602 notes.
+- **4.3.5 Sensitive attributes:** Synthetic names, NHS numbers, DOBs, sites — treated as if real PHI throughout.
+- **4.3.6 Representativeness:** Fully synthetic; not representative of real Trust notes. Real validation required before deployment.
+- **4.3.7 Source URL:** https://huggingface.co/datasets/NHSEDataScience/synthetic_clinical_notes
+- **4.3.8 Cleaning:** Mojibake repair (`_fix_mojibake`); consistent date-shift for DOBs.
+- **4.3.9 Sharing:** Only de-identified text + content-free trust metrics are shareable. Raw data and the vault are gitignored and never committed.
+
+### 5. Risks, mitigations and impact assessments
+
+- **5.1 Impact assessment:** A **DPIA is required before any real deployment** and has **not** been done (prototype on synthetic data). IG/Caldicott sign-off and DARS approval also required.
+- **5.2 Risks and mitigations:**
+
+| Risk | Impact | Mitigation |
+|---|---|---|
+| False negative (missed PII) | Re-identification of a patient | Name-agnostic rule recognisers; vault from structured tables; assert_clean() hard gate; vault-independent residual-PII audit (`scan_pii`) surfaced to clinician |
+| **Name-recall bias** (non-English names) | Unequal re-identification risk across demographics | Rule recognisers are demographic-agnostic; vault provides deterministic coverage; **stratified recall evaluation required** before deployment |
+| LLM hallucination / fabrication | Clinically incorrect summary | Grounded-only SYSTEM prompt; clinician reviews and signs off every summary |
+| Tavily leaking patient text | PHI to public internet | SYSTEM prompt prohibition; assert_clean() runs before Tavily is ever called; trust metric monitors for policy violations |
+| Orphaned surrogate tokens | Model-invented `[LABEL_n]` not re-identifiable | `reidentify_out` detects and flags unmapped tokens; replaced with `[redacted]`; surfaced in leaked_tokens |
+| Vault compromise | Re-identification via the linkage key | Vault stays Trust-local; gitignored; treated as the re-identification key |
+| Pseudonymised ≠ anonymised (UK GDPR) | Mistaken belief data is non-personal | Stated honestly throughout; DPIA + IG sign-off required |
+
+---
+
+*NoteGuard · {Tech: Europe} London AI Hackathon · prototype · v0.2.0*

docs/tool_card.md

@@ -0,0 +1,123 @@
+# NoteGuard — Tool Card
+
+**Version:** 0.2.0
+**Track:** Public Sector & Citizen Services — NHS Secure Data Environment on-ramp
+**Status:** Hackathon prototype; not validated for production use without further evaluation.
+
+---
+
+## Specification
+
+| Field | Value |
+|---|---|
+| Description | De-identification gate + LangGraph agent that detects/removes PII from NHS clinical notes before any LLM sees them, then grounds a discharge summary in public NICE/NHS guidance |
+| Type | Hybrid pipeline — pure-Python rule recognisers + Microsoft Presidio (spaCy NER, `en_core_web_md`, shipped in the deployed image); Gemini 2.5 Flash as the agent model; Tavily for public-guidance retrieval |
+| Developer | Chaeyoon Kim — {Tech: Europe} London AI Hackathon |
+| Status / version | Prototype · v1.0.0 |
+| Repository | github.com/chaeyoonyunakim/noteguard-agent |
+
+> Documented as a **tool card**, not a model card. NoteGuard does not train a model.
+> A gov.uk Algorithmic Transparency Recording Standard (ATRS) record is in [`report.md`](report.md).
+
+---
+
+## What it does
+
+NoteGuard is a **trust layer** for clinical AI. It:
+
+1. **De-identifies** free-text NHS clinical notes inside the Trust using rule-based recognisers (NHS number, GMC/NMC, DOB, postcode, email, phone) and a Presidio + spaCy NER detector (`en_core_web_md`, shipped in the deployed image; degrades to a no-op stub if absent) that catches free-text patient/clinician names with no vault entry.
+2. **Asserts clean** — raises `ValueError` if any known identifier survives, hard-blocking the model boundary.
+3. Passes de-identified text to a **LangGraph ReAct agent** (Gemini 2.5 Flash) that drafts a compact eDischarge summary grounded in NICE/NHS guidance retrieved via Tavily.
+4. **Re-identifies** the summary for the clinician — the model never sees or writes a real name.
+5. **Audits the de-identification** — a vault-independent `scan_pii` pass flags any residual PII the model still saw (incl. free-text names the vault missed), plus orphaned surrogate tokens for reversibility. The trust panel reports only this; it carries no answer-quality metrics.
+
+> "De-identify in → agent (Gemini + Tavily) → re-identify out → compute trust."
+
+---
+
+## Who uses it
+
+| Role | When | Why |
+|---|---|---|
+| NHS Clinician | At discharge | Needs a draft summary without manually de-identifying notes |
+| Data Wrangler / IG Analyst | Before releasing notes to AI teams | Cannot share raw free-text; needs measured leakage |
+| SDE Operator | At Trust egress boundary | Gate between raw Trust data and a Secure Data Environment |
+
+---
+
+## Use cases out of scope
+
+- **Not** a substitute for Information Governance sign-off, a DPIA, or DARS approval — it is a technical control, not a legal basis for processing.
+- **Not** validated on real Trust data, non-English notes, or scanned/handwritten documents.
+- **Not** a guarantee of zero re-identification: pseudonymised output is still personal data under UK GDPR, and residual leakage is *measured*, not assumed zero on unseen data.
+- **Not** for clinical decision-making, autonomous prescribing, or any use of note content beyond de-identification and grounded summarisation.
+- **Not** a replacement for a clinician review — the output is a draft that the clinician signs off.
+
+---
+
+## Detection coverage
+
+| Entity type | Method | Notes |
+|---|---|---|
+| Patient / clinician name (`PERSON`) | Vault match (patients.csv + admissions.csv) + Presidio spaCy NER (`en_core_web_md`) | Vault is ground-truth; Presidio catches unlisted free-text names; `scan_pii` audits whatever still slips through |
+| NHS number (`NHS`) | Regex + 9-digit context anchor | Catches standard and synthetic-dataset forms |
+| Date of birth (`DOB`) | DOB regex + consistent date-shift | Shift preserves clinical plausibility |
+| UK postcode (`POSTCODE`) | Regex | Redacted outward-code only |
+| GMC number (`GMC`) | Context-anchored regex with connector words | "GMC No. 7654321", "GMC number 7654321" |
+| NMC / PIN (`NMC`) | Context-anchored regex with connector words | "NMC number: 18D6896L", "PIN 18D6896L" |
+| Email / phone | Regex | Standard patterns |
+
+---
+
+## Anonymisation policy
+
+| Mode | Behaviour |
+|---|---|
+| **Pseudonymise** (default) | Consistent surrogate tokens `[LABEL_n]`; DOB date-shifted; reidentify() restores originals for the clinician |
+| Patient naming | The discharge summary never names the patient — no title line, no real name, no patient surrogate; the model refers to "the patient" throughout |
+
+---
+
+## Bias and fairness
+
+The Presidio NER (spaCy `en_core_web_md`) is trained largely on Western/English text, so **name recall can be lower for names of non-English origin** — and a smaller model (`_md` vs `_lg`) trades some recall for image size. This is an equity risk: under-detection means those patients carry a *higher residual re-identification risk*. The `scan_pii` audit surfaces residual names to the clinician rather than hiding the gap. Honest position and mitigations:
+
+- The rule-based recognisers (NHS number, DOB, postcode, GMC/NMC) are **name-agnostic** and detect structured identifiers uniformly regardless of patient demographics.
+- The **vault** (from `patients.csv` + `admissions.csv`) provides deterministic, demographic-agnostic coverage for all names in the structured dataset.
+- **Required before deployment:** evaluate name recall *stratified by name origin* on representative Trust data and report the disparity. Not yet done — evaluation is on the `NHSEDataScience/synthetic_clinical_notes` synthetic dataset only.
+
+---
+
+## NHS Five Safes mapping
+
+| Safe | Status | How |
+|---|---|---|
+| **Safe data** | ✅ | De-identified before model; assert_clean() hard gate; leakage measured |
+| **Safe settings** | ✅ | Processing inside Trust; vault gitignored; Tavily receives only public queries |
+| **Safe outputs** | ✅ | Only de-identified text + content-free trust metrics leave model boundary |
+| **Safe people** | ⚠️ | Clinician reviews and signs off the draft; vault stays Trust-local |
+| **Safe projects** | ⚠️ | Technical layer only; DPIA + project approval (DARS) remain Trust processes |
+
+---
+
+## Limitations and caveats
+
+- **Pseudonymised data is still personal data** under UK GDPR — the surrogate vault is the re-identification key and must stay Trust-local.
+- **Not clinically validated:** evaluated on the `NHSEDataScience/synthetic_clinical_notes` dataset. Real deployment requires validation on representative Trust data.
+- **Tavily search** is for public NICE/NHS guidance only — patient text or surrogate tokens are never sent to it (enforced in the SYSTEM prompt and monitored via the trust metric).
+- **Governance prerequisites for deployment:** a Data Protection Impact Assessment (DPIA), IG/Caldicott sign-off, and DARS project approval are required before any real use. NoteGuard is the technical control, not the approval.
+
+---
+
+## Components
+
+| Component | Role in NoteGuard |
+|---|---|
+| **Google Gemini 2.5 Flash** | Agent model — drafts the eDischarge summary from de-identified text |
+| **Tavily** | Public-guidance search — NICE/NHS sources only; never receives patient text |
+| LangGraph | Agent orchestration |
+| LangSmith | Tracing and evaluation |
+
+---
+
+*NoteGuard · {Tech: Europe} London AI Hackathon · prototype · not for clinical use without further validation*

docs/user_guide.md

@@ -0,0 +1,147 @@
+# User guide
+
+## Prerequisites
+
+- Python 3.10 or later
+- A free [Google AI Studio API key](https://aistudio.google.com/apikey)
+- A [Tavily API key](https://tavily.com) (free tier available)
+- A [LangSmith API key](https://smith.langchain.com) (free tier available)
+
+## Installation
+
+```bash
+git clone https://github.com/chaeyoonyunakim/noteguard-agent.git
+cd noteguard-agent
+
+python -m venv .venv
+.venv\Scripts\activate          # Windows
+# source .venv/bin/activate     # macOS / Linux
+
+pip install -e ".[dev]"
+```
+
+To also install the Streamlit de-id demo:
+
+```bash
+pip install -e ".[demo]"       # Streamlit interactive demo
+```
+
+## Configuration
+
+```bash
+cp .env.example .env
+```
+
+Open `.env` and fill in your credentials:
+
+```env
+GOOGLE_API_KEY=AIza...
+TAVILY_API_KEY=tvly-...
+LANGSMITH_API_KEY=ls__...
+LANGSMITH_TRACING=true
+# NOTEGUARD_MODEL=google_genai:gemini-2.5-flash   # optional override
+```
+
+## Running the de-identification demo (no API keys needed)
+
+```bash
+python src/deid.py
+```
+
+Demonstrates the de-id core on a synthetic note — no network calls, no keys.
+
+## Running the interactive Streamlit demo (no API keys needed)
+
+```bash
+streamlit run streamlit_app.py
+```
+
+Lets you paste any text, click **De-identify**, and see the surrogate-token
+output alongside the vault contents and `assert_clean` result.
+
+## Downloading the dataset
+
+```bash
+python src/fetch_dataset.py
+```
+
+Downloads `patients.csv`, `admissions.csv`, and `synthetic_clinical_notes.csv`
+from the `NHSEDataScience/synthetic_clinical_notes` Hugging Face dataset into `data/`.
+Run once before starting the server to enable the note-picker and vault-based leakage metrics.
+
+## Running the clinician web UI (recommended for demos)
+
+```bash
+uvicorn app.api:app --reload --port 8000
+```
+
+Open [http://localhost:8000](http://localhost:8000).
+
+1. Click **Load note** (top-right) to open the note picker, or paste your own note.
+2. Click **Generate** (~20–30 s on first run; the model loads and de-identifies).
+3. Use the segmented toggle to switch views without re-calling the API:
+   - **Clinician view** — the original note with every redacted identifier highlighted in red.
+   - **What the AI sees** — the de-identified note; real identifiers are replaced by
+     `[TYPE_N]` surrogate chips (e.g. `[PERSON_1]`, `[NHS_1]`).
+4. The compact eDischarge card appears on the right, re-identified for the clinician.
+5. The trust panel below shows whether de-identification was done correctly — and
+   nothing about answer quality:
+   - **De-identification** — `PASS` only when nothing un-redacted reached the model
+     *and* every surrogate is reversible; `FAIL` otherwise.
+   - **Identifiers replaced** — count of PII spans pseudonymised in this call.
+   - **Residual PII · model input** — suspected un-redacted identifiers the model still
+     saw (`0` = clean). When > 0, the offending snippets are listed (e.g.
+     `name: Ethel Joanne Duffy`). This catches free-text names the vault/NER passes
+     missed — the case the old re-id-risk number was blind to.
+   - **Reversible** — `✓` when every surrogate restores to a real value; `✗` lists the
+     orphaned/unresolved tokens.
+6. Click **← Edit note** to reset and process a different note.
+
+## Running the LangGraph dev server
+
+```bash
+langgraph dev
+```
+
+Connect the [Agent Chat UI](https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024)
+and interact with the `noteguard` graph directly.
+
+## Running the LangSmith evaluations
+
+```bash
+python -m eval.run_eval
+```
+
+Needs `LANGSMITH_API_KEY` and `LANGSMITH_TRACING=true`. Runs two evaluators:
+
+| Evaluator | Target | What it measures |
+|---|---|---|
+| `zero_phi_to_model` | 1.0 | No known identifier appeared in any message seen by the model. |
+| `faithfulness` | 0.8+ | Every clinical claim in the answer is supported by the source note. |
+
+## Development
+
+```bash
+ruff check src agent app eval tests   # lint
+ruff format src agent app eval tests  # format
+pytest                                 # run the test suite
+pytest --cov=src --cov-report=term    # with coverage
+```
+
+## Loading a real patient vault
+
+The de-id core can be seeded from the
+[`NHSEDataScience/synthetic_clinical_notes`](https://huggingface.co/datasets/NHSEDataScience/synthetic_clinical_notes)
+dataset (MIT licence, fully synthetic):
+
+```python
+from src.deid import NoteGuard, load_known_from_csv
+
+known = load_known_from_csv("data/patients.csv", "data/admissions.csv")
+ng = NoteGuard(known=known)
+result = ng.deidentify(raw_note)
+ng.assert_clean(result.clean_text)
+```
+
+This builds the identifier vault from both structured tables — patient names and
+clinician names — so residual leakage is measured against ground truth.

eval/run_eval.py

@@ -0,0 +1,103 @@
+"""LangSmith evaluation for the NoteGuard agent slice.
+
+Two evaluators that map straight onto the judging story:
+  1. zero_phi_to_model  - the hard privacy guarantee (must be 1.0)
+  2. faithfulness       - LLM-as-judge: is every claim supported by the note?
+
+Run:  python -m eval.run_eval
+Needs: LANGSMITH_API_KEY, GOOGLE_API_KEY, TAVILY_API_KEY (+ LANGSMITH_TRACING=true)
+
+API note: the LangSmith evaluate surface has shifted across versions. This targets
+langsmith>=0.1 with dict-style evaluators (inputs/outputs). Adjust signatures if
+your installed version differs.
+"""
+
+from __future__ import annotations
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from langchain.chat_models import init_chat_model
+from langchain_core.messages import HumanMessage
+from langsmith import Client
+
+from agent.graph import build_graph
+from src.deid import NoteGuard
+
+KNOWN = {"PERSON": ["Margaret Okafor"], "NHS": ["485 777 3456"]}
+EXAMPLES = [
+    {
+        "note": (
+            "Ward 4B. Pt Margaret Okafor (NHS 485 777 3456, DOB 22/09/1958, F, 45 Elm Road SW1A 1AA). "
+            "GP: Dr James Obi, Riverside Surgery, Lambeth SE1 7PB. "
+            "Admitted 12 Jan 2025 via ED with acute exacerbation of COPD. "
+            "PMH: COPD (GOLD III), T2DM on metformin, hypertension on amlodipine. NKDA. "
+            "O2 sats 88% on air. Managed with nebulised salbutamol, ipratropium, IV hydrocortisone, "
+            "doxycycline. CXR: bilateral hyperinflation, no consolidation. WBC 11.2, CRP 78. "
+            "Discharged 14 Jan 2025. TTO: carbocisteine 375 mg TDS, prednisolone 30 mg OD 5/7, "
+            "doxycycline 100 mg OD 4/7. Metformin and amlodipine continued. "
+            "Consultant: Dr Sarah Chen, Respiratory Medicine."
+        ),
+        "question": "Draft an NHS eDischarge summary.",
+    },
+]
+
+client = Client()
+_judge = None
+
+
+def _content_str(content) -> str:
+    """Flatten AIMessage content — Gemini returns a list of blocks, not a plain string."""
+    if isinstance(content, list):
+        return " ".join(b.get("text", "") if isinstance(b, dict) else str(b) for b in content)
+    return content or ""
+
+
+def target(inputs: dict) -> dict:
+    graph = build_graph(known=KNOWN)
+    state = graph.invoke(
+        {"messages": [HumanMessage(content=inputs["note"] + "\n\n" + inputs["question"])]},
+    )
+    model_facing = " ".join(_content_str(getattr(m, "content", "")) for m in state["messages"])
+    return {"clinician_answer": state.get("clinician_answer", ""), "model_facing": model_facing}
+
+
+def zero_phi_to_model(inputs: dict, outputs: dict) -> dict:
+    hits = NoteGuard(known=KNOWN).residual_identifiers(outputs["model_facing"])
+    return {"key": "zero_phi_to_model", "score": 1.0 if not hits else 0.0}
+
+
+def faithfulness(inputs: dict, outputs: dict) -> dict:
+    global _judge
+    _judge = _judge or init_chat_model("google_genai:gemini-2.5-flash")
+    prompt = (
+        f"NOTE:\n{inputs['note']}\n\nSUMMARY:\n{outputs['clinician_answer']}\n\n"
+        "Is every clinical claim in SUMMARY supported by NOTE? "
+        "Reply with a single number between 0 and 1."
+    )
+    raw = _content_str(_judge.invoke(prompt).content)
+    try:
+        score = max(0.0, min(1.0, float(raw.strip().split()[0])))
+    except (ValueError, IndexError):
+        score = 0.0
+    return {"key": "faithfulness", "score": score}
+
+
+if __name__ == "__main__":
+    dataset_name = "noteguard-discharge-eval"
+    try:
+        dataset = client.create_dataset(dataset_name)
+        client.create_examples(
+            dataset_id=dataset.id,
+            inputs=[{"note": e["note"], "question": e["question"]} for e in EXAMPLES],
+        )
+    except Exception:
+        pass  # dataset already exists from a previous run
+
+    client.evaluate(
+        target,
+        data=dataset_name,
+        evaluators=[zero_phi_to_model, faithfulness],
+        experiment_prefix="noteguard-slice",
+    )

langgraph.json

@@ -0,0 +1,7 @@
+{
+  "dependencies": ["."],
+  "graphs": {
+    "noteguard": "./agent/graph.py:graph"
+  },
+  "env": ".env"
+}

pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "noteguard-agent"
+version = "1.2.4"
+description = "Trust layer for clinical AI — de-identifies NHS notes before LLM sees them."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Chaeyoon Kim" }]
+keywords = ["nhs", "de-identification", "phi", "langgraph", "gemini", "rap"]
+dependencies = [
+    "fastapi>=0.109.0",
+    "uvicorn[standard]>=0.27.0",
+    "langgraph>=0.2.0",
+    "langchain>=0.3.0",
+    "langchain-google-genai>=2.0.0",
+    "langchain-tavily>=0.1.0",
+    "langsmith>=0.1.0",
+    "python-dotenv>=1.0.0",
+    "huggingface_hub>=0.20.0",
+]
+
+[project.optional-dependencies]
+# pip install -e ".[nlp]"        — Presidio + spaCy NER for free-text PERSON/LOCATION.
+# Also needs a spaCy model:  python -m spacy download en_core_web_md
+nlp = ["presidio-analyzer>=2.2.0", "spacy>=3.7.0,<4"]
+# pip install -e ".[demo]"       — Streamlit interactive demo
+demo = ["streamlit>=1.35.0"]
+# pip install -e ".[dev]"        — full dev tooling incl. langgraph dev server
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.1.0",
+    "ruff>=0.3.0",
+    "pre-commit>=3.6.0",
+    "langgraph-cli[inmem]>=0.4.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/chaeyoonyunakim/noteguard-agent"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["src*", "agent*", "app*", "eval*"]
+
+[tool.ruff]
+line-length = 110
+target-version = "py310"
+src = ["src", "agent", "app", "eval", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "W"]
+ignore = ["B008"]
+
+[tool.ruff.lint.per-file-ignores]
+"agent/graph.py" = ["E402"]
+"app/api.py" = ["E402"]
+"eval/run_eval.py" = ["E402", "I001"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

src/__init__.py

@@ -0,0 +1,3 @@
+from .deid import DeidResult, NoteGuard, load_known_from_csv
+
+__all__ = ["NoteGuard", "DeidResult", "load_known_from_csv"]

src/deid.py

@@ -0,0 +1,433 @@
+"""NoteGuard de-identification core.
+
+Dependency-free and runnable on its own (`python noteguard/deid.py`).
+If `presidio-analyzer` + a spaCy model are installed the module upgrades
+free-text PERSON/LOCATION detection automatically; the rule + vault layer
+below always runs without them.
+
+Design:
+- NHS-aware recognisers (NHS number, GMC/NMC, postcode, DOB, email, phone)
+- vault of known identifiers from patients.csv + admissions.csv so redaction
+  is exact AND measurable
+- patient-consistent surrogates (same original → same token across notes)
+- DOB date-shift (kept clinically plausible); other identifiers tokenised
+- reidentify() restores originals for the CLINICIAN's eyes only
+- assert_clean() is the hard guarantee that no identifier reaches the model
+"""
+
+from __future__ import annotations
+
+import csv
+import os
+import re
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+
+NHS_NUMBER = re.compile(r"\b\d{3}[ -]?\d{3}[ -]?\d{4}\b")
+NHS_CONTEXT = re.compile(r"(?i)\bNHS(?:\s*(?:no\.?|number|#))?[:\s]*([0-9][0-9 \-]{6,12}\d)")
+UK_POSTCODE = re.compile(r"\b([A-Z]{1,2}\d[A-Z\d]? ?\d[A-Z]{2})\b")
+DOB = re.compile(r"\b(\d{1,2}[/\-.]\d{1,2}[/\-.]\d{2,4})\b")
+EMAIL = re.compile(r"\b[\w.+-]+@[\w-]+\.[\w.-]+\b")
+PHONE = re.compile(r"\b0\d{2,3}[ -]?\d{3,4}[ -]?\d{3,4}\b")
+
+# GMC/NMC: optional connector word then optional colon/spaces before the ID
+# Handles: "GMC No. 7654321", "NMC number: 18D6896L", "PIN 18D6896L", etc.
+_CONN = r"(?:\s*(?:no\.?|number|reg(?:istration)?|pin|#))?[:\s]*"
+GMC = re.compile(r"(?i)\bGMC" + _CONN + r"(\d{7})\b")
+NMC = re.compile(r"(?i)\b(?:NMC|PIN)" + _CONN + r"(\d{2}[A-Z]\d{4}[A-Z])\b")
+
+# Surrogate token pattern — catches any [LABEL_n] the model might invent
+_SURROGATE_PAT = re.compile(r"\[[A-Z]+_\d+\]")
+
+# Broader surrogate-shaped pattern: [LABEL_<anything>]. Catches both [LABEL_n] and
+# stray template placeholders the model may echo from the system prompt (e.g.
+# [DATE_X]), so none reach the clinician verbatim. Used by redact_unresolved().
+_ORPHAN_PAT = re.compile(r"\[[A-Z]+_[A-Za-z0-9]+\]")
+
+# Person-title prefixes that almost always precede a real name. Used by the
+# trust-panel audit (scan_pii) to flag free-text names that slipped past the
+# vault / NER passes — e.g. "Dr Ethel Joanne Duffy", "Nurse Jasmine Freda Murray".
+# Requires >= 2 Title-Case tokens after the title so role words ("Nurse
+# Practitioner", "Consultant Cardiologist") do not false-positive, and a correctly
+# tokenised name ("Dr [PERSON_1]") never matches because "[" is not a letter.
+_PERSON_TITLE = (
+    r"(?:Dr|Doctor|Mr|Mrs|Ms|Miss|Prof|Professor|Nurse|Sister|Matron|Midwife|Sir|Dame|Consultant|GP)"
+)
+_NAME_AFTER_TITLE = re.compile(r"\b" + _PERSON_TITLE + r"\b[.,:]?\s+([A-Z][a-z]+(?:\s+[A-Z][a-z]+){1,3})")
+
+# Column names we look for in any CSV to extract person names
+_NAME_COLS = frozenset(
+    {
+        "full_name",
+        "patient_name",
+        "first_name",
+        "surname",
+        "last_name",
+        "clinician_name",
+        "author_name",
+        "author",
+        "attending",
+        "attending_physician",
+        "nurse",
+        "consultant",
+        "doctor",
+        "provider",
+    }
+)
+
+
+# ── Optional NLP detector (Presidio + spaCy) ─────────────────────────────────
+
+# Clinical terms/abbreviations that the small spaCy model (en_core_web_md) often
+# mislabels as PERSON/LOCATION. They are never redacted as names even when the NER
+# layer flags them — over-redaction like "Subcut" -> [PERSON_3] is wrong and noisy.
+# Compared case-insensitively; keep to terms that are not plausible real names.
+_NER_STOPWORDS = frozenset(
+    {
+        "subcut",
+        "subcutaneous",
+        "obs",
+        "sats",
+        "spo2",
+        "nad",
+        "nbm",
+        "nkda",
+        "prn",
+        "stat",
+        "mane",
+        "nocte",
+        "neuro",
+        "resp",
+        "cvs",
+        "abdo",
+        "perrla",
+        "gcs",
+        "afebrile",
+        "apyrexial",
+        "euvolaemic",
+        "normotensive",
+        "tachycardic",
+        "bradycardic",
+        "pyrexial",
+        "bibasal",
+        "pneumomediastinum",
+    }
+)
+
+
+class _Detector:
+    """Stub detector — no-op when Presidio/spaCy is not installed."""
+
+    def detect_persons(self, text: str) -> list[str]:
+        return []
+
+
+def _build_detector() -> _Detector:
+    """Upgrade free-text PERSON/LOCATION detection to Presidio + spaCy when
+    available; otherwise return a no-op stub so the rule + vault layer still runs.
+
+    The spaCy model is configurable via ``NOTEGUARD_SPACY_MODEL`` (default
+    ``en_core_web_md`` — small enough to ship in the Docker image, materially
+    better recall than ``_sm``; set ``_lg`` for best recall at ~14x the size).
+    Any import or engine-setup failure degrades gracefully to the stub: NER is a
+    recall boost over the rules + vault, never a hard dependency.
+    """
+    try:
+        from presidio_analyzer import AnalyzerEngine  # type: ignore
+        from presidio_analyzer.nlp_engine import NlpEngineProvider  # type: ignore
+
+        model = os.getenv("NOTEGUARD_SPACY_MODEL", "en_core_web_md")
+        provider = NlpEngineProvider(
+            nlp_configuration={
+                "nlp_engine_name": "spacy",
+                "models": [{"lang_code": "en", "model_name": model}],
+            }
+        )
+        engine = AnalyzerEngine(nlp_engine=provider.create_engine(), supported_languages=["en"])
+
+        class _PresidioDetector(_Detector):
+            def detect_persons(self, text: str) -> list[str]:
+                results = engine.analyze(text, language="en", entities=["PERSON", "LOCATION"])
+                return [text[r.start : r.end] for r in results if r.end > r.start]
+
+        return _PresidioDetector()
+    except Exception:
+        return _Detector()
+
+
+_DETECTOR: _Detector = _build_detector()
+
+
+# ── Vault loader ──────────────────────────────────────────────────────────────
+
+
+def load_known_from_csv(patients_csv: str, admissions_csv: str | None = None) -> dict:
+    """Build the identifier vault from the synthetic dataset's structured tables.
+
+    Reads ``full_name`` and common name columns from *patients_csv*, plus NHS
+    numbers.  If *admissions_csv* is supplied, any clinician/author name columns
+    found there are added to the PERSON set so clinician names are caught
+    deterministically even without Presidio.
+    """
+    known: dict[str, set] = {"PERSON": set(), "NHS": set()}
+
+    def _pull_row(row: dict) -> None:
+        for col in _NAME_COLS:
+            v = (row.get(col) or "").strip()
+            if len(v) > 2:
+                known["PERSON"].add(v)
+
+    with open(patients_csv, newline="", encoding="utf-8-sig") as f:
+        for row in csv.DictReader(f):
+            _pull_row(row)
+            nhs = (row.get("nhs_number") or "").strip()
+            if nhs:
+                known["NHS"].add(nhs)
+
+    if admissions_csv:
+        try:
+            with open(admissions_csv, newline="", encoding="utf-8-sig") as f:
+                for row in csv.DictReader(f):
+                    _pull_row(row)
+        except FileNotFoundError:
+            pass
+
+    return {k: sorted(v) for k, v in known.items()}
+
+
+# ── Core de-identification ────────────────────────────────────────────────────
+
+
+@dataclass
+class DeidResult:
+    clean_text: str
+    forward: dict
+    reverse: dict
+    residual: list
+
+
+class NoteGuard:
+    def __init__(self, known=None, dob_shift_days=37, forward=None, reverse=None):
+        self.known = {k: list(v) for k, v in (known or {}).items()}
+        self.dob_shift = dob_shift_days
+        self.forward = dict(forward or {})
+        self.reverse = dict(reverse or {})
+        self._counter: dict[str, int] = {}
+        for tok in self.reverse:
+            m = re.match(r"\[([A-Z]+)_(\d+)\]", tok)
+            if m:
+                self._counter[m.group(1)] = max(self._counter.get(m.group(1), 0), int(m.group(2)))
+
+    @staticmethod
+    def _fix_mojibake(s: str) -> str:
+        # Each pair: (UTF-8 bytes of the real char decoded as Windows-1252, real char)
+        # ·  = · → ·  (middle dot U+00B7)
+        # ’ = ’ → '  (right single quote U+2019)
+        # – = â€" → –  (en-dash U+2013; 0x93 in Win-1252 = U+201C)
+        # é = é → é  (e-acute U+00E9)
+        return s.replace("·", "·").replace("’", "’").replace("–", "–").replace("é", "é")
+
+    def _surrogate(self, label: str, original: str) -> str:
+        if original in self.forward:
+            return self.forward[original]
+        self._counter[label] = self._counter.get(label, 0) + 1
+        tok = f"[{label}_{self._counter[label]}]"
+        self.forward[original] = tok
+        self.reverse[tok] = original
+        return tok
+
+    def _shift_date(self, s: str) -> str:
+        if s in self.forward:
+            return self.forward[s]
+        for fmt in ("%d/%m/%Y", "%d/%m/%y", "%d-%m-%Y", "%Y-%m-%d", "%d.%m.%Y"):
+            try:
+                shifted = (datetime.strptime(s, fmt) + timedelta(days=self.dob_shift)).strftime(fmt)
+                self.forward[s] = shifted
+                self.reverse[shifted] = s
+                return shifted
+            except ValueError:
+                continue
+        return self._surrogate("DATE", s)
+
+    def _redact(self, pattern, label, text, group=0, transform=None):
+        def repl(m):
+            original = m.group(group)
+            surr = transform(original) if transform else self._surrogate(label, original)
+            return m.group(0).replace(original, surr)
+
+        return pattern.sub(repl, text)
+
+    def deidentify(self, text: str) -> DeidResult:
+        t = self._fix_mojibake(text)
+
+        # Vault pass — patient names + NHS numbers from structured tables
+        for label in ("PERSON", "NHS"):
+            terms = [x for x in self.known.get(label, []) if x]
+            if terms:
+                alternatives = "|".join(re.escape(x) for x in sorted(terms, key=len, reverse=True))
+                pat = re.compile(r"\b(" + alternatives + r")\b")
+                t = self._redact(pat, label, t, group=1)
+
+        # Rule-based recognisers
+        t = self._redact(NHS_CONTEXT, "NHS", t, group=1)
+        t = self._redact(NHS_NUMBER, "NHS", t, group=0)
+        t = self._redact(GMC, "GMC", t, group=1)
+        t = self._redact(NMC, "NMC", t, group=1)
+        t = self._redact(EMAIL, "EMAIL", t, group=0)
+        t = self._redact(PHONE, "PHONE", t, group=0)
+        t = self._redact(UK_POSTCODE, "POSTCODE", t, group=1)
+        t = self._redact(DOB, "DOB", t, group=1, transform=self._shift_date)
+
+        # Optional NLP pass — catches clinician names and locations not in vault
+        for name in self._detect_names(t):
+            if name not in self.forward:
+                t = t.replace(name, self._surrogate("PERSON", name))
+
+        return DeidResult(t, dict(self.forward), dict(self.reverse), self._residual_known(t))
+
+    @staticmethod
+    def _detect_names(text: str) -> list[str]:
+        """NER-detected person/location names, minus clinical-term false positives.
+
+        Filters the raw detector output so abbreviations the small spaCy model
+        mislabels (e.g. "Subcut") are not treated as names.
+        """
+        return [
+            n for n in _DETECTOR.detect_persons(text) if n and len(n) > 2 and n.lower() not in _NER_STOPWORDS
+        ]
+
+    def _residual_known(self, text: str) -> list:
+        # Use word-boundary match, same as the deidentify vault pass, so that
+        # short names like "Dia" don't false-positive on "Diastolic"/"Diabetes".
+        return [
+            v
+            for vals in self.known.values()
+            for v in vals
+            if v and re.search(r"\b" + re.escape(v) + r"\b", text)
+        ]
+
+    def residual_identifiers(self, text: str) -> list[str]:
+        """Comprehensive leak check — used for the trust metric.
+
+        Covers:
+        - vault names that survived de-id
+        - regex patterns (NHS, email, GMC, NMC)
+        - orphaned surrogate tokens (invented by the model, no reverse mapping)
+        - NLP-detected persons/locations (when Presidio is installed)
+        """
+        hits: list[str] = list(self._residual_known(text))
+
+        for pat in (NHS_CONTEXT, NHS_NUMBER, EMAIL, GMC, NMC):
+            if pat.search(text):
+                hits.append(f"pattern:{pat.pattern[:40]}")
+
+        # Orphaned surrogates: a [LABEL_n] in the text with no reverse mapping
+        # means the model invented a token we cannot restore — it's a leak.
+        for m in _SURROGATE_PAT.finditer(text):
+            tok = m.group(0)
+            if tok not in self.reverse:
+                hits.append(f"unmapped_token:{tok}")
+
+        # NLP pass (no-op when Presidio not installed)
+        for name in self._detect_names(text):
+            hits.append(f"PERSON:{name[:30]}")
+
+        return list(dict.fromkeys(hits))  # deduplicate, preserve order
+
+    def scan_pii(self, text: str) -> list[dict]:
+        """Vault-independent audit of a *de-identified* text for residual PII.
+
+        ``assert_clean``/``residual_identifiers`` only know the vault and
+        structured patterns, so a free-text name that was never in the vault
+        (with no Presidio installed) passes them silently — exactly the failure
+        where "Dr Ethel Joanne Duffy" reaches the model un-redacted. This adds a
+        high-precision person-title heuristic so the trust panel can report
+        whether de-identification actually succeeded, even on a pasted note with
+        no ground-truth vault.
+
+        Returns a de-duplicated list of ``{"type": str, "text": str}`` findings,
+        each a span of suspected un-redacted PII still visible to the model.
+        Surrogate tokens (``[PERSON_1]``) are never flagged. Shifted dates are
+        intentional, so dates are out of scope here.
+        """
+        findings: list[dict] = []
+        spans: list[tuple[int, int]] = []
+
+        def _add(typ: str, start: int, end: int) -> None:
+            if start < 0 or any(start < pe and ps < end for ps, pe in spans):
+                return  # invalid, or overlaps an earlier (higher-priority) finding
+            spans.append((start, end))
+            findings.append({"type": typ, "text": text[start:end]})
+
+        # 1. structured identifiers that should have been tokenised but survived
+        for typ, pat, grp in (
+            ("NHS number", NHS_CONTEXT, 1),
+            ("NHS number", NHS_NUMBER, 0),
+            ("GMC", GMC, 1),
+            ("NMC", NMC, 1),
+            ("email", EMAIL, 0),
+            ("phone", PHONE, 0),
+            ("postcode", UK_POSTCODE, 1),
+        ):
+            for m in pat.finditer(text):
+                _add(typ, m.start(grp), m.end(grp))
+
+        # 2. free-text person names the vault/NER passes missed (title heuristic)
+        for m in _NAME_AFTER_TITLE.finditer(text):
+            _add("name", m.start(1), m.end(1))
+
+        # 3. vault names that survived de-id (when a ground-truth vault is loaded)
+        for v in self._residual_known(text):
+            idx = text.find(v)
+            _add("name", idx, idx + len(v))
+
+        return findings
+
+    def assert_clean(self, text: str) -> None:
+        """Hard guarantee: raises if any known identifier or regex pattern survives."""
+        hits = list(self._residual_known(text))
+        for pat in (NHS_CONTEXT, NHS_NUMBER, EMAIL, GMC, NMC):
+            if pat.search(text):
+                hits.append(pat.pattern[:40])
+        if hits:
+            raise ValueError(f"NoteGuard guarantee failed: identifiers reached the model boundary: {hits}")
+
+    def reidentify(self, text: str) -> str:
+        for tok, original in sorted(self.reverse.items(), key=lambda kv: len(kv[0]), reverse=True):
+            text = text.replace(tok, original)
+        return text
+
+    def redact_unresolved(self, text: str) -> tuple[str, list[str]]:
+        """Redact any surrogate-shaped token still present after ``reidentify()``.
+
+        Catches both unrestored surrogates (a ``[PERSON_9]`` with no reverse entry)
+        and stray template placeholders the model echoes from the prompt (e.g.
+        ``[DATE_X]``) — neither must ever reach the clinician verbatim. Returns the
+        cleaned text and the tokens that were redacted (a reversibility-leak signal).
+        """
+        leaked: list[str] = []
+
+        def _r(m: re.Match) -> str:
+            leaked.append(m.group(0))
+            return "[redacted]"
+
+        return _ORPHAN_PAT.sub(_r, text), leaked
+
+
+if __name__ == "__main__":
+    known = {"PERSON": ["Margaret Okafor"], "NHS": ["485 777 3456"]}
+    note = (
+        "02 Jan, Ward RJ1. Pt Margaret Okafor (NHS 485 777 3456, DOB 14/03/1934) "
+        "admitted post-fall. Nurse Chukwuebuka reviewed. "
+        "Contact a.okafor@example.com, 020 7946 0991. "
+        "GMC No. 7654321. NMC number: 18D6896L."
+    )
+    print("INPUT:\n", note, "\n")
+    ng = NoteGuard(known=known)
+    res = ng.deidentify(note)
+    print("DE-IDENTIFIED (what the model sees):\n", res.clean_text, "\n")
+    print("Residual identifiers:", res.residual)
+    ng.assert_clean(res.clean_text)
+    print("assert_clean: OK\n")
+    restored = NoteGuard(reverse=res.reverse).reidentify(res.clean_text)
+    print("RE-IDENTIFIED (clinician view only):\n", restored)

src/fetch_dataset.py

@@ -0,0 +1,41 @@
+"""Download NHSEDataScience/synthetic_clinical_notes (Silver tier) to data/.
+
+Usage:
+    python src/fetch_dataset.py
+
+Downloads three CSVs into ./data/:
+    synthetic_clinical_notes.csv  patients.csv  admissions.csv
+
+Run once before starting the server to enable /samples and /sample/* endpoints.
+Requires:  huggingface_hub  (pip install huggingface_hub)
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+DATA_DIR = Path(__file__).parent.parent / "data"
+REPO_ID = "NHSEDataScience/synthetic_clinical_notes"
+SILVER_FILES = [
+    "silver/synthetic_clinical_notes.csv",
+    "silver/patients.csv",
+    "silver/admissions.csv",
+]
+
+
+def fetch() -> None:
+    from huggingface_hub import hf_hub_download
+
+    DATA_DIR.mkdir(exist_ok=True)
+    for remote_path in SILVER_FILES:
+        dest = DATA_DIR / Path(remote_path).name
+        print(f"  {remote_path} ...", end=" ", flush=True)
+        cached = hf_hub_download(repo_id=REPO_ID, filename=remote_path, repo_type="dataset")
+        shutil.copy(cached, dest)
+        print(f"-> {dest.name}")
+    print(f"\nDone. Files in {DATA_DIR}/")
+
+
+if __name__ == "__main__":
+    fetch()

streamlit_app.py

@@ -0,0 +1,77 @@
+"""NoteGuard — interactive de-identification demo (Streamlit).
+
+Run: streamlit run streamlit_app.py
+No API keys required — uses the pure-Python rule layer only.
+"""
+
+from __future__ import annotations
+
+import streamlit as st
+from src.deid import NoteGuard
+
+st.set_page_config(page_title="NoteGuard demo", page_icon=":lock:", layout="wide")
+
+st.title("NoteGuard — NHS clinical-note de-identification")
+st.caption(
+    "Trust layer for clinical AI · "
+    "Pseudonymises free-text before any LLM sees it · "
+    "Pure-Python rule layer (no API key needed for this demo)"
+)
+
+BUILT_IN = (
+    "02 Jan 2025, Ward RJ1.\n"
+    "Pt Margaret Okafor (NHS 485 777 3456, DOB 14/03/1934, F).\n"
+    "GP: Dr James Obi, Riverside Surgery SE1 7PB.\n"
+    "Admitted post-fall. Hx: AF on warfarin, T2DM on metformin.\n"
+    "Nurse Chukwuebuka Okafor reviewed at triage, NMC number: 18D6896L.\n"
+    "Consultant: Dr Sarah Chen, GMC No. 7654321.\n"
+    "Contact: a.okafor@nhs.net · 020 7946 0991."
+)
+
+col_in, col_out = st.columns(2)
+
+with col_in:
+    st.subheader("Clinical note (input)")
+    note = st.text_area(
+        "Paste or edit a clinical note:", value=BUILT_IN, height=300, label_visibility="collapsed"
+    )
+    known_names = st.text_input(
+        "Known patient/clinician names (comma-separated, optional):",
+        placeholder="e.g. Margaret Okafor, Chukwuebuka Okafor",
+    )
+
+run = st.button("De-identify", type="primary")
+
+if run and note.strip():
+    known: dict = {"PERSON": [], "NHS": []}
+    if known_names.strip():
+        known["PERSON"] = [n.strip() for n in known_names.split(",") if n.strip()]
+
+    ng = NoteGuard(known=known)
+    result = ng.deidentify(note)
+
+    with col_out:
+        st.subheader("De-identified text (what the AI sees)")
+        st.code(result.clean_text, language=None)
+
+    st.divider()
+    col_m1, col_m2, col_m3 = st.columns(3)
+    col_m1.metric("Identifiers removed", len(result.forward))
+    col_m2.metric("Residual (known vault)", len(result.residual))
+    col_m3.metric("Re-ID risk", "0.0%" if not result.residual else f"{len(result.residual)} found")
+
+    if result.forward:
+        with st.expander("Surrogate mapping (clinician eyes only — never sent to model)"):
+            st.table(
+                [
+                    {"original": k, "surrogate": v}
+                    for k, v in sorted(result.forward.items(), key=lambda kv: kv[1])
+                ]
+            )
+
+    if result.residual:
+        st.error(f"Residual identifiers detected: {result.residual}")
+    else:
+        st.success("assert_clean passed — no known identifier reached the model boundary.")
+elif run:
+    st.warning("Please enter a note to de-identify.")

tests/test_deid.py

@@ -0,0 +1,340 @@
+"""Unit tests for noteguard.deid.
+
+All tests use the standard-library-only de-id core — no external services,
+no API keys, no network calls required. Safe to run in CI.
+"""
+
+from __future__ import annotations
+
+import pytest
+from src.deid import NoteGuard, load_known_from_csv
+
+KNOWN = {"PERSON": ["Margaret Okafor"], "NHS": ["485 777 3456"]}
+
+
+def _ng() -> NoteGuard:
+    return NoteGuard(known=KNOWN)
+
+
+@pytest.fixture(autouse=True)
+def _no_ner(monkeypatch):
+    """Pin the rule/vault layer for unit tests.
+
+    Presidio NER is an optional recall boost (the ``[nlp]`` extra). Tests must be
+    deterministic whether or not it is installed, so default every test to the
+    no-op detector; the NER-path test injects its own fake on top.
+    """
+    import src.deid as deid
+
+    monkeypatch.setattr(deid, "_DETECTOR", deid._Detector())
+
+
+# ── deidentify ────────────────────────────────────────────────────────────────
+
+
+def test_nhs_number_replaced():
+    ng = _ng()
+    result = ng.deidentify("Patient NHS 485 777 3456 admitted.")
+    assert "485 777 3456" not in result.clean_text
+    assert "[NHS_" in result.clean_text
+
+
+def test_person_name_replaced():
+    ng = _ng()
+    result = ng.deidentify("Pt Margaret Okafor discharged home.")
+    assert "Margaret Okafor" not in result.clean_text
+    assert "[PERSON_" in result.clean_text
+
+
+def test_email_replaced():
+    ng = _ng()
+    result = ng.deidentify("Contact a.okafor@nhs.net for follow-up.")
+    assert "@" not in result.clean_text
+
+
+def test_dob_replaced():
+    ng = _ng()
+    result = ng.deidentify("DOB 14/03/1934, admitted post-fall.")
+    assert "14/03/1934" not in result.clean_text
+
+
+def test_gmc_replaced():
+    ng = _ng()
+    result = ng.deidentify("Referring clinician GMC 1234567.")
+    assert "1234567" not in result.clean_text
+
+
+def test_clean_text_passes_through_unchanged():
+    ng = _ng()
+    note = "Patient admitted post-fall. Hx AF, on warfarin. BP 128/74."
+    result = ng.deidentify(note)
+    assert result.clean_text == note
+
+
+# ── GMC / NMC connector-word variants ────────────────────────────────────────
+
+
+def test_gmc_with_connector_no():
+    ng = _ng()
+    res = ng.deidentify("Referring clinician GMC No. 7654321.")
+    assert "7654321" not in res.clean_text
+    assert "[GMC_" in res.clean_text
+
+
+def test_gmc_with_connector_number():
+    ng = _ng()
+    res = ng.deidentify("GMC number 7654321 on record.")
+    assert "7654321" not in res.clean_text
+
+
+def test_nmc_with_connector_number_colon():
+    ng = _ng()
+    res = ng.deidentify("Nurse Chukwuebuka Okafor, NMC number: 18D6896L")
+    assert "18D6896L" not in res.clean_text
+    assert "[NMC_" in res.clean_text
+
+
+def test_nmc_with_pin():
+    ng = _ng()
+    res = ng.deidentify("Registered nurse PIN 18D6896L.")
+    assert "18D6896L" not in res.clean_text
+
+
+def test_nmc_bare():
+    ng = _ng()
+    res = ng.deidentify("NMC 18D6896L confirmed.")
+    assert "18D6896L" not in res.clean_text
+
+
+# ── Clinician name detection (via expanded vault) ─────────────────────────────
+
+
+def test_clinician_name_via_vault():
+    """Clinician names added to the vault are redacted deterministically."""
+    known = {"PERSON": ["Chukwuebuka Okafor", "Margaret Okafor"], "NHS": []}
+    ng = NoteGuard(known=known)
+    res = ng.deidentify("Nurse Chukwuebuka Okafor assessed the patient.")
+    assert "Chukwuebuka Okafor" not in res.clean_text
+    assert "[PERSON_" in res.clean_text
+
+
+def test_full_clinician_nmc_note():
+    """Combined: nurse name in vault + NMC number with connector word."""
+    known = {"PERSON": ["Chukwuebuka Okafor"], "NHS": []}
+    ng = NoteGuard(known=known)
+    note = "Patient assessed at triage by Nurse Chukwuebuka Okafor, NMC number: 18D6896L"
+    res = ng.deidentify(note)
+    assert "Chukwuebuka Okafor" not in res.clean_text
+    assert "18D6896L" not in res.clean_text
+    ng.assert_clean(res.clean_text)
+
+
+# ── assert_clean ──────────────────────────────────────────────────────────────
+
+
+def test_assert_clean_passes_on_safe_text():
+    ng = _ng()
+    ng.assert_clean("Admitted post-fall. Hx AF. INR 2.4.")  # must not raise
+
+
+def test_assert_clean_raises_on_nhs_number():
+    ng = _ng()
+    with pytest.raises(ValueError, match="485 777 3456"):
+        ng.assert_clean("NHS 485 777 3456 still present.")
+
+
+def test_assert_clean_raises_on_known_name():
+    ng = _ng()
+    with pytest.raises(ValueError, match="Margaret Okafor"):
+        ng.assert_clean("Patient Margaret Okafor discharged.")
+
+
+def test_assert_clean_raises_on_nmc():
+    ng = _ng()
+    with pytest.raises(ValueError):
+        ng.assert_clean("NMC number: 18D6896L not redacted.")
+
+
+# ── residual_identifiers (trust metric) ───────────────────────────────────────
+
+
+def test_residual_identifiers_catches_orphaned_token():
+    """A [LABEL_n] token with no reverse mapping is an unmapped-token leak."""
+    ng = NoteGuard(known={}, reverse={"[PERSON_1]": "Real Name"})
+    text = "Summary for [PERSON_1] and [PERSON_2]."  # PERSON_2 has no mapping
+    hits = ng.residual_identifiers(text)
+    assert any("unmapped_token" in h for h in hits)
+    # PERSON_1 is mapped — should NOT appear as orphaned
+    assert not any("PERSON_1" in h for h in hits)
+
+
+def test_residual_identifiers_catches_nmc():
+    ng = _ng()
+    hits = ng.residual_identifiers("Nurse PIN 18D6896L still present.")
+    assert any(h for h in hits)  # something was found
+
+
+# ── reidentify ────────────────────────────────────────────────────────────────
+
+
+def test_reidentify_restores_surrogate():
+    ng = _ng()
+    result = ng.deidentify("Pt Margaret Okafor (NHS 485 777 3456) admitted.")
+    restored = ng.reidentify(result.clean_text)
+    assert "Margaret Okafor" in restored
+    assert "485 777 3456" in restored
+
+
+def test_reidentify_consistent_surrogates():
+    """Same original -> same surrogate across multiple notes."""
+    ng = _ng()
+    r1 = ng.deidentify("Note 1: Margaret Okafor, INR normal.")
+    r2 = ng.deidentify("Note 2: Margaret Okafor, discharged.")
+    tokens_1 = {tok for tok in r1.clean_text.split() if tok.startswith("[PERSON-")}
+    tokens_2 = {tok for tok in r2.clean_text.split() if tok.startswith("[PERSON-")}
+    assert tokens_1 == tokens_2
+
+
+# ── load_known_from_csv ───────────────────────────────────────────────────────
+
+
+def test_load_known_from_csv(tmp_path):
+    csv_file = tmp_path / "patients.csv"
+    csv_file.write_text("full_name,nhs_number\nJane Smith,123 456 7890\n")
+    known = load_known_from_csv(str(csv_file))
+    assert "Jane Smith" in known["PERSON"]
+    assert "123 456 7890" in known["NHS"]
+
+
+def test_load_known_from_csv_admissions(tmp_path):
+    """Names in admissions.csv clinician columns are added to the vault."""
+    patients = tmp_path / "patients.csv"
+    patients.write_text("full_name,nhs_number\nJane Smith,123 456 7890\n")
+    admissions = tmp_path / "admissions.csv"
+    admissions.write_text("clinician_name,attending\nDr Wei Wang,Nurse Chukwuebuka Okafor\n")
+    known = load_known_from_csv(str(patients), str(admissions))
+    assert "Dr Wei Wang" in known["PERSON"]
+    assert "Nurse Chukwuebuka Okafor" in known["PERSON"]
+
+
+def test_load_known_from_csv_missing_admissions(tmp_path):
+    """Missing admissions.csv is silently ignored."""
+    patients = tmp_path / "patients.csv"
+    patients.write_text("full_name,nhs_number\nJane Smith,123 456 7890\n")
+    known = load_known_from_csv(str(patients), str(tmp_path / "missing.csv"))
+    assert "Jane Smith" in known["PERSON"]
+
+
+# ── scan_pii: vault-independent residual-PII audit for the trust panel ─────────
+
+
+def test_scan_pii_flags_titled_names_missed_by_vault():
+    """The reported failure: free-text clinician names with no vault entry slip
+    past de-id, and scan_pii must catch them while ignoring tokenised IDs."""
+    ng = NoteGuard(known={"PERSON": [], "NHS": []})  # arbitrary pasted note, no vault
+    note = (
+        "Contacted patient's GP, Dr. Ethel Joanne Duffy, to provide an update.\n"
+        "Nurse Jasmine Freda Murray\nNMC number: 20F4626L"
+    )
+    res = ng.deidentify(note)
+    findings = ng.scan_pii(res.clean_text)
+    texts = " | ".join(f["text"] for f in findings)
+    assert all(f["type"] == "name" for f in findings)
+    assert "Ethel Joanne Duffy" in texts
+    assert "Jasmine Freda Murray" in texts
+    assert "NMC" not in texts and "[NMC_1]" not in texts  # tokenised id is not PII
+
+
+def test_scan_pii_clean_when_names_tokenised():
+    """When names are in the vault they become surrogates → no residual PII."""
+    ng = NoteGuard(known={"PERSON": ["Ethel Joanne Duffy", "Jasmine Freda Murray"], "NHS": []})
+    res = ng.deidentify("GP Dr. Ethel Joanne Duffy. Nurse Jasmine Freda Murray.")
+    assert ng.scan_pii(res.clean_text) == []
+
+
+def test_scan_pii_ignores_surrogate_tokens_and_role_words():
+    """Surrogate tokens and bare role words must not be flagged as names."""
+    ng = NoteGuard()
+    text = "Consultant: [PERSON_1], seen by Dr [PERSON_2]. Nurse Practitioner reviewed."
+    assert ng.scan_pii(text) == []
+
+
+def test_scan_pii_flags_residual_structured_identifier():
+    """A structured identifier that slipped through is reported with its type."""
+    ng = NoteGuard()
+    findings = ng.scan_pii("Contact the team at a.b.smith@nhs.net for queries.")
+    assert any(f["type"] == "email" and "a.b.smith@nhs.net" in f["text"] for f in findings)
+
+
+# ── NER path: Presidio/spaCy redacts free-text names with no vault entry ───────
+
+
+def test_deidentify_redacts_ner_detected_names(monkeypatch):
+    """When an NLP detector is present, a free-text name with no vault entry is
+    still tokenised — the recall boost the [nlp] extra adds in the deployed image."""
+    import src.deid as deid
+
+    class _Fake(deid._Detector):
+        def detect_persons(self, text: str) -> list[str]:
+            return ["Ethel Joanne Duffy"] if "Ethel Joanne Duffy" in text else []
+
+    monkeypatch.setattr(deid, "_DETECTOR", _Fake())
+    ng = deid.NoteGuard(known={"PERSON": [], "NHS": []})
+    res = ng.deidentify("Reviewed by Ethel Joanne Duffy on the ward round.")
+    assert "Ethel Joanne Duffy" not in res.clean_text
+    assert "[PERSON_" in res.clean_text
+    assert ng.scan_pii(res.clean_text) == []  # nothing left for the audit to flag
+
+
+def test_shifted_date_round_trips_through_reidentify():
+    """A visit date is shifted (so the model never sees the real one), but the
+    shift is reversible: reproducing the shifted date restores the true date for
+    the clinician. This is the mechanism the discharge-summary date relies on."""
+    ng = NoteGuard()
+    res = ng.deidentify("Admission date 13/02/26.")
+    shifted = res.forward["13/02/26"]
+    assert shifted != "13/02/26"  # the model sees a different (shifted) date
+    assert "13/02/26" not in res.clean_text
+    # Model reproduces the shifted date verbatim → reidentify restores the real one.
+    restored = NoteGuard(reverse=res.reverse).reidentify(f"Admitted on {shifted}.")
+    assert "13/02/26" in restored
+
+
+def test_redact_unresolved_strips_stray_date_placeholder():
+    """A stray template placeholder like [DATE_X] (label + non-digit) is redacted
+    and flagged, so it never reaches the clinician verbatim."""
+    ng = NoteGuard()
+    out, leaked = ng.redact_unresolved("Admitted [DATE_X] after chest pain.")
+    assert "[DATE_X]" not in out
+    assert out == "Admitted [redacted] after chest pain."
+    assert leaked == ["[DATE_X]"]
+
+
+def test_redact_unresolved_strips_unrestored_surrogate():
+    """An unrestored [LABEL_n] surrogate is also caught."""
+    ng = NoteGuard()
+    out, leaked = ng.redact_unresolved("Seen by [PERSON_9].")
+    assert out == "Seen by [redacted]." and leaked == ["[PERSON_9]"]
+
+
+def test_redact_unresolved_leaves_clean_text_untouched():
+    """Text with no surrogate-shaped tokens is returned unchanged."""
+    ng = NoteGuard()
+    out, leaked = ng.redact_unresolved("Admitted after chest pain. Stable.")
+    assert out == "Admitted after chest pain. Stable." and leaked == []
+
+
+def test_ner_clinical_stopwords_not_redacted(monkeypatch):
+    """Clinical abbreviations the NER layer mislabels (e.g. 'Subcut') are kept,
+    while a real name flagged in the same pass is still redacted."""
+    import src.deid as deid
+
+    class _Fake(deid._Detector):
+        def detect_persons(self, text: str) -> list[str]:
+            return ["Subcut", "Afua Asare"]
+
+    monkeypatch.setattr(deid, "_DETECTOR", _Fake())
+    ng = deid.NoteGuard(known={"PERSON": [], "NHS": []})
+    res = ng.deidentify("Subcut emph noted on palpation. Reviewed by Afua Asare.")
+    assert "Subcut" in res.clean_text  # clinical term — not a name
+    assert "Afua Asare" not in res.clean_text and "[PERSON_" in res.clean_text