generic-ml-cache-bootstrap 0.29.0__py3-none-any.whl

generic_ml_cache_bootstrap/__init__.py

@@ -0,0 +1,26 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""generic-ml-cache-bootstrap: the composition root and plugin discovery layer.
+
+This is where the application is assembled at startup. It owns two jobs that are
+neither pure domain (core) nor a driven adapter (adapters):
+
+* **Discovery** — find the ``gmlcache.adapters`` plugins, whitelist them at load
+  time, and decide which distributions are trusted (provenance).
+* **Composition** — wire the core use cases to the concrete adapters and hand the
+  drivers (CLI, daemon) a ready application API.
+
+It depends on both ``core`` and ``adapters`` (it must ``new`` the infra), and is
+imported only by the drivers — never by an adapter (that would be a leaf calling
+the composition root). See ``docs/design/bootstrap-split-and-v4-plan.md``.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+try:
+    __version__ = _pkg_version("generic-ml-cache-bootstrap")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0+unknown"

generic_ml_cache_bootstrap/application.py

@@ -0,0 +1,274 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""build_application_api — the shared composition root.
+
+The ~15-object assembly that turns a store location + a connection factory into
+a wired :class:`ApplicationApi` was duplicated, almost line for line, between the
+CLI's ``_compose.py`` and the daemon's ``app.py``. It lives here now, in the one
+package allowed to import both ``core`` and the concrete ``adapters``.
+
+Only one thing genuinely differs between the drivers: **which client adapters to
+wire**. The CLI runs one selected client per invocation; the daemon wires every
+whitelisted client. That single variation is injected as the ``build_runners``
+strategy; everything else (store recovery, blob store + encryption, migrations,
+repository, metrics, the use-case graph) is identical and lives here.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+
+from generic_ml_cache_adapters.adapter.outbound.api.anthropic_subscription_relay_adapter import (
+    AnthropicSubscriptionRelayAdapter,
+)
+from generic_ml_cache_adapters.adapter.outbound.crypto.encrypting_blob_store import (
+    EncryptingBlobStore,
+    TokenRequiredBlobStore,
+)
+from generic_ml_cache_adapters.adapter.outbound.crypto.filesystem_encryption_manifest_store import (
+    FilesystemEncryptionManifestStore,
+)
+from generic_ml_cache_adapters.adapter.outbound.crypto.store_encryptor import StoreEncryptor
+from generic_ml_cache_adapters.adapter.outbound.diagnostics.null_diagnostics_adapter import (
+    NullDiagnosticsAdapter,
+)
+from generic_ml_cache_adapters.adapter.outbound.fingerprint.filesystem_file_fingerprint import (
+    FilesystemFileFingerprint,
+)
+from generic_ml_cache_adapters.adapter.outbound.persistence.filesystem_execution_key_lock import (
+    FilesystemExecutionKeyLock,
+    lock_wait_for_client_timeout,
+)
+from generic_ml_cache_adapters.adapter.outbound.persistence.filesystem_store_lock import (
+    FilesystemStoreLock,
+)
+from generic_ml_cache_adapters.adapter.outbound.storage.filesystem_blob_store import (
+    FilesystemBlobStore,
+)
+from generic_ml_cache_adapters.adapter.outbound.workspace.filesystem_workspace import (
+    FilesystemWorkspace,
+)
+from generic_ml_cache_core.application.port.outbound.adapter_catalog_port import AdapterCatalogPort
+from generic_ml_cache_core.application.port.outbound.adapter_resolver_port import (
+    AdapterResolverPort,
+)
+from generic_ml_cache_core.application.port.outbound.blob_store_port import BlobStorePort
+from generic_ml_cache_core.application.port.outbound.diagnostics_port import DiagnosticsPort
+from generic_ml_cache_core.application.port.outbound.file_fingerprint_port import (
+    FileFingerprintPort,
+)
+from generic_ml_cache_core.application.port.outbound.registered_adapter_port import (
+    RegisteredAdapterPort,
+)
+from generic_ml_cache_core.application.port.outbound.store_migration_port import (
+    CURRENT_MODEL_VERSION,
+    StoreMigrationPort,
+)
+from generic_ml_cache_core.application.usecase.artifact_content_service import (
+    ArtifactContentService,
+)
+from generic_ml_cache_core.application.usecase.execution_query_service import ExecutionQueryService
+from generic_ml_cache_core.application.usecase.probe_service import ProbeService
+from generic_ml_cache_core.application.usecase.purge_service import PurgeService
+from generic_ml_cache_core.application.usecase.repair_store_service import RepairStoreService
+from generic_ml_cache_core.application.usecase.run_ml_execution_service import (
+    RunMlExecutionService,
+)
+from generic_ml_cache_core.application.usecase.session_admin_service import SessionAdminService
+from generic_ml_cache_core.application.usecase.session_report_service import SessionReportService
+from generic_ml_cache_core.application.usecase.session_tags_service import SessionTagsService
+from generic_ml_cache_core.application.usecase.store_stats_service import StoreStatsService
+from generic_ml_cache_core.application.wiring.application_api import ApplicationApi
+from generic_ml_cache_core.common.errors import PersistenceContractOutdated
+
+from generic_ml_cache_bootstrap.discovery.composition import catalog_and_resolver_for
+from generic_ml_cache_bootstrap.persistence_backend import (
+    PersistenceBackend,
+    sqlite_persistence_backend,
+)
+
+_BLOBS_DIRNAME = "blobs"
+#: The shipped SQLite store's database filename under the store root — used to build
+#: the default PersistenceBackend when an embedder injects none.
+_DB_NAME = "executions.sqlite3"
+
+# The driver-specific variation: given the resolved catalog + resolver, return the
+# runner adapters to wire, keyed by client NAME. (CLI: one selected client; daemon:
+# all whitelisted.)
+BuildRunners = Callable[[AdapterCatalogPort, AdapterResolverPort], dict[str, RegisteredAdapterPort]]
+
+
+def recover_store(store_root: Path) -> None:
+    """Roll back any half-finished encryption migration before the store is read."""
+    StoreEncryptor(
+        store_root,
+        FilesystemEncryptionManifestStore(store_root),
+        FilesystemStoreLock(store_root),
+    ).recover()
+
+
+def resolve_blob_store(store_root: Path, encryption_token: str | None) -> BlobStorePort:
+    """The blob store, wrapped for encryption when the store has a manifest."""
+    blob_store: BlobStorePort = FilesystemBlobStore(store_root / _BLOBS_DIRNAME)
+    manifest = FilesystemEncryptionManifestStore(store_root).load()
+    if manifest is None:
+        return blob_store
+    if encryption_token is None:
+        return TokenRequiredBlobStore(blob_store)
+    from generic_ml_cache_adapters.adapter.outbound.crypto.aesgcm_cipher import AesGcmCipher
+
+    cipher = AesGcmCipher()
+    data_key = cipher.open_envelope(encryption_token, manifest)
+    return EncryptingBlobStore(blob_store, cipher, data_key)
+
+
+def provision_store(migration: StoreMigrationPort) -> None:
+    """Run the persistence-contract handshake (C-2), then migrate.
+
+    Fail-fast at boot if the injected adapter implements an older model contract
+    than this build requires, rather than letting a stale mapping silently drop a
+    field. The shipped SQLite adapter is always current; the check guards a
+    third-party adapter that might lag ``CURRENT_MODEL_VERSION``.
+    """
+    implemented = migration.implemented_version()
+    if implemented < CURRENT_MODEL_VERSION:
+        raise PersistenceContractOutdated(
+            f"persistence adapter implements model version {implemented}, but this build "
+            f"requires version {CURRENT_MODEL_VERSION}; upgrade the adapter's mapping/migrations"
+        )
+    migration.migrate_to_current()
+
+
+def build_application_api(
+    store_root: Path,
+    build_runners: BuildRunners,
+    *,
+    persistence: PersistenceBackend | None = None,
+    blob_store: BlobStorePort | None = None,
+    file_fingerprint: FileFingerprintPort | None = None,
+    encryption_token: str | None = None,
+    max_size: int | None = None,
+    whitelist: frozenset[str] | None = None,
+    client_timeout: float | None = None,
+    diag: DiagnosticsPort | None = None,
+) -> ApplicationApi:
+    """Wire the application: the use-case graph over its outbound adapters.
+
+    ``build_runners`` is the only required driver-specific input — it chooses which
+    client adapters to wire. The infrastructure adapters are OVERRIDABLE with shipped
+    defaults (V33, ``@ConditionalOnMissingBean``): the DB-backed adapters as one
+    ``PersistenceBackend`` bundle (default = SQLite under ``store_root``), and the
+    blob store / file fingerprint individually. A standalone driver injects nothing and
+    gets the batteries-included SQLite + filesystem stack; an embedder supplies a
+    Postgres/S3 backend and the C-2 boot handshake validates it.
+    """
+    store_root = Path(store_root)
+    _diag: DiagnosticsPort = diag if diag is not None else NullDiagnosticsAdapter()
+    # Roll back a half-finished encryption migration ONLY on the default filesystem
+    # stack (X20). recover_store hardcodes FilesystemEncryptionManifestStore +
+    # FilesystemStoreLock, so if an embedder injects its own blob store (Postgres/S3)
+    # it owns its own recovery and bootstrap must not read/write/lock local FS
+    # encryption state under a nominal store_root. Checked before blob_store is
+    # resolved to its default below.
+    if blob_store is None:
+        recover_store(store_root)
+    persistence = persistence or sqlite_persistence_backend(store_root / _DB_NAME, _diag)
+    blob_store = (
+        blob_store if blob_store is not None else resolve_blob_store(store_root, encryption_token)
+    )
+    file_fingerprint = (
+        file_fingerprint if file_fingerprint is not None else FilesystemFileFingerprint()
+    )
+    # One shared per-key lock instance (X7): the record path and eviction/purge both
+    # coordinate on it, so an eviction of a key waits for a concurrent write of that
+    # same key (and vice versa) — its in-process stripe only serializes if it is the
+    # same object. Size its cross-process wait to the client call it protects (Y2), so a
+    # contender waits out an ordinary slow call (coalescing into one client run) instead
+    # of tripping the old fixed 5s and running the expensive call a second time.
+    execution_key_lock = FilesystemExecutionKeyLock(
+        store_root, _diag, timeout_seconds=lock_wait_for_client_timeout(client_timeout)
+    )
+    provision_store(persistence.migration)
+    catalog, resolver = catalog_and_resolver_for(whitelist)
+    runners = build_runners(catalog, resolver)
+    # The caching HTTP gateway (the daemon's /gateway/claude route) dispatches an
+    # API_PASSTHROUGH command to this verbatim relay through the shared run use case —
+    # it is not a user-selectable client, so it is wired here rather than discovered.
+    runners.setdefault(AnthropicSubscriptionRelayAdapter.name, AnthropicSubscriptionRelayAdapter())
+    # One application service per capability (grouped by shared machinery); each is
+    # exposed through the segregated per-operation inbound-port fields of ApplicationApi
+    # (B-1). On the outbound side (V32/V33) each service depends only on the role ports
+    # it needs, drawn from the PersistenceBackend bundle's per-role fields (one impl
+    # instance backs several of them).
+    purge = PurgeService(
+        persistence.purge_ml_runs,
+        blob_store,
+        journal=persistence.purge_journal,
+        sessions=persistence.session_query,
+        execution_key_lock=execution_key_lock,
+        diag=_diag,
+    )
+    session_tags = SessionTagsService(persistence.session_tags)
+    session_admin = SessionAdminService(
+        specs=persistence.session_spec, sessions=persistence.session_query
+    )
+    session_report = SessionReportService(
+        report_source=persistence.session_report_source,
+        sessions=persistence.session_query,
+        repository=persistence.read_ml_run,
+        repair_source=persistence.repair_ml_runs,
+    )
+    execution_query = ExecutionQueryService(persistence.inspect_ml_runs)
+    store_stats = StoreStatsService(persistence.call_stats)
+    artifact_content = ArtifactContentService(blob_store)
+    repair_store = RepairStoreService(
+        repair_source=persistence.repair_ml_runs,
+        artifact_persistence=persistence.save_ml_run,
+        blob_store=blob_store,
+    )
+    return ApplicationApi(
+        run_ml=RunMlExecutionService(
+            file_fingerprint,
+            runners,
+            blob_store,
+            save=persistence.save_ml_run,
+            read=persistence.read_ml_run,
+            annotate=persistence.annotate_ml_run,
+            record=persistence.record_call_event,
+            execution_key_lock=execution_key_lock,
+            store_lock=FilesystemStoreLock(store_root),
+            purge_service=purge,
+            max_size=max_size,
+            workspace=FilesystemWorkspace(),
+            diag=_diag,
+        ),
+        probe=ProbeService(file_fingerprint, persistence.read_ml_run),
+        purge_by_key=purge,
+        purge_by_tag=purge,
+        purge_by_session=purge,
+        purge_by_session_tag=purge,
+        purge_all=purge,
+        evict_stale=purge,
+        evict_to_quota=purge,
+        tag_session=session_tags,
+        untag_session=session_tags,
+        list_session_tags=session_tags,
+        set_session_spec=session_admin,
+        clear_session_spec=session_admin,
+        get_session_spec=session_admin,
+        list_session_ids=session_admin,
+        sessions_for_tag=session_admin,
+        execution_keys_for_session=session_admin,
+        report_for_session=session_report,
+        report_for_tag=session_report,
+        list_execution_summaries=execution_query,
+        total_stored_bytes=execution_query,
+        tags_for_execution=execution_query,
+        find_current_execution=execution_query,
+        find_executions_by_key_prefix=execution_query,
+        event_counts=store_stats,
+        hit_counts_by_key=store_stats,
+        read_artifact_blob=artifact_content,
+        repair_store=repair_store,
+    )

