fhir-ig-rag

A pragmatic “IG facts service” for PS-CA (Patient Summary for Canada). It turns the official StructureDefinition JSON artifacts into deterministic, queryable answers for conformance, testing, and implementation support.

---

Why this exists

Standards and vendor discussions often stall on questions like:

• What is Must Support for this profile?
• What constraints/invariants apply?
• Which ValueSet is bound here, and how strong is the binding?
• If we change a ValueSet, what breaks?

This project makes those answers traceable to the IG artifacts, reducing ambiguity, speeding reviews, and enabling “blast radius” analysis for terminology/profile changes. It also exposes MCP tools so agents can fetch facts instead of guessing.

---

Architecture (high level)

Data flow

StructureDefinition JSONs
  -> ingestion CLI loaders
    -> Postgres tables (packages, artifacts, sd_elements, sd_bindings, sd_constraints)
      -> FastAPI “facts” endpoints
        -> MCP tools (wrap the API for agent hosts)

Core data model

• packages: ig, ig_version
• artifacts: canonical_url, version, name, sd_type, baseDefinition, title, file_path
• sd_elements: artifact_id + path (unique), must_support, min/max, source (diff/snapshot)
• sd_bindings: artifact_id + path + value_set (unique), strength, source (diff/snapshot), value_set is non-null ('' if missing)
• sd_constraints: artifact_id + path + key (unique), severity, human, expression, source

---

Capabilities

FastAPI endpoints

• GET /health
• GET /gq/must-support
• GET /gq/bindings
• GET /gq/constraints
• GET /gq/value-set/where-used

MCP tools (stdio)

• psca_must_support
• psca_bindings
• psca_constraints
• psca_where_used_value_set

---

Setup on your machine

Prerequisites

• Python 3.10+
• Postgres reachable (Docker compose included)
• macOS/Linux shell examples (zsh/bash)

1) Clone & venv

git clone <repo-url>
cd fhir-ig-rag
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -e .

2) Environment

Create .env:

cat > .env <<'EOF'
DATABASE_URL=postgresql+psycopg://ig:ig@localhost:5432/igdb
EOF

3) Start Postgres (Docker option)

docker compose up -d
# psql inside container:
docker exec -it fhir_ig_rag_postgres psql -U ig -d igdb

4) Migrations

.venv/bin/python -m alembic upgrade head
# or: make migrate

5) Import PS-CA StructureDefinitions

Place the JSONs at data/artifacts/ps-ca/2.1.1/StructureDefinition/, then:

.venv/bin/python -m app.ingest.cli import-structuredefs \
  --ig ps-ca \
  --ig-version 2.1.1 \
  --dir data/artifacts/ps-ca/2.1.1/StructureDefinition
# or: make import-psca

6) Load extracted features

.venv/bin.python -m app.ingest.cli load-sd-elements --ig ps-ca --ig-version 2.1.1
.venv/bin.python -m app.ingest.cli load-sd-bindings --ig ps-ca --ig-version 2.1.1
.venv/bin.python -m app.ingest.cli load-sd-constraints --ig ps-ca --ig-version 2.1.1

7) Smoke test DB connectivity (API layer)

.venv/bin/python -c "from app.api.db import SessionLocal; from sqlalchemy import text; s=SessionLocal(); s.execute(text('select 1')); print('db ok'); s.close()"

8) Run FastAPI server

.venv/bin.python -m uvicorn app.api.main:app --reload --port 8000
# or: make serve

Health check:

curl -s http://localhost:8000/health

---

FastAPI usage examples

# 1) Must Support paths
curl -s "http://localhost:8000/gq/must-support?canonical=http://fhir.infoway-inforoute.ca/io/psca/StructureDefinition/patient-ca-ps" | jq .

# 2) Binding at a path
curl -s "http://localhost:8000/gq/bindings?canonical=http://fhir.infoway-inforoute.ca/io/psca/StructureDefinition/allergyintolerance-ca-ps&path=AllergyIntolerance.code" | jq .

