iris-vector-graph 1.45.0__tar.gz → 1.45.2__tar.gz

{iris_vector_graph-1.45.0 → iris_vector_graph-1.45.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris-vector-graph
-Version: 1.45.0
+Version: 1.45.2
 Summary: Transactional Graph + Vector retrieval system for InterSystems IRIS with hybrid search, openCypher, and GraphQL APIs
 Project-URL: Homepage, https://github.com/isc-tdyar/iris-vector-graph
 Project-URL: Documentation, https://github.com/isc-tdyar/iris-vector-graph/tree/main/docs
@@ -474,6 +474,16 @@ anchors = engine.get_kg_anchors(icd_codes=["J18.0", "E11.9"])
 
 ## Changelog
 
+### v1.45.2 (2026-04-03)
+- `embedded.py`: auto-fixes `sys.path` shadowing — ensures `/usr/irissys/lib/python` is first so the embedded `iris` module takes priority over pip-installed `intersystems_irispython`
+- `embedded.py`: clear error message when shadowed iris (no `iris.sql`) is detected, naming the root cause
+- Documented the XD timeout constraint and embed_daemon pattern for long-running ML operations in embedded context
+- 3 new tests covering path-fix and shadowing detection
+
+### v1.45.1 (2026-04-03)
+- `embed_nodes`: FK-safe delete — DELETE failure on `kg_NodeEmbeddings` (spurious FK error in embedded Python context) is silently ignored; INSERT proceeds correctly
+- `vector_search`: uses `VECTOR_COSINE(TO_VECTOR(col), ...)` so it works on both native VECTOR columns AND VARCHAR-stored vectors (e.g. DocChunk.VectorChunk from fhir-017)
+
 ### v1.45.0 (2026-04-03)
 - `embed_nodes(model, where, text_fn, batch_size, force, progress_callback)` — incremental node embedding over `Graph_KG.nodes` with SQL WHERE filter, custom text builder, and per-call model override. Unblocks mixed-ontology graphs (embed only KG8 nodes without re-embedding NCIT's 200K nodes).
 - `vector_search(table, vector_col, query_embedding, top_k, id_col, return_cols, score_threshold)` — search any IRIS VECTOR column, not just `kg_NodeEmbeddings`. Works on DocChunk tables, RAG corpora, custom HNSW indexes.

{iris_vector_graph-1.45.0 → iris_vector_graph-1.45.2}/README.md

@@ -403,6 +403,16 @@ anchors = engine.get_kg_anchors(icd_codes=["J18.0", "E11.9"])
 
 ## Changelog
 
+### v1.45.2 (2026-04-03)
+- `embedded.py`: auto-fixes `sys.path` shadowing — ensures `/usr/irissys/lib/python` is first so the embedded `iris` module takes priority over pip-installed `intersystems_irispython`
+- `embedded.py`: clear error message when shadowed iris (no `iris.sql`) is detected, naming the root cause
+- Documented the XD timeout constraint and embed_daemon pattern for long-running ML operations in embedded context
+- 3 new tests covering path-fix and shadowing detection
+
+### v1.45.1 (2026-04-03)
+- `embed_nodes`: FK-safe delete — DELETE failure on `kg_NodeEmbeddings` (spurious FK error in embedded Python context) is silently ignored; INSERT proceeds correctly
+- `vector_search`: uses `VECTOR_COSINE(TO_VECTOR(col), ...)` so it works on both native VECTOR columns AND VARCHAR-stored vectors (e.g. DocChunk.VectorChunk from fhir-017)
+
 ### v1.45.0 (2026-04-03)
 - `embed_nodes(model, where, text_fn, batch_size, force, progress_callback)` — incremental node embedding over `Graph_KG.nodes` with SQL WHERE filter, custom text builder, and per-call model override. Unblocks mixed-ontology graphs (embed only KG8 nodes without re-embedding NCIT's 200K nodes).
 - `vector_search(table, vector_col, query_embedding, top_k, id_col, return_cols, score_threshold)` — search any IRIS VECTOR column, not just `kg_NodeEmbeddings`. Works on DocChunk tables, RAG corpora, custom HNSW indexes.

{iris_vector_graph-1.45.0 → iris_vector_graph-1.45.2}/iris_vector_graph/embedded.py

@@ -11,14 +11,60 @@ Language=python method with zero boilerplate:
 
 Only available when running inside IRIS (the embedded iris module must be
 importable). Raises ImportError with a clear message otherwise.
+
+## Known constraints for Language=python (wgproto) context
+
+### sys.path shadowing after pip install
+When iris-vector-graph is pip-installed inside an IRIS container, the pip
+package puts an external `iris` (intersystems_irispython) on sys.path. This
+external `iris` lacks `iris.execute`, `iris.gref`, `iris.cls`, and
+`iris.sql` — so Language=python methods that call EmbeddedConnection break.
+
+Fix: ensure `/usr/irissys/lib/python` is first in sys.path so the embedded
+`iris` module takes priority. This module does that automatically in
+`_require_iris_sql()`.
+
+### Long-running operations (model loading, bulk embed) and XD timeout
+Language=python methods run inside a wgproto job with a configurable XD
+timeout (default ~30s). Loading a SentenceTransformer model takes ~8-10s,
+which may exceed the timeout.
+
+Pattern for long-running ML operations:
+1. Run as a persistent `irispython` process outside the wgproto lifecycle
+2. Communicate via IRIS globals (e.g. `^EmbedQueue(reqId, "text") = text`)
+3. Language=python method submits to queue and polls for result
+
+See iris_vector_graph/docs/embedded-ml-pattern.md for a reference
+implementation (the "embed_daemon" pattern).
 """
 
 __all__ = ["EmbeddedConnection", "EmbeddedCursor"]
 
+import sys as _sys
+
+
+def _ensure_embedded_iris_first():
+    embedded_path = '/usr/irissys/lib/python'
+    mgr_path = '/usr/irissys/mgr/python'
+    if embedded_path not in _sys.path:
+        _sys.path.insert(0, embedded_path)
+    elif _sys.path[0] != embedded_path:
+        _sys.path.remove(embedded_path)
+        _sys.path.insert(0, embedded_path)
+    if mgr_path not in _sys.path:
+        _sys.path.insert(1, mgr_path)
+
 
 def _require_iris_sql():
+    _ensure_embedded_iris_first()
     try:
         import iris  # noqa: F401
+        if not hasattr(iris, 'sql'):
+            raise ImportError(
+                "iris module found but has no iris.sql attribute — "
+                "the pip intersystems_irispython package is shadowing the embedded iris module. "
+                "Ensure /usr/irissys/lib/python is first in sys.path."
+            )
         return iris.sql
     except ImportError as exc:
         raise ImportError(

{iris_vector_graph-1.45.0 → iris_vector_graph-1.45.2}/iris_vector_graph/engine.py

@@ -1209,7 +1209,10 @@ class IRISGraphEngine:
                     try:
                         emb = self.embed_text(text)
                         emb_str = ",".join(str(x) for x in emb)
-                        cursor.execute(f"DELETE FROM {_table('kg_NodeEmbeddings')} WHERE id = ?", [node_id])
+                        try:
+                            cursor.execute(f"DELETE FROM {_table('kg_NodeEmbeddings')} WHERE id = ?", [node_id])
+                        except Exception:
+                            pass
                         cursor.execute(
                             f"INSERT INTO {_table('kg_NodeEmbeddings')} (id, emb) VALUES (?, TO_VECTOR(?))",
                             [node_id, emb_str],
@@ -1688,7 +1691,7 @@ class IRISGraphEngine:
             query_vec_str = query_embedding
 
         extra = ", ".join(sanitize_identifier(c) for c in (return_cols or []) if c != id_col)
-        select_cols = f"t.{id_col}, VECTOR_COSINE(t.{vector_col}, TO_VECTOR(?, DOUBLE)) AS score"
+        select_cols = f"t.{id_col}, VECTOR_COSINE(TO_VECTOR(t.{vector_col}), TO_VECTOR(?, DOUBLE)) AS score"
         if extra:
             select_cols += f", {extra}"
 

{iris_vector_graph-1.45.0 → iris_vector_graph-1.45.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "iris-vector-graph"
-version = "1.45.0"
+version = "1.45.2"
 description = "Transactional Graph + Vector retrieval system for InterSystems IRIS with hybrid search, openCypher, and GraphQL APIs"
 readme = "README.md"
 license = "MIT"

{iris_vector_graph-1.45.0 → iris_vector_graph-1.45.2}/tests/unit/test_embedded.py

@@ -168,6 +168,42 @@ class TestEmbeddedConnectionUnit:
             with pytest.raises(ImportError, match="embedded iris module"):
                 _require_iris_sql()
 
+    def test_shadowed_iris_error_message_contains_guidance(self):
+        from iris_vector_graph import embedded
+        import importlib, inspect
+        src = inspect.getsource(embedded._require_iris_sql)
+        assert "iris.sql attribute" in src
+        assert "intersystems_irispython" in src
+        assert "lib/python" in src or "/usr/irissys" in src
+
+    def test_ensure_embedded_iris_first_inserts_path(self):
+        from iris_vector_graph.embedded import _ensure_embedded_iris_first
+        import sys
+        embedded_path = '/usr/irissys/lib/python'
+        original = sys.path.copy()
+        try:
+            if embedded_path in sys.path:
+                sys.path.remove(embedded_path)
+            _ensure_embedded_iris_first()
+            assert sys.path[0] == embedded_path
+        finally:
+            sys.path[:] = original
+
+    def test_ensure_embedded_iris_first_moves_to_front_if_not_first(self):
+        from iris_vector_graph.embedded import _ensure_embedded_iris_first
+        import sys
+        embedded_path = '/usr/irissys/lib/python'
+        original = sys.path.copy()
+        try:
+            if embedded_path in sys.path:
+                sys.path.remove(embedded_path)
+            sys.path.append(embedded_path)
+            assert sys.path[0] != embedded_path
+            _ensure_embedded_iris_first()
+            assert sys.path[0] == embedded_path
+        finally:
+            sys.path[:] = original
+
 
 class TestTopLevelImports: