aethergraph 0.1.0a1__py3-none-any.whl → 0.1.0a2__py3-none-any.whl

aethergraph/storage/eventlog/sqlite_event_sync.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+import json
+from pathlib import Path
+import sqlite3
+import threading
+import time
+from typing import Any
+
+"""
+This is not used in the main codebase; only used by async wrapper SqliteEventLog.
+"""
+
+
+class SQLiteEventLogSync:
+    def __init__(self, path: str):
+        path_obj = Path(path)
+        path_obj.parent.mkdir(parents=True, exist_ok=True)
+
+        self._db = sqlite3.connect(
+            str(path_obj),
+            check_same_thread=False,
+            isolation_level=None,
+        )
+        self._lock = threading.RLock()
+        self._initialize_db()
+
+    def _initialize_db(self) -> None:
+        self._db.execute(
+            """
+            CREATE TABLE IF NOT EXISTS events (
+                id        INTEGER PRIMARY KEY AUTOINCREMENT,
+                ts        REAL NOT NULL,
+                scope_id  TEXT,
+                kind      TEXT,
+                tags_json TEXT,
+                payload   TEXT NOT NULL,
+                -- new tenant / dimension columns
+                user_id   TEXT,
+                org_id    TEXT,
+                run_id    TEXT,
+                session_id TEXT
+            )
+            """
+        )
+        # Migration for existing DBs
+        cols = {row[1] for row in self._db.execute("PRAGMA table_info(events)").fetchall()}
+        if "user_id" not in cols:
+            self._db.execute("ALTER TABLE events ADD COLUMN user_id TEXT")
+        if "org_id" not in cols:
+            self._db.execute("ALTER TABLE events ADD COLUMN org_id TEXT")
+        if "run_id" not in cols:
+            self._db.execute("ALTER TABLE events ADD COLUMN run_id TEXT")
+        if "session_id" not in cols:
+            self._db.execute("ALTER TABLE events ADD COLUMN session_id TEXT")
+
+        # Existing indexes
+        self._db.execute("CREATE INDEX IF NOT EXISTS idx_events_scope ON events(scope_id)")
+        self._db.execute("CREATE INDEX IF NOT EXISTS idx_events_kind  ON events(kind)")
+        self._db.execute("CREATE INDEX IF NOT EXISTS idx_events_ts    ON events(ts)")
+
+        # tenant-aware indexes
+        self._db.execute("CREATE INDEX IF NOT EXISTS idx_events_user_ts ON events(user_id, ts)")
+        self._db.execute("CREATE INDEX IF NOT EXISTS idx_events_org_ts ON events(org_id, ts)")
+        self._db.execute("CREATE INDEX IF NOT EXISTS idx_events_run_ts ON events(run_id, ts)")
+
+    def append(self, evt: dict) -> None:
+        row = dict(evt)
+
+        ts = row.get("ts")
+        if isinstance(ts, datetime):
+            ts = ts.timestamp()
+        elif isinstance(ts, int | float):
+            ts = float(ts)
+        elif isinstance(ts, str):
+            # Handle ISO 8601 timestamps like '2025-11-27T19:48:09.758687+00:00' or ...Z
+            try:
+                s = ts.replace("Z", "+00:00") if ts.endswith("Z") else ts
+                dt = datetime.fromisoformat(s)
+                if dt.tzinfo is None:
+                    dt = dt.replace(tzinfo=timezone.utc)
+                ts = dt.timestamp()
+            except Exception:
+                # Fallback: current time if we can't parse
+                ts = time.time()
+
+        if ts is None:
+            ts = time.time()
+
+        scope_id = row.get("scope_id")
+        kind = row.get("kind")
+        tags = row.get("tags") or []
+        tags_json = json.dumps(tags, ensure_ascii=False)
+
+        # tenant & run dims (not all events will have these fields. Chat events can just use session_id to retrieve info after optional authentication)
+        user_id = row.get("user_id")
+        org_id = row.get("org_id")
+        run_id = row.get("run_id")
+        session_id = row.get("session_id")
+
+        # Optionally overwrite the ts in the payload to the normalized float
+        row["ts"] = ts
+        payload = json.dumps(row, ensure_ascii=False)
+
+        with self._lock:
+            self._db.execute(
+                """
+                INSERT INTO events (ts, scope_id, kind, tags_json, payload, user_id, org_id, run_id, session_id)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (ts, scope_id, kind, tags_json, payload, user_id, org_id, run_id, session_id),
+            )
+
+    def query(
+        self,
+        *,
+        scope_id: str | None = None,
+        since: datetime | None = None,
+        until: datetime | None = None,
+        kinds: list[str] | None = None,
+        limit: int | None = None,
+        tags: list[str] | None = None,
+        offset: int = 0,
+        user_id: str | None = None,
+        org_id: str | None = None,
+    ) -> list[dict]:
+        where: list[str] = []
+        params: list[Any] = []
+
+        if scope_id is not None:
+            where.append("scope_id = ?")
+            params.append(scope_id)
+
+        if since is not None:
+            where.append("ts >= ?")
+            params.append(since.timestamp())
+
+        if until is not None:
+            where.append("ts <= ?")
+            params.append(until.timestamp())
+
+        if kinds:
+            where.append(f"kind IN ({', '.join('?' for _ in kinds)})")
+            params.extend(kinds)
+
+        # Tenant-level filters for metering
+        if user_id is not None:
+            where.append("user_id = ?")
+            params.append(user_id)
+        if org_id is not None:
+            where.append("org_id = ?")
+            params.append(org_id)
+
+        sql = "SELECT payload, tags_json FROM events"
+        if where:
+            sql += " WHERE " + " AND ".join(where)
+        sql += " ORDER BY ts ASC"
+
+        with self._lock:
+            rows = self._db.execute(sql, params).fetchall()
+
+        tags_set = set(tags or [])
+        filtered: list[dict] = []
+        for payload_str, tags_json in rows:
+            evt = json.loads(payload_str)
+            if tags:
+                row_tags = set(json.loads(tags_json) or [])
+                if not row_tags.issuperset(tags_set):
+                    continue
+            filtered.append(evt)
+
+        if offset:
+            filtered = filtered[offset:]
+        if limit is not None:
+            filtered = filtered[:limit]
+
+        return filtered

aethergraph/storage/factory.py

@@ -0,0 +1,432 @@
+import os
+from pathlib import Path
+
+from aethergraph.config.config import AppSettings, ContinuationStoreSettings
+from aethergraph.contracts.services.continuations import AsyncContinuationStore
+from aethergraph.contracts.services.kv import AsyncKV
+from aethergraph.contracts.services.memory import HotLog, Indices, Persistence
+from aethergraph.contracts.services.runs import RunStore
+from aethergraph.contracts.services.state_stores import GraphStateStore
+from aethergraph.contracts.storage.artifact_index import AsyncArtifactIndex
+from aethergraph.contracts.storage.artifact_store import AsyncArtifactStore
+from aethergraph.contracts.storage.doc_store import DocStore
+from aethergraph.contracts.storage.event_log import EventLog
+
+
+def build_doc_store(cfg: AppSettings) -> DocStore:
+    """
+    Global DocStore factory, used by:
+      - Memory persistence (EventLogPersistence)
+      - RAG
+      - Continuations (if you choose to share it)
+      - Anything else that wants "document-ish" JSON blobs.
+    """
+    root = Path(cfg.root).resolve()
+    dc = cfg.storage.docs
+
+    if dc.backend == "sqlite":
+        from aethergraph.storage.docstore.sqlite_doc import SqliteDocStore
+
+        path = root / dc.sqlite_path
+        path.parent.mkdir(parents=True, exist_ok=True)
+        return SqliteDocStore(path=str(path))
+
+    if dc.backend == "fs":
+        from aethergraph.storage.docstore.fs_doc import FSDocStore
+
+        doc_root = root / dc.fs_dir
+        doc_root.mkdir(parents=True, exist_ok=True)
+        return FSDocStore(root=str(doc_root))
+
+    raise ValueError(f"Unknown DocStore backend: {dc.backend!r}")
+
+
+def build_event_log(cfg: AppSettings, service_name: str | None = None) -> EventLog | None:
+    """
+    Global EventLog factory.
+    Used by:
+      - GraphStateStore (if you want)
+      - Memory (EventLogPersistence)
+      - Continuations audit (optional)
+    """
+    root = Path(cfg.root).resolve()
+    ec = cfg.storage.eventlog
+
+    if ec.backend == "none":
+        return None
+
+    if ec.backend == "sqlite":
+        from aethergraph.storage.eventlog.sqlite_event import SqliteEventLog
+
+        # If you use a different DB file per service, you get isolation between services,
+        # but lose global querying and may have more files to manage.
+        # If you use a single DB file, all services share the same event log table(s).
+        path = root / ec.sqlite_path  # You could do: root / f"{service_name}_{ec.sqlite_path}"
+        path.parent.mkdir(parents=True, exist_ok=True)
+        return SqliteEventLog(path=str(path))
+
+    if ec.backend == "fs":
+        from aethergraph.storage.eventlog.fs_event import FSEventLog
+
+        ev_root = root / ec.fs_dir if not service_name else root / ec.fs_dir / service_name
+        ev_root.mkdir(parents=True, exist_ok=True)
+        return FSEventLog(root=str(ev_root))
+
+    raise ValueError(f"Unknown EventLog backend: {ec.backend!r}")
+
+
+def build_kv_store(cfg: AppSettings, *, extra_prefix: str = "") -> AsyncKV:
+    """
+    Global KV factory.
+
+    extra_prefix lets subsystems (memory, continuations, etc.) add their own
+    namespace on top of the global storage.kv.prefix.
+    """
+    root = Path(cfg.root).resolve()
+    kc = cfg.storage.kv
+
+    full_prefix = f"{kc.prefix}{extra_prefix}"
+
+    if kc.backend == "sqlite":
+        from aethergraph.storage.kv.sqlite_kv import SqliteKV
+
+        path = root / kc.sqlite_path
+        path.parent.mkdir(parents=True, exist_ok=True)
+        return SqliteKV(path=str(path), prefix=full_prefix)
+
+    if kc.backend == "inmem":
+        from aethergraph.storage.kv.inmem_kv import InMemoryKV
+
+        return InMemoryKV(prefix=full_prefix)
+
+    raise ValueError(f"Unknown KV backend: {kc.backend!r}")
+
+
+def build_artifact_store(cfg: AppSettings) -> AsyncArtifactStore:
+    """
+    Decide which artifact store backend to use based on AppSettings.storage.artifacts.
+    """
+    art_cfg = cfg.storage.artifacts
+    root = os.path.abspath(cfg.root)
+
+    if art_cfg.backend == "fs":
+        from aethergraph.storage.artifacts.fs_cas import FSArtifactStore
+
+        base_dir = os.path.join(root, art_cfg.fs.base_dir)
+        return FSArtifactStore(base_dir=base_dir)
+
+    if art_cfg.backend == "s3":
+        from aethergraph.storage.artifacts.s3_cas import (
+            S3ArtifactStore,  # late import to avoid boto3 dependency if unused
+        )
+
+        if not art_cfg.s3.bucket:
+            raise ValueError("S3 backend selected, but STORAGE__ARTIFACTS__S3__BUCKET is empty")
+
+        staging_dir = art_cfg.s3.staging_dir
+        if not staging_dir:
+            staging_dir = os.path.join(root, ".aethergraph_tmp", "artifacts")
+        return S3ArtifactStore(
+            bucket=art_cfg.s3.bucket,
+            prefix=art_cfg.s3.prefix,
+            staging_dir=staging_dir,
+        )
+
+    raise ValueError(f"Unknown artifacts backend: {art_cfg.backend!r}")
+
+
+def build_artifact_index(cfg: AppSettings) -> AsyncArtifactIndex:
+    idx_cfg = cfg.storage.artifact_index
+    root = os.path.abspath(cfg.root)
+
+    if idx_cfg.backend == "jsonl":
+        from aethergraph.storage.artifacts.artifact_index_jsonl import JsonlArtifactIndex
+
+        path = os.path.join(root, idx_cfg.jsonl.path)
+        occ = (
+            os.path.join(root, idx_cfg.jsonl.occurrences_path)
+            if idx_cfg.jsonl.occurrences_path
+            else None
+        )
+        return JsonlArtifactIndex(path=path, occurrences_path=occ)
+
+    if idx_cfg.backend == "sqlite":
+        from aethergraph.storage.artifacts.artifact_index_sqlite import SqliteArtifactIndex
+
+        path = os.path.join(root, idx_cfg.sqlite.path)
+        return SqliteArtifactIndex(path=path)
+
+    raise ValueError(f"Unknown artifact index backend: {idx_cfg.backend!r}")
+
+
+def build_graph_state_store(cfg: AppSettings) -> GraphStateStore:
+    from aethergraph.storage.graph_state_store.state_store import GraphStateStoreImpl
+
+    gs_cfg = cfg.storage.graph_state
+
+    if gs_cfg.backend == "fs":
+        from aethergraph.storage.docstore.fs_doc import FSDocStore
+        from aethergraph.storage.eventlog.fs_event import FSEventLog
+
+        base = os.path.join(cfg.root, gs_cfg.fs_root)
+        docs = FSDocStore(os.path.join(base, "docs"))
+        log = FSEventLog(os.path.join(base, "events"))
+    elif gs_cfg.backend == "sqlite":
+        from aethergraph.storage.docstore.sqlite_doc import SqliteDocStore
+        from aethergraph.storage.eventlog.sqlite_event import SqliteEventLog
+
+        db_path = os.path.join(cfg.root, gs_cfg.sqlite_path)
+        docs = SqliteDocStore(db_path)
+        log = SqliteEventLog(db_path)
+    else:
+        raise ValueError(f"Unknown graph_state backend: {gs_cfg.backend!r}")
+
+    return GraphStateStoreImpl(doc_store=docs, event_log=log)
+
+
+def build_run_store(cfg: AppSettings) -> RunStore:
+    """
+    Factory for RunStore:
+
+      - "memory": InMemoryRunStore (no persistence)
+      - "fs":     DocRunStore on top of FSDocStore
+      - "sqlite": DocRunStore on top of SqliteDocStore
+    """
+    rs_cfg = cfg.storage.runs
+
+    if rs_cfg.backend == "memory":
+        from aethergraph.storage.runs.inmen_store import InMemoryRunStore
+
+        return InMemoryRunStore()
+
+    if rs_cfg.backend == "fs":
+        from aethergraph.storage.docstore.fs_doc import FSDocStore
+        from aethergraph.storage.runs.doc_store import DocRunStore
+
+        base = os.path.join(cfg.root, rs_cfg.fs_root)
+        docs = FSDocStore(base)
+        return DocRunStore(
+            docs, prefix="run-"
+        )  # use "run-" prefix to avoid OS path issues on Windows
+
+    if rs_cfg.backend == "sqlite":
+        from aethergraph.storage.runs.sqlite_run_store import SQLiteRunStore
+
+        db_path = os.path.join(cfg.root, rs_cfg.sqlite_path)
+        return SQLiteRunStore(path=db_path)
+
+    raise ValueError(f"Unknown run storage backend: {rs_cfg.backend!r}")
+
+
+def build_session_store(cfg: AppSettings):
+    """
+    Factory for SessionStore:
+
+      - "memory": InMemorySessionStore (no persistence)
+      - "fs":     DocSessionStore on top of FSDocStore
+      - "sqlite": DocSessionStore on top of SqliteDocStore
+    """
+    ss_cfg = cfg.storage.sessions
+
+    if ss_cfg.backend == "memory":
+        # If you want pure dict-backed like your original snippet, keep it.
+        # Otherwise you can also implement InMemoryDocStore + DocSessionStore.
+        from aethergraph.storage.sessions.inmem_store import InMemorySessionStore
+
+        return InMemorySessionStore()
+
+    if ss_cfg.backend == "fs":
+        from aethergraph.storage.docstore.fs_doc import FSDocStore
+        from aethergraph.storage.sessions.doc_store import DocSessionStore
+
+        base = os.path.join(cfg.root, ss_cfg.fs_root)
+        docs = FSDocStore(base)
+        return DocSessionStore(docs, prefix="session-")  # windows-safe
+
+    if ss_cfg.backend == "sqlite":
+        from aethergraph.storage.sessions.sqlite_session_store import SQLiteSessionStore
+
+        db_path = os.path.join(cfg.root, ss_cfg.sqlite_path)
+        return SQLiteSessionStore(path=db_path)
+    raise ValueError(f"Unknown session storage backend: {ss_cfg.backend!r}")
+
+
+def _secret_bytes(secret_key: str) -> bytes:
+    # simple default; support hex/env later if needed
+    return secret_key.encode("utf-8")
+
+
+def _build_kvdoc_cont_store(
+    root: Path,
+    cfg: ContinuationStoreSettings,
+    secret: bytes,
+) -> AsyncContinuationStore:
+    kvdoc = cfg.kvdoc
+    from aethergraph.storage.continuation_store.kvdoc_cont import KVDocContinuationStore
+
+    # ---- DocStore ----
+    if kvdoc.doc_store_backend == "sqlite":
+        from aethergraph.storage.docstore.sqlite_doc import SqliteDocStore
+
+        doc_path = root / kvdoc.sqlite_doc_store_path
+        doc_path.parent.mkdir(parents=True, exist_ok=True)
+        doc_store: DocStore = SqliteDocStore(path=str(doc_path))
+    elif kvdoc.doc_store_backend == "fs":
+        from aethergraph.storage.docstore.fs_doc import FSDocStore
+
+        doc_dir = root / kvdoc.fs_doc_store_dir
+        doc_dir.mkdir(parents=True, exist_ok=True)
+        doc_store = FSDocStore(root=str(doc_dir))
+    else:
+        raise ValueError(f"Unknown doc_store_backend: {kvdoc.doc_store_backend}")
+
+    # ---- KV ----
+    if kvdoc.kv_backend == "sqlite":
+        from aethergraph.storage.kv.sqlite_kv import SqliteKV
+
+        kv_path = root / kvdoc.sqlite_kv_path
+        kv_path.parent.mkdir(parents=True, exist_ok=True)
+        kv: AsyncKV = SqliteKV(path=str(kv_path), prefix=f"{cfg.namespace}:")
+    elif kvdoc.kv_backend == "inmem":
+        from aethergraph.storage.kv.inmem_kv import InMemoryKV
+
+        kv = InMemoryKV(prefix=f"{cfg.namespace}:")
+    else:
+        raise ValueError(f"Unknown kv_backend: {kvdoc.kv_backend}")
+
+    # ---- EventLog (optional) ----
+    event_log: EventLog | None
+    if kvdoc.eventlog_backend == "none":
+        event_log = None
+    elif kvdoc.eventlog_backend == "sqlite":
+        from aethergraph.storage.eventlog.sqlite_event import SqliteEventLog
+
+        ev_path = root / kvdoc.sqlite_eventlog_path
+        ev_path.parent.mkdir(parents=True, exist_ok=True)
+        event_log = SqliteEventLog(path=str(ev_path))
+    elif kvdoc.eventlog_backend == "fs":
+        from aethergraph.storage.eventlog.fs_event import FSEventLog
+
+        ev_dir = root / kvdoc.fs_eventlog_dir
+        ev_dir.mkdir(parents=True, exist_ok=True)
+        event_log = FSEventLog(root=str(ev_dir))
+    else:
+        raise ValueError(f"Unknown eventlog_backend: {kvdoc.eventlog_backend}")
+
+    return KVDocContinuationStore(
+        doc_store=doc_store,
+        kv=kv,
+        event_log=event_log,
+        secret=secret,
+        namespace=cfg.namespace,
+    )
+
+
+def build_continuation_store(cfg: AppSettings) -> AsyncContinuationStore:
+    """
+    High-level factory used by your runtime builder.
+
+    Mirrors `build_artifact_store(cfg)` in style.
+    """
+    root = Path(cfg.root).resolve()
+    cont_cfg: ContinuationStoreSettings = cfg.storage.continuation
+    secret = _secret_bytes(cont_cfg.secret_key)
+
+    if cont_cfg.backend == "memory":
+        from aethergraph.services.continuations.stores.inmem_store import InMemoryContinuationStore
+
+        return InMemoryContinuationStore(secret=secret)
+
+    if cont_cfg.backend == "fs":
+        from aethergraph.services.continuations.stores.fs_store import FSContinuationStore
+
+        # Keep old FS behavior for people who rely on on-disk layout.
+        fs_root = root / cont_cfg.fs.root
+        fs_root.parent.mkdir(parents=True, exist_ok=True)
+        return FSContinuationStore(root=fs_root, secret=secret)
+
+    if cont_cfg.backend == "kvdoc":
+        return _build_kvdoc_cont_store(root, cont_cfg, secret)
+
+    raise ValueError(f"Unknown continuation backend: {cont_cfg.backend}")
+
+
+def build_vector_index(cfg: AppSettings):
+    """
+    Build a VectorIndex based on cfg.storage.vector_index.
+    """
+    vcfg = cfg.storage.vector_index
+    root = os.path.abspath(cfg.root)
+
+    if vcfg.backend == "sqlite":
+        from aethergraph.storage.vector_index.sqlite_index import SQLiteVectorIndex
+
+        index_root = os.path.join(root, vcfg.sqlite.dir)
+        return SQLiteVectorIndex(root=index_root)
+
+    if vcfg.backend == "faiss":
+        from aethergraph.storage.vector_index.faiss_index import FAISSVectorIndex
+
+        index_root = os.path.join(root, vcfg.faiss.dir)
+        return FAISSVectorIndex(root=index_root, dim=vcfg.faiss.dim)
+
+    if vcfg.backend == "chroma":
+        try:
+            import chromadb
+        except ImportError as e:
+            chromadb = None  # type: ignore
+            raise RuntimeError("Chroma backend requires `chromadb` to be installed.") from e
+        from aethergraph.storage.vector_index.chroma_index import ChromaVectorIndex
+
+        if chromadb is None:
+            raise RuntimeError(
+                "Chroma backend selected, but `chromadb` is not installed. "
+                "Install it with `pip install chromadb`."
+            )
+        persist_dir = os.path.join(root, vcfg.chroma.persist_dir)
+        client = chromadb.PersistentClient(path=persist_dir)
+        return ChromaVectorIndex(
+            client=client,
+            collection_prefix=vcfg.chroma.collection_prefix,
+        )
+
+    raise ValueError(f"Unknown vector index backend: {vcfg.backend!r}")
+
+
+def build_memory_persistence(cfg: AppSettings) -> Persistence:
+    mp = cfg.storage.memory.persistence
+    root = cfg.root
+
+    if mp.backend == "fs":
+        from aethergraph.storage.memory.fs_persist import FSPersistence
+
+        return FSPersistence(base_dir=root)
+
+    if mp.backend == "eventlog":
+        from aethergraph.storage.memory.event_persist import EventLogPersistence
+
+        docs = build_doc_store(cfg)
+        log = build_event_log(cfg)
+        if log is None:
+            raise ValueError("memory.persistence.backend=eventlog requires a non-none EventLog")
+        return EventLogPersistence(
+            log=log,
+            docs=docs,
+            uri_prefix=mp.uri_prefix,
+        )
+
+    raise ValueError(f"Unknown memory persistence backend: {mp.backend!r}")
+
+
+def build_memory_hotlog(cfg: AppSettings) -> HotLog:
+    from aethergraph.storage.memory.hotlog import KVHotLog
+
+    kv = build_kv_store(cfg, extra_prefix="mem:hot:")
+    return KVHotLog(kv=kv)
+
+
+def build_memory_indices(cfg: AppSettings) -> Indices:
+    from aethergraph.storage.memory.indices import KVIndices
+
+    kv = build_kv_store(cfg, extra_prefix="mem:idx:")
+    return KVIndices(kv=kv, hot_ttl_s=cfg.storage.memory.indices.ttl_s)

aethergraph/storage/fs_utils.py

@@ -0,0 +1,28 @@
+import asyncio
+from pathlib import Path
+from urllib.parse import unquote, urlparse
+from urllib.request import url2pathname
+
+
+async def to_thread(fn, *a, **k):
+    return await asyncio.to_thread(fn, *a, **k)
+
+
+def _to_file_uri(path_str: str) -> str:
+    """Canonical RFC-8089 file URI (file:///C:/..., forward slashes)."""
+    return Path(path_str).resolve().as_uri()
+
+
+def _from_uri_or_path(s: str) -> Path:
+    """Robustly turn a file:// URI or plain path into a local Path."""
+    if "://" not in s:
+        return Path(s)
+    u = urlparse(s)
+    if (u.scheme or "").lower() != "file":
+        raise ValueError(f"Unsupported URI scheme: {u.scheme}")
+    # if u.netloc:
+    #     raw = f"//{u.netloc}{u.path}"   # UNC: file://server/share/...
+    # else:
+    #     raw = u.path                    # Local drive: file:///C:/...
+    raw = f"//{u.netloc}{u.path}" if u.netloc else u.path
+    return Path(url2pathname(unquote(raw)))

aethergraph/storage/graph_state_store/state_store.py

@@ -0,0 +1,64 @@
+import time
+
+from aethergraph.contracts.services.state_stores import GraphSnapshot, GraphStateStore, StateEvent
+from aethergraph.contracts.storage.doc_store import DocStore
+from aethergraph.contracts.storage.event_log import EventLog
+
+
+class GraphStateStoreImpl(GraphStateStore):
+    """
+    Generic GraphStateStore implementation that combines a DocStore for snapshots
+    - DocStore for storing GraphSnapshot documents
+    - EventLog for storing StateEvent logs
+    """
+
+    def __init__(self, *, doc_store: "DocStore", event_log: "EventLog"):
+        self._docs = doc_store
+        self._log = event_log
+
+    def _snapshot_id(self, run_id: str) -> str:
+        return f"graph_state/{run_id}/latest"
+
+    async def save_snapshot(self, snap: GraphSnapshot) -> None:
+        # TODO: consider add history of snapshots by rev/timestamp
+        # e.g. hist_id = f"graph_state/{run_id}/rev_{snap.rev:08d}_{int(snap.created_at)}"
+        # self._docs.put(hist_id, snap.__dict__)
+        # but this is not needed for retrieval of latest snapshot
+        await self._docs.put(self._snapshot_id(snap.run_id), snap.__dict__)
+
+    async def load_latest_snapshot(self, run_id) -> GraphSnapshot | None:
+        # The saved snapshot is always the latest so just fetch by fixed id
+        doc = await self._docs.get(self._snapshot_id(run_id))
+        return GraphSnapshot(**doc) if doc else None
+
+    async def append_event(self, ev: StateEvent) -> None:
+        # standard event log append
+        payload = ev.__dict__.copy()
+        payload.setdefault("scope_id", ev.run_id)
+        payload.setdefault("kind", "graph_state")
+        payload.setdefault("ts", time.time())
+        await self._log.append(payload)
+
+    async def load_events_since(self, run_id, from_rev) -> list[StateEvent]:
+        rows = await self._log.query(
+            scope_id=run_id,
+            kinds=["graph_state"],
+            # from_rev filter will be applied below
+        )
+        out = []
+        for row in rows:
+            if row.get("rev", -1) > from_rev:
+                out.append(StateEvent(**row))
+        return out
+
+    async def list_run_ids(self, graph_id: str | None = None) -> list[str]:
+        # Basic version: ask DocStore for all ids and filter. This is sufficient for local/file-based stores.
+        # In cloud implementations, this should be optimized with proper indexing
+        ids = await self._docs.list()
+        runs: set[str] = set()
+        for doc_id in ids:
+            if not doc_id.startswith("graph_state/"):
+                continue
+            _, run_id, *_ = doc_id.split("/")
+            runs.add(run_id)
+        return sorted(runs)