iris-vector-graph 1.87.0__tar.gz → 1.89.0__tar.gz

{iris_vector_graph-1.87.0 → iris_vector_graph-1.89.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris-vector-graph
-Version: 1.87.0
+Version: 1.89.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
@@ -753,6 +753,45 @@ anchors = engine.get_kg_anchors(icd_codes=["J18.0", "E11.9"])
 
  ## Changelog
 
+### v1.88.0 (2026-05-07)
+- **feat**: `ffi_kg_build_2hop_exact_int` Rust function — integer-indexed single-pass 2-hop dedup from `^KG("out")`. Writes results to `^ArnoKG("2h")` temp global; `DecodeBuildResults()` ObjectScript method converts to `^KG("deg2p_exact")`
+- **feat**: `KHop2CountExact(src, pred)` ObjectScript method — O(1) `$Get(^KG("deg2p_exact"))`, fallback to `KHop2Count` when not populated. 0.14ms p50 on SF10 (was 70ms)
+- **feat**: `Build2HopExactStats()` — Rust-first (tries `kg_build_2hop_exact_int`), ObjectScript fallback. Called automatically by `BuildNKG` and `engine.rebuild_nkg()`
+- **feat**: `engine.khop2_count_exact(node_id, pred)` — public method with `KHop2Input` validation
+- **feat**: `engine.backfill_deg2p_exact()` — populate `^KG("deg2p_exact")` for graphs loaded via `BulkIngestEdges`
+- **feat**: `execute_cypher` `[:P*2] RETURN count(n)` fast path now routes to `KHop2CountExact` (exact, not upper bound)
+- **test**: `tests/e2e/test_ic3_exact_count.py` — correctness + perf validation for 2-hop exact COUNT
+- **test**: `tests/e2e/test_untested_methods.py` — 113/113 public engine methods now have at least one test (100% coverage)
+
+### v1.87.0 (2026-05-07)
+- **feat**: `iris_vector_graph/_validate.py` — 10 Pydantic `BaseModel` input schemas for high-risk engine methods: `NodeIdInput`, `EdgeInput`, `CypherInput`, `IVFBuildInput`, `VectorSearchInput`, `BM25BuildInput`, `BM25SearchInput`, `KHop2Input`, `TemporalEdgeInput`, `VecSearchInput`
+- **feat**: Input validation at call entry on `execute_cypher`, `create_node`, `create_edge`, `ivf_build`, `ivf_search`, `bm25_build`, `bm25_search`, `khop2_count_fast`, `create_edge_temporal`, `search_nodes_by_vector`
+- All 10 schemas exported from `iris_vector_graph.__init__`; 44/44 unit tests in `test_validation.py`
+- **chore**: `BulkIngestEdges` marked `[ Internal ]` in `EdgeScan.cls` — safe path is `engine.bulk_ingest_edges()`
+
+### v1.86.0 (2026-05-07)
+- **feat**: `IVGResult` Pydantic `BaseModel` replaces `Dict[str, Any]` as return type of `execute_cypher`
+  - Backward-compatible: `result["columns"]`, `result.get("error")`, `"error" in result` all work
+  - `bool(result)` = `True` on success, `False` on error
+  - `result.columns`, `result.rows`, `result.error`, `result.metadata`, `result.sql` via dot notation
+  - 23 unit tests in `test_ivgresult.py`; all 189+ existing call sites pass unchanged
+- **feat**: Fourth Pydantic increment — `IVGResult` joins `SQLQuery`, `QueryMetadata`, `IndexHandle`
+
+### v1.85.0 (2026-05-06)
+- **fix**: Unbounded variable-length path queries (no LIMIT) now always route to `_bfs_stream_pages` (cursor-based `ReadBFSPage`) instead of `ReadBFSResults` (single JSON string that hits `<MAXSTRING>` at 93K+ results). Bounded queries (LIMIT present) keep `ReadBFSResults` fast path.
+- **fix**: `test_sc003_results_match_bfs` — replaced raw `NKGAccel.BFSJson` call (bypassed engine, `^NKG` stale) with engine determinism check; `knows_data` fixture calls `engine.rebuild_nkg()` for sync guarantee
+- **test**: `tests/e2e/test_streaming_bfs.py` — 3 e2e + 2 routing unit tests for streaming BFS
+
+### v1.84.0 (2026-05-06)
+- **feat**: `engine.index(name)` → `IndexHandle` (Pydantic `BaseModel`) — unified entry point for all index types (`ivf`, `bm25`, `vec`, `plaid`) via `.search()`, `.insert()`, `.info()`, `.drop()`
+- **feat**: `IVGIndex` `@runtime_checkable` Protocol — structural subtyping, no inheritance required
+- **feat**: `_build_index_registry()` — auto-populates `{name: type}` from `^IVF`, `^VecIdx`, `^BM25Idx`, `^PLAID` on `IRISGraphEngine.__init__`; updated by `*_build` methods
+- **feat**: `PLAIDSearch.Build` public ClassMethod — calls `StoreCentroids`+`StoreDocTokensBatch`+`BuildInvertedIndex` internally; helpers marked `[ Private ]`
+- **feat**: `plaid_build()` now calls `PLAIDSearch.Build` (single round-trip); `plaid_info()` returns `{"type":"plaid","indexed":N,"nlist":L,"dim":D}`
+- **feat**: All `*_info()` methods return `"type"` key — `ivf_info()`, `bm25_info()`, `vec_info()`, `plaid_info()`
+- **feat**: `IVGIndex` and `IndexHandle` exported from `iris_vector_graph.__init__`
+- **test**: Full PLAID e2e coverage (5/5); `engine.index()` dispatch tests (5 pass, 1 skip)
+
 ### v1.83.0 (2026-05-06)
 - **feat**: `KHop2Count` + `KHop2NeighborIds(maxResults)` on `Graph.KG.Traversal` — pure ObjectScript 2-hop traversal with process-private dedup, no JSON serialization
 - **feat**: `execute_cypher` routes `[:PRED*2]` COUNT and LIMIT patterns to fast paths — IC3 LIMIT 1000 now **1.2ms p50** (was 14-22ms; 3.5x faster than GES 4.19ms)

{iris_vector_graph-1.87.0 → iris_vector_graph-1.89.0}/README.md

@@ -681,6 +681,45 @@ anchors = engine.get_kg_anchors(icd_codes=["J18.0", "E11.9"])
 
  ## Changelog
 
+### v1.88.0 (2026-05-07)
+- **feat**: `ffi_kg_build_2hop_exact_int` Rust function — integer-indexed single-pass 2-hop dedup from `^KG("out")`. Writes results to `^ArnoKG("2h")` temp global; `DecodeBuildResults()` ObjectScript method converts to `^KG("deg2p_exact")`
+- **feat**: `KHop2CountExact(src, pred)` ObjectScript method — O(1) `$Get(^KG("deg2p_exact"))`, fallback to `KHop2Count` when not populated. 0.14ms p50 on SF10 (was 70ms)
+- **feat**: `Build2HopExactStats()` — Rust-first (tries `kg_build_2hop_exact_int`), ObjectScript fallback. Called automatically by `BuildNKG` and `engine.rebuild_nkg()`
+- **feat**: `engine.khop2_count_exact(node_id, pred)` — public method with `KHop2Input` validation
+- **feat**: `engine.backfill_deg2p_exact()` — populate `^KG("deg2p_exact")` for graphs loaded via `BulkIngestEdges`
+- **feat**: `execute_cypher` `[:P*2] RETURN count(n)` fast path now routes to `KHop2CountExact` (exact, not upper bound)
+- **test**: `tests/e2e/test_ic3_exact_count.py` — correctness + perf validation for 2-hop exact COUNT
+- **test**: `tests/e2e/test_untested_methods.py` — 113/113 public engine methods now have at least one test (100% coverage)
+
+### v1.87.0 (2026-05-07)
+- **feat**: `iris_vector_graph/_validate.py` — 10 Pydantic `BaseModel` input schemas for high-risk engine methods: `NodeIdInput`, `EdgeInput`, `CypherInput`, `IVFBuildInput`, `VectorSearchInput`, `BM25BuildInput`, `BM25SearchInput`, `KHop2Input`, `TemporalEdgeInput`, `VecSearchInput`
+- **feat**: Input validation at call entry on `execute_cypher`, `create_node`, `create_edge`, `ivf_build`, `ivf_search`, `bm25_build`, `bm25_search`, `khop2_count_fast`, `create_edge_temporal`, `search_nodes_by_vector`
+- All 10 schemas exported from `iris_vector_graph.__init__`; 44/44 unit tests in `test_validation.py`
+- **chore**: `BulkIngestEdges` marked `[ Internal ]` in `EdgeScan.cls` — safe path is `engine.bulk_ingest_edges()`
+
+### v1.86.0 (2026-05-07)
+- **feat**: `IVGResult` Pydantic `BaseModel` replaces `Dict[str, Any]` as return type of `execute_cypher`
+  - Backward-compatible: `result["columns"]`, `result.get("error")`, `"error" in result` all work
+  - `bool(result)` = `True` on success, `False` on error
+  - `result.columns`, `result.rows`, `result.error`, `result.metadata`, `result.sql` via dot notation
+  - 23 unit tests in `test_ivgresult.py`; all 189+ existing call sites pass unchanged
+- **feat**: Fourth Pydantic increment — `IVGResult` joins `SQLQuery`, `QueryMetadata`, `IndexHandle`
+
+### v1.85.0 (2026-05-06)
+- **fix**: Unbounded variable-length path queries (no LIMIT) now always route to `_bfs_stream_pages` (cursor-based `ReadBFSPage`) instead of `ReadBFSResults` (single JSON string that hits `<MAXSTRING>` at 93K+ results). Bounded queries (LIMIT present) keep `ReadBFSResults` fast path.
+- **fix**: `test_sc003_results_match_bfs` — replaced raw `NKGAccel.BFSJson` call (bypassed engine, `^NKG` stale) with engine determinism check; `knows_data` fixture calls `engine.rebuild_nkg()` for sync guarantee
+- **test**: `tests/e2e/test_streaming_bfs.py` — 3 e2e + 2 routing unit tests for streaming BFS
+
+### v1.84.0 (2026-05-06)
+- **feat**: `engine.index(name)` → `IndexHandle` (Pydantic `BaseModel`) — unified entry point for all index types (`ivf`, `bm25`, `vec`, `plaid`) via `.search()`, `.insert()`, `.info()`, `.drop()`
+- **feat**: `IVGIndex` `@runtime_checkable` Protocol — structural subtyping, no inheritance required
+- **feat**: `_build_index_registry()` — auto-populates `{name: type}` from `^IVF`, `^VecIdx`, `^BM25Idx`, `^PLAID` on `IRISGraphEngine.__init__`; updated by `*_build` methods
+- **feat**: `PLAIDSearch.Build` public ClassMethod — calls `StoreCentroids`+`StoreDocTokensBatch`+`BuildInvertedIndex` internally; helpers marked `[ Private ]`
+- **feat**: `plaid_build()` now calls `PLAIDSearch.Build` (single round-trip); `plaid_info()` returns `{"type":"plaid","indexed":N,"nlist":L,"dim":D}`
+- **feat**: All `*_info()` methods return `"type"` key — `ivf_info()`, `bm25_info()`, `vec_info()`, `plaid_info()`
+- **feat**: `IVGIndex` and `IndexHandle` exported from `iris_vector_graph.__init__`
+- **test**: Full PLAID e2e coverage (5/5); `engine.index()` dispatch tests (5 pass, 1 skip)
+
 ### v1.83.0 (2026-05-06)
 - **feat**: `KHop2Count` + `KHop2NeighborIds(maxResults)` on `Graph.KG.Traversal` — pure ObjectScript 2-hop traversal with process-private dedup, no JSON serialization
 - **feat**: `execute_cypher` routes `[:PRED*2]` COUNT and LIMIT patterns to fast paths — IC3 LIMIT 1000 now **1.2ms p50** (was 14-22ms; 3.5x faster than GES 4.19ms)

{iris_vector_graph-1.87.0 → iris_vector_graph-1.89.0}/iris_src/src/Graph/KG/EdgeScan.cls

@@ -86,7 +86,7 @@ ClassMethod DeleteAdjacency(s As %String, p As %String, o As %String)
 /// edges_json: JSON array of [s, p, o] triples or {"s":..,"p":..,"o":..} objects.
 /// predicate: default predicate if using [s, o] pair format.
 /// Returns count of edges written.
-ClassMethod BulkIngestEdges(edgesJson As %String, predicate As %String = "R") As %Integer [ Language = python ]
+ClassMethod BulkIngestEdges(edgesJson As %String, predicate As %String = "R") As %Integer [ Internal, Language = python ]
 {
     import iris, json, warnings
     data = json.loads(edgesJson)

{iris_vector_graph-1.87.0 → iris_vector_graph-1.89.0}/iris_src/src/Graph/KG/NKGAccel.cls

@@ -559,7 +559,7 @@ ClassMethod BFSJson(seed As %String, predicatesJson As %String = "[]", maxHops A
     If '$Data(^||NKGAccel("compute_fn")) {
         Set dllid = $ZF(-4, 1, dllPath)
         If dllid = 0 {
-            Return ##class(Graph.KG.Traversal).BFSFastJson(seed, predicatesJson, maxHops, "")
+            Return ##class(Graph.KG.Traversal).BFSFastJsonSorted(seed, predicatesJson, maxHops, "", "out", maxResults)
         }
         Set ^||NKGAccel("dllid") = dllid
         Set ^||NKGAccel("compute_fn") = $ZF(-4, 3, dllid, "kg_bfs_compute")
@@ -569,11 +569,11 @@ ClassMethod BFSJson(seed As %String, predicatesJson As %String = "[]", maxHops A
     Set dllid = ^||NKGAccel("dllid")
     Set computeFn = ^||NKGAccel("compute_fn")
     If computeFn = 0 {
-        Return ##class(Graph.KG.Traversal).BFSFastJson(seed, predicatesJson, maxHops, "")
+        Return ##class(Graph.KG.Traversal).BFSFastJsonSorted(seed, predicatesJson, maxHops, "", "out", maxResults)
     }
     Do ..CacheNKGAdj()
     If '$Data(^ArnoKG("KG", "nkg_adj")) {
-        Return ##class(Graph.KG.Traversal).BFSFastJson(seed, predicatesJson, maxHops, "")
+        Return ##class(Graph.KG.Traversal).BFSFastJsonSorted(seed, predicatesJson, maxHops, "", "out", maxResults)
     }
     Kill ^ArnoKG("bfs_result")
     Set raw = $ZF(-5, dllid, computeFn, "^ArnoKG", "^ArnoKG", seed, predicatesJson, maxHops, maxResults)
@@ -583,15 +583,27 @@ ClassMethod BFSJson(seed As %String, predicatesJson As %String = "[]", maxHops A
     Set n = +$Piece(raw, ":", 3)
     Set readFn = ^||NKGAccel("read_fn")
     If readFn = 0 {
-        Return ##class(Graph.KG.Traversal).BFSFastJson(seed, predicatesJson, maxHops, "")
+        Return ##class(Graph.KG.Traversal).BFSFastJsonSorted(seed, predicatesJson, maxHops, "", "out", maxResults)
     }
-    Set result = ""
+    Set assembled = ""
     For i = 1:1:n {
-        Set chunk = $ZF(-5, dllid, readFn, "^ArnoKG", i)
-        Set result = result _ chunk
+        Set assembled = assembled _ $ZF(-5, dllid, readFn, "^ArnoKG", i)
     }
     Kill ^ArnoKG("bfs_result")
-    Return result
+    Set tag = $Job _ "_bfs"
+    Kill ^ArnoKG("bfs_r", tag)
+    Set arr = ##class(%DynamicArray).%FromJSON(assembled)
+    Set sz = arr.%Size()
+    For i = 0:1:(sz-1) {
+        Set item = arr.%Get(i)
+        Set step = +item.%Get("step")
+        Set o    = item.%Get("o")
+        Set s    = item.%Get("s")
+        Set p    = item.%Get("p")
+        Set w    = +item.%Get("w")
+        Set ^ArnoKG("bfs_r", tag, step, o) = $ListBuild(s, p, w)
+    }
+    Return "SORTED:" _ tag
 }
 
 ClassMethod InvalidateAdjCache()
@@ -1035,4 +1047,41 @@ ClassMethod CountDistinctKHop(srcId As %String, predsJson As %String = "", maxHo
     Return "{""estimate"":"_estimate_",""registers"":256,""std_error"":0.065}"
 }
 
+ClassMethod Build2HopExact() As %Boolean
+{
+    If '..IsLoaded() {
+        Do ..Load("/tmp/libarno_callout.so")
+        If '..IsLoaded() {
+            If ##class(Graph.KG.ArnoAccel).IsAvailable() {
+                Set ^||NKGAccel("dllid") = $Get(^||ArnoAccel("dllid"), 0)
+            }
+        }
+    }
+    If '..IsLoaded() Return 0
+    Set dllid = $Get(^||NKGAccel("dllid"), 0)
+    If dllid = 0 Return 0
+    Set fid = $ZF(-4, 3, dllid, "kg_build_2hop_exact_stream")
+    If fid = 0 Return 0
+    Kill ^ArnoKG("2hs")
+    Set raw = $ZF(-5, dllid, fid)
+    If $Extract(raw, 1, 8) '= "CHUNKED:" Return 0
+    Set n = +$Piece(raw, ":", 3)
+    Set data = ""
+    For i = 1:1:n {
+        Set data = data _ $Get(^ArnoKG("2hs", i), "")
+    }
+    Kill ^ArnoKG("2hs")
+    For pos = 1:1:$Length(data, $Char(10)) {
+        Set line = $Piece(data, $Char(10), pos)
+        If line = "" Continue
+        Set s    = $Piece(line, $Char(31), 1)
+        Set p    = $Piece(line, $Char(31), 2)
+        Set cnt  = +$Piece(line, $Char(31), 3)
+        If (s '= "") && (p '= "") && (cnt > 0) {
+            Set ^KG("deg2p_exact", s, p) = cnt
+        }
+    }
+    Return 1
+}
+
 }