# 3) Constraints for a profile (and optional path filter)
curl -s "http://localhost:8000/gq/constraints?canonical=http://fhir.infoway-inforoute.ca/io/psca/StructureDefinition/patient-ca-ps" | jq .
curl -s "http://localhost:8000/gq/constraints?canonical=http://fhir.infoway-inforoute.ca/io/psca/StructureDefinition/patient-ca-ps&path=Patient.name" | jq .

# 4) ValueSet where-used (blast radius)
curl -s "http://localhost:8000/gq/value-set/where-used?value_set=https://fhir.infoway-inforoute.ca/ValueSet/pharmaceuticalbiologicproductandsubstancecode" | jq .

# 5) Profile summary (top mustSupport/bindings/constraints)
curl -s "http://localhost:8000/gq/profile-summary?canonical=http://fhir.infoway-inforoute.ca/io/psca/StructureDefinition/patient-ca-ps" | jq .
# Full lists (include_all=true)
curl -s "http://localhost:8000/gq/profile-summary?canonical=http://fhir.infoway-inforoute.ca/io/psca/StructureDefinition/patient-ca-ps&include_all=true" | jq .

# 6) Element details (bindings/constraints for a specific path)
curl -s "http://localhost:8000/gq/element-details?canonical=http://fhir.infoway-inforoute.ca/io/psca/StructureDefinition/allergyintolerance-ca-ps&path=AllergyIntolerance.code" | jq .

---

MCP server (tools for agents)

Prereq: FastAPI running on localhost:8000.

Run MCP server (stdio):

.venv/bin/python -m app.mcp_server.server

Tools exposed:

• psca_must_support(canonical, version=None)
• psca_bindings(canonical, path, version=None)
• psca_constraints(canonical, path=None, version=None)
• psca_where_used_value_set(value_set, ig='ps-ca', ig_version='2.1.1')
• psca_profile_summary(canonical, version=None)
• psca_profile_summary_all(canonical, version=None)
• psca_element_details(canonical, path, version=None)
• psca_router(question, canonical=None, path=None, value_set=None, version=None, execute=True) (hybrid NL router)

Router env vars:

• ROUTER_MODE=ollama (otherwise deterministic)
• OLLAMA_URL (default http://localhost:11434)
• OLLAMA_MODEL (default qwen2.5:3b-instruct)

Example natural-language prompts (no tool names needed):

1. “What bindings apply to AllergyIntolerance.code in PS-CA? canonical http://fhir.infoway-inforoute.ca/io/psca/StructureDefinition/allergyintolerance-ca-ps”
2. “Show me everything required for Patient.name in PS-CA (must support, bindings, constraints).”
3. “Where is https://fhir.infoway-inforoute.ca/ValueSet/pharmaceuticalbiologicproductandsubstancecode used across PS-CA?”

Claude Desktop quick setup

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "fhir-ig-rag-psca": {
      "command": "/ABSOLUTE/PATH/TO/fhir-ig-rag/.venv/bin/python",
      "args": ["-m", "app.mcp_server.server"],
      "env": { "PYTHONUNBUFFERED": "1" }
    }
  }
}

Restart Claude Desktop. The MCP server stays quiet until the client sends tool calls.

---

Troubleshooting

• Port in use: run uvicorn on another port (--port 8001) and adjust MCP base URL in app/mcp_server/server.py if needed.
• MCP seems idle: stdio servers print nothing until a client sends requests—this is expected.
• jq errors: if the response isn’t JSON (e.g., 404 HTML), jq will fail; inspect with curl -i.

---

Roadmap ideas

• Support additional artifact types (ValueSet, CodeSystem, CapabilityStatement)
• Profile lineage and “what changed vs base” diffs
• Analytics endpoints (top ValueSets, top constraints)
• Agent client that chains these tools with an LLM for richer reasoning

If you want this README tailored to a specific workflow or deployment target, let me know and I’ll adjust the commands accordingly.