generic-ml-cache-core 0.2.0__tar.gz → 0.3.0__tar.gz

{generic_ml_cache_core-0.2.0 → generic_ml_cache_core-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: generic-ml-cache-core
-Version: 0.2.0
+Version: 0.3.0
 Summary: Hexagonal core library for generic-ml-cache: domain, use cases, ports, and the default outbound adapters (SQLite repo, blob store, local clients, API). Stateless; inject the data source. Zero runtime deps.
 Project-URL: Homepage, https://github.com/danielslobozian/generic-ml-cache
 Project-URL: Repository, https://github.com/danielslobozian/generic-ml-cache

{generic_ml_cache_core-0.2.0 → generic_ml_cache_core-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "generic-ml-cache-core"
-version = "0.2.0"
+version = "0.3.0"
 description = "Hexagonal core library for generic-ml-cache: domain, use cases, ports, and the default outbound adapters (SQLite repo, blob store, local clients, API). Stateless; inject the data source. Zero runtime deps."
 readme = "README.md"
 requires-python = ">=3.9"

{generic_ml_cache_core-0.2.0 → generic_ml_cache_core-0.3.0}/src/generic_ml_cache_core/adapter/out/persistence/in_memory_execution_repository.py

@@ -5,7 +5,7 @@
 from __future__ import annotations
 
 from dataclasses import replace
-from typing import Dict, List, Optional
+from typing import Dict, List, Optional, Set
 
 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
@@ -30,6 +30,7 @@ class InMemoryExecutionRepository(ExecutionRepositoryPort):
     def __init__(self, clock: ClockPort) -> None:
         self._clock = clock
         self._by_key: Dict[str, List[MlExecution]] = {}
+        self._tags_by_key: Dict[str, Set[str]] = {}
 
     def find_current(self, execution_key: str) -> Optional[MlExecution]:
         for execution in self._by_key.get(execution_key, []):
@@ -51,6 +52,17 @@ class InMemoryExecutionRepository(ExecutionRepositoryPort):
                     prior.superseded_at = superseded_at
         history.append(stored)
 
+    def add_tags(self, execution_key: str, tags: List[str]) -> None:
+        # Tags the key's current execution; a no-op when there is none.
+        if not tags or self.find_current(execution_key) is None:
+            return
+        self._tags_by_key.setdefault(execution_key, set()).update(tags)
+
+    def tags_for(self, execution_key: str) -> List[str]:
+        if self.find_current(execution_key) is None:
+            return []
+        return sorted(self._tags_by_key.get(execution_key, set()))
+
     @staticmethod
     def _is_servable(execution: MlExecution) -> bool:
         """A servable execution is the current cached answer: a persisted success

{generic_ml_cache_core-0.2.0 → generic_ml_cache_core-0.3.0}/src/generic_ml_cache_core/adapter/out/persistence/sqlite_execution_repository.py

@@ -86,6 +86,11 @@ CREATE TABLE IF NOT EXISTS token_usage (
     cost_usd           REAL,
     raw_json           TEXT NOT NULL
 );
+CREATE TABLE IF NOT EXISTS execution_tags (
+    execution_id INTEGER NOT NULL,
+    tag          TEXT NOT NULL,
+    UNIQUE(execution_id, tag)
+);
 """
 
 
@@ -288,6 +293,48 @@ class SqliteExecutionRepository(ExecutionRepositoryPort):
             ),
         )
 
+    # -- tags (a separate annotation; never rewrites an execution) --------
+
+    @staticmethod
+    def _current_execution_id(connection: sqlite3.Connection, execution_key: str) -> Optional[int]:
+        row = connection.execute(
+            "SELECT id FROM executions WHERE execution_key = ? AND state = ? "
+            "AND output_persisted = 1 AND superseded_at IS NULL ORDER BY id DESC LIMIT 1",
+            (execution_key, ExecutionState.SUCCESS.value),
+        ).fetchone()
+        return int(row[0]) if row is not None else None
+
+    def add_tags(self, execution_key: str, tags: List[str]) -> None:
+        if not tags:
+            return
+        connection = self._connect()
+        try:
+            execution_id = self._current_execution_id(connection, execution_key)
+            if execution_id is None:
+                return
+            for tag in tags:
+                connection.execute(
+                    "INSERT OR IGNORE INTO execution_tags (execution_id, tag) VALUES (?, ?)",
+                    (execution_id, tag),
+                )
+            connection.commit()
+        finally:
+            connection.close()
+
+    def tags_for(self, execution_key: str) -> List[str]:
+        connection = self._connect()
+        try:
+            execution_id = self._current_execution_id(connection, execution_key)
+            if execution_id is None:
+                return []
+            rows = connection.execute(
+                "SELECT tag FROM execution_tags WHERE execution_id = ? ORDER BY tag",
+                (execution_id,),
+            ).fetchall()
+            return [tag for (tag,) in rows]
+        finally:
+            connection.close()
+
     # -- reconstruction ---------------------------------------------------
 
     def _load_execution(self, connection: sqlite3.Connection, row: tuple) -> MlExecution:

{generic_ml_cache_core-0.2.0 → generic_ml_cache_core-0.3.0}/src/generic_ml_cache_core/application/domain/model/execution/ml_execution.py

@@ -6,7 +6,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass, field
 from datetime import datetime
-from typing import List, Optional
+from typing import Iterable, List, Optional
 
 from generic_ml_cache_core.application.domain.model.execution.artifact import Artifact
 from generic_ml_cache_core.application.domain.model.identity.call_identity import CallIdentity
@@ -39,3 +39,14 @@ class MlExecution:
     token_usage: Optional[TokenUsage] = None
     failure: Optional[ExecutionFailure] = None
     superseded_at: Optional[datetime] = None
+
+
+def normalize_tags(raw_tags: Iterable[str]) -> List[str]:
+    """Normalise user-supplied tags: trim, drop blanks, de-duplicate, sort.
+
+    Tags are metadata, never part of the cache key. Normalising at the boundary
+    keeps stored tags deterministic (the same set in any input order compares
+    equal) without interpreting their meaning — they are stored verbatim
+    otherwise.
+    """
+    return sorted({tag.strip() for tag in raw_tags if tag and tag.strip()})

{generic_ml_cache_core-0.2.0 → generic_ml_cache_core-0.3.0}/src/generic_ml_cache_core/application/port/inbound/run_managed_local_execution_command.py

@@ -34,6 +34,7 @@ class RunManagedLocalExecutionCommand:
     cache_mode: CacheMode = CacheMode.CACHE
     persist_output: bool = True
     record_on_error: bool = False
+    tags: List[str] = field(default_factory=list)
 
     @property
     def is_uncacheable(self) -> bool:

{generic_ml_cache_core-0.2.0 → generic_ml_cache_core-0.3.0}/src/generic_ml_cache_core/application/port/out/execution_repository_port.py

@@ -38,3 +38,15 @@ class ExecutionRepositoryPort(ABC):
         """Append a new execution. If it is a servable success, atomically
         supersede the prior current execution for the same key — the supersession
         happens here, where atomicity belongs, never in the caller."""
+
+    @abstractmethod
+    def add_tags(self, execution_key: str, tags: List[str]) -> None:
+        """Attach ``tags`` to the current execution for ``execution_key``,
+        idempotently — already-present tags are left untouched, new ones added.
+        A separate annotation layer: this never rewrites the execution record,
+        and is a no-op if there is no current execution for the key."""
+
+    @abstractmethod
+    def tags_for(self, execution_key: str) -> List[str]:
+        """Return the tags on the current execution for ``execution_key``, sorted;
+        empty if none (or no current execution)."""

{generic_ml_cache_core-0.2.0 → generic_ml_cache_core-0.3.0}/src/generic_ml_cache_core/application/usecase/cached_ml_execution_service.py

@@ -93,6 +93,19 @@ class CachedMlExecutionService(ABC):
         """Whether this command cannot be cached. Default: always cacheable."""
         return False
 
