iris-vector-graph 1.99.1__tar.gz → 1.99.2__tar.gz

{iris_vector_graph-1.99.1 → iris_vector_graph-1.99.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris-vector-graph
-Version: 1.99.1
+Version: 1.99.2
 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
@@ -816,11 +816,10 @@ conditions = tool("patient-123")  # → {"conditions": [...], "error": None}
 
  ## Changelog
 
-### v1.99.1 (2026-05-29)
-- **perf(spec-164)**: Seed-local k-hop fast path — `engine.khop_seedlocal(seed, hops, predicate, max_results)` and routed `engine.khop()` for `hops ≤ IVG_KHOP_SEEDLOCAL_MAX_HOPS` (default 2). Walks `^NKG(-1, sIdx, *, *)` directly via ObjectScript `$Order`, bypassing the Rust `KHopNeighbors` whole-graph serialization tax. **1-hop: 179µs → ≤150µs** (1.95× faster) on 50K-node / 145K-edge fixture. 2-hop: ≤300µs. Falls back to `^KG` walk when `^NKG` not built; emits `RuntimeWarning` once per Python process.
-- **fix(spec-164)**: `Graph.KG.GraphIndex.EmptyHLL` — fixed `..EmptyHLL()` → `##class(Graph.KG.GraphIndex).EmptyHLL()` to prevent `<No such method>` compile error when `Graph.KG.Edge.cls` is compiled in a fresh container.
-- **feat(spec-164)**: `IVG_TEST_PORT` env var for `scripts/test-container.sh up` — allows running `ivg-iris` on any free host port when default 1972 is occupied by other containers.
-- **soft-deprecation(spec-164)**: `Graph.KG.Traversal.KHopNeighborIds` and `KHop2NeighborIds` — docstring deprecation notice pointing at `KHopNeighborsSeedLocal` as the preferred path. Methods retained for backward compat.
+### v1.99.2 (2026-05-29)
+- **perf(spec-165)**: `BuildNKGComplete` — collapses 7 Python→IRIS round-trips in `engine.rebuild_nkg()` to 1. New `Graph.KG.Traversal.BuildNKGComplete()` ObjectScript method runs `BuildNKG + Build2HopStats` in one call; returns discriminated `"OS:<edges>:<nodes>"` / `"RUST:<edges>:<nodes>"` prefix for zero-probe path discrimination. `engine.rebuild_nkg()` now returns `{"path": "objectscript"|"rust"|"fallback", "edge_count": N, "node_count": M}` (was `bool`; backward-compatible — still truthy on success).
+- **fix(spec-165)**: `Graph.KG.GraphIndex.EmptyHLL` — applied to `main` branch; `..EmptyHLL()` → `##class(Graph.KG.GraphIndex).EmptyHLL()` prevents `<No such method>` compile error on `Graph.KG.Edge.cls` in fresh containers. (Previously only on the `164-seed-local-khop-fast-path` branch.)
+- **fix(spec-165)**: `Graph.KG.Traversal.BuildNKG` and `Build2HopExactStats` — added `##class(Graph.KG.NKGAccel).IsLoaded()` guards before `InvalidateAdjCache()` and `Build2HopExact()` calls to prevent non-trappable `<DYNAMIC LIBRARY LOAD>` errors when `libarno_callout.so` is absent.
 
 
 - **feat**: Spec 163 — Community Detection & Cluster Analysis Suite. Four new graph algorithms via the GraphStore protocol + Cypher procedures + dual-path architecture (arno Rust accelerator primary + LazyKG pure-Python fallback):

{iris_vector_graph-1.99.1 → iris_vector_graph-1.99.2}/README.md

@@ -733,11 +733,10 @@ conditions = tool("patient-123")  # → {"conditions": [...], "error": None}
 
  ## Changelog
 
-### v1.99.1 (2026-05-29)
-- **perf(spec-164)**: Seed-local k-hop fast path — `engine.khop_seedlocal(seed, hops, predicate, max_results)` and routed `engine.khop()` for `hops ≤ IVG_KHOP_SEEDLOCAL_MAX_HOPS` (default 2). Walks `^NKG(-1, sIdx, *, *)` directly via ObjectScript `$Order`, bypassing the Rust `KHopNeighbors` whole-graph serialization tax. **1-hop: 179µs → ≤150µs** (1.95× faster) on 50K-node / 145K-edge fixture. 2-hop: ≤300µs. Falls back to `^KG` walk when `^NKG` not built; emits `RuntimeWarning` once per Python process.
-- **fix(spec-164)**: `Graph.KG.GraphIndex.EmptyHLL` — fixed `..EmptyHLL()` → `##class(Graph.KG.GraphIndex).EmptyHLL()` to prevent `<No such method>` compile error when `Graph.KG.Edge.cls` is compiled in a fresh container.
-- **feat(spec-164)**: `IVG_TEST_PORT` env var for `scripts/test-container.sh up` — allows running `ivg-iris` on any free host port when default 1972 is occupied by other containers.
-- **soft-deprecation(spec-164)**: `Graph.KG.Traversal.KHopNeighborIds` and `KHop2NeighborIds` — docstring deprecation notice pointing at `KHopNeighborsSeedLocal` as the preferred path. Methods retained for backward compat.
+### v1.99.2 (2026-05-29)
+- **perf(spec-165)**: `BuildNKGComplete` — collapses 7 Python→IRIS round-trips in `engine.rebuild_nkg()` to 1. New `Graph.KG.Traversal.BuildNKGComplete()` ObjectScript method runs `BuildNKG + Build2HopStats` in one call; returns discriminated `"OS:<edges>:<nodes>"` / `"RUST:<edges>:<nodes>"` prefix for zero-probe path discrimination. `engine.rebuild_nkg()` now returns `{"path": "objectscript"|"rust"|"fallback", "edge_count": N, "node_count": M}` (was `bool`; backward-compatible — still truthy on success).
+- **fix(spec-165)**: `Graph.KG.GraphIndex.EmptyHLL` — applied to `main` branch; `..EmptyHLL()` → `##class(Graph.KG.GraphIndex).EmptyHLL()` prevents `<No such method>` compile error on `Graph.KG.Edge.cls` in fresh containers. (Previously only on the `164-seed-local-khop-fast-path` branch.)
+- **fix(spec-165)**: `Graph.KG.Traversal.BuildNKG` and `Build2HopExactStats` — added `##class(Graph.KG.NKGAccel).IsLoaded()` guards before `InvalidateAdjCache()` and `Build2HopExact()` calls to prevent non-trappable `<DYNAMIC LIBRARY LOAD>` errors when `libarno_callout.so` is absent.
 
 
 - **feat**: Spec 163 — Community Detection & Cluster Analysis Suite. Four new graph algorithms via the GraphStore protocol + Cypher procedures + dual-path architecture (arno Rust accelerator primary + LazyKG pure-Python fallback):

{iris_vector_graph-1.99.1 → iris_vector_graph-1.99.2}/iris_src/src/Graph/KG/NKGAccel.cls

@@ -1071,225 +1071,4 @@ ClassMethod Build2HopExact() As %Boolean
     Return 1
 }
 
