Refactor to Gold-RAP structure: src/ package, tests/, docs/, data/, output/

Structure
- Rename package noteguard/ -> src/; British spelling recognizers -> recognisers
(file, method, and all imports; Presidio's add_recognizer untouched).
- Streamlit app moved to repo root (streamlit_app.py); run_eval.py -> tests/.
- Generated artifacts now write to output/ (was data/out/).

Declutter
- Remove empty app/ and experiments/ dirs, the committed results.json, and the
stale docs/failed_experiments.md. Update docs/tool_card.md.

Gold RAP ("analysis as a product")
- pyproject.toml: pip-installable package + ruff/pytest config.
- CI (.github/workflows/ci.yml) runs ruff + pytest on push/PR.
- CHANGELOG.md; logging in the eval entry point.

Notes
- src/ stays one cohesive package (its modules import each other); evaluate.py is a
library used by both src/trust_demo.py and tests/run_eval.py, so both are kept.

Verified: pip install -e ".[dev]"; ruff clean; 23 tests pass; run_eval writes output/results.json.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.claude/skills/run-evaluation/SKILL.md

@@ -7,8 +7,8 @@ description: How to run the NoteGuard evaluation (detection P/R/F1 + residual le
 The eval is the project's pass/fail signal — it proves sanitisation actually removes PII, with numbers.
 
 1. Data: either `NOTEGUARD_DATA_DIR=<folder with the 3 CSVs>` (offline) or let it auto-download from HF.
-2. Run `python run_eval.py --compare --limit 300` (use a larger `--limit` for the headline; `--method
-   pseudonym` to measure leakage under pseudonymisation). Writes `results.json`.
+2. Run `python tests/run_eval.py --compare --limit 300` (use a larger `--limit` for the headline;
+   `--method pseudonym` to measure leakage under pseudonymisation). Writes `output/results.json`.
 3. It joins each note to its patient/admission record (the EVAL-ONLY oracle) to get ground truth, then
    reports, per detector:
    - **detection P / R / F1** per entity type (precision is a conservative lower bound — removing PII
@@ -18,7 +18,7 @@ The eval is the project's pass/fail signal — it proves sanitisation actually r
 ## How to read it
 - `--compare` prints two rows: **rules** → **presidio+rules** (the shipping detector). The leakage
   should drop sharply between them.
-- Watch residual leakage as the headline. If it regresses after a change to `noteguard/recognizers.py`,
+- Watch residual leakage as the headline. If it regresses after a change to `src/recognisers.py`,
   `detect.py`, or `transform.py`, fix it before continuing.
 
 Log anything that didn't work in `experiments/FAILED.md`.

.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main, "dev/**", "feat/**"]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install package + dev tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Lint (ruff)
+        run: ruff check .
+      - name: Unit tests (pytest)
+        run: pytest -q

.gitignore

@@ -1,14 +1,19 @@
-# NHS PHI safety: raw data, de-identified output, and the re-identification vault NEVER leave the repo
-data/raw/
-data/out/
+# NHS PHI safety: raw data, generated output, and the re-identification vault NEVER leave the repo
+data/*
+!data/.gitkeep
+output/*
+!output/.gitkeep
 *.vault.json
 
-# Python
+# Python / packaging
 .venv/
 __pycache__/
 *.pyc
 .pytest_cache/
+.ruff_cache/
 *.egg-info/
+build/
+dist/
 
 # macOS / zip extraction junk
 .DS_Store

CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes are documented here. Format follows [Keep a Changelog](https://keepachangelog.com);
+the project uses [semantic versioning](https://semver.org).
+
+## [1.0.0] — 2026-06-20
+
+Gold-RAP restructure ("analysis as a product").
+
+### Added
+- Standard RAP directory layout: `src/` (package), `tests/` (unit tests + `run_eval.py`),
+  `docs/`, `data/` (inputs), `output/` (generated artifacts).
+- `pyproject.toml` — the project is now pip-installable (`pip install -e .`).
+- Continuous integration (`.github/workflows/ci.yml`) running `ruff` + `pytest` on every push/PR.
+- `ruff` lint configuration and `logging` in the evaluation entry point.
+- This changelog.
+
+### Changed
+- Renamed the package `noteguard/` → `src/`; all imports updated to `src.*`.
+- Generated outputs (metrics, two-Trust artifacts) now write to `output/` instead of `data/out/`.
+- `run_eval.py` moved under `tests/` as the evaluation entry point.
+
+### Removed
+- Decluttered `experiments/` (failure log moved to `docs/failed_experiments.md`).
+- Removed the committed `results.json` artifact (now regenerated into `output/`, gitignored).

CLAUDE.md

@@ -9,29 +9,29 @@ data leaves a Trust. Encode Club "Trusted Data & AI Infrastructure" hackathon; f
 python -m venv .venv; .\.venv\Scripts\Activate.ps1
 pip install -r requirements.txt; python -m spacy download en_core_web_lg
 
-python run_eval.py --compare --limit 300   # VERIFIABLE SIGNAL: rules vs presidio+rules -> results.json
-python -m noteguard.trust_demo             # two NHS Trusts share only de-identified data -> data/out/
-streamlit run app/streamlit_app.py         # demo (Try-it / Metrics / Governance / Two-Trust)
+python tests/run_eval.py --compare --limit 300   # VERIFIABLE SIGNAL: rules vs presidio+rules -> output/results.json
+python -m src.trust_demo                          # two NHS Trusts share only de-identified data -> output/
+streamlit run streamlit_app.py                    # demo (Try-it / Metrics / Governance / Two-Trust)
 python -m pytest tests/ -v
 
 # Offline data: set NOTEGUARD_DATA_DIR to a folder holding the 3 CSVs (else auto-downloaded from HF).
 ```
 
 ## Architecture
-- `noteguard/` — `data` (load + ground-truth join, EVAL-ONLY oracle) · `recognizers` (pure-Python
+- `src/` — `data` (load + ground-truth join, EVAL-ONLY oracle) · `recognisers` (pure-Python
   rules) · `detect` (Rule / Presidio, graceful fallback) · `transform`
   (redact | patient-consistent pseudonymise + date-shift, Faker) · `evaluate` (P/R/F1 + residual
   leakage) · `pipeline` · `trust_demo`.
-- `run_eval.py` CLI · `app/streamlit_app.py` demo · `tests/` mirror `noteguard/`.
+- `tests/run_eval.py` CLI · `streamlit_app.py` demo · `tests/` mirror `src/`. Packaged via `pyproject.toml`.
 
 ## Code style
 - Python 3.10+, type hints on function signatures. The pure-Python rule layer must stay importable
   WITHOUT spaCy/Presidio (the fallback path). snake_case / PascalCase.
 
 ## Data rules (treat the synthetic notes as if real NHS PHI)
-- `data/raw/`, `data/out/`, and any vault export are gitignored — never commit. Never paste note text
+- `data/raw/`, `output/`, and any vault export are gitignored — never commit. Never paste note text
   into prompts; point at file paths.
-- The note→patient join (`noteguard/data.py` ground truth) is the EVAL-ONLY oracle. It must NEVER feed
+- The note→patient join (`src/data.py` ground truth) is the EVAL-ONLY oracle. It must NEVER feed
   detection/transform — that is data leakage and invalidates the metric.
 - Never silently fall back to an older/cached dataset — fail loudly.
 
@@ -54,6 +54,5 @@ python -m pytest tests/ -v
 - Default spaCy model is now `en_core_web_lg`; the `PII_SPACY_MODEL` env var still overrides.
 
 ## Working with Claude
-- After editing `noteguard/recognizers.py` / `detect.py` / `transform.py`, run
-  `python run_eval.py --compare` and check residual leakage didn't regress. Log dead ends in
-  `experiments/FAILED.md`.
+- After editing `src/recognisers.py` / `detect.py` / `transform.py`, run
+  `python tests/run_eval.py --compare` and check residual leakage didn't regress.

README.md

@@ -62,11 +62,23 @@ The rules→engine drop is the headline: it shows, with numbers, exactly what th
                                            └────────────────────────────┘
 ```
 
-`noteguard/` — `data` (load + ground-truth join, **eval-only oracle**) · `recognizers` (pure-Python
-rules: NHS checksum/context, postcode, date, phone, email, GMC/NMC/ODS, UUID) · `detect`
-(`RuleDetector` / `PresidioDetector`) · `transform`
-(redaction | patient-consistent pseudonymisation + date-shift, Faker vault) · `evaluate` (P/R/F1 +
-residual leakage) · `pipeline` · `trust_demo`.
+**Project layout** (Gold-RAP "analysis as a product"):
+
+```
+src/                 the package
+  data.py            load CSVs + ground-truth join (EVAL-ONLY oracle)
+  recognisers.py     pure-Python rules: NHS checksum/context, postcode, date, phone, email, GMC/NMC/ODS, UUID
+  detect.py          RuleDetector / PresidioDetector behind one Detector interface
+  transform.py       redaction | patient-consistent pseudonymisation + DOB date-shift (Faker vault)
+  pipeline.py        single-note detect -> sanitise -> audit
+  evaluate.py        detection P/R/F1 + residual-leakage metric
+  trust_demo.py      two-Trust sanitise-at-source demo
+tests/               unit tests + run_eval.py (the evaluation CLI)
+docs/                tool card + project docs
+data/                input CSVs (gitignored)
+output/              generated artifacts: results.json, manifests (gitignored)
+streamlit_app.py     the demo UI            pyproject.toml   packaging + lint/test config
+```
 
 ## Trust & governance — mapped to the NHS Five Safes
 - **Safe data** — PII removed to DAPB1523/ICO standard across patient + staff + org identifiers.
@@ -78,19 +90,36 @@ residual leakage) · `pipeline` · `trust_demo`.
 ## Run it
 
 ```bash
-python -m venv .venv; .\.venv\Scripts\Activate.ps1      # Windows PowerShell
-pip install -r requirements.txt
-python -m spacy download en_core_web_sm
-
-python run_eval.py --compare --limit 300   # reproduce the table → results.json
-python -m noteguard.trust_demo             # two NHS Trusts share only de-identified data → data/out/
-streamlit run app/streamlit_app.py         # demo: Try-it · Metrics · Governance · Two-Trust
-python -m pytest tests/ -v
+# 1) create AND activate the virtual environment
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1        # Windows PowerShell
+# source .venv/Scripts/activate     #   ... or Windows Git Bash
+# source .venv/bin/activate         #   ... or macOS / Linux
+
+# 2) install the package (editable) + the spaCy model
+pip install -e ".[app,dev]"
+python -m spacy download en_core_web_lg   # or en_core_web_sm for a faster, lighter run
+
+# 3) run
+python tests/run_eval.py --compare --limit 300   # reproduce the table -> output/results.json
+python -m src.trust_demo                          # two NHS Trusts share only de-identified data -> output/
+streamlit run streamlit_app.py                    # demo: Try-it · Metrics · Governance · Two-Trust
+pytest -q                                          # unit tests
 ```
 
 The dataset 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`.
 
+## Deploy the live demo (Hugging Face Spaces)
+
+```bash
+pip install -U huggingface_hub      # provides the `hf` CLI
+hf auth login                        # paste a WRITE token from https://huggingface.co/settings/tokens
+hf repos create <user>/noteguard --repo-type space --space-sdk docker
+git remote add space https://huggingface.co/spaces/<user>/noteguard
+git push space HEAD:main             # builds the image and serves streamlit_app.py
+```
+
 ## Data notes (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.

data/.gitkeep

@@ -0,0 +1 @@
+# Input data lives here (e.g. data/raw/...). Contents are gitignored — never commit PHI.

docs/tool_card.md

@@ -31,7 +31,7 @@ NoteGuard is a **de-identification gate** for free-text NHS clinical notes. It d
 | Patient name (`PERSON`) | spaCy `en_core_web_lg` NER | 100% recall in benchmarks |
 | NHS number (`UK_NHS`) | Regex + Modulus-11 checksum + 9-digit context anchor | Catches both standard and synthetic dataset forms |
 | Date of birth (`DATE_TIME`) | Presidio + date regex | 100% recall |
-| Site / hospital name (`LOCATION`, `ORGANIZATION`) | spaCy NER + rule-based suffix anchor | "X Hospital / Infirmary / NHS Trust" patterns |
+| Site / hospital name (`LOCATION`) | spaCy NER + rule-based suffix anchor | "X Hospital / Infirmary / NHS Trust" patterns (ORGANIZATION is excluded — it over-tags labels) |
 | UK postcode (`UK_POSTCODE`) | Regex | Outward-code only after pseudonymisation |
 | Clinician GMC / NMC (`GMC`, `NMC`) | Context-anchored regex | "GMC 1234567", "NMC PIN 12A3456B" |
 | ODS org code (`NHS_ODS`) | Context-anchored regex | "ODS A12345", "Practice Code A12345" |
@@ -92,7 +92,7 @@ This matches the real NHS Information Governance workflow and makes the tool's a
 - **Pseudonymised data is still personal data** under UK GDPR — the vault is the re-identification key and must stay Trust-local.
 - **Precision is a conservative lower bound**: clinician names and unlisted locations correctly detected count as false positives in the evaluation (ground truth is patient-table-only).
 - **Not clinically validated**: evaluated on the `NHSEDataScience/synthetic_clinical_notes` dataset. Real deployment requires validation on representative Trust data.
-- **Clinical transformer models** (e.g. `obi/deid_roberta_i2b2`) were tested and performed worse on UK names than `en_core_web_lg` (i2b2 training data is US-centric). See `experiments/FAILED.md`.
+- **Clinical transformer models** (e.g. `obi/deid_roberta_i2b2`) were tested and performed worse on UK names than `en_core_web_lg` (i2b2 training data is US-centric).
 
 ---
 

experiments/FAILED.md

@@ -1,17 +0,0 @@
-# Failed experiments / dead ends
-
-Log approaches that did not work so we don't repeat them. One entry per attempt:
-what we tried, why it failed, what we did instead.
-
-## Assumed UK_POSTCODE / UK_NINO / UK_PASSPORT / UK_VEHICLE_REGISTRATION were Presidio built-ins
-The supported-entities docs list these as UK entities, so the plan said "enable built-ins". But the
-released `presidio-analyzer==2.2.362` only ships `UK_NHS` (verified via `get_supported_entities()` ->
-only `UK_NHS` under UK). A leakage test caught `SW1A 1AA` surviving. Fix: added custom recognizers in
-`src/recognizers/uk_entities.py` emitting the same entity names. Lesson: verify the installed version's
-recognizers, don't trust the docs page (which tracks `main`).
-
-<!-- Example:
-## spaCy en_core_web_sm alone for names
-Tried relying only on NER for PERSON detection. Missed "Surname, First Middle" forms common in the
-notes, leaking names. Fix: added the roster lookup recognizer (src/recognizers/roster.py) as a backstop.
--->

output/.gitkeep

@@ -0,0 +1 @@
+# Generated artifacts (results.json, two-Trust manifests) are written here. Contents are gitignored.

pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "noteguard"
+version = "1.0.0"
+description = "Sanitise-at-source PII removal for NHS clinical notes (Presidio + spaCy)"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+dependencies = [
+    "presidio-analyzer",
+    "presidio-anonymizer",
+    "spacy>=3.7,<3.9",
+    "faker",
+    "ftfy",
+    "huggingface_hub",
+    "pandas",
+]
+
+[project.optional-dependencies]
+app = ["streamlit"]
+dev = ["pytest", "ruff"]
+
+[tool.setuptools]
+packages = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP"]
+ignore = ["E501"]  # long descriptive lines/docstrings tolerated

results.json

@@ -1,203 +0,0 @@
-{
-  "rules": {
-    "detector": "rules",
-    "transform": "redaction",
-    "notes_evaluated": 1602,
-    "detection": {
-      "overall": {
-        "precision": 0.1031,
-        "recall": 0.2522,
-        "f1": 0.1464,
-        "tp": 259,
-        "fp": 2252,
-        "fn": 768
-      },
-      "per_entity": {
-        "DATE_TIME": {
-          "precision": 0.0739,
-          "recall": 1.0,
-          "f1": 0.1377,
-          "support": 84
-        },
-        "GMC": {
-          "precision": 0.0,
-          "recall": 0.0,
-          "f1": 0.0,
-          "support": 0
-        },
-        "NMC": {
-          "precision": 0.0,
-          "recall": 0.0,
-          "f1": 0.0,
-          "support": 0
-        },
-        "PERSON": {
-          "precision": 0.0,
-          "recall": 0.0,
-          "f1": 0.0,
-          "support": 764
-        },
-        "RECORD_ID": {
-          "precision": 0.0,
-          "recall": 0.0,
-          "f1": 0.0,
-          "support": 0
-        },
-        "UK_NHS": {
-          "precision": 0.9777,
-          "recall": 0.9777,
-          "f1": 0.9777,
-          "support": 179
-        }
-      }
-    },
-    "leakage": {
-      "total_known_pii_occurrences": 1027,
-      "residual_leaks_after_sanitisation": 768,
-      "leakage_rate": 0.7478,
-      "leakage_rate_pct": 74.78
-    }
-  },
-  "presidio+rules": {
-    "detector": "presidio+rules",
-    "transform": "redaction",
-    "notes_evaluated": 1602,
-    "detection": {
-      "overall": {
-        "precision": 0.0682,
-        "recall": 0.7624,
-        "f1": 0.1251,
-        "tp": 783,
-        "fp": 10706,
-        "fn": 244
-      },
-      "per_entity": {
-        "DATE_TIME": {
-          "precision": 0.022,
-          "recall": 1.0,
-          "f1": 0.0431,
-          "support": 84
-        },
-        "GMC": {
-          "precision": 0.0,
-          "recall": 0.0,
-          "f1": 0.0,
-          "support": 0
-        },
-        "LOCATION": {
-          "precision": 0.0,
-          "recall": 0.0,
-          "f1": 0.0,
-          "support": 0
-        },
-        "NMC": {
-          "precision": 0.0,
-          "recall": 0.0,
-          "f1": 0.0,
-          "support": 0
-        },
-        "PERSON": {
-          "precision": 0.0925,
-          "recall": 0.6819,
-          "f1": 0.1629,
-          "support": 764
-        },
-        "RECORD_ID": {
-          "precision": 0.0,
-          "recall": 0.0,
-          "f1": 0.0,
-          "support": 0
-        },
-        "UK_NHS": {
-          "precision": 0.978,
-          "recall": 0.9944,
-          "f1": 0.9861,
-          "support": 179
-        },
-        "URL": {
-          "precision": 0.0,
-          "recall": 0.0,
-          "f1": 0.0,
-          "support": 0
-        }
-      }
-    },
-    "leakage": {
-      "total_known_pii_occurrences": 1027,
-      "residual_leaks_after_sanitisation": 87,
-      "leakage_rate": 0.0847,
-      "leakage_rate_pct": 8.47
-    }
-  },
-  "presidio+rules+roster": {
-    "detector": "presidio+rules+gazetteer",
-    "transform": "redaction",
-    "notes_evaluated": 1602,
-    "detection": {
-      "overall": {
-        "precision": 0.0705,
-        "recall": 0.7965,
-        "f1": 0.1295,
-        "tp": 818,
-        "fp": 10787,
-        "fn": 209
-      },
-      "per_entity": {
-        "DATE_TIME": {
-          "precision": 0.022,
-          "recall": 1.0,
-          "f1": 0.0431,
-          "support": 84
-        },
-        "GMC": {
-          "precision": 0.0,
-          "recall": 0.0,
-          "f1": 0.0,
-          "support": 0
-        },
-        "LOCATION": {
-          "precision": 0.0,
-          "recall": 0.0,
-          "f1": 0.0,
-          "support": 0
-        },
-        "NMC": {
-          "precision": 0.0,
-          "recall": 0.0,
-          "f1": 0.0,
-          "support": 0
-        },
-        "PERSON": {
-          "precision": 0.0967,
-          "recall": 0.7277,
-          "f1": 0.1707,
-          "support": 764
-        },
-        "RECORD_ID": {
-          "precision": 0.0,
-          "recall": 0.0,
-          "f1": 0.0,
-          "support": 0
-        },
-        "UK_NHS": {
-          "precision": 0.978,
-          "recall": 0.9944,
-          "f1": 0.9861,
-          "support": 179
-        },
-        "URL": {
-          "precision": 0.0,
-          "recall": 0.0,
-          "f1": 0.0,
-          "support": 0
-        }
-      }
-    },
-    "leakage": {
-      "total_known_pii_occurrences": 1027,
-      "residual_leaks_after_sanitisation": 1,
-      "leakage_rate": 0.001,
-      "leakage_rate_pct": 0.1
-    }
-  }
-}

scripts/post_edit_check.py

@@ -1,11 +1,11 @@
 """PostToolUse hook: re-run the de-identification tests after edits to the scrubbing logic.
 
-Wired in `.claude/settings.json`. The team guide's lesson is "verify everything" — recognizers and
+Wired in `.claude/settings.json`. The team guide's lesson is "verify everything" — recognisers and
 anonymisation operators are exactly where a silent regression would let PII leak, so we re-check them
 on every edit.
 
 Safe by design:
-- Only acts on edits to `src/recognizers/` or `src/anonymize.py`; otherwise exits 0 silently.
+- Only acts on edits to the scrubbing modules in `src/`; otherwise exits 0 silently.
 - Gated behind the `PII_ENABLE_HOOK=1` env var so it never disrupts an unrelated session or a
   half-installed environment. Turn it on once the venv + tests exist.
 - Exits 0 (never blocks) if the venv or pytest is missing.
@@ -19,7 +19,7 @@ import sys
 from pathlib import Path
 
 REPO = Path(__file__).resolve().parent.parent
-WATCHED = ("noteguard/recognizers.py", "noteguard/detect.py", "noteguard/transform.py")
+WATCHED = ("src/recognisers.py", "src/detect.py", "src/transform.py")
 
 
 def main() -> int:

{noteguard → src}/detect.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 
 from typing import Protocol
 
-from .recognizers import Span, find_rule_spans
+from .recognisers import Span, find_rule_spans
 
 
 class Detector(Protocol):
@@ -70,10 +70,10 @@ class PresidioDetector:
         self.engine = AnalyzerEngine(nlp_engine=provider.create_engine())
         self.score_threshold = score_threshold
         self.review_threshold = review_threshold
-        self._register_uk_recognizers()
+        self._register_uk_recognisers()
 
-    def _register_uk_recognizers(self) -> None:
-        """Register UK entity recognizers that Presidio documents but does not ship."""
+    def _register_uk_recognisers(self) -> None:
+        """Register UK entity recognisers that Presidio documents but does not ship."""
         from presidio_analyzer import Pattern, PatternRecognizer
 
         custom = [

{noteguard → src}/evaluate.py

@@ -21,7 +21,7 @@ from datetime import datetime
 
 from .data import NoteRecord
 from .detect import Detector
-from .recognizers import Span
+from .recognisers 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"]

{noteguard → src}/pipeline.py

@@ -8,7 +8,7 @@ from collections import Counter
 from dataclasses import dataclass, field
 
 from .detect import Detector, build_detector
-from .recognizers import Span
+from .recognisers import Span
 from .transform import REDACTION, PseudonymVault, Replacement, apply_transform
 
 

{noteguard → src}/transform.py

@@ -21,7 +21,7 @@ import string
 from dataclasses import dataclass, field
 from datetime import datetime, timedelta
 
-from .recognizers import Span
+from .recognisers import Span
 
 REDACTION = "redaction"
 PSEUDONYM = "pseudonym"
@@ -57,7 +57,7 @@ _POSTCODE_INWARD = re.compile(r"\s*\d[A-Za-z]{2}\s*$")
 try:  # realistic surrogates if Faker is available
     from faker import Faker
 
-    _FAKER: "Faker | None" = Faker("en_GB")
+    _FAKER: Faker | None = Faker("en_GB")
 except Exception:  # pragma: no cover - keeps the pure-Python path working
     _FAKER = None
 
@@ -156,7 +156,7 @@ def _fake_vehicle(value: str) -> str:
 
 def _fake_nhs_number(value: str) -> str:
     """Deterministic, checksum-VALID fake NHS number (stable per original)."""
-    from .recognizers import nhs_number_is_valid
+    from .recognisers import nhs_number_is_valid
 
     seed = _seed(value)
     for _ in range(1000):
@@ -211,7 +211,7 @@ def apply_transform(
 
 
 if __name__ == "__main__":
-    from .recognizers import find_rule_spans
+    from .recognisers 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)

{noteguard → src}/trust_demo.py

@@ -6,8 +6,8 @@ de-identified text + a content-free audit manifest to a shared pool. Raw notes a
 vaults never leave the Trust. This is the sanitise-at-source gate that sits in
 front of a federated SDE / FLock.io training round.
 
-    python -m noteguard.trust_demo                 # pseudonymise, 300 notes
-    python -m noteguard.trust_demo redaction 600
+    python -m src.trust_demo                 # pseudonymise, 300 notes
+    python -m src.trust_demo redaction 600
 """
 from __future__ import annotations
 
@@ -18,11 +18,11 @@ from pathlib import Path
 
 from .data import NoteRecord, load_notes
 from .detect import build_detector
-from .evaluate import ground_truth_spans, value_variants, _find_all
+from .evaluate import _find_all, ground_truth_spans, value_variants
 from .pipeline import Pipeline
 from .transform import PSEUDONYM, PseudonymVault
 
-OUT_DIR = Path(__file__).resolve().parent.parent / "data" / "out"
+OUT_DIR = Path(__file__).resolve().parent.parent / "output"
 TRUST_NAMES = {0: "Trust A (Northgate NHS Foundation Trust)", 1: "Trust B (Riverside NHS Trust)"}
 
 

app/streamlit_app.py → streamlit_app.py

@@ -3,7 +3,7 @@
 Run from the repo root:  streamlit run app/streamlit_app.py
 
 Try-it (detect & sanitise) · Metrics & leakage · Governance (Five Safes) · Two-Trust sharing.
-Built on the noteguard package (pluggable detectors + patient-consistent transforms).
+Built on the NoteGuard package (src/) — pluggable detectors + patient-consistent transforms.
 """
 from __future__ import annotations
 
@@ -18,14 +18,14 @@ import streamlit as st
 REPO = Path(__file__).resolve().parent.parent
 sys.path.insert(0, str(REPO))
 
-from noteguard.data import load_notes  # noqa: E402
-from noteguard.detect import build_detector  # noqa: E402
-from noteguard.evaluate import evaluate  # noqa: E402
-from noteguard.pipeline import Pipeline  # noqa: E402
-from noteguard.transform import PSEUDONYM, REDACTION, PseudonymVault  # noqa: E402
+from src.data import load_notes  # noqa: E402
+from src.detect import build_detector  # noqa: E402
+from src.evaluate import evaluate  # noqa: E402
+from src.pipeline import Pipeline  # noqa: E402
+from src.transform import PSEUDONYM, REDACTION, PseudonymVault  # noqa: E402
 
-OUT_DIR = REPO / "data" / "out"
-RESULTS = REPO / "results.json"
+OUT_DIR = REPO / "output"
+RESULTS = REPO / "output" / "results.json"
 
 ENTITY_COLORS = {
     "PERSON": "#ffd6e0", "UK_NHS": "#ffe9b3", "DATE_TIME": "#d4f4dd", "UK_POSTCODE": "#cfe8ff",
@@ -271,14 +271,14 @@ with tab_trust:
     )
     summary = load_json(OUT_DIR / "trust_demo_summary.json")
     if st.button("▶ Run two-Trust demo"):
-        from noteguard.trust_demo import main as run_trust
+        from src.trust_demo import main as run_trust
         with st.spinner("Sanitising at each Trust…"):
             run_trust()
         summary = load_json(OUT_DIR / "trust_demo_summary.json")
 
     if summary:
         cols = st.columns(len(summary["trusts"]) + 1)
-        for col, t in zip(cols, summary["trusts"]):
+        for col, t in zip(cols, summary["trusts"], strict=False):
             with col:
                 st.markdown(f"#### 🏥 {t['trust'].split('(')[0].strip()}")
                 st.metric("Notes de-identified", t["notes_deidentified"])
@@ -292,4 +292,4 @@ with tab_trust:
             st.metric("Total residual leaks", summary["total_residual_leaks"])
             st.caption("→ ready for federated AI / FLock.io")
     else:
-        st.info("Click **Run two-Trust demo** or run `python -m noteguard.trust_demo`.")
+        st.info("Click **Run two-Trust demo** or run `python -m src.trust_demo`.")

run_eval.py → tests/run_eval.py

@@ -1,20 +1,30 @@
 """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
+    python tests/run_eval.py --limit 300            # quick run
+    python tests/run_eval.py --method pseudonym     # leakage under pseudonymisation
+    python tests/run_eval.py --compare              # rules-only vs presidio+rules
 
-Writes results.json (consumed by the demo's metrics panel) and prints a summary.
+Writes output/results.json (consumed by the Streamlit metrics panel) and prints a summary.
+This is the pipeline's evaluation entry point; it lives under tests/ alongside the unit tests.
 """
 from __future__ import annotations
 
 import argparse
 import json
+import logging
+import sys
+from pathlib import Path
 
-from noteguard.data import load_notes
-from noteguard.detect import RuleDetector, build_detector
-from noteguard.evaluate import EvalResult, evaluate
-from noteguard.transform import REDACTION
+REPO = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(REPO))  # make the `src` package importable when run as a script
+
+from src.data import load_notes  # noqa: E402
+from src.detect import RuleDetector, build_detector  # noqa: E402
+from src.evaluate import EvalResult, evaluate  # noqa: E402
+from src.transform import REDACTION  # noqa: E402
+
+OUTPUT_DIR = REPO / "output"
+logger = logging.getLogger("noteguard.eval")
 
 
 def _print_summary(res: EvalResult) -> None:
@@ -33,18 +43,19 @@ def _print_summary(res: EvalResult) -> None:
 
 
 def main() -> None:
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s")
     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")
+    ap.add_argument("--out", default=None, help="output JSON path (default: output/results.json)")
     args = ap.parse_args()
 
-    print(f"[noteguard] loading notes (limit={args.limit}) ...")
+    logger.info("loading notes (limit=%s) ...", 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.")
+    logger.info("%d notes; %d known PII values joined.",
+                len(records), sum(len(r.ground_truth) for r in records))
 
     runs: dict[str, EvalResult] = {}
     if args.compare:
@@ -52,8 +63,7 @@ def main() -> None:
         runs["rules"] = evaluate(records, RuleDetector(), args.method)
         _print_summary(runs["rules"])
         print("\n=== presidio+rules (shipping headline detector) ===")
-        presidio = build_detector(True)
-        runs["presidio+rules"] = evaluate(records, presidio, args.method)
+        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)
@@ -61,10 +71,10 @@ def main() -> None:
         _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}")
+    OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+    out_path = Path(args.out) if args.out else OUTPUT_DIR / "results.json"
+    out_path.write_text(json.dumps({n: r.to_dict() for n, r in runs.items()}, indent=2), encoding="utf-8")
+    logger.info("wrote %s", out_path)
 
 
 if __name__ == "__main__":

tests/test_nhs_number.py

@@ -1,5 +1,5 @@
 """NHS number Modulus-11 checksum and all surface forms the dataset uses."""
-from noteguard.recognizers import UK_NHS, find_rule_spans, nhs_number_is_valid
+from src.recognisers import UK_NHS, find_rule_spans, nhs_number_is_valid
 
 
 def _has_nhs(text: str) -> bool:

tests/test_pipeline.py

@@ -2,9 +2,9 @@
 
 Uses the pure-Python RuleDetector so the test is fast and needs no spaCy/Presidio.
 """
-from noteguard.detect import RuleDetector
-from noteguard.pipeline import Pipeline
-from noteguard.transform import PSEUDONYM
+from src.detect import RuleDetector
+from src.pipeline import Pipeline
+from src.transform import PSEUDONYM
 
 
 def test_pipeline_removes_known_pii():

tests/{test_recognizers.py → test_recognisers.py}

@@ -1,6 +1,12 @@
 """Rule-layer recognisers: NHS checksum + the folded-in NHS/staff/org identifiers."""
-from noteguard.recognizers import (
-    GMC, NHS_ODS, NMC, RECORD_ID, UK_NHS, find_rule_spans, nhs_number_is_valid,
+from src.recognisers import (
+    GMC,
+    NHS_ODS,
+    NMC,
+    RECORD_ID,
+    UK_NHS,
+    find_rule_spans,
+    nhs_number_is_valid,
 )
 
 
@@ -39,10 +45,10 @@ def test_record_uuid():
 
 
 def test_uk_nino():
-    from noteguard.recognizers import UK_NINO
+    from src.recognisers import UK_NINO
     assert UK_NINO in _types("NI: AB 12 34 56 C")
 
 
 def test_uk_vehicle_registration():
-    from noteguard.recognizers import UK_VEHICLE_REGISTRATION
+    from src.recognisers import UK_VEHICLE_REGISTRATION
     assert UK_VEHICLE_REGISTRATION in _types("vehicle AB12 CDE")

tests/test_transform.py

@@ -2,9 +2,13 @@
 import re
 from datetime import datetime
 
-from noteguard.recognizers import find_rule_spans, nhs_number_is_valid
-from noteguard.transform import (
-    PSEUDONYM, REDACTION, PseudonymVault, _fake_nhs_number, apply_transform,
+from src.recognisers import find_rule_spans, nhs_number_is_valid
+from src.transform import (
+    PSEUDONYM,
+    REDACTION,
+    PseudonymVault,
+    _fake_nhs_number,
+    apply_transform,
 )