+    def _execution_tags(self, command: CacheableExecutionCommand) -> List[str]:
+        """User-supplied tags to attach to executions this service records.
+        Metadata only — never part of the key. Default: none."""
+        return []
+
+    def _apply_tags(self, execution_key: str, command: CacheableExecutionCommand) -> None:
+        """Attach the command's tags to the current execution for this key,
+        idempotently (a no-op when there are none). Tags are a separate
+        annotation: adding one never rewrites the execution record."""
+        tags = self._execution_tags(command)
+        if tags:
+            self._repository.add_tags(execution_key, tags)
+
     # -- resolution paths -------------------------------------------------
 
     def _serve_offline(self, command: CacheableExecutionCommand, execution_key: str) -> MlExecution:
@@ -107,6 +120,7 @@ class CachedMlExecutionService(ABC):
     ) -> MlExecution:
         hydrated_execution = self._hydrate(current_execution)
         self._record_event(journal_events.HIT, execution_key, command)
+        self._apply_tags(execution_key, command)
         return hydrated_execution
 
     def _run_uncacheable(
@@ -139,6 +153,7 @@ class CachedMlExecutionService(ABC):
         if should_store:
             self._repository.save(execution)
             self._record_event(journal_events.RECORD, execution_key, command)
+            self._apply_tags(execution_key, command)
         else:
             self._record_event(journal_events.RUN, execution_key, command)
         return execution

{generic_ml_cache_core-0.2.0 → generic_ml_cache_core-0.3.0}/src/generic_ml_cache_core/application/usecase/run_managed_local_execution_service.py

@@ -4,8 +4,9 @@
 
 from __future__ import annotations
 
-from typing import Tuple
+from typing import List, Tuple
 
+from generic_ml_cache_core.application.domain.model.execution.ml_execution import normalize_tags
 from generic_ml_cache_core.application.domain.model.identity.call_identity import CallIdentity
 from generic_ml_cache_core.application.domain.model.run.client_run_request import ClientRunRequest
 from generic_ml_cache_core.application.domain.model.run.client_run_result import ClientRunResult
@@ -66,6 +67,9 @@ class RunManagedLocalExecutionService(CachedMlExecutionService, RunManagedLocalE
     def _is_uncacheable(self, command: RunManagedLocalExecutionCommand) -> bool:
         return command.is_uncacheable
 
+    def _execution_tags(self, command: RunManagedLocalExecutionCommand) -> List[str]:
+        return normalize_tags(command.tags)
+
     @staticmethod
     def _build_client_run_request(command: RunManagedLocalExecutionCommand) -> ClientRunRequest:
         # The one allowed self-less method (AGENTS §6): the inbound-command ->

{generic_ml_cache_core-0.2.0 → generic_ml_cache_core-0.3.0}/tests/test_execution_repository.py

@@ -107,6 +107,31 @@ def test_save_then_find_current_returns_the_execution():
     assert found.execution_state is ExecutionState.SUCCESS
 
 
+def test_add_tags_then_tags_for_returns_them_sorted():
+    repository = _repository()
+    identity = _identity()
+    repository.save(_execution(identity))
+    repository.add_tags(identity.generate_key(), ["ticket", "id-scan"])
+    assert repository.tags_for(identity.generate_key()) == ["id-scan", "ticket"]
+
+
+def test_add_tags_is_idempotent_and_accumulates():
+    repository = _repository()
+    identity = _identity()
+    repository.save(_execution(identity))
+    key = identity.generate_key()
+    repository.add_tags(key, ["ticket"])
+    repository.add_tags(key, ["ticket", "id-scan"])  # 'ticket' already present
+    assert repository.tags_for(key) == ["id-scan", "ticket"]
+
+
+def test_add_tags_is_a_no_op_without_a_current_execution():
+    repository = _repository()
+    identity = _identity()
+    repository.add_tags(identity.generate_key(), ["x"])  # nothing stored
+    assert repository.tags_for(identity.generate_key()) == []
+
+
 def test_find_current_returns_dehydrated_artifacts():
     repository = _repository()
     identity = _identity()

{generic_ml_cache_core-0.2.0 → generic_ml_cache_core-0.3.0}/tests/test_ml_execution.py

@@ -16,7 +16,10 @@ from generic_ml_cache_core.application.domain.model.execution.execution_failure
 )
 from generic_ml_cache_core.application.domain.model.execution.execution_kind import ExecutionKind
 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.domain.model.execution.ml_execution import (
+    MlExecution,
+    normalize_tags,
+)
 from generic_ml_cache_core.application.domain.model.usage.token_usage import TokenUsage
 
 
@@ -152,3 +155,11 @@ def test_dehydrated_execution_has_artifacts_without_content():
     )
     assert execution.artifacts[0].is_hydrated is False
     assert execution.artifacts[0].blob_key == "k"