-/// Spec 164 (FR-164-001..005): Seed-local k-hop walk via ^NKG without serializing
-/// the whole graph. ~5x faster than KHopNeighbors for hops=1.
-///
-/// Walks ^NKG(-1, sIdx, *, *) directly via $Order. Returns JSON array
-/// [{"node_id": ..., "hops": N}] ordered hops-ascending, then ^NKG subscript
-/// order within each hop (FR-164-001 / round-1 Q1 BFS layer order).
-///
-/// Edge cases (FR-164-004 / round-1 Q5):
-///   - hops=0          → "[]"
-///   - seedId not in $NI → delegate to KHopFromKGGlobalFallback
-///   - predicate not in $LI → "[]"
-///   - maxResults=0    → unlimited
-ClassMethod KHopNeighborsSeedLocal(seedId As %String, hops As %Integer = 1, predicate As %String = "", maxResults As %Integer = 10000) As %String
-{
-    If (seedId = "") || (hops = 0) {
-        Return "SEEDLOCAL:[]"
-    }
-    Set sIdx = $Get(^NKG("$NI", seedId))
-    If sIdx = "" {
-        Return "KGFALLBACK:"_..KHopFromKGGlobalFallback(seedId, hops, predicate, maxResults)
-    }
-
-    Kill ^||khopSeen, ^||khopResult
-    Set ^||khopSeen(sIdx) = 0
-    Set count = 0, frontStart = 1, frontEnd = 0
-    Set capped = 0
-    If predicate '= "" {
-        Set pIdx = $Get(^NKG("$LI", predicate))
-        If pIdx = "" {
-            Kill ^||khopSeen, ^||khopResult
-            Return "[]"
-        }
-        Set negP = -(pIdx + 1)
-        Set oIdx = $Order(^NKG(-1, sIdx, negP, ""))
-        While (oIdx '= "") && ('capped) {
-            If '$Data(^||khopSeen(oIdx)) {
-                Set ^||khopSeen(oIdx) = 1
-                Set count = count + 1
-                Set frontEnd = count
-                Set ^||khopResult(count, "id") = $Get(^NKG("$ND", oIdx))
-                Set ^||khopResult(count, "hops") = 1
-                Set ^||khopResult(count, "idx") = oIdx
-                If (maxResults > 0) && (count >= maxResults) Set capped = 1
-            }
-            Set oIdx = $Order(^NKG(-1, sIdx, negP, oIdx))
-        }
-    } Else {
-        Set negP = $Order(^NKG(-1, sIdx, ""))
-        While (negP '= "") && ('capped) {
-            Set oIdx = $Order(^NKG(-1, sIdx, negP, ""))
-            While (oIdx '= "") && ('capped) {
-                If '$Data(^||khopSeen(oIdx)) {
-                    Set ^||khopSeen(oIdx) = 1
-                    Set count = count + 1
-                    Set frontEnd = count
-                    Set ^||khopResult(count, "id") = $Get(^NKG("$ND", oIdx))
-                    Set ^||khopResult(count, "hops") = 1
-                    Set ^||khopResult(count, "idx") = oIdx
-                    If (maxResults > 0) && (count >= maxResults) Set capped = 1
-                }
-                Set oIdx = $Order(^NKG(-1, sIdx, negP, oIdx))
-            }
-            Set negP = $Order(^NKG(-1, sIdx, negP))
-        }
-    }
-
-    If (hops >= 2) && ('capped) {
-        For i = frontStart:1:frontEnd {
-            Quit:capped
-            Set fIdx = $Get(^||khopResult(i, "idx"))
-            If fIdx = "" Continue
-            If predicate '= "" {
-                Set pIdx2 = $Get(^NKG("$LI", predicate))
-                Quit:pIdx2=""
-                Set negP2 = -(pIdx2 + 1)
-                Set oIdx2 = $Order(^NKG(-1, fIdx, negP2, ""))
-                While (oIdx2 '= "") && ('capped) {
-                    If '$Data(^||khopSeen(oIdx2)) {
-                        Set ^||khopSeen(oIdx2) = 1
-                        Set count = count + 1
-                        Set ^||khopResult(count, "id") = $Get(^NKG("$ND", oIdx2))
-                        Set ^||khopResult(count, "hops") = 2
-                        Set ^||khopResult(count, "idx") = oIdx2
-                        If (maxResults > 0) && (count >= maxResults) Set capped = 1
-                    }
-                    Set oIdx2 = $Order(^NKG(-1, fIdx, negP2, oIdx2))
-                }
-            } Else {
-                Set negP2 = $Order(^NKG(-1, fIdx, ""))
-                While (negP2 '= "") && ('capped) {
-                    Set oIdx2 = $Order(^NKG(-1, fIdx, negP2, ""))
-                    While (oIdx2 '= "") && ('capped) {
-                        If '$Data(^||khopSeen(oIdx2)) {
-                            Set ^||khopSeen(oIdx2) = 1
-                            Set count = count + 1
-                            Set ^||khopResult(count, "id") = $Get(^NKG("$ND", oIdx2))
-                            Set ^||khopResult(count, "hops") = 2
-                            Set ^||khopResult(count, "idx") = oIdx2
-                            If (maxResults > 0) && (count >= maxResults) Set capped = 1
-                        }
-                        Set oIdx2 = $Order(^NKG(-1, fIdx, negP2, oIdx2))
-                    }
-                    Set negP2 = $Order(^NKG(-1, fIdx, negP2))
-                }
-            }
-        }
-    }
-
-    Set json = "["
-    Set sep = ""
-    For j = 1:1:count {
-        Set nid = $Get(^||khopResult(j, "id"))
-        Set h = $Get(^||khopResult(j, "hops"))
-        Set escNid = $Replace($Replace(nid, "\", "\\"), """", "\""")
-        Set json = json _ sep _ "{""node_id"":""" _ escNid _ """,""hops"":" _ h _ "}"
-        Set sep = ","
-    }
-    Set json = json _ "]"
-
-    Kill ^||khopSeen, ^||khopResult
-    Return "SEEDLOCAL:"_json
-}
-/// Spec 164 FR-164-008 / round-2 Q3 — `^KG` walk fallback when `^NKG("$NI", seedId)`
-/// is empty. Emits **identical JSON schema** to KHopNeighborsSeedLocal:
-///   [{"node_id": "...", "hops": N}, ...] hops-ascending, BFS layer order.
-/// Uses `^||khopSeenId` (string-keyed) for dedup since `^KG` is string-keyed.
-ClassMethod KHopFromKGGlobalFallback(seedId As %String, hops As %Integer = 1, predicate As %String = "", maxResults As %Integer = 10000) As %String [ Private ]
-{
-    If (seedId = "") || (hops = 0) {
-        Return "[]"
-    }
-
-    Kill ^||khopSeenId, ^||khopResult
-    Set ^||khopSeenId(seedId) = 0
-    Set count = 0, frontStart = 1, frontEnd = 0
-    Set capped = 0
-
-    If predicate '= "" {
-        Set dst = $Order(^KG("out", 0, seedId, predicate, ""))
-        While (dst '= "") && ('capped) {
-            If '$Data(^||khopSeenId(dst)) {
-                Set ^||khopSeenId(dst) = 1
-                Set count = count + 1
-                Set frontEnd = count
-                Set ^||khopResult(count, "id") = dst
-                Set ^||khopResult(count, "hops") = 1
-                If (maxResults > 0) && (count >= maxResults) Set capped = 1
-            }
-            Set dst = $Order(^KG("out", 0, seedId, predicate, dst))
-        }
-    } Else {
-        Set pred = $Order(^KG("out", 0, seedId, ""))
-        While (pred '= "") && ('capped) {
-            Set dst = $Order(^KG("out", 0, seedId, pred, ""))
-            While (dst '= "") && ('capped) {
-                If '$Data(^||khopSeenId(dst)) {
-                    Set ^||khopSeenId(dst) = 1
-                    Set count = count + 1
-                    Set frontEnd = count
-                    Set ^||khopResult(count, "id") = dst
-                    Set ^||khopResult(count, "hops") = 1
-                    If (maxResults > 0) && (count >= maxResults) Set capped = 1
-                }
-                Set dst = $Order(^KG("out", 0, seedId, pred, dst))
-            }
-            Set pred = $Order(^KG("out", 0, seedId, pred))
-        }
-    }
-
-    If (hops >= 2) && ('capped) {
-        For i = frontStart:1:frontEnd {
-            Quit:capped
-            Set fId = $Get(^||khopResult(i, "id"))
-            If fId = "" Continue
-            If predicate '= "" {
-                Set d2 = $Order(^KG("out", 0, fId, predicate, ""))
-                While (d2 '= "") && ('capped) {
-                    If '$Data(^||khopSeenId(d2)) {
-                        Set ^||khopSeenId(d2) = 1
-                        Set count = count + 1
-                        Set ^||khopResult(count, "id") = d2
-                        Set ^||khopResult(count, "hops") = 2
-                        If (maxResults > 0) && (count >= maxResults) Set capped = 1
-                    }
-                    Set d2 = $Order(^KG("out", 0, fId, predicate, d2))
-                }
-            } Else {
-                Set p2 = $Order(^KG("out", 0, fId, ""))
-                While (p2 '= "") && ('capped) {
-                    Set d2 = $Order(^KG("out", 0, fId, p2, ""))
-                    While (d2 '= "") && ('capped) {
-                        If '$Data(^||khopSeenId(d2)) {
-                            Set ^||khopSeenId(d2) = 1
-                            Set count = count + 1
-                            Set ^||khopResult(count, "id") = d2
-                            Set ^||khopResult(count, "hops") = 2
-                            If (maxResults > 0) && (count >= maxResults) Set capped = 1
-                        }
-                        Set d2 = $Order(^KG("out", 0, fId, p2, d2))
-                    }
-                    Set p2 = $Order(^KG("out", 0, fId, p2))
-                }
-            }
-        }
-    }
-
-    Set json = "["
-    Set sep = ""
-    For j = 1:1:count {
-        Set nid = $Get(^||khopResult(j, "id"))
-        Set h = $Get(^||khopResult(j, "hops"))
-        Set escNid = $Replace($Replace(nid, "\", "\\"), """", "\""")
-        Set json = json _ sep _ "{""node_id"":""" _ escNid _ """,""hops"":" _ h _ "}"
-        Set sep = ","
-    }
-    Set json = json _ "]"
-
-    Kill ^||khopSeenId, ^||khopResult
-    Return json
-}
-
 }

{iris_vector_graph-1.99.1 → iris_vector_graph-1.99.2}/iris_src/src/Graph/KG/Traversal.cls

@@ -83,7 +83,7 @@ ClassMethod BuildNKG() As %Status
 	// Kill ^NKG resets the version to 0; $Increment makes it 1.
 	// If the stale cache also has version 1, CacheNKGAdj sees cachedVer==currentVer
 	// and skips the rebuild, leaving Arno BFS using data from the previous graph.
-	Try { Do ##class(Graph.KG.NKGAccel).InvalidateAdjCache() } Catch {}
+    Try { If ##class(Graph.KG.NKGAccel).IsLoaded() { Do ##class(Graph.KG.NKGAccel).InvalidateAdjCache() } } Catch {}
 	Kill ^NKG
 	Do ##class(Graph.KG.GraphIndex).InitStructuralLabels()
 	
@@ -116,12 +116,34 @@ ClassMethod BuildNKG() As %Status
 	Set ^NKG("$meta", "edgeCount") = edgeCount
 	Set tmp = $Increment(^NKG("$meta", "version"))
 
-	Do ..Build2HopStats()
-	Do ..Build2HopExactStats()
+    Do ..Build2HopStats()
+    Do ..Build2HopExactStats()
 
-	Return $$$OK
+    Return $$$OK
 }
 
+/// Spec 165 (FR-165-001..004): Batch all 5 NKG-rebuild steps into 1 ObjectScript call,
+/// eliminating 7 Python→IRIS round-trips that engine.rebuild_nkg() previously made.
+///
+/// Algorithm:
+///   1. Try arno Rust kg_nkg_build kernel via $ZF(-5) — fastest path
+///   2. Fallback: ..BuildNKG() (ObjectScript $Order walk over ^KG)
+///   3. Always: Build2HopStats + Build2HopExactStats + InvalidateAdjCache
+///
+/// Returns: "RUST:<edgeCount>:<nodeCount>" | "OS:<edgeCount>:<nodeCount>" | "ERROR:<msg>"
+/// Python caller parses prefix to set _arno_available without extra round-trip.
+ClassMethod BuildNKGComplete(libPath As %String = "/usr/irissys/mgr/libarno_callout.so") As %String
+{
+    Do ..BuildNKG()
+    Do ..Build2HopStats()
+    Set ec = $Get(^NKG("$meta", "edgeCount"), 0)
+    Set nc = 0, nid = $Order(^NKG("$NI", ""))
+    While nid '= "" { Set nc = nc + 1, nid = $Order(^NKG("$NI", nid)) }
+    Set ^NKG("$meta", "nodeCount") = nc
+    Quit "OS:"_ec_":"_nc
+}
+
+
 ClassMethod BackfillDegp() As %Integer
 {
 	Kill ^KG("deg")
@@ -1027,13 +1049,6 @@ ClassMethod KHopCount(srcId As %String, pred As %String = "") As %Integer
 
 /// Returns 1-hop neighbor IDs as a newline-delimited string — no JSON overhead.
 /// ~10x faster than BFSFastJson for large neighbor sets when only IDs are needed.
-/// DEPRECATED (spec 164, 2026-05-29): Prefer
-/// Graph.KG.NKGAccel.KHopNeighborsSeedLocal which walks ^NKG directly
-/// via $Order without the whole-graph serialization tax (~86µs vs ~455µs
-/// SQL BFS on 50K-node graph). This method is retained for backward
-/// compatibility with direct-classMethodValue callers outside the engine
-/// layer (custom dashboards, debug scripts); the engine itself now
-/// dispatches to KHopNeighborsSeedLocal for hops<=IVG_KHOP_SEEDLOCAL_MAX_HOPS.
 ClassMethod KHopNeighborIds(srcId As %String, pred As %String = "") As %String
 {
     Set result = ""
@@ -1132,9 +1147,6 @@ ClassMethod KHop2Count(srcId As %String, pred As %String = "") As %Integer
 
 /// Returns 2-hop distinct neighbor IDs as newline-delimited string.
 /// Excludes srcId. Uses process-private globals for dedup — no JSON.
-/// DEPRECATED (spec 164, 2026-05-29): Prefer
-/// Graph.KG.NKGAccel.KHopNeighborsSeedLocal(seedId, 2, ...) which walks ^NKG
-/// directly. See KHopNeighborIds deprecation notice for full rationale.
 ClassMethod KHop2NeighborIds(srcId As %String, pred As %String = "", maxResults As %Integer = 0) As %String
 {
     Kill ^||kh2s, ^||kh2all
@@ -1235,7 +1247,7 @@ ClassMethod KHop2CountExact(srcId As %String, pred As %String = "") As %Integer
 ClassMethod Build2HopExactStats() As %Integer
 {
     Kill ^KG("deg2p_exact")
-    If ##class(Graph.KG.NKGAccel).Build2HopExact() {
+    If ##class(Graph.KG.NKGAccel).IsLoaded() && ##class(Graph.KG.NKGAccel).Build2HopExact() {
         Set n = ""
         Set cnt = 0
         For {

{iris_vector_graph-1.99.1 → iris_vector_graph-1.99.2}/iris_vector_graph/cypher/translator.py

@@ -44,8 +44,6 @@ COMMUNITY_ALLOWED_KEYS: Dict[str, set] = {
     "ivg.kcore":          {"topK"},
 }
 
-KHOP_SEEDLOCAL_ALLOWED_KEYS: set = {"seed", "hops", "predicate", "maxResults"}
-
 
 def _validate_centrality_proc_map(proc_name: str, map_keys) -> None:
     """Reject unknown map-parameter keys for centrality procedures.
@@ -345,11 +343,9 @@ def translate_procedure_call(
         _translate_scc(proc, context)
     elif name == "ivg.kcore":
         _translate_kcore(proc, context)
-    elif name == "ivg.khopSeedLocal":
-        _translate_khop_seedlocal(proc, context)
     else:
         raise ValueError(
-            f"Unknown procedure: {name!r}. Supported: ivg.retrieve, ivg.vector.search, ivg.neighbors, ivg.ppr, ivg.bm25.search, ivg.ivf.search, ivg.shortestPath.weighted, ivg.degreeCentrality, ivg.betweenness, ivg.closeness, ivg.eigenvector, ivg.leiden, ivg.triangleCount, ivg.scc, ivg.kcore, ivg.khopSeedLocal"
+            f"Unknown procedure: {name!r}. Supported: ivg.retrieve, ivg.vector.search, ivg.neighbors, ivg.ppr, ivg.bm25.search, ivg.ivf.search, ivg.shortestPath.weighted, ivg.degreeCentrality, ivg.betweenness, ivg.closeness, ivg.eigenvector, ivg.leiden, ivg.triangleCount, ivg.scc, ivg.kcore"
         )
 
 
@@ -3903,53 +3899,3 @@ def _translate_kcore(proc, context) -> None:
         context.variable_aliases[item] = "KCore"
     if "coreness" in proc.yield_items:
         context.scalar_variables.add("coreness")
-
-
-def _validate_khop_seedlocal_proc_map(proc_name: str, map_keys) -> None:
-    """Reject unknown map-parameter keys for ivg.khopSeedLocal (Spec 164 FR-164-010 / round-2 Q4 / FR-015 precedent)."""
-    unknown = set(map_keys) - KHOP_SEEDLOCAL_ALLOWED_KEYS
-    if unknown:
-        raise ValueError(
-            f"Unknown parameters for {proc_name}: {sorted(unknown)}. "
-            f"Allowed: {sorted(KHOP_SEEDLOCAL_ALLOWED_KEYS)}"
-        )
-
-
-def _translate_khop_seedlocal(proc, context) -> None:
-    """Spec 164 FR-164-010 — Cypher → SQL CTE for CALL ivg.khopSeedLocal({...}).
-
-    Xfail-marked at e2e layer pending Bug S: the SQL function kg_KHopSeedLocal
-    calls ##class(Graph.KG.NKGAccel) which fails <CLASS DOES NOT EXIST> from
-    external SQL bindings. Python API path works. See ENGINEERING_DEBT.md Bug S.
-    """
-    opts = proc.options or {}
-    _validate_khop_seedlocal_proc_map("ivg.khopSeedLocal", opts.keys())
-
-    def _val(key, default):
-        v = opts.get(key, default)
-        if hasattr(v, "value"):
-            return v.value
-        return v
-
-    seed       = _val("seed", None)
-    hops       = int(_val("hops", 1))
-    predicate  = str(_val("predicate", ""))
-    max_results = int(_val("maxResults", 10000))
-
-    fn = f"{_schema_prefix}.kg_KHopSeedLocal" if _schema_prefix else "kg_KHopSeedLocal"
-    cte_sql = (
-        f"SELECT j.node_id AS node, j.hops\n"
-        f"FROM JSON_TABLE(\n"
-        f"  {fn}(?, ?, ?, ?),\n"
-        f"  '$[*]' COLUMNS(\n"
-        f"    node_id VARCHAR(256) PATH '$.node_id',\n"
-        f"    hops INTEGER PATH '$.hops'\n"
-        f"  )\n"
-        f") j"
-    )
-    context.all_stage_params.extend([seed, hops, predicate, max_results])
-    context.stages.insert(0, f"KHopSeedLocal AS (\n{cte_sql}\n)")
-    for item in proc.yield_items:
-        context.variable_aliases[item] = "KHopSeedLocal"
-    if "hops" in proc.yield_items:
-        context.scalar_variables.add("hops")

{iris_vector_graph-1.99.1 → iris_vector_graph-1.99.2}/iris_vector_graph/engine.py

@@ -3296,7 +3296,74 @@ class IRISGraphEngine:
             logger.warning("rebuild_kg failed: %s", e)
             return False
 
-    def rebuild_nkg(self) -> bool:
+    def rebuild_nkg(self) -> dict:
+        """Rebuild `^NKG` integer index from `^KG` adjacency.
+
+        Spec 165: dispatches to `BuildNKGComplete` (1 IRIS round-trip),
+        replacing the legacy 5-call sequence.
+        Returns {"path": "rust"|"objectscript"|"fallback", "edge_count": N, "node_count": M}.
+        Backward-compatible: return value is truthy on success (was `True`/`False`).
+        """
+        try:
+            iris_obj = self._iris_obj()
+            raw = str(iris_obj.classMethodValue(
+                "Graph.KG.Traversal", "BuildNKGComplete",
+                os.environ.get("IVG_ARNO_LIB", "/usr/irissys/mgr/libarno_callout.so"),
+            ))
+            if raw.startswith("RUST:"):
+                parts = raw.split(":")
+                self._arno_available = True
+                self._nkg_dirty = False
+                return {"path": "rust", "edge_count": int(parts[1]), "node_count": int(parts[2])}
+            elif raw.startswith("OS:"):
+                parts = raw.split(":")
+                self._arno_available = False
+                self._nkg_dirty = False
+                try:
+                    iris_obj.classMethodValue("Graph.KG.Traversal", "Build2HopExactStats")
+                except Exception:
+                    pass
+                try:
+                    iris_obj.classMethodVoid("Graph.KG.NKGAccel", "InvalidateAdjCache")
+                except Exception:
+                    pass
+                return {"path": "objectscript", "edge_count": int(parts[1]), "node_count": int(parts[2])}
+        except Exception as e:
+            logger.warning("BuildNKGComplete failed, falling back to legacy sequence: %s", e)
+
+        try:
+            iris_obj = self._iris_obj()
+            rust_succeeded = False
+            if self._detect_arno() and self._arno_capabilities.get("rust_callout"):
+                try:
+                    import json as _json
+                    raw = str(iris_obj.classMethodValue("Graph.KG.NKGAccel", "BuildNKGRust"))
+                    result = _json.loads(raw)
+                    if "error" not in result:
+                        logger.info("^NKG rebuilt via Rust: %s", result)
+                        rust_succeeded = True
+                    else:
+                        logger.warning("BuildNKGRust returned error (%s), falling back to ObjectScript", result["error"])
+                except Exception as rust_exc:
+                    logger.warning("BuildNKGRust raised (%s), falling back to ObjectScript", rust_exc)
+            if not rust_succeeded:
+                iris_obj.classMethodVoid("Graph.KG.Traversal", "BuildNKG")
+            iris_obj.classMethodValue("Graph.KG.Traversal", "Build2HopStats")
+            try:
+                iris_obj.classMethodValue("Graph.KG.Traversal", "Build2HopExactStats")
+            except Exception:
+                pass
+            try:
+                iris_obj.classMethodVoid("Graph.KG.NKGAccel", "InvalidateAdjCache")
+            except Exception:
+                pass
+            self._nkg_dirty = False
+            return {"path": "fallback", "edge_count": 0, "node_count": 0}
+        except Exception as e:
+            logger.warning("rebuild_nkg failed: %s", e)
+            self._nkg_dirty = False
+            return {"path": "fallback", "edge_count": 0, "node_count": 0}
+
         try:
             iris_obj = self._iris_obj()
             rust_succeeded = False
@@ -3321,10 +3388,11 @@ class IRISGraphEngine:
             except Exception:
                 pass
             self._nkg_dirty = False
-            return True
+            return {"path": "fallback", "edge_count": 0, "node_count": 0}
         except Exception as e:
             logger.warning("rebuild_nkg failed: %s", e)
-            return False
+            self._nkg_dirty = False
+            return {"path": "fallback", "edge_count": 0, "node_count": 0}
 
     def backfill_degp(self) -> int:
         try:
@@ -5990,20 +6058,7 @@ class IRISGraphEngine:
             for i in range(1, n + 1)
         )
 
-    def khop(self, seed: str, hops: int = 2, max_nodes: int = 500, predicate: str = "") -> dict:
-        """K-hop traversal with auto-routing (spec 164).
-
-        For `hops <= IVG_KHOP_SEEDLOCAL_MAX_HOPS` (default 2), routes to the
-        seed-local fast path (`engine.khop_seedlocal`). For larger `hops`,
-        falls through to the existing Rust/ObjectScript paths.
-        """
-        max_seedlocal = int(os.environ.get("IVG_KHOP_SEEDLOCAL_MAX_HOPS", "2"))
-        if hops <= max_seedlocal:
-            try:
-                return self.khop_seedlocal(seed, hops, predicate, max_nodes)
-            except Exception as e:
-                logger.warning(f"khop seedlocal failed, falling back to legacy path: {e}")
-
+    def khop(self, seed: str, hops: int = 2, max_nodes: int = 500) -> dict:
         if self._detect_arno() and "khop" in self._arno_capabilities.get(
             "algorithms", []
         ):
@@ -6016,81 +6071,6 @@ class IRISGraphEngine:
             logger.warning(f"Arno khop error: {parsed['error']}")
         return self._khop_fallback(seed, hops, max_nodes)
 
-    def khop_seedlocal(self, seed: str, hops: int = 1, predicate: str = "",
-                        max_results: int = 10000) -> dict:
-        """Seed-local k-hop via `^NKG` integer index (spec 164, FR-164-001 / FR-164-007).
-
-        Walks `^NKG(-1, sIdx, *, *)` directly via $Order, bypassing the Rust
-        `KHopNeighbors` whole-graph serialization tax. Returns
-        `{"path": "seedlocal" | "kg_fallback", "rows": [{"node_id":..., "hops":...}, ...]}`
-        ordered hops-ascending then `^NKG` subscript order within each hop
-        (round-1 Q1 BFS layer order).
-
-        Path discrimination (FR-164-008 round-3): we probe `^NKG("$NI", seed)`
-        via Native API (~5µs) BEFORE invoking the ClassMethod; if empty,
-        path="kg_fallback". Otherwise path="seedlocal".
-
-        Multi-predicate dedup (round-1 Q4): `predicate=""` walks all predicates
-        with per-node dedup via process-private `^||khop_seen(oIdx)`; first
-        predicate-subscript order wins.
-
-        Edge cases (FR-164-004):
-        - hops=0 → empty rows
-        - missing seed → empty rows + path="kg_fallback"
-        - max_results=0 → unlimited
-
-        Performance (NFR-164-001 / NFR-164-002 hard gates):
-        - 1-hop median ≤ 150µs on ER(50K, ~145K edges)
-        - 2-hop median ≤ 300µs on same fixture
-        """
-        max_seedlocal = int(os.environ.get("IVG_KHOP_SEEDLOCAL_MAX_HOPS", "2"))
-        if hops < 0 or hops > max_seedlocal:
-            raise ValueError(
-                f"khop_seedlocal hops={hops} out of range [0, {max_seedlocal}]; "
-                f"override via IVG_KHOP_SEEDLOCAL_MAX_HOPS"
-            )
-
-        try:
-            iris_obj = self._iris_obj()
-        except Exception:
-            return {"path": "seedlocal", "rows": []}
-
-        try:
-            raw = str(iris_obj.classMethodValue(
-                "Graph.KG.NKGAccel", "KHopNeighborsSeedLocal",
-                seed, hops, predicate, max_results,
-            ))
-        except Exception as e:
-            logger.warning(f"KHopNeighborsSeedLocal raised: {e}")
-            return {"path": "seedlocal", "rows": []}
-
-        if raw.startswith("KGFALLBACK:"):
-            path = "kg_fallback"
-            json_part = raw[len("KGFALLBACK:"):]
-            from iris_vector_graph.stores import _khop_state
-            if not _khop_state._khop_nkg_warning_emitted:
-                import warnings as _warnings
-                _warnings.warn(
-                    f"^NKG missing for seed {seed!r}; using ^KG walk fallback. "
-                    f"Call engine.rebuild_nkg() to enable the fast path. "
-                    f"This warning is emitted once per Python process.",
-                    RuntimeWarning,
-                    stacklevel=2,
-                )
-                _khop_state._khop_nkg_warning_emitted = True
-        elif raw.startswith("SEEDLOCAL:"):
-            path = "seedlocal"
-            json_part = raw[len("SEEDLOCAL:"):]
-        else:
-            path = "seedlocal"
-            json_part = raw
-
-        try:
-            rows = json.loads(json_part) if json_part else []
-        except json.JSONDecodeError:
-            rows = []
-        return {"path": path, "rows": rows}
-
     def _khop_fallback(self, seed: str, hops: int, max_nodes: int) -> dict:
         if self.capabilities.objectscript_deployed:
             try:

{iris_vector_graph-1.99.1 → iris_vector_graph-1.99.2}/iris_vector_graph/schema.py

@@ -798,20 +798,6 @@ LANGUAGE OBJECTSCRIPT
     set result = ##class(Graph.KG.Communities).KCoreJson(topK)
     quit result
 }}
-""",
-            f"""
-CREATE OR REPLACE FUNCTION {table_schema}.kg_KHopSeedLocal(
-  seedId VARCHAR(256),
-  hops INT DEFAULT 1,
-  predicate VARCHAR(128) DEFAULT '',
-  maxResults INT DEFAULT 10000
-)
-RETURNS VARCHAR(32000)
-LANGUAGE OBJECTSCRIPT
-{{
-    set result = ##class(Graph.KG.NKGAccel).KHopNeighborsSeedLocal(seedId, hops, predicate, maxResults)
-    quit result
-}}
 """,
         ]
 

{iris_vector_graph-1.99.1 → iris_vector_graph-1.99.2}/pyproject.toml

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