Describe a clinical cohort or detection rule in one sentence — get back a validated, audit-ready algorithm.
PSDL Inspector turns plain English into a checked clinical scenario: a visual DAG, OMOP terminology anchoring, a checksummed certified bundle, and a real-database cost preflight — without writing a line of PSDL by hand.
git clone https://github.com/Chesterguan/psdl-inspector.git
cd psdl-inspector && docker compose up # → http://localhost:9806▶ 13-second demo · 5-minute quickstart · Full walkthrough on YouTube · Docs
- Describe it, don't code it — one sentence → a validated PSDL scenario, AI-generated and auto-checked against
psdl-lang. No new syntax to learn. - See the logic — an interactive DAG + semantic outline surface errors at authoring time, not at IRB review.
- Hand it off — a checksummed certified bundle with OMOP anchors + an IRB-ready Word doc, and a SQL preflight that reads GO / CAUTION / BLOCK before a query ever touches the warehouse.
Inspector is the free, single-user tool. Need a scenario registry, role-based review/approval, IRB templates, and SSO across a team? → PSDL Workbench (commercial) — request access or info.
One clinical sentence becomes a scenario that is generated, validated, and costed against a real 288M-row MIMIC-IV/OMOP database — the preflight runs a real EXPLAIN (metadata only; it never executes the query or reads a patient row):
"Detect and stage acute kidney injury by the KDIGO criteria using serum creatinine."
↓ AI generates PSDL (gpt-4o-mini, auto-retried until valid)
↓ validates (real thresholds, real KDIGO stages)
↓ anchors to OMOP (creatinine → LOINC 2160-0, concept 3016723)
↓ certifies (checksummed bundle, IRB Word doc)
↓ preflights on real data 🟢 GO (real EXPLAIN, nothing executed)
Reproduce it yourself: docs/demos/ ships the scenario YAMLs, narrator cue sheets, and the recording script.
| You are… | Inspector gives you… |
|---|---|
| A clinical researcher / cohort builder | A sentence → a checked, shareable algorithm you can hand to a data team — no SQL, no DSL to learn first |
| A data engineer / informaticist | A readable DAG + semantic diff of the logic, OMOP anchoring, and a preflight that catches a cartesian-join blow-up before it hits the warehouse |
| An IRB / compliance reviewer | A checksummed certified bundle + AI-enriched Word doc with intent, rationale, provenance, and a clear audit boundary |
Where Inspector sits in the chain — it certifies algorithms; it never executes them (what that means →):
┌─────────────┐ ┌─────────────┐ ┌─────────────────┐
│ AUTHORING │ → │ INSPECTOR │ → │ PLATFORM │
│ (sentence │ │ (validate + │ │ (execute on │
│ or YAML) │ │ certify) │ │ patient data) │
└─────────────┘ └─────────────┘ └─────────────────┘
psdl-lang psdl-inspector your runtime / Workbench
git clone https://github.com/Chesterguan/psdl-inspector.git
cd psdl-inspector && docker compose up # → http://localhost:9806The image bundles the OMOP vocabulary for terminology search, so the first build takes a few minutes. AI generation needs a key (optional): cp .env.example .env and set OPENAI_API_KEY=sk-..., or use a local model (brew install ollama && ollama serve && ollama pull mistral-small).
Full local (non-Docker) setup → the 5-minute quickstart. Self-hosting, the anchoring-engine choice, and the wizard walkthrough → docs/.
| Feature | Description |
|---|---|
| Generate | One sentence → a validated scenario, via OpenAI or local Ollama, auto-retried until it passes |
| Build | Visual scenario builder with guided workflow and OMOP vocabulary search |
| Validate | Real-time syntax and semantic validation via psdl-lang |
| Visualize | Interactive DAG view (signal → trend → logic) + semantic outline tree |
| Anchor | Automatic terminology binding to OMOP vocabulary at export |
| Bundle | 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 |
| Data Catalog | Read-only browse of an Observatory-scanned data lake (schemas, columns, inferred roles) |
| Preflight | SQL cost/risk check (GO / CAUTION / BLOCK) before a query touches the warehouse — offline by default; optional real EXPLAIN against your own local DB |
▶ Sepsis-3 qSOFA walkthrough on YouTube — a full pipeline run (Builder/YAML → Validate → Outline → DAG → Anchor → Certified Bundle → IRB Word export → MEDS Preview).
Two reproducible scenarios ship under docs/demos/ (sepsis screen; T2DM + diabetic nephropathy on metformin) with scenario YAMLs, narrator cue sheets, and a DevTools loader.
| Quickstart | Zero to a certified algorithm in 5 minutes |
| Using Inspector | Wizard workflow + the BioLORD/legacy anchoring engine choice |
| API & bundle reference | REST endpoints, certified bundle schema, MEDS preview, compatibility |
| Architecture & scope | System design + what Inspector does/doesn't do |
| Execution contract | How execution platforms consume the certified bundle |
| Deployment | Docker / Vercel / Render |
Full index: docs/.
| Project | Description | Link |
|---|---|---|
| PSDL | Patient Scenario Definition Language spec | GitHub |
| psdl-lang | Python library for PSDL parsing | PyPI |
| psdl_meds | MEDS writer + validator, embedded here and reused by Workbench | backend/psdl_meds/ |
| PSDL Workbench | Institutional platform for live cohort execution + governance | Commercial (closed-source / SaaS) |
- 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)
- MEDS preview +
psdl-medsCLI (shared library with PSDL Workbench) - Editable DAG (visual scenario editing)
- Lint rules (best practices, style checks)
- Scenario registry with versioning
- Semantic diff (structural, not text)
Contributions welcome — see CONTRIBUTING.md. Python: PEP 8 + type hints. TypeScript: ESLint + Prettier, strict mode. Commits: Conventional Commits.
MIT — see LICENSE.
Built for teams who take clinical algorithm governance seriously.