PSDL Inspector

Governance middleware for clinical scenarios.

PSDL Inspector validates, visualizes, and certifies PSDL scenarios, producing audit-ready bundles for regulatory compliance.

┌─────────────────────────────────────────────────────────────┐
│                    PSDL ECOSYSTEM                           │
│                                                             │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────┐ │
│  │  AUTHORING  │ →  │  INSPECTOR  │ →  │    PLATFORM     │ │
│  │  (YAML)     │    │ (Certify)   │    │   (Execute)     │ │
│  └─────────────┘    └─────────────┘    └─────────────────┘ │
│                                                             │
│  psdl-lang          psdl-inspector     (your runtime)      │
└─────────────────────────────────────────────────────────────┘

Demo

Author → certify → preflight against a live database

The AKI early-detection scenario goes end-to-end — Input → Preview (DAG) → Export (certified bundle) → Prepare — then a realistic cohort extraction is preflighted against a real local database (MIMIC-IV in OMOP CDM). A forgotten join (cartesian blow-up) is caught as 🔴 BLOCK; the fixed, scoped query reads 🟢 GO — driven by a real EXPLAIN, metadata only, never executing the query.

▶ Watch the sepsis walkthrough on YouTube → youtu.be/j-3UHeCyHDk

The recording follows a Sepsis-3 qSOFA + lactate screen end-to-end through the full pipeline (Builder/YAML → Validate → Outline → DAG → Anchor → Certified Bundle → IRB Word export → MEDS Preview).

Two reproducible scenarios are shipped under docs/demos/ — scenario YAMLs, narrator cue sheets, and a DevTools loader:

#	Scenario	Audience	Recording
1	Sepsis-3 qSOFA + lactate screen	Clinical informatics	▶ YouTube above
2	T2DM + diabetic nephropathy on metformin cohort	Research / cohort builders	Self-record kit (cue sheet ready)

Compatibility

Inspector always tracks the latest psdl-lang — the requirements pin is psdl-lang>=0.4.0 so the most recent compatible release is installed. The table below records the spec/bundle versions consumed at the time of each Inspector release; older Inspector versions are not retroactively bumped.

Inspector Version	psdl-lang at release	PSDL Spec	Bundle Version	Status
0.2.x	0.4.x (latest)	0.4	1.1	Current
0.1.x	0.3.1	0.3	1.0	Maintained (legacy spec)
-	< 0.2	-	-	Not supported

Note: Inspector follows psdl-lang's latest release. Pin psdl-lang>=0.4.0 in your own requirements to track along — the package provides parsing, validation, and IR generation that Inspector builds upon.

Features

Feature	Description
Build	Visual scenario builder with guided workflow and OMOP vocabulary search
Generate	AI-assisted scenario creation with OpenAI or local Ollama
Validate	Real-time syntax and semantic validation via psdl-lang
Visualize	Interactive DAG view with ReactFlow (signal → trend → logic)
Outline	Semantic tree navigation of scenario structure
Anchor	Automatic terminology binding to OMOP vocabulary at export
Bundle	Generate checksummed certified bundles with terminology anchors
Export	IRB preparation with AI-enriched Word document export
MEDS Preview	Synthesize a 10-row MEDS-format Parquet preview from anchored signals, no DB required; ships with `psdl-meds` CLI for offline conversion
Data Catalog	Read-only browse of an Observatory-scanned data lake (schemas, columns, inferred roles) with provenance + staleness — see what institutional data exists
Preflight	SQL cost/risk check (GO / CAUTION / BLOCK) before a query touches the warehouse — offline by default; optionally run a real `EXPLAIN` against your own local DB for a tightened, high-confidence plan (metadata only, never executes)

What Inspector Does NOT Do

Inspector is governance middleware — it certifies that algorithms are correct. It does not execute them.

Out of Scope	Reason
Read patient data (EHR, OMOP, FHIR rows)	Execution platform responsibility
Execute scenarios in production	Execution platform responsibility
Send clinical alerts	Execution platform responsibility
Handle PHI/HIPAA data	No patient data in certification

Preflight's optional live plan connects to your own local database for an EXPLAIN only — it reads query-plan metadata (estimated rows, scan types), never patient rows. No data is fetched and no query is executed.

Try It Out

Option 1: Docker (Recommended)

git clone https://github.com/Chesterguan/psdl-inspector.git
cd psdl-inspector
docker-compose up

Open http://localhost:9806

Note: The Docker image includes the full OMOP vocabulary (~1GB) for immediate terminology search. First build may take a few minutes.

Optional: Add your API keys for AI generation:

cp .env.example .env
# Edit .env with OPENAI_API_KEY=sk-...
docker-compose up

Option 2: Deploy Your Own

See Deployment Guide for Vercel + Render setup.

Development Setup

Requirements

Python 3.9+
Node.js 18+
psdl-lang (latest, installed automatically)

1. Clone Repository

git clone https://github.com/Chesterguan/psdl-inspector.git
cd psdl-inspector