+
+
+def test_normalize_tags_trims_drops_blanks_dedupes_and_sorts():
+    assert normalize_tags(["  beta ", "alpha", "beta", "", "   ", "alpha"]) == ["alpha", "beta"]
+
+
+def test_normalize_tags_of_nothing_is_empty():
+    assert normalize_tags([]) == []

{generic_ml_cache_core-0.2.0 → generic_ml_cache_core-0.3.0}/tests/test_run_managed_local_execution_service.py

@@ -382,3 +382,24 @@ def test_grants_change_the_identity():
     harness.use_case.execute(_command())
     harness.use_case.execute(_command(grants=["net"]))
     assert len(harness.runner.calls) == 2
+
+
+# --- tags (non-identity metadata) --------------------------------------------
+
+
+def test_tags_are_normalized_and_applied_to_the_recorded_execution():
+    harness = _Harness(ClientRunResult(exit_code=0, stdout="answer\n"))
+    execution = harness.use_case.execute(_command(tags=["  ticket ", "scan", "ticket", "", "scan"]))
+    key = execution.call_identity.generate_key()
+    assert harness.repository.tags_for(key) == ["scan", "ticket"]
+
+
+def test_a_hit_accumulates_new_tags_onto_the_entry():
+    harness = _Harness()
+    first = harness.use_case.execute(_command(tags=["scan"]))
+    key = first.call_identity.generate_key()
+    harness.use_case.execute(_command(tags=["ticket"]))  # same input -> a hit
+    # Tags are out of the key (still one run) and accumulate on the entry.
+    assert len(harness.runner.calls) == 1
+    assert harness.metrics.events == ["record", "hit"]
+    assert harness.repository.tags_for(key) == ["scan", "ticket"]

{generic_ml_cache_core-0.2.0 → generic_ml_cache_core-0.3.0}/tests/test_sqlite_execution_repository.py

@@ -173,6 +173,31 @@ def test_token_usage_round_trips(tmp_path):
     assert restored == usage
 
 
+def test_add_tags_then_tags_for_returns_them_sorted(tmp_path):
+    repository = _repository(tmp_path)
+    identity = _managed_identity()
+    repository.save(_execution(identity))
+    repository.add_tags(identity.generate_key(), ["ticket", "id-scan"])
+    assert repository.tags_for(identity.generate_key()) == ["id-scan", "ticket"]
+
+
+def test_add_tags_is_idempotent_and_accumulates(tmp_path):
+    repository = _repository(tmp_path)
+    identity = _managed_identity()
+    repository.save(_execution(identity))
+    key = identity.generate_key()
+    repository.add_tags(key, ["ticket"])
+    repository.add_tags(key, ["ticket", "id-scan"])  # 'ticket' already present
+    assert repository.tags_for(key) == ["id-scan", "ticket"]
+
+
+def test_add_tags_is_a_no_op_without_a_current_execution(tmp_path):
+    repository = _repository(tmp_path)
+    identity = _managed_identity()
+    repository.add_tags(identity.generate_key(), ["x"])  # nothing stored
+    assert repository.tags_for(identity.generate_key()) == []
+
+
 def test_failure_round_trips_in_history(tmp_path):
     repository = _repository(tmp_path)
     identity = _managed_identity()