Deploy 8244dcbebc2e76b6843857728efe8f835b7426b4 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,141 @@
+# 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.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,79 @@
+# 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` scores faithfulness (LLM-as-judge) of the answer against the
+  de-identified source note — it never sees PHI.
+
+## Key files
+- `src/deid.py` — de-id core (std-lib only): NHS-aware rules + vault-from-CSV,
+  consistent surrogates, DOB date-shift, `reidentify`, `assert_clean`. Keep it
+  dependency-free; Presidio/spaCy are optional behind the same interface.
+- `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,27 @@
+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
+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"
+
+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,238 @@
+---
+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:
+                         leakage % · identifiers removed
+                         leaked tokens · faithfulness · sources
+```
+
+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` | Extracts Tavily sources and scores faithfulness (LLM-as-judge over the de-identified note). |
+
+---
+
+## REST API
+
+### POST /process
+
+```json
+{
+  "note": "Pt Margaret Okafor (NHS 485 777 3456) admitted post-fall.",
+  "question": "Draft a discharge summary.",
+  "person_id": "pt-001"
+}
+```
+
+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.identifiers_removed` | Count of identifiers replaced |
+| `metrics.residual_risk` | `0.0` when privacy guarantee held; fractional or `1.0` when leaks detected |
+| `metrics.leaked_tokens` | List of unmapped/unresolved surrogate tokens detected post-model |
+| `metrics.grounded_sources` | Distinct Tavily sources cited |
+| `metrics.faithfulness` | LLM-judge score `0–1`: is every claim in the summary supported by the de-identified note? |
+
+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.
+
+**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.0.0

agent/graph.py

