iris-vector-graph 1.94.0__tar.gz → 1.98.0__tar.gz

{iris_vector_graph-1.94.0 → iris_vector_graph-1.98.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris-vector-graph
-Version: 1.94.0
+Version: 1.98.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
@@ -29,6 +29,10 @@ 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: 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: core
 Requires-Dist: intersystems-iris>=1.0.0; extra == 'core'
 Provides-Extra: demo
@@ -36,7 +40,7 @@ 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.14.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'
@@ -45,6 +49,7 @@ 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: networkx>=3.0; extra == 'full'
 Requires-Dist: numpy>=1.24.0; extra == 'full'
 Requires-Dist: pandas>=2.0.0; extra == 'full'
@@ -188,17 +193,19 @@ The single 2025.1 failure: `SKIP` clause uses `ORDER BY + OFFSET` on JSON_TABLE-
 
 Two live demos ship in `src/iris_demo_server/`:
 
-| Demo | URL | What it shows |
-|------|-----|--------------|
-| **Fraud Detection** | `http://localhost:8200/fraud` | Real-time fraud scoring, bitemporal audit trails, ring pattern detection |
-| **Biomedical Research** | `http://localhost:8200/bio` | Protein similarity search, pathway traversal, D3 network visualization |
+| Demo | URL | What it shows | Docs |
+|------|-----|--------------|------|
+| **Fraud Detection** | `http://localhost:8200/fraud` | Real-time fraud scoring, ring detection, money mule identification, bitemporal audit trails | [docs/demos/FRAUD_DEMO.md](docs/demos/FRAUD_DEMO.md) |
+| **Biomedical Research** | `http://localhost:8200/bio` | Protein similarity search, pathway traversal, hybrid vector+graph queries, D3 network visualization | [docs/demos/BIOMEDICAL_DEMO.md](docs/demos/BIOMEDICAL_DEMO.md) |
+
+The fraud demo is inspired by the [AWS Neptune fraud graph reference notebook](https://github.com/aws/graph-notebook/blob/main/src/graph_notebook/notebooks/01-Neptune-Database/03-Sample-Applications/01-Fraud-Graphs/01-Building-a-Fraud-Graph-Application.ipynb) — the same fraud ring and identity theft patterns (first-party and third-party fraud on credit card transaction data), running on IRIS with Cypher instead of Gremlin.
 
 ```bash
 # 1. Start IRIS
 docker compose up -d
 
 # 2. Install deps (once)
-pip install iris-vector-graph[full]
+pip install "iris-vector-graph[full]"
 
 # 3. Start demo server
 python -m uvicorn iris_demo_server.app:app --port 8200 --host 127.0.0.1 \
@@ -208,7 +215,7 @@ python -m uvicorn iris_demo_server.app:app --port 8200 --host 127.0.0.1 \
 open http://localhost:8200
 ```
 
-The demos use the generic IVG graph engine — no separate backend required. All data is created by the demo on first run.
+The demos use the generic IVG graph engine — no separate backend required.
 
 ---
 
@@ -803,6 +810,26 @@ conditions = tool("patient-123")  # → {"conditions": [...], "error": None}
 
  ## Changelog
 
+### v1.98.0 (2026-05-28)
+- **feat**: Spec 162 — Centrality Suite. Four new graph centrality algorithms shipping via the GraphStore protocol + Cypher procedures, closing the biggest coverage gap vs Neo4j GDS:
+  - `engine.degree_centrality(direction, predicate, top_k)` — out/in/both, predicate-filtered, normalized to (n-1)
+  - `engine.betweenness_centrality(sample_size, direction, max_hops, top_k, mem_budget_mb, progress_callback)` — Brandes (2001), Brandes-Pich approximation when sampled, per-source memory budget, progress reporting
+  - `engine.closeness_centrality(formula, direction, max_hops, top_k, progress_callback)` — `harmonic` (default, robust to disconnection) and `classical` formulas
+  - `engine.eigenvector_centrality(max_iter, tol, top_k, progress_callback)` — power iteration over raw adjacency `A`, L2-normalized, matches `networkx.eigenvector_centrality_numpy` (NOT PageRank with α=1)
+- **feat**: 4 Cypher procedures `CALL ivg.degreeCentrality({...}) YIELD node, score, degree`, `CALL ivg.betweenness({...}) YIELD node, score`, `CALL ivg.closeness({...})`, `CALL ivg.eigenvector({...})` with map-parameter syntax. Procedure-call validator rejects unknown keys (FR-029 forward-compat reservation for future `weighted` variants).
+- **feat**: `engine.get_centrality_warnings()` reads `^IVG.warnings("centrality", ...)` for memory-budget skip events; Brandes writes warning entries when per-source predecessor accumulator exceeds `mem_budget_mb`.
+- **feat**: 4 new `GraphStore` protocol methods (`execute_degree_centrality`, `execute_betweenness`, `execute_closeness`, `execute_eigenvector`) + 4 capability keys.
+- **feat**: 4 new Pydantic input models exported from package root: `DegreeCentralityInput`, `BetweennessInput`, `ClosenessInput`, `EigenvectorInput`.
+- **feat**: `scripts/test-container.sh` — single entry point for IRIS test container ops (replaces ad-hoc `IRISContainer.start()` calls). Includes graceful `iris stop IRIS quietly` before `docker rm -f` (Bug T mitigation).
+- **feat**: Container renamed from legacy `gqs-ivg-test` (ephemeral) to `ivg-iris` (persistent, registered in lab_manager registry as `status: active`).
+- **fix (Bug S)**: Native API gref-bypass production path for centrality algorithms — when `iris.createIRIS().classMethodValue('Graph.KG.Centrality', ...)` returns `<CLASS DOES NOT EXIST>` from `%SYS.DBSRV` cache, the Python store automatically falls back to direct `^KG` global access via `iris_inst.set/get/nextSubscript/kill`. Algorithm correctness proven via Pearson > 0.85 with networkx reference on `networkx.betweenness_centrality`, `harmonic_centrality`, `eigenvector_centrality_numpy`, `out_degree_centrality`.
+- **fix (Bug T)**: `iris-devtester>=1.18.1` upstream fix — `IRISContainer.__exit__()` now calls `stop_gracefully()` (graceful `iris stop IRIS quietly`) before Docker SIGKILL, preventing silent row loss on container restart. IVG bumped pin to `iris-devtester>=1.18.1`.
+- **fix (Bug R, false alarm)**: Investigation confirmed `los-iris` slowness from unindexed `rdf_labels.s`/`rdf_props.s` was specific to productivity-framework's container schema; IVG's `initialize_schema()` already creates `idx_labels_s` and `idx_props_s`. No IVG fix needed.
+- **test**: 16 new e2e tests in `tests/e2e/test_centrality_e2e.py` — networkx parity master gate + per-algorithm validation (15 PASS + 1 XFAIL Bug S Cypher path, deeply documented).
+- **test**: 30 new unit tests in `tests/unit/test_centrality_unit.py` and `tests/unit/test_centrality_translator.py` — protocol routing, Pydantic validation, Cypher translator FR-029 enforcement.
+- **docs**: `specs/162-centrality-suite/{spec,plan,research,data-model,quickstart,tasks}.md` — full spec with 5 clarifications integrated, 29 functional requirements, 6 NFRs, 10 user stories.
+- **docs**: `ENGINEERING_DEBT.md` Bug S + Bug T entries with reproduction steps and resolution context.
+
 ### v1.88.0 (2026-05-07)
 - **feat**: `ffi_kg_build_2hop_exact_int` Rust function — integer-indexed single-pass 2-hop dedup from `^KG("out")`. Writes results to `^ArnoKG("2h")` temp global; `DecodeBuildResults()` ObjectScript method converts to `^KG("deg2p_exact")`
 - **feat**: `KHop2CountExact(src, pred)` ObjectScript method — O(1) `$Get(^KG("deg2p_exact"))`, fallback to `KHop2Count` when not populated. 0.14ms p50 on SF10 (was 70ms)
@@ -1252,6 +1279,109 @@ Four openCypher gaps closed, all from structured gap analysis against the openCy
 
 ## Changelog
 
+### v1.97.0 (2026-05-16)
+
+**Three new features closing the gap with NornicDB-style vector-graph fusion:**
+
+**`CALL ivg.retrieve(query, limit, bm25_name?, vec_label?, rrf_k?)`** — single Cypher procedure for BM25 + vector + RRF fusion. Equivalent to NornicDB's `db.retrieve()`:
+```cypher
+CALL ivg.retrieve('insulin resistance', 10) YIELD node, score
+MATCH (node)-[:INTERACTS_WITH]->(target)
+RETURN target.node_id, score ORDER BY score DESC
+```
+Generates three-CTE SQL (BM25_Retrieve + Vec_Retrieve + Retrieve with FULL OUTER JOIN RRF fusion).
+
+**`WHERE vector_distance(n, $vec) < 0.3`** — scalar vector similarity predicate in WHERE/RETURN clauses:
+```cypher
+MATCH (n:Gene) WHERE vector_distance(n, $vec) < 0.3 RETURN n.node_id
+MATCH (n) RETURN n.node_id, vector_similarity(n, $vec) AS sim ORDER BY sim DESC LIMIT 10
+```
+Translates to `VECTOR_COSINE()` subquery against `kg_NodeEmbeddings`.
+
+**`Graph.KG.EmbedQueue`** — async embedding queue (ObjectScript). Write nodes now, embeddings appear asynchronously:
+```python
+engine.enqueue_for_embedding(["n1", "n2", "n3"], embedding_config="my-model")
+engine.start_background_embedding(batch_size=100)
+count = engine.embed_queue_pending()
+result = engine.process_embed_queue(batch_size=50)
+```
+Uses `^EmbedQueue` global + `Graph.KG.EmbedQueue.ProcessBatch()` via `%SYSTEM.Task`.
+
+### v1.96.2 (2026-05-15)
+
+**Fix**: `_build_index_registry()` infinite loop when `iris.gref` is a `MagicMock` (external connections via IVR or test mocks). `gref.order()` on a MagicMock returns a MagicMock, which is never `== ""`, causing infinite loop. Fix: `isinstance(name, str)` guard + `range(10000)` hard limit. Reported by IVR session.
+
+### v1.96.1 (2026-05-15)
+
+**Fix**: Lazy-load `sentence-transformers` and `torch` to prevent repeated memory allocation. Inline `from sentence_transformers import SentenceTransformer` in `embed_text()`, `embed_nodes()`, `embed_edges()` replaced with module-level singletons (`_get_sentence_transformers()`, `_load_sentence_transformer()`). Prevents torch reference counting from blocking GC between embedding batches.
+
+### v1.96.0 (2026-05-15)
+
+**IVG SDK, CLI, Deploy, and iris-embedded-python-wrapper adoption** (spec 160):
+
+**`iris_vector_graph.sdk`** — new thin HTTP client, zero `intersystems-irispython` required:
+```python
+from iris_vector_graph import IVGClient
+with IVGClient("http://localhost:8200", api_key="...") as client:
+    result = client.execute_cypher("MATCH (n) RETURN count(n)")
+    result = client.execute_aql("FOR v IN 1..2 OUTBOUND @s g RETURN v._key", bind_vars={"s": "n1"})
+```
+- `IVGRecord` — dict-style row access: `r["name"]` and `r[0]` both work
+- `IVGError` / `IVGClientError` / `IVGServerError` — structured exception hierarchy
+- `AsyncIVGClient` — identical async API
+- Retry on 5xx (3× exponential backoff)
+- `ping()`, `schema()`, `server_info()`, `stats()`, `explain()`, `load_ndjson()`
+
+**`ivg` CLI** — `pip install "iris-vector-graph[cli]"`:
+```bash
+ivg connect http://localhost:8200
+ivg query "MATCH (n) RETURN count(n)"
+ivg query --aql "FOR v IN 1..2 OUTBOUND @s g RETURN v" --bind s=mesh:D003924
+ivg load graph.ndjson
+ivg schema init / status
+ivg indexes list / rebuild
+ivg server start --iris-host localhost --iris-port 1972
+```
+
+**`deploy/`** folder — four setup paths:
+- `deploy/docker/compose.yml` — fresh IRIS + IVG server in Docker
+- `deploy/bolt-on/install.sh` — bolt onto existing IRIS
+- `deploy/README.md` — decision guide
+
+**`iris-embedded-python-wrapper` adoption**:
+- `IRISGraphEngine.from_wrapper(hostname=...)` — new classmethod using `iris.dbapi.connect()`
+- `cypher_api.py` `_make_engine()` prefers wrapper's `iris.dbapi.connect()` when available
+- `iris-embedded-python-wrapper>=0.5.20` added to `[full]` extra
+- `EmbeddedConnection` retained for backward compatibility
+
+### v1.95.0 (2026-05-15)
+
+**Admin API** — IVG now has a production-grade admin surface matching Neo4j/ArangoDB:
+
+**Fixed: `SHOW INDEXES` / `SHOW CONSTRAINTS`** — were empty stubs; now return actual BM25, IVF, HNSW, PLAID, ^KG, ^NKG indexes and uniqueness constraints. Neo4j Browser, LangChain, and all Neo4j-compatible tools now see the real index state on connect.
+
+**New REST endpoints on the Cypher API:**
+- `GET /schema` — labels, relationship types, property keys, counts
+- `GET /indexes` — full index inventory (all types)
+- `GET /server` — IVG version, IRIS version, namespace, schema status, BFS path
+- `GET /metrics` — Prometheus-format metrics (node/edge/embedding counts, status)
+- `GET /stats` — counts by label, predicate, embedding coverage
+- `POST /admin/schema/init` — initialize schema
+- `POST /admin/indexes/rebuild` — rebuild ^KG and ^NKG adjacency indexes
+- `POST /admin/embed` — trigger node embedding
+- `POST /admin/load` — stream NDJSON graph data
+- `GET /admin/export` — export graph as NDJSON
+- `POST /admin/snapshot` — save snapshot to disk
+- `GET /admin/queries` — list active IRIS queries
+- `DELETE /admin/queries/{id}` — kill a running query
+- `POST /admin/explain` — translate Cypher to SQL (debugging + optimization)
+
+**GraphStore protocol additions** (6 new methods):
+`get_node_count()`, `get_edge_count()`, `get_labels()`, `get_relationship_types()`, `list_indexes()`, `server_info()`
+
+**Engine additions:**
+`engine.list_active_queries()`, `engine.kill_query(id)`
+
 ### v1.94.0 (2026-05-15)
 
 **GraphStore Protocol** — `IRISGraphEngine` now has a pluggable storage backend (spec 156).

{iris_vector_graph-1.94.0 → iris_vector_graph-1.98.0}/README.md

@@ -116,17 +116,19 @@ The single 2025.1 failure: `SKIP` clause uses `ORDER BY + OFFSET` on JSON_TABLE-
 
 Two live demos ship in `src/iris_demo_server/`:
 
-| Demo | URL | What it shows |
-|------|-----|--------------|
-| **Fraud Detection** | `http://localhost:8200/fraud` | Real-time fraud scoring, bitemporal audit trails, ring pattern detection |
-| **Biomedical Research** | `http://localhost:8200/bio` | Protein similarity search, pathway traversal, D3 network visualization |
+| Demo | URL | What it shows | Docs |
+|------|-----|--------------|------|
+| **Fraud Detection** | `http://localhost:8200/fraud` | Real-time fraud scoring, ring detection, money mule identification, bitemporal audit trails | [docs/demos/FRAUD_DEMO.md](docs/demos/FRAUD_DEMO.md) |
+| **Biomedical Research** | `http://localhost:8200/bio` | Protein similarity search, pathway traversal, hybrid vector+graph queries, D3 network visualization | [docs/demos/BIOMEDICAL_DEMO.md](docs/demos/BIOMEDICAL_DEMO.md) |
+
+The fraud demo is inspired by the [AWS Neptune fraud graph reference notebook](https://github.com/aws/graph-notebook/blob/main/src/graph_notebook/notebooks/01-Neptune-Database/03-Sample-Applications/01-Fraud-Graphs/01-Building-a-Fraud-Graph-Application.ipynb) — the same fraud ring and identity theft patterns (first-party and third-party fraud on credit card transaction data), running on IRIS with Cypher instead of Gremlin.
 
 ```bash
 # 1. Start IRIS
 docker compose up -d
 
 # 2. Install deps (once)
-pip install iris-vector-graph[full]
+pip install "iris-vector-graph[full]"
 
 # 3. Start demo server
 python -m uvicorn iris_demo_server.app:app --port 8200 --host 127.0.0.1 \
@@ -136,7 +138,7 @@ python -m uvicorn iris_demo_server.app:app --port 8200 --host 127.0.0.1 \
 open http://localhost:8200
 ```
 
-The demos use the generic IVG graph engine — no separate backend required. All data is created by the demo on first run.
+The demos use the generic IVG graph engine — no separate backend required.
 
 ---
 
@@ -731,6 +733,26 @@ conditions = tool("patient-123")  # → {"conditions": [...], "error": None}
 
  ## Changelog
 
+### v1.98.0 (2026-05-28)
+- **feat**: Spec 162 — Centrality Suite. Four new graph centrality algorithms shipping via the GraphStore protocol + Cypher procedures, closing the biggest coverage gap vs Neo4j GDS:
+  - `engine.degree_centrality(direction, predicate, top_k)` — out/in/both, predicate-filtered, normalized to (n-1)
+  - `engine.betweenness_centrality(sample_size, direction, max_hops, top_k, mem_budget_mb, progress_callback)` — Brandes (2001), Brandes-Pich approximation when sampled, per-source memory budget, progress reporting
+  - `engine.closeness_centrality(formula, direction, max_hops, top_k, progress_callback)` — `harmonic` (default, robust to disconnection) and `classical` formulas
+  - `engine.eigenvector_centrality(max_iter, tol, top_k, progress_callback)` — power iteration over raw adjacency `A`, L2-normalized, matches `networkx.eigenvector_centrality_numpy` (NOT PageRank with α=1)
+- **feat**: 4 Cypher procedures `CALL ivg.degreeCentrality({...}) YIELD node, score, degree`, `CALL ivg.betweenness({...}) YIELD node, score`, `CALL ivg.closeness({...})`, `CALL ivg.eigenvector({...})` with map-parameter syntax. Procedure-call validator rejects unknown keys (FR-029 forward-compat reservation for future `weighted` variants).
+- **feat**: `engine.get_centrality_warnings()` reads `^IVG.warnings("centrality", ...)` for memory-budget skip events; Brandes writes warning entries when per-source predecessor accumulator exceeds `mem_budget_mb`.
+- **feat**: 4 new `GraphStore` protocol methods (`execute_degree_centrality`, `execute_betweenness`, `execute_closeness`, `execute_eigenvector`) + 4 capability keys.
+- **feat**: 4 new Pydantic input models exported from package root: `DegreeCentralityInput`, `BetweennessInput`, `ClosenessInput`, `EigenvectorInput`.
+- **feat**: `scripts/test-container.sh` — single entry point for IRIS test container ops (replaces ad-hoc `IRISContainer.start()` calls). Includes graceful `iris stop IRIS quietly` before `docker rm -f` (Bug T mitigation).
+- **feat**: Container renamed from legacy `gqs-ivg-test` (ephemeral) to `ivg-iris` (persistent, registered in lab_manager registry as `status: active`).
+- **fix (Bug S)**: Native API gref-bypass production path for centrality algorithms — when `iris.createIRIS().classMethodValue('Graph.KG.Centrality', ...)` returns `<CLASS DOES NOT EXIST>` from `%SYS.DBSRV` cache, the Python store automatically falls back to direct `^KG` global access via `iris_inst.set/get/nextSubscript/kill`. Algorithm correctness proven via Pearson > 0.85 with networkx reference on `networkx.betweenness_centrality`, `harmonic_centrality`, `eigenvector_centrality_numpy`, `out_degree_centrality`.
+- **fix (Bug T)**: `iris-devtester>=1.18.1` upstream fix — `IRISContainer.__exit__()` now calls `stop_gracefully()` (graceful `iris stop IRIS quietly`) before Docker SIGKILL, preventing silent row loss on container restart. IVG bumped pin to `iris-devtester>=1.18.1`.
+- **fix (Bug R, false alarm)**: Investigation confirmed `los-iris` slowness from unindexed `rdf_labels.s`/`rdf_props.s` was specific to productivity-framework's container schema; IVG's `initialize_schema()` already creates `idx_labels_s` and `idx_props_s`. No IVG fix needed.
+- **test**: 16 new e2e tests in `tests/e2e/test_centrality_e2e.py` — networkx parity master gate + per-algorithm validation (15 PASS + 1 XFAIL Bug S Cypher path, deeply documented).
+- **test**: 30 new unit tests in `tests/unit/test_centrality_unit.py` and `tests/unit/test_centrality_translator.py` — protocol routing, Pydantic validation, Cypher translator FR-029 enforcement.
+- **docs**: `specs/162-centrality-suite/{spec,plan,research,data-model,quickstart,tasks}.md` — full spec with 5 clarifications integrated, 29 functional requirements, 6 NFRs, 10 user stories.
+- **docs**: `ENGINEERING_DEBT.md` Bug S + Bug T entries with reproduction steps and resolution context.
+
 ### v1.88.0 (2026-05-07)
 - **feat**: `ffi_kg_build_2hop_exact_int` Rust function — integer-indexed single-pass 2-hop dedup from `^KG("out")`. Writes results to `^ArnoKG("2h")` temp global; `DecodeBuildResults()` ObjectScript method converts to `^KG("deg2p_exact")`
 - **feat**: `KHop2CountExact(src, pred)` ObjectScript method — O(1) `$Get(^KG("deg2p_exact"))`, fallback to `KHop2Count` when not populated. 0.14ms p50 on SF10 (was 70ms)
@@ -1180,6 +1202,109 @@ Four openCypher gaps closed, all from structured gap analysis against the openCy
 
 ## Changelog
 
+### v1.97.0 (2026-05-16)
+
+**Three new features closing the gap with NornicDB-style vector-graph fusion:**
+
+**`CALL ivg.retrieve(query, limit, bm25_name?, vec_label?, rrf_k?)`** — single Cypher procedure for BM25 + vector + RRF fusion. Equivalent to NornicDB's `db.retrieve()`:
+```cypher
+CALL ivg.retrieve('insulin resistance', 10) YIELD node, score
+MATCH (node)-[:INTERACTS_WITH]->(target)
+RETURN target.node_id, score ORDER BY score DESC
+```
+Generates three-CTE SQL (BM25_Retrieve + Vec_Retrieve + Retrieve with FULL OUTER JOIN RRF fusion).
+
+**`WHERE vector_distance(n, $vec) < 0.3`** — scalar vector similarity predicate in WHERE/RETURN clauses:
+```cypher
+MATCH (n:Gene) WHERE vector_distance(n, $vec) < 0.3 RETURN n.node_id
+MATCH (n) RETURN n.node_id, vector_similarity(n, $vec) AS sim ORDER BY sim DESC LIMIT 10
+```
+Translates to `VECTOR_COSINE()` subquery against `kg_NodeEmbeddings`.
+
+**`Graph.KG.EmbedQueue`** — async embedding queue (ObjectScript). Write nodes now, embeddings appear asynchronously:
+```python
+engine.enqueue_for_embedding(["n1", "n2", "n3"], embedding_config="my-model")
+engine.start_background_embedding(batch_size=100)
+count = engine.embed_queue_pending()
+result = engine.process_embed_queue(batch_size=50)
+```
+Uses `^EmbedQueue` global + `Graph.KG.EmbedQueue.ProcessBatch()` via `%SYSTEM.Task`.
+
+### v1.96.2 (2026-05-15)
+
+**Fix**: `_build_index_registry()` infinite loop when `iris.gref` is a `MagicMock` (external connections via IVR or test mocks). `gref.order()` on a MagicMock returns a MagicMock, which is never `== ""`, causing infinite loop. Fix: `isinstance(name, str)` guard + `range(10000)` hard limit. Reported by IVR session.
+
+### v1.96.1 (2026-05-15)
+
+**Fix**: Lazy-load `sentence-transformers` and `torch` to prevent repeated memory allocation. Inline `from sentence_transformers import SentenceTransformer` in `embed_text()`, `embed_nodes()`, `embed_edges()` replaced with module-level singletons (`_get_sentence_transformers()`, `_load_sentence_transformer()`). Prevents torch reference counting from blocking GC between embedding batches.
+
+### v1.96.0 (2026-05-15)
+
+**IVG SDK, CLI, Deploy, and iris-embedded-python-wrapper adoption** (spec 160):
+
+**`iris_vector_graph.sdk`** — new thin HTTP client, zero `intersystems-irispython` required:
+```python
+from iris_vector_graph import IVGClient
+with IVGClient("http://localhost:8200", api_key="...") as client:
+    result = client.execute_cypher("MATCH (n) RETURN count(n)")
+    result = client.execute_aql("FOR v IN 1..2 OUTBOUND @s g RETURN v._key", bind_vars={"s": "n1"})
+```
+- `IVGRecord` — dict-style row access: `r["name"]` and `r[0]` both work
+- `IVGError` / `IVGClientError` / `IVGServerError` — structured exception hierarchy
+- `AsyncIVGClient` — identical async API
+- Retry on 5xx (3× exponential backoff)
+- `ping()`, `schema()`, `server_info()`, `stats()`, `explain()`, `load_ndjson()`
+
+**`ivg` CLI** — `pip install "iris-vector-graph[cli]"`:
+```bash
+ivg connect http://localhost:8200
+ivg query "MATCH (n) RETURN count(n)"
+ivg query --aql "FOR v IN 1..2 OUTBOUND @s g RETURN v" --bind s=mesh:D003924
+ivg load graph.ndjson
+ivg schema init / status
+ivg indexes list / rebuild
+ivg server start --iris-host localhost --iris-port 1972
+```
+
+**`deploy/`** folder — four setup paths:
+- `deploy/docker/compose.yml` — fresh IRIS + IVG server in Docker
+- `deploy/bolt-on/install.sh` — bolt onto existing IRIS
+- `deploy/README.md` — decision guide
+
+**`iris-embedded-python-wrapper` adoption**:
+- `IRISGraphEngine.from_wrapper(hostname=...)` — new classmethod using `iris.dbapi.connect()`
+- `cypher_api.py` `_make_engine()` prefers wrapper's `iris.dbapi.connect()` when available
+- `iris-embedded-python-wrapper>=0.5.20` added to `[full]` extra
+- `EmbeddedConnection` retained for backward compatibility
+
+### v1.95.0 (2026-05-15)
+
+**Admin API** — IVG now has a production-grade admin surface matching Neo4j/ArangoDB:
+
+**Fixed: `SHOW INDEXES` / `SHOW CONSTRAINTS`** — were empty stubs; now return actual BM25, IVF, HNSW, PLAID, ^KG, ^NKG indexes and uniqueness constraints. Neo4j Browser, LangChain, and all Neo4j-compatible tools now see the real index state on connect.
+
+**New REST endpoints on the Cypher API:**
+- `GET /schema` — labels, relationship types, property keys, counts
+- `GET /indexes` — full index inventory (all types)
+- `GET /server` — IVG version, IRIS version, namespace, schema status, BFS path
+- `GET /metrics` — Prometheus-format metrics (node/edge/embedding counts, status)
+- `GET /stats` — counts by label, predicate, embedding coverage
+- `POST /admin/schema/init` — initialize schema
+- `POST /admin/indexes/rebuild` — rebuild ^KG and ^NKG adjacency indexes
+- `POST /admin/embed` — trigger node embedding
+- `POST /admin/load` — stream NDJSON graph data
+- `GET /admin/export` — export graph as NDJSON
+- `POST /admin/snapshot` — save snapshot to disk
+- `GET /admin/queries` — list active IRIS queries
+- `DELETE /admin/queries/{id}` — kill a running query
+- `POST /admin/explain` — translate Cypher to SQL (debugging + optimization)
+
+**GraphStore protocol additions** (6 new methods):
+`get_node_count()`, `get_edge_count()`, `get_labels()`, `get_relationship_types()`, `list_indexes()`, `server_info()`
+
+**Engine additions:**
+`engine.list_active_queries()`, `engine.kill_query(id)`
+
 ### v1.94.0 (2026-05-15)
 
 **GraphStore Protocol** — `IRISGraphEngine` now has a pluggable storage backend (spec 156).

iris_vector_graph-1.98.0/iris_src/src/Graph/KG/Centrality.cls

@@ -0,0 +1,154 @@
+/// Centrality algorithms for the Knowledge Graph.
+/// Pure ObjectScript over ^KG globals — no iris module dependency, safe from any call context.
+///
+/// Algorithms (spec 162):
+///   - DegreeCentralityJson    — out/in/total-degree centrality, normalized to (n-1)
+///   - BetweennessJson         — Brandes' algorithm with optional sampling and memory budget
+///   - ClosenessJson           — harmonic (default) or classical formula
+///   - EigenvectorJson         — power iteration over raw adjacency A (NOT PageRank with α=1)
+///
+/// Storage (read-only):
+///   ^KG("out", 0, s, p, o)   outbound edges (shard-0)
+///   ^KG("in",  0, o, p, s)   inbound edges (shard-0)
+///   ^KG("deg", node)         total out-degree
+///   ^KG("degp", node, pred)  per-predicate out-degree
+///
+/// Process-private scratch (killed on exit):
+///   ^||CENT(-score, node)    descending sort buffer (shared across algos)
+///   ^||BC.*                  Brandes per-source accumulators (Betweenness only)
+///   ^||CL.*                  Closeness accumulators
+///   ^||EIG.*                 Eigenvector x and xnew vectors
+///
+/// Durable warning log:
+///   ^IVG.warnings("centrality", $H, source) = "BC mem budget exceeded ..."
+///
+/// Concurrency contract:
+///   Reads ^KG live — no snapshot, no lock. Concurrent mutations during a multi-second
+///   run may produce inconsistent scores. Run on a quiescent graph for reproducibility.
+///   Matches Neo4j GDS contract (FR-021).
+Class Graph.KG.Centrality Extends %RegisteredObject [ SqlSchemaName = Graph_KG ]
+{
+
+/// Degree Centrality, normalized to (n-1).
+///
+/// @param direction  "out" (default) | "in" | "both"
+/// @param predicate  Empty string = all predicates; otherwise filter to one predicate
+/// @param topK       Max rows to return (default 10000; 0 = uncapped)
+/// @returns JSON array: [{"id":"node","score":0.42,"degree":17}, ...] sorted desc by score
+ClassMethod DegreeCentralityJson(direction As %String = "out", predicate As %String = "", topK As %Integer = 10000) As %String
+{
+    // Count nodes for normalization
+    Set nodeCount = 0
+    Set node = ""
+    For {
+        Set node = $Order(^KG("deg", node))
+        Quit:node=""
+        Set nodeCount = nodeCount + 1
+    }
+    If nodeCount = 0 Return "[]"
+    Set norm = 1.0 / $Select(nodeCount > 1: nodeCount - 1, 1: 1)
+    
+    Kill ^||CENT
+    
+    // Compute degree for each node based on direction + predicate
+    Set node = ""
+    For {
+        Set node = $Order(^KG("deg", node))
+        Quit:node=""
+        
+        Set deg = 0
+        If predicate = "" {
+            // All predicates
+            If direction = "out" {
+                Set deg = +$Get(^KG("deg", node))
+            } ElseIf direction = "in" {
+                // Walk ^KG("in", 0, node, p, s) and count
+                Set p = ""
+                For {
+                    Set p = $Order(^KG("in", 0, node, p))
+                    Quit:p=""
+                    Set s = ""
+                    For {
+                        Set s = $Order(^KG("in", 0, node, p, s))
+                        Quit:s=""
+                        Set deg = deg + 1
+                    }
+                }
+            } Else {
+                // both = out + in
+                Set deg = +$Get(^KG("deg", node))
+                Set p = ""
+                For {
+                    Set p = $Order(^KG("in", 0, node, p))
+                    Quit:p=""
+                    Set s = ""
+                    For {
+                        Set s = $Order(^KG("in", 0, node, p, s))
+                        Quit:s=""
+                        Set deg = deg + 1
+                    }
+                }
+            }
+        } Else {
+            // Specific predicate
+            If direction = "out" {
+                Set deg = +$Get(^KG("degp", node, predicate))
+            } ElseIf direction = "in" {
+                // Walk ^KG("in", 0, node, predicate, *)
+                Set s = ""
+                For {
+                    Set s = $Order(^KG("in", 0, node, predicate, s))
+                    Quit:s=""
+                    Set deg = deg + 1
+                }
+            } Else {
+                Set deg = +$Get(^KG("degp", node, predicate))
+                Set s = ""
+                For {
+                    Set s = $Order(^KG("in", 0, node, predicate, s))
+                    Quit:s=""
+                    Set deg = deg + 1
+                }
+            }
+        }
+        
+        Set score = deg * norm
+        // Use negative score for descending $Order
+        Set ^||CENT(-score, node) = deg
+    }
+    
+    // Build JSON result array (top-K)
+    Set result = ##class(%DynamicArray).%New()
+    Set negScore = ""
+    Set count = 0
+    Set cap = $Select(topK > 0: topK, 1: 999999999)
+    For {
+        Set negScore = $Order(^||CENT(negScore))
+        Quit:negScore=""
+        Set n = ""
+        For {
+            Set n = $Order(^||CENT(negScore, n), 1, deg)
+            Quit:n=""
+            Set obj = ##class(%DynamicObject).%New()
+            Do obj.%Set("id", n)
+            Do obj.%Set("score", -negScore, "number")
+            Do obj.%Set("degree", deg, "number")
+            Do result.%Push(obj)
+            Set count = count + 1
+            Quit:count>=cap
+        }
+        Quit:count>=cap
+    }
+    
+    Kill ^||CENT
+    Return result.%ToJSON()
+}
+
+/// SQL stored procedure wrapper for DegreeCentralityJson.
+/// Used by the Cypher translator's ivg.degreeCentrality CTE.
+ClassMethod kgDegreeCentrality(direction As %String, predicate As %String, topK As %Integer) As %String [ SqlName = kg_DegreeCentrality, SqlProc ]
+{
+    Return ..DegreeCentralityJson(direction, predicate, topK)
+}
+
+}

{iris_vector_graph-1.94.0 → iris_vector_graph-1.98.0}/iris_src/src/Graph/KG/EdgeScan.cls

@@ -97,10 +97,8 @@ ClassMethod DeleteAdjacency(s As %String, p As %String, o As %String)
 }
 
 
-/// Bulk ingest edges directly to ^KG globals via embedded Python.
-/// 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.
+/// DEPRECATED: writes to process-private ^||KG via Python iris.gref — data lost on process exit.
+/// Use BulkIngestEdgesSQL instead. Kept for backward compatibility only.
 ClassMethod BulkIngestEdges(edgesJson As %String, predicate As %String = "R") As %Integer [ Internal, Language = python ]
 {
     import iris, json, warnings
@@ -124,4 +122,88 @@ ClassMethod BulkIngestEdges(edgesJson As %String, predicate As %String = "R") As
     return n
 }
 
+/// Bulk ingest edges via SQL INSERT + persistent ^KG global writes.
+/// Writes to BOTH rdf_edges (SQL, queryable via Cypher) AND ^KG globals (BFS acceleration).
+/// edges_json: JSON array of {"s":s,"p":p,"o":o} objects.
+/// Returns count of edges written.
+ClassMethod BulkIngestEdgesSQL(edgesJson As %String, predicate As %String = "KNOWS") As %Integer
+{
+	Set data = {}.%FromJSON(edgesJson)
+	Set n = 0
+	TSTART
+	Set iter = data.%GetIterator()
+	While iter.%GetNext(.idx, .edge) {
+		Set s = edge.s
+		Set p = $Select(edge.p'="":edge.p, 1:predicate)
+		Set o = edge.o
+		If (s = "") || (o = "") { Continue }
+		If s = o { Continue }
+		&sql(INSERT INTO Graph_KG.rdf_edges (s, p, o_id) VALUES (:s, :p, :o))
+		If (SQLCODE '= 0) && (SQLCODE '= -119) { Continue }
+		Do ..WriteAdjacency(s, p, o, "1.0")
+		Set n = n + 1
+	}
+	TCOMMIT
+	Quit n
+}
+
+/// Bulk ingest edges from a JSON file path — streams large datasets without MAXSTRING limit.
+ClassMethod BulkIngestEdgesFile(filePath As %String, predicate As %String = "KNOWS") As %Integer
+{
+	Set stream = ##class(%Stream.FileCharacter).%New()
+	Do stream.LinkToFile(filePath)
+	Set json = ""
+	While 'stream.AtEnd {
+		Set json = json _ stream.Read(32000)
+	}
+	Quit ..BulkIngestEdgesSQL(json, predicate)
+}
+
+/// Bulk ingest nodes + labels + properties via batched SQL.
+/// nodesJson: JSON array of {"id":id, "labels":["L1",...], "props":{"k":"v",...}} objects.
+/// Returns count of nodes written.
+ClassMethod BulkIngestNodesSQL(nodesJson As %String) As %Integer
+{
+	Set data = {}.%FromJSON(nodesJson)
+	Set n = 0
+	TSTART
+	Set iter = data.%GetIterator()
+	While iter.%GetNext(.idx, .node) {
+		Set id = node.id
+		If id = "" { Continue }
+		&sql(INSERT INTO Graph_KG.nodes (node_id) VALUES (:id))
+		If (SQLCODE '= 0) && (SQLCODE '= -119) { Continue }
+		If $IsObject(node.labels) {
+			Set liter = node.labels.%GetIterator()
+			While liter.%GetNext(.li, .label) {
+				If label = "" { Continue }
+				&sql(INSERT INTO Graph_KG.rdf_labels (s, label) VALUES (:id, :label))
+			}
+		}
+		If $IsObject(node.props) {
+			Set piter = node.props.%GetIterator()
+			While piter.%GetNext(.key, .val) {
+				If key = "" { Continue }
+				Try {
+					Set valStr = $Select($IsObject(val):val.%ToJSON(), $IsValidNum(val):val, 1:""""_$Replace($ZConvert(val,"O","UTF8"),"""","""""")_"""")
+					&sql(INSERT INTO Graph_KG.rdf_props (s, "key", val) VALUES (:id, :key, :valStr))
+				} Catch ex { }
+			}
+		}
+		Set n = n + 1
+	}
+		}
+		If $IsObject(node.props) {
+			Set piter = node.props.%GetIterator()
+			While piter.%GetNext(.key, .val) {
+				If key = "" { Continue }
+				Set valStr = $Select($IsObject(val):val.%ToJSON(), 1:""""_$Replace(val,"""","""""")_"""")
+				&sql(INSERT INTO Graph_KG.rdf_props (s, "key", val) VALUES (:id, :key, :valStr))
+			}
+		}
+		Set n = n + 1
+	}	TCOMMIT
+	Quit n
+}
+
 }