psdl-lang 0.3.1

Patient Scenario Definition Language - Reference Implementation

PSDL - Patient Scenario Definition Language

An open, vendor-neutral standard for expressing clinical scenarios in healthcare AI.

What SQL became for data queries, ONNX for ML models, and GraphQL for APIs — PSDL is becoming the semantic layer for clinical AI.

Installation

pip install psdl-lang

# With OMOP adapter
pip install psdl-lang[omop]

# With FHIR adapter
pip install psdl-lang[fhir]

# Full installation
pip install psdl-lang[full]

Quick Start

from psdl import PSDLParser, PSDLEvaluator, InMemoryBackend, DataPoint
from psdl.examples import get_scenario, list_scenarios
from datetime import datetime, timedelta

# List available built-in scenarios
print(list_scenarios())
# ['aki_detection', 'hyperkalemia_detection', 'lactic_acidosis', 'sepsis_screening']

# Load a built-in scenario
scenario = get_scenario("aki_detection")
print(f"Loaded: {scenario.name}")

# Set up data backend and add patient data
backend = InMemoryBackend()
now = datetime.now()

backend.add_data(
    patient_id="patient_123",
    signal_name="Cr",
    data=[
        DataPoint(now - timedelta(hours=6), 1.0),
        DataPoint(now - timedelta(hours=3), 1.3),
        DataPoint(now, 1.8),
    ]
)

# Evaluate
evaluator = PSDLEvaluator(scenario, backend)
result = evaluator.evaluate_patient(patient_id="patient_123", reference_time=now)

if result.is_triggered:
    print(f"Alert: {result.triggered_logic}")

Define Your Own Scenario

scenario: AKI_Early_Detection
version: "0.1.0"

signals:
  Cr:
    source: creatinine
    concept_id: 3016723  # OMOP concept
    unit: mg/dL

trends:
  cr_rising:
    expr: delta(Cr, 6h) > 0.3
    description: "Creatinine rise > 0.3 mg/dL in 6 hours"

  cr_high:
    expr: last(Cr) > 1.5
    description: "Current creatinine elevated"

logic:
  aki_risk:
    expr: cr_rising AND cr_high
    severity: high
    description: "Early AKI - rising and elevated creatinine"

from psdl import PSDLParser

parser = PSDLParser()
scenario = parser.parse_file("my_scenario.yaml")
# or parse from string
scenario = parser.parse(yaml_content)

Temporal Operators

Operator	Example	Description
delta	delta(Cr, 6h) > 0.3	Change over time window
slope	slope(HR, 1h) > 5	Linear trend (regression)
last	last(Cr) > 1.5	Most recent value
min/max	max(Temp, 24h) > 38.5	Min/max in window
sma/ema	ema(BP, 2h) < 90	Moving averages
count	count(Cr, 24h) >= 2	Observation count

Window formats: 30s, 5m, 6h, 1d, 7d

Data Adapters

OMOP CDM

from psdl import get_omop_adapter

OMOPAdapter = get_omop_adapter()
adapter = OMOPAdapter(connection_string="postgresql://...")

FHIR R4

from psdl import get_fhir_adapter

FHIRAdapter = get_fhir_adapter()
adapter = FHIRAdapter(base_url="https://hapi.fhir.org/baseR4")

Why PSDL?

Challenge	Without PSDL	With PSDL
Portability	Logic tied to hospital systems	Same scenario runs anywhere
Auditability	Scattered across code/configs	Single version-controlled file
Reproducibility	Hidden state, implicit deps	Deterministic execution
Compliance	Manual documentation	Built-in audit primitives

Links

• GitHub: github.com/Chesterguan/PSDL
• Documentation: Whitepaper
• Examples: Example Scenarios
• Try in Colab: Interactive Notebook

License

Apache 2.0 - See LICENSE for details.