Fhir Ig Rag

真实的

务实 “IG事实服务” PS-CA（加拿大患者总结）。它将官方的StructureDefinition JSON工件转化为确定性的、可查询的答案，以提供一致性、测试和实现支持。

______________________________________________________________________

为什么存在

标准和供应商讨论经常在以下问题上停滞不前：

• 是什么 必须支持 对于这个配置文件？
• 哪些约束/不变量适用？
• 这里绑定了哪个值集，绑定有多强？
• 如果我们更改一个ValueSet，什么会中断？

这个项目给出了这些答案 可追溯到IG工件，减少歧义，加快审查速度，并实现术语/配置文件更改的“爆炸半径”分析。它还公开了MCP工具，因此代理可以获取事实而不是猜测。

______________________________________________________________________

建筑（高级）

数据流

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)

核心数据模型

• 包裹：ig，ig版本
• 人工制品：canonical_url、版本、名称、sd_type、base定义、标题、文件路径
• sd_元素：artifact_id+路径（唯一）、must_support、最小值/最大值、源（差异/快照）
• sd_bindings：artifact_id+路径+值集（唯一）、强度、源（差异/快照）、值集不为空（如果缺少“”）
• sd约束：artifact_id+路径+密钥（唯一）、严重性、人、表达式、源

______________________________________________________________________

能力

FastAPI端点

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

MCP工具（stdio）

• psca_must_support
• psca_bindings
• psca_constraints
• psca_where_used_value_set

______________________________________________________________________

在您的计算机上进行设置

先决条件

• Python 3.10+
• Postgres可达（包括Docker compose）
• macOS/Linux shell示例（zsh/bash）

1） 克隆和虚拟

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

2） 环境

创建 .env:

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

3） 启动Postgres（Docker选项）

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

4） 移民

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

5） 导入PS-CA结构定义

将JSON放置在 data/artifacts/ps-ca/2.1.1/StructureDefinition/那么：

.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） 加载提取的特征

.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） 烟雾测试数据库连接（API层）

.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） 运行FastAPI服务器

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

健康检查：

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

______________________________________________________________________

FastAPI使用示例

# 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服务器（代理工具）

先决条件： FastAPI正在运行 localhost:8000.

运行MCP服务器（stdio）：

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

暴露的工具：

• 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) （混合NL路由器）

路由器环境变量：

• ROUTER_MODE=ollama （否则为确定性）
• OLLAMA_URL （默认值 http://localhost:11434)
• OLLAMA_MODEL （默认值 qwen2.5:3b-instruct)

自然语言提示示例（无需工具名称）：

1. “PS-CA中AllergyIntolerance.code有哪些绑定？规范http://fhir.infoway-inforoute.ca/io/psca/StructureDefinition/allergyintolerance-ca-ps”
2. “在PS-CA中显示Patient.name所需的一切（必须支持、绑定、约束）。”
3. “在哪里https://fhir.infoway-inforoute.ca/ValueSet/pharmaceuticalbiologicproductandsubstancecode在PS-CA上使用？”

克劳德桌面快速设置

增添 ~/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" }
    }
  }
}

重新启动克劳德桌面。MCP服务器保持安静，直到客户端发送工具调用。

______________________________________________________________________

故障排除

• 正在使用的端口： 在另一个港口运行uvicorn(--port 8001)并在中调整MCP基本URL app/mcp_server/server.py 如果需要的话。
• MCP似乎处于空闲状态： stdio服务器在客户端发送请求之前不会打印任何内容——这是意料之中的。
• jq错误： 如果响应不是JSON（例如404 HTML）， jq 将失败；检查 curl -i.

______________________________________________________________________

路线图构想

• 支持其他工件类型（ValueSet、CodeSystem、CapabilityStatement）
• 档案沿袭和“变化与基础”差异
• 分析端点（顶级值集、顶级约束）
• 代理客户端将这些工具与LLM链接起来，以实现更丰富的推理

如果您希望此README针对特定的工作流或部署目标进行定制，请告诉我，我将相应地调整命令。