2. Backend Setup

cd backend
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8200

API available at http://localhost:8200

3. Frontend Setup

cd frontend
npm install
npm run dev

App available at http://localhost:9806

4. Configure AI (Optional)

For AI-assisted scenario generation:

# Option 1: OpenAI (recommended - fast, accurate)
export OPENAI_API_KEY="sk-your-key-here"

# Option 2: Local Ollama (private, no API key needed)
brew install ollama
ollama serve
ollama pull mistral-small

5. Verify Installation

Navigate to http://localhost:9806. The header should display:

Inspector v0.2.0
psdl-lang v0.4.x  # whichever latest pip resolved

Wizard Workflow

PSDL Inspector uses a 3-step wizard workflow:

Step 1: Input

Three input modes are available:

Builder Mode (New in v0.2.0): Constrained visual builder with guided workflow
- Signal selection with OMOP vocabulary search
- Trend configuration with metric selection
- Logic rule builder with severity levels
- Outputs configuration (decisions, features, evidence)
- Audit section (intent, rationale, provenance)
Generate Mode: AI-assisted scenario creation from natural language
- OpenAI GPT-4o-mini (cloud, recommended)
- Ollama (local, privacy-preserving)
- Auto-validation and error correction
- Optional clinical context for accurate thresholds
Editor Mode: Manual YAML editing with CodeMirror
- Syntax highlighting and auto-completion
- Line numbers and template insertion
- Real-time validation feedback

Step 2: Preview

Outline: Tree view of signals, trends, and logic with dependency tracking
DAG: Interactive ReactFlow graph visualization
- Custom node shapes (parallelogram, rounded rect, diamond, hexagon)
- Severity-based coloring for logic nodes
- Node details panel on hover
Bundle: Certified audit bundle preview with checksum and governance checklist

Step 3: Export

Governance Documentation: Clinical summary, justification, risk assessment
JSON Bundle: Checksummed certified audit bundle with terminology anchors
Word Document: AI-enriched IRB documentation with:
- Executive summary and clinical background
- Algorithm overview and data elements
- Safety considerations and limitations
- Technical appendix

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     Frontend (Next.js)                          │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌───────────────┐   │
│  │ Generate │→ │ Editor   │→ │ Preview  │→ │    Export     │   │
│  │ (AI)     │  │ (YAML)   │  │ DAG/Tree │  │ Bundle + Word │   │
│  └──────────┘  └──────────┘  └──────────┘  └───────────────┘   │
└────────────────────────────┬────────────────────────────────────┘
                             │ REST API
┌────────────────────────────▼────────────────────────────────────┐
│                     Backend (FastAPI)                           │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────┐    │
│  │ /generate    │  │ /validate    │  │ /export/bundle     │    │
│  │ /outline     │  │              │  │ /export/irb-doc    │    │
│  └──────────────┘  └──────────────┘  └────────────────────┘    │
│         │                 │                    │                │
│  ┌──────▼──────┐  ┌───────▼───────┐  ┌────────▼─────────┐      │
│  │  OpenAI /   │  │   psdl-lang   │  │   python-docx    │      │
│  │   Ollama    │  │  (validation) │  │  (Word export)   │      │
│  └─────────────┘  └───────────────┘  └──────────────────┘      │
└─────────────────────────────────────────────────────────────────┘

API Reference

GET /api/version

Returns version information.

{
  "inspector": "0.2.0",
  "psdl_lang": "0.4.0"
}

GET /api/generate/status

Check LLM provider availability.

{
  "openai": { "available": true, "model": "gpt-4o-mini" },
  "ollama": { "available": true, "model": "mistral-small", "models": [...] },
  "default_provider": "openai"
}

POST /api/generate/scenario

Generate PSDL scenario from natural language.

{
  "prompt": "Detect AKI using creatinine changes",
  "provider": "openai",
  "max_retries": 3,
  "clinical_context": "KDIGO criteria..."
}

POST /api/validate

Validate a PSDL scenario.

POST /api/outline

Generate semantic outline with dependency tracking.

POST /api/export/bundle

Export certified audit bundle with checksum.

POST /api/export/irb-document

Export AI-enriched Word document for IRB preparation.

POST /api/meds/preview

Synthesize a 10-row MEDS preview shard from anchored signals.

// Request
{
  "anchors": [
    {
      "psdl_signal": "serum_creatinine",
      "omop_vocabulary": "LOINC",
      "omop_concept_code": "2160-0",
      "expected_unit": "mg/dL"
    }
  ],
  "n": 10
}

// Response
{
  "n_events": 10,
  "n_subjects": 3,
  "path": "/tmp/psdl_inspector_meds/preview.parquet",
  "codes_used": ["LOINC/2160-0"]
}

Subjects are synthetic negative integers and timestamps step by one day from 2024-01-01, so the output can never collide with real PHI. The shard is validated against meds.schema.data_schema() before return.

MEDS Preview (`psdl_meds`)

