generic-ml-cache-core 0.2.0__py3-none-any.whl

generic_ml_cache_core/adapter/out/metrics/access_registry.py

@@ -0,0 +1,147 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The access registry: a side log of cache access events for observability.
+
+It is **non-load-bearing by construction** -- it records *that* a hit / miss /
+record / eviction happened, for `stats` and `prune` to read, but it never gates
+correctness. Every operation swallows its own errors: if the database is missing,
+locked, unwritable, or corrupt, the cache still resolves exactly as it would
+without it. It is deliberately separate from the executions, which stay pure and
+immutable -- no access counters are ever written back into a recording.
+
+Stored in the store directory as ``registry.sqlite3`` (stdlib ``sqlite3`` only;
+no third-party dependency). It carries no integrity/checksum role: a checksum kept
+beside the data it guards, in a folder the user can write, protects nothing a
+determined editor couldn't also rewrite -- so we don't pretend to.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, Optional
+
+# The access events. A resolve emits exactly one of HIT / MISS / RECORD
+# (passthrough calls are outside cache accounting and emit nothing).
+HIT = "hit"
+MISS = "miss"
+RECORD = "record"
+
+_DB_NAME = "registry.sqlite3"
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS access_events (
+    id        INTEGER PRIMARY KEY AUTOINCREMENT,
+    ts        TEXT NOT NULL,
+    event     TEXT NOT NULL,
+    match_key TEXT,
+    client    TEXT,
+    model     TEXT,
+    effort    TEXT
+)
+"""
+
+
+class AccessRegistry:
+    """A best-effort SQLite log of access events, living beside the executions."""
+
+    def __init__(self, root: Path) -> None:
+        self._path = Path(root) / _DB_NAME
+
+    def _connect(self) -> sqlite3.Connection:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        conn = sqlite3.connect(self._path)
+        conn.execute(_SCHEMA)
+        return conn
+
+    def record(
+        self,
+        event: str,
+        *,
+        match_key: Optional[str],
+        client: str,
+        model: str,
+        effort: str,
+    ) -> None:
+        """Append one access event. Never raises -- failures are swallowed so the
+        cache is never affected by the registry being unavailable."""
+        try:
+            conn = self._connect()
+            try:
+                conn.execute(
+                    "INSERT INTO access_events (ts, event, match_key, client, model, effort) "
+                    "VALUES (?, ?, ?, ?, ?, ?)",
+                    (
+                        datetime.now(timezone.utc).isoformat(timespec="seconds"),
+                        event,
+                        match_key,
+                        client,
+                        model,
+                        effort,
+                    ),
+                )
+                conn.commit()
+            finally:
+                conn.close()
+        except Exception:
+            # Non-load-bearing: observability must never break the cache.
+            pass
+
+    def hit_counts_by_key(self) -> Dict[str, int]:
+        """Return {match_key: number-of-hits} across all recorded HIT events
+        ({} if unavailable).
+
+        A hit is a real call that was *not* made because a stored execution answered it,
+        so multiplying an execution's recorded usage by its hit count is exactly the
+        usage that hit saved. Best-effort like everything here: never raises.
+        """
+        try:
+            conn = self._connect()
+            try:
+                rows = conn.execute(
+                    "SELECT match_key, COUNT(*) FROM access_events "
+                    "WHERE event = ? AND match_key IS NOT NULL GROUP BY match_key",
+                    (HIT,),
+                ).fetchall()
+                return {key: int(count) for key, count in rows}
+            finally:
+                conn.close()
+        except Exception:
+            return {}
+
+    def event_counts(self) -> Dict[str, int]:
+        """Return {event: count} across all recorded events ({} if unavailable)."""
+        try:
+            conn = self._connect()
+            try:
+                rows = conn.execute(
+                    "SELECT event, COUNT(*) FROM access_events GROUP BY event"
+                ).fetchall()
+                return {event: count for event, count in rows}
+            finally:
+                conn.close()
+        except Exception:
+            return {}
+
+    def last_access(self) -> Dict[str, float]:
+        """Return {match_key: latest-event epoch seconds} for LRU eviction ordering
+        ({} if unavailable). An execution absent here has never been seen by the
+        registry; the caller falls back to file age for it."""
+        try:
+            conn = self._connect()
+            try:
+                rows = conn.execute(
+                    "SELECT match_key, MAX(ts) FROM access_events "
+                    "WHERE match_key IS NOT NULL GROUP BY match_key"
+                ).fetchall()
+            finally:
+                conn.close()
+        except Exception:
+            return {}
+        out: Dict[str, float] = {}
+        for key, ts in rows:
+            try:
+                out[key] = datetime.fromisoformat(ts).timestamp()
+            except Exception:
+                pass
+        return out

generic_ml_cache_core/adapter/out/metrics/journal_metrics.py

@@ -0,0 +1,45 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""JournalMetrics: the MetricsPort over the SQLite access registry."""
+
+from __future__ import annotations
+
+from typing import Dict, Optional
+
+from generic_ml_cache_core.adapter.out.metrics.access_registry import AccessRegistry
+from generic_ml_cache_core.application.port.out.metrics_port import MetricsPort
+
+
+class JournalMetrics(MetricsPort):
+    """Implements the journal over the existing best-effort access registry.
+
+    Non-load-bearing by construction: the registry swallows its own errors, so
+    ``record_event`` never raises and the projections return empty on failure —
+    observability never breaks an execution. This adapter only maps the port's
+    ``execution_key`` onto the registry's ``match_key``.
+    """
+
+    def __init__(self, registry: AccessRegistry) -> None:
+        self._registry = registry
+
+    def record_event(
+        self,
+        event: str,
+        *,
+        execution_key: Optional[str],
+        client: str,
+        model: str,
+        effort: str,
+    ) -> None:
+        self._registry.record(
+            event, match_key=execution_key, client=client, model=model, effort=effort
+        )
+
+    def hit_counts_by_key(self) -> Dict[str, int]:
+        return self._registry.hit_counts_by_key()
+
+    def event_counts(self) -> Dict[str, int]:
+        return self._registry.event_counts()
+
+    def last_access(self) -> Dict[str, float]:
+        return self._registry.last_access()

