Back to projects

Integration Engineering

Healthcare AI Context Pipeline

One HL7v2 message goes in. Out comes a validated clinical briefing to ground an AI agent's patient call — plus conformant FHIR resources, ready to post back to the EHR.

HL7v2 → FHIR R4 Clinical Validation Gate AI Agent & FHIR Write-Back
  1. 01IngestParse ADT, ORU, SIU and RDE messages; route by trigger event.
  2. 02EnrichPull conditions, labs and medications from a FHIR R4 API.
  3. 03Quality gateNormalize per site config, then validate against clinical rules.
  4. 04AgentAssemble the briefing that grounds the patient conversation.
  5. 05Write-backEmit DocumentReference, Task and Flag resources.

Run it

Pick an inbound message and run the pipeline. The briefing is the real output of the demo CLI against that message — parsed, enriched from FHIR, and checked by the clinical quality gate.

$ python demo.py --message samples/hl7/adt_a03_discharge_chf.hl7 --mode context-only --mock

Enriched — pulled from the patient's FHIR chart

Conditions Atrial fibrillation (I48.91)
Medications Furosemide 40mg tablet · Carvedilol 25mg tablet · Losartan 50mg tablet
Labs Sodium 132 mmol/L · Potassium 5.1 mEq/L · Creatinine 1.5 mg/dL · Hemoglobin 11.5 g/dL

Inbound — raw HL7v2

MSH|^~\&|EPIC|GOODHEALTH|RECEIVER|FACILITY|20260325140000||ADT^A03|MSG00001|P|2.5.1
PID|1||MRN12345^^^GOODHEALTH^MR||DOE^JOHN^A||19590215|M|||1450 STERLING AVE^^YORK^PA^17401||7175551234
PV1|1|I|4N^4012^01||||1234567^SMITH^SARAH^M^MD|||CARDIOLOGY||||||1234567^SMITH^SARAH^M^MD|IN||V001|||||||||||||||||||||||||20260715|20260720
DG1|1||I50.9^Heart failure unspecified^I10|||A
DG1|2||I10^Essential hypertension^I10|||S
DG1|3||E11.9^Type 2 diabetes mellitus without complications^I10|||S
AL1|1|DA|LISINOPRIL|MO|COUGH
AL1|2|DA|ASPIRIN|SV|ANAPHYLAXIS
IN1|1|BCBS001|BCBS001|BLUE CROSS BLUE SHIELD PA||||||||||||||POL123456789

Outbound — agent briefing

Awaiting run — press Run pipeline to process this message.

The briefing merges the inbound HL7 event with the patient's existing chart pulled from FHIR (above), then runs the clinical quality gate over the combined result.

ADT^A03 — 9 in, 8 enriched, 66 outRecorded from real runs — not executing in your browser.Synthetic patient data. No PHI.

What the quality gate catches

Validating what arrived is the easy half. The failures that actually poison an agent's context are quieter than a malformed segment.

Data gap

A required lab is missing.

The post-discharge heart-failure protocol expects a BNP result (LOINC 42637-9). Nothing in the message is malformed — something simply is not there, and the agent is told before it dials.

Freshness

Present, but too old to trust.

Labs are checked against a per-use-case age threshold, so a stale creatinine cannot quietly stand in for a current one.

Per site

Field positions differ by health system.

Segment offsets, date formats and code systems come from configuration rather than code, so onboarding a new site does not mean forking the parser.

The rules are configuration

Required labs, reference ranges and staleness thresholds live in YAML per clinical use case — so a new workflow is a config change, not a code change.

use_cases:
  post_discharge_chf:
    description: "Post-discharge follow-up for congestive heart failure patients"
    required_fields:
      - patient
      - diagnoses
      - medications
      - labs
    required_labs:
      - "42637-9"   # BNP
      - "2160-0"    # Creatinine
      - "2823-3"    # Potassium

config/validation_rules.yaml