iris-vector-graph 3.2.0__tar.gz → 4.1.0__tar.gz

iris_vector_graph-4.1.0/.gitignore

@@ -0,0 +1,182 @@
+# Dependencies
+node_modules
+dist
+
+# Environment files — never commit credentials
+.env
+.env.local
+.env.test
+.env.*.local
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Backup files
+*.bak
+*.tmp
+*.orig
+*~
+
+# Archives
+*.zip
+*.tar.gz
+*.tar
+*.rar
+
+# ...except the snapshot archives old releases wrote. These are test fixtures: an
+# upgrade test needs an artifact a previous version actually produced, and that
+# cannot be regenerated once the release is in the past.
+!tests/fixtures/snapshots/*.zip
+
+# Data directories (large test datasets)
+data/
+
+# License files (sensitive)
+*.key
+
+# IDE/Editor files
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Claude configuration
+.claude/
+
+# Test coverage
+coverage/
+coverage*.json
+*,cover
+.nyc_output
+
+# Python cache
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# UV package manager
+.uv/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Python testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# Test results
+test_results.json
+docs/dc_contest_raw.md
+.mcp.json
+
+# Agent-specific config (not project docs)
+CLAUDE.md
+AGENTS.md
+CODEX.md
+TABNINE.md
+DOCS_IRIS_PYTHON_ISSUES.md
+docker-compose.test.yml
+
+# Build artifacts
+dist/
+
+# Benchmark caches
+.benchmarks/
+tests/benchmarks/results/*.json
+.ruff_cache/
+*.crt
+deploy/certs/
+
+# Playwright MCP session artifacts
+.playwright-mcp/
+
+# Screenshot artifacts from development
+browser-*.png
+playwright-*.png
+
+# LDBC benchmark data (large, machine-specific)
+person_knows_person_0_0.csv
+social_network-sf10-*/
+social_network-sf100-*/
+social_network-*/
+
+# Benchmark/profiling outputs
+results/
+outputs/
+benchmarks/results/
+tests/benchmarks/results/*.json
+bench_output.txt
+bench_results.txt
+
+# Internal agent/tool configs (not user-facing)
+CLAUDE.md
+CODEX.md
+TABNINE.md
+DOCS_IRIS_PYTHON_ISSUES.md
+
+# Speckit planning artifacts (internal dev workflow)
+.specify/
+.sisyphus/
+specs/
+
+# Internal audits and pain-point docs
+API_AUDIT.md
+IVG_CONSUMER_PAIN_POINTS.md
+ENGINEERING_DEBT.md
+NEO4J_BENCHMARK_2026.md
+
+# Developer-specific docker-compose variants
+docker-compose.enterprise.yml
+docker-compose.enterprise-2026.yml
+docker-compose.yaml
+
+# Playwright MCP session artifacts
+.playwright-mcp/
+examples/expanded_mindwalk_KG_10000.*
+.sesskey
+data/drkg/
+
+# Throwaway probe scripts and measurement output. Kept out of the tree so a
+# release diff shows only work, not the scaffolding used to verify it.
+scratch/

iris_vector_graph-4.1.0/PKG-INFO

@@ -0,0 +1,490 @@
+Metadata-Version: 2.5
+Name: iris-vector-graph
+Version: 4.1.0
+Summary: Native graph database layer for InterSystems IRIS — openCypher, hybrid vector search, temporal property graph, RDF export, SHACL validation
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Requires-Dist: intersystems-iris>=1.0.0
+Requires-Dist: iris-embedded-python-wrapper>=0.5.20
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: requests>=2.28.0
+Provides-Extra: ai
+Requires-Dist: iris-agentic-dev>=1.0; extra == 'ai'
+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: behave>=1.2.6; 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'
+Requires-Dist: scikit-learn>=1.3.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: pyshacl>=0.25.0; 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: rdf
+Requires-Dist: pyshacl>=0.25.0; extra == 'rdf'
+Requires-Dist: rdflib>=6.0.0; extra == 'rdf'
+Provides-Extra: tck
+Requires-Dist: behave>=1.2.6; extra == 'tck'
+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
+
+<!-- markdownlint-disable MD013 -->
+
+# iris-vector-graph
+
+**Turn InterSystems IRIS into a graph + vector database** — openCypher queries, HNSW/BM25 hybrid search, temporal property graph, RDF/SHACL/PROV-O semantic layer, and Neo4j Bolt protocol compatibility.
+
+[![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 graph**              | An ISC FHIR repository as a named graph; concept → resource → patient ranking ([guide](docs/FHIR_GRAPH.md)) |
+| **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                                                  |
+| **RDF export**              | `export_rdf()` — full or filtered graph to Turtle/NT/NQuads/JSON-LD                                         |
+| **SHACL validation**        | `validate_shacl()` — SHACL Core via PySHACL; `ValidationReport` dataclass                                   |
+| **PROV-O**                  | `prov_export()` — temporal edges as W3C PROV-O provenance graph                                             |
+
+---
+
+## 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
+
+```text
+┌─────────────────────────────────────────────────────────────────────┐
+│                          iris-vector-graph                          │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│   ┌───────────────┐   ┌───────────────┐   ┌───────────────────┐    │
+│   │  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).
+
+---
+
+## Semantic Layer (RDF / SHACL / PROV-O)
+
+```bash
+pip install 'iris-vector-graph[rdf]'
+```
+
+```python
+# Export graph as Turtle (full or filtered)
+engine.export_rdf("kg.ttl")
+engine.export_rdf("proteins.nt", format="nt", label_filter=["Protein", "Disease"])
+engine.export_rdf_from_cypher("MATCH (p:Patient)-[r]->(e) RETURN p,r,e", "patients.ttl")
+
+# Persistent namespace prefixes
+engine.register_namespace("fhir", "http://hl7.org/fhir/")
+
+# SHACL Core validation
+report = engine.validate_shacl("shapes/patient.ttl")
+if not report.conforms:
+    for v in report.violations:
+        print(f"{v.focus_node}: {v.message} [{v.severity}]")
+
+# PROV-O temporal provenance
+engine.prov_export("provenance.ttl", ts_start=1700000000)
+prov = engine.prov_as_dict(edge_id=42)
+```
+
+Every write to ivg is stored as W3C-aligned SPO triples (`rdf_edges`, `rdf_props`, `rdf_labels`)
+with OWL 2 RL inference, named graph support, and RDF-star style edge qualifiers.
+See [docs/SEMANTIC_LAYER.md](docs/SEMANTIC_LAYER.md) for the full guide: format
+reference, SHACL shape writing, PROV-O vocabulary mapping, and integration patterns.
+
+---
+
+## Named Graphs
+
+Scope nodes and edges to a named graph — useful for multi-tenant data, staging
+vs. production snapshots, or materializing a ledger reconstruction into an
+isolated subgraph.
+
+```python
+# Create a node in the "umls" named graph
+engine.create_node("C0027051", labels=["Concept"], graph="umls")
+
+# Create an edge in the same named graph
+engine.create_edge("C0027051", "ISA", "C0085580", graph="umls")
+
+# Cypher: USE GRAPH targets the context for CREATE and MERGE
+engine.execute_cypher("USE GRAPH umls CREATE (n:Concept {id: 'C0001234'})")
+
+# Import an NDJSON file into a named graph
+engine.import_graph_ndjson("export.ndjson", graph="staging")
+
+# Erase one graph's content from every store: SQL rows, ^KG adjacency,
+# degree counters, all five temporal trees. drop_graph() is a deprecated alias.
+engine.erase_graph("staging")
+
+# Erase every graph, including the stores no per-graph erase can reach
+engine.erase_all()
+
+# Independent per-graph, bidirectional drift check between SQL and ^KG
+engine.verify_graph("umls")["ok"]
+
+# delete_edge defaults to the default graph; pass all_graphs=True to sweep all
+engine.delete_edge("C0027051", "ISA", "C0085580", graph="umls")
+engine.delete_edge("C0027051", "ISA", "C0085580", all_graphs=True)
+```
+
+Nodes in the default graph use `graph=""` (empty-string sentinel); the BFS
+adjacency index (`^KG`) partitions by graph key so traversals stay within
+their graph. Existing code that never passes `graph=` is unaffected.
+
+See [docs/USER_GUIDE.md](docs/USER_GUIDE.md#named-graphs) for the full guide.
+
+---
+
+## FHIR Repository as a Graph
+
+Run IVG in an ISC FHIR namespace (`HS.FHIRServer`, R4 JsonAdvSQL) and the repository
+becomes the named graph `fhir:<NAMESPACE>:<package>`: one node per live resource, one
+edge per indexed reference. Codes and properties stay in the repository.
+
+```python
+reg = engine.fhir_graph_register()           # creates the fhir_* tables on first use
+g = reg["graph_id"]                          # e.g. fhir:IVGFHIR:X0001
+engine.fhir_graph_rebuild(g)
+engine.fhir_graph_schedule(g, interval_s=60) # incremental sync from the Task Manager
+
+# Map a code to a concept node, then rank patients around the concept
+engine.code_crosswalk_add("http://hl7.org/fhir/sid/icd-10-cm", "E11.9", "C0011860",
+                          target_graph="umls", relation="exact")
+ranked = engine.fhir_concept_ppr(g, "umls", ["C0011860"], params="clinical",
+                                 group_by="patient", top_k=10)
+
+engine.fhir_coverage_report(g)               # what the interpretation reached
+```
+
+The same from a shell: `ivg fhir register|rebuild|sync --once|status|schedule|links`.
+See [docs/FHIR_GRAPH.md](docs/FHIR_GRAPH.md) for the model, the interpretation
+contract (base R4, no profiles), sync, reports and limits.
+
+---
+
+## Revision Ledger (Transaction-Time History)
+
+The structural graph (nodes, labels, properties, relationships, qualifiers) can
+be versioned with an opt-in, immutable revision ledger. A changeset applies
+atomically and produces exactly one revision; a failed operation applies
+nothing. This is **transaction time** (when the ledger recorded a change) and is
+independent of the temporal property graph's **event time** (`ts` on temporal
+edges), which is unchanged and unversioned.
+
+```python
+from iris_vector_graph.ledger import Changeset
+
+genesis = engine.ledger.enable()              # idempotent; captures the existing graph
+head = engine.ledger.head()
+
+cs = Changeset(actor="ingest:etl-42", actor_type="ingest",
+               message="equipment sync",
+               expected_head=head.revision_id,      # optimistic concurrency
+               idempotency_key="etl-42-2026-09-05")  # safe retry
+cs.create_node("pump-7", labels=["Equipment"], properties={"status": "ok"})
+cs.create_node("tank-2")
+r = cs.create_relationship("pump-7", "FEEDS", "tank-2", qualifiers={"weight": "1.0"})
+cs.set_qualifier(r, "capacity", "100")
+result = engine.ledger.commit(cs)              # StaleHeadError if another writer won
+
+engine.ledger.history(limit=20)                # deterministic, pageable, filterable
+engine.ledger.get_revision(result.revision.revision_id).records
+engine.ledger.diff(genesis.revision_id, result.revision.revision_id)
+engine.ledger.reconstruct(genesis.revision_id) # read-only graph as of a revision
+engine.ledger.export_reconstruction(result.revision.revision_id, "at-rev.ndjson")
+engine.ledger.verify()                         # replay from genesis == current tables?
+engine.ledger.verify(adopt=True)               # record any unrecorded (legacy) writes
+```
+
+Existing APIs keep working with a ledger enabled; writes made through them are
+"unrecorded" and are surfaced by `verify()`. `enable(strict=True)` (or
+`set_strict(True)`) rejects non-ledger structural writes with
+`LedgerStrictModeError`; reads, temporal writes, and index maintenance are
+unaffected. Relationships get a stable **statement identity** that survives
+qualifier changes and snapshot restore. Counters are in
+`engine.status().ledger`, the `Graph_KG.ledger_stats` table, and a metrics hook
+(`engine.ledger.register_metrics_hook`, see
+[docs/ledger-prometheus-hook.md](docs/ledger-prometheus-hook.md)).
+
+---
+
+## Non-USER Namespace Deployment
+
+By default IVG connects to the `USER` namespace. When deploying against a
+HealthShare, Ensemble, or multi-tenant IRIS instance where data lives in a
+different namespace, pass `namespace=` at engine construction:
+
+```python
+from iris_vector_graph import IRISGraphEngine
+import iris.dbapi as dbapi
+
+conn = dbapi.connect(hostname="...", port=1972, namespace="MYGRAPH", ...)
+engine = IRISGraphEngine(conn, namespace="MYGRAPH")
+```
+
+`MYGRAPH` is a placeholder — use a namespace you own and have deployed IVG
+into. A namespace an installed product manages (a HealthShare/Ensemble
+platform or customization namespace) is the wrong home for IVG's schema: that
+product's own upgrade process owns the class and table set there.
+
+On first use, the engine probes `$Data(^KG("deg"))` to verify the `^KG`
+globals are accessible. If they are absent a `WARNING` is logged naming the
+namespace and the fix. Set `IVG_STRICT_NAMESPACE=1` to upgrade the warning
+to a raised `NamespaceMismatchWarning`.
+
+A namespace is an IVG namespace only once the `Graph.KG.*` classes are deployed
+into it: a DDL-only schema, and a CPF global mapping alone, look right and behave
+differently. How to check a namespace and how to map `^KG`:
+[Admin Guide §3](docs/ADMIN_GUIDE.md#deploying-into-a-non-user-namespace).
+
+### Env var controls
+
+| Env var                        | Effect                                                        |
+| ------------------------------ | ------------------------------------------------------------- |
+| _(neither)_                    | `logging.warning` on mismatch, execution continues            |
+| `IVG_STRICT_NAMESPACE=1`       | `logging.warning` + raises `NamespaceMismatchWarning`         |
+| `IVG_IGNORE_NAMESPACE_CHECK=1` | Skip probe entirely (HealthShare platform-managed namespaces) |
+
+`IVG_IGNORE_NAMESPACE_CHECK=1` takes precedence over `IVG_STRICT_NAMESPACE=1`.
+
+---
+
+## Documentation
+
+| Document                                                 | Contents                                                                  |
+| -------------------------------------------------------- | ------------------------------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md)                         | Cypher examples, named graphs, ledger, temporal edges, vector search      |
+| [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                      |
+| [Semantic Layer](docs/SEMANTIC_LAYER.md)                 | RDF export, SHACL validation, PROV-O provenance                           |
+| [FHIR Graph](docs/FHIR_GRAPH.md)                         | FHIR repository as a graph: quick start, interpretation contract, reports |
+| [openCypher TCK](docs/TCK.md)                            | How the TCK figure is produced, what a pass checks, how to rerun it       |
+| [Changelog](CHANGELOG.md)                                | Full version history                                                      |
+
+---
+
+## AI Agent Development
+
+When building agents that use IVG as a knowledge graph backend, install the
+[iris-agentic-dev](https://github.com/intersystems-community/iris-agentic-dev) MCP
+toolkit for ObjectScript compilation, global inspection, and IRIS method invocation
+from your agent's tool loop:
+
+```bash
+pip install iris-agentic-dev
+```
+
+This gives your agent `iris_compile`, `iris_execute`, `iris_global`, and related tools
+that work alongside IVG's Python API.
+
+Skill files with agent-oriented quickstarts:
+
+- [`skills/iris-vector-graph/SKILL.md`](skills/iris-vector-graph/SKILL.md) — IVG API,
+  temporal edges, SHACL, globals, container setup, common gotchas
+- [`skills/ivg-arno/SKILL.md`](skills/ivg-arno/SKILL.md) — Arno Rust acceleration,
+  BFS at scale, enterprise container, ASQ query syntax
+
+---
+
+## License
+
+MIT. See [LICENSE](LICENSE).