{iris_vector_graph-1.87.0 → iris_vector_graph-1.89.0}/iris_src/src/Graph/KG/Traversal.cls

@@ -111,6 +111,7 @@ ClassMethod BuildNKG() As %Status
 	Set tmp = $Increment(^NKG("$meta", "version"))
 
 	Do ..Build2HopStats()
+	Do ..Build2HopExactStats()
 
 	Return $$$OK
 }
@@ -1166,4 +1167,68 @@ ClassMethod KHop2CountFast(srcId As %String, pred As %String = "") As %Integer
     Return ..KHop2Count(srcId, pred)
 }
 
+ClassMethod KHop2CountExact(srcId As %String, pred As %String = "") As %Integer
+{
+    If pred '= "" {
+        Set cnt = $Get(^KG("deg2p_exact", srcId, pred), -1)
+        If cnt >= 0 Return +cnt
+    }
+    Return ..KHop2Count(srcId, pred)
+}
+
+ClassMethod Build2HopExactStats() As %Integer
+{
+    Kill ^KG("deg2p_exact")
+    If ##class(Graph.KG.NKGAccel).Build2HopExact() {
+        Set n = ""
+        Set cnt = 0
+        For {
+            Set n = $Order(^KG("deg2p_exact", n))
+            Quit:n=""
+            Set cnt = cnt + 1
+        }
+        Return cnt
+    }
+    Set src = ""
+    Set cnt = 0
+    For {
+        Set src = $Order(^KG("out", 0, src))
+        Quit:src=""
+        Set pred = ""
+        For {
+            Set pred = $Order(^KG("out", 0, src, pred))
+            Quit:pred=""
+            Kill ^||h2s
+            Set ^||h2s(src) = ""
+            Set mid = ""
+            For {
+                Set mid = $Order(^KG("out", 0, src, pred, mid))
+                Quit:mid=""
+                Set ^||h2s(mid) = ""
+            }
+            Set exact = 0
+            Set mid = ""
+            For {
+                Set mid = $Order(^KG("out", 0, src, pred, mid))
+                Quit:mid=""
+                Set o2 = ""
+                For {
+                    Set o2 = $Order(^KG("out", 0, mid, pred, o2))
+                    Quit:o2=""
+                    If '$Data(^||h2s(o2)) {
+                        Set ^||h2s(o2) = ""
+                        Set exact = exact + 1
+                    }
+                }
+            }
+            Kill ^||h2s
+            If exact > 0 {
+                Set ^KG("deg2p_exact", src, pred) = exact
+                Set cnt = cnt + 1
+            }
+        }
+    }
+    Return cnt
+}
+
 }

