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

{iris_vector_graph-1.99.3 → iris_vector_graph-2.0.0}/.gitignore

@@ -167,3 +167,4 @@ docker-compose.yaml
 .playwright-mcp/
 examples/expanded_mindwalk_KG_10000.*
 .sesskey
+data/drkg/

{iris_vector_graph-1.99.3 → iris_vector_graph-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris-vector-graph
-Version: 1.99.3
+Version: 2.0.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,9 @@ 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'
@@ -146,11 +149,28 @@ print(result["rows"])  # [('Bob',)]
 ## Install
 
 ```bash
-pip install iris-vector-graph              # Core: just intersystems-irispython
+pip install iris-vector-graph              # Core: 266KB — just intersystems-irispython
 pip install iris-vector-graph[full]        # Full: + FastAPI, GraphQL, numpy, networkx
+pip install iris-vector-graph[communities] # + igraph, leidenalg (fast Leiden + closeness)
 pip install iris-vector-graph[plaid]       # + sklearn for PLAID K-means build
 ```
 
+**Graph Browser** (interactive UI at `/browser/`) — the browser static files are not
+included in the default wheel to keep it small (266KB vs 30MB). To enable the browser:
+
+```bash
+# Install from source — includes browser_static/ automatically
+pip install 'iris-vector-graph[browser]' --no-binary iris-vector-graph
+
+# Or: clone the repo and copy the assets next to your installed package
+git clone https://github.com/intersystems-community/iris-vector-graph
+cp -r iris-vector-graph/iris_vector_graph/browser_static \
+      $(python -c "import iris_vector_graph; print(iris_vector_graph.__file__[:-11])")
+```
+
+The API server works fine without the browser assets — the `/browser/` route returns
+a helpful message if `browser_static/` is not present.
+
 ### ObjectScript Only (IPM)
 
 ```
@@ -179,7 +199,7 @@ Pure ObjectScript — VecIndex, PLAIDSearch, PageRank, Subgraph, GraphIndex, Tem
 | **GraphQL** | Auto-generated schema from knowledge graph labels. |
 | **Embedded Python** | `EmbeddedConnection` — zero-boilerplate dbapi2 adapter for IRIS Language=python methods. |
 | **Multi-graph** | `USE graphname` maps to IRIS namespace/schema switching via `set_schema_prefix()`. |
-| **NKGAccel** | Rust-accelerated BFS via `Graph.KG.NKGAccel` — requires enterprise IRIS + `libarno_callout.so`. |
+| **NKGAccel** | Rust-accelerated BFS via `Graph.KG.NKGAccel` — requires the native accelerator library. |
 
 ## Compliance
 
@@ -258,7 +278,7 @@ IRIS_USERNAME=_SYSTEM IRIS_PASSWORD=SYS \
 python3 -m uvicorn iris_vector_graph.cypher_api:app --port 8000
 ```
 
-- **Browser** — `http://localhost:8000/browser/` (force-directed graph visualization)
+- **Browser** — `http://localhost:8000/browser/` (force-directed graph visualization — requires browser assets, see [Install](#install))
 - **Bolt TCP** — `bolt://localhost:7687` (Python/Java/Go/.NET drivers, LangChain, cypher-shell)
 - **HTTP API** — `http://localhost:8000/api/cypher` (curl, httpie, REST clients)
 
@@ -542,7 +562,7 @@ SQL Tables  (probe: 23ms)
   ...
 Adjacency Globals
   ✓ ^KG   (50,000 source nodes indexed)
-  ✗ ^NKG  (Arno integer index)
+  ✗ ^NKG  (integer adjacency index for Rust acceleration)
 ...
 ```
 
@@ -567,20 +587,20 @@ results = engine.plaid_search("colbert_idx", query_tokens, k=10)
 
 Finds the minimum-**cost** path between two nodes using Dijkstra's algorithm. Unlike `shortestPath()` which minimizes hops, this minimizes the sum of edge weights.
 
-Edge weights come from the numeric value stored in `^KG("out",0,s,p,o)` — set automatically when you call `create_edge` or `WriteAdjacency` with a weight parameter.
+Edge weights are set via the `weight` parameter on `create_edge` (or updated later with `set_edge_weight`).
 
 ```python
 # Store weighted edges
 engine.create_node("svc:auth")
 engine.create_node("svc:db")
-iris_obj = engine._iris_obj()
-iris_obj.classMethodVoid("Graph.KG.EdgeScan", "WriteAdjacency",
-    "svc:auth", "CALLS", "svc:db", "5.2")  # weight=5.2ms latency
-
-iris_obj.classMethodVoid("Graph.KG.EdgeScan", "WriteAdjacency",
-    "svc:auth", "CALLS", "svc:cache", "0.3")
-iris_obj.classMethodVoid("Graph.KG.EdgeScan", "WriteAdjacency",
-    "svc:cache", "CALLS", "svc:db", "0.8")
+engine.create_node("svc:cache")
+
+engine.create_edge("svc:auth", "CALLS", "svc:db", weight=5.2)    # 5.2ms latency
+engine.create_edge("svc:auth", "CALLS", "svc:cache", weight=0.3)
+engine.create_edge("svc:cache", "CALLS", "svc:db", weight=0.8)
+
+# Update a weight later
+engine.set_edge_weight("svc:auth", "CALLS", "svc:db", 4.9)
 ```
 
 ```cypher
@@ -685,27 +705,169 @@ RETURN node, score
 
 ## Graph Analytics
 
+IVG ships a full graph algorithm suite backed by automatic dispatch chains — the fastest available tier runs transparently.
+
+#### Betweenness dispatch (ER-2000, sampled 200 sources)
+
+| Tier | Backend | When it fires | Latency |
+|------|---------|---------------|---------|
+| 1 | **Native Rust accelerator** | arno library deployed + `^NKG` built | ~8ms |
+| 2 | **ObjectScript Brandes** | arno absent; `^NKG` built | ~70ms |
+| 3 | **Python LazyKG** | `^NKG` not built | slow, always works |
+
+#### Closeness dispatch (ER-2000, harmonic)
+
+| Tier | Backend | When it fires | Latency |
+|------|---------|---------------|---------|
+| 1 | **igraph C closeness** | igraph installed in IRIS embedded Python | ~115ms |
+| 2 | **ObjectScript MSBFS** | igraph absent; dependency-free 64-bit frontier BFS | ~400ms |
+| 3 | **Python LazyKG** | fallback of last resort | slow, always works |
+
+igraph closeness is **bit-identical to networkx** (Pearson r = 1.0). Install into IRIS embedded Python with `irispython -m pip install igraph` — see [scripts/install-embedded-deps.sh](scripts/install-embedded-deps.sh).
+
+#### Leiden dispatch
+
+| Tier | Backend | When it fires | Latency (ER-2000) |
+|------|---------|---------------|---------|
+| 1 | **arno Rust** | arno library + leidenalg compiled | ~8ms |
+| 2 | **leidenalg server-side** | leidenalg installed in IRIS embedded Python | ~137ms |
+| 3 | **LazyKG + leidenalg** | leidenalg in external Python | ~137ms |
+| 4 | **networkx Louvain** | no leidenalg anywhere | degraded quality |
+
+Dispatch is **automatic and transparent** — call the engine method, get the fastest path available.
+
+### Centrality (v1.98.0 + v2.0.0)
+
 ```python
-from iris_vector_graph.operators import IRISGraphOperators
+# Degree centrality — out/in/both, optionally predicate-filtered
+scores = engine.degree_centrality(direction="out", top_k=20)
+# → [{"id": "auth-service", "score": 0.847, "degree": 12}, ...]
+
+# Betweenness centrality — Brandes (2001), Rust parallel when accelerator loaded
+# sample_size=200: Brandes-Pich approximation (fast, good ranking)
+# sample_size=0:   exact full Brandes (slower, ground truth)
+scores = engine.betweenness_centrality(sample_size=200, top_k=20)
+# → [{"id": "api-gateway", "score": 4821.3}, ...]
+
+# Neighborhood betweenness — O(neighborhood), not O(graph)
+# Scales to any total graph size; performance depends on hops neighborhood only
+scores = engine.betweenness_centrality_neighborhood(
+    seed="MESH:D009101",   # Multiple Myeloma (or any node ID)
+    hops=2,                # 2-hop neighborhood: ~500-5K nodes for biomedical KGs
+    sample_size=200,
+    top_k=20,
+)
+# → [{"id": "TP53", "score": 1234.5}, ...]   (hub bottlenecks in disease neighborhood)
+
+# Closeness centrality — harmonic (default) or classical
+scores = engine.closeness_centrality(formula="harmonic", top_k=20)
+# formula="classical": standard Bavelas–Freeman, undefined for disconnected graphs
+# formula="harmonic":  Beauchamp (1965), well-defined for disconnected graphs
+
+# Eigenvector centrality — power iteration, L2-normalized
+scores = engine.eigenvector_centrality(max_iter=50, tol=1e-6, top_k=20)
+# matches networkx.eigenvector_centrality_numpy (raw adjacency A, not transition matrix)
+```
+
+**Via Cypher:**
+
+```cypher
+CALL ivg.degreeCentrality({direction: "out", topK: 20})
+  YIELD node, score, degree
+
+CALL ivg.betweenness({sampleSize: 200, topK: 20})
+  YIELD node, score
+
+CALL ivg.closeness({formula: "harmonic", topK: 20})
+  YIELD node, score
+
+CALL ivg.eigenvector({maxIter: 50, topK: 20})
+  YIELD node, score
+```
+
+---
+
+### Community Detection (v1.99.0)
+
+```python
+# Leiden community detection (Traag et al. 2019)
+# gamma=1.0: ModularityVertexPartition (canonical Leiden, default)
+# gamma != 1.0: CPMVertexPartition (resolution parameter, smaller communities)
+communities = engine.leiden_communities(gamma=1.0, top_k=100)
+# → [{"id": "node-a", "community": 0, "size": 23}, ...]
+
+# Triangle count + local clustering coefficient
+triangles = engine.triangle_count(top_k=100)
+# → [{"id": "hub-node", "triangles": 45, "lcc": 0.73}, ...]
+
+# Strongly connected components (iterative Tarjan 1972)
+sccs = engine.strongly_connected_components(top_k=100)
+# → [{"id": "node-a", "component": 0, "size": 8}, ...]
+
+# K-core decomposition (Batagelj-Zaversnik 2003, O(V+E))
+cores = engine.k_core_decomposition(top_k=100)
+# → [{"id": "dense-hub", "coreness": 5}, ...]
+```
+
+**Via Cypher:**
+
+```cypher
+CALL ivg.leiden({gamma: 1.0, topK: 100})
+  YIELD node, community, size
+
+CALL ivg.triangleCount({topK: 100})
+  YIELD node, triangles, lcc
+
+CALL ivg.scc({topK: 100})
+  YIELD node, component, size
+
+CALL ivg.kcore({topK: 100})
+  YIELD node, coreness
+```
 
-ops = IRISGraphOperators(conn)
+---
+
+### Algorithm Selection Guide
 
-# Personalized PageRank
-scores = ops.kg_PAGERANK(seed_entities=["service:auth"], damping=0.85)
+| Question | Algorithm | Notes |
+|----------|-----------|-------|
+| Who has the most connections? | `degree_centrality` | Fast, O(V+E) |
+| Who controls information flow? | `betweenness_centrality` | Use `sample_size=200` for large graphs |
+| Which disease-network bottlenecks matter? | `betweenness_centrality_neighborhood` | O(neighborhood), not O(graph) |
+| Who reaches others fastest? | `closeness_centrality(formula="harmonic")` | Handles disconnected graphs |
+| Who is most influential by propagation? | `eigenvector_centrality` | Captures network prestige |
+| What are the dense clusters? | `leiden_communities` | Best modularity; use `gamma<1.0` for smaller communities |
+| How tightly connected are nodes? | `triangle_count` | LCC field = local clustering coefficient |
+| Are there feedback loops? | `strongly_connected_components` | Directed-graph cycles |
+| What is the network's backbone? | `k_core_decomposition` | High coreness = structural core |
 
-# K-hop subgraph
-subgraph = ops.kg_SUBGRAPH(seed_ids=["service:auth"], k_hops=3)
+---
 
-# PPR-guided subgraph (prevents k^n blowup)
-guided = ops.kg_PPR_GUIDED_SUBGRAPH(seed_ids=["service:auth"], top_k=50, max_hops=5)
+### Native Accelerator (Rust, Production Performance)
+
+```bash
+# Copy the accelerator library to your IRIS container
+docker cp libarno_callout_arm64_linux.so <container>:/usr/irissys/mgr/libarno_callout.so
 
-# Community detection
-communities = ops.kg_CDLP()
-components  = ops.kg_WCC()
+# Load it at IRIS startup (e.g., in %ZSTART or your application init)
+Do ##class(Graph.KG.NKGAccel).Load("/usr/irissys/mgr/libarno_callout.so")
+```
+
+Without the accelerator, all algorithms fall back gracefully to the ObjectScript parallel (Tier 2) or Python LazyKG (Tier 3) path. See [docs/performance/GRAPH_ALGORITHMS.md](docs/performance/GRAPH_ALGORITHMS.md) for tier latencies.
+
+Algorithms that operate under memory budgets emit warnings to `^IVG.warnings`:
+
+```python
+# Check if any nodes were skipped due to memory budget
+warnings = engine.get_community_warnings(max_entries=50)
+warnings += engine.get_centrality_warnings(max_entries=50)
+for w in warnings:
+    print(w)  # {"node_id": "...", "reason": "mem_budget_exceeded", ...}
 ```
 
 ---
 
+
 ## FHIR Bridge
 
 ```python
@@ -738,85 +900,175 @@ conditions = tool("patient-123")  # → {"conditions": [...], "error": None}
 
 ## Architecture
 
-### Global Structure
-
-| Global | Purpose |
-|--------|---------|
-| `^KG("out", s, p, o)` | Knowledge graph — outbound edges |
-| `^KG("in", o, p, s)` | Knowledge graph — inbound edges |
-| `^KG("tout", ts, s, p, o)` | Temporal index — outbound, ordered by timestamp |
-| `^KG("tin", ts, o, p, s)` | Temporal index — inbound, ordered by timestamp |
-| `^KG("bucket", bucket, s)` | Pre-aggregated edge count per 5-minute bucket |
-| `^KG("tagg", bucket, s, p, key)` | Pre-aggregated COUNT/SUM/MIN/MAX/HLL per bucket |
-| `^KG("edgeprop", ts, s, p, o, key)` | Rich edge attributes |
-| `^NKG` | Integer-encoded `^KG` for Arno acceleration |
-| `^VecIdx` | VecIndex RP-tree ANN |
-| `^PLAID` | PLAID multi-vector |
-| `^BM25Idx` | BM25 lexical search index |
-
-### Schema (Graph_KG)
-
-| Table | Purpose |
-|-------|---------|
-| `nodes` | Node registry (node_id PK) |
-| `rdf_edges` | Edges (s, p, o_id) |
-| `rdf_labels` | Node labels (s, label) |
-| `rdf_props` | Node properties (s, key, val) |
-| `kg_NodeEmbeddings` | HNSW vector index (id, emb VECTOR) |
-| `kg_EdgeEmbeddings` | Triple embeddings (s, p, o_id, emb VECTOR) — composite PK |
-| `fhir_bridges` | ICD-10→MeSH clinical code mappings |
-
-### ObjectScript Classes
-
-| Class | Key Methods |
-|-------|-------------|
-| `Graph.KG.TemporalIndex` | InsertEdge, BulkInsert, QueryWindow, GetVelocity, FindBursts, GetAggregate, GetBucketGroups, GetDistinctCount, Purge |
-| `Graph.KG.VecIndex` | Create, InsertJSON, Build, SearchJSON, SearchMultiJSON, InsertBatchJSON |
-| `Graph.KG.PLAIDSearch` | StoreCentroids, BuildInvertedIndex, Search |
-| `Graph.KG.PageRank` | RunJson, PageRankGlobalJson |
-| `Graph.KG.Algorithms` | WCCJson, CDLPJson |
-| `Graph.KG.Subgraph` | SubgraphJson, PPRGuidedJson |
-| `Graph.KG.Traversal` | BuildKG, BuildNKG, BFSFastJson, ShortestPathJson |
-| `Graph.KG.BulkLoader` | BulkLoad (`INSERT %NOINDEX %NOCHECK` + `%BuildIndices`) |
-| `Graph.KG.BM25Index` | Build, Search, Insert, Drop, Info, SearchProc (`kg_BM25` stored procedure) |
-| `Graph.KG.IVFIndex` | Build, Search, Drop, Info, SearchProc (`kg_IVF` stored procedure) |
-| `Graph.KG.EdgeScan` | MatchEdges (`Graph_KG.MatchEdges` stored procedure), WriteAdjacency, DeleteAdjacency |
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                    iris-vector-graph  v2.0.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   │
+│                                                                     │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+For global structure, SQL schema, and ObjectScript class reference, see [docs/architecture/ARCHITECTURE.md](docs/architecture/ARCHITECTURE.md).
 
 ---
 
 ## Performance
 
-| Operation | Latency | Dataset |
-|-----------|---------|---------|
-| Temporal edge ingest | 134K edges/sec | RE2-TT 535M edges, Enterprise IRIS |
-| Window query (selective) | 0.1ms | O(results), B-tree traversal |
-| GetAggregate (1 bucket, 5min) | 0.085ms | 50K-edge dataset |
+**Graph traversal & search** (M3 Ultra, Community IRIS 2025.1, 8.9K nodes / 31K edges):
+
+| Operation | Latency | Notes |
+|-----------|---------|-------|
+| 1-hop neighbors | 0.3ms | `$Order` on `^KG` |
+| Temporal window query | 0.1ms | O(results), B-tree |
+| GetAggregate (1 bucket, 5min) | 0.085ms | Pre-aggregated |
 | GetAggregate (288 buckets, 24hr) | 0.160ms | O(buckets), not O(edges) |
-| GetBucketGroups (3 sources, 1hr) | 0.193ms | |
-| GetDistinctCount (1 bucket) | 0.101ms | 16-register HLL |
 | VecIndex search (1K vecs, 128-dim) | 4ms | RP-tree + `$vectorop` SIMD |
 | HNSW search (143K vecs, 768-dim) | 1.7ms | Native IRIS VECTOR index |
 | PLAID search (500 docs, 4 tokens) | ~14ms | Centroid scoring + MaxSim |
-| BM25Index search (174 nodes, 3-term) | 0.3ms | Pure ObjectScript `$Order` posting-list |
+| BM25Index search (174 nodes, 3-term) | 0.3ms | `$Order` posting-list |
 | PPR (10K nodes) | 62ms | Pure ObjectScript |
-| 1-hop neighbors | 0.3ms | `$Order` on `^KG` |
+
+For graph algorithm benchmarks (betweenness, Leiden, centrality vs networkx, tier comparison), see **[docs/performance/GRAPH_ALGORITHMS.md](docs/performance/GRAPH_ALGORITHMS.md)**.
+
+### Comparative performance & scale
+
+IVG has been validated end-to-end on a real biomedical knowledge graph
+([DRKG](https://github.com/gnn4dr/DRKG): ~97K nodes / ~5.9M edges) and compared
+head-to-head against Neo4j Graph Data Science and networkx on shared fixtures.
+
+**Methodology** — same machine, same graphs (Zachary karate club, Erdős–Rényi
+random graphs, and DRKG), same Community-edition core budget for both engines.
+Each engine loads the identical edge set, then runs degree / betweenness /
+closeness centrality and Leiden community detection. Correctness is checked by
+correlating every IVG result against networkx as a reference (results match
+exactly). Timings are wall-clock medians.
+
+**Rough findings** (full numbers in
+[DRKG_SCALE.md](docs/performance/DRKG_SCALE.md)):
+
+- On read-side graph analytics — **degree and betweenness centrality, and Leiden
+  community detection** — IVG is competitive with or faster than Neo4j GDS, while
+  producing identical results to networkx.
+- **Closeness centrality** uses a three-tier dispatch. With igraph installed in
+  IRIS embedded Python: ~10ms on ER(500) and ~115ms on ER(2000), bit-identical
+  to networkx (Pearson r = 1.0), competitive with GDS (~9ms / ~138ms). Without
+  igraph, the second tier is a dependency-free pure-ObjectScript MSBFS (64-source
+  batching, `$BITLOGIC` frontiers) — substantially faster than the old sequential
+  all-pairs BFS while remaining 100% correct (Pearson r ≥ 0.9999 vs networkx).
+  Both tiers degrade gracefully to Python LazyKG as a final fallback.
+- IVG reaches this by running the heavy algorithms server-side: pure-ObjectScript
+  over its integer adjacency index for traversal-style work, and IRIS *embedded
+  Python* (igraph / leidenalg) for the algorithms where a mature parallel C
+  library wins — in-process, with no data leaving the database.
+- At biomedical-KG scale, the full DRKG (5.9M edges) loads, indexes, and becomes
+  query-ready in single-digit minutes, with adjacency maintained incrementally
+  during ingest (no separate post-load build phase).
+
+These are indicative engineering benchmarks on a developer machine, not a
+formal audited comparison; numbers vary with hardware, graph shape, and tuning.
+
+### Running the benchmarks
+
+```bash
+# Algorithm parity vs networkx (no external services needed)
+pytest tests/e2e/test_centrality_e2e.py
+
+# Head-to-head IVG vs Neo4j GDS vs networkx (needs a Neo4j+GDS instance)
+IVG_HEADTOHEAD=1 \
+  NEO4J_URI=bolt://localhost:7687 NEO4J_USER=neo4j NEO4J_PASSWORD=<pw> \
+  pytest tests/perf/test_head_to_head.py -s
+# (the Neo4j leg is skipped automatically if no instance is reachable)
+
+# Biomedical-scale load (downloads DRKG ~217MB, loads into the IRIS container)
+python scripts/load_drkg.py --embeddings
+```
+
+JSON results are written under `benchmarks/`. See
+[DRKG_SCALE.md](docs/performance/DRKG_SCALE.md) for the full methodology, the
+per-metric numbers, and the IRIS tuning notes (global buffer pool, journaling,
+embedded-Python dispatch).
 
 ---
 
 ## Documentation
 
+- [**User Guide**](docs/USER_GUIDE.md) — API reference for developers: algorithms, Cypher, error handling
+- [**Admin Guide**](docs/ADMIN_GUIDE.md) — deployment, container setup, accelerator library, troubleshooting
+- [Architecture Reference](docs/architecture/ARCHITECTURE.md) — globals, SQL schema, ObjectScript classes
+- [Performance Benchmarks](docs/performance/GRAPH_ALGORITHMS.md) — algorithm latency vs networkx
 - [Python SDK Reference](docs/python/PYTHON_SDK.md)
-- [Architecture](docs/architecture/ARCHITECTURE.md)
-- [Schema Reference](docs/architecture/ACTUAL_SCHEMA.md)
-- [Temporal Graph Full Spec](docs/enhancements/006-temporal-property-graph-full-spec.md)
-- [Setup Guide](docs/setup/QUICKSTART.md)
+- [Temporal Graph Spec](docs/enhancements/006-temporal-property-graph-full-spec.md)
 - [Testing Policy](docs/TESTING_POLICY.md)
 
 ---
 
  ## Changelog
 
+### v2.0.0 (2026-05-29)
+
+**Major release: all centrality algorithms accelerated to Rust rayon parallel. New neighborhood betweenness for biomedical KGs.**
+
+**Centrality ObjectScript fast paths (specs 168-170):**
+- **`ClosenessGlobal`** — harmonic/classical closeness via BFS over `^NKG`; matches `networkx.harmonic_centrality` (raw `sumInv`). Fix: was incorrectly dividing by `(n-1)` total container count.
+- **`EigenvectorGlobal`** — L2-normalized power iteration; matches `networkx.eigenvector_centrality_numpy`.
+- **`BetweennessGlobal`** — Brandes (2001) with sampled approximation (`maxSources=200` default) and `%SYSTEM.WorkMgr` 8-way ObjectScript parallelism; `$BITLOGIC` BFS cuts per-source cost 2×.
+
+**Native Rust accelerator: parallel Brandes (spec 171):**
+- Rust function reads adjacency cache once (version-keyed), stores in process-static memory, runs rayon parallel Brandes — zero IRIS I/O on cache hits.
+- Benchmark: karate **6×**, ER(500) **68×**, ER(2000) **5×** faster than networkx on sampled=200.
+- Exact Brandes: karate **4×**, ER(500) **5×** faster than networkx; see [performance doc](docs/performance/GRAPH_ALGORITHMS.md) for full numbers.
+
+**Neighborhood betweenness for biomedical KGs (spec 173):**
+- `engine.betweenness_centrality_neighborhood(seed, hops=2, sample_size=200, top_k=20)` — extracts 2-hop disease neighborhood (~500-5K nodes), runs Brandes on subgraph only. **Performance scales with neighborhood size, not total KG size.** A 10M-node biomedical KG with a 5K-node disease neighborhood runs in ~10ms.
+- Rust implementation extracts subgraph from in-process adjacency cache (microseconds) then runs rayon Brandes on the subgraph. Zero IRIS I/O after first call.
+- Biomedical use case: "Which genes are the bottlenecks between Multiple Myeloma and its known drug targets?"
+
+**Bug fixes:**
+- `<MAXNUMBER>` overflow in ObjectScript Brandes — replaced O(N²) comma-string BFS queue with `^||bfsQueue` global; capped all intermediate arithmetic with `+$Number(expr,15)`.
+- `$Number(x,15)` doesn't cap magnitude (only precision) — added `+` unary prefix to force numeric evaluation before storage.
+- IRIS emits `"score":.666` (no leading zero) for fractional scores — `_fix_iris_json()` regex patches all JSON output before `json.loads()`.
+- Rust accelerator repeated-call 5,000ms regression — `NameSpace::try_new` opened a new CalIn session per call; fixed by version-keyed `BETWEENNESS_ADJ_CACHE` that skips IRIS I/O on cache hits.
+- `ExportAdjacencyNKG` NODEMAP format — now embeds node names in adjacency cache eliminating N round-trips to `^NKG("$ND",i)` per Brandes call (was 997ms → 16ms on ER(500)).
+
 ### v1.99.0 (2026-05-28)
+
 - **feat**: Spec 163 — Community Detection & Cluster Analysis Suite. Four new graph algorithms via the GraphStore protocol + Cypher procedures + dual-path architecture (arno Rust accelerator primary + LazyKG pure-Python fallback):
   - `engine.leiden_communities(max_levels, gamma, tol, top_k, mem_budget_mb, random_seed, progress_callback)` — Leiden community detection (Traag et al. 2019). At `gamma=1.0` uses `ModularityVertexPartition` (canonical Leiden); at `gamma != 1.0` uses `CPMVertexPartition` for resolution control. ARI = 1.0 with `leidenalg` reference (4-way benchmark on karate, ER(500), ER(2000)).
   - `engine.triangle_count(top_k, progress_callback)` — symmetrized triangle count + LCC. Pearson > 0.95 with `networkx.triangles(networkx.Graph(G_directed))` on Erdős-Rényi 100-node fixture.