iris-vector-graph 2.2.0__tar.gz → 2.3.1__tar.gz

{iris_vector_graph-2.2.0 → iris_vector_graph-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris-vector-graph
-Version: 2.2.0
+Version: 2.3.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
@@ -63,6 +63,7 @@ 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'
@@ -79,6 +80,9 @@ 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: visualization
 Requires-Dist: graphviz>=0.20.0; extra == 'visualization'
 Requires-Dist: matplotlib>=3.7.0; extra == 'visualization'
@@ -143,19 +147,22 @@ print(result["rows"])  # [('Bob',)]
 
 ## 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 |
+| 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                                           |
+| **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                                      |
 
 ---
 
@@ -165,16 +172,16 @@ 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) |
+| 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)
 
@@ -238,16 +245,50 @@ Full schema and ObjectScript class reference: [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.
+
+---
+
 ## 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 |
+| 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        |
+| [Semantic Layer](docs/SEMANTIC_LAYER.md)                 | RDF export, SHACL validation, PROV-O provenance             |
+| [Changelog](CHANGELOG.md)                                | Full version history                                        |
 
 ---
 

{iris_vector_graph-2.2.0 → iris_vector_graph-2.3.1}/README.md

@@ -56,19 +56,22 @@ print(result["rows"])  # [('Bob',)]
 
 ## 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 |
+| 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                                           |
+| **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                                      |
 
 ---
 
@@ -78,16 +81,16 @@ 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) |
+| 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)
 
