aevum-store-postgres 0.2.0__tar.gz

aevum_store_postgres-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_postgres-0.2.0/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: aevum-store-postgres
+Version: 0.2.0
+Summary: Aevum — PostgreSQL GraphStore + ConsentLedger backend (team 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: psycopg[binary]<4.0,>=3.1
+Description-Content-Type: text/markdown
+
+# aevum-store-postgres
+
+PostgreSQL-backed graph store for Aevum. Suitable for team deployments with shared state, concurrent writers, and durable persistence.
+
+```bash
+pip install aevum-store-postgres
+```
+
+```python
+import psycopg
+from aevum.core import Engine
+from aevum.store.postgres import PostgresStore
+from aevum.store.postgres.store import initialize_schema
+
+conn = psycopg.connect("postgresql://user:pass@localhost/aevum")
+initialize_schema(conn)
+engine = Engine(graph_store=PostgresStore(conn))
+```
+
+For single-node deployments without PostgreSQL, use `aevum-store-oxigraph` instead.
+See the [main repository README](https://github.com/aevum-labs/aevum) for backend selection guidance.

aevum_store_postgres-0.2.0/README.md

@@ -0,0 +1,21 @@
+# aevum-store-postgres
+
+PostgreSQL-backed graph store for Aevum. Suitable for team deployments with shared state, concurrent writers, and durable persistence.
+
+```bash
+pip install aevum-store-postgres
+```
+
+```python
+import psycopg
+from aevum.core import Engine
+from aevum.store.postgres import PostgresStore
+from aevum.store.postgres.store import initialize_schema
+
+conn = psycopg.connect("postgresql://user:pass@localhost/aevum")
+initialize_schema(conn)
+engine = Engine(graph_store=PostgresStore(conn))
+```
+
+For single-node deployments without PostgreSQL, use `aevum-store-oxigraph` instead.
+See the [main repository README](https://github.com/aevum-labs/aevum) for backend selection guidance.

aevum_store_postgres-0.2.0/pyproject.toml

@@ -0,0 +1,60 @@
+[project]
+name = "aevum-store-postgres"
+version = "0.2.0"
+description = "Aevum — PostgreSQL GraphStore + ConsentLedger backend (team 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",
+    "psycopg[binary]>=3.1,<4.0",
+]
+
+[project.scripts]
+aevum-store-migrate = "aevum.store.postgres.migrate:main"
+
+[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"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["ANN"]

aevum_store_postgres-0.2.0/src/aevum/store/postgres/__init__.py

@@ -0,0 +1,30 @@
+"""
+aevum.store.postgres -- PostgreSQL backends for graph, consent, and ledger.
+
+Usage:
+    from aevum.store.postgres import PostgresStore, PostgresConsentLedger, PostgresLedger
+    from aevum.store.postgres.ledger import initialize_ledger_schema
+    import psycopg
+
+    conn = psycopg.connect("postgresql://user:pass@host/dbname")
+    initialize_schema(conn)           # graph + consent DDL
+    initialize_ledger_schema(conn)    # ledger DDL
+
+    store = PostgresStore(conn)
+    consent = PostgresConsentLedger(conn)
+    ledger = PostgresLedger(conn, sigchain)
+
+    engine = Engine(
+        graph_store=store,
+        consent_ledger=consent,
+        ledger=ledger,
+    )
+"""
+
+from aevum.store.postgres.consent import PostgresConsentLedger
+from aevum.store.postgres.ledger import PostgresLedger
+from aevum.store.postgres.store import PostgresStore
+
+__version__ = "0.1.0"
+
+__all__ = ["PostgresStore", "PostgresConsentLedger", "PostgresLedger"]

aevum_store_postgres-0.2.0/src/aevum/store/postgres/consent.py

@@ -0,0 +1,110 @@
+"""
+PostgresConsentLedger — ConsentLedgerProtocol backed by PostgreSQL.
+
+Grants stored as JSONB in aevum_consent_grants.
+OR-Set semantics: revocation wins over concurrent grants.
+Expiration checked in Python (matching InMemoryConsentLedger behaviour).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import threading
+from datetime import UTC, datetime
+from typing import Any
+
+from aevum.core.consent.models import ConsentGrant
+
+
+class PostgresConsentLedger:
+    """
+    ConsentLedgerProtocol implementation backed by PostgreSQL.
+
+    Args:
+        conn:  An open psycopg.Connection (autocommit=True recommended).
+        lock:  Optional shared Lock. Pass the same lock used by PostgresStore
+               when both share one connection.
+    """
+
+    def __init__(self, conn: Any, lock: threading.Lock | None = None) -> None:
+        self._conn = conn
+        self._lock = lock or threading.Lock()
+
+    # ── ConsentLedgerProtocol ──────────────────────────────────────────────────
+
+    def add_grant(self, grant: ConsentGrant) -> None:
+        """Upsert a consent grant. Replaces any prior record with the same grant_id."""
+        sql = """
+            INSERT INTO aevum_consent_grants (grant_id, grant_data)
+            VALUES (%s, %s::jsonb)
+            ON CONFLICT (grant_id) DO UPDATE SET grant_data = EXCLUDED.grant_data
+        """
+        with self._lock, self._conn.cursor() as cur:
+            cur.execute(sql, (grant.grant_id, json.dumps(grant.model_dump())))
+
+    def revoke_grant(self, grant_id: str) -> None:
+        """Mark a grant as revoked (immutable update via JSONB merge)."""
+        sql = """
+            UPDATE aevum_consent_grants
+            SET grant_data = jsonb_set(grant_data, '{revocation_status}', '"revoked"')
+            WHERE grant_id = %s
+        """
+        with self._lock, self._conn.cursor() as cur:
+            cur.execute(sql, (grant_id,))
+
+    def has_consent(
+        self,
+        *,
+        subject_id: str,
+        operation: str,
+        grantee_id: str,
+        purpose: str | None = None,
+    ) -> bool:
+        """
+        Return True if an active, unexpired grant covers this operation.
+
+        Mirrors InMemoryConsentLedger: loads candidates from DB, checks
+        expiration and operation in Python to stay consistent with the spec.
+        """
+        sql = """
+            SELECT grant_data
+            FROM aevum_consent_grants
+            WHERE grant_data->>'subject_id'       = %s
+              AND grant_data->>'grantee_id'        = %s
+              AND grant_data->>'revocation_status' = 'active'
+        """
+        with self._lock, self._conn.cursor() as cur:
+            cur.execute(sql, (subject_id, grantee_id))
+            rows = cur.fetchall()
+
+        now = datetime.now(UTC)
+        for row in rows:
+            raw = row[0]
+            d: dict[str, Any] = json.loads(raw) if isinstance(raw, str) else raw
+            if operation not in d.get("operations", []):
+                continue
+            try:
+                expires = datetime.fromisoformat(
+                    d["expires_at"].replace("Z", "+00:00")
+                )
+                if now > expires:
+                    continue
+            except (KeyError, ValueError):
+                continue
+            return True
+        return False
+
+    def all_grants(self) -> list[ConsentGrant]:
+        """Return all stored grants (active, revoked, and expired)."""
+        sql = "SELECT grant_data FROM aevum_consent_grants"
+        with self._lock, self._conn.cursor() as cur:
+            cur.execute(sql)
+            rows = cur.fetchall()
+        grants: list[ConsentGrant] = []
+        for row in rows:
+            raw = row[0]
+            d: dict[str, Any] = json.loads(raw) if isinstance(raw, str) else raw
+            with contextlib.suppress(Exception):
+                grants.append(ConsentGrant(**d))
+        return grants

aevum_store_postgres-0.2.0/src/aevum/store/postgres/ledger.py

@@ -0,0 +1,198 @@
+"""
+PostgresLedger -- persistent episodic ledger backed by PostgreSQL.
+
+AuditEvents are serialized as JSONB. Sigchain verification still works --
+verify_chain() reads all events in sequence order from Postgres.
+
+Barrier 4 (Audit Immutability) enforced by __delitem__ and __setitem__.
+The database table is INSERT-only -- no UPDATE or DELETE ever issued.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+from typing import Any
+
+from aevum.core.audit.event import AuditEvent
+from aevum.core.audit.sigchain import Sigchain
+from aevum.core.exceptions import BarrierViolationError, ReplayNotFoundError
+
+_DDL_LEDGER = """
+CREATE TABLE IF NOT EXISTS aevum_ledger (
+    sequence        BIGSERIAL PRIMARY KEY,
+    event_id        TEXT NOT NULL UNIQUE,
+    audit_id        TEXT NOT NULL UNIQUE,
+    event_type      TEXT NOT NULL,
+    actor           TEXT NOT NULL,
+    system_time     BIGINT NOT NULL,
+    episode_id      TEXT,
+    causation_id    TEXT,
+    correlation_id  TEXT,
+    prior_hash      TEXT NOT NULL,
+    payload_hash    TEXT NOT NULL,
+    signature       TEXT NOT NULL,
+    signer_key_id   TEXT NOT NULL,
+    schema_version  TEXT NOT NULL DEFAULT '1.0',
+    valid_from      TEXT NOT NULL,
+    valid_to        TEXT,
+    trace_id        TEXT,
+    span_id         TEXT,
+    payload         JSONB NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_aevum_ledger_audit_id ON aevum_ledger (audit_id);
+CREATE INDEX IF NOT EXISTS idx_aevum_ledger_sequence ON aevum_ledger (sequence);
+"""
+
+
+def initialize_ledger_schema(conn: Any) -> None:
+    """Create the aevum_ledger table if it does not exist."""
+    with conn.cursor() as cur:
+        cur.execute(_DDL_LEDGER)
+    conn.commit()
+
+
+def _event_to_row(event: AuditEvent) -> dict[str, Any]:
+    return {
+        "event_id": event.event_id,
+        "audit_id": event.audit_id(),
+        "event_type": event.event_type,
+        "actor": event.actor,
+        "system_time": event.system_time,
+        "episode_id": event.episode_id,
+        "causation_id": event.causation_id,
+        "correlation_id": event.correlation_id,
+        "prior_hash": event.prior_hash,
+        "payload_hash": event.payload_hash,
+        "signature": event.signature,
+        "signer_key_id": event.signer_key_id,
+        "schema_version": event.schema_version,
+        "valid_from": event.valid_from,
+        "valid_to": event.valid_to,
+        "trace_id": event.trace_id,
+        "span_id": event.span_id,
+        "payload": json.dumps(event.payload, default=str),
+    }
+
+
+def _row_to_event(row: dict[str, Any]) -> AuditEvent:
+    payload = row["payload"]
+    if isinstance(payload, str):
+        payload = json.loads(payload)
+    return AuditEvent(
+        event_id=row["event_id"],
+        episode_id=row.get("episode_id", ""),
+        sequence=row["sequence"],
+        event_type=row["event_type"],
+        schema_version=row.get("schema_version", "1.0"),
+        valid_from=row["valid_from"],
+        valid_to=row.get("valid_to"),
+        system_time=row["system_time"],
+        causation_id=row.get("causation_id"),
+        correlation_id=row.get("correlation_id"),
+        actor=row["actor"],
+        trace_id=row.get("trace_id"),
+        span_id=row.get("span_id"),
+        payload=payload,
+        payload_hash=row["payload_hash"],
+        prior_hash=row["prior_hash"],
+        signature=row["signature"],
+        signer_key_id=row["signer_key_id"],
+    )
+
+
+class PostgresLedger:
+    """
+    Persistent episodic ledger backed by PostgreSQL.
+
+    Thread-safe. INSERT-only (Barrier 4 at application layer).
+    Pass a shared threading.Lock if sharing a connection with PostgresStore.
+    """
+
+    def __init__(
+        self,
+        conn: Any,
+        sigchain: Sigchain,
+        lock: threading.Lock | None = None,
+    ) -> None:
+        self._conn = conn
+        self._sigchain = sigchain
+        self._lock = lock or threading.Lock()
+
+    def append(
+        self,
+        *,
+        event_type: str,
+        payload: dict[str, Any],
+        actor: str,
+        episode_id: str | None = None,
+        causation_id: str | None = None,
+        correlation_id: str | None = None,
+    ) -> AuditEvent:
+        with self._lock:
+            event = self._sigchain.new_event(
+                event_type=event_type,
+                payload=payload,
+                actor=actor,
+                episode_id=episode_id,
+                causation_id=causation_id,
+                correlation_id=correlation_id,
+            )
+            row = _event_to_row(event)
+            with self._conn.cursor() as cur:
+                cur.execute(
+                    """
+                    INSERT INTO aevum_ledger (
+                        event_id, audit_id, event_type, actor, system_time,
+                        episode_id, causation_id, correlation_id,
+                        prior_hash, payload_hash, signature, signer_key_id,
+                        schema_version, valid_from, valid_to,
+                        trace_id, span_id, payload
+                    ) VALUES (
+                        %(event_id)s, %(audit_id)s, %(event_type)s, %(actor)s,
+                        %(system_time)s, %(episode_id)s, %(causation_id)s,
+                        %(correlation_id)s, %(prior_hash)s, %(payload_hash)s,
+                        %(signature)s, %(signer_key_id)s, %(schema_version)s,
+                        %(valid_from)s, %(valid_to)s, %(trace_id)s,
+                        %(span_id)s, %(payload)s::jsonb
+                    )
+                    """,
+                    row,
+                )
+            self._conn.commit()
+            return event
+
+    def get(self, audit_id: str) -> AuditEvent:
+        from psycopg.rows import dict_row
+        with self._lock, self._conn.cursor(row_factory=dict_row) as cur:
+            cur.execute(
+                "SELECT * FROM aevum_ledger WHERE audit_id = %s",
+                (audit_id,),
+            )
+            row = cur.fetchone()
+        if row is None:
+            raise ReplayNotFoundError(f"No ledger entry for {audit_id!r}")
+        return _row_to_event(row)
+
+    def all_events(self) -> list[AuditEvent]:
+        from psycopg.rows import dict_row
+        with self._lock, self._conn.cursor(row_factory=dict_row) as cur:
+            cur.execute("SELECT * FROM aevum_ledger ORDER BY sequence ASC")
+            rows = cur.fetchall()
+        return [_row_to_event(r) for r in rows]
+
+    def count(self) -> int:
+        with self._lock, self._conn.cursor() as cur:
+            cur.execute("SELECT COUNT(*) FROM aevum_ledger")
+            result = cur.fetchone()
+        return result[0] if result else 0
+
+    def __delitem__(self, key: object) -> None:
+        raise BarrierViolationError(
+            "Attempted to delete a ledger entry -- Barrier 4 (Audit Immutability) violated."
+        )
+
+    def __setitem__(self, key: object, value: object) -> None:
+        raise BarrierViolationError(
+            "Attempted to overwrite a ledger entry -- Barrier 4 (Audit Immutability) violated."
+        )

aevum_store_postgres-0.2.0/src/aevum/store/postgres/migrate.py

@@ -0,0 +1,134 @@
+"""
+migrate_from_oxigraph — export Oxigraph data and import into PostgresStore.
+
+Usage:
+    from aevum.store.postgres.migrate import migrate_from_oxigraph
+    stats = migrate_from_oxigraph(
+        source_store=oxigraph_store,
+        target_store=postgres_store,
+        source_consent=in_memory_ledger,    # optional
+        target_consent=postgres_consent,    # optional
+    )
+    print(stats)  # {"entities": 42, "grants": 5}
+
+CLI (after installation):
+    aevum-store-migrate --source-dsn "" --target-dsn "postgresql://..."
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from aevum.store.postgres.consent import PostgresConsentLedger
+    from aevum.store.postgres.store import PostgresStore
+
+
+def migrate_from_oxigraph(
+    source_store: Any,
+    target_store: PostgresStore,
+    source_consent: Any | None = None,
+    target_consent: PostgresConsentLedger | None = None,
+) -> dict[str, int]:
+    """
+    Copy all entities and consent grants from an OxigraphStore to PostgresStore.
+
+    Args:
+        source_store:   An OxigraphStore instance (must have sparql_select,
+                        get_entity, get_entity_classification).
+        target_store:   The destination PostgresStore.
+        source_consent: Optional ConsentLedger to migrate grants from.
+        target_consent: Optional PostgresConsentLedger to migrate grants into.
+
+    Returns:
+        dict with counts: {"entities": <n>, "grants": <n>}
+    """
+    entities_migrated = 0
+    grants_migrated = 0
+
+    # --- Migrate entities ---
+    rows = source_store.sparql_select(
+        "SELECT DISTINCT ?s WHERE { GRAPH <urn:aevum:knowledge> { ?s ?p ?o } }"
+    )
+    for row in rows:
+        iri: str = row.get("s", "")
+        if not iri:
+            continue
+        # Strip namespace prefix added by OxigraphStore._entity_node
+        entity_id = iri[len("urn:aevum:entity:"):] if iri.startswith("urn:aevum:entity:") else iri
+
+        data = source_store.get_entity(entity_id)
+        if data is None:
+            # Try with the full IRI (entity_id was stored as IRI)
+            data = source_store.get_entity(iri)
+        if data is None:
+            continue
+
+        classification = source_store.get_entity_classification(entity_id)
+        target_store.store_entity(entity_id, data, classification)
+        entities_migrated += 1
+
+    # --- Migrate consent grants ---
+    if source_consent is not None and target_consent is not None:
+        for grant in source_consent.all_grants():
+            target_consent.add_grant(grant)
+            grants_migrated += 1
+
+    return {"entities": entities_migrated, "grants": grants_migrated}
+
+
+def main() -> None:
+    """CLI entry point for aevum-store-migrate."""
+    parser = argparse.ArgumentParser(
+        description="Migrate Aevum data from Oxigraph to PostgreSQL"
+    )
+    parser.add_argument(
+        "--source-path",
+        default=None,
+        help="Path to Oxigraph store directory (omit for in-memory — useful only for testing)",
+    )
+    parser.add_argument(
+        "--target-dsn",
+        required=True,
+        help="PostgreSQL DSN (e.g. postgresql://user:pass@localhost/aevum)",
+    )
+    args = parser.parse_args()
+
+    try:
+        import psycopg
+    except ImportError:
+        print("psycopg is required: pip install psycopg[binary]", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        from aevum.store.oxigraph import OxigraphStore
+    except ImportError:
+        print("aevum-store-oxigraph is required for migration", file=sys.stderr)
+        sys.exit(1)
+
+    from aevum.store.postgres import PostgresConsentLedger, PostgresStore
+    from aevum.store.postgres.schema import initialize_schema
+
+    source = OxigraphStore(args.source_path)
+    conn = psycopg.connect(args.target_dsn, autocommit=True)
+    initialize_schema(conn)
+
+    import threading
+    lock = threading.Lock()
+    target = PostgresStore(conn, lock)
+    target_consent = PostgresConsentLedger(conn, lock)
+
+    stats = migrate_from_oxigraph(
+        source_store=source,
+        target_store=target,
+        source_consent=None,
+        target_consent=target_consent,
+    )
+    conn.close()
+    print(f"Migration complete: {stats['entities']} entities, {stats['grants']} grants")
+
+
+if __name__ == "__main__":
+    main()

aevum_store_postgres-0.2.0/src/aevum/store/postgres/schema.py

@@ -0,0 +1,33 @@
+"""
+DDL for the Aevum PostgreSQL schema.
+
+Two tables:
+  aevum_entities       — entity data + classification (GraphStore backend)
+  aevum_consent_grants — consent grants as JSONB (ConsentLedger backend)
+
+Call initialize_schema(conn) once after connecting.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+_DDL = """\
+CREATE TABLE IF NOT EXISTS aevum_entities (
+    entity_id      TEXT        PRIMARY KEY,
+    data           JSONB       NOT NULL,
+    classification INT         NOT NULL DEFAULT 0,
+    ingested_at    TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE IF NOT EXISTS aevum_consent_grants (
+    grant_id   TEXT  PRIMARY KEY,
+    grant_data JSONB NOT NULL
+);
+"""
+
+
+def initialize_schema(conn: Any) -> None:
+    """Create Aevum tables if they do not already exist."""
+    with conn.cursor() as cur:
+        cur.execute(_DDL)