@@ -0,0 +1,239 @@
+"""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 json
+import os
+import re
+
+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.
+Never write the literal text of a surrogate token (e.g. [PERSON_1]) in the title line — \
+use {{PATIENT}} there instead (see below).
+
+## Output format — four elements, blank line between each
+
+{{PATIENT}} — discharge summary
+
+Admitted [DATE_X] 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
+
+**Title line:** write exactly `{{PATIENT}} — discharge summary`. \
+The placeholder {{PATIENT}} is resolved to the real patient name by the system — \
+you must never write a real name, a surrogate token, or any other identifier there.
+
+**Narrative paragraph:** plain clinical prose, max 4 sentences. Include only facts stated in \
+the source note — never invent investigations, doses, dates, or diagnoses. \
+Surrogate tokens ([DATE_1], [PERSON_1], etc.) may appear here and will be restored. \
+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
+    person_name: str  # resolved from person_id — fills {{PATIENT}} in title
+    # --- trust panel fields ---
+    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  # tokens/patterns that slipped through (post-model)
+    faithfulness_score: float  # LLM-as-judge: 0–1
+    sources: list  # Tavily URLs cited in the answer
+
+
+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 ""
+
+        # Check model output for orphaned tokens BEFORE reidentify restores known ones
+        reverse = state.get("reverse") or {}
+        leaked: list[str] = []
+        for m in re.finditer(r"\[[A-Z]+_\d+\]", raw_text):
+            tok = m.group(0)
+            if tok not in reverse:
+                leaked.append(f"unmapped_token:{tok}")
+
+        # Restore known surrogates
+        restored = ng.reidentify(raw_text)
+
+        # Replace {{PATIENT}} with the structured patient name (never from model)
+        person_name = state.get("person_name") or "Patient"
+        restored = restored.replace("{{PATIENT}}", person_name)
+
+        # Replace any remaining [LABEL_n] that reidentify couldn't resolve — flag each
+        def _replace_leftover(m: re.Match) -> str:
+            tok = m.group(0)
+            leaked.append(f"unresolved_token:{tok}")
+            return "[redacted]"
+
+        restored = re.sub(r"\[[A-Z]+_\d+\]", _replace_leftover, restored)
+
+        return {"clinician_answer": restored, "leaked_tokens": leaked}
+
+    def compute_trust(state: State):
+        """Extract Tavily sources and compute faithfulness (LLM-as-judge).
+
+        The faithfulness judge compares the de-identified AI answer against
+        the de-identified source note (deid_text) — it never sees PHI.
+        """
+        # --- Tavily sources from ToolMessages ---
+        sources: list[str] = []
+        for msg in state["messages"]:
+            content = getattr(msg, "content", None)
+            if not content:
+                continue
+            try:
+                items = json.loads(content) if isinstance(content, str) else content
+                if isinstance(items, list):
+                    for item in items:
+                        if isinstance(item, dict) and item.get("url"):
+                            sources.append(item["url"])
+            except (json.JSONDecodeError, TypeError):
+                pass
+
+        # --- faithfulness: judge de-identified answer vs de-identified source note ---
+        score = 0.0
+        last_ai = next((m for m in reversed(state["messages"]) if isinstance(m, AIMessage)), None)
+        context = state.get("deid_text") or ""
+        if last_ai and context:
+            ai_content = last_ai.content
+            if isinstance(ai_content, list):
+                ai_content = " ".join(
+                    b.get("text", "") if isinstance(b, dict) else str(b) for b in ai_content
+                ).strip()
+            prompt = (
+                f"CONTEXT (de-identified source note):\n{context}\n\n"
+                f"ANSWER:\n{ai_content}\n\n"
+                "Is every clinical claim in ANSWER supported by CONTEXT? "
+                "Reply with a single number between 0 and 1."
+            )
+            try:
+                raw = model.invoke(prompt).content
+                if isinstance(raw, list):
+                    raw = " ".join(b.get("text", "") if isinstance(b, dict) else str(b) for b in raw)
+                score = max(0.0, min(1.0, float(raw.strip().split()[0])))
+            except Exception:
+                score = 0.0
+
+        # Merge leaked_tokens from reidentify_out with any new findings
+        leaked = list(state.get("leaked_tokens") or [])
+        residual_extra = state.get("residual_count", 0)
+
+        return {
+            "sources": list(dict.fromkeys(filter(None, sources))),
+            "faithfulness_score": score,
+            "leaked_tokens": leaked,
+            # Bump residual_count so the API's risk calculation sees the truth
+            "residual_count": residual_extra + 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,295 @@
+"""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.0.0")
+
+# ---------------------------------------------------------------------------
+# Dataset — loaded once at startup; degrades gracefully when data/ is absent
+# ---------------------------------------------------------------------------
+
+_NOTES: list[dict] = []
+_DEFAULT_KNOWN: dict | None = None
+_PATIENT_NAMES: dict[str, str] = {}  # person_id -> full_name for {{PATIENT}} resolution
+
+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)
+
+    # Build person_id → name lookup for {{PATIENT}} resolution
+    with open(_patients_csv, newline="", encoding="utf-8-sig") as _pf:
+        for _row in csv.DictReader(_pf):
+            _pid = (_row.get("person_id") or "").strip()
+            _name = (
+                _row.get("full_name")
+                or _row.get("patient_name")
+                or f"{_row.get('first_name', '').strip()} {_row.get('surname', '').strip()}".strip()
+            )
+            if _pid and _name:
+                _PATIENT_NAMES[_pid] = _name
+
+    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  # when set, {{PATIENT}} resolves to the real name
+
+
+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
+
+    residual = state.get("residual_count", 0)
+    return SummariseResponse(
+        clinician_answer=state.get("clinician_answer", ""),
+        identifiers_removed=len(state.get("forward", {})),
+        residual_risk=0.0 if residual == 0 else 1.0,
+        deidentified_excerpt=(state.get("deid_text") or "")[:400],
+        ok=residual == 0,
+    )
+
+
+@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
+    person_name = _PATIENT_NAMES.get(req.person_id, "Patient") if req.person_id else "Patient"
+    try:
+        g = _get_graph(known)
+        state = g.invoke(
+            {
+                "messages": [HumanMessage(content=req.note + "\n\n" + req.question)],
+                "person_name": person_name,
+            }
+        )
+    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 {}
+    residual = state.get("residual_count", 0)
+    leaked = state.get("leaked_tokens") or []
+    faith = state.get("faithfulness_score", 0.0)
+    has_leak = residual > 0 or bool(leaked)
+
+    return ProcessResponse(
+        clinician_note=req.note,
+        ai_note=state.get("deid_text", ""),
+        identifiers=list(forward.keys()),
+        discharge_summary=state.get("clinician_answer", ""),
+        metrics={
+            "identifiers_removed": len(forward),
+            "residual_risk": 0.0
+            if not has_leak
+            else min(1.0, (residual + len(leaked)) / max(len(forward), 1)),
+            "grounded_sources": len(state.get("sources") or []),
+            "faithfulness": faith if state.get("deid_text") else None,
+            "leaked_tokens": leaked,
+        },
+    )
+
+
+if STATIC_DIR.exists():
+    app.mount("/static", StaticFiles(directory=str(STATIC_DIR)), name="static")