{iris_vector_graph-1.87.0 → iris_vector_graph-1.89.0}/iris_vector_graph/engine.py

@@ -1536,12 +1536,26 @@ class IRISGraphEngine:
                     max_hops,
                     max_results,
                 )
-                bfs_results = _json.loads(str(bfs_json)) if bfs_json else []
+                bfs_str = str(bfs_json) if bfs_json else ""
+                if bfs_str.startswith("SORTED:") and bfs_str != "SORTED:0":
+                    tag = bfs_str.split(":")[1]
+                    if max_results == 0:
+                        bfs_results = list(_bfs_stream_pages(self.conn, tag))
+                    else:
+                        try:
+                            results_str = str(_call_classmethod(
+                                self.conn, "Graph.KG.Traversal", "ReadBFSResults", tag
+                            ))
+                            bfs_results = _json.loads(results_str)
+                        except Exception:
+                            bfs_results = list(_bfs_stream_pages(self.conn, tag))
+                elif bfs_str:
+                    bfs_results = _json.loads(bfs_str)
+                else:
+                    bfs_results = []
                 logger.debug("Arno BFSJson: %d results for %s", len(bfs_results), source_id)
-                if not bfs_results and not self._arno_capabilities.get("rust_callout"):
-                    bfs_results = None
             except Exception as e:
