aevum-store-oxigraph 0.2.0__tar.gz

aevum_store_oxigraph-0.2.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.venv/
+*.egg-info/
+
+# Build
+dist/
+build/
+
+# Tools
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.hypothesis/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Verify scripts (run locally, never commit)
+verify_phase*.py
+scripts/verify_phase*.py

aevum_store_oxigraph-0.2.0/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: aevum-store-oxigraph
+Version: 0.2.0
+Summary: Aevum — Oxigraph GraphStore backend (small deployments).
+Project-URL: Homepage, https://aevum.build
+Project-URL: Repository, https://github.com/aevum-labs/aevum
+License: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: aevum-core
+Requires-Dist: pyoxigraph<0.6,>=0.5
+Description-Content-Type: text/markdown
+
+# aevum-store-oxigraph
+
+Oxigraph-backed graph store for Aevum. Suitable for single-node and embedded deployments. No external database required.
+
+```bash
+pip install aevum-store-oxigraph
+```
+
+```python
+from aevum.core import Engine
+from aevum.store.oxigraph import OxigraphStore
+
+engine = Engine(graph_store=OxigraphStore(path="./aevum-data"))
+```
+
+For team deployments requiring shared state, use `aevum-store-postgres` instead.
+See the [main repository README](https://github.com/aevum-labs/aevum) for backend selection guidance.

aevum_store_oxigraph-0.2.0/README.md

@@ -0,0 +1,17 @@
+# aevum-store-oxigraph
+
+Oxigraph-backed graph store for Aevum. Suitable for single-node and embedded deployments. No external database required.
+
+```bash
+pip install aevum-store-oxigraph
+```
+
+```python
+from aevum.core import Engine
+from aevum.store.oxigraph import OxigraphStore
+
+engine = Engine(graph_store=OxigraphStore(path="./aevum-data"))
+```
+
+For team deployments requiring shared state, use `aevum-store-postgres` instead.
+See the [main repository README](https://github.com/aevum-labs/aevum) for backend selection guidance.

aevum_store_oxigraph-0.2.0/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "aevum-store-oxigraph"
+version = "0.2.0"
+description = "Aevum — Oxigraph GraphStore backend (small deployments)."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "aevum-core",
+    "pyoxigraph>=0.5,<0.6",
+]
+
+[project.urls]
+Homepage = "https://aevum.build"
+Repository = "https://github.com/aevum-labs/aevum"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aevum"]
+
+[tool.uv.sources]
+aevum-core = { workspace = true }
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = "--tb=short"
+pythonpath = ["src", "tests"]
+
+[tool.mypy]
+strict = true
+python_version = "3.11"
+mypy_path = "src"
+explicit_package_bases = true
+ignore_missing_imports = true
+
+[tool.ruff]
+line-length = 130
+
+[tool.ruff.lint]
+select = ["E", "F", "UP", "B", "SIM", "I", "ANN"]
+ignore = ["ANN401"]

aevum_store_oxigraph-0.2.0/src/aevum/store/oxigraph/__init__.py

@@ -0,0 +1,21 @@
+"""
+aevum.store.oxigraph — Oxigraph GraphStore backend.
+
+Usage:
+    from aevum.store.oxigraph import OxigraphStore
+    from aevum.core import Engine
+
+    # In-memory (dev/test):
+    store = OxigraphStore()
+
+    # Disk-backed (production):
+    store = OxigraphStore(path="/var/lib/aevum/graph")
+
+    engine = Engine(graph_store=store)
+"""
+
+from aevum.store.oxigraph.store import OxigraphStore
+
+__version__ = "0.1.0"
+
+__all__ = ["OxigraphStore"]

aevum_store_oxigraph-0.2.0/src/aevum/store/oxigraph/store.py

@@ -0,0 +1,252 @@
+"""
+OxigraphStore — GraphStore Protocol backed by pyoxigraph.
+
+Satisfies the aevum.core.protocols.graph_store.GraphStore Protocol.
+Uses three Named Graphs (frozen invariants from spec Section 04.3):
+  urn:aevum:knowledge   — working graph (entities and relationships)
+  urn:aevum:provenance  — per-entity provenance records as quads
+  urn:aevum:consent     — consent ledger (managed by aevum-core)
+
+RDF-star is NOT used (dropped in pyoxigraph 0.5).
+Provenance is stored as separate quads in urn:aevum:provenance.
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+import threading
+from pathlib import Path
+from typing import Any
+
+from pyoxigraph import Literal, NamedNode, Quad, QuerySolutions, Store
+
+from aevum.store.oxigraph.vocabulary import (
+    PRED_CLASS_LVL,
+    PRED_INGEST_AT,
+    PRED_SUBJECT_ID,
+    PRED_TYPE,
+    TYPE_ENTITY,
+)
+
+# Three Named Graphs — FROZEN INVARIANTS (spec Section 04.3)
+GRAPH_KNOWLEDGE  = NamedNode("urn:aevum:knowledge")
+GRAPH_PROVENANCE = NamedNode("urn:aevum:provenance")
+GRAPH_CONSENT    = NamedNode("urn:aevum:consent")
+
+# XSD datatypes
+XSD_STRING   = NamedNode("http://www.w3.org/2001/XMLSchema#string")
+XSD_INTEGER  = NamedNode("http://www.w3.org/2001/XMLSchema#integer")
+XSD_DATETIME = NamedNode("http://www.w3.org/2001/XMLSchema#dateTime")
+
+
+def _entity_node(entity_id: str) -> NamedNode:
+    """Map an entity_id string to an RDF NamedNode IRI."""
+    if entity_id.startswith("http") or entity_id.startswith("urn:"):
+        return NamedNode(entity_id)
+    return NamedNode(f"urn:aevum:entity:{entity_id}")
+
+
+def _lit_str(value: str) -> Literal:
+    return Literal(value, datatype=XSD_STRING)
+
+
+def _lit_int(value: int) -> Literal:
+    return Literal(str(value), datatype=XSD_INTEGER)
+
+
+def _lit_dt(value: str) -> Literal:
+    return Literal(value, datatype=XSD_DATETIME)
+
+
+class OxigraphStore:
+    """
+    GraphStore implementation backed by pyoxigraph.
+
+    Thread-safe via internal lock.
+    Satisfies aevum.core.protocols.graph_store.GraphStore Protocol.
+    """
+
+    def __init__(self, path: str | Path | None = None) -> None:
+        """
+        Create an OxigraphStore.
+
+        Args:
+            path: Directory for disk-backed persistence.
+                  None = in-memory (dev/test only, lost on restart).
+        """
+        if path is not None:
+            self._store = Store(str(path))
+        else:
+            self._store = Store()
+        self._lock = threading.Lock()
+        self._init_named_graphs()
+
+    def _init_named_graphs(self) -> None:
+        """Ensure all three Named Graphs exist in the store."""
+        with self._lock:
+            for graph in (GRAPH_KNOWLEDGE, GRAPH_PROVENANCE, GRAPH_CONSENT):
+                self._store.add_graph(graph)
+
+    def store_entity(
+        self,
+        entity_id: str,
+        data: dict[str, Any],
+        classification: int = 0,
+    ) -> None:
+        """
+        Store or update an entity in urn:aevum:knowledge.
+        Stores provenance metadata in urn:aevum:provenance.
+
+        Classification level enforces Barrier 2 at read time.
+        """
+        node = _entity_node(entity_id)
+        now_iso = datetime.datetime.now(datetime.UTC).isoformat()
+
+        with self._lock:
+            # Remove existing quads for this entity before re-inserting
+            # (update semantics — last write wins within a subject)
+            existing = list(self._store.quads_for_pattern(
+                node, None, None, GRAPH_KNOWLEDGE
+            ))
+            for quad in existing:
+                self._store.remove(quad)
+
+            # Core type quad
+            self._store.add(Quad(node, PRED_TYPE, TYPE_ENTITY, GRAPH_KNOWLEDGE))
+
+            # Store each data field as a separate quad
+            # Non-string values are JSON-serialized as string literals
+            for key, value in data.items():
+                pred = NamedNode(f"urn:aevum:field:{key}")
+                if isinstance(value, str):
+                    obj: Literal = _lit_str(value)
+                elif isinstance(value, int):
+                    obj = _lit_int(value)
+                elif isinstance(value, float):
+                    obj = Literal(str(value), datatype=NamedNode(
+                        "http://www.w3.org/2001/XMLSchema#double"
+                    ))
+                else:
+                    obj = _lit_str(json.dumps(value))
+                self._store.add(Quad(node, pred, obj, GRAPH_KNOWLEDGE))
+
+            # Store provenance in urn:aevum:provenance
+            # (separate quads — not RDF-star, which is dropped in 0.5)
+            prov_quads = [
+                Quad(node, PRED_SUBJECT_ID, _lit_str(entity_id), GRAPH_PROVENANCE),
+                Quad(node, PRED_CLASS_LVL, _lit_int(classification), GRAPH_PROVENANCE),
+                Quad(node, PRED_INGEST_AT, _lit_dt(now_iso), GRAPH_PROVENANCE),
+            ]
+            for q in prov_quads:
+                self._store.add(q)
+
+    def get_entity(self, entity_id: str) -> dict[str, Any] | None:
+        """Retrieve an entity by ID. Returns None if not found."""
+        node = _entity_node(entity_id)
+        result: dict[str, Any] = {}
+
+        with self._lock:
+            quads = list(self._store.quads_for_pattern(
+                node, None, None, GRAPH_KNOWLEDGE
+            ))
+
+        if not quads:
+            return None
+
+        for quad in quads:
+            pred_str = quad.predicate.value
+            if pred_str == PRED_TYPE.value:
+                continue  # skip rdf:type
+            if pred_str.startswith("urn:aevum:field:"):
+                key = pred_str[len("urn:aevum:field:"):]
+                obj = quad.object
+                if isinstance(obj, (NamedNode, Literal)):
+                    raw = obj.value
+                    try:
+                        result[key] = json.loads(raw)
+                    except (json.JSONDecodeError, ValueError):
+                        result[key] = raw
+
+        return result if result else None
+
+    def get_entity_classification(self, entity_id: str) -> int:
+        """Return the classification level of an entity (default 0)."""
+        node = _entity_node(entity_id)
+        with self._lock:
+            quads = list(self._store.quads_for_pattern(
+                node, PRED_CLASS_LVL, None, GRAPH_PROVENANCE
+            ))
+        if not quads:
+            return 0
+        obj = quads[0].object
+        if not isinstance(obj, (NamedNode, Literal)):
+            return 0
+        try:
+            return int(obj.value)
+        except ValueError:
+            return 0
+
+    def query_entities(
+        self,
+        subject_ids: list[str],
+        classification_max: int = 0,
+    ) -> dict[str, dict[str, Any]]:
+        """
+        Retrieve entities for the given subject IDs.
+        Excludes entities classified above classification_max (Barrier 2).
+        """
+        result: dict[str, dict[str, Any]] = {}
+        for entity_id in subject_ids:
+            entity_class = self.get_entity_classification(entity_id)
+            if entity_class > classification_max:
+                continue  # Barrier 2: classification ceiling
+            entity_data = self.get_entity(entity_id)
+            if entity_data is not None:
+                result[entity_id] = entity_data
+        return result
+
+    def sparql_select(
+        self,
+        query: str,
+        default_graph: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """
+        Execute a SPARQL SELECT query and return results as a list of dicts.
+
+        Not part of the GraphStore Protocol. Useful for ad-hoc traversal
+        within complications or diagnostics. Not exposed as a public HTTP endpoint.
+        """
+        kwargs: dict[str, Any] = {}
+        if default_graph:
+            kwargs["default_graph"] = NamedNode(default_graph)
+        with self._lock:
+            solutions = self._store.query(query, **kwargs)
+        rows: list[dict[str, Any]] = []
+        if not isinstance(solutions, QuerySolutions):
+            return rows
+        for sol in solutions:
+            row: dict[str, Any] = {}
+            for var in sol.variables():
+                term = sol[var]
+                if term is not None and isinstance(term, (NamedNode, Literal)):
+                    row[str(var)] = term.value
+            rows.append(row)
+        return rows
+
+    def entity_count(self) -> int:
+        """Return number of distinct entities in urn:aevum:knowledge."""
+        with self._lock:
+            quads = list(self._store.quads_for_pattern(
+                None, PRED_TYPE, TYPE_ENTITY, GRAPH_KNOWLEDGE
+            ))
+        return len(quads)
+
+    def clear_knowledge_graph(self) -> None:
+        """
+        Clear all entities from urn:aevum:knowledge and urn:aevum:provenance.
+        For testing only — not available via any public API.
+        """
+        with self._lock:
+            self._store.clear_graph(GRAPH_KNOWLEDGE)
+            self._store.clear_graph(GRAPH_PROVENANCE)

aevum_store_oxigraph-0.2.0/src/aevum/store/oxigraph/vocabulary.py

@@ -0,0 +1,26 @@
+"""
+Standard relationship vocabulary for the Aevum knowledge graph.
+
+These predicates are used when storing entities and their relationships.
+They are not exposed as a user-facing SPARQL endpoint (Non-Goal per spec 3.4).
+"""
+
+from __future__ import annotations
+
+from pyoxigraph import NamedNode
+
+# Aevum namespace
+AEVUM = "https://aevum.build/vocab/"
+
+# Core predicates
+PRED_TYPE       = NamedNode("http://www.w3.org/1999/02/22-rdf-syntax-ns#type")
+PRED_LABEL      = NamedNode("http://www.w3.org/2000/01/rdf-schema#label")
+PRED_CONTENT    = NamedNode(f"{AEVUM}content")
+PRED_SUBJECT_ID = NamedNode(f"{AEVUM}subjectId")
+PRED_SOURCE_ID  = NamedNode(f"{AEVUM}sourceId")
+PRED_AUDIT_ID   = NamedNode(f"{AEVUM}auditId")
+PRED_CLASS_LVL  = NamedNode(f"{AEVUM}classificationLevel")
+PRED_INGEST_AT  = NamedNode(f"{AEVUM}ingestedAt")
+
+# Entity types
+TYPE_ENTITY     = NamedNode(f"{AEVUM}Entity")

aevum_store_oxigraph-0.2.0/tests/test_engine_integration.py

@@ -0,0 +1,115 @@
+"""
+Integration test: Engine using OxigraphStore instead of InMemoryGraphStore.
+Verifies the real backend works end-to-end with the kernel.
+"""
+
+from __future__ import annotations
+
+from aevum.core import Engine
+from aevum.core.consent.models import ConsentGrant
+
+from aevum.store.oxigraph import OxigraphStore
+
+
+def _engine() -> Engine:
+    store = OxigraphStore()
+    engine = Engine(graph_store=store)
+    engine.add_consent_grant(ConsentGrant(
+        grant_id="g1",
+        subject_id="subject-1",
+        grantee_id="actor",
+        operations=["ingest", "query", "replay", "export"],
+        purpose="integration-test",
+        classification_max=3,
+        granted_at="2026-01-01T00:00:00Z",
+        expires_at="2030-01-01T00:00:00Z",
+    ))
+    return engine
+
+
+def _prov() -> dict:
+    return {
+        "source_id": "test-src",
+        "chain_of_custody": ["test-src"],
+        "classification": 0,
+    }
+
+
+def test_ingest_then_query_with_oxigraph() -> None:
+    engine = _engine()
+    ingest_result = engine.ingest(
+        data={"content": "hello world", "type": "text"},
+        provenance=_prov(),
+        purpose="integration-test",
+        subject_id="subject-1",
+        actor="actor",
+    )
+    assert ingest_result.status == "ok"
+
+    query_result = engine.query(
+        purpose="integration-test",
+        subject_ids=["subject-1"],
+        actor="actor",
+    )
+    assert query_result.status == "ok"
+    assert "subject-1" in query_result.data["results"]
+
+
+def test_classification_ceiling_enforced_via_engine() -> None:
+    """Barrier 2 still applies when using OxigraphStore."""
+    engine = _engine()
+    engine.ingest(
+        data={"content": "public"},
+        provenance={**_prov(), "classification": 0},
+        purpose="integration-test",
+        subject_id="subject-1",
+        actor="actor",
+    )
+    # Query with classification_max=0 — should get results
+    r = engine.query(
+        purpose="integration-test",
+        subject_ids=["subject-1"],
+        actor="actor",
+        classification_max=0,
+    )
+    assert r.status == "ok"
+
+
+def test_sigchain_intact_with_oxigraph() -> None:
+    """Sigchain still works regardless of graph backend."""
+    engine = _engine()
+    for i in range(5):
+        engine.commit(event_type=f"app.event_{i}", payload={"i": i}, actor="actor")
+    assert engine.verify_sigchain() is True
+
+
+def test_demo_ten_lines() -> None:
+    """
+    A developer can ingest data and query it back using OxigraphStore in ~10 lines.
+    """
+    from aevum.core import Engine
+    from aevum.core.consent.models import ConsentGrant
+
+    from aevum.store.oxigraph import OxigraphStore
+
+    store = OxigraphStore()
+    engine = Engine(graph_store=store)
+    engine.add_consent_grant(ConsentGrant(
+        grant_id="demo-grant", subject_id="user-42", grantee_id="demo-actor",
+        operations=["ingest", "query", "replay", "export"],
+        purpose="demo", classification_max=3,
+        granted_at="2026-01-01T00:00:00Z", expires_at="2030-01-01T00:00:00Z",
+    ))
+    ingest = engine.ingest(
+        data={"name": "Alice", "role": "engineer"},
+        provenance={"source_id": "hr-system", "chain_of_custody": ["hr-system"],
+                    "classification": 0},
+        purpose="demo", subject_id="user-42", actor="demo-actor",
+    )
+    assert ingest.status == "ok"
+
+    result = engine.query(
+        purpose="demo", subject_ids=["user-42"], actor="demo-actor"
+    )
+    assert result.status == "ok"
+    assert "user-42" in result.data["results"]

aevum_store_oxigraph-0.2.0/tests/test_store.py

@@ -0,0 +1,142 @@
+"""
+Tests for OxigraphStore — GraphStore Protocol conformance.
+All tests run against in-memory store (no disk I/O in CI).
+"""
+
+from __future__ import annotations
+
+from aevum.core.protocols.graph_store import GraphStore
+
+from aevum.store.oxigraph import OxigraphStore
+
+
+def _store() -> OxigraphStore:
+    return OxigraphStore()  # in-memory
+
+
+def test_satisfies_graphstore_protocol() -> None:
+    """OxigraphStore must satisfy the GraphStore Protocol at runtime."""
+    assert isinstance(_store(), GraphStore)
+
+
+def test_store_and_get_entity() -> None:
+    s = _store()
+    s.store_entity("e1", {"content": "hello", "type": "text"})
+    result = s.get_entity("e1")
+    assert result is not None
+    assert result["content"] == "hello"
+    assert result["type"] == "text"
+
+
+def test_get_nonexistent_entity_returns_none() -> None:
+    s = _store()
+    assert s.get_entity("does-not-exist") is None
+
+
+def test_update_entity_replaces_data() -> None:
+    s = _store()
+    s.store_entity("e1", {"content": "original"})
+    s.store_entity("e1", {"content": "updated"})
+    result = s.get_entity("e1")
+    assert result is not None
+    assert result["content"] == "updated"
+
+
+def test_query_entities_returns_matching() -> None:
+    s = _store()
+    s.store_entity("s1", {"content": "data1"})
+    s.store_entity("s2", {"content": "data2"})
+    results = s.query_entities(["s1", "s2"])
+    assert "s1" in results
+    assert "s2" in results
+    assert results["s1"]["content"] == "data1"
+
+
+def test_query_entities_absent_returns_empty() -> None:
+    s = _store()
+    results = s.query_entities(["not-here"])
+    assert results == {}
+
+
+def test_classification_ceiling_barrier2() -> None:
+    """Barrier 2: entities above classification_max are excluded."""
+    s = _store()
+    s.store_entity("public-data", {"content": "public"}, classification=0)
+    s.store_entity("secret-data", {"content": "secret"}, classification=3)
+
+    # classification_max=0: only public data returned
+    results = s.query_entities(["public-data", "secret-data"], classification_max=0)
+    assert "public-data" in results
+    assert "secret-data" not in results
+
+    # classification_max=3: both returned
+    results = s.query_entities(["public-data", "secret-data"], classification_max=3)
+    assert "public-data" in results
+    assert "secret-data" in results
+
+
+def test_classification_stored_and_retrieved() -> None:
+    s = _store()
+    s.store_entity("classified", {"content": "sensitive"}, classification=2)
+    assert s.get_entity_classification("classified") == 2
+    assert s.get_entity_classification("unknown") == 0
+
+
+def test_entity_count() -> None:
+    s = _store()
+    assert s.entity_count() == 0
+    s.store_entity("e1", {"x": 1})
+    s.store_entity("e2", {"x": 2})
+    assert s.entity_count() == 2
+
+
+def test_integer_values_round_trip() -> None:
+    s = _store()
+    s.store_entity("e1", {"count": 42, "label": "test"})
+    result = s.get_entity("e1")
+    assert result is not None
+    assert result["count"] == 42
+
+
+def test_three_named_graphs_exist() -> None:
+    """The three Named Graph URIs must be present after store init."""
+    from aevum.store.oxigraph.store import GRAPH_CONSENT, GRAPH_KNOWLEDGE, GRAPH_PROVENANCE
+    s = _store()
+    graphs = {str(g) for g in s._store.named_graphs()}
+    assert str(GRAPH_KNOWLEDGE) in graphs
+    assert str(GRAPH_PROVENANCE) in graphs
+    assert str(GRAPH_CONSENT) in graphs
+
+
+def test_clear_does_not_affect_consent_graph() -> None:
+    """clear_knowledge_graph must not touch urn:aevum:consent."""
+    from aevum.store.oxigraph.store import GRAPH_CONSENT
+    s = _store()
+    s.store_entity("e1", {"content": "data"})
+    s.clear_knowledge_graph()
+    assert s.get_entity("e1") is None
+    # Consent graph still exists
+    graphs = {str(g) for g in s._store.named_graphs()}
+    assert str(GRAPH_CONSENT) in graphs
+
+
+def test_thread_safety() -> None:
+    """Concurrent writes must not corrupt the store."""
+    import threading
+    s = _store()
+    errors: list[str] = []
+
+    def write(i: int) -> None:
+        try:
+            s.store_entity(f"entity-{i}", {"value": i})
+        except Exception as e:
+            errors.append(str(e))
+
+    threads = [threading.Thread(target=write, args=(i,)) for i in range(20)]
+    for t in threads:
+        t.start()
+    for t in threads:
+        t.join()
+
+    assert errors == [], f"Thread safety errors: {errors}"
+    assert s.entity_count() == 20