iris-vector-graph 2.0.0__tar.gz → 2.1.1__tar.gz

iris_vector_graph-2.1.1/PKG-INFO

@@ -0,0 +1,255 @@
+Metadata-Version: 2.4
+Name: iris-vector-graph
+Version: 2.1.1
+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
+Project-URL: Repository, https://github.com/intersystems-community/iris-vector-graph
+Project-URL: Issues, https://github.com/intersystems-community/iris-vector-graph/issues
+Author-email: InterSystems Community Team <grants@intersystems.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bioinformatics,biomedical,graph,iris,knowledge-graph,protein-interactions,vector-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Requires-Dist: intersystems-iris>=1.0.0
+Provides-Extra: biodata
+Requires-Dist: biopython>=1.81; extra == 'biodata'
+Requires-Dist: bioservices>=1.11.0; extra == 'biodata'
+Requires-Dist: mygene>=3.2.0; extra == 'biodata'
+Requires-Dist: obonet>=1.0.0; extra == 'biodata'
+Provides-Extra: browser
+Requires-Dist: fastapi>=0.118.0; extra == 'browser'
+Requires-Dist: uvicorn>=0.37.0; extra == 'browser'
+Provides-Extra: cli
+Requires-Dist: click>=8.0.0; extra == 'cli'
+Requires-Dist: httpx>=0.28.1; extra == 'cli'
+Requires-Dist: tabulate>=0.9.0; extra == 'cli'
+Provides-Extra: communities
+Requires-Dist: leidenalg>=0.10; extra == 'communities'
+Requires-Dist: networkx>=3.0; extra == 'communities'
+Requires-Dist: python-igraph>=0.11; extra == 'communities'
+Provides-Extra: core
+Requires-Dist: intersystems-iris>=1.0.0; extra == 'core'
+Provides-Extra: demo
+Requires-Dist: python-fasthtml>=0.12.0; extra == 'demo'
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: flake8>=6.0.0; extra == 'dev'
+Requires-Dist: iris-devtester>=1.18.1; extra == 'dev'
+Requires-Dist: isort>=5.12.0; extra == 'dev'
+Requires-Dist: mypy>=1.5.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-playwright>=0.7.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Provides-Extra: full
+Requires-Dist: fastapi>=0.118.0; extra == 'full'
+Requires-Dist: httpx>=0.28.1; extra == 'full'
+Requires-Dist: iris-embedded-python-wrapper>=0.5.20; extra == 'full'
+Requires-Dist: leidenalg>=0.10; extra == 'full'
+Requires-Dist: networkx>=3.0; extra == 'full'
+Requires-Dist: numpy>=1.24.0; extra == 'full'
+Requires-Dist: pandas>=2.0.0; extra == 'full'
+Requires-Dist: pydantic>=2.11.9; extra == 'full'
+Requires-Dist: python-dotenv>=1.0.0; extra == 'full'
+Requires-Dist: python-igraph>=0.11; extra == 'full'
+Requires-Dist: rdflib>=6.0.0; extra == 'full'
+Requires-Dist: requests>=2.28.0; extra == 'full'
+Requires-Dist: strawberry-graphql[fastapi]>=0.280.0; extra == 'full'
+Requires-Dist: uvicorn>=0.37.0; extra == 'full'
+Provides-Extra: ml
+Requires-Dist: scikit-learn>=1.3.0; extra == 'ml'
+Requires-Dist: scipy>=1.11.0; extra == 'ml'
+Requires-Dist: torch>=2.0.0; extra == 'ml'
+Provides-Extra: performance
+Requires-Dist: memory-profiler>=0.61.0; extra == 'performance'
+Requires-Dist: psutil>=5.9.0; extra == 'performance'
+Provides-Extra: plaid
+Requires-Dist: numpy>=1.24.0; extra == 'plaid'
+Requires-Dist: scikit-learn>=1.3.0; extra == 'plaid'
+Provides-Extra: visualization
+Requires-Dist: graphviz>=0.20.0; extra == 'visualization'
+Requires-Dist: matplotlib>=3.7.0; extra == 'visualization'
+Requires-Dist: plotly>=5.15.0; extra == 'visualization'
+Description-Content-Type: text/markdown
+
+# iris-vector-graph
+
+**Knowledge graph engine for InterSystems IRIS** — openCypher queries, temporal property graph, vector search, and graph analytics.
+
+[![PyPI](https://img.shields.io/pypi/v/iris-vector-graph)](https://pypi.org/project/iris-vector-graph/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![IRIS 2024.1+](https://img.shields.io/badge/IRIS-2024.1+-purple.svg)](https://www.intersystems.com/products/intersystems-iris/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+---
+
+## Getting Started
+
+Five minutes from zero to running graph queries.
+
+### 1. Start IRIS
+
+```bash
+docker compose up -d
+```
+
+Starts IRIS Community Edition on `localhost:1972`. No license required.
+Default credentials: `_SYSTEM` / `SYS`.
+
+### 2. Install
+
+```bash
+pip install iris-vector-graph
+```
+
+### 3. Run your first query
+
+```python
+import iris
+from iris_vector_graph.engine import IRISGraphEngine
+
+conn = iris.connect("localhost", 1972, "USER", "_SYSTEM", "SYS")
+engine = IRISGraphEngine(conn, embedding_dimension=768)
+engine.initialize_schema()
+
+engine.create_node("alice", labels=["Person"], properties={"name": "Alice"})
+engine.create_node("bob",   labels=["Person"], properties={"name": "Bob"})
+engine.create_edge("alice", "KNOWS", "bob")
+
+result = engine.execute_cypher(
+    "MATCH (a {node_id:$id})-[:KNOWS]->(b) RETURN b.name AS name",
+    {"id": "alice"}
+)
+print(result["rows"])  # [('Bob',)]
+```
+
+> **Note:** `initialize_schema()` prints compile warnings on Community Edition — safe to ignore.
+> Enterprise-only classes (`Graph.KG.MCPService`, `Graph.KG.MCPToolSet`) are not required.
+
+---
+
+## What It Does
+
+| Feature | Notes |
+|---------|-------|
+| **openCypher** | `MATCH`, `CREATE`, `MERGE`, `DELETE`, `WITH`, `UNWIND`, variable-length paths, subqueries |
+| **Temporal property graph** | Time-windowed edges, pre-aggregated bucket analytics, O(1) window queries |
+| **Vector search** | HNSW (native IRIS VECTOR), IVFFlat, PLAID multi-vector, BM25 full-text |
+| **Graph analytics** | Betweenness, closeness, eigenvector, degree centrality; Leiden community detection; SCC; k-core; PPR |
+| **Shortest path** | Unweighted BFS (`shortestPath`), weighted Dijkstra (`ivg.shortestPath.weighted`) |
+| **NKG fast-path** | `[*1..N]` Cypher patterns route to integer-keyed `^NKG` index, bypassing SQL translation |
+| **Bulk loader** | 190–312K edges/s direct `^KG` write; incremental `^NKG` rebuild |
+| **FHIR bridge** | ICD-10 → knowledge graph mapping via FHIR R4 |
+| **Bolt protocol** | neo4j-driver compatible wire protocol (TCP + WebSocket) |
+| **Embedded Python** | Graph algorithms run server-side via IRIS embedded Python (igraph, leidenalg) |
+| **IPM / ZPM** | ObjectScript-only install via InterSystems Package Manager |
+
+---
+
+## Performance
+
+Hardware: M3 Ultra, Community IRIS 2026.1, ARM64 Docker.
+
+### Query latency
+
+| Query | Latency | Notes |
+|-------|---------|-------|
+| 1-hop neighbor lookup | ~0.4ms | `$Order` on `^KG` |
+| NKG fast-path `[*1..N]`, hops 2–5 | 1.4–2.0ms | **4.9–13.4x faster than SQL path** |
+| IC3 2-hop with LIMIT (LDBC SF10) | 1.2ms | 3.5x faster than GES/GraphScope |
+| IC13 shortest path (LDBC SF10) | 2.1–3.2ms | Comparable to GES at SF1000 on cluster |
+| HNSW vector search (768-dim) | 1.7ms | Native IRIS VECTOR index |
+| BM25 full-text (174 nodes, 3-term) | 0.3ms | Posting-list `$Order` |
+| Temporal window query | 0.1ms | O(results), B-tree |
+| Pre-aggregated bucket (24hr/288 buckets) | 0.16ms | O(buckets), not O(edges) |
+
+### Algorithm comparison (vs Neo4j GDS and networkx)
+
+IVG is competitive with or faster than Neo4j GDS on degree centrality, betweenness, and Leiden
+community detection, producing results identical to networkx (Pearson r = 1.0).
+Validated on DRKG biomedical KG (~97K nodes / ~5.9M edges).
+
+Full methodology and numbers: [docs/performance/BENCHMARKS.md](docs/performance/BENCHMARKS.md)
+and [docs/performance/GRAPH_ALGORITHMS.md](docs/performance/GRAPH_ALGORITHMS.md).
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                    iris-vector-graph  v2.1.0                        │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│   ┌───────────────┐   ┌───────────────┐   ┌───────────────────┐    │
+│   │  Python SDK   │   │  Cypher/AQL   │   │   Bolt (wire)     │    │
+│   │  IRISGraph    │   │  translator   │   │   neo4j-driver    │    │
+│   │  Engine       │   │  + executor   │   │   compatible      │    │
+│   └───────┬───────┘   └───────┬───────┘   └────────┬──────────┘    │
+│           └──────────────┬────┘                    │               │
+│                          ▼                          │               │
+│             ┌────────────────────────┐              │               │
+│             │   GraphStore protocol  │◄─────────────┘               │
+│             │   (pluggable backend)  │                              │
+│             └───────────┬────────────┘                              │
+│                         │                                           │
+│          ┌──────────────┼──────────────┐                           │
+│          ▼              ▼              ▼                            │
+│   ┌─────────────┐ ┌──────────┐ ┌───────────────┐                  │
+│   │  SQL layer  │ │  ^KG     │ │  ^NKG         │                  │
+│   │  Graph_KG.* │ │  globals │ │  integer adj  │                  │
+│   │  (nodes,    │ │  (edges, │ │  index        │                  │
+│   │   edges,    │ │   temp,  │ └───────┬───────┘                  │
+│   │   vectors)  │ │   PPR)   │         │                          │
+│   └─────────────┘ └──────────┘         │                          │
+│                                         ▼                          │
+│                              ┌────────────────────┐               │
+│                              │  Algorithm tiers   │               │
+│                              ├────────────────────┤               │
+│                              │ 1. Rust accelerator│ ← fastest     │
+│                              │    (rayon parallel)│               │
+│                              │ 2. ObjectScript    │               │
+│                              │    parallel 8×     │               │
+│                              │ 3. Python LazyKG   │ ← always works│
+│                              └────────────────────┘               │
+│                                                                     │
+│   Centrality:  betweenness (Brandes) · closeness · eigenvector     │
+│                degree                                              │
+│   Community:   Leiden · triangle count · SCC · k-core             │
+│   Search:      vector (HNSW/IVF/PLAID) · BM25 · temporal · PPR   │
+│                                                                     │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+Full schema and ObjectScript class reference: [docs/architecture/ARCHITECTURE.md](docs/architecture/ARCHITECTURE.md).
+
+---
+
+## Documentation
+
+| Document | Contents |
+|----------|----------|
+| [User Guide](docs/USER_GUIDE.md) | Cypher examples, temporal edges, vector search, bulk loader |
+| [Admin Guide](docs/ADMIN_GUIDE.md) | Container setup, schema management, index rebuilding |
+| [Admin API](docs/ADMIN_API.md) | Python API reference for engine administration |
+| [Benchmarks](docs/performance/BENCHMARKS.md) | Full methodology, LDBC SNB results, ingestion throughput |
+| [Graph Algorithms](docs/performance/GRAPH_ALGORITHMS.md) | Centrality and community detection benchmark details |
+| [Changelog](CHANGELOG.md) | Full version history |
+
+---
+
+## License
+
+MIT. See [LICENSE](LICENSE).

iris_vector_graph-2.1.1/README.md

@@ -0,0 +1,169 @@
+# iris-vector-graph
+
+**Knowledge graph engine for InterSystems IRIS** — openCypher queries, temporal property graph, vector search, and graph analytics.
+
+[![PyPI](https://img.shields.io/pypi/v/iris-vector-graph)](https://pypi.org/project/iris-vector-graph/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![IRIS 2024.1+](https://img.shields.io/badge/IRIS-2024.1+-purple.svg)](https://www.intersystems.com/products/intersystems-iris/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+---
+
+## Getting Started
+
+Five minutes from zero to running graph queries.
+
+### 1. Start IRIS
+
+```bash
+docker compose up -d
+```
+
+Starts IRIS Community Edition on `localhost:1972`. No license required.
+Default credentials: `_SYSTEM` / `SYS`.
+
+### 2. Install
+
+```bash
+pip install iris-vector-graph
+```
+
+### 3. Run your first query
+
+```python
+import iris
+from iris_vector_graph.engine import IRISGraphEngine
+
+conn = iris.connect("localhost", 1972, "USER", "_SYSTEM", "SYS")
+engine = IRISGraphEngine(conn, embedding_dimension=768)
+engine.initialize_schema()
+
+engine.create_node("alice", labels=["Person"], properties={"name": "Alice"})
+engine.create_node("bob",   labels=["Person"], properties={"name": "Bob"})
+engine.create_edge("alice", "KNOWS", "bob")
+
+result = engine.execute_cypher(
+    "MATCH (a {node_id:$id})-[:KNOWS]->(b) RETURN b.name AS name",
+    {"id": "alice"}
+)
+print(result["rows"])  # [('Bob',)]
+```
+
+> **Note:** `initialize_schema()` prints compile warnings on Community Edition — safe to ignore.
+> Enterprise-only classes (`Graph.KG.MCPService`, `Graph.KG.MCPToolSet`) are not required.
+
+---
+
+## What It Does
+
+| Feature | Notes |
+|---------|-------|
+| **openCypher** | `MATCH`, `CREATE`, `MERGE`, `DELETE`, `WITH`, `UNWIND`, variable-length paths, subqueries |
+| **Temporal property graph** | Time-windowed edges, pre-aggregated bucket analytics, O(1) window queries |
+| **Vector search** | HNSW (native IRIS VECTOR), IVFFlat, PLAID multi-vector, BM25 full-text |
+| **Graph analytics** | Betweenness, closeness, eigenvector, degree centrality; Leiden community detection; SCC; k-core; PPR |
+| **Shortest path** | Unweighted BFS (`shortestPath`), weighted Dijkstra (`ivg.shortestPath.weighted`) |
+| **NKG fast-path** | `[*1..N]` Cypher patterns route to integer-keyed `^NKG` index, bypassing SQL translation |
+| **Bulk loader** | 190–312K edges/s direct `^KG` write; incremental `^NKG` rebuild |
+| **FHIR bridge** | ICD-10 → knowledge graph mapping via FHIR R4 |
+| **Bolt protocol** | neo4j-driver compatible wire protocol (TCP + WebSocket) |
+| **Embedded Python** | Graph algorithms run server-side via IRIS embedded Python (igraph, leidenalg) |
+| **IPM / ZPM** | ObjectScript-only install via InterSystems Package Manager |
+
+---
+
+## Performance
+
+Hardware: M3 Ultra, Community IRIS 2026.1, ARM64 Docker.
+
+### Query latency
+
+| Query | Latency | Notes |
+|-------|---------|-------|
+| 1-hop neighbor lookup | ~0.4ms | `$Order` on `^KG` |
+| NKG fast-path `[*1..N]`, hops 2–5 | 1.4–2.0ms | **4.9–13.4x faster than SQL path** |
+| IC3 2-hop with LIMIT (LDBC SF10) | 1.2ms | 3.5x faster than GES/GraphScope |
+| IC13 shortest path (LDBC SF10) | 2.1–3.2ms | Comparable to GES at SF1000 on cluster |
+| HNSW vector search (768-dim) | 1.7ms | Native IRIS VECTOR index |
+| BM25 full-text (174 nodes, 3-term) | 0.3ms | Posting-list `$Order` |
+| Temporal window query | 0.1ms | O(results), B-tree |
+| Pre-aggregated bucket (24hr/288 buckets) | 0.16ms | O(buckets), not O(edges) |
+
+### Algorithm comparison (vs Neo4j GDS and networkx)
+
+IVG is competitive with or faster than Neo4j GDS on degree centrality, betweenness, and Leiden
+community detection, producing results identical to networkx (Pearson r = 1.0).
+Validated on DRKG biomedical KG (~97K nodes / ~5.9M edges).
+
+Full methodology and numbers: [docs/performance/BENCHMARKS.md](docs/performance/BENCHMARKS.md)
+and [docs/performance/GRAPH_ALGORITHMS.md](docs/performance/GRAPH_ALGORITHMS.md).
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                    iris-vector-graph  v2.1.0                        │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│   ┌───────────────┐   ┌───────────────┐   ┌───────────────────┐    │
+│   │  Python SDK   │   │  Cypher/AQL   │   │   Bolt (wire)     │    │
+│   │  IRISGraph    │   │  translator   │   │   neo4j-driver    │    │
+│   │  Engine       │   │  + executor   │   │   compatible      │    │
+│   └───────┬───────┘   └───────┬───────┘   └────────┬──────────┘    │
+│           └──────────────┬────┘                    │               │
+│                          ▼                          │               │
+│             ┌────────────────────────┐              │               │
+│             │   GraphStore protocol  │◄─────────────┘               │
+│             │   (pluggable backend)  │                              │
+│             └───────────┬────────────┘                              │
+│                         │                                           │
+│          ┌──────────────┼──────────────┐                           │
+│          ▼              ▼              ▼                            │
+│   ┌─────────────┐ ┌──────────┐ ┌───────────────┐                  │
+│   │  SQL layer  │ │  ^KG     │ │  ^NKG         │                  │
+│   │  Graph_KG.* │ │  globals │ │  integer adj  │                  │
+│   │  (nodes,    │ │  (edges, │ │  index        │                  │
+│   │   edges,    │ │   temp,  │ └───────┬───────┘                  │
+│   │   vectors)  │ │   PPR)   │         │                          │
+│   └─────────────┘ └──────────┘         │                          │
+│                                         ▼                          │
+│                              ┌────────────────────┐               │
+│                              │  Algorithm tiers   │               │
+│                              ├────────────────────┤               │
+│                              │ 1. Rust accelerator│ ← fastest     │
+│                              │    (rayon parallel)│               │
+│                              │ 2. ObjectScript    │               │
+│                              │    parallel 8×     │               │
+│                              │ 3. Python LazyKG   │ ← always works│
+│                              └────────────────────┘               │
+│                                                                     │
+│   Centrality:  betweenness (Brandes) · closeness · eigenvector     │
+│                degree                                              │
+│   Community:   Leiden · triangle count · SCC · k-core             │
+│   Search:      vector (HNSW/IVF/PLAID) · BM25 · temporal · PPR   │
+│                                                                     │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+Full schema and ObjectScript class reference: [docs/architecture/ARCHITECTURE.md](docs/architecture/ARCHITECTURE.md).
+
+---
+
+## Documentation
+
+| Document | Contents |
+|----------|----------|
+| [User Guide](docs/USER_GUIDE.md) | Cypher examples, temporal edges, vector search, bulk loader |
+| [Admin Guide](docs/ADMIN_GUIDE.md) | Container setup, schema management, index rebuilding |
+| [Admin API](docs/ADMIN_API.md) | Python API reference for engine administration |
+| [Benchmarks](docs/performance/BENCHMARKS.md) | Full methodology, LDBC SNB results, ingestion throughput |
+| [Graph Algorithms](docs/performance/GRAPH_ALGORITHMS.md) | Centrality and community detection benchmark details |
+| [Changelog](CHANGELOG.md) | Full version history |
+
+---
+
+## License
+
+MIT. See [LICENSE](LICENSE).

{iris_vector_graph-2.0.0 → iris_vector_graph-2.1.1}/examples/domains/biomedical/resolver.py

@@ -201,11 +201,16 @@ class BiomedicalDomainResolver(DomainResolver):
         if input.organism:
             properties["organism"] = input.organism
 
-        engine.create_node(
+        if engine.node_exists(str(input.id)):
+            raise Exception(f"Protein with ID {input.id} already exists")
+
+        created = engine.create_node(
             node_id=str(input.id),
             labels=["Protein"],
             properties=properties
         )
+        if not created:
+            raise Exception(f"Protein with ID {input.id} already exists")
 
         if input.embedding and len(input.embedding) > 0:
             if len(input.embedding) != 768:
@@ -232,11 +237,7 @@ class BiomedicalDomainResolver(DomainResolver):
     async def _update_protein_mutation(
         self, info: Info, id: strawberry.ID, input: UpdateProteinInput
     ) -> Protein:
-        """
-        Update an existing protein's fields.
-
-        Uses engine.update_node for properties.
-        """
+        """Update an existing protein's fields."""
         from iris_vector_graph.engine import IRISGraphEngine
         db_connection = info.context.get("db_connection")
         engine = IRISGraphEngine(db_connection)
@@ -244,7 +245,7 @@ class BiomedicalDomainResolver(DomainResolver):
         if not engine.node_exists(str(id)):
             raise Exception(f"Protein with ID {id} not found")
 
-        updates = {}
+        updates: Dict[str, str] = {}
         if input.name is not None:
             updates["name"] = input.name
         if input.function is not None:
@@ -253,7 +254,23 @@ class BiomedicalDomainResolver(DomainResolver):
             updates["confidence"] = str(input.confidence)
 
         if updates:
-            engine.update_node(str(id), properties=updates)
+            cursor = db_connection.cursor()
+            for key, val in updates.items():
+                try:
+                    cursor.execute(
+                        "UPDATE Graph_KG.rdf_props SET val = ? WHERE s = ? AND key = ?",
+                        [val, str(id), key],
+                    )
+                    if cursor.rowcount == 0:
+                        cursor.execute(
+                            "INSERT INTO Graph_KG.rdf_props (s, key, val) VALUES (?, ?, ?)",
+                            [str(id), key, val],
+                        )
+                except Exception:
+                    cursor.execute(
+                        "INSERT INTO Graph_KG.rdf_props (s, key, val) VALUES (?, ?, ?)",
+                        [str(id), key, val],
+                    )
 
         db_connection.commit()
 

{iris_vector_graph-2.0.0 → iris_vector_graph-2.1.1}/examples/domains/biomedical/types.py

@@ -130,24 +130,21 @@ class Protein(Node):
         # Check if embeddings exist for this protein
         try:
             cursor.execute(
-                "SELECT COUNT(*) FROM kg_NodeEmbeddings WHERE id = ?",
+                "SELECT COUNT(*) FROM Graph_KG.kg_NodeEmbeddings WHERE id = ?",
                 (str(self.id),)
             )
             count = cursor.fetchone()[0]
             if count == 0:
-                # No embedding for this protein
                 return []
         except Exception:
             return []
 
-        # Try to use VECTOR functions if available (IRIS 2025.1+)
-        # Query using HNSW vector search with VECTOR_DOT_PRODUCT
         query = """
             SELECT TOP ?
                 e2.id,
                 VECTOR_DOT_PRODUCT(e1.emb, e2.emb) as similarity
-            FROM kg_NodeEmbeddings e1,
-                 kg_NodeEmbeddings e2
+            FROM Graph_KG.kg_NodeEmbeddings e1,
+                 Graph_KG.kg_NodeEmbeddings e2
             WHERE e1.id = ?
               AND e2.id != ?
               AND VECTOR_DOT_PRODUCT(e1.emb, e2.emb) >= ?

{iris_vector_graph-2.0.0 → iris_vector_graph-2.1.1}/iris_src/src/Graph/KG/NKGAccelAdjacency.cls

@@ -229,8 +229,9 @@ ClassMethod ExportAdjacencyFromSeed(seed As %String, maxHops As %Integer = 4, pr
     Kill ^||seedBFS
     Return result
 }
-ClassMethod ExportAdjacencyWithPreds() As %String [ Private ]
+ClassMethod ExportAdjacencyWithPreds(requiredPreds As %List = "") As %String [ Private ]
 {
+    Set hasGuard = (requiredPreds '= "") && ($ListLength(requiredPreds) > 0)
     Set result = "", chunk = "", chunkNum = 0
     Set src = ""
     For {
@@ -246,6 +247,7 @@ ClassMethod ExportAdjacencyWithPreds() As %String [ Private ]
             For {
                 Set dst = $Order(^NKG(-1, src, pred, dst))
                 Quit:dst=""
+                If hasGuard && '##class(Graph.KG.NKGAccelTraversal).StructuralGuard(dst, requiredPreds) Continue
                 Set dstStr = $Get(^NKG("$ND", dst), dst)
                 Set line = srcStr _ $Char(31) _ predStr _ $Char(31) _ dstStr _ $Char(10)
                 If $Length(result) + $Length(line) > 3000000 {

{iris_vector_graph-2.0.0 → iris_vector_graph-2.1.1}/iris_src/src/Graph/KG/NKGAccelTraversal.cls

@@ -26,10 +26,10 @@ ClassMethod KHopNeighbors(seedId As %String, k As %Integer = 2, maxNodes As %Int
             Set node = $Order(^||frontier(node))
             Quit:node=""
             If useNKG {
-                Set pred = ""
+                Set pred = -99999999
                 For {
                     Set pred = $Order(^NKG(-1, node, pred))
-                    Quit:pred=""
+                    Quit:(pred="")!(pred>=0)
                     Set dst = ""
                     For {
                         Set dst = $Order(^NKG(-1, node, pred, dst))
@@ -109,10 +109,10 @@ ClassMethod KHopNeighborsSorted(seedId As %String, k As %Integer = 2, maxNodes A
             Set node = $Order(^||frontier(node))
             Quit:node=""
             If useNKG {
-                Set pred = ""
+                Set pred = -99999999
                 For {
                     Set pred = $Order(^NKG(-1, node, pred))
-                    Quit:pred=""
+                    Quit:(pred="")!(pred>=0)
                     Set dst = ""
                     For {
                         Set dst = $Order(^NKG(-1, node, pred, dst))
@@ -196,10 +196,10 @@ ClassMethod PPRNative(seedId As %String, alpha As %Double = 0.85, maxIter As %In
         If useNKG {
             Set nkgIdx = $Get(^NKG("$NI", nodeId), "")
             If nkgIdx '= "" {
-                Set pred = ""
+                Set pred = -99999999
                 For {
                     Set pred = $Order(^NKG(-1, nkgIdx, pred))
-                    Quit:pred=""
+                    Quit:(pred="")!(pred>=0)
                     Set dst = ""
                     For {
                         Set dst = $Order(^NKG(-1, nkgIdx, pred, dst))
@@ -308,7 +308,7 @@ ClassMethod RandomWalkJson(seedId As %String, walkLength As %Integer = 20, numWa
             Kill ^||walkNbrs
             Set nbrCount = 0
             If useNKG && (currentIdx '= "") {
-                Set pred = "" For { Set pred=$Order(^NKG(-1,currentIdx,pred)) Quit:pred=""  Set dst="" For { Set dst=$Order(^NKG(-1,currentIdx,pred,dst)) Quit:dst=""  Set nbrCount=nbrCount+1, ^||walkNbrs(nbrCount)=dst } }
+                Set pred = -99999999  For { Set pred=$Order(^NKG(-1,currentIdx,pred)) Quit:(pred="")||(pred>=0)  Set dst="" For { Set dst=$Order(^NKG(-1,currentIdx,pred,dst)) Quit:dst=""  Set nbrCount=nbrCount+1, ^||walkNbrs(nbrCount)=dst } }
             } Else {
                 Set pred="" For { Set pred=$Order(^KG("out",current,pred)) Quit:pred=""  Set dst="" For { Set dst=$Order(^KG("out",current,pred,dst)) Quit:dst=""  Set nbrCount=nbrCount+1, ^||walkNbrs(nbrCount)=dst } }
             }
@@ -387,10 +387,10 @@ ClassMethod ShortestPathNKG(srcId As %String, dstId As %String, maxHops As %Inte
         For {
             Set ni = $Order(^||BF(ni))
             Quit:ni=""
-            Set pred = ""
+            Set pred = -99999999
             For {
                 Set pred = $Order(^NKG(-1, ni, pred))
-                Quit:pred=""
+                Quit:(pred="")!(pred>=0)
                 Set di = ""
                 For {
                     Set di = $Order(^NKG(-1, ni, pred, di))
@@ -413,10 +413,10 @@ ClassMethod ShortestPathNKG(srcId As %String, dstId As %String, maxHops As %Inte
         For {
             Set ni = $Order(^||BB(ni))
             Quit:ni=""
-            Set pred = ""
+            Set pred = -99999999
             For {
                 Set pred = $Order(^NKG(-2, ni, pred))
-                Quit:pred=""
+                Quit:(pred="")!(pred>=0)
                 Set si = ""
                 For {
                     Set si = $Order(^NKG(-2, ni, pred, si))
@@ -479,11 +479,10 @@ ClassMethod CountDistinctKHop(srcId As %String, predsJson As %String = "", maxHo
             Set s = $Order(frontier(s))
             Quit:s=""
             If direction = "out" || (direction = "both") {
-                Set pIdx2 = ""
+                Set pIdx2 = -99999999
                 For {
                     Set pIdx2 = $Order(^NKG(-1, s, pIdx2))
-                    Quit:pIdx2=""
-                    If pIdx2 >= 0 Quit
+                    Quit:(pIdx2="")!(pIdx2>=0)
                     If $IsObject(predsIdxArr) {
                         Set matched = 0
                         For pi = 0:1:(predsIdxArr.%Size()-1) {
@@ -503,11 +502,10 @@ ClassMethod CountDistinctKHop(srcId As %String, predsJson As %String = "", maxHo
                 }
             }
             If direction = "in" || (direction = "both") {
-                Set pIdx2 = ""
+                Set pIdx2 = -99999999
                 For {
                     Set pIdx2 = $Order(^NKG(-2, s, pIdx2))
-                    Quit:pIdx2=""
-                    If pIdx2 >= 0 Quit
+                    Quit:(pIdx2="")!(pIdx2>=0)
                     If $IsObject(predsIdxArr) {
                         Set matched = 0
                         For pi = 0:1:(predsIdxArr.%Size()-1) {
@@ -557,6 +555,20 @@ ClassMethod CountDistinctKHop(srcId As %String, predsJson As %String = "", maxHo
     Set estimate = ##class(Graph.KG.GraphIndex).EstimateHLL(merged)
     Return "{""estimate"":"_estimate_",""registers"":256,""std_error"":0.065}"
 }
+/// Returns 1 if nodeIdx has at least one edge for every predicate index in requiredPreds.
+/// Uses $Data — no value fetch — for structural check only.
+ClassMethod StructuralGuard(nodeIdx As %Integer, requiredPreds As %List) As %Boolean
+{
+    Set len = $ListLength(requiredPreds)
+    If len = 0 Return 1
+    For i = 1:1:len {
+        Set predIdx = $List(requiredPreds, i)
+        // NKG stores pred keys as -(pIdx+1) to keep them negative (sort before "")
+        If '$Data(^NKG(-1, nodeIdx, -(predIdx+1))) Return 0
+    }
+    Return 1
+}
+
 ClassMethod Build2HopExact() As %Boolean
 {
     If '##class(Graph.KG.NKGAccelLoader).IsLoaded() {