generic-ml-cache-daemon 0.13.0__py3-none-any.whl

generic_ml_cache_daemon/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+__version__ = "0.13.0"

generic_ml_cache_daemon/__main__.py

@@ -0,0 +1,27 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Entry point: run the daemon via ``python -m generic_ml_cache_daemon``."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import uvicorn
+
+from generic_ml_cache_daemon.app import create_app
+
+_DEFAULT_HOST = "127.0.0.1"
+_DEFAULT_PORT = 8765
+
+
+def main() -> None:
+    store_root = Path(os.environ.get("GMLCACHE_STORE", str(Path.home() / ".gmlcache")))
+    session_id = os.environ.get("GMLCACHE_SESSION") or None
+    enable_metrics = os.environ.get("GMLCACHE_METRICS", "").lower() in ("1", "true", "yes")
+    application = create_app(store_root, session_id=session_id, enable_metrics=enable_metrics)
+    uvicorn.run(application, host=_DEFAULT_HOST, port=_DEFAULT_PORT)
+
+
+if __name__ == "__main__":
+    main()

generic_ml_cache_daemon/app.py

@@ -0,0 +1,63 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""FastAPI application factory for the generic-ml-cache daemon."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from fastapi import FastAPI
+
+from generic_ml_cache_core.adapter.inbound.composition import build_use_cases
+
+from generic_ml_cache_daemon import __version__
+
+
+def create_app(
+    store_root: Path,
+    *,
+    session_id: Optional[str] = None,
+    enable_metrics: bool = False,
+) -> FastAPI:
+    """Create and configure the daemon FastAPI application.
+
+    Args:
+        store_root: path to the gmlcache store directory (the injected data source).
+        session_id: optional session all intercepted calls are recorded under.
+        enable_metrics: expose the Prometheus /metrics endpoint.
+
+    Returns:
+        A fully wired FastAPI application. Routes are mounted by this function;
+        callers should not mount additional routes after construction.
+    """
+    application = FastAPI(
+        title="generic-ml-cache daemon",
+        version=__version__,
+        docs_url="/docs",
+        redoc_url="/redoc",
+    )
+
+    wired_use_cases = build_use_cases(store_root)
+    application.state.wired = wired_use_cases
+    application.state.store_root = store_root
+    application.state.session_id = session_id
+    application.state.enable_metrics = enable_metrics
+
+    from generic_ml_cache_daemon.jobs import JobRegistry
+    from generic_ml_cache_daemon.routes.executions import router as executions_router
+    from generic_ml_cache_daemon.routes.gateway import router as gateway_router
+    from generic_ml_cache_daemon.routes.health import router as health_router
+    from generic_ml_cache_daemon.routes.jobs import router as jobs_router
+    from generic_ml_cache_daemon.routes.run import router as run_router
+    from generic_ml_cache_daemon.routes.sessions import router as sessions_router
+
+    application.state.job_registry = JobRegistry()
+    application.include_router(health_router)
+    application.include_router(sessions_router)
+    application.include_router(executions_router)
+    application.include_router(run_router)
+    application.include_router(jobs_router)
+    application.include_router(gateway_router)
+
+    return application

generic_ml_cache_daemon/jobs.py

@@ -0,0 +1,86 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""In-process job registry for detached background executions.
+
+Each POST /jobs submission gets a unique job_id. The execution runs in a
+background thread; callers poll GET /jobs/{id} or stream GET /jobs/{id}/stream.
+The registry is in-process memory only — jobs are not persisted across restarts.
+"""
+
+from __future__ import annotations
+
+import concurrent.futures
+import secrets
+import threading
+from enum import Enum
+from typing import Dict, Optional
+
+from generic_ml_cache_core.application.domain.model.execution.ml_execution import MlExecution
+
+
+class JobState(str, Enum):
+    PENDING = "pending"
+    RUNNING = "running"
+    DONE = "done"
+    ERROR = "error"
+
+
+class Job:
+    def __init__(self, job_id: str) -> None:
+        self.job_id = job_id
+        self.state = JobState.PENDING
+        self.execution: Optional[MlExecution] = None
+        self.error: Optional[str] = None
+        self._done_event = threading.Event()
+
+    def wait(self, timeout: Optional[float] = None) -> bool:
+        return self._done_event.wait(timeout=timeout)
+
+    def mark_running(self) -> None:
+        self.state = JobState.RUNNING
+
+    def mark_done(self, execution: MlExecution) -> None:
+        self.execution = execution
+        self.state = JobState.DONE
+        self._done_event.set()
+
+    def mark_error(self, error: str) -> None:
+        self.error = error
+        self.state = JobState.ERROR
+        self._done_event.set()
+
+
+class JobRegistry:
+    """Thread-safe in-memory registry of submitted jobs."""
+
+    def __init__(self) -> None:
+        self._jobs: Dict[str, Job] = {}
+        self._lock = threading.Lock()
+        self._executor = concurrent.futures.ThreadPoolExecutor(
+            max_workers=4, thread_name_prefix="gmlc-job"
+        )
+
+    def submit(self, fn, *args) -> Job:
+        job_id = secrets.token_hex(8)
+        job = Job(job_id)
+        with self._lock:
+            self._jobs[job_id] = job
+
+        def _run() -> None:
+            job.mark_running()
+            try:
+                execution = fn(*args)
+                job.mark_done(execution)
+            except Exception as exc:
+                job.mark_error(str(exc))
+
+        self._executor.submit(_run)
+        return job
+
+    def get(self, job_id: str) -> Optional[Job]:
+        with self._lock:
+            return self._jobs.get(job_id)
+
+    def list_ids(self) -> list:
+        with self._lock:
+            return list(self._jobs.keys())

generic_ml_cache_daemon/metrics.py

@@ -0,0 +1,17 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Prometheus metrics setup for the daemon. Requires the optional [metrics] extra."""
+
+from __future__ import annotations
+
+try:
+    import prometheus_client  # type: ignore[import-untyped]  # noqa: F401
+
+    _AVAILABLE = True
+except ImportError:  # pragma: no cover
+    _AVAILABLE = False
+
+
+def is_prometheus_available() -> bool:
+    """Return True when the prometheus-client extra is installed."""
+    return _AVAILABLE

generic_ml_cache_daemon/models/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0

generic_ml_cache_daemon/models/execution.py

@@ -0,0 +1,59 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Pydantic models for the Executions HTTP API and global stats/purge."""
+
+from __future__ import annotations
+
+from typing import Dict, List, Literal, Union
+
+from pydantic import BaseModel
+
+
+class ExecutionSummaryResponse(BaseModel):
+    execution_key: str
+    kind: str
+    client: str
+    model: str
+
+
+class ExecutionListResponse(BaseModel):
+    executions: List[ExecutionSummaryResponse]
+    total: int
+
+
+class GlobalStatsResponse(BaseModel):
+    executions: int
+    event_counts: Dict[str, int]
+
+
+class PurgeByAll(BaseModel):
+    by: Literal["all"]
+
+
+class PurgeByKey(BaseModel):
+    by: Literal["key"]
+    target: str
+
+
+class PurgeByTag(BaseModel):
+    by: Literal["tag"]
+    target: str
+
+
+class PurgeBySession(BaseModel):
+    by: Literal["session"]
+    target: str
+
+
+class PurgeBySessionTag(BaseModel):
+    by: Literal["session_tag"]
+    target: str
+
+
+PurgeBody = Union[PurgeByAll, PurgeByKey, PurgeByTag, PurgeBySession, PurgeBySessionTag]
+
+
+class PurgeResponse(BaseModel):
+    executions_removed: int
+    bytes_freed: int
+    blobs_removed: int

generic_ml_cache_daemon/models/gateway.py

@@ -0,0 +1,39 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Pydantic models for the Claude gateway (/gateway/claude/v1/messages)."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel
+
+
+class MessageParam(BaseModel):
+    role: str
+    content: str
+
+
+class MessagesRequest(BaseModel):
+    model: str
+    messages: List[MessageParam]
+    max_tokens: int = 8192
+    system: Optional[str] = None
+    session_id: Optional[str] = None
+
+
+class ContentBlock(BaseModel):
+    type: str = "text"
+    text: str
+
+
+class MessagesResponse(BaseModel):
+    id: str
+    type: str = "message"
+    role: str = "assistant"
+    content: List[ContentBlock]
+    model: str
+    stop_reason: str = "end_turn"
+    stop_sequence: Optional[str] = None
+    usage: Dict[str, Any]
+    x_cache_hit: bool = False

generic_ml_cache_daemon/models/health.py

@@ -0,0 +1,25 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Pydantic response models for /health, /ready, and /info."""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from pydantic import BaseModel
+
+
+class HealthResponse(BaseModel):
+    status: str
+
+
+class ReadyResponse(BaseModel):
+    status: str
+    detail: Optional[str] = None
+
+
+class InfoResponse(BaseModel):
+    version: str
+    store_root: str
+    session_id: Optional[str] = None
+    adapters: List[str]

generic_ml_cache_daemon/models/job.py

@@ -0,0 +1,28 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Pydantic models for the Jobs HTTP API (detached background executions)."""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from pydantic import BaseModel
+
+
+class JobSubmitBody(BaseModel):
+    client: str
+    model: str
+    effort: str = ""
+    prompt: str = ""
+    context: str = ""
+    tags: List[str] = []
+    session_id: Optional[str] = None
+
+
+class JobResponse(BaseModel):
+    job_id: str
+    state: str
+    execution_key: Optional[str] = None
+    stdout: Optional[str] = None
+    stderr: Optional[str] = None
+    error: Optional[str] = None

generic_ml_cache_daemon/models/run.py

@@ -0,0 +1,27 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Pydantic models for the /run endpoint."""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from pydantic import BaseModel
+
+
+class RunBody(BaseModel):
+    client: str
+    model: str
+    effort: str = ""
+    prompt: str = ""
+    context: str = ""
+    tags: List[str] = []
+    session_id: Optional[str] = None
+
+
+class RunResponse(BaseModel):
+    execution_key: str
+    state: str
+    cache_hit: bool
+    stdout: Optional[str] = None
+    stderr: Optional[str] = None

generic_ml_cache_daemon/models/session.py

@@ -0,0 +1,43 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Pydantic models for the Sessions HTTP API."""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from pydantic import BaseModel
+
+
+class SpecBody(BaseModel):
+    client: str
+    model: str
+    effort: str
+
+
+class SessionCreateBody(BaseModel):
+    tags: List[str] = []
+    spec: Optional[SpecBody] = None
+
+
+class SessionResponse(BaseModel):
+    session_id: str
+    tags: List[str]
+    spec: Optional[SpecBody] = None
+
+
+class SessionStatsResponse(BaseModel):
+    session_id: str
+    tags: List[str]
+    spec: Optional[SpecBody] = None
+    calls: int
+    hits: int
+    hit_rate: float
+
+
+class TagBody(BaseModel):
+    tag: str
+
+
+class SessionListResponse(BaseModel):
+    session_ids: List[str]

generic_ml_cache_daemon/routes/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0

generic_ml_cache_daemon/routes/executions.py

@@ -0,0 +1,102 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Routes: /executions, /stats, /purge."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Body, HTTPException, Request  # noqa: F401
+
+from generic_ml_cache_daemon.models.execution import (
+    ExecutionListResponse,
+    ExecutionSummaryResponse,
+    GlobalStatsResponse,
+    PurgeBody,
+    PurgeByAll,
+    PurgeByKey,
+    PurgeBySession,
+    PurgeBySessionTag,
+    PurgeByTag,
+    PurgeResponse,
+)
+
+router = APIRouter()
+
+
+@router.get("/executions")
+def list_executions(request: Request) -> ExecutionListResponse:
+    """Return all current (servable) executions."""
+    summaries = request.app.state.wired.repository.current_execution_summaries()
+    items = [
+        ExecutionSummaryResponse(
+            execution_key=s.execution_key, kind=s.kind, client=s.client, model=s.model
+        )
+        for s in summaries
+    ]
+    return ExecutionListResponse(executions=items, total=len(items))
+
+
+@router.get(
+    "/executions/{key}",
+    responses={
+        404: {"description": "Execution not found"},
+        409: {"description": "Ambiguous key prefix matches multiple executions"},
+    },
+)
+def get_execution(key: str, request: Request) -> ExecutionSummaryResponse:
+    """Return the execution whose key equals or starts with ``key``."""
+    summaries = request.app.state.wired.repository.current_execution_summaries()
+    # exact match first, then prefix
+    exact = [s for s in summaries if s.execution_key == key]
+    if exact:
+        s = exact[0]
+        return ExecutionSummaryResponse(
+            execution_key=s.execution_key, kind=s.kind, client=s.client, model=s.model
+        )
+    prefix_matches = [s for s in summaries if s.execution_key.startswith(key)]
+    if not prefix_matches:
+        raise HTTPException(status_code=404, detail=f"execution {key!r} not found")
+    if len(prefix_matches) > 1:
+        raise HTTPException(
+            status_code=409,
+            detail=f"ambiguous key prefix {key!r} matches {len(prefix_matches)} executions",
+        )
+    s = prefix_matches[0]
+    return ExecutionSummaryResponse(
+        execution_key=s.execution_key, kind=s.kind, client=s.client, model=s.model
+    )
+
+
+@router.get("/stats")
+def get_stats(request: Request) -> GlobalStatsResponse:
+    """Return global store statistics."""
+    wired = request.app.state.wired
+    summaries = wired.repository.current_execution_summaries()
+    return GlobalStatsResponse(
+        executions=len(summaries),
+        event_counts=wired.metrics.event_counts(),
+    )
+
+
+@router.post("/purge", responses={422: {"description": "Unsupported purge scope"}})
+def purge(body: Annotated[PurgeBody, Body(discriminator="by")], request: Request) -> PurgeResponse:
+    """Purge (soft-delete) executions by scope."""
+    purge_service = request.app.state.wired.purge
+    if isinstance(body, PurgeByAll):
+        report = purge_service.purge_all()
+    elif isinstance(body, PurgeByKey):
+        report = purge_service.purge_one(body.target)
+    elif isinstance(body, PurgeByTag):
+        report = purge_service.purge_by_tag(body.target)
+    elif isinstance(body, PurgeBySession):
+        report = purge_service.purge_by_session(body.target)
+    elif isinstance(body, PurgeBySessionTag):
+        report = purge_service.purge_by_session_tag(body.target)
+    else:  # pragma: no cover
+        raise HTTPException(status_code=422, detail="unsupported purge scope")
+    return PurgeResponse(
+        executions_removed=report.executions_removed,
+        bytes_freed=report.bytes_freed,
+        blobs_removed=report.blobs_removed,
+    )

generic_ml_cache_daemon/routes/gateway.py

@@ -0,0 +1,119 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Route: POST /gateway/claude/v1/messages — Anthropic Messages API caching proxy.
+
+Scope for 0.13.0: single-user-turn conversations only (one role=user message in
+the messages array). Multi-turn support requires thread-aware context handling and
+is deferred to a future element.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import secrets
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Request
+
+from generic_ml_cache_core.adapter.inbound.composition import resolve_execution_kind
+from generic_ml_cache_core.application.domain.model.execution.artifact import ArtifactType
+from generic_ml_cache_core.application.domain.model.execution.execution_state import (
+    ExecutionState,
+)
+from generic_ml_cache_core.application.port.inbound.run_ml_execution_command import (
+    RunMlExecutionCommand,
+)
+
+from generic_ml_cache_daemon.models.gateway import (
+    ContentBlock,
+    MessagesRequest,
+    MessagesResponse,
+)
+
+router = APIRouter(prefix="/gateway/claude")
+
+_STDOUT = ArtifactType.STDOUT
+_CLIENT = "anthropic"
+
+
+def _extract_stdout(execution: Any) -> str:
+    for artifact in execution.artifacts:
+        if artifact.artifact_type is _STDOUT and artifact.content is not None:
+            try:
+                return artifact.content.decode("utf-8", errors="replace")
+            except Exception:  # pragma: no cover
+                return ""
+    return ""
+
+
+def _build_usage(execution: Any) -> dict:
+    if execution.token_usage is None:
+        return {"input_tokens": 0, "output_tokens": 0}
+    tu = execution.token_usage
+    return {
+        "input_tokens": tu.input_tokens or 0,
+        "output_tokens": tu.output_tokens or 0,
+        "cache_read_input_tokens": getattr(tu, "cache_read_tokens", None) or 0,
+        "cache_creation_input_tokens": getattr(tu, "cache_write_tokens", None) or 0,
+    }
+
+
+@router.post(
+    "/v1/messages",
+    responses={
+        422: {"description": "Multi-turn request (only single-turn supported in 0.13.0)"},
+        502: {"description": "Upstream Anthropic call failed"},
+        503: {"description": "Anthropic adapter not available"},
+    },
+)
+async def proxy_messages(body: MessagesRequest, request: Request) -> MessagesResponse:
+    """Cache-aware proxy for POST https://api.anthropic.com/v1/messages.
+
+    Only single-turn conversations (one user message) are supported in 0.13.0.
+    Multi-turn requests (messages with more than one entry) return HTTP 422.
+    """
+    user_messages = [m for m in body.messages if m.role == "user"]
+    if len(user_messages) != 1 or len(body.messages) > 1:
+        raise HTTPException(
+            status_code=422,
+            detail=(
+                "The gateway currently supports single-turn requests only "
+                "(one role=user message, no prior assistant turns). "
+                "Multi-turn support is planned."
+            ),
+        )
+
+    try:
+        kind = resolve_execution_kind(_CLIENT)
+    except Exception as exc:  # pragma: no cover
+        raise HTTPException(status_code=503, detail=str(exc)) from exc
+
+    command = RunMlExecutionCommand(
+        execution_kind=kind,
+        client=_CLIENT,
+        model=body.model,
+        prompt=user_messages[0].content,
+        user_system_prompt=body.system,
+        session_id=body.session_id,
+    )
+
+    wired = request.app.state.wired
+    loop = asyncio.get_event_loop()
+    execution = await loop.run_in_executor(None, wired.run_ml.execute, command)
+
+    if execution.execution_state is ExecutionState.FAILED:
+        raise HTTPException(
+            status_code=502,
+            detail="upstream Anthropic call failed",
+        )
+
+    stdout = _extract_stdout(execution)
+    cache_hit = execution.execution_state is ExecutionState.SUCCESS and bool(stdout)
+
+    return MessagesResponse(
+        id=f"msg_{secrets.token_hex(12)}",
+        content=[ContentBlock(text=stdout)],
+        model=body.model,
+        usage=_build_usage(execution),
+        x_cache_hit=cache_hit,
+    )

generic_ml_cache_daemon/routes/health.py

@@ -0,0 +1,75 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Routes: /health, /ready, /info, /metrics."""
+
+from __future__ import annotations
+
+from typing import List
+
+from fastapi import APIRouter, Request, Response
+from fastapi.responses import JSONResponse, PlainTextResponse
+
+from generic_ml_cache_core.adapter.out.api.api_registry import registered_api_names
+from generic_ml_cache_core.adapter.out.client.registry import registered_names
+
+from generic_ml_cache_daemon import __version__
+from generic_ml_cache_daemon.metrics import is_prometheus_available
+from generic_ml_cache_daemon.models.health import HealthResponse, InfoResponse, ReadyResponse
+
+router = APIRouter()
+
+
+@router.get("/health")
+def get_health() -> HealthResponse:
+    """Liveness: confirm the daemon process is alive."""
+    return HealthResponse(status="ok")
+
+
+@router.get("/ready", response_model=ReadyResponse)
+def get_ready(request: Request) -> Response:
+    """Readiness: confirm the store is accessible and the daemon can serve requests."""
+    wired = request.app.state.wired
+    try:
+        wired.metrics.event_counts()
+        return JSONResponse(content=ReadyResponse(status="ready").model_dump())
+    except Exception:
+        return JSONResponse(
+            status_code=503,
+            content=ReadyResponse(status="not ready", detail="store not accessible").model_dump(),
+        )
+
+
+@router.get("/info", response_model=InfoResponse)
+def get_info(request: Request) -> InfoResponse:
+    """Return daemon version, store path, active adapters, and bound session."""
+    store_root: str = str(request.app.state.store_root)
+    session_id: str | None = request.app.state.session_id
+    all_adapter_names: List[str] = sorted(set(registered_names()) | set(registered_api_names()))
+    return InfoResponse(
+        version=__version__,
+        store_root=store_root,
+        session_id=session_id,
+        adapters=all_adapter_names,
+    )
+
+
+@router.get("/metrics")
+def get_metrics(request: Request) -> Response:
+    """Prometheus metrics. Requires the [metrics] extra and enable_metrics=True."""
+    if not request.app.state.enable_metrics:
+        return JSONResponse(
+            status_code=503,
+            content={"detail": "metrics endpoint not enabled (start daemon with --metrics)"},
+        )
+    if not is_prometheus_available():  # pragma: no cover
+        return JSONResponse(
+            status_code=501,
+            content={"detail": "prometheus-client extra not installed"},
+        )
+    import prometheus_client  # type: ignore[import-untyped]
+
+    metrics_output = prometheus_client.generate_latest()
+    return PlainTextResponse(
+        content=metrics_output.decode("utf-8"),
+        media_type=prometheus_client.CONTENT_TYPE_LATEST,
+    )