@@ -151,16 +154,50 @@ Full schema and ObjectScript class reference: [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.
+
+---
+
 ## 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 |
+| 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        |
+| [Semantic Layer](docs/SEMANTIC_LAYER.md)                 | RDF export, SHACL validation, PROV-O provenance             |
+| [Changelog](CHANGELOG.md)                                | Full version history                                        |
 
 ---
 

iris_vector_graph-2.3.1/examples/demo_rdf_semantic_layer.py

@@ -0,0 +1,335 @@
+"""
+Demo: RDF Semantic Layer — Export, SHACL Validation, PROV-O Provenance
+
+Demonstrates the three semantic layer capabilities added in v2.3.0:
+
+  1. RDF Export  — full graph and filtered subgraph to Turtle/N-Triples/JSON-LD
+  2. SHACL       — validate data quality with shape constraints
+  3. PROV-O      — export temporal edge provenance as W3C PROV-O
+
+Prerequisites:
+    pip install 'iris-vector-graph[rdf]'
+    scripts/test-container.sh up   # start IRIS Community Edition
+
+Run:
+    python examples/demo_rdf_semantic_layer.py
+"""
+
+import json
+import os
+import sys
+import tempfile
+
+# ---------------------------------------------------------------------------
+# Connection
+# ---------------------------------------------------------------------------
+
+def connect():
+    try:
+        import iris.dbapi as dbapi
+        conn = dbapi.connect(
+            hostname=os.environ.get("IRIS_HOST", "localhost"),
+            port=int(os.environ.get("IVG_PORT", "21972")),
+            namespace="USER",
+            username=os.environ.get("IRIS_USER", "_SYSTEM"),
+            password=os.environ.get("IRIS_PASSWORD", "SYS"),
+        )
+        return conn
+    except Exception as e:
+        print(f"[ERROR] Cannot connect to IRIS: {e}")
+        print("        Start the container with: scripts/test-container.sh up")
+        sys.exit(1)
+
+
+# ---------------------------------------------------------------------------
+# Seed data — a small FHIR-like clinical graph
+# ---------------------------------------------------------------------------
+
+PATIENTS = [
+    {"id": "Patient/p001", "name": "Alice Chen", "birthDate": "1980-03-15", "cohort": "HFrEF"},
+    {"id": "Patient/p002", "name": "Bob Martinez", "birthDate": "1955-07-22", "cohort": "HFrEF"},
+    {"id": "Patient/p003", "name": "Carol Kim",                              "cohort": "control"},  # missing birthDate
+]
+
+ENCOUNTERS = [
+    {"id": "Encounter/e001", "type": "Admission",  "patient": "Patient/p001"},
+    {"id": "Encounter/e002", "type": "Discharge",  "patient": "Patient/p001"},
+    {"id": "Encounter/e003", "type": "Admission",  "patient": "Patient/p002"},
+]
+
+TIMESTAMPS = {
+    ("Patient/p001", "admitted",    "Encounter/e001"): (1700000000, 1700086400),
+    ("Patient/p001", "discharged",  "Encounter/e002"): (1700086400, 1700100000),
+    ("Patient/p002", "admitted",    "Encounter/e003"): (1700200000, None),
+}
+
+PATIENT_SHAPE = """
+@prefix sh:   <http://www.w3.org/ns/shacl#> .
+@prefix fhir: <http://hl7.org/fhir/> .
+@prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .
+
+fhir:PatientShape a sh:NodeShape ;
+    sh:targetClass fhir:Patient ;
+    sh:property [
+        sh:path     fhir:birthDate ;
+        sh:minCount 1 ;
+        sh:message  "Patient must have a birthDate" ;
+    ] ;
+    sh:property [
+        sh:path     fhir:name ;
+        sh:minCount 1 ;
+        sh:message  "Patient must have a name" ;
+    ] .
+"""
+
+
+def seed(engine):
+    """Load sample clinical data into IVG."""
+    print("\n--- Seeding clinical graph ---")
+    for p in PATIENTS:
+        props = {k: v for k, v in p.items() if k not in ("id",)}
+        engine.create_node(
+            p["id"],
+            labels=["http://hl7.org/fhir/Patient"],
+            properties={f"http://hl7.org/fhir/{k}": v for k, v in props.items()},
+        )
+    print(f"  {len(PATIENTS)} patients loaded")
+
+    for enc in ENCOUNTERS:
+        props = {k: v for k, v in enc.items() if k not in ("id", "patient")}
+        engine.create_node(enc["id"], labels=["http://hl7.org/fhir/Encounter"], properties=props)
+        engine.create_edge(enc["patient"], "http://hl7.org/fhir/encounter", enc["id"])
+    print(f"  {len(ENCOUNTERS)} encounters loaded")
+
+    for (src, pred, tgt), (ts_start, ts_end) in TIMESTAMPS.items():
+        engine.create_edge_temporal(
+            source=src,
+            predicate=f"http://hl7.org/fhir/{pred}",
+            target=tgt,
+            timestamp=ts_start,
+        )
+    print(f"  {len(TIMESTAMPS)} temporal edges loaded")
+
+    engine.register_namespace("fhir", "http://hl7.org/fhir/")
+    engine.register_namespace("ex",   "http://example.org/")
+
+
+# ---------------------------------------------------------------------------
+# Demo 1: RDF Export
+# ---------------------------------------------------------------------------
+
+def demo_export(engine, outdir):
+    print("\n--- Part 1: RDF Export ---")
+
+    # 1a. Full graph as Turtle
+    ttl_path = os.path.join(outdir, "clinical.ttl")
+    result = engine.export_rdf(ttl_path)
+    print(f"  Full export → {ttl_path}")
+    print(f"    {result['triples']} triples, {result['nodes']} nodes, {result['edges']} edges")
+
+    # 1b. Patients only as N-Triples
+    nt_path = os.path.join(outdir, "patients.nt")
+    result = engine.export_rdf(nt_path, format="nt", label_filter=["http://hl7.org/fhir/Patient"])
+    print(f"  Patient subgraph → {nt_path}  ({result['triples']} triples)")
+
+    # 1c. Cypher-based subgraph: HFrEF cohort only
+    hfref_path = os.path.join(outdir, "hfref_cohort.ttl")
+    result = engine.export_rdf_from_cypher(
+        "MATCH (p:Patient) WHERE p.cohort = 'HFrEF' RETURN p.id AS id",
+        hfref_path,
+    )
+    print(f"  HFrEF cohort export → {hfref_path}  ({result['triples']} triples)")
+
+    # 1d. Verify Turtle is valid
+    import rdflib
+    g = rdflib.Graph()
+    g.parse(ttl_path, format="turtle")
+    print(f"  Verified: {len(g)} triples parse cleanly in rdflib")
+
+    # Show first 5 triples
+    print("  Sample triples:")
+    for i, (s, p, o) in enumerate(g):
+        print(f"    {str(s)[-30:]:30s}  {str(p)[-25:]:25s}  {str(o)[:40]}")
+        if i >= 4:
+            break
+
+    return ttl_path
+
+
+# ---------------------------------------------------------------------------
+# Demo 2: SHACL Validation
+# ---------------------------------------------------------------------------
+
+def demo_shacl(engine, outdir):
+    print("\n--- Part 2: SHACL Core Validation ---")
+
+    # 2a. Validate all patients against birthDate + name shapes
+    print("  Validating all patients against PatientShape...")
+    report = engine.validate_shacl(PATIENT_SHAPE)
+    print(f"  Conforms: {report.conforms}")
+    print(f"  Violations: {len(report.violations)}")
+
+    for v in report.violations:
+        print(f"    [{v.severity}] {v.focus_node.split('/')[-1]:20s} → {v.message}")
+
+    # 2b. Validate only Carol Kim (known to be missing birthDate)
+    carol_id = "Patient/p003"
+    print(f"\n  Targeted validation of {carol_id}:")
+    report_targeted = engine.validate_shacl(PATIENT_SHAPE, node_ids=[carol_id])
+    print(f"  Conforms: {report_targeted.conforms}")
+    for v in report_targeted.violations:
+        print(f"    [{v.severity}] {v.message}")
+
+    # 2c. Show JSON-serializable report
+    report_dict = report.to_dict()
+    report_path = os.path.join(outdir, "validation_report.json")
+    with open(report_path, "w") as f:
+        json.dump(report_dict, f, indent=2)
+    print(f"\n  Full report saved → {report_path}")
+
+
+# ---------------------------------------------------------------------------
+# Demo 3: PROV-O Temporal Provenance
+# ---------------------------------------------------------------------------
+
+def demo_prov(engine, outdir):
+    print("\n--- Part 3: PROV-O Temporal Provenance ---")
+
+    # 3a. Export all temporal edges as PROV-O
+    prov_path = os.path.join(outdir, "provenance.ttl")
+    result = engine.prov_export(prov_path)
+    print(f"  PROV-O export → {prov_path}")
+    print(f"    {result['activities']} activities, {result['entities']} entities")
+
+    # 3b. Verify with rdflib
+    import rdflib
+    PROV = rdflib.Namespace("http://www.w3.org/ns/prov#")
+    g = rdflib.Graph()
+    g.parse(prov_path, format="turtle")
+
+    activities = list(g.subjects(rdflib.RDF.type, PROV.Activity))
+    entities   = list(g.subjects(rdflib.RDF.type, PROV.Entity))
+    print(f"  Verified: {len(activities)} prov:Activity, {len(entities)} prov:Entity")
+
+    # 3c. Show activity details
+    print("  Activities:")
+    for act in activities[:3]:
+        started = next(g.objects(act, PROV.startedAtTime), "—")
+        ended   = next(g.objects(act, PROV.endedAtTime), "—")
+        used    = next(g.objects(act, PROV.used), "—")
+        short_act = str(act).split("/")[-1][:40]
+        print(f"    {short_act}")
+        print(f"      started:  {started}")
+        print(f"      ended:    {ended}")
+        print(f"      used:     {str(used).split('/')[-1]}")
+
+    # 3d. Time-windowed export (Alice's admission only)
+    window_path = os.path.join(outdir, "alice_prov.ttl")
+    engine.prov_export(window_path, ts_start=1699999999, ts_end=1700086401)
+    g2 = rdflib.Graph()
+    g2.parse(window_path, format="turtle")
+    print(f"\n  Alice time-window export → {window_path}")
+    print(f"    {len(list(g2.subjects(rdflib.RDF.type, PROV.Activity)))} activities in window")
+
+    return prov_path
+
+
+# ---------------------------------------------------------------------------
+# Demo 4: End-to-End integration
+# ---------------------------------------------------------------------------
+
+def demo_integration(engine, ttl_path, outdir):
+    print("\n--- Part 4: End-to-End Integration Pattern ---")
+    print("  Simulate: export IVG graph → validate with SHACL → export provenance")
+
+    # Round-trip: export then verify with rdflib
+    import rdflib
+    g = rdflib.Graph()
+    g.parse(ttl_path, format="turtle")
+
+    # Count by type
+    by_type = {}
+    for s, p, o in g.triples((None, rdflib.RDF.type, None)):
+        type_name = str(o).split("/")[-1] or str(o).split("#")[-1]
+        by_type[type_name] = by_type.get(type_name, 0) + 1
+
+    print("  Graph composition by type:")
+    for t, count in sorted(by_type.items(), key=lambda x: -x[1]):
+        print(f"    {t:30s}: {count}")
+
+    print(f"\n  → Graph is now portable to any SPARQL endpoint or rdflib pipeline.")
+    print(f"  → SHACL validated before publication.")
+    print(f"  → PROV-O provenance attached for audit trail.")
+
+
+# ---------------------------------------------------------------------------
+# Cleanup
+# ---------------------------------------------------------------------------
+
+def cleanup(engine):
+    cur = engine.conn.cursor()
+    try:
+        for p in PATIENTS:
+            cur.execute("DELETE FROM Graph_KG.nodes WHERE node_id = ?", [p["id"]])
+        for enc in ENCOUNTERS:
+            cur.execute("DELETE FROM Graph_KG.nodes WHERE node_id = ?", [enc["id"]])
+        cur.execute(
+            "DELETE FROM Graph_KG.rdf_edges WHERE s LIKE 'Patient/%' OR s LIKE 'Encounter/%'"
+        )
+        cur.execute(
+            "DELETE FROM Graph_KG.rdf_labels WHERE s LIKE 'Patient/%' OR s LIKE 'Encounter/%'"
+        )
+        cur.execute(
+            "DELETE FROM Graph_KG.rdf_props WHERE s LIKE 'Patient/%' OR s LIKE 'Encounter/%'"
+        )
+        engine.conn.commit()
+    except Exception:
+        pass
+    finally:
+        cur.close()
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main():
+    print("=" * 60)
+    print("  iris-vector-graph — RDF Semantic Layer Demo (v2.3.0)")
+    print("=" * 60)
+
+    # Check rdflib available
+    try:
+        import rdflib
+        print(f"\n  rdflib {rdflib.__version__} detected")
+    except ImportError:
+        print("\n[ERROR] rdflib not installed.")
+        print("        Run: pip install 'iris-vector-graph[rdf]'")
+        sys.exit(1)
+
+    conn = connect()
+    print(f"\n  Connected to IRIS")
+
+    from iris_vector_graph.engine import IRISGraphEngine
+    engine = IRISGraphEngine(conn, embedding_dimension=4)
+    engine.initialize_schema()
+
+    with tempfile.TemporaryDirectory() as outdir:
+        try:
+            seed(engine)
+            ttl_path = demo_export(engine, outdir)
+            demo_shacl(engine, outdir)
+            demo_prov(engine, outdir)
+            demo_integration(engine, ttl_path, outdir)
+        finally:
+            cleanup(engine)
+
+    conn.close()
+    print("\n" + "=" * 60)
+    print("  Demo complete.")
+    print("  See docs/SEMANTIC_LAYER.md for the full guide.")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

{iris_vector_graph-2.2.0 → iris_vector_graph-2.3.1}/iris_src/src/Graph/KG/EdgeScan.cls

@@ -1,3 +1,27 @@
+/// Graph.KG.EdgeScan — adjacency-global maintenance + scan procedures.
+///
+/// ============================================================================
+/// ^KG ADJACENCY LAYOUT OF RECORD (canonical — do not deviate)
+/// ============================================================================
+/// The production adjacency layout is SHARD-PREFIXED:
+///
+///     ^KG("out", 0, s, p, o) = weight     outbound edges
+///     ^KG("in",  0, o, p, s) = weight     inbound edges
+///     ^KG("deg", s)          = out-degree
+///     ^KG("degp", s, p)      = per-predicate out-degree
+///
+/// Every live reader scans this layout: MatchEdges (here), Graph.KG.Algorithms,
+/// Graph.KG.Centrality, Graph.KG.Subgraph, and the NKG builders. WriteAdjacency
+/// (below), TraversalBuild.BuildKG, TemporalIndex.InsertEdge, and the (currently
+/// undeployed) Graph.KG.GraphIndex functional index all WRITE this exact form.
+///
+/// There is a LEGACY no-shard layout — ^KG("out", s, p, o) — still written by
+/// the bench harness (Graph.KG.BenchSeeder / BenchFormat) and the standalone CSV
+/// Graph.KG.Loader, and read by dead Else-fallback branches in NKGAccelTraversal
+/// / NKGAccelAdjacency. Nothing in the production write/read path uses it.
+/// DO NOT add new readers or writers of the no-shard form. If you need adjacency,
+/// use ^KG("out", 0, ...). See docs/index-maintenance-architecture-review.md.
+/// ============================================================================
 Class Graph.KG.EdgeScan Extends %RegisteredObject
 {
 

{iris_vector_graph-2.2.0 → iris_vector_graph-2.3.1}/iris_src/src/Graph/KG/GraphIndex.cls

@@ -62,8 +62,12 @@ ClassMethod InsertIndex(pID As %String, s As %Binary, p As %Binary, o As %Binary
 {
 	Set weight = ##class(Graph.KG.GraphIndex).ExtractWeight(qualifiers)
 
-	Set ^KG("out", s, p, o) = weight
-	Set ^KG("in", o, p, s) = weight
+	// Shard-0 layout — MUST match EdgeScan.WriteAdjacency / TraversalBuild.BuildKG.
+	// Every live reader (MatchEdges, Algorithms, Centrality, NKG BFS) scans
+	// ^KG("out", 0, ...). Writing the legacy no-shard layout here would populate
+	// globals nothing reads. See Graph.KG.EdgeScan:WriteAdjacency for the canonical form.
+	Set ^KG("out", 0, s, p, o) = weight
+	Set ^KG("in", 0, o, p, s) = weight
 	Set tmp = $Increment(^KG("deg", s))
 	Set tmp = $Increment(^KG("degp", s, p))
 
@@ -147,8 +151,8 @@ ClassMethod UpdateIndex(pID As %String, s As %Binary, p As %Binary, o As %Binary
 
 ClassMethod DeleteIndex(pID As %String, s As %Binary, p As %Binary, o As %Binary, qualifiers As %Binary = "") As %Status [ ServerOnly = 1 ]
 {
-	Kill ^KG("out", s, p, o)
-	Kill ^KG("in", o, p, s)
+	Kill ^KG("out", 0, s, p, o)
+	Kill ^KG("in", 0, o, p, s)
 	Set tmp = $Increment(^KG("deg", s), -1)
 	Set tmp = $Increment(^KG("degp", s, p), -1)
 	If $Get(^KG("deg", s)) <= 0 Kill ^KG("deg", s)