Inspector embeds the psdl_meds shared library so authors can see what their scenario will produce in MEDS format before running it against any real data. Use the "Preview MEDS shape" card on the Export step, or the psdl-meds CLI for offline work:

# Convert a CSV of (subject_id, time, code, numeric_value) rows to MEDS Parquet
psdl-meds convert --input cohort.csv --out cohort.parquet

# Synthesize a preview shard from anchored signals (no DB needed)
psdl-meds preview --anchors anchors.json --out preview.parquet -n 10

The same library is used by PSDL Workbench for live OMOP-backed cohort exports.

Certified Audit Bundle

Inspector outputs Certified Audit Bundles — the contract between authoring and execution:

{
  "bundle_version": "1.1",
  "certified_at": "2026-01-26T10:30:00Z",
  "checksum": "sha256:abc123...",

  "scenario": {
    "name": "AKI_Detection",
    "version": "0.3.1",
    "raw_yaml": "...",
    "parsed": { /* Full IR */ }
  },

  "terminology_anchors": {
    "anchors": {
      "creatinine": {
        "concept_id": 3016723,
        "vocabulary_id": "LOINC",
        "concept_code": "2160-0",
        "concept_name": "Creatinine [Mass/volume] in Serum or Plasma",
        "standard_unit": "mg/dL",
        "match_confidence": "high"
      }
    },
    "unanchored_refs": [],
    "anchored_count": 1,
    "total_refs": 1
  },

  "validation": {
    "psdl_lang_version": "0.4.0",
    "inspector_version": "0.2.0",
    "valid": true,
    "errors": [],
    "warnings": []
  },

  "audit": {
    "intent": "Detect early AKI for timely intervention",
    "rationale": "Based on KDIGO guidelines",
    "provenance": "doi:10.1038/..."
  },

  "summary": "Human-readable summary for IRB..."
}

Terminology Anchors (v1.1)

The terminology_anchors section maps semantic refs (e.g., "creatinine") to OMOP concept IDs. This enables:

Portable execution: Same scenario runs on any OMOP-compliant site
Interoperability: Standard vocabulary binding (LOINC, SNOMED, RxNorm)
Audit trail: Clear mapping from algorithm refs to standard concepts

See EXECUTION_CONTRACT.md for how execution platforms use these anchors.

Tech Stack

Component	Technology
Frontend	Next.js 14, React 18, Tailwind CSS
Editor	CodeMirror 6
Visualization	ReactFlow, dagre (auto-layout)
Backend	FastAPI, Python 3.9+
Validation	psdl-lang (latest)
AI Generation	OpenAI GPT-4o-mini, Ollama
Document Export	python-docx

Related Projects

Project	Description	Link
PSDL	Patient Scenario Definition Language spec	GitHub
psdl-lang	Python library for PSDL parsing	PyPI
psdl_meds	MEDS (Medical Event Data Standard) writer + validator, embedded here and reused by Workbench	backend/psdl_meds/
PSDL Workbench	Institutional platform for live cohort execution + governance	GitHub

Roadmap

Contributing

Contributions welcome! See CONTRIBUTING.md for detailed guidelines.

Quick start:

# Backend (with hot reload)
cd backend && source .venv/bin/activate
pip install psdl-lang --upgrade  # Always get latest
uvicorn app.main:app --reload --port 8200

# Frontend (with hot reload)
cd frontend && npm run dev

Code Style

Python: Follow PEP 8, use type hints
TypeScript: ESLint + Prettier, strict mode
Commits: Conventional commits (feat:, fix:, docs:, etc.)

License

MIT License - see LICENSE for details.

Built for teams who take clinical algorithm governance seriously.

Name		Name	Last commit message	Last commit date
Latest commit History 136 Commits
assets		assets
backend		backend
docs		docs
frontend		frontend
testorg		testorg
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
render.yaml		render.yaml
vercel.json		vercel.json

Folders and files

Latest commit

History

Repository files navigation

PSDL Inspector

Demo

Author → certify → preflight against a live database

▶ Watch the sepsis walkthrough on YouTube → youtu.be/j-3UHeCyHDk

Compatibility

Features

What Inspector Does NOT Do

Try It Out

Option 1: Docker (Recommended)

Option 2: Deploy Your Own

Development Setup

Requirements

1. Clone Repository

2. Backend Setup

3. Frontend Setup

4. Configure AI (Optional)

5. Verify Installation

Wizard Workflow

Step 1: Input

Step 2: Preview

Step 3: Export

Architecture

API Reference

GET /api/version

GET /api/generate/status

POST /api/generate/scenario

POST /api/validate

POST /api/outline

POST /api/export/bundle

POST /api/export/irb-document

POST /api/meds/preview

MEDS Preview (psdl_meds)

Certified Audit Bundle

Terminology Anchors (v1.1)

Tech Stack

Related Projects

Roadmap

Contributing

Code Style

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

MEDS Preview (`psdl_meds`)

Packages