generic_ml_cache_core/adapter/out/persistence/__init__.py

@@ -0,0 +1 @@
+"""Hexagonal layer package."""

generic_ml_cache_core/adapter/out/persistence/call_identity_serialization.py

@@ -0,0 +1,100 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Serialize a polymorphic CallIdentity for the SQLite repository.
+
+The hybrid persistence (domain-model §3): the queryable fields (kind, client,
+model, effort) become real columns; the divergent/opaque fields ride in a JSON
+column. This pair maps each CallIdentity subclass to that row shape and back. It
+lives in the adapter — the domain identities know nothing about the database.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+
+from generic_ml_cache_core.application.domain.model.identity.api_call_identity import (
+    ApiCallIdentity,
+)
+from generic_ml_cache_core.application.domain.model.identity.call_identity import CallIdentity
+from generic_ml_cache_core.application.domain.model.execution.execution_kind import ExecutionKind
+from generic_ml_cache_core.application.domain.model.identity.managed_call_identity import (
+    ManagedCallIdentity,
+)
+from generic_ml_cache_core.application.domain.model.identity.passthrough_call_identity import (
+    PassthroughCallIdentity,
+)
+
+
+@dataclass(frozen=True)
+class SerializedIdentity:
+    """The row shape: denormalized query columns + the serialized remainder."""
+
+    kind: str
+    client: str
+    model: str
+    effort: str
+    identity_json: str
+
+
+def serialize_identity(identity: CallIdentity) -> SerializedIdentity:
+    if isinstance(identity, ManagedCallIdentity):
+        return SerializedIdentity(
+            kind=ExecutionKind.LOCAL_MANAGED.value,
+            client=identity.client,
+            model=identity.model,
+            effort=identity.effort,
+            identity_json=json.dumps(
+                {
+                    "context_fingerprint": identity.context_fingerprint,
+                    "prompt_fingerprint": identity.prompt_fingerprint,
+                    "input_file_fingerprints": identity.input_file_fingerprints,
+                    "client_args_fingerprint": identity.client_args_fingerprint,
+                    "grants": sorted(identity.grants),
+                }
+            ),
+        )
+    if isinstance(identity, PassthroughCallIdentity):
+        return SerializedIdentity(
+            kind=ExecutionKind.LOCAL_PASSTHROUGH.value,
+            client=identity.client,
+            model="",
+            effort="",
+            identity_json=json.dumps({"native_args_fingerprint": identity.native_args_fingerprint}),
+        )
+    if isinstance(identity, ApiCallIdentity):
+        return SerializedIdentity(
+            kind=ExecutionKind.API.value,
+            client=identity.provider,
+            model=identity.model,
+            effort="",
+            identity_json=json.dumps({"messages_fingerprint": identity.messages_fingerprint}),
+        )
+    raise ValueError(f"cannot serialize unknown call identity type: {type(identity).__name__}")
+
+
+def deserialize_identity(serialized: SerializedIdentity) -> CallIdentity:
+    fields = json.loads(serialized.identity_json)
+    if serialized.kind == ExecutionKind.LOCAL_MANAGED.value:
+        return ManagedCallIdentity(
+            client=serialized.client,
+            model=serialized.model,
+            effort=serialized.effort,
+            context_fingerprint=fields["context_fingerprint"],
+            prompt_fingerprint=fields["prompt_fingerprint"],
+            input_file_fingerprints=dict(fields["input_file_fingerprints"]),
+            client_args_fingerprint=fields["client_args_fingerprint"],
+            grants=frozenset(fields["grants"]),
+        )
+    if serialized.kind == ExecutionKind.LOCAL_PASSTHROUGH.value:
+        return PassthroughCallIdentity(
+            client=serialized.client,
+            native_args_fingerprint=fields["native_args_fingerprint"],
+        )
+    if serialized.kind == ExecutionKind.API.value:
+        return ApiCallIdentity(
+            provider=serialized.client,
+            model=serialized.model,
+            messages_fingerprint=fields["messages_fingerprint"],
+        )
+    raise ValueError(f"cannot deserialize unknown identity kind: {serialized.kind!r}")

