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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris-vector-graph
-Version: 1.87.0
+Version: 1.88.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

{iris_vector_graph-1.87.0 → iris_vector_graph-1.88.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.88.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.ArnoAccel).IsAvailable() {
+        Set dllid = $Get(^||ArnoAccel("dllid"), 0)
+        If dllid > 0 {
+            Set fid = $ZF(-4, 3, dllid, "kg_build_2hop_exact")
+            If fid > 0 {
+                Set result = $ZF(-5, dllid, fid)
+                Return +$Piece($Piece(result, "entries", 2), "}", 1)
+            }
+        }
+    }
+    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.88.0}/iris_vector_graph/engine.py

@@ -1743,7 +1743,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 +3126,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 +3141,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 +3156,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.88.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "iris-vector-graph"
-version = "1.87.0"
+version = "1.88.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.88.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"