generic_ml_cache_daemon/routes/jobs.py

@@ -0,0 +1,91 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Routes: /jobs — submit detached background executions and stream/poll their status."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any, AsyncIterator, Dict, Optional
+
+from fastapi import APIRouter, HTTPException, Request
+
+from generic_ml_cache_core.application.domain.model.execution.artifact import ArtifactType
+
+from generic_ml_cache_daemon.jobs import Job, JobState
+from generic_ml_cache_daemon.models.job import JobResponse, JobSubmitBody
+from generic_ml_cache_daemon.routes.run import _build_command, _extract_artifact
+
+router = APIRouter(prefix="/jobs")
+
+_STDOUT = ArtifactType.STDOUT
+_STDERR = ArtifactType.STDERR
+_SSE_POLL_INTERVAL = 0.1
+
+
+def _job_to_response(job: Job) -> JobResponse:
+    execution_key: Optional[str] = None
+    stdout: Optional[str] = None
+    stderr: Optional[str] = None
+    if job.execution is not None:
+        execution_key = job.execution.call_identity.generate_key()
+        stdout = _extract_artifact(job.execution, _STDOUT)
+        stderr = _extract_artifact(job.execution, _STDERR)
+    return JobResponse(
+        job_id=job.job_id,
+        state=job.state.value,
+        execution_key=execution_key,
+        stdout=stdout,
+        stderr=stderr,
+        error=job.error,
+    )
+
+
+@router.post("", status_code=202)
+def submit_job(body: JobSubmitBody, request: Request) -> JobResponse:
+    """Submit an execution to run in the background. Returns immediately with
+    a job_id in 'pending' state."""
+    command = _build_command(body)  # type: ignore[arg-type]
+    wired = request.app.state.wired
+    registry = request.app.state.job_registry
+    job = registry.submit(wired.run_ml.execute, command)
+    return _job_to_response(job)
+
+
+@router.get("")
+def list_jobs(request: Request) -> Dict[str, Any]:
+    """Return all known job IDs."""
+    registry = request.app.state.job_registry
+    return {"job_ids": registry.list_ids()}
+
+
+@router.get("/{job_id}", responses={404: {"description": "Job not found"}})
+def get_job(job_id: str, request: Request) -> JobResponse:
+    """Return the current status of a job."""
+    registry = request.app.state.job_registry
+    job = registry.get(job_id)
+    if job is None:
+        raise HTTPException(status_code=404, detail=f"job {job_id!r} not found")
+    return _job_to_response(job)
+
+
+@router.get("/{job_id}/stream", responses={404: {"description": "Job not found"}})
+async def stream_job(job_id: str, request: Request) -> Any:
+    """SSE stream for a job. Emits a 'status' event every 100ms until the job
+    completes, then a final 'complete' or 'error' event."""
+    from sse_starlette.sse import EventSourceResponse
+
+    registry = request.app.state.job_registry
+    job = registry.get(job_id)
+    if job is None:
+        raise HTTPException(status_code=404, detail=f"job {job_id!r} not found")
+
+    async def generator() -> AsyncIterator[Dict[str, str]]:
+        while job.state not in (JobState.DONE, JobState.ERROR):  # pragma: no cover
+            yield {"data": json.dumps({"type": "status", "state": job.state.value})}
+            await asyncio.sleep(_SSE_POLL_INTERVAL)
+        response = _job_to_response(job)
+        event_type = "complete" if job.state is JobState.DONE else "error"
+        yield {"data": json.dumps({"type": event_type, **response.model_dump()})}
+
+    return EventSourceResponse(generator())

generic_ml_cache_daemon/routes/run.py

@@ -0,0 +1,114 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Route: POST /run — synchronous execution or SSE stream, content-negotiated."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any, AsyncIterator, Dict, Optional
+
+from fastapi import APIRouter, HTTPException, Request
+from fastapi.responses import JSONResponse
+from sse_starlette.sse import EventSourceResponse
+
+from generic_ml_cache_core.adapter.inbound.composition import resolve_execution_kind
+from generic_ml_cache_core.application.domain.model.execution.artifact import ArtifactType
+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.inbound.run_ml_execution_command import (
+    RunMlExecutionCommand,
+)
+
+from generic_ml_cache_daemon.models.run import RunBody, RunResponse
+
+router = APIRouter()
+
+_STDOUT = ArtifactType.STDOUT
+_STDERR = ArtifactType.STDERR
+
+
+def _build_command(body: RunBody) -> RunMlExecutionCommand:
+    try:
+        kind = resolve_execution_kind(body.client)
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    return RunMlExecutionCommand(
+        execution_kind=kind,
+        client=body.client,
+        model=body.model,
+        effort=body.effort,
+        prompt=body.prompt,
+        context=body.context,
+        tags=body.tags,
+        session_id=body.session_id,
+    )
+
+
+def _extract_artifact(execution: MlExecution, artifact_type: ArtifactType) -> Optional[str]:
+    for artifact in execution.artifacts:
+        if artifact.artifact_type is artifact_type and artifact.content is not None:
+            try:
+                return artifact.content.decode("utf-8", errors="replace")
+            except Exception:  # pragma: no cover
+                return None
+    return None
+
+
+def _was_cache_hit(execution: MlExecution) -> bool:
+    return execution.execution_state is ExecutionState.SUCCESS and any(
+        a.artifact_type is _STDOUT for a in execution.artifacts
+    )
+
+
+def _to_response(execution: MlExecution, cache_hit: bool) -> RunResponse:
+    key = execution.call_identity.generate_key()
+    return RunResponse(
+        execution_key=key,
+        state=execution.execution_state.value,
+        cache_hit=cache_hit,
+        stdout=_extract_artifact(execution, _STDOUT),
+        stderr=_extract_artifact(execution, _STDERR),
+    )
+
+
+def _to_dict(response: RunResponse) -> Dict[str, Any]:
+    return response.model_dump()
+
+
+async def _run_in_thread(wired: Any, command: RunMlExecutionCommand) -> MlExecution:
+    loop = asyncio.get_event_loop()
+    return await loop.run_in_executor(None, wired.run_ml.execute, command)
+
+
+async def _sse_generator(
+    wired: Any, command: RunMlExecutionCommand
+) -> AsyncIterator[Dict[str, str]]:
+    yield {"data": json.dumps({"type": "accepted"})}
+    execution = await _run_in_thread(wired, command)
+    hit = _was_cache_hit(execution)
+    response = _to_response(execution, hit)
+    yield {"data": json.dumps({"type": "complete", **_to_dict(response)})}
+
+
+@router.post("/run", responses={400: {"description": "Unknown or unsupported client"}})
+async def run(body: RunBody, request: Request) -> Any:
+    """Execute an ML call synchronously (JSON) or as a server-sent event stream (SSE).
+
+    Content negotiation:
+    - ``Accept: text/event-stream`` → SSE: an ``accepted`` event followed by a
+      ``complete`` event when the execution finishes.
+    - Any other ``Accept`` → JSON: blocks until the execution completes.
+    """
+    command = _build_command(body)
+    wired = request.app.state.wired
+
+    if "text/event-stream" in request.headers.get("accept", ""):
+        return EventSourceResponse(_sse_generator(wired, command))
+
+    execution = await _run_in_thread(wired, command)
+    cache_hit = _was_cache_hit(execution)
+    response = _to_response(execution, cache_hit)
+    return JSONResponse(content=_to_dict(response))