app/static/index.html

@@ -0,0 +1,585 @@
+<!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 -->
+<div class="trust-row">
+  <div class="metric" id="mRisk">
+    <div class="mlabel">Re-id risk · model input</div>
+    <div class="mvalue" id="mRiskVal">—</div>
+    <div id="leakDetail" class="leak-detail" style="display:none"></div>
+  </div>
+  <div class="metric" id="mIds">
+    <div class="mlabel">Identifiers removed</div>
+    <div class="mvalue" id="mIdsVal">—</div>
+  </div>
+  <div class="metric" id="mFaith" hidden>
+    <div class="mlabel">Faithfulness</div>
+    <div class="mvalue" id="mFaithVal">—</div>
+  </div>
+  <div class="metric" id="mSrc">
+    <div class="mlabel">Grounded sources</div>
+    <div class="mvalue" id="mSrcVal">—</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');
+  document.getElementById('mRiskVal').textContent = '—';
+  document.getElementById('mRiskVal').className = 'mvalue';
+  document.getElementById('mIdsVal').textContent = '—';
+  document.getElementById('mSrcVal').textContent = '—';
+  document.getElementById('mFaith').hidden = true;
+  const leakEl = document.getElementById('leakDetail');
+  if (leakEl) { leakEl.textContent = ''; leakEl.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>`;
+    }
+    if (line.includes('— discharge summary') || line.includes('- discharge summary')) {
+      return `<p class="card-title">${esc(line)}</p>`;
+    }
+    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
+    const m = result.metrics;
+    const rv = document.getElementById('mRiskVal');
+    rv.textContent = (m.residual_risk * 100).toFixed(1) + '%';
+    rv.className = 'mvalue ' + (m.residual_risk === 0 ? 'ok' : 'risk');
+    document.getElementById('mIdsVal').textContent = m.identifiers_removed;
+    document.getElementById('mSrcVal').textContent = m.grounded_sources;
+    if (m.faithfulness !== null && m.faithfulness !== undefined) {
+      document.getElementById('mFaith').hidden = false;
+      document.getElementById('mFaithVal').textContent = (m.faithfulness * 100).toFixed(0) + '%';
+    }
+    // Leak detail — shown when residual_risk > 0
+    const leakEl = document.getElementById('leakDetail');
+    if (leakEl && m.residual_risk > 0 && m.leaked_tokens && m.leaked_tokens.length) {
+      leakEl.textContent = 'Leak detected: ' + m.leaked_tokens.slice(0, 3).join(', ');
+      leakEl.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,162 @@
+# 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` | LLM-as-judge + source extraction | Faithfulness (answer vs de-identified source note) + source URLs 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. |
+| `person_name` | `str` | Real patient name for `{{PATIENT}}` placeholder resolution. |
+| `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]` | Unmapped/unresolved surrogate tokens detected post-model. |
+| `clinician_answer` | `str` | Re-identified, clinician-facing answer. |
+| `faithfulness_score` | `float` | LLM-as-judge 0–1 score. |
+| `sources` | `list[str]` | Tavily / NICE / NHS URLs cited. |
+
+## 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": {
+    "identifiers_removed": 5,
+    "residual_risk": 0.0,
+    "grounded_sources": 2,
+    "faithfulness": 0.9,
+    "leaked_tokens": []
+  }
+}
+```
+
+`422` is returned when `assert_clean()` detects surviving PHI — the model sees nothing.
+
+`metrics.residual_risk` is `0.0` when the guarantee holds; fractional (or `1.0`) when
+residual identifiers or leaked surrogate tokens are detected.
+
+## 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 and sets `person_id` for `{{PATIENT}}` resolution.
+- **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: Re-id risk, Identifiers removed, Faithfulness (answer vs de-identified note), Grounded sources, leaked tokens (shown when non-empty).
+
+## 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 an optional Presidio/spaCy NLP layer. 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, optional Presidio/spaCy).
+
+### 2. Description and rationale
+
+- **2.1 Detailed description:** A clinical note is passed through `deidentify_in` (rule recognisers + vault match + optional NLP), which raises if any identifier survives (`assert_clean()`). The clean text reaches the LangGraph ReAct agent; Tavily retrieves public NICE/NHS guidance. The agent drafts a four-element compact discharge card using a `{{PATIENT}}` placeholder for the title. `reidentify_out` restores surrogates and resolves `{{PATIENT}}` from `patients.csv` — the model never sees the real name. `compute_trust` measures residual leakage, orphaned tokens, and faithfulness.
+- **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 (identifiers removed, residual risk, leaked tokens, faithfulness score), 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) optional Presidio + spaCy `en_core_web_lg`; (c) LangGraph ReAct agent with Gemini 2.5 Flash; (d) Tavily public-guidance search; (e) 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 (optional) | `PERSON`, `LOCATION` | spaCy `en_core_web_lg`, score-thresholded | No-op fallback when not installed |
+| Gemini 2.5 Flash | Discharge summary drafting | LangGraph ReAct; SYSTEM prompt enforces `{{PATIENT}}` and no-PHI rules | `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 | Trust metric | Residual leakage + orphaned-token check + LLM-as-judge faithfulness | 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; residual risk metric 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; faithfulness score; clinician signs off |
+| 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 + optional Microsoft Presidio (spaCy NER); 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 an optional NLP detector (Presidio + spaCy `en_core_web_lg`).
+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. **Computes a trust metric** — residual leakage rate, leaked-token list, and faithfulness score.
+
+> "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) + optional Presidio spaCy NER | Vault is ground-truth; Presidio adds unlisted names |
+| 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}}` placeholder | Title line of discharge summary uses this literal; resolved from `patients.csv` — the model never writes the real name |
+
+---
+
+## Bias and fairness
+
+The optional Presidio NER (spaCy `en_core_web_lg`) is trained largely on Western/English text, so **name recall can be lower for names of non-English origin**. This is an equity risk: under-detection means those patients carry a *higher residual re-identification risk*. 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,142 @@
+# 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:
+   - **Re-id risk · model input** — `0.0 %` when the privacy guarantee holds; higher when leaks detected.
+   - **Identifiers removed** — count of distinct tokens de-identified in this call.
+   - **Faithfulness** — LLM-as-judge score (`0–100 %`): is every claim in the summary supported by the de-identified note?
+   - **Grounded sources** — number of distinct Tavily / NICE / NHS URLs cited by Gemini.
+   - **Leaked tokens** — surrogate tokens that survived the model without being re-identified (should be empty).
+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,61 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "noteguard-agent"
+version = "1.0.0"
+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 ".[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,288 @@
+"""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 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+\]")
+
+# 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) ─────────────────────────────────
+
+
+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:
+    try:
+        from presidio_analyzer import AnalyzerEngine  # type: ignore
+
+        engine = AnalyzerEngine()
+
+        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 _DETECTOR.detect_persons(t):
+            if name and len(name) > 2 and 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))
+
+    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 _DETECTOR.detect_persons(text):
+            if name:
+                hits.append(f"PERSON:{name[:30]}")
+
+        return list(dict.fromkeys(hits))  # deduplicate, preserve order
+
+    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
+
+
+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,212 @@
+"""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)
+
+
+# ── 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"]