Chest X-Ray CDS Proof of Concept

Educational proof of concept. Not for clinical use.

An end-to-end, safety-constrained applied AI system for NIH ChestX-ray14: checksum-verified DenseNet-121 multi-label inference, provenance-preserving synthetic patient workflows, append-only clinician review, schema-validated tool-using LLM drafting, and an enforced human approval gate before patient-friendly output.

The project demonstrates reproducible model provenance, patient-isolated dataset handling, strict bundle-integrity checks, structured persistence, and fail-closed workflow transitions in a single local CLI. It is not a medical device and must not be used for diagnosis, treatment, triage, or real patient care. Only synthetic patient information belongs in the demo.

What the demo shows

• Verified local inference across 14 ChestX-ray14 labels
• Synthetic patient and study records stored in SQLite
• Append-only simulated clinician review with manually entered severity
• Structured LLM drafting from a small, allow-listed set of records
• A hard approval gate before patient-friendly text can be generated

Model scores are unconfirmed outputs, not diagnoses. Severity is never inferred from model confidence.

Requirements

• Python 3.11
• A local model bundle at artifacts/model_bundle/
• A local ChestX-ray14 demo manifest and images under data/

The model bundle, radiographs, generated databases, and credentials are not included in this public repository. See data/README.md and artifacts/README.md for the expected local layout.

Quick start

Create the environment:

python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e '.[dev]'

Run the fully local, deterministic demo after placing the required model and data artifacts:

LLM_PROVIDER=mock python scripts/cxr_cli.py demo --no-open-image

To use the optional OpenRouter integration, omit LLM_PROVIDER=mock. The CLI requests the API key through a hidden prompt and keeps it only in process memory:

python scripts/cxr_cli.py llm-status
python scripts/cxr_cli.py demo --no-open-image

Do not put credentials in commands, .env files, source files, logs, issues, or commits.

Verify the project

ruff check .
ruff format --check .
pytest

For a complete guided walkthrough, see docs/DEMO_GUIDE.md. Important safety and interpretation limits are documented in docs/LIMITATIONS.md.

Repository layout

configs/       Local demo and training configuration
data/          Ignored local dataset storage
artifacts/     Ignored model and generated output storage
src/cxr_poc/   Application package
scripts/       Demo, data, training, and verification commands
tests/         Automated tests
docs/          Architecture, evaluation, limitations, and demo guidance

Public-repository safety

The ignore rules exclude local environments, credentials, datasets, model files, databases, generated artifacts, and logs. Before publishing changes, inspect git status and never force-add ignored files. If a real credential is ever committed, revoke it immediately; deleting it in a later commit does not remove it from Git history.