iris-vector-graph 1.91.3__tar.gz → 1.92.0__tar.gz

{iris_vector_graph-1.91.3 → iris_vector_graph-1.92.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris-vector-graph
-Version: 1.91.3
+Version: 1.92.0
 Summary: Transactional Graph + Vector retrieval system for InterSystems IRIS with hybrid search, openCypher, and GraphQL APIs
 Project-URL: Homepage, https://github.com/intersystems-community/iris-vector-graph
 Project-URL: Documentation, https://github.com/intersystems-community/iris-vector-graph/tree/main/docs
@@ -696,11 +696,29 @@ components  = ops.kg_WCC()
 ## FHIR Bridge
 
 ```python
+from iris_vector_graph import get_kg_anchors, unified_clinical_pipeline, FHIRSearchTool
+
 # Load ICD-10→MeSH mappings from UMLS MRCONSO
 # python scripts/ingest/load_umls_bridges.py --mrconso /path/to/MRCONSO.RRF
 
+# Resolve ICD-10 codes to KG node IDs
 anchors = engine.get_kg_anchors(icd_codes=["J18.0", "E11.9"])
 # → ["MeSH:D001996", "MeSH:D003924"]  (filtered to nodes in KG)
+
+# Full pipeline: FHIR patient → conditions → KG anchors → PPR → ranked results
+result = unified_clinical_pipeline(
+    engine=engine,
+    query="pneumonia elderly",
+    fhir_base_url="http://localhost:8080/fhir",
+    patient_id="maria-gonzalez-001",
+)
+# result["status"] → "ok"
+# result["anchors"] → ["MeSH:D011014", "MeSH:D003924"]
+# result["ppr_results"] → [{"node_id": "...", "score": 0.85}, ...]
+
+# MCP-compatible tool for AI agents
+tool = FHIRSearchTool(base_url="http://localhost:8080/fhir")
+conditions = tool("patient-123")  # → {"conditions": [...], "error": None}
 ```
 
 ---
@@ -1234,6 +1252,21 @@ Four openCypher gaps closed, all from structured gap analysis against the openCy
 
 ## Changelog
 
+### v1.92.0 (2026-05-11)
+
+**FHIR-KG Clinical Bridge** — new `iris_vector_graph.fhir_bridge` module bridges clinical patient data to the biomedical knowledge graph.
+
+- `get_kg_anchors(engine, icd_codes)` — resolve ICD-10 codes to KG node IDs via `fhir_bridges` table
+- `extract_icd_codes(bundle)` — parse ICD-10 codes from FHIR Condition bundles
+- `fhir_search_conditions(url, patient_id)` — FHIR REST client (10s independent timeout, BasicAuth)
+- `unified_clinical_pipeline(engine, ...)` — full pipeline: FHIR → anchors → PPR → ranked results with provenance
+- `FHIRSearchTool` — MCP-compatible FHIR search wrapper for AI agents
+- `GetPatientKGNeighborhoodTool` — MCP-compatible patient → graph neighborhood tool
+- Cypher API: `POST /api/cypher` accepts optional `fhir_patient_id` + `fhir_base_url` — auto-resolves patient anchors into `$patient_anchors` parameter
+
+**Bug fix:**
+- Duplicate key detection now catches IRIS's actual "failed unique check" error message (previously only checked for SQLCODE -119 and "duplicate" substring, which don't match)
+
 ### v1.91.0 (2026-05-09)
 
 **Engine-first architecture** — `IRISGraphOperators` is now a thin shim over `IRISGraphEngine`.

{iris_vector_graph-1.91.3 → iris_vector_graph-1.92.0}/README.md

