iris-vector-graph 1.63.1__tar.gz → 1.63.3__tar.gz

{iris_vector_graph-1.63.1 → iris_vector_graph-1.63.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris-vector-graph
-Version: 1.63.1
+Version: 1.63.3
 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
@@ -407,6 +407,43 @@ Returns `[{"s": str, "p": str, "o_id": str, "score": float}, ...]` sorted descen
 
 ---
 
+## Engine Status
+
+Call `engine.status()` at any time to get a structured snapshot of all components. This is the canonical answer to "why is query X returning nothing?"
+
+```python
+s = engine.status()
+print(s.report())
+
+# Readiness gates — use before running query types
+s.ready_for_bfs           # var-length / undirected / shortestPath — needs ^KG + edges
+s.ready_for_vector_search # needs node embeddings
+s.ready_for_edge_search   # needs edge embeddings
+s.ready_for_full_text     # needs BM25 index
+
+# Example: rebuild ^KG if stale
+if not s.ready_for_bfs and s.tables.edges > 0:
+    engine.build_graph_globals()  # calls BuildKG()
+```
+
+Sample output:
+```
+IVG Engine Status
+══════════════════════════════════════════
+SQL Tables  (probe: 23ms)
+  nodes              10,000
+  edges              50,000
+  ...
+Adjacency Globals
+  ✓ ^KG   (50,000 source nodes indexed)
+  ✗ ^NKG  (Arno integer index)
+...
+```
+
+`status()` is explicit-call only — never run automatically at init or before queries. Cost ~50ms.
+
+---
+
 ## PLAID Multi-Vector Search
 
 ```python
@@ -655,6 +692,21 @@ anchors = engine.get_kg_anchors(icd_codes=["J18.0", "E11.9"])
 
 ## Changelog
 
+### v1.63.3 (2026-04-26)
+- feat: `engine.status() -> EngineStatus` — structured runtime snapshot: SQL row counts, `^KG`/`^NKG` population, ObjectScript classes, Arno capabilities, HNSW/IVF/BM25/PLAID index inventory. Readiness properties: `ready_for_bfs`, `ready_for_vector_search`, `ready_for_edge_search`, `ready_for_full_text`. Detects `^KG`/`rdf_edges` predicate mismatch (stale ^KG from different data snapshot). (spec 080)
+- fix: `BuildKG()` `Traversal.cls` SQL cursors now use fully-qualified `Graph_KG.rdf_edges`, `Graph_KG.rdf_labels`, `Graph_KG.rdf_props` — fixes predicate mismatch when IRIS namespace default SQL schema is not `Graph_KG` (e.g. MINDWALK namespace with `SQLUser` default)
+- fix: `kg_IVFMeta`, `kg_BM25Meta`, `kg_PlaidMeta` added to security allowlist
+- `EngineStatus` exported from top-level `iris_vector_graph`
+
+
+### v1.63.2 (2026-04-25)
+- fix: `MATCH (a)-[r*1..N]-(b)` undirected BFS now traverses `^KG("in",...)` for inbound edges (was outbound-only)
+- fix: `MATCH (a)<-[r*1..N]-(b)` inbound-only BFS now works  
+- fix: `initialize_schema()` ObjectScript LoadDir tries Docker `/tmp/src/` before Mac path — fixes silent compile failure in test containers
+- 4 E2E tests: directed-out, undirected, multihop undirected, directed-in all passing
+- Arno BFSJson falls back gracefully to BFSFastJson for graphs >3.5MB adjacency string (299K+ long-ID edges); per-seed export is spec 079 future work
+
+
 ### v1.63.0 (2026-04-25)
 - feat: Arno/Rust fast path for BFS (`_execute_var_length_cypher`) — when `libarno_callout.so` is loaded with `Graph.KG.NKGAccel.BFSJson`, var-length Cypher queries use Rust BFS over `^NKG` integer adjacency instead of ObjectScript `BFSFastJson`. Projected 128ms → <30ms p50 for 6K+ result BFS at 10K/50K scale. Falls back transparently to `BFSFastJson` when Arno not loaded. (spec 079, arno spec 035)
 

{iris_vector_graph-1.63.1 → iris_vector_graph-1.63.3}/README.md

@@ -335,6 +335,43 @@ Returns `[{"s": str, "p": str, "o_id": str, "score": float}, ...]` sorted descen
 
 ---
 
+## Engine Status
+
+Call `engine.status()` at any time to get a structured snapshot of all components. This is the canonical answer to "why is query X returning nothing?"
+
+```python
+s = engine.status()
+print(s.report())
+
+# Readiness gates — use before running query types
+s.ready_for_bfs           # var-length / undirected / shortestPath — needs ^KG + edges
+s.ready_for_vector_search # needs node embeddings
+s.ready_for_edge_search   # needs edge embeddings
+s.ready_for_full_text     # needs BM25 index
+
+# Example: rebuild ^KG if stale
+if not s.ready_for_bfs and s.tables.edges > 0:
+    engine.build_graph_globals()  # calls BuildKG()
+```
+
+Sample output:
+```
+IVG Engine Status
+══════════════════════════════════════════
+SQL Tables  (probe: 23ms)
+  nodes              10,000
+  edges              50,000
+  ...
+Adjacency Globals
+  ✓ ^KG   (50,000 source nodes indexed)
+  ✗ ^NKG  (Arno integer index)
+...
+```
+
+`status()` is explicit-call only — never run automatically at init or before queries. Cost ~50ms.
+
+---
+
 ## PLAID Multi-Vector Search
 
 ```python
@@ -583,6 +620,21 @@ anchors = engine.get_kg_anchors(icd_codes=["J18.0", "E11.9"])
 
 ## Changelog
 
+### v1.63.3 (2026-04-26)
+- feat: `engine.status() -> EngineStatus` — structured runtime snapshot: SQL row counts, `^KG`/`^NKG` population, ObjectScript classes, Arno capabilities, HNSW/IVF/BM25/PLAID index inventory. Readiness properties: `ready_for_bfs`, `ready_for_vector_search`, `ready_for_edge_search`, `ready_for_full_text`. Detects `^KG`/`rdf_edges` predicate mismatch (stale ^KG from different data snapshot). (spec 080)
+- fix: `BuildKG()` `Traversal.cls` SQL cursors now use fully-qualified `Graph_KG.rdf_edges`, `Graph_KG.rdf_labels`, `Graph_KG.rdf_props` — fixes predicate mismatch when IRIS namespace default SQL schema is not `Graph_KG` (e.g. MINDWALK namespace with `SQLUser` default)
+- fix: `kg_IVFMeta`, `kg_BM25Meta`, `kg_PlaidMeta` added to security allowlist
+- `EngineStatus` exported from top-level `iris_vector_graph`
+
+
+### v1.63.2 (2026-04-25)
+- fix: `MATCH (a)-[r*1..N]-(b)` undirected BFS now traverses `^KG("in",...)` for inbound edges (was outbound-only)
+- fix: `MATCH (a)<-[r*1..N]-(b)` inbound-only BFS now works  
+- fix: `initialize_schema()` ObjectScript LoadDir tries Docker `/tmp/src/` before Mac path — fixes silent compile failure in test containers
+- 4 E2E tests: directed-out, undirected, multihop undirected, directed-in all passing
+- Arno BFSJson falls back gracefully to BFSFastJson for graphs >3.5MB adjacency string (299K+ long-ID edges); per-seed export is spec 079 future work
+
+
 ### v1.63.0 (2026-04-25)
 - feat: Arno/Rust fast path for BFS (`_execute_var_length_cypher`) — when `libarno_callout.so` is loaded with `Graph.KG.NKGAccel.BFSJson`, var-length Cypher queries use Rust BFS over `^NKG` integer adjacency instead of ObjectScript `BFSFastJson`. Projected 128ms → <30ms p50 for 6K+ result BFS at 10K/50K scale. Falls back transparently to `BFSFastJson` when Arno not loaded. (spec 079, arno spec 035)
 

{iris_vector_graph-1.63.1 → iris_vector_graph-1.63.3}/iris_src/src/Graph/KG/Traversal.cls

@@ -13,7 +13,7 @@ ClassMethod BuildKG() As %Status
 		TStart
 		
 		// 1. Labels
-		&sql(DECLARE c1 CURSOR FOR SELECT s, label FROM rdf_labels)
+		&sql(DECLARE c1 CURSOR FOR SELECT s, label FROM Graph_KG.rdf_labels)
 		&sql(OPEN c1)
 		For {
 			&sql(FETCH c1 INTO :s, :label)
@@ -23,7 +23,7 @@ ClassMethod BuildKG() As %Status
 		&sql(CLOSE c1)
 		
 		// 2. Props
-		&sql(DECLARE c2 CURSOR FOR SELECT s, key, val FROM rdf_props)
+		&sql(DECLARE c2 CURSOR FOR SELECT s, key, val FROM Graph_KG.rdf_props)
 		&sql(OPEN c2)
 		For {
 			&sql(FETCH c2 INTO :s, :key, :val)
@@ -34,7 +34,7 @@ ClassMethod BuildKG() As %Status
 		
 		// 3. Edges & Stats (including weights)
 		Set count = 0
-		&sql(DECLARE c3 CURSOR FOR SELECT s, p, o_id, qualifiers FROM rdf_edges)
+		&sql(DECLARE c3 CURSOR FOR SELECT s, p, o_id, qualifiers FROM Graph_KG.rdf_edges)
 		&sql(OPEN c3)
 		For {
 			&sql(FETCH c3 INTO :s, :p, :o, :qual)
@@ -151,8 +151,9 @@ ClassMethod TraverseAllPredicates(s As %String, hop As %Integer, maxHops As %Int
 }
 
 /// Optimized BFS using Process-Private Globals and $ListBuild to bypass object bottleneck
+/// @param direction "out" (default), "in", or "both" for undirected BFS
 /// @returns Number of edges found. Results are in ^||BFS.Results(i) = $lb(s, p, o, w, step)
-ClassMethod BFSFast(srcId As %String, preds As %DynamicArray = "", maxHops As %Integer = 2, dstLabel As %String = "") As %Integer
+ClassMethod BFSFast(srcId As %String, preds As %DynamicArray = "", maxHops As %Integer = 2, dstLabel As %String = "", direction As %String = "out") As %Integer
 {
     Kill ^||BFS.Results
     If (srcId = "") || (maxHops <= 0) Return 0
@@ -171,10 +172,20 @@ ClassMethod BFSFast(srcId As %String, preds As %DynamicArray = "", maxHops As %I
             Set s = $Order(frontier(s))
             If s = "" Quit
             
-            If fixedP '= "" {
-                Do ..TraverseWithPredicateFast(s, fixedP, hop, maxHops, nextP, dstLabel, .count, .nextFrontier, .seen)
-            } Else {
-                Do ..TraverseAllPredicatesFast(s, hop, maxHops, nextP, dstLabel, .count, .nextFrontier, .seen)
+            If direction = "out" || (direction = "both") {
+                If fixedP '= "" {
+                    Do ..TraverseWithPredicateFast(s, fixedP, hop, maxHops, nextP, dstLabel, .count, .nextFrontier, .seen)
+                } Else {
+                    Do ..TraverseAllPredicatesFast(s, hop, maxHops, nextP, dstLabel, .count, .nextFrontier, .seen)
+                }
+            }
+            
+            If direction = "in" || (direction = "both") {
+                If fixedP '= "" {
+                    Do ..TraverseWithPredicateFastInbound(s, fixedP, hop, .count, .nextFrontier, .seen)
+                } Else {
+                    Do ..TraverseAllPredicatesFastInbound(s, hop, .count, .nextFrontier, .seen)
+                }
             }
         }
         
@@ -216,6 +227,30 @@ ClassMethod TraverseAllPredicatesFast(s As %String, hop As %Integer, maxHops As
     }
 }
 
+/// Inbound BFS: traverse ^KG("in", 0, s, p, o) where s is the target, o is the source.
+/// Result stored as (o, p, s) to preserve original edge direction.
+ClassMethod TraverseWithPredicateFastInbound(s As %String, p As %String, hop As %Integer, ByRef count As %Integer, ByRef nextFrontier, ByRef seen) [ Internal, Private ]
+{
+    Set o = ""
+    For {
+        Set o = $Order(^KG("in", 0, s, p, o))
+        If o = "" Quit
+        Set count = count + 1
+        Set ^||BFS.Results(count) = $ListBuild(s, p, o, $Get(^KG("out", 0, o, p, s), 1.0), hop)
+        If '$Data(seen(o)) Set nextFrontier(o) = ""
+    }
+}
+
+ClassMethod TraverseAllPredicatesFastInbound(s As %String, hop As %Integer, ByRef count As %Integer, ByRef nextFrontier, ByRef seen) [ Internal, Private ]
+{
+    Set p = ""
+    For {
+        Set p = $Order(^KG("in", 0, s, p))
+        If p = "" Quit
+        Do ..TraverseWithPredicateFastInbound(s, p, hop, .count, .nextFrontier, .seen)
+    }
+}
+
 /// Main BFS implementation
 ClassMethod BFS(srcId As %String, preds As %DynamicArray = "", maxHops As %Integer = 2, dstLabel As %String = "") As %DynamicArray
 {
@@ -287,7 +322,7 @@ ClassMethod BFSJSON(srcId As %String, preds As %DynamicArray, maxHops As %Intege
 /// @param maxHops  Maximum hops (default 2)
 /// @param dstLabel Filter destination nodes by label (empty = no filter)
 /// @returns JSON array: [{"s":..,"p":..,"o":..,"w":..,"step":..}, ...] in traversal order
-ClassMethod BFSFastJson(srcId As %String, predsJson As %String = "", maxHops As %Integer = 2, dstLabel As %String = "") As %String
+ClassMethod BFSFastJson(srcId As %String, predsJson As %String = "", maxHops As %Integer = 2, dstLabel As %String = "", direction As %String = "out") As %String
 {
     // Parse predicates JSON into a %DynamicArray (null/"" means all predicates)
     Set preds = ""
@@ -300,7 +335,7 @@ ClassMethod BFSFastJson(srcId As %String, predsJson As %String = "", maxHops As
     }
 
     // Run BFSFast -- writes to ^||BFS.Results(i) = $ListBuild(s,p,o,w,step)
-    Set count = ..BFSFast(srcId, preds, maxHops, dstLabel)
+    Set count = ..BFSFast(srcId, preds, maxHops, dstLabel, direction)
 
     If count = 0 Return "[]"
 
@@ -640,4 +675,22 @@ ClassMethod DijkstraProc(srcId As %String, dstId As %String, weightProp As %Stri
 	Quit ..DijkstraJson(srcId, dstId, weightProp, maxCost, maxHops, direction)
 }
 
+ClassMethod KGEdgeCount(maxCount As %Integer = 10000) As %Integer
+{
+    Set count = 0
+    Set s = ""
+    For {
+        Set s = $Order(^KG("out", 0, s))
+        Quit:s=""
+        Set count = count + 1
+        If count >= maxCount Quit
+    }
+    Return count
+}
+
+ClassMethod NKGPopulated() As %Integer
+{
+    Return ($Data(^NKG) > 0)
+}
+
 }

{iris_vector_graph-1.63.1 → iris_vector_graph-1.63.3}/iris_vector_graph/__init__.py

@@ -3,6 +3,7 @@ IRIS Graph Core - Domain-Agnostic Graph Engine
 """
 
 from .engine import IRISGraphEngine
+from .status import EngineStatus
 from .schema import GraphSchema
 from .capabilities import IRISCapabilities
 from .vector_utils import VectorOptimizer

{iris_vector_graph-1.63.1 → iris_vector_graph-1.63.3}/iris_vector_graph/cypher/translator.py

@@ -1759,7 +1759,7 @@ def translate_relationship_pattern(
         src_id_param = _resolve_id_param(source_node)
         dst_id_param = _resolve_id_param(target_node)
 
-        direction_str = "both" if rel.direction == ast.Direction.BOTH else "out"
+        direction_str = "both" if rel.direction == ast.Direction.BOTH else ("in" if rel.direction == ast.Direction.INCOMING else "out")
 
         context.var_length_paths.append(
             {

{iris_vector_graph-1.63.1 → iris_vector_graph-1.63.3}/iris_vector_graph/engine.py

@@ -20,6 +20,10 @@ from iris_vector_graph.cypher.translator import (
 )
 from iris_vector_graph.schema import GraphSchema, _call_classmethod
 from iris_vector_graph.capabilities import IRISCapabilities
+from iris_vector_graph.status import (
+    EngineStatus, TableCounts, AdjacencyStatus,
+    ObjectScriptStatus, ArnoStatus, IndexInventory,
+)
 from iris_vector_graph.security import validate_table_name
 
 logger = logging.getLogger(__name__)
@@ -1206,6 +1210,7 @@ class IRISGraphEngine:
                     predicates_json,
                     max_hops,
                     "",
+                    vl.get("direction", "out"),
                 )
                 bfs_results = _json.loads(str(bfs_json)) if bfs_json else []
             except Exception as e:
@@ -2053,6 +2058,145 @@ class IRISGraphEngine:
 
         return {"id": row_map[id_key], "labels": labels, "properties": props}
 
+    def status(self) -> "EngineStatus":
+        import time as _time
+        t0 = _time.perf_counter()
+        errors: list = []
+        cursor = self.conn.cursor()
+
+        def _count(sql):
+            try:
+                cursor.execute(sql)
+                row = cursor.fetchone()
+                return int(row[0]) if row else 0
+            except Exception as e:
+                errors.append(f"count probe failed: {e}")
+                return 0
+
+        tables = TableCounts(
+            nodes=_count(f"SELECT COUNT(*) FROM {_table('nodes')}"),
+            edges=_count(f"SELECT COUNT(*) FROM {_table('rdf_edges')}"),
+            labels=_count(f"SELECT COUNT(*) FROM {_table('rdf_labels')}"),
+            props=_count(f"SELECT COUNT(*) FROM {_table('rdf_props')}"),
+            node_embeddings=_count(f"SELECT COUNT(*) FROM {_table('kg_NodeEmbeddings')}"),
+            edge_embeddings=_count(f"SELECT COUNT(*) FROM {_table('kg_EdgeEmbeddings')}"),
+        )
+
+        kg_count = 0
+        kg_capped = False
+        kg_populated = False
+        nkg_populated = False
+        try:
+            native = self._iris_obj()
+            kg_count = int(native.classMethodValue("Graph.KG.Traversal", "KGEdgeCount", 10000))
+            kg_populated = kg_count > 0
+            kg_capped = kg_count >= 10000
+            nkg_populated = bool(int(native.classMethodValue("Graph.KG.Traversal", "NKGPopulated")))
+        except Exception as e:
+            try:
+                iris_native = self._iris_obj()
+                kg_populated = bool(iris_native.isDefined(["KG", "out"]))
+            except Exception:
+                errors.append(f"^KG probe failed: {e}")
+
+        adjacency = AdjacencyStatus(
+            kg_populated=kg_populated,
+            kg_edge_count=kg_count,
+            kg_edge_count_capped=kg_capped,
+            nkg_populated=nkg_populated,
+        )
+
+        if kg_populated and tables.edges > 0:
+            try:
+                native = self._iris_obj()
+                kg_pred = str(native.get(["KG", "out", 0, ""])) or ""
+                if not kg_pred:
+                    s_val = ""
+                    kg_pred_node = native.orderAll(["KG", "out", 0, s_val])
+                    if kg_pred_node:
+                        kg_pred = str(native.orderAll(
+                            ["KG", "out", 0, str(kg_pred_node), ""]
+                        ) or "")
+            except Exception:
+                kg_pred = ""
+
+            if kg_pred:
+                try:
+                    cursor.execute(
+                        f"SELECT COUNT(*) FROM {_table('rdf_edges')} WHERE p = ?",
+                        [kg_pred],
+                    )
+                    row = cursor.fetchone()
+                    if row and int(row[0]) == 0:
+                        errors.append(
+                            f"^KG predicate mismatch: ^KG has '{kg_pred[:60]}' "
+                            f"but rdf_edges has no matching p — "
+                            f"^KG is stale from a different data snapshot. "
+                            f"Run BuildKG() after reloading graph data."
+                        )
+                except Exception:
+                    pass
+
+        os_classes = []
+        os_deployed = self.capabilities.objectscript_deployed
+        _known_classes = [
+            "Graph.KG.Traversal", "Graph.KG.PageRank", "Graph.KG.IVFIndex",
+            "Graph.KG.BM25Index", "Graph.KG.ArnoAccel", "Graph.KG.Snapshot",
+            "Graph.KG.Dijkstra",
+        ]
+        if os_deployed:
+            for cls in _known_classes:
+                try:
+                    cursor.execute(
+                        "SELECT COUNT(*) FROM %Dictionary.ClassDefinition WHERE Name = ?",
+                        [cls],
+                    )
+                    row = cursor.fetchone()
+                    if row and int(row[0]) > 0:
+                        os_classes.append(cls)
+                except Exception:
+                    pass
+
+        objectscript = ObjectScriptStatus(deployed=os_deployed, classes=os_classes)
+
+        self._detect_arno()
+        arno = ArnoStatus(
+            loaded=bool(self._arno_available),
+            capabilities=dict(self._arno_capabilities),
+        )
+
+        hnsw_built = _count(f"SELECT COUNT(*) FROM {_table('kg_NodeEmbeddings_optimized')}") > 0
+
+        def _list_index(sql):
+            try:
+                cursor.execute(sql)
+                return [row[0] for row in cursor.fetchall() if row[0]]
+            except Exception:
+                return []
+
+        ivf = _list_index(f"SELECT DISTINCT name FROM {_table('kg_IVFMeta')}")
+        bm25 = _list_index(f"SELECT DISTINCT name FROM {_table('kg_BM25Meta')}")
+        plaid = _list_index(f"SELECT DISTINCT idx_name FROM {_table('kg_PlaidMeta')}")
+
+        indexes = IndexInventory(
+            hnsw_built=hnsw_built,
+            ivf_indexes=ivf,
+            bm25_indexes=bm25,
+            plaid_indexes=plaid,
+        )
+
+        probe_ms = (_time.perf_counter() - t0) * 1000
+        return EngineStatus(
+            tables=tables,
+            adjacency=adjacency,
+            objectscript=objectscript,
+            arno=arno,
+            indexes=indexes,
+            embedding_dimension=self.embedding_dimension,
+            probe_ms=probe_ms,
+            errors=errors,
+        )
+
     def count_nodes(self, label: Optional[str] = None) -> int:
         """
         Count nodes in the graph using optimized SQL.
@@ -4887,7 +5031,7 @@ class IRISGraphEngine:
             try:
                 iris_obj = self._iris_obj()
                 result = iris_obj.classMethodValue(
-                    "Graph.KG.Traversal", "BFSFastJson", seed, "", hops, ""
+                    "Graph.KG.Traversal", "BFSFastJson", seed, "", hops, "", "out"
                 )
                 if result:
                     edges = json.loads(str(result))

{iris_vector_graph-1.63.1 → iris_vector_graph-1.63.3}/iris_vector_graph/schema.py

@@ -757,7 +757,7 @@ LANGUAGE OBJECTSCRIPT
 
         src_dir = str(iris_src_path / "src") if iris_src_path else ""
         deployed = False
-        for candidate_dir in [src_dir, "/tmp/src/", "/irisdev/app/iris_src/src/"]:
+        for candidate_dir in ["/tmp/src/", "/irisdev/app/iris_src/src/", src_dir]:
             if not candidate_dir:
                 continue
             try:

{iris_vector_graph-1.63.1 → iris_vector_graph-1.63.3}/iris_vector_graph/security.py

@@ -12,7 +12,10 @@ VALID_GRAPH_TABLES = {
     "kg_EdgeEmbeddings",
     "docs",
     "fhir_bridges",
-    "rdf_reifications"
+    "rdf_reifications",
+    "kg_IVFMeta",
+    "kg_BM25Meta",
+    "kg_PlaidMeta",
 }
 
 def sanitize_identifier(identifier: str) -> str:

iris_vector_graph-1.63.3/iris_vector_graph/status.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List
+
+
+@dataclass
+class TableCounts:
+    nodes: int = 0
+    edges: int = 0
+    labels: int = 0
+    props: int = 0
+    node_embeddings: int = 0
+    edge_embeddings: int = 0
+
+
+@dataclass
+class AdjacencyStatus:
+    kg_populated: bool = False
+    kg_edge_count: int = 0
+    kg_edge_count_capped: bool = False
+    nkg_populated: bool = False
+
+
+@dataclass
+class ObjectScriptStatus:
+    deployed: bool = False
+    classes: List[str] = field(default_factory=list)
+
+
+@dataclass
+class ArnoStatus:
+    loaded: bool = False
+    capabilities: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class IndexInventory:
+    hnsw_built: bool = False
+    ivf_indexes: List[str] = field(default_factory=list)
+    bm25_indexes: List[str] = field(default_factory=list)
+    plaid_indexes: List[str] = field(default_factory=list)
+
+
+@dataclass
+class EngineStatus:
+    tables: TableCounts = field(default_factory=TableCounts)
+    adjacency: AdjacencyStatus = field(default_factory=AdjacencyStatus)
+    objectscript: ObjectScriptStatus = field(default_factory=ObjectScriptStatus)
+    arno: ArnoStatus = field(default_factory=ArnoStatus)
+    indexes: IndexInventory = field(default_factory=IndexInventory)
+    embedding_dimension: int = 768
+    probe_ms: float = 0.0
+    errors: List[str] = field(default_factory=list)
+
+    @property
+    def ready_for_bfs(self) -> bool:
+        return self.adjacency.kg_populated and self.tables.edges > 0
+
+    @property
+    def ready_for_vector_search(self) -> bool:
+        return self.tables.node_embeddings > 0
+
+    @property
+    def ready_for_edge_search(self) -> bool:
+        return self.tables.edge_embeddings > 0
+
+    @property
+    def ready_for_full_text(self) -> bool:
+        return bool(self.indexes.bm25_indexes)
+
+    def report(self) -> str:
+        def tick(ok: bool) -> str:
+            return "✓" if ok else "✗"
+
+        kg_count = (
+            f"≥{self.adjacency.kg_edge_count:,}"
+            if self.adjacency.kg_edge_count_capped
+            else f"{self.adjacency.kg_edge_count:,}"
+        )
+
+        lines = [
+            "IVG Engine Status",
+            "═" * 50,
+            f"\nSQL Tables  (probe: {self.probe_ms:.0f}ms)",
+            f"  nodes              {self.tables.nodes:>10,}",
+            f"  edges              {self.tables.edges:>10,}",
+            f"  labels             {self.tables.labels:>10,}",
+            f"  properties         {self.tables.props:>10,}",
+            f"  node embeddings    {self.tables.node_embeddings:>10,}",
+            f"  edge embeddings    {self.tables.edge_embeddings:>10,}",
+            f"  embedding dim      {self.embedding_dimension:>10}",
+            f"\nAdjacency Globals",
+            f"  {tick(self.adjacency.kg_populated)} ^KG   ({kg_count} source nodes indexed)",
+            f"  {tick(self.adjacency.nkg_populated)} ^NKG  (Arno integer index)",
+        ]
+
+        if not self.adjacency.kg_populated and self.tables.edges > 0:
+            lines.append(
+                "  ⚠ ^KG empty but edges exist — "
+                "call BuildKG() or rebuild on container startup"
+            )
+
+        lines += [
+            f"\nObjectScript Classes",
+            f"  {tick(self.objectscript.deployed)} Deployed",
+        ]
+        for cls in sorted(self.objectscript.classes):
+            lines.append(f"    · {cls}")
+
+        lines.append(f"\nArno Accelerator")
+        if self.arno.loaded:
+            algos = [k for k, v in self.arno.capabilities.items()
+                     if v and k not in ("nkg_data",)]
+            lines.append(f"  ✓ Loaded — algorithms: {', '.join(algos) or 'none'}")
+        else:
+            lines.append("  ✗ Not loaded  (BFS/PPR using ObjectScript fallback)")
+
+        lines += [
+            f"\nIndexes",
+            f"  {tick(self.indexes.hnsw_built)} HNSW node vector index",
+            f"  {'✓' if self.indexes.ivf_indexes else '·'} IVF:   "
+            f"{', '.join(self.indexes.ivf_indexes) or 'none'}",
+            f"  {'✓' if self.indexes.bm25_indexes else '·'} BM25:  "
+            f"{', '.join(self.indexes.bm25_indexes) or 'none'}",
+            f"  {'✓' if self.indexes.plaid_indexes else '·'} PLAID: "
+            f"{', '.join(self.indexes.plaid_indexes) or 'none'}",
+        ]
+
+        if self.errors:
+            lines.append(f"\nProbe errors ({len(self.errors)})")
+            for e in self.errors:
+                lines.append(f"  ! {e}")
+
+        lines.append("\n" + "═" * 50)
+        return "\n".join(lines)

{iris_vector_graph-1.63.1 → iris_vector_graph-1.63.3}/pyproject.toml

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