-                logger.warning(f"Arno BFSJson failed, falling back to BFSFastJson: {e}")
+                logger.warning(f"Arno BFSJson failed, falling back to BFSFastJsonSorted: {e}")
                 bfs_results = None
 
         if bfs_results is None:
@@ -1566,21 +1580,8 @@ class IRISGraphEngine:
                 else:
                     bfs_results = []
             except Exception as e:
-                logger.warning(f"BFSFastJsonSorted failed ({e}), falling back to chunked")
-                try:
-                    resp = str(_call_classmethod(
-                        self.conn, "Graph.KG.Traversal", "BFSFastJsonChunked",
-                        source_id, predicates_json, max_hops, "", direction, max_results,
-                    ))
-                    if resp.startswith("CHUNKED:") and resp != "CHUNKED:0":
-                        tag, n_chunks = resp.split(":")[1], int(resp.split(":")[2])
-                        parts = [str(_call_classmethod(self.conn, "Graph.KG.Traversal", "ReadBFSChunk", tag, str(i))) for i in range(1, n_chunks + 1)]
-                        bfs_results = _json.loads("[" + "".join(parts) + "]")
-                    else:
-                        bfs_results = []
-                except Exception as e2:
-                    logger.warning(f"BFSFastJsonChunked also failed: {e2}")
-                    return IVGResult(columns=[], rows=[], sql="", params=[], metadata=sql_query.query_metadata)
+                logger.warning(f"BFSFastJsonSorted failed: {e}")
+                return IVGResult(columns=[], rows=[], sql="", params=[], metadata=sql_query.query_metadata)
 
 
         if min_hops > 1:
@@ -1743,7 +1744,7 @@ class IRISGraphEngine:
                 return None
             try:
                 cnt = int(self._iris_obj().classMethodValue(
-                    "Graph.KG.Traversal", "KHop2Count", str(src_id), pred
+                    "Graph.KG.Traversal", "KHop2CountExact", str(src_id), pred
                 ))
                 return IVGResult(columns=[col], rows=[(cnt,)])
             except Exception:
@@ -3126,6 +3127,7 @@ class IRISGraphEngine:
             else:
                 iris_obj.classMethodVoid("Graph.KG.Traversal", "BuildNKG")
             iris_obj.classMethodValue("Graph.KG.Traversal", "Build2HopStats")
+            iris_obj.classMethodValue("Graph.KG.Traversal", "Build2HopExactStats")
             self._nkg_dirty = False
             return True
         except Exception as e:
@@ -3140,6 +3142,14 @@ class IRISGraphEngine:
             logger.warning("backfill_degp failed: %s", e)
             return 0
 
+    def backfill_deg2p_exact(self) -> int:
+        try:
+            result = self._iris_obj().classMethodValue("Graph.KG.Traversal", "Build2HopExactStats")
+            return int(result)
+        except Exception as e:
+            logger.warning("backfill_deg2p_exact failed: %s", e)
+            return 0
+
     def khop2_count_fast(self, node_id: str, predicate: str = "") -> int:
         KHop2Input(node_id=node_id)
         result = self._iris_obj().classMethodValue(
@@ -3147,6 +3157,13 @@ class IRISGraphEngine:
         )
         return int(result)
 