@@ -624,11 +624,29 @@ components  = ops.kg_WCC()
 ## FHIR Bridge
 
 ```python
+from iris_vector_graph import get_kg_anchors, unified_clinical_pipeline, FHIRSearchTool
+
 # Load ICD-10→MeSH mappings from UMLS MRCONSO
 # python scripts/ingest/load_umls_bridges.py --mrconso /path/to/MRCONSO.RRF
 
+# Resolve ICD-10 codes to KG node IDs
 anchors = engine.get_kg_anchors(icd_codes=["J18.0", "E11.9"])
 # → ["MeSH:D001996", "MeSH:D003924"]  (filtered to nodes in KG)
+
+# Full pipeline: FHIR patient → conditions → KG anchors → PPR → ranked results
+result = unified_clinical_pipeline(
+    engine=engine,
+    query="pneumonia elderly",
+    fhir_base_url="http://localhost:8080/fhir",
+    patient_id="maria-gonzalez-001",
+)
+# result["status"] → "ok"
+# result["anchors"] → ["MeSH:D011014", "MeSH:D003924"]
+# result["ppr_results"] → [{"node_id": "...", "score": 0.85}, ...]
+
+# MCP-compatible tool for AI agents
+tool = FHIRSearchTool(base_url="http://localhost:8080/fhir")
+conditions = tool("patient-123")  # → {"conditions": [...], "error": None}
 ```
 
 ---
@@ -1162,6 +1180,21 @@ Four openCypher gaps closed, all from structured gap analysis against the openCy
 
 ## Changelog
 
+### v1.92.0 (2026-05-11)
+
+**FHIR-KG Clinical Bridge** — new `iris_vector_graph.fhir_bridge` module bridges clinical patient data to the biomedical knowledge graph.
+
+- `get_kg_anchors(engine, icd_codes)` — resolve ICD-10 codes to KG node IDs via `fhir_bridges` table
+- `extract_icd_codes(bundle)` — parse ICD-10 codes from FHIR Condition bundles
+- `fhir_search_conditions(url, patient_id)` — FHIR REST client (10s independent timeout, BasicAuth)
+- `unified_clinical_pipeline(engine, ...)` — full pipeline: FHIR → anchors → PPR → ranked results with provenance
+- `FHIRSearchTool` — MCP-compatible FHIR search wrapper for AI agents
+- `GetPatientKGNeighborhoodTool` — MCP-compatible patient → graph neighborhood tool
+- Cypher API: `POST /api/cypher` accepts optional `fhir_patient_id` + `fhir_base_url` — auto-resolves patient anchors into `$patient_anchors` parameter
+
+**Bug fix:**
+- Duplicate key detection now catches IRIS's actual "failed unique check" error message (previously only checked for SQLCODE -119 and "duplicate" substring, which don't match)
+
 ### v1.91.0 (2026-05-09)
 
 **Engine-first architecture** — `IRISGraphOperators` is now a thin shim over `IRISGraphEngine`.

{iris_vector_graph-1.91.3 → iris_vector_graph-1.92.0}/iris_vector_graph/__init__.py

@@ -24,6 +24,14 @@ from .dbapi_utils import (
     create_ivfflat_index,
     vector_similarity_search,
 )
+from .fhir_bridge import (
+    get_kg_anchors,
+    extract_icd_codes,
+    fhir_search_conditions,
+    unified_clinical_pipeline,
+    FHIRSearchTool,
+    GetPatientKGNeighborhoodTool,
+)
 
 try:
     from .embedded import EmbeddedConnection, EmbeddedCursor
@@ -58,4 +66,10 @@ __all__ = [
     "KHop2Input",
     "TemporalEdgeInput",
     "VecSearchInput",
+    "get_kg_anchors",
+    "extract_icd_codes",
+    "fhir_search_conditions",
+    "unified_clinical_pipeline",
+    "FHIRSearchTool",
+    "GetPatientKGNeighborhoodTool",
 ]

{iris_vector_graph-1.91.3 → iris_vector_graph-1.92.0}/iris_vector_graph/bulk_loader.py

@@ -70,8 +70,8 @@ class BulkLoader:
                 if commit_per_batch:
                     self.conn.rollback()
                 err_str = str(e)
-                # UNIQUE violation: fall back to row-by-row for this batch
-                if "-119" in err_str or "UNIQUE" in err_str:
+                err_lower = err_str.lower()
+                if "-119" in err_str or "unique" in err_lower:
                     for row in batch:
                         try:
                             cursor.execute(sql, row)

{iris_vector_graph-1.91.3 → iris_vector_graph-1.92.0}/iris_vector_graph/cypher_api.py

@@ -18,9 +18,11 @@ from pathlib import Path
 from pydantic import BaseModel, Field
 
 try:
+    from iris_vector_graph.embedded import _ensure_embedded_iris_first
+    _ensure_embedded_iris_first()
     import iris
-    _EMBEDDED = True
-except ImportError:
+    _EMBEDDED = hasattr(iris, 'cls')
+except (ImportError, Exception):
     _EMBEDDED = False
 
 from contextlib import asynccontextmanager
@@ -93,6 +95,9 @@ class CypherRequest(BaseModel):
     query: str
     parameters: dict[str, Any] = Field(default_factory=dict)
     limitRows: int = 1000
+    fhir_patient_id: str | None = None
+    fhir_base_url: str | None = None
+    fhir_auth: tuple[str, str] | list[str] | None = None
 
 
 @app.websocket("/")
@@ -183,12 +188,37 @@ def health():
         return {"status": "ok", "engine": False, "error": str(e)}
 
 
+def _resolve_patient_anchors(req: CypherRequest) -> list[str]:
+    from iris_vector_graph.fhir_bridge import fhir_search_conditions, get_kg_anchors
+
+    fhir_url = req.fhir_base_url or os.environ.get("FHIR_BASE_URL", "")
+    if not fhir_url:
+        return []
+    auth = tuple(req.fhir_auth) if req.fhir_auth else None
+    fhir_result = fhir_search_conditions(
+        fhir_base_url=fhir_url,
+        patient_id=req.fhir_patient_id,
+        auth=auth,
+    )
+    if fhir_result["error"] or not fhir_result["conditions"]:
+        return []
+    icd_codes = [c["code"] for c in fhir_result["conditions"] if c.get("code")]
+    if not icd_codes:
+        return []
+    engine = _get_engine()
+    return get_kg_anchors(engine, icd_codes)
+
+
 @app.post("/api/cypher")
 def cypher_query(req: CypherRequest):
     trace_id = str(uuid.uuid4())[:8]
     t0 = time.time()
     try:
-        result = _run_cypher(req.query, req.parameters, req.limitRows)
+        params = dict(req.parameters)
+        if req.fhir_patient_id:
+            anchors = _resolve_patient_anchors(req)
+            params["patient_anchors"] = anchors
+        result = _run_cypher(req.query, params, req.limitRows)
         duration = int((time.time() - t0) * 1000)
         _log("POST", "/api/cypher", 200, duration, trace_id)
         return result

{iris_vector_graph-1.91.3 → iris_vector_graph-1.92.0}/iris_vector_graph/engine.py

@@ -879,14 +879,20 @@ class IRISGraphEngine:
 
     def _assert_node_exists(self, node_id: str) -> None:
         cursor = self.conn.cursor()
