Update files

.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+.DS_Store
+# HF dataset cache pulled at runtime
+synthetic_clinical_notes/
+patients.csv
+admissions.csv

NOTEGU~1.MD

@@ -0,0 +1,137 @@
+# NoteGuard — Project Brief & Handover
+
+**NoteGuard**
+*An automatic PII preprocessing tool that sanitises NHS clinical notes before any model training.*
+
+**Hackathon:** FLock.io × UK Sovereign AI (48 hours)
+**Team:** Chaeyoon + Yumi
+**Last updated:** 19 June 2026
+
+---
+
+## TL;DR
+
+NoteGuard is an automatic preprocessing tool that **discovers, inspects, redacts, and de-identifies PII in free-text NHS clinical notes** before the data is used to train any model. It runs **locally at each trust** ("sanitise at source"), so each institution cleans its own data before anything is shared or used in collaborative/federated training.
+
+> One-liner: *NoteGuard — automatic PII sanitisation for NHS clinical notes. Clean data in, no identifiers out.*
+
+**Tracks:** Trusted Data & AI Infrastructure + AI Governance, Transparency & Trust.
+
+---
+
+## The problem
+
+Clinical notes are the most IG-sensitive data the NHS holds. To use them for any ML they must first be de-identified, but:
+
+- Manual de-identification is slow, inconsistent, and doesn't scale.
+- Centralised tools (e.g. Google Cloud Sensitive Data Protection / Cloud DLP) require sending data to a proprietary external cloud.
+- Free-text notes hide PII *inline in the narrative*, and real notes are full of typos and abbreviations that defeat naive rules.
+
+NoteGuard automates de-identification at the point data enters the pipeline, on-prem, with a **measurable** leakage rate.
+
+---
+
+## Sovereignty framing (clarified by the judges)
+
+"Sovereignty" does **not** mean locking data to UK soil. It means **data-jurisdiction sovereignty**: any institution or region retains governance over its own data and can collaborate without surrendering it — whether that boundary is an NHS trust, a London ICB, a US state health department, or an EU region.
+
+NoteGuard's contribution: it sanitises data **inside its own governance boundary, wherever that is**, so cross-institution collaboration (incl. federated training) becomes possible without any central party ever seeing raw PII. NoteGuard is the **privacy-preserving on-ramp** to collaborative/federated AI.
+
+> Avoid "don't send it to a US hyperscaler" — it's about *control*, not location.
+
+---
+
+## Scope (narrowed — this is the whole build)
+
+We are building **only the PII preprocessing tool**, not a federated model. Federated learning is the *context/motivation* (sanitise-at-source enables it); the *deliverable* is the sanitiser.
+
+**Note on FLock:** the judges confirmed we do **not** have to use FLock's API. Build the tool standalone; reference FLock as the decentralised-coordination layer NoteGuard feeds into.
+
+---
+
+## The pipeline (the product)
+
+### 1. Ingest
+Load clinical notes (NHSE synthetic dataset).
+
+### 2. Detect / Inspect PII (layered — no single method catches everything)
+- **Rules + checksums:** NHS number (10-digit, **mod-11 checksum** — standout custom recogniser), UK postcodes, dates, phone, email.
+- **Gazetteer:** match names / site names from the patient & admission tables against the note text.
+- **NER model:** catch PII *inline in the narrative* (PERSON, DATE, LOCATION) that rules miss.
+
+### 3. Transform / De-identify (offer several; explain the utility trade-off)
+- **Redaction** → `[PERSON]`, `[NHS_NUMBER]`
+- **Surrogate replacement** → fake-but-realistic value (keeps text readable for downstream NLP)
+- **Consistent pseudonymisation** → same patient → same token across all their notes (preserves the longitudinal journey) via a mapping vault
+- **Date shifting** → shift each patient's dates by a consistent random offset (preserves intervals)
+
+### 4. Validate / Risk-score
+Output a **clean, training-ready dataset** + an **audit report** of what was removed + a **k-anonymity** re-identification risk score.
+
+---
+
+## Recommended engine: Microsoft Presidio
+
+Don't build detection from scratch. **Presidio** is open-source, purpose-built for PII detection + anonymisation, runs fully on-prem (sovereign), and is extensible with custom recognisers — the de-facto open-source equivalent of GCP Sensitive Data Protection.
+
+Our 48h work = add NHS-specific recognisers (NHS-number checksum, NHS org/site lists) + wire up the transforms. **spaCy / medspaCy** underneath for the NER layer.
+
+---
+
+## Evaluation (our "reliable" pillar — wins on measurable results)
+
+The synthetic dataset has **known** PII (names/NHS numbers in the structured tables), so we can build ground-truth labels and report real numbers:
+
+- **Precision / recall / F1 of PII detection, per entity type.**
+- **Residual PII leakage rate** after de-identification.
+- **Robustness to noise:** the dataset's injected **typos + abbreviations** degrade detection — report F1 *with vs without* them. "PII detection under realistic messy text" is a strong, honest result.
+
+---
+
+## Dataset
+
+**NHSEDataScience/synthetic_clinical_notes** (Hugging Face) — NHS England's own synthetic dataset.
+
+- ~70 synthetic patients (50 adult, 20 paediatric), 20–50 notes each, full admission→discharge journeys.
+- **Deliberately injected typos + medical abbreviations** — the messiness is the test.
+- Names / NHS numbers in the patient & admission tables → ground truth for the de-id eval.
+- No FDP, no real data, no IG barrier. "We deliberately used synthetic data so it's shareable and governance-safe" is a strength.
+
+---
+
+## NHS England framing (credibility edge)
+
+Adopt NHSE Data Science's own ethics scaffolding rather than inventing one. Four characteristics: **fair, transparent, value-adding, reliable.**
+
+**Lighter governance artefacts (no heavy ML-model paperwork now):**
+1. **Tool Card / datasheet** for NoteGuard
+2. **Data Hazards assessment** (datahazards.com — NHSE applies it to every project)
+3. **Five Safes mapping** (Safe Data: de-identify at source)
+
+**NHSE siblings to cite hard** (NoteGuard is the productised, automated version): *Tool to Assess Privacy Risk of Text Data*; *Privacy of Unstructured Data*; *Emerging Privacy Enhancing Technologies (PETs)*; *SDE Service Data Wranglers — Reusable Data Validation Process* (literally the target role).
+
+---
+
+## 48-hour MVP
+
+A small web UI:
+**messy clinical note → highlighted detected PII (inspect) → choose a de-id transform → sanitised note out → detection F1 + leakage + k-anonymity score.**
+Behind it: Presidio + NHS custom recognisers running against the synthetic dataset. The **detect → de-identify → score** loop is the demo that lands.
+
+---
+
+## Division of labour (suggested)
+
+- **Person A:** Presidio engine + NHS custom recognisers (NHS-number checksum, gazetteers) + transforms (redaction/pseudonymisation/date-shift).
+- **Person B:** Web UI demo + evaluation harness (precision/recall/F1, leakage rate, k-anonymity).
+- **Shared / Chaeyoon (ethicist edge):** Tool Card, Data Hazards, Five Safes mapping, the pitch + architecture diagram.
+
+---
+
+## Why this wins (judging criteria check)
+
+- ✅ Clear, relevant real-world use case (automated NHS de-identification preprocessing)
+- ✅ Thoughtful use of privacy-preserving AI (sanitise-at-source; on-ramp to federated/collaborative AI)
+- ✅ Strong technical implementation (layered detection, multiple transforms, robustness-to-noise eval)
+- ✅ Attention to trust, governance, security (Five Safes, NHSE ethics, measurable leakage rate, audit log)
+- ✅ Credible path to real-world adoption (open-source, on-prem, generalises to any jurisdiction; aligns to NHSE's own tooling)

README.md

@@ -1 +1,100 @@
-# Automatic-PII-preprocessing-tool
+# 🛡️ NoteGuard
+
+**Automatic PII sanitisation for NHS clinical notes — clean data in, no identifiers out.**
+
+NoteGuard discovers, inspects, redacts, and de-identifies PII in free-text NHS
+clinical notes **before** the data is used to train any model. It runs **locally
+at each institution** ("sanitise at source"), so every trust cleans its own data
+inside its own governance boundary before anything is shared or used in
+collaborative / federated training.
+
+> Federated learning lets institutions train without moving data. NoteGuard is the
+> **privacy-preserving on-ramp** that makes the data safe to train on in the first place.
+
+Hackathon: **FLock.io × UK Sovereign AI** — track *Trusted Data & AI Infrastructure*.
+
+---
+
+## What makes this more than "just Presidio"
+
+[Microsoft Presidio](https://microsoft.github.io/presidio/) is the detection
+**engine** — we don't reinvent it. NoteGuard is the **clinical assurance layer**
+Presidio leaves to you:
+
+1. **Measured residual leakage.** Presidio detects PII but never tells you *how
+   much still leaks on your data*. Because the NHSE dataset keeps PII in structured
+   tables, we join them back to each note to get ground truth for free and report a
+   real **re-identification risk** number.
+2. **Domain adaptation to messy clinical text.** Real notes are full of typos and
+   abbreviations. We measure detection with vs without that noise, and add NHS-aware
+   recognisers (checksum-validated NHS numbers **plus** context-anchored detection
+   for the dataset's 9-digit synthetic numbers that Presidio's `UK_NHS` misses).
+3. **Patient-consistent, longitudinal de-identification.** Presidio anonymises per
+   document. NoteGuard keeps the *same patient → same surrogate* across their whole
+   admission journey and shifts each patient's dates by one consistent offset, so
+   intervals (clinical timelines) survive — useful data, not just safe data.
+4. **Governance wrapper.** Per-note audit of what was removed, plus the dataset-level
+   leakage report — aligned to NHSE's *fair / transparent / value-adding / reliable*
+   ethics and the Five Safes (Safe Data: de-identify at source).
+
+## Results (500 NHSE synthetic notes)
+
+| Detector | NHS number F1 | PERSON recall | **Residual leakage** |
+|---|---|---|---|
+| rules only | 0.97 | 0.00 | **73.3 %** |
+| **presidio + rules** | **0.98** | **0.69** | **4.6 %** |
+
+**Residual leakage** = known identifiers (joined from the structured tables) still
+present in the note *after* sanitisation. The rules→engine drop from 73 % → 4.6 %
+is the headline: it shows, with numbers, exactly what the NER engine buys you.
+
+> Precision is reported against *structured* PII only, so it is a conservative lower
+> bound — correctly removing a clinician's name (not in the tables) counts here as a
+> false positive. Recall and leakage are the sound, headline metrics.
+
+## Architecture
+
+```
+data.py        load 3 CSVs, join on person_id/admission_id → per-note ground-truth PII
+recognizers.py pure-Python rules: NHS checksum + NHS-context + postcode/date/phone/email
+detect.py      Detector interface: RuleDetector · PresidioDetector · Gazetteer · Composite
+transform.py   redaction · patient-consistent pseudonymisation (vault) · date-shift
+evaluate.py    ground-truth matching → per-entity P/R/F1 + residual leakage rate
+pipeline.py    single-note detect → de-identify → audit (used by UI + CLI)
+run_eval.py    dataset-level evaluation → results.json
+app.py         Gradio demo: note → highlighted PII → transform → sanitised + metrics
+```
+
+The rule layer and evaluation harness are **pure Python** — they run even if
+Presidio/spaCy are unavailable, so the core "measure the leakage" capability never
+depends on the heavy NER stack.
+
+## Quickstart
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+python -m spacy download en_core_web_sm
+
+python run_eval.py --compare --limit 500   # reproduce the table above → results.json
+python app.py                              # launch the demo UI (http://127.0.0.1:7860)
+```
+
+The NHSE synthetic dataset
+([`NHSEDataScience/synthetic_clinical_notes`](https://huggingface.co/datasets/NHSEDataScience/synthetic_clinical_notes))
+is pulled automatically on first run. To run fully offline, drop the three CSVs in a
+folder and set `NOTEGUARD_DATA_DIR=/path/to/csvs`.
+
+## Data note (found by inspecting the data, not assuming)
+
+- NHS numbers in this synthetic set are **9 digits** (real ones are 10 + mod-11
+  check). We catch both: checksum-validated 10-digit anywhere, **and**
+  context-anchored numbers after an "NHS …" label.
+- The `ward` column is the literal word `ward`, and some fields are double-encoded
+  (`·`). Both are handled in `data.py` so they don't pollute the ground truth.
+
+## Why synthetic data is a strength
+
+No real patient data, no IG barrier, fully shareable — and it ships **known** PII in
+structured tables, which is exactly what lets us report an honest, measurable leakage
+rate instead of a vibe.

work-process_yumi/app.py

@@ -0,0 +1,144 @@
+"""NoteGuard demo UI.
+
+The demo that lands: messy clinical note -> highlighted detected PII (inspect) ->
+choose a de-identification transform -> sanitised note out -> audit + the
+dataset-level residual-leakage numbers behind it.
+
+    python app.py
+"""
+from __future__ import annotations
+
+import json
+import os
+
+import gradio as gr
+
+from noteguard.data import load_notes
+from noteguard.pipeline import Pipeline
+from noteguard.transform import PSEUDONYM, REDACTION, PseudonymVault
+
+# ---- load engine + a few sample notes once ---------------------------------
+print("[noteguard] loading detection engine (Presidio + spaCy) ...")
+PIPELINE = Pipeline()
+print("[noteguard] loading sample notes ...")
+try:
+    SAMPLES = load_notes(limit=40)
+except Exception as e:  # pragma: no cover
+    print(f"[noteguard] could not load dataset samples ({e}); paste-only mode.")
+    SAMPLES = []
+
+SAMPLE_CHOICES = [
+    f"{i}: {(s.note_type or 'note')} — {s.text[:48].strip()}…"
+    for i, s in enumerate(SAMPLES) if s.text
+]
+
+
+def _highlight(text: str, spans) -> dict:
+    return {
+        "text": text,
+        "entities": [
+            {"entity": s.entity_type, "start": s.start, "end": s.end} for s in spans
+        ],
+    }
+
+
+def load_sample(choice: str) -> tuple[str, str]:
+    if not choice:
+        return "", ""
+    idx = int(choice.split(":", 1)[0])
+    rec = SAMPLES[idx]
+    return rec.text, rec.person_id
+
+
+def run(text: str, method_label: str, person_id: str):
+    method = PSEUDONYM if method_label.startswith("Pseudonym") else REDACTION
+    # fresh vault per run so the demo is reproducible
+    PIPELINE.vault = PseudonymVault()
+    result = PIPELINE.sanitise(text or "", method, person_id or "demo")
+
+    highlighted = _highlight(text or "", result.spans)
+    by_type = result.audit.get("by_type", {})
+    audit_md = "\n".join(f"- **{k}**: {v}" for k, v in sorted(by_type.items())) or "_none detected_"
+    audit_md = (
+        f"**Detector:** `{result.audit['detector']}`  \n"
+        f"**Transform:** `{method}`  \n"
+        f"**Entities removed:** {result.audit['entities_removed']}\n\n"
+        f"{audit_md}"
+    )
+    return highlighted, result.sanitised, audit_md
+
+
+_PII_LABEL = {"UK_NHS": "NHS number", "PERSON": "Name", "DATE_TIME": "Date of birth"}
+
+
+def metrics_panel() -> str:
+    if not os.path.exists("results.json"):
+        return "_Run `python run_eval.py --limit 500` to populate metrics._"
+    with open("results.json") as f:
+        data = json.load(f)
+    # show the shipping detector (NER model + rules)
+    name = "presidio+rules" if "presidio+rules" in data else next(iter(data))
+    r = data[name]
+    notes = r["notes_evaluated"]
+    leak = r["leakage"]["leakage_rate_pct"]
+    removed = round(100 - leak, 2)
+    pe = r["detection"]["per_entity"]
+
+    rows = ["| PII type | Detected (recall) | occurrences |", "|---|---|---|"]
+    for et in ("UK_NHS", "PERSON", "DATE_TIME"):
+        m = pe.get(et)
+        if m and m["support"] > 0:
+            rows.append(f"| {_PII_LABEL.get(et, et)} | {m['recall']:.0%} | {m['support']} |")
+    return (
+        f"### 📊 Measured on {notes} NHSE synthetic notes\n\n"
+        f"## ✅ Removed **{removed}%** of known identifiers\n"
+        f"_residual re-identification risk: **{leak}%** leakage_\n\n"
+        + "\n".join(rows)
+        + "\n\n_Ground truth is joined from the dataset's structured patient / "
+          "admission tables, so the leakage rate is a real, measurable "
+          "re-identification risk — not an estimate._"
+    )
+
+
+with gr.Blocks(title="NoteGuard") as demo:
+    gr.Markdown(
+        "# 🛡️ NoteGuard\n"
+        "**Automatic PII sanitisation for NHS clinical notes — clean data in, no "
+        "identifiers out.** Sanitise-at-source so institutions can collaborate "
+        "(incl. federated training) without ever sharing raw PII."
+    )
+    person_state = gr.State("")
+    with gr.Row():
+        with gr.Column(scale=1):
+            sample_dd = gr.Dropdown(SAMPLE_CHOICES, label="Load a sample NHSE note",
+                                    value=SAMPLE_CHOICES[0] if SAMPLE_CHOICES else None)
+            note_in = gr.Textbox(label="Clinical note (messy free-text)", lines=14,
+                                 placeholder="Paste a clinical note…")
+            method = gr.Radio(
+                ["Redaction → [PERSON]", "Pseudonymisation (patient-consistent + date-shift)"],
+                value="Redaction → [PERSON]", label="De-identification transform",
+            )
+            run_btn = gr.Button("Detect & sanitise", variant="primary")
+        with gr.Column(scale=1):
+            highlighted = gr.HighlightedText(label="1) Detected PII (inspect)")
+            sanitised = gr.Textbox(label="2) Sanitised note (training-ready)", lines=10)
+            audit = gr.Markdown(label="3) Audit")
+
+    gr.Markdown("---")
+    with gr.Row():
+        gr.Markdown("## 📊 Dataset-level metrics")
+        refresh_btn = gr.Button("🔄 Refresh from results.json", scale=0)
+    metrics_md = gr.Markdown(metrics_panel())
+
+    sample_dd.change(load_sample, sample_dd, [note_in, person_state])
+    run_btn.click(run, [note_in, method, person_state], [highlighted, sanitised, audit])
+    refresh_btn.click(metrics_panel, None, metrics_md)
+
+    # re-read results.json on every page load so the panel never shows a stale snapshot
+    demo.load(metrics_panel, None, metrics_md)
+    if SAMPLE_CHOICES:
+        demo.load(load_sample, sample_dd, [note_in, person_state])
+
+
+if __name__ == "__main__":
+    demo.launch()

work-process_yumi/noteguard/__init__.py

@@ -0,0 +1,7 @@
+"""NoteGuard — automatic PII sanitisation for NHS clinical notes.
+
+Clean data in, no identifiers out. Sanitise-at-source so institutions can
+collaborate (incl. federated training) without surrendering raw PII.
+"""
+
+__version__ = "0.1.0"

work-process_yumi/noteguard/data.py

@@ -0,0 +1,218 @@
+"""Load the NHSE synthetic clinical notes dataset and build per-note ground truth.
+
+The dataset ships three CSVs that share keys:
+  patients.csv    person_id, full_name, nhs_number, date_of_birth, ...
+  admissions.csv  admission_id, patient_name/first_name/surname, site_name, ward, ...
+  notes.csv       clinical_note_id, clean_note_text, person_id, admission_id, ...
+
+Because the PII lives in the *structured* tables, we get ground-truth labels for
+free: for each note we join back to the patient/admission rows and collect the
+known PII strings that *should* be removed. That join is what makes a real,
+measurable leakage rate possible — the thing Presidio alone never gives you.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from functools import lru_cache
+
+import pandas as pd
+
+REPO_ID = "NHSEDataScience/synthetic_clinical_notes"
+
+
+# --- entity types we align to Presidio's vocabulary -------------------------
+PERSON = "PERSON"
+UK_NHS = "UK_NHS"
+DATE = "DATE_TIME"
+LOCATION = "LOCATION"
+
+
+@dataclass(frozen=True)
+class GroundTruthPII:
+    """One known PII value that should not survive sanitisation."""
+    text: str
+    entity_type: str
+
+
+@dataclass
+class NoteRecord:
+    note_id: str
+    person_id: str
+    admission_id: str
+    text: str
+    note_type: str = ""
+    note_subject: str = ""
+    # known PII strings for THIS note, derived from the structured tables
+    ground_truth: list[GroundTruthPII] = field(default_factory=list)
+
+
+def _fix_mojibake(s: str) -> str:
+    """Repair the known UTF-8-as-latin-1 decoding defect (e.g. '·' -> '·')."""
+    if not s or ("Â" not in s and "Ã" not in s):
+        return s
+    try:
+        return s.encode("latin-1").decode("utf-8")
+    except (UnicodeDecodeError, UnicodeEncodeError):
+        return s
+
+
+def _first_col(df: pd.DataFrame, *candidates: str) -> str | None:
+    for c in candidates:
+        if c in df.columns:
+            return c
+    return None
+
+
+def _download_csvs(local_dir: str | None = None) -> dict[str, str]:
+    """Discover and fetch the three CSVs from the HF dataset repo.
+
+    Returns a dict {"patients"|"admissions"|"notes": local_path}.
+    """
+    from huggingface_hub import hf_hub_download, list_repo_files
+
+    files = [f for f in list_repo_files(REPO_ID, repo_type="dataset") if f.endswith(".csv")]
+    picked: dict[str, str] = {}
+    for f in files:
+        name = f.lower()
+        if "patient" in name and "patients" not in picked:
+            picked["patients"] = f
+        elif "admission" in name:
+            picked["admissions"] = f
+        elif "note" in name:
+            picked["notes"] = f
+    missing = {"patients", "admissions", "notes"} - picked.keys()
+    if missing:
+        raise RuntimeError(
+            f"Could not locate {missing} CSVs in {REPO_ID}. Found: {files}"
+        )
+    out: dict[str, str] = {}
+    for key, repo_path in picked.items():
+        out[key] = hf_hub_download(
+            REPO_ID, repo_path, repo_type="dataset", local_dir=local_dir
+        )
+    return out
+
+
+@lru_cache(maxsize=1)
+def load_tables(local_dir: str | None = None) -> tuple[pd.DataFrame, pd.DataFrame, pd.DataFrame]:
+    """Return (patients, admissions, notes) DataFrames.
+
+    Honours NOTEGUARD_DATA_DIR (a folder holding the three CSVs) so the demo can
+    run fully offline once the data is cached.
+    """
+    data_dir = local_dir or os.environ.get("NOTEGUARD_DATA_DIR")
+    if data_dir and os.path.isdir(data_dir):
+        def _read(*names):
+            for n in names:
+                p = os.path.join(data_dir, n)
+                if os.path.exists(p):
+                    return pd.read_csv(p, dtype=str, keep_default_na=False)
+            raise FileNotFoundError(f"None of {names} in {data_dir}")
+        patients = _read("patients.csv")
+        admissions = _read("admissions.csv")
+        notes = _read("synthetic_clinical_notes.csv", "notes.csv")
+    else:
+        paths = _download_csvs(local_dir=local_dir)
+        patients = pd.read_csv(paths["patients"], dtype=str, keep_default_na=False)
+        admissions = pd.read_csv(paths["admissions"], dtype=str, keep_default_na=False)
+        notes = pd.read_csv(paths["notes"], dtype=str, keep_default_na=False)
+    return patients, admissions, notes
+
+
+# generic values that are not identifying on their own — never treat as PII GT
+_GENERIC = {
+    "ward", "bay", "bed", "unit", "unknown", "none", "n/a", "na",
+    "male", "female", "trust", "hospital", "patient", "nil",
+}
+
+
+def _gt_from_row(row: pd.Series, df: pd.DataFrame, mapping: dict[str, str]) -> list[GroundTruthPII]:
+    out: list[GroundTruthPII] = []
+    for col, etype in mapping.items():
+        actual = _first_col(df, col)
+        if actual is None:
+            continue
+        val = _fix_mojibake(str(row.get(actual, "")).strip())
+        if not val or val.lower() in _GENERIC or len(val) < 2:
+            continue
+        out.append(GroundTruthPII(val, etype))
+    return out
+
+
+# which structured columns map to which entity type
+PATIENT_PII = {
+    "full_name": PERSON,
+    "nhs_number": UK_NHS,
+    "date_of_birth": DATE,
+}
+ADMISSION_PII = {
+    "patient_name": PERSON,
+    "first_name": PERSON,
+    "surname": PERSON,
+    "full_name": PERSON,
+    "nhs_number": UK_NHS,
+    "date_of_birth": DATE,
+    "site_name": LOCATION,
+    "ward": LOCATION,
+    "bed_location": LOCATION,
+}
+
+
+def load_notes(limit: int | None = None, local_dir: str | None = None) -> list[NoteRecord]:
+    """Build NoteRecords with ground-truth PII joined from patient/admission tables."""
+    patients, admissions, notes = load_tables(local_dir=local_dir)
+
+    pid_col = _first_col(patients, "person_id")
+    patients_idx = patients.set_index(pid_col) if pid_col else None
+
+    aid_col = _first_col(admissions, "admission_id")
+    admissions_idx = admissions.set_index(aid_col) if aid_col else None
+
+    text_col = _first_col(notes, "clean_note_text", "note_text", "text")
+    n_pid = _first_col(notes, "person_id", "patient_id")
+    n_aid = _first_col(notes, "admission_id")
+    nid_col = _first_col(notes, "clinical_note_id", "note_id")
+    ntype = _first_col(notes, "note_type")
+    nsubj = _first_col(notes, "note_subject")
+
+    records: list[NoteRecord] = []
+    rows = notes if limit is None else notes.head(limit)
+    for _, r in rows.iterrows():
+        pid = str(r.get(n_pid, "")) if n_pid else ""
+        aid = str(r.get(n_aid, "")) if n_aid else ""
+        gt: list[GroundTruthPII] = []
+        if patients_idx is not None and pid in patients_idx.index:
+            prow = patients_idx.loc[pid]
+            if isinstance(prow, pd.DataFrame):
+                prow = prow.iloc[0]
+            gt += _gt_from_row(prow, patients, PATIENT_PII)
+        if admissions_idx is not None and aid in admissions_idx.index:
+            arow = admissions_idx.loc[aid]
+            if isinstance(arow, pd.DataFrame):
+                arow = arow.iloc[0]
+            gt += _gt_from_row(arow, admissions, ADMISSION_PII)
+
+        # dedupe on (text, type)
+        gt = list({(g.text, g.entity_type): g for g in gt}.values())
+
+        records.append(
+            NoteRecord(
+                note_id=str(r.get(nid_col, "")) if nid_col else "",
+                person_id=pid,
+                admission_id=aid,
+                text=_fix_mojibake(str(r.get(text_col, ""))) if text_col else "",
+                note_type=str(r.get(ntype, "")) if ntype else "",
+                note_subject=str(r.get(nsubj, "")) if nsubj else "",
+                ground_truth=gt,
+            )
+        )
+    return records
+
+
+if __name__ == "__main__":
+    recs = load_notes(limit=5)
+    for rec in recs:
+        print(f"\n=== note {rec.note_id} (person {rec.person_id}) ===")
+        print(rec.text[:200].replace("\n", " "), "...")
+        print("  ground-truth PII:", [(g.text, g.entity_type) for g in rec.ground_truth])

work-process_yumi/noteguard/detect.py

@@ -0,0 +1,127 @@
+"""Detection layer.
+
+NoteGuard does not reinvent detection — Presidio is the engine. Our job is to
+(1) compose Presidio's NER with our transparent rule layer, (2) keep everything
+behind one `Detector` interface so the pipeline and eval are engine-agnostic, and
+(3) make detection degrade gracefully to pure-Python rules when spaCy/Presidio
+are unavailable.
+"""
+from __future__ import annotations
+
+import re
+from typing import Iterable, Protocol
+
+from .recognizers import Span, find_rule_spans
+
+
+class Detector(Protocol):
+    def detect(self, text: str) -> list[Span]: ...
+
+
+class RuleDetector:
+    """Pure-Python baseline. No external dependencies."""
+
+    name = "rules"
+
+    def detect(self, text: str) -> list[Span]:
+        return find_rule_spans(text)
+
+
+class PresidioDetector:
+    """Presidio AnalyzerEngine (spaCy NER + recognisers), unioned with our rules.
+
+    The rule layer is kept in the union because our NHS-number recogniser is
+    checksum-validated and our outputs stay auditable.
+    """
+
+    name = "presidio+rules"
+
+    # Presidio entity types we keep (already aligned to our vocabulary)
+    KEEP = {
+        "PERSON", "DATE_TIME", "EMAIL_ADDRESS", "PHONE_NUMBER",
+        "LOCATION", "UK_NHS", "UK_NINO", "IP_ADDRESS", "URL",
+    }
+
+    def __init__(self, spacy_model: str = "en_core_web_sm", score_threshold: float = 0.4):
+        from presidio_analyzer import AnalyzerEngine
+        from presidio_analyzer.nlp_engine import NlpEngineProvider
+
+        provider = NlpEngineProvider(nlp_configuration={
+            "nlp_engine_name": "spacy",
+            "models": [{"lang_code": "en", "model_name": spacy_model}],
+        })
+        self.engine = AnalyzerEngine(nlp_engine=provider.create_engine())
+        self.score_threshold = score_threshold
+
+    def detect(self, text: str) -> list[Span]:
+        results = self.engine.analyze(text=text, language="en")
+        spans = [
+            Span(r.start, r.end, r.entity_type, text[r.start:r.end], r.score)
+            for r in results
+            if r.entity_type in self.KEEP and r.score >= self.score_threshold
+        ]
+        spans += find_rule_spans(text)
+        return _merge(spans)
+
+
+class GazetteerDetector:
+    """Match a known list of names/sites (the roster a trust actually holds).
+
+    Catches identifiers the NER model misses (rare names, typo'd surnames) using
+    whole-word, case-insensitive matching. Used as an optional layer to show the
+    recall lift — not part of the headline eval, to avoid circularity.
+    """
+
+    name = "gazetteer"
+
+    def __init__(self, terms: Iterable[tuple[str, str]], min_len: int = 3):
+        self._patterns: list[tuple[re.Pattern, str]] = []
+        seen: set[str] = set()
+        for term, etype in terms:
+            term = (term or "").strip()
+            if len(term) < min_len or term.lower() in seen:
+                continue
+            seen.add(term.lower())
+            self._patterns.append(
+                (re.compile(rf"\b{re.escape(term)}\b", re.IGNORECASE), etype)
+            )
+
+    def detect(self, text: str) -> list[Span]:
+        spans: list[Span] = []
+        for pat, etype in self._patterns:
+            for m in pat.finditer(text):
+                spans.append(Span(m.start(), m.end(), etype, m.group(), 0.9))
+        return spans
+
+
+class CompositeDetector:
+    def __init__(self, *detectors: Detector):
+        self.detectors = detectors
+        self.name = "+".join(getattr(d, "name", "?") for d in detectors)
+
+    def detect(self, text: str) -> list[Span]:
+        spans: list[Span] = []
+        for d in self.detectors:
+            spans += d.detect(text)
+        return _merge(spans)
+
+
+def _merge(spans: list[Span]) -> list[Span]:
+    """Sort, then drop spans fully contained in a longer span (keep highest score)."""
+    spans = sorted(spans, key=lambda s: (s.start, -(s.end - s.start), -s.score))
+    kept: list[Span] = []
+    for s in spans:
+        if any(k.start <= s.start and s.end <= k.end for k in kept):
+            continue
+        kept.append(s)
+    return kept
+
+
+def build_detector(use_presidio: bool = True) -> Detector:
+    """Best available detector; falls back to rules if Presidio import fails."""
+    if use_presidio:
+        try:
+            return PresidioDetector()
+        except Exception as e:  # pragma: no cover - environment dependent
+            print(f"[noteguard] Presidio unavailable ({e}); falling back to rules.")
+    return RuleDetector()

work-process_yumi/noteguard/evaluate.py

@@ -0,0 +1,220 @@
+"""Evaluation harness — NoteGuard's 'reliable' pillar.
+
+Because the dataset's PII lives in structured tables, every note has ground-truth
+identifiers. We measure two things Presidio alone never reports:
+
+  1. Detection quality  : per-entity precision / recall / F1 against known PII.
+  2. Residual leakage   : after sanitisation, how many KNOWN identifiers still
+                          appear in the output text. This is the headline number —
+                          an honest, measurable re-identification risk.
+
+Caveat we state openly: precision is measured against *structured* PII only.
+A note may contain PII not present in the tables (e.g. a clinician's name); a
+correct detection of it counts here as a false positive, so reported precision is
+a conservative lower bound. Recall and leakage are unaffected.
+"""
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass, field
+from datetime import datetime
+
+from .data import NoteRecord
+from .detect import Detector
+from .recognizers import Span
+from .transform import REDACTION, PseudonymVault, apply_transform
+
+_DATE_FORMATS = ["%d/%m/%Y", "%d-%m-%Y", "%Y-%m-%d", "%d/%m/%y", "%d-%m-%y", "%d %b %Y", "%d %B %Y"]
+
+
+def _date_variants(value: str) -> list[str]:
+    for fmt in _DATE_FORMATS:
+        try:
+            dt = datetime.strptime(value.strip(), fmt)
+            return list({dt.strftime(f) for f in _DATE_FORMATS})
+        except ValueError:
+            continue
+    return [value]
+
+
+def value_variants(value: str, entity_type: str) -> list[str]:
+    """Surface forms of a known PII value as it might appear in free text."""
+    value = value.strip()
+    if not value:
+        return []
+    if entity_type == "PERSON":
+        parts = value.split()
+        out = [value]
+        if len(parts) > 1:
+            out.append(parts[-1])   # surname alone
+            out.append(parts[0])    # forename alone
+        return out
+    if entity_type == "UK_NHS":
+        digits = "".join(ch for ch in value if ch.isdigit())
+        out = {value, digits}
+        if len(digits) == 10:
+            out.add(f"{digits[:3]} {digits[3:6]} {digits[6:]}")
+            out.add(f"{digits[:3]}-{digits[3:6]}-{digits[6:]}")
+        return list(out)
+    if entity_type == "DATE_TIME":
+        return _date_variants(value)
+    return [value]
+
+
+def _find_all(haystack: str, needle: str) -> list[tuple[int, int]]:
+    """Case-insensitive, word-boundary-aware occurrences of needle in haystack."""
+    if not needle:
+        return []
+    hl, nl = haystack.lower(), needle.lower()
+    spots: list[tuple[int, int]] = []
+    start = 0
+    while True:
+        i = hl.find(nl, start)
+        if i == -1:
+            break
+        left_ok = i == 0 or not (hl[i - 1].isalnum())
+        right_ok = i + len(nl) == len(hl) or not (hl[i + len(nl)].isalnum())
+        if left_ok and right_ok:
+            spots.append((i, i + len(nl)))
+        start = i + 1
+    return spots
+
+
+def ground_truth_spans(record: NoteRecord) -> list[Span]:
+    """Locate each known PII value (and its surface variants) inside the note."""
+    occ: list[Span] = []
+    for gt in record.ground_truth:
+        for variant in value_variants(gt.text, gt.entity_type):
+            if len(variant) < 2:
+                continue
+            for s, e in _find_all(record.text, variant):
+                occ.append(Span(s, e, gt.entity_type, record.text[s:e]))
+    return _dedupe(occ)
+
+
+def _dedupe(spans: list[Span]) -> list[Span]:
+    seen: set[tuple[int, int]] = set()
+    out: list[Span] = []
+    for s in sorted(spans, key=lambda x: (x.start, -(x.end - x.start))):
+        if any(s.start >= a and s.end <= b for (a, b) in seen):
+            continue
+        seen.add((s.start, s.end))
+        out.append(s)
+    return out
+
+
+def _overlaps(a: Span, b: Span) -> bool:
+    return a.start < b.end and b.start < a.end
+
+
+@dataclass
+class Counter:
+    tp: int = 0
+    fp: int = 0
+    fn: int = 0
+
+    @property
+    def precision(self) -> float:
+        return self.tp / (self.tp + self.fp) if (self.tp + self.fp) else 0.0
+
+    @property
+    def recall(self) -> float:
+        return self.tp / (self.tp + self.fn) if (self.tp + self.fn) else 0.0
+
+    @property
+    def f1(self) -> float:
+        p, r = self.precision, self.recall
+        return 2 * p * r / (p + r) if (p + r) else 0.0
+
+
+@dataclass
+class EvalResult:
+    notes: int = 0
+    per_entity: dict[str, Counter] = field(default_factory=lambda: defaultdict(Counter))
+    overall: Counter = field(default_factory=Counter)
+    total_gt_occurrences: int = 0
+    residual_leaks: int = 0
+    transform_method: str = REDACTION
+    detector_name: str = ""
+
+    @property
+    def leakage_rate(self) -> float:
+        return self.residual_leaks / self.total_gt_occurrences if self.total_gt_occurrences else 0.0
+
+    def to_dict(self) -> dict:
+        return {
+            "detector": self.detector_name,
+            "transform": self.transform_method,
+            "notes_evaluated": self.notes,
+            "detection": {
+                "overall": {
+                    "precision": round(self.overall.precision, 4),
+                    "recall": round(self.overall.recall, 4),
+                    "f1": round(self.overall.f1, 4),
+                    "tp": self.overall.tp, "fp": self.overall.fp, "fn": self.overall.fn,
+                },
+                "per_entity": {
+                    et: {
+                        "precision": round(c.precision, 4),
+                        "recall": round(c.recall, 4),
+                        "f1": round(c.f1, 4),
+                        "support": c.tp + c.fn,
+                    }
+                    for et, c in sorted(self.per_entity.items())
+                },
+            },
+            "leakage": {
+                "total_known_pii_occurrences": self.total_gt_occurrences,
+                "residual_leaks_after_sanitisation": self.residual_leaks,
+                "leakage_rate": round(self.leakage_rate, 4),
+                "leakage_rate_pct": round(100 * self.leakage_rate, 2),
+            },
+        }
+
+
+def evaluate(
+    records: list[NoteRecord],
+    detector: Detector,
+    transform_method: str = REDACTION,
+) -> EvalResult:
+    res = EvalResult(transform_method=transform_method, detector_name=getattr(detector, "name", "?"))
+    for rec in records:
+        if not rec.text:
+            continue
+        res.notes += 1
+        gt = ground_truth_spans(rec)
+        detected = detector.detect(rec.text)
+
+        # ---- detection precision / recall (overlap-based) ----
+        matched_det: set[int] = set()
+        for g in gt:
+            hit = next((i for i, d in enumerate(detected)
+                        if i not in matched_det and _overlaps(g, d)), None)
+            if hit is not None:
+                matched_det.add(hit)
+                res.per_entity[g.entity_type].tp += 1
+                res.overall.tp += 1
+            else:
+                res.per_entity[g.entity_type].fn += 1
+                res.overall.fn += 1
+        for i, d in enumerate(detected):
+            if i not in matched_det:
+                res.per_entity[d.entity_type].fp += 1
+                res.overall.fp += 1
+
+        # ---- residual leakage after sanitisation ----
+        vault = PseudonymVault()
+        sanitised, _ = apply_transform(
+            rec.text, detected, transform_method, vault, rec.person_id
+        )
+        res.total_gt_occurrences += len(gt)
+        # a known value leaks if any of its surface variants survives in output
+        for g in gt:
+            leaked = False
+            for variant in value_variants(g.text, g.entity_type):
+                if len(variant) >= 2 and _find_all(sanitised, variant):
+                    leaked = True
+                    break
+            if leaked:
+                res.residual_leaks += 1
+    return res

work-process_yumi/noteguard/pipeline.py

@@ -0,0 +1,40 @@
+"""End-to-end single-note pipeline: detect -> de-identify -> audit.
+
+This is the unit the demo UI and the CLI both call.
+"""
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass, field
+
+from .detect import Detector, build_detector
+from .recognizers import Span
+from .transform import REDACTION, PseudonymVault, Replacement, apply_transform
+
+
+@dataclass
+class SanitiseResult:
+    original: str
+    sanitised: str
+    spans: list[Span]
+    replacements: list[Replacement]
+    method: str
+    audit: dict = field(default_factory=dict)
+
+
+class Pipeline:
+    def __init__(self, detector: Detector | None = None, vault: PseudonymVault | None = None):
+        self.detector = detector or build_detector()
+        self.vault = vault or PseudonymVault()
+
+    def sanitise(self, text: str, method: str = REDACTION, person_id: str = "") -> SanitiseResult:
+        spans = self.detector.detect(text)
+        sanitised, repls = apply_transform(text, spans, method, self.vault, person_id)
+        by_type = Counter(s.entity_type for s in spans)
+        audit = {
+            "detector": getattr(self.detector, "name", "?"),
+            "method": method,
+            "entities_removed": sum(by_type.values()),
+            "by_type": dict(by_type),
+        }
+        return SanitiseResult(text, sanitised, spans, repls, method, audit)

work-process_yumi/noteguard/recognizers.py

@@ -0,0 +1,106 @@
+"""Pure-Python rule recognisers — no spaCy / Presidio dependency.
+
+These give NoteGuard a transparent, auditable baseline that runs anywhere, and
+let the evaluation harness work even before the (heavier) NER engine is wired up.
+The NHS-number recogniser validates the mod-11 check digit so random 10-digit
+strings (dose volumes, IDs) aren't flagged as patient identifiers.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from .data import DATE, LOCATION, PERSON, UK_NHS  # noqa: F401  (re-exported types)
+
+EMAIL = "EMAIL_ADDRESS"
+PHONE = "PHONE_NUMBER"
+POSTCODE = "UK_POSTCODE"
+
+
+@dataclass(frozen=True)
+class Span:
+    start: int
+    end: int
+    entity_type: str
+    text: str
+    score: float = 1.0
+
+
+def nhs_number_is_valid(digits: str) -> bool:
+    """Validate a 10-digit NHS number using the Modulus 11 check-digit algorithm."""
+    d = re.sub(r"\D", "", digits)
+    if len(d) != 10:
+        return False
+    total = sum(int(d[i]) * (10 - i) for i in range(9))
+    remainder = total % 11
+    check = 11 - remainder
+    if check == 11:
+        check = 0
+    if check == 10:
+        return False  # never valid
+    return check == int(d[9])
+
+
+# Real NHS numbers are 10 digits with a mod-11 check digit, optionally grouped.
+_NHS_RE = re.compile(r"\b\d{3}[ -]?\d{3}[ -]?\d{4}\b")
+# Context-anchored: an "NHS ..." label followed by a 9-10 digit number. Needed
+# because this synthetic dataset uses 9-digit NHS numbers (no valid checksum),
+# which neither the checksum rule nor Presidio's UK_NHS recogniser would catch.
+_NHS_CTX_RE = re.compile(
+    r"NHS\s*(?:Number|No\.?|#)?\s*[:\-]?\s*(\d{3}[ -]?\d{3}[ -]?\d{2,4})",
+    re.IGNORECASE,
+)
+_EMAIL_RE = re.compile(r"\b[\w.+-]+@[\w-]+\.[\w.-]+\b")
+_PHONE_RE = re.compile(r"\b(?:\+?44\s?|0)(?:\d\s?){9,10}\b")
+# UK postcode (simplified but standard) e.g. SW1A 1AA, M1 1AE
+_POSTCODE_RE = re.compile(
+    r"\b[A-Z]{1,2}\d[A-Z\d]?\s*\d[A-Z]{2}\b", re.IGNORECASE
+)
+_DATE_RE = re.compile(
+    r"\b(\d{1,2}[/-]\d{1,2}[/-]\d{2,4}"
+    r"|\d{4}-\d{2}-\d{2}"
+    r"|\d{1,2}\s+(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)[a-z]*\.?\s+\d{2,4})\b",
+    re.IGNORECASE,
+)
+
+
+def find_rule_spans(text: str) -> list[Span]:
+    spans: list[Span] = []
+
+    for m in _NHS_RE.finditer(text):
+        if nhs_number_is_valid(m.group()):
+            spans.append(Span(m.start(), m.end(), UK_NHS, m.group()))
+    # context-anchored NHS numbers (catches the 9-digit synthetic ones)
+    for m in _NHS_CTX_RE.finditer(text):
+        spans.append(Span(m.start(1), m.end(1), UK_NHS, m.group(1)))
+
+    for regex, etype in (
+        (_EMAIL_RE, EMAIL),
+        (_PHONE_RE, PHONE),
+        (_POSTCODE_RE, POSTCODE),
+        (_DATE_RE, DATE),
+    ):
+        for m in regex.finditer(text):
+            spans.append(Span(m.start(), m.end(), etype, m.group()))
+
+    return _dedupe(spans)
+
+
+def _dedupe(spans: list[Span]) -> list[Span]:
+    """Drop spans fully contained within another (keep the longer match)."""
+    spans = sorted(spans, key=lambda s: (s.start, -(s.end - s.start)))
+    kept: list[Span] = []
+    for s in spans:
+        if any(k.start <= s.start and s.end <= k.end for k in kept):
+            continue
+        kept.append(s)
+    return kept
+
+
+if __name__ == "__main__":
+    # quick check: 9434765919 is a documented valid NHS test number
+    assert nhs_number_is_valid("943 476 5919"), "valid NHS number rejected"
+    assert not nhs_number_is_valid("943 476 5918"), "bad check digit accepted"
+    demo = "NHS no 943 476 5919, ring 07700 900123, dob 12/03/1981, SW1A 1AA."
+    for sp in find_rule_spans(demo):
+        print(sp)

work-process_yumi/noteguard/transform.py

@@ -0,0 +1,129 @@
+"""De-identification transforms.
+
+Presidio anonymises per-document; the value NoteGuard adds is *cross-note,
+patient-consistent* de-identification — the same patient maps to the same
+surrogate across their whole admission journey, and their dates are shifted by a
+single consistent offset so intervals (and therefore clinical timelines) survive.
+That utility-preserving longitudinal property is what makes the cleaned data
+useful for downstream / federated training instead of just safe.
+"""
+from __future__ import annotations
+
+import hashlib
+import re
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+
+from .recognizers import Span
+
+REDACTION = "redaction"
+PSEUDONYM = "pseudonym"
+
+_DATE_FORMATS = ["%d/%m/%Y", "%d-%m-%Y", "%Y-%m-%d", "%d/%m/%y", "%d-%m-%y"]
+
+
+@dataclass
+class Replacement:
+    original: str
+    replacement: str
+    entity_type: str
+
+
+@dataclass
+class PseudonymVault:
+    """Stable original-value -> surrogate mapping (the 'mapping vault')."""
+    _map: dict[tuple[str, str], str] = field(default_factory=dict)
+    _counts: dict[str, int] = field(default_factory=dict)
+
+    def token_for(self, entity_type: str, value: str) -> str:
+        key = (entity_type, value.strip().lower())
+        if key not in self._map:
+            self._counts[entity_type] = self._counts.get(entity_type, 0) + 1
+            n = self._counts[entity_type]
+            if entity_type == "PERSON":
+                surrogate = f"Patient_{n:03d}"
+            elif entity_type == "UK_NHS":
+                surrogate = _fake_nhs_number(value)
+            else:
+                surrogate = f"{entity_type}_{n:03d}"
+            self._map[key] = surrogate
+        return self._map[key]
+
+    def export(self) -> dict[str, str]:
+        """Audit/export of the vault (keep this secret in production)."""
+        return {f"{etype}:{val}": tok for (etype, val), tok in self._map.items()}
+
+
+def _patient_date_offset(person_id: str, max_days: int = 365) -> int:
+    """Deterministic per-patient shift in [-max_days, max_days], from person_id."""
+    h = int(hashlib.sha256(f"noteguard:{person_id}".encode()).hexdigest(), 16)
+    return (h % (2 * max_days + 1)) - max_days
+
+
+def _fake_nhs_number(value: str) -> str:
+    """Deterministic, checksum-VALID fake NHS number (stable per original)."""
+    from .recognizers import nhs_number_is_valid
+
+    seed = int(hashlib.sha256(value.encode()).hexdigest(), 16)
+    for _ in range(1000):
+        nine = f"{seed % 1_000_000_000:09d}"
+        total = sum(int(nine[i]) * (10 - i) for i in range(9))
+        check = 11 - (total % 11)
+        check = 0 if check == 11 else check
+        if check != 10:
+            candidate = nine + str(check)
+            if nhs_number_is_valid(candidate):
+                return candidate
+        seed = (seed * 1103515245 + 12345) & ((1 << 64) - 1)
+    return "0000000000"
+
+
+def _shift_date(value: str, offset_days: int) -> str | None:
+    for fmt in _DATE_FORMATS:
+        try:
+            dt = datetime.strptime(value.strip(), fmt)
+            return (dt + timedelta(days=offset_days)).strftime(fmt)
+        except ValueError:
+            continue
+    return None
+
+
+def apply_transform(
+    text: str,
+    spans: list[Span],
+    method: str = REDACTION,
+    vault: PseudonymVault | None = None,
+    person_id: str = "",
+) -> tuple[str, list[Replacement]]:
+    """Return (sanitised_text, replacements). Spans applied right-to-left."""
+    vault = vault or PseudonymVault()
+    offset = _patient_date_offset(person_id) if person_id else 0
+    out = text
+    used: list[Replacement] = []
+    for s in sorted(spans, key=lambda x: x.start, reverse=True):
+        original = text[s.start:s.end]
+        if method == REDACTION:
+            repl = f"[{s.entity_type}]"
+        else:  # PSEUDONYM
+            if s.entity_type == "DATE_TIME":
+                shifted = _shift_date(original, offset)
+                repl = shifted if shifted else "[DATE_TIME]"
+            else:
+                repl = vault.token_for(s.entity_type, original)
+        out = out[:s.start] + repl + out[s.end:]
+        used.append(Replacement(original, repl, s.entity_type))
+    used.reverse()
+    return out, used
+
+
+if __name__ == "__main__":
+    from .recognizers import find_rule_spans
+
+    txt = "Pt John seen 12/03/1981, NHS 943 476 5919. Reviewed again 20/03/1981."
+    spans = find_rule_spans(txt)
+    for method in (REDACTION, PSEUDONYM):
+        v = PseudonymVault()
+        new, repls = apply_transform(txt, spans, method, v, person_id="p7")
+        print(f"\n[{method}] {new}")
+        for r in repls:
+            print("   ", r.original, "->", r.replacement, f"({r.entity_type})")

work-process_yumi/requirements.txt

@@ -0,0 +1,6 @@
+pandas>=2.0
+huggingface_hub>=0.23
+presidio-analyzer>=2.2
+presidio-anonymizer>=2.2
+spacy>=3.7
+gradio>=4.0

work-process_yumi/results.json

@@ -0,0 +1,61 @@
+{
+  "presidio+rules": {
+    "detector": "presidio+rules",
+    "transform": "redaction",
+    "notes_evaluated": 500,
+    "detection": {
+      "overall": {
+        "precision": 0.0678,
+        "recall": 0.7752,
+        "f1": 0.1247,
+        "tp": 238,
+        "fp": 3271,
+        "fn": 69
+      },
+      "per_entity": {
+        "DATE_TIME": {
+          "precision": 0.0171,
+          "recall": 1.0,
+          "f1": 0.0336,
+          "support": 25
+        },
+        "LOCATION": {
+          "precision": 0.0,
+          "recall": 0.0,
+          "f1": 0.0,
+          "support": 0
+        },
+        "PERSON": {
+          "precision": 0.088,
+          "recall": 0.6937,
+          "f1": 0.1562,
+          "support": 222
+        },
+        "PHONE_NUMBER": {
+          "precision": 0.0,
+          "recall": 0.0,
+          "f1": 0.0,
+          "support": 0
+        },
+        "UK_NHS": {
+          "precision": 0.9833,
+          "recall": 0.9833,
+          "f1": 0.9833,
+          "support": 60
+        },
+        "URL": {
+          "precision": 0.0,
+          "recall": 0.0,
+          "f1": 0.0,
+          "support": 0
+        }
+      }
+    },
+    "leakage": {
+      "total_known_pii_occurrences": 307,
+      "residual_leaks_after_sanitisation": 14,
+      "leakage_rate": 0.0456,
+      "leakage_rate_pct": 4.56
+    }
+  }
+}

work-process_yumi/run_eval.py

@@ -0,0 +1,70 @@
+"""Run the NoteGuard evaluation over the NHSE synthetic dataset.
+
+    python run_eval.py --limit 300            # quick run
+    python run_eval.py --method pseudonym     # leakage under pseudonymisation
+    python run_eval.py --compare              # rules-only vs presidio+rules
+
+Writes results.json (consumed by the demo's metrics panel) and prints a summary.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+
+from noteguard.data import load_notes
+from noteguard.detect import RuleDetector, build_detector
+from noteguard.evaluate import EvalResult, evaluate
+from noteguard.transform import REDACTION
+
+
+def _print_summary(res: EvalResult) -> None:
+    d = res.to_dict()
+    print(f"\n  detector : {d['detector']}")
+    print(f"  transform: {d['transform']}   notes: {d['notes_evaluated']}")
+    ov = d["detection"]["overall"]
+    print(f"  detection  P={ov['precision']:.3f}  R={ov['recall']:.3f}  F1={ov['f1']:.3f}")
+    print("  per-entity:")
+    for et, m in d["detection"]["per_entity"].items():
+        print(f"     {et:<14} P={m['precision']:.3f} R={m['recall']:.3f} "
+              f"F1={m['f1']:.3f}  (support={m['support']})")
+    lk = d["leakage"]
+    print(f"  >> RESIDUAL LEAKAGE: {lk['residual_leaks_after_sanitisation']}"
+          f"/{lk['total_known_pii_occurrences']} = {lk['leakage_rate_pct']:.2f}%")
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--limit", type=int, default=300, help="max notes (None=all)")
+    ap.add_argument("--method", default=REDACTION, choices=["redaction", "pseudonym"])
+    ap.add_argument("--no-presidio", action="store_true", help="rules only")
+    ap.add_argument("--compare", action="store_true", help="rules vs presidio+rules")
+    ap.add_argument("--out", default="results.json")
+    args = ap.parse_args()
+
+    print(f"[noteguard] loading notes (limit={args.limit}) ...")
+    records = load_notes(limit=args.limit)
+    print(f"[noteguard] {len(records)} notes; "
+          f"{sum(len(r.ground_truth) for r in records)} known PII values joined.")
+
+    runs: dict[str, EvalResult] = {}
+    if args.compare:
+        print("\n=== rules-only ===")
+        runs["rules"] = evaluate(records, RuleDetector(), args.method)
+        _print_summary(runs["rules"])
+        print("\n=== presidio+rules ===")
+        runs["presidio+rules"] = evaluate(records, build_detector(True), args.method)
+        _print_summary(runs["presidio+rules"])
+    else:
+        det = RuleDetector() if args.no_presidio else build_detector(True)
+        res = evaluate(records, det, args.method)
+        _print_summary(res)
+        runs[res.detector_name] = res
+
+    payload = {name: r.to_dict() for name, r in runs.items()}
+    with open(args.out, "w") as f:
+        json.dump(payload, f, indent=2)
+    print(f"\n[noteguard] wrote {args.out}")
+
+
+if __name__ == "__main__":
+    main()