+    def khop2_count_exact(self, node_id: str, predicate: str = "") -> int:
+        KHop2Input(node_id=node_id)
+        result = self._iris_obj().classMethodValue(
+            "Graph.KG.Traversal", "KHop2CountExact", node_id, predicate
+        )
+        return int(result)
+
     def bulk_ingest_edges(
         self,
         edges: List[Dict[str, Any]],

{iris_vector_graph-1.87.0 → iris_vector_graph-1.89.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "iris-vector-graph"
-version = "1.87.0"
+version = "1.89.0"
 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.89.0/tests/e2e/test_arno_bfs_unified.py

@@ -0,0 +1,137 @@
+import os
+import time
+import statistics
+import pytest
+
+IRIS_HOST = os.environ.get("IRIS_HOST", "localhost")
+IRIS_ENT_PORT = int(os.environ.get("IRIS_ENT_PORT", "4972"))
+IRIS_COM_PORT = int(os.environ.get("IRIS_COM_PORT", "1972"))
+SKIP = os.environ.get("SKIP_IRIS_TESTS", "false").lower() == "true"
+PRED = "KNOWS"
+
+
+@pytest.fixture(scope="module")
+def community_engine():
+    try:
+        import iris
+        from iris_vector_graph.engine import IRISGraphEngine
+        conn = iris.connect(IRIS_HOST, IRIS_COM_PORT, "USER", "_SYSTEM", "SYS")
+        yield IRISGraphEngine(conn), iris.createIRIS(conn)
+        conn.close()
+    except Exception as e:
+        pytest.skip(f"Community IRIS unavailable: {e}")
+
+
+@pytest.fixture(scope="module")
+def enterprise_engine():
+    try:
+        import iris
+        from iris_vector_graph.engine import IRISGraphEngine
+        conn = iris.connect(IRIS_HOST, IRIS_ENT_PORT, "USER", "_SYSTEM", "SYS")
+        o = iris.createIRIS(conn)
+        o.classMethodValue("Graph.KG.ArnoAccel", "Load")
+        eng = IRISGraphEngine(conn)
+        eng._detect_arno()
+        if not eng._arno_capabilities.get("rust_callout") or \
+           "bfs" not in eng._arno_capabilities.get("rust_algorithms", []):
+            pytest.skip("Arno Rust BFS not available on enterprise container")
+        cur = conn.cursor()
+        cur.execute("SELECT TOP 1 s FROM Graph_KG.rdf_edges WHERE p = ?", [PRED])
+        row = cur.fetchone()
+        if not row:
+            pytest.skip("No KNOWS edges in enterprise — LDBC data not loaded")
+        yield eng, o, str(row[0])
+        conn.close()
+    except Exception as e:
+        pytest.skip(f"Enterprise IRIS unavailable or Rust BFS inactive: {e}")
+
+
+@pytest.fixture(scope="module")
+def bfs_test_graph(community_engine):
+    eng, o = community_engine
+    cur = eng.conn.cursor()
+    nodes = ["bfs_hub", "bfs_a", "bfs_b", "bfs_c"]
+    for n in nodes:
+        cur.execute("SELECT COUNT(*) FROM Graph_KG.nodes WHERE node_id=?", [n])
+        if cur.fetchone()[0] == 0:
+            cur.execute("INSERT INTO Graph_KG.nodes (node_id) VALUES (?)", [n])
+    eng.conn.commit()
+    from iris_vector_graph.schema import _call_classmethod
+    for s, t in [("bfs_hub", "bfs_a"), ("bfs_hub", "bfs_b"), ("bfs_a", "bfs_c")]:
+        cur.execute("SELECT COUNT(*) FROM Graph_KG.rdf_edges WHERE s=? AND p=? AND o_id=?", [s, "BFS_R", t])
+        if cur.fetchone()[0] == 0:
+            cur.execute("INSERT INTO Graph_KG.rdf_edges (s,p,o_id) VALUES (?,?,?)", [s, "BFS_R", t])
+    eng.conn.commit()
+    _call_classmethod(eng.conn, "Graph.KG.Traversal", "BuildKG")
+    yield
+    for n in nodes:
+        cur.execute("DELETE FROM Graph_KG.rdf_edges WHERE s=? OR o_id=?", [n, n])
+        cur.execute("DELETE FROM Graph_KG.nodes WHERE node_id=?", [n])
+    eng.conn.commit()
+
+
+@pytest.mark.skipif(SKIP, reason="SKIP_IRIS_TESTS=true")
+@pytest.mark.e2e
+def test_nkgaccel_bfs_json_output_format_is_sorted(enterprise_engine):
+    eng, o, seed = enterprise_engine
+    result = str(o.classMethodString("Graph.KG.NKGAccel", "BFSJson", seed, '["KNOWS"]', 2, 100))
+    assert result.startswith("SORTED:"), \
+        f"NKGAccel.BFSJson must return 'SORTED:tag' after spec 153, got: {result[:40]}"
+
+
+@pytest.mark.skipif(SKIP, reason="SKIP_IRIS_TESTS=true")
+@pytest.mark.e2e
+def test_rust_bfs_result_matches_objectscript(enterprise_engine):
+    eng, o, seed = enterprise_engine
+    from iris_vector_graph.schema import _call_classmethod_large
+    import json
+
+    rust_raw = str(o.classMethodString("Graph.KG.NKGAccel", "BFSJson", seed, '["KNOWS"]', 2, 0))
+    if rust_raw.startswith("SORTED:"):
+        tag = rust_raw.split(":")[1]
+        rust_results = json.loads(str(o.classMethodString("Graph.KG.Traversal", "ReadBFSResults", tag)))
+    else:
+        rust_results = json.loads(rust_raw)
+
+    obj_results = json.loads(_call_classmethod_large(o, "Graph.KG.Traversal", "BFSFastJson", seed, "KNOWS", 2))
+    assert len(rust_results) > 0
+    assert abs(len(rust_results) - len(obj_results)) <= 1, \
+        f"Rust ({len(rust_results)}) and ObjectScript ({len(obj_results)}) BFS counts differ by >1"
+
+
+@pytest.mark.skipif(SKIP, reason="SKIP_IRIS_TESTS=true")
+@pytest.mark.e2e
+def test_engine_execute_cypher_bfs_via_rust(enterprise_engine):
+    eng, o, seed = enterprise_engine
+    result = eng.execute_cypher(
+        "MATCH (s {node_id:$id})-[:KNOWS*1..2]->(n) RETURN n.node_id LIMIT 100",
+        {"id": seed}
+    )
+    assert result, "execute_cypher must succeed"
+    assert len(result.rows) > 0, "Must return results"
+    assert len(result.rows) <= 100
+
+
+@pytest.mark.skipif(SKIP, reason="SKIP_IRIS_TESTS=true")
+@pytest.mark.e2e
+def test_engine_chunked_branch_removed():
+    import iris_vector_graph.engine as eng_mod
+    import inspect
+    src = inspect.getsource(eng_mod.IRISGraphEngine._execute_var_length_cypher)
+    assert "BFSFastJsonChunked" not in src, \
+        "Legacy BFSFastJsonChunked branch must be removed from _execute_var_length_cypher"
+
+
+@pytest.mark.skipif(SKIP, reason="SKIP_IRIS_TESTS=true")
+@pytest.mark.e2e
+def test_objectscript_bfs_still_works_after_change(community_engine, bfs_test_graph):
+    eng, o = community_engine
+    result = eng.execute_cypher(
+        "MATCH (s {node_id:$id})-[:BFS_R*1..2]->(n) RETURN n.node_id",
+        {"id": "bfs_hub"}
+    )
+    assert result
+    ids = {r[0] for r in result.rows}
+    assert "bfs_a" in ids
+    assert "bfs_b" in ids
+    assert "bfs_c" in ids

iris_vector_graph-1.89.0/tests/e2e/test_ic3_exact_count.py

@@ -0,0 +1,108 @@
+import os
+import statistics
+import time
+
+import pytest
+
+ENTERPRISE_CONTAINER = "iris-enterprise-2026"
+SEEDS = ["p_28587302384882", "p_10995116278184", "p_10995116279040"]
+PRED = "KNOWS"
+
+
+@pytest.fixture(scope="module")
+def enterprise_engine():
+    try:
+        import iris
+        from iris_vector_graph.engine import IRISGraphEngine
+
+        conn = iris.connect("localhost", 4972, "USER", "_SYSTEM", "SYS")
+        o = iris.createIRIS(conn)
+        o.classMethodValue("Graph.KG.ArnoAccel", "Load")
+        cur = conn.cursor()
+        cur.execute("SELECT COUNT(*) FROM Graph_KG.nodes WHERE node_id LIKE 'p_%'")
+        if cur.fetchone()[0] < 1000:
+            pytest.skip("LDBC SF10 data not loaded on enterprise container")
+        eng = IRISGraphEngine(conn)
+        yield eng, o
+        conn.close()
+    except Exception as e:
+        pytest.skip(f"Enterprise IRIS unavailable: {e}")
+
+
+@pytest.fixture(scope="module")
+def with_exact_stats(enterprise_engine):
+    eng, o = enterprise_engine
+    o.classMethodValue("Graph.KG.Traversal", "Build2HopExactStats")
+    yield eng, o
+
+
+@pytest.mark.e2e
+def test_khop2_count_exact_matches_khop2_count(with_exact_stats):
+    eng, o = with_exact_stats
+    from iris_vector_graph.schema import _call_classmethod_large
+    for seed in SEEDS:
+        exact = int(o.classMethodValue("Graph.KG.Traversal", "KHop2CountExact", seed, PRED))
+        slow = int(_call_classmethod_large(o, "Graph.KG.Traversal", "KHop2Count", seed, PRED))
+        assert exact == slow, f"KHop2CountExact({seed}) = {exact} != KHop2Count = {slow}"
+
+
+@pytest.mark.e2e
+def test_khop2_count_exact_under_1ms(with_exact_stats):
+    eng, o = with_exact_stats
+    seed = SEEDS[0]
+    times = []
+    for _ in range(10):
+        o.classMethodValue("Graph.KG.Traversal", "KHop2CountExact", seed, PRED)
+    for _ in range(30):
+        t0 = time.perf_counter()
+        o.classMethodValue("Graph.KG.Traversal", "KHop2CountExact", seed, PRED)
+        times.append((time.perf_counter() - t0) * 1000)
+    p50 = statistics.median(times)
+    assert p50 < 1.0, f"KHop2CountExact p50={p50:.3f}ms exceeds 1ms target"
+
+
+@pytest.mark.e2e
+def test_execute_cypher_2hop_count_uses_exact(with_exact_stats):
+    eng, o = with_exact_stats
+    seed = SEEDS[0]
+    from iris_vector_graph.schema import _call_classmethod_large
+    expected = int(_call_classmethod_large(o, "Graph.KG.Traversal", "KHop2Count", seed, PRED))
+    times = []
+    for _ in range(5):
+        o.classMethodValue("Graph.KG.Traversal", "KHop2CountExact", seed, PRED)
+    for _ in range(20):
+        t0 = time.perf_counter()
+        result = eng.execute_cypher(
+            f"MATCH (s {{node_id:$id}})-[:{PRED}*2]->(n) RETURN count(n) AS cnt",
+            {"id": seed},
+        )
+        times.append((time.perf_counter() - t0) * 1000)
+    p50 = statistics.median(times)
+    cnt = result.rows[0][0]
+    assert int(cnt) == expected, f"execute_cypher returned {cnt}, expected {expected}"
+    assert p50 < 1.0, f"execute_cypher 2-hop COUNT p50={p50:.3f}ms exceeds 1ms"
+
+
+@pytest.mark.e2e
+def test_khop2_count_exact_fallback(enterprise_engine):
+    eng, o = enterprise_engine
+    import iris
+    conn = eng.conn
+    iris_obj = iris.createIRIS(conn)
+    iris_obj.classMethodVoid("Graph.KG.Traversal", "Build2HopExactStats")
+    iris_obj.classMethodValue("%SYSTEM.Process", "Xecute", 'Kill ^KG("deg2p_exact")')
+    seed = SEEDS[0]
+    from iris_vector_graph.schema import _call_classmethod_large
+    exact = int(iris_obj.classMethodValue("Graph.KG.Traversal", "KHop2CountExact", seed, PRED))
+    slow = int(_call_classmethod_large(iris_obj, "Graph.KG.Traversal", "KHop2Count", seed, PRED))
+    assert exact == slow, f"Fallback KHop2CountExact={exact} != KHop2Count={slow}"
+
+
+@pytest.mark.e2e
+def test_rebuild_nkg_under_30s(enterprise_engine):
+    eng, o = enterprise_engine
+    t0 = time.time()
+    ok = eng.rebuild_nkg()
+    elapsed = time.time() - t0
+    assert ok, "rebuild_nkg() returned False"
+    assert elapsed <= 30.0, f"rebuild_nkg took {elapsed:.1f}s, exceeds 30s target"