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)      │
└─────────────────────────────────────────────────────────────┘

Compatibility

Inspector Version	psdl-lang Version	PSDL Spec	Bundle Version	Status
0.2.x	0.3.1	0.3	1.1	Current
0.1.x	0.3.1	0.3	1.0	Maintained
-	0.2.x	0.2	-	Not supported
-	< 0.2	-	-	Not supported

Note: PSDL Inspector requires psdl-lang 0.3.x. The psdl-lang library 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

What Inspector Does NOT Do

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

Out of Scope	Reason
Connect to patient data (EHR, OMOP, FHIR)	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

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 0.3.1 (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.3.1

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.3.1"
}

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.

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.3.1",
    "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 0.3.1
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

Roadmap

• AI-assisted scenario generation (OpenAI + Ollama)
• Interactive DAG visualization with ReactFlow
• AI-enriched IRB Word document export
• Visual scenario builder with guided workflow
• Terminology anchoring (OMOP vocabulary binding)
• Modular vocabulary search (embedders, retrievers, rerankers)
• Editable DAG (visual scenario editing)
• Lint rules (best practices, style checks)
• Scenario registry with versioning
• Semantic diff (structural, not text)

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.