generic_ml_cache_bootstrap/diagnostics.py

@@ -0,0 +1,38 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Driver-facing hook for the diagnostics (logging) port (W28).
+
+Choosing whether to log, at what level, and to which file is *driver policy* — the
+CLI resolves it from flags + env + config, the daemon from env. But constructing
+the concrete diagnostics adapter (null vs structlog) is infrastructure, and a
+driver must not import a concrete ``adapters.…diagnostics`` class to do it — that
+is the ``cli``/``daemon`` -> ``adapters`` edge W28 removes. The driver resolves the
+settings and hands them here; the composition root builds the port.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from generic_ml_cache_adapters.adapter.outbound.diagnostics.null_diagnostics_adapter import (
+    NullDiagnosticsAdapter,
+)
+from generic_ml_cache_adapters.adapter.outbound.diagnostics.structlog_diagnostics_adapter import (
+    StructlogDiagnosticsAdapter,
+)
+from generic_ml_cache_core.application.port.outbound.diagnostics_port import DiagnosticsPort
+
+
+def build_diagnostics(log_level: str | None, log_file: Path | None = None) -> DiagnosticsPort:
+    """Build the diagnostics port from a driver's resolved logging settings.
+
+    An empty/absent ``log_level`` selects the quiet no-op adapter (the store still
+    works; nothing is logged). Otherwise structured logging is written to
+    ``log_file`` (its parent directory is created), which must be provided.
+    """
+    if not log_level:
+        return NullDiagnosticsAdapter()
+    if log_file is None:
+        raise ValueError("a log file is required when a log level is set")
+    log_file.parent.mkdir(parents=True, exist_ok=True)
+    return StructlogDiagnosticsAdapter(log_file, level=log_level)

