Medication Safety and Interaction Assistant

An AI agent built on InterSystems IRIS AI Hub that analyses a patient’s FHIR medication record for safety signals. Given a patient ID, it queries a FHIR R4 server and runs deterministic checks across 14 safety categories, producing structured findings and recommended clinician actions.

Safety categories checked:
Black box warnings · Drug-drug interactions · Drug-food cautions · Population contraindications (age, pregnancy/lactation) · Activity cautions (driving, machinery) · Drug-condition warnings · Lab threshold warnings · QT/arrhythmia risk · Anticholinergic burden · Mental health warnings · Family history risks · Duplicate therapy · Allergy cross-check · Adherence signals

Team

• Gil Tavassy — Developer Community profile · LinkedIn

Submission mode: solo project.

Architecture

One container runs the safety engine and connects to your FHIR server:

The container connects to a FHIR R4 server running on your host machine (or any reachable URL configured in .env).

Prerequisites

• Docker Desktop (Windows / Mac) or Docker Engine (Linux)
• InterSystems IRIS AI Hub EAP image — the AI Hub is baked into this image.
  1. Register / log in at https://evaluation.intersystems.com/Eval/early-access/AIHub and select the AI Hub program.
  2. Download two files:
     • irishealth-community-2026.2.0AI.162.0-docker.tar.gz (x64) — or the arm64 variant for Mac M-series
     • iris-container-x64.key (or iris-container-arm64.key for ARM64)
  3. Load and tag the image (one-time step per machine):

     docker image load -i irishealth-community-2026.2.0AI.162.0-docker.tar.gz
     docker tag docker.iscinternal.com/docker-intersystems/intersystems/irishealth-community:2026.2.0AI.162.0 irishealth-community:2026.2.0AI.162.0
     

Quick start

1. Clone this repository.
2. Copy your iris-container-x64.key into the keys/ folder at the repo root.
3. Open .env and set FHIR_BASE_URL to your FHIR server’s address. The default (http://host.docker.internal:52773/fhir/r4) points to the standard IRIS web port on your host machine — no change needed if that is where your server runs.
4. Build and start:

   docker compose build
   docker compose up -d
   

5. Wait ~60 seconds for the container to become healthy.
6. Load patient data into your FHIR server (see Patient data below).
7. Run a safety analysis.

Patient data

The safety engine requires at least one patient in your FHIR R4 server.

Option A — Load from the included test cases

Each file in med_safety_io/ contains a ready-made FHIR patient bundle under inputResources. Use the included helper script to post all test profiles at once:

python scripts/create_medication_safety_profiles.py

By default the script posts to http://localhost:52773/fhir/r4 (your host FHIR server). Set FHIR_BASE_URL in the environment to override:

FHIR_BASE_URL=http://localhost:52773/fhir/r4 python scripts/create_medication_safety_profiles.py

This creates patients covering the main safety scenarios: duplicate therapy, drug-drug interaction, allergy conflict, QT risk, anticholinergic burden, and more.

Option B — Load your own FHIR R4 patient

Use any FHIR R4 client (Postman, HAPI FHIR CLI, curl) to POST patient data to your FHIR server.

Note the patient ID — you’ll use it in the run command below.

Running a safety analysis

Replace <patientId> with your patient’s FHIR ID:

docker exec medication-safety-and-interaction-assistant-iris-1 bash -c \
  "printf 'Do ##class(Sample.AI.Examples.MedicationSafetyAssistant).Demo(\"\",\"detailed\")\nHalt\n' \
  | iris session IRIS -U USER 2>&1 | grep -Ev '^(USER>|Node:)'"

Test case patient IDs (after running create_medication_safety_profiles.py):

Environment variables

Set in .env (loaded automatically by Docker Compose):

FHIR resources used

Patient · MedicationRequest · MedicationStatement · AllergyIntolerance · Condition · Observation · FamilyMemberHistory

Output structure

Each analysis produces:

• Patient Overview — demographics and evidence inventory
• Clinical Snapshot — findings across all 14 safety categories (strict warnings first, then conservative)
• Recommended Actions — structured list with actionType, priority, slaHours, sourceRisk
• Counseling Summary — plain-language guidance for the clinician
• Context-Aware Guidance — vector search snippets when configured
• Review Notes — resource counts for audit

Example artifacts

Pre-generated outputs are in med_safety_io/ — each *-case.json file contains the input FHIR resources and the assistant’s full output for that safety scenario.