generic_ml_cache_daemon/routes/sessions.py

@@ -0,0 +1,122 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Routes: /sessions — CRUD, stats, spec, and tags."""
+
+from __future__ import annotations
+
+import secrets
+
+from fastapi import APIRouter, HTTPException, Request
+
+from generic_ml_cache_core.application.domain.model.session.session_spec import SessionSpec
+
+from generic_ml_cache_daemon.models.session import (
+    SessionCreateBody,
+    SessionListResponse,
+    SessionResponse,
+    SessionStatsResponse,
+    SpecBody,
+    TagBody,
+)
+
+router = APIRouter(prefix="/sessions")
+
+_HIT = "hit"
+_MISS = "miss"
+
+
+def _spec_to_body(spec: SessionSpec | None) -> SpecBody | None:
+    if spec is None:
+        return None
+    return SpecBody(client=spec.client, model=spec.model, effort=spec.effort)
+
+
+def _session_response(metrics, session_id: str) -> SessionResponse:
+    return SessionResponse(
+        session_id=session_id,
+        tags=metrics.session_tags(session_id),
+        spec=_spec_to_body(metrics.session_spec(session_id)),
+    )
+
+
+@router.get("")
+def list_sessions(request: Request) -> SessionListResponse:
+    """Return all known session IDs."""
+    metrics = request.app.state.wired.metrics
+    return SessionListResponse(session_ids=metrics.list_session_ids())
+
+
+@router.post("", status_code=201)
+def create_session(body: SessionCreateBody, request: Request) -> SessionResponse:
+    """Create a new session, optionally seeding it with tags and/or a spec."""
+    session_id = secrets.token_hex(8)
+    metrics = request.app.state.wired.metrics
+    for tag in body.tags:
+        metrics.add_session_tag(session_id, tag)
+    if body.spec is not None:
+        metrics.set_session_spec(
+            session_id,
+            SessionSpec(client=body.spec.client, model=body.spec.model, effort=body.spec.effort),
+        )
+    return _session_response(metrics, session_id)
+
+
+@router.get("/{session_id}", responses={404: {"description": "Session not found"}})
+def get_session(session_id: str, request: Request) -> SessionResponse:
+    """Return tags and spec for a session."""
+    metrics = request.app.state.wired.metrics
+    tags = metrics.session_tags(session_id)
+    spec = metrics.session_spec(session_id)
+    if not tags and spec is None:
+        raise HTTPException(status_code=404, detail=f"session {session_id!r} not found")
+    return SessionResponse(session_id=session_id, tags=tags, spec=_spec_to_body(spec))
+
+
+@router.get("/{session_id}/stats")
+def get_session_stats(session_id: str, request: Request) -> SessionStatsResponse:
+    """Return call/hit statistics for a session."""
+    metrics = request.app.state.wired.metrics
+    counts = metrics.session_event_counts(session_id)
+    hits = counts.get(_HIT, 0)
+    misses = counts.get(_MISS, 0)
+    calls = hits + misses
+    hit_rate = round(hits / calls, 4) if calls > 0 else 0.0
+    return SessionStatsResponse(
+        session_id=session_id,
+        tags=metrics.session_tags(session_id),
+        spec=_spec_to_body(metrics.session_spec(session_id)),
+        calls=calls,
+        hits=hits,
+        hit_rate=hit_rate,
+    )
+
+
+@router.put("/{session_id}/spec", status_code=200)
+def set_session_spec(session_id: str, body: SpecBody, request: Request) -> SessionResponse:
+    """Attach or replace the execution spec for a session."""
+    metrics = request.app.state.wired.metrics
+    metrics.set_session_spec(
+        session_id,
+        SessionSpec(client=body.client, model=body.model, effort=body.effort),
+    )
+    return _session_response(metrics, session_id)
+
+
+@router.delete("/{session_id}/spec", status_code=204)
+def clear_session_spec(session_id: str, request: Request) -> None:
+    """Remove the execution spec for a session (no-op if absent)."""
+    request.app.state.wired.metrics.clear_session_spec(session_id)
+
+
+@router.post("/{session_id}/tags", status_code=201)
+def add_session_tag(session_id: str, body: TagBody, request: Request) -> SessionResponse:
+    """Add a tag to a session."""
+    metrics = request.app.state.wired.metrics
+    metrics.add_session_tag(session_id, body.tag)
+    return _session_response(metrics, session_id)
+
+
+@router.delete("/{session_id}/tags/{tag}", status_code=204)
+def remove_session_tag(session_id: str, tag: str, request: Request) -> None:
+    """Remove a tag from a session (no-op if tag is absent)."""
+    request.app.state.wired.metrics.remove_session_tag(session_id, tag)

generic_ml_cache_daemon-0.13.0.dist-info/METADATA

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: generic-ml-cache-daemon
+Version: 0.13.0
+Summary: Local HTTP daemon for generic-ml-cache: REST API, gateway proxy, and session transport. A thin inbound driver over generic-ml-cache-core.
+Project-URL: Homepage, https://github.com/danielslobozian/generic-ml-cache
+Project-URL: Repository, https://github.com/danielslobozian/generic-ml-cache
+Project-URL: Issues, https://github.com/danielslobozian/generic-ml-cache/issues
+Project-URL: Changelog, https://github.com/danielslobozian/generic-ml-cache/blob/main/CHANGELOG.md
+Author: Daniel Slobozian
+License-Expression: Apache-2.0
+Keywords: ai,cache,daemon,fastapi,gateway,http,llm,proxy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: fastapi>=0.115
+Requires-Dist: generic-ml-cache-core>=0.12.0
+Requires-Dist: sse-starlette>=2.0
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: dev
+Requires-Dist: coverage>=7; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: prometheus-client>=0.20; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.15; extra == 'dev'
+Provides-Extra: metrics
+Requires-Dist: prometheus-client>=0.20; extra == 'metrics'

generic_ml_cache_daemon-0.13.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+generic_ml_cache_daemon/__init__.py,sha256=AXxNWYeI4Ago5Q0i6K_9XF7N7mhRGikxniniOL-olsE,109
+generic_ml_cache_daemon/__main__.py,sha256=bK_4qHAvsSeI82iKWycVa7l_V66pfQ7UrxYrEWYZtII,819
+generic_ml_cache_daemon/app.py,sha256=ao_O2G99wYqPXXH_y-x5HL3sDioORuzXDbM3iS6-Ess,2290
+generic_ml_cache_daemon/jobs.py,sha256=PERCq9uk_aKsasUi4ulKY_CT7a2GujkMzKVPRLn7zRw,2504
+generic_ml_cache_daemon/metrics.py,sha256=z5Go7NLznbZdMLIBr_ifTzUl6_qplQX8U5X0xRlabVk,507
+generic_ml_cache_daemon/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+generic_ml_cache_daemon/models/__init__.py,sha256=Btv93JzW7tt7nDwSgwfnpysoCcAjHee0up8CJAOyKvQ,86
+generic_ml_cache_daemon/models/execution.py,sha256=tQDhTwQadJ8T5ODJMF4xYZiMXRa9APlpBIhn44YzS44,1139
+generic_ml_cache_daemon/models/gateway.py,sha256=hKxMZ5wK04CjtwNlnBQVhnNUqIgUG05BrwqQAw6fhrI,871
+generic_ml_cache_daemon/models/health.py,sha256=abnyljTynlCkaTLJuY8UK01vzMLm7OVCmF5TYW93FLI,517
+generic_ml_cache_daemon/models/job.py,sha256=LzTqr3TNImTEYcH4pQuQVrFjTJJMkV4QqPJ4CFbJcCA,659
+generic_ml_cache_daemon/models/run.py,sha256=pq6tA9o7U8edFwdTsPiPUkFDuhcpK-qN6lF4iRObvuQ,575
+generic_ml_cache_daemon/models/session.py,sha256=zrsuM5YTzYzbqJnUJOAUnBgSOkIumy430Erg-qS1n3M,799
+generic_ml_cache_daemon/routes/__init__.py,sha256=Btv93JzW7tt7nDwSgwfnpysoCcAjHee0up8CJAOyKvQ,86
+generic_ml_cache_daemon/routes/executions.py,sha256=Is8aK4lxyChdenzewJGowZI37c-vA1geK7TIpOc5DIw,3659
+generic_ml_cache_daemon/routes/gateway.py,sha256=8b33uDkDsmKVF2VeqPkiml1FijkpqZ-FjaKHcr3kUto,4054
+generic_ml_cache_daemon/routes/health.py,sha256=lnytyIPedyQig07k73YsMwqat2Z8Q-UdEECjld1T2Ck,2773
+generic_ml_cache_daemon/routes/jobs.py,sha256=I_lSVDK9JxTS35o22W5czoIUXUes2KhV_cp3TG3Jf8g,3429
+generic_ml_cache_daemon/routes/run.py,sha256=D2MdhGgBEanzhzgMUCtWyAyeDxw2sMzp9M6BnHT02Uw,4080
+generic_ml_cache_daemon/routes/sessions.py,sha256=FfDi0TlPdQreY1ODzhzKqi4vqPdXwIyu1uRAV0Jlh7Q,4367
+generic_ml_cache_daemon-0.13.0.dist-info/METADATA,sha256=--ru-jyhRlUpgENQJbkEwHwRYrjYGt_MTpxweBw8mQs,1720
+generic_ml_cache_daemon-0.13.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+generic_ml_cache_daemon-0.13.0.dist-info/RECORD,,

generic_ml_cache_daemon-0.13.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any