generic_ml_cache_bootstrap/discovery/__init__.py

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Adapter discovery: catalogs, resolvers, and descriptor helpers.
+
+This is infrastructure — it may scan installed entry points and construct
+concrete adapter classes. Core only sees the AdapterCatalogPort / AdapterResolverPort
+contracts; the implementations live here and are injected by the composition root.
+"""

generic_ml_cache_bootstrap/discovery/_entrypoints.py

@@ -0,0 +1,45 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Low-level entry-point access for the discovery layer.
+
+This is the one place that touches ``importlib.metadata`` — the packaging system.
+It belongs in the adapters/infrastructure package, never in core.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+
+ADAPTER_ENTRYPOINT_GROUP = "gmlcache.adapters"
+ADAPTER_CONTRACT_VERSION = "1"
+
+
+def iter_entry_points(
+    group: str = ADAPTER_ENTRYPOINT_GROUP,
+) -> list[importlib.metadata.EntryPoint]:
+    """Return the entry points in ``group``."""
+    return list(importlib.metadata.entry_points(group=group))
+
+
+def distribution_name(entry_point: importlib.metadata.EntryPoint) -> str:
+    """The name of the distribution providing ``entry_point`` (``""`` if unknown).
+
+    Used to decide trust at load time: an entry point whose distribution is in
+    the trusted set is loaded; others are third-party, off unless whitelisted.
+    """
+    dist = entry_point.dist
+    if dist is None or not dist.metadata:
+        return ""
+    return dist.name or ""
+
+
+def describe_source(entry_point: importlib.metadata.EntryPoint) -> str:
+    """Human-readable "<package> <version>" for the distribution providing ``entry_point``."""
+    dist = entry_point.dist
+    if dist is None:
+        return entry_point.value
+    name = dist.name or ""
+    version = dist.version or ""
+    if name and version:
+        return f"{name} {version}"
+    return name or entry_point.value

generic_ml_cache_bootstrap/discovery/api_discover.py

@@ -0,0 +1,61 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""API provider discovery: list models for a registered API provider.
+
+Advisory and read-only — mirrors the client discover module but for direct
+REST adapters (Gemini, Anthropic, OpenAI …) rather than local CLI clients.
+The adapter reads its own API key from the environment when ``api_key`` is not
+passed explicitly.
+"""
+
+from __future__ import annotations
+
+from generic_ml_cache_core.application.domain.model.model_listing import ModelListing
+from generic_ml_cache_core.application.port.outbound.model_listing_port import ModelListingPort
+from generic_ml_cache_core.common.errors import UnknownClient
+
+from generic_ml_cache_bootstrap.discovery.composition import get_adapter
+
+
+def list_api_models(
+    provider: str,
+    api_key: str | None = None,
+    whitelist: frozenset[str] | None = None,
+) -> ModelListing:
+    """List models for a registered API provider.
+
+    Returns a :class:`ModelListing` in all cases — never raises for an absent or
+    unsupported provider. Three honest outcomes:
+
+    * unknown provider → ``present=False``
+    * provider registered but adapter does not implement ModelListingPort →
+      ``supported=False``
+    * provider listed → ``supported=True`` and ``models`` populated
+
+    ``api_key`` is accepted for backward compatibility; adapters resolve their
+    key from the environment when it is not passed.
+    """
+    try:
+        adapter = get_adapter(provider, whitelist=whitelist)
+    except UnknownClient as exc:
+        return ModelListing(name=provider, present=False, supported=False, reason=str(exc))
+
+    if not isinstance(adapter, ModelListingPort):
+        return ModelListing(
+            name=provider,
+            present=True,
+            supported=False,
+            reason="this provider has no model-listing endpoint",
+        )
+
+    try:
+        models = adapter.list_models()
+    except Exception as exc:  # noqa: BLE001 — any transport failure → honest error
+        return ModelListing(
+            name=provider,
+            present=True,
+            supported=True,
+            reason=f"model listing failed: {exc}",
+        )
+
+    return ModelListing(name=provider, present=True, supported=True, models=models)