-        # Use constant table names or sanitized identifiers
-        table = validate_table_name("nodes")
-        cursor.execute(
-            f"SELECT COUNT(*) FROM Graph_KG.{table} WHERE node_id = ?", [node_id]
-        )
-        result = cursor.fetchone()
-        if not result or result[0] == 0:
-            raise ValueError(f"Node does not exist: {node_id}")
+        try:
+            cursor.execute(
+                f"SELECT COUNT(*) FROM {_table('nodes')} WHERE node_id = ?", [node_id]
+            )
+            result = cursor.fetchone()
+            if not result or result[0] == 0:
+                raise ValueError(f"Node does not exist: {node_id}")
+        except ValueError:
+            raise
+        except Exception:
+            pass
+        finally:
+            if hasattr(cursor, 'close'):
+                cursor.close()
 
     def execute_cypher(
         self, cypher_query: str, parameters: Dict[str, Any] = None,
@@ -2823,10 +2829,11 @@ class IRISGraphEngine:
             return True
         except Exception as e:
             cursor.execute("ROLLBACK")
+            err_lower = str(e).lower()
             if (
-                "UNIQUE" in str(e)
+                "unique" in err_lower
                 or "-119" in str(e)
-                or "validation failed" in str(e).lower()
+                or "validation failed" in err_lower
             ):
                 logger.debug(f"create_node skipped: {node_id}: {str(e)[:80]}")
             else:
@@ -2858,7 +2865,8 @@ class IRISGraphEngine:
             self.conn.commit()
         except Exception as e:
             self.conn.rollback()
-            if "UNIQUE" in str(e) or "-119" in str(e):
+            err_lower = str(e).lower()
+            if "unique" in err_lower or "-119" in str(e):
                 logger.debug(
                     f"create_edge duplicate: {source_id}-[{predicate}]->{target_id}"
                 )
@@ -6810,7 +6818,9 @@ class IRISGraphEngine:
 
     def get_node_properties(self, node_id: str) -> Dict[str, Any]:
         node = self.get_node(node_id)
-        return node.get("properties", {}) if node else {}
+        if not node:
+            return {}
+        return {k: v for k, v in node.items() if k not in ("id", "labels")}
 
     def get_node_name(self, node_id: str) -> Optional[str]:
         props = self.get_node_properties(node_id)
@@ -6847,11 +6857,13 @@ class IRISGraphEngine:
         cursor = self.conn.cursor()
         try:
             cursor.execute(
-                f"INSERT OR IGNORE INTO {_table('nodes')} (node_id) VALUES (?)", [node_id]
+                f"INSERT INTO {_table('nodes')} (node_id) VALUES (?)", [node_id]
             )
             self.conn.commit()
-        except Exception:
-            pass
+        except Exception as e:
+            err_lower = str(e).lower()
+            if "-119" not in str(e) and "duplicate" not in err_lower and "unique" not in err_lower:
+                raise
         finally:
             cursor.close()
         if properties:
@@ -6860,7 +6872,11 @@ class IRISGraphEngine:
                 cursor2 = self.conn.cursor()
                 try:
                     cursor2.execute(
-                        f"INSERT OR REPLACE INTO {_table('rdf_props')} (s, \"key\", val) VALUES (?, ?, ?)",
+                        f"DELETE FROM {_table('rdf_props')} WHERE s = ? AND \"key\" = ?",
+                        [node_id, k]
+                    )
+                    cursor2.execute(
+                        f"INSERT INTO {_table('rdf_props')} (s, \"key\", val) VALUES (?, ?, ?)",
                         [node_id, k, val_str]
                     )
                     self.conn.commit()
@@ -6873,12 +6889,66 @@ class IRISGraphEngine:
                 cursor3 = self.conn.cursor()
                 try:
                     cursor3.execute(
-                        f"INSERT OR IGNORE INTO {_table('rdf_labels')} (s, label) VALUES (?, ?)",
+                        f"INSERT INTO {_table('rdf_labels')} (s, label) VALUES (?, ?)",
                         [node_id, lbl]
                     )
                     self.conn.commit()
-                except Exception:
-                    pass
+                except Exception as e:
+                    err_lower = str(e).lower()
+                    if "-119" not in str(e) and "duplicate" not in err_lower and "unique" not in err_lower:
+                        raise
                 finally:
                     cursor3.close()
         return True
+
+    def store_edge(self, source_id: str, predicate: str, target_id: str,
+                   qualifiers: Optional[Dict[str, Any]] = None) -> bool:
+        self.store_node(source_id)
+        self.store_node(target_id)
+        cursor = self.conn.cursor()
+        try:
+            qual_json = json.dumps(qualifiers) if qualifiers else None
+            cursor.execute(
+                f"INSERT INTO {_table('rdf_edges')} (s, p, o_id, qualifiers) VALUES (?, ?, ?, ?)",
+                [source_id, predicate, target_id, qual_json],
+            )
+            self.conn.commit()
+        except Exception as e:
+            err_lower = str(e).lower()
+            if "-119" not in str(e) and "duplicate" not in err_lower and "unique" not in err_lower:
+                raise
+        finally:
+            cursor.close()
+        return True
+
+    def nodes_exist(self, node_ids: List[str]) -> set:
+        if not node_ids:
+            return set()
+        existing: set = set()
+        cursor = self.conn.cursor()
+        try:
+            for i in range(0, len(node_ids), 200):
+                batch = node_ids[i:i + 200]
+                phs = ",".join(["?"] * len(batch))
+                try:
+                    cursor.execute(
+                        f"SELECT node_id FROM {_table('nodes')} WHERE node_id IN ({phs})",
+                        batch,
+                    )
+                    for row in cursor.fetchall():
+                        existing.add(row[0])
+                except Exception:
+                    for nid in batch:
+                        try:
+                            cursor.execute(
+                                f"SELECT COUNT(*) FROM {_table('nodes')} WHERE node_id = ?",
+                                [nid],
+                            )
+                            row = cursor.fetchone()
+                            if row and int(row[0]) > 0:
+                                existing.add(nid)
+                        except Exception:
+                            pass
+        finally:
+            cursor.close()
+        return existing