generic_ml_cache_core/adapter/out/persistence/in_memory_execution_repository.py

@@ -0,0 +1,69 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""InMemoryExecutionRepository: an ephemeral, append-only execution store."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import Dict, List, Optional
+
+from generic_ml_cache_core.application.domain.model.execution.execution_state import ExecutionState
+from generic_ml_cache_core.application.domain.model.execution.ml_execution import MlExecution
+from generic_ml_cache_core.application.port.out.clock_port import ClockPort
+from generic_ml_cache_core.application.port.out.execution_repository_port import (
+    ExecutionRepositoryPort,
+)
+
+
+class InMemoryExecutionRepository(ExecutionRepositoryPort):
+    """An in-memory, append-only implementation of the execution repository.
+
+    Holds only structure: every saved execution is dehydrated (artifact bytes
+    dropped) before storage, so the repository never carries output content —
+    the bytes live in the blob store. Suitable as an ephemeral cache for a
+    library consumer and as a faithful test double that forces the use case down
+    the same hydrate-from-blob path the durable adapter will.
+
+    The clock is injected (it stamps supersession), so time is deterministic.
+    """
+
+    def __init__(self, clock: ClockPort) -> None:
+        self._clock = clock
+        self._by_key: Dict[str, List[MlExecution]] = {}
+
+    def find_current(self, execution_key: str) -> Optional[MlExecution]:
+        for execution in self._by_key.get(execution_key, []):
+            if self._is_servable(execution):
+                return replace(execution)
+        return None
+
+    def find_all(self, execution_key: str) -> List[MlExecution]:
+        return [replace(execution) for execution in self._by_key.get(execution_key, [])]
+
+    def save(self, execution: MlExecution) -> None:
+        execution_key = execution.call_identity.generate_key()
+        stored = self._dehydrate(execution)
+        history = self._by_key.setdefault(execution_key, [])
+        if self._is_servable(stored):
+            superseded_at = self._clock.now()
+            for prior in history:
+                if self._is_servable(prior):
+                    prior.superseded_at = superseded_at
+        history.append(stored)
+
+    @staticmethod
+    def _is_servable(execution: MlExecution) -> bool:
+        """A servable execution is the current cached answer: a persisted success
+        that has not been superseded."""
+        return (
+            execution.execution_state is ExecutionState.SUCCESS
+            and execution.output_persisted
+            and execution.superseded_at is None
+        )
+
+    @staticmethod
+    def _dehydrate(execution: MlExecution) -> MlExecution:
+        """Return a copy whose artifacts carry no bytes — the repository stores
+        structure only; the bytes belong to the blob store."""
+        dehydrated_artifacts = [replace(artifact, content=None) for artifact in execution.artifacts]
+        return replace(execution, artifacts=dehydrated_artifacts)