generic-ml-cache-cli 0.7.0__tar.gz → 0.8.0__tar.gz

{generic_ml_cache_cli-0.7.0 → generic_ml_cache_cli-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: generic-ml-cache-cli
-Version: 0.7.0
+Version: 0.8.0
 Summary: Terminal UI for generic-ml-cache: the gmlcache command. A thin inbound driver over generic-ml-cache-core -- reads config, provides the data source, maps commands onto the core library.
 Project-URL: Homepage, https://github.com/danielslobozian/generic-ml-cache
 Project-URL: Repository, https://github.com/danielslobozian/generic-ml-cache
@@ -24,7 +24,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Utilities
 Requires-Python: >=3.9
 Requires-Dist: argcomplete<4,>=3
-Requires-Dist: generic-ml-cache-core>=0.7.0
+Requires-Dist: generic-ml-cache-core>=0.8.0
 Provides-Extra: dev
 Requires-Dist: coverage>=7; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
@@ -57,6 +57,12 @@ API) call once, replay it forever by its content key, offline and byte-for-byte.
 <img src="https://raw.githubusercontent.com/danielslobozian/generic-ml-cache/main/docs/images/gmlcache-demo.gif" alt="gmlcache: a miss records the real client call; the same command again is served instantly from cache, byte-identical" width="760">
 </p>
 
+<p align="center"><sub><b>Detached + live streaming</b> — <code>run --detach</code> returns an id; <code>execution watch</code> follows the client's live progress to the result</sub></p>
+
+<p align="center">
+<img src="https://raw.githubusercontent.com/danielslobozian/generic-ml-cache/main/docs/images/gmlcache-async.gif" alt="gmlcache run --detach, then execution watch streaming the client's live thinking and tool calls to the result" width="760">
+</p>
+
 ## Install
 
 ```bash
@@ -69,12 +75,15 @@ This installs the `gmlcache` command and pulls in the engine,
 ## Use
 
 ```bash
-gmlcache run    --client claude --model sonnet --prompt "…"   # record on a miss, replay on a hit
-gmlcache check  --client claude --model sonnet --prompt "…"   # is this exact call already cached?
-gmlcache list                                                 # stored executions, grouped by client/model
-gmlcache stats                                                # totals, hit counts, token usage & cost
-gmlcache inspect <key>                                        # pretty-print one stored execution
-gmlcache doctor | models | status | init                     # environment & configuration helpers
+gmlcache run    --client claude --model sonnet --prompt "…"            # record on a miss, replay on a hit
+gmlcache check  --client claude --model sonnet --prompt "…"            # forecast: is this exact call cached?
+gmlcache run    --client claude --model sonnet --prompt "…" --detach   # run detached → prints an execution id
+gmlcache execution watch <id>                                         # follow a detached run's live progress
+gmlcache session report <id>                                          # token usage by provider/model for a workflow
+gmlcache encrypt                                                      # encrypt the whole store at rest
+gmlcache export --tag eval -o data.jsonl                              # export the (input, output) dataset corpus
+gmlcache list | tags | stats | inspect <key>                          # browse stored executions
+gmlcache doctor | models | status | init                             # environment & configuration helpers
 ```
 
 ## What it does
@@ -84,6 +93,9 @@ gmlcache doctor | models | status | init                     # environment & con
 - **Replays** an identical request instantly and offline, **byte-for-byte** — gmlcache
   adds nothing to the client's output, so it is a transparent drop-in.
 - **Reports** — list, group, inspect, and measure stored executions and their savings.
+- **And more** — group a workflow's runs into **sessions** with per-provider/model usage
+  reports, **encrypt** the whole store at rest, run **detached** (`--detach`) with a live
+  progress stream, and **export** an `(input, output)` dataset.
 
 ## Built on a reusable engine
 

{generic_ml_cache_cli-0.7.0 → generic_ml_cache_cli-0.8.0}/README.md

@@ -22,6 +22,12 @@ API) call once, replay it forever by its content key, offline and byte-for-byte.
 <img src="https://raw.githubusercontent.com/danielslobozian/generic-ml-cache/main/docs/images/gmlcache-demo.gif" alt="gmlcache: a miss records the real client call; the same command again is served instantly from cache, byte-identical" width="760">
 </p>
 
+<p align="center"><sub><b>Detached + live streaming</b> — <code>run --detach</code> returns an id; <code>execution watch</code> follows the client's live progress to the result</sub></p>
+
+<p align="center">
+<img src="https://raw.githubusercontent.com/danielslobozian/generic-ml-cache/main/docs/images/gmlcache-async.gif" alt="gmlcache run --detach, then execution watch streaming the client's live thinking and tool calls to the result" width="760">
+</p>
+
 ## Install
 
 ```bash
@@ -34,12 +40,15 @@ This installs the `gmlcache` command and pulls in the engine,
 ## Use
 
 ```bash
-gmlcache run    --client claude --model sonnet --prompt "…"   # record on a miss, replay on a hit
-gmlcache check  --client claude --model sonnet --prompt "…"   # is this exact call already cached?
-gmlcache list                                                 # stored executions, grouped by client/model
-gmlcache stats                                                # totals, hit counts, token usage & cost
-gmlcache inspect <key>                                        # pretty-print one stored execution
-gmlcache doctor | models | status | init                     # environment & configuration helpers
+gmlcache run    --client claude --model sonnet --prompt "…"            # record on a miss, replay on a hit
+gmlcache check  --client claude --model sonnet --prompt "…"            # forecast: is this exact call cached?
+gmlcache run    --client claude --model sonnet --prompt "…" --detach   # run detached → prints an execution id
+gmlcache execution watch <id>                                         # follow a detached run's live progress
+gmlcache session report <id>                                          # token usage by provider/model for a workflow
+gmlcache encrypt                                                      # encrypt the whole store at rest
+gmlcache export --tag eval -o data.jsonl                              # export the (input, output) dataset corpus
+gmlcache list | tags | stats | inspect <key>                          # browse stored executions
+gmlcache doctor | models | status | init                             # environment & configuration helpers
 ```
 
 ## What it does
@@ -49,6 +58,9 @@ gmlcache doctor | models | status | init                     # environment & con
 - **Replays** an identical request instantly and offline, **byte-for-byte** — gmlcache
   adds nothing to the client's output, so it is a transparent drop-in.
 - **Reports** — list, group, inspect, and measure stored executions and their savings.
+- **And more** — group a workflow's runs into **sessions** with per-provider/model usage
+  reports, **encrypt** the whole store at rest, run **detached** (`--detach`) with a live
+  progress stream, and **export** an `(input, output)` dataset.
 
 ## Built on a reusable engine
 

{generic_ml_cache_cli-0.7.0 → generic_ml_cache_cli-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "generic-ml-cache-cli"
-version = "0.7.0"
+version = "0.8.0"
 description = "Terminal UI for generic-ml-cache: the gmlcache command. A thin inbound driver over generic-ml-cache-core -- reads config, provides the data source, maps commands onto the core library."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -25,7 +25,7 @@ classifiers = [
   "Programming Language :: Python :: 3.13",
   "Topic :: Utilities",
 ]
-dependencies = ["generic-ml-cache-core>=0.7.0", "argcomplete>=3,<4"]
+dependencies = ["generic-ml-cache-core>=0.8.0", "argcomplete>=3,<4"]
 
 [project.urls]
 Homepage = "https://github.com/danielslobozian/generic-ml-cache"

generic_ml_cache_cli-0.8.0/src/generic_ml_cache_cli/async_jobs.py

@@ -0,0 +1,244 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Detached ("async") execution jobs.
+
+A detached managed run is a separate, OS-detached ``gmlcache`` worker process that does an
+ordinary managed run and records the result into the normal content-addressed cache. The
+launch command returns immediately with a **job id**; the worker outlives it.
+
+State lives under ``<store>/jobs/``:
+
+* ``<id>/spec.json``    — the run to perform (the serialized ``run`` arguments).
+* ``<id>/status.json``  — the mutable lifecycle (submitted → running → succeeded | failed),
+  timings, exit code, and the resulting cache key once done.
+* ``<id>/events.jsonl`` — the durable, append-only NDJSON progress log (for ``watch``).
+* ``locks/<id>.lock``   — a **liveness lock** the worker holds for its whole run.
+
+The liveness lock reuses SQLite's ``BEGIN EXCLUSIVE`` (same trick as the encryption store
+lock): it is released by the OS when the holder's process dies, with no stale locks, on every
+platform. So a reader can tell a *live* worker (lock held) from one that *vanished* mid-run
+(lock free while ``status.json`` still says ``running`` → **interrupted**).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sqlite3
+import subprocess
+import sys
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Iterator, List, Optional
+
+from generic_ml_cache_core.common.errors import StoreLocked
+from generic_ml_cache_core.stream import StreamWriter
+
+#: A job id is generated by gmlcache (secrets.token_hex). Validating against this
+#: allowlist before it ever builds a filesystem path stops a crafted id (``../…``)
+#: from escaping the jobs directory — a user supplies it to `execution <id>`.
+_JOB_ID = re.compile(r"\A[a-z0-9]{1,64}\Z")
+
+
+def _safe_job_id(job_id: str) -> str:
+    if not isinstance(job_id, str) or not _JOB_ID.match(job_id):
+        raise ValueError(f"invalid job id: {job_id!r}")
+    return job_id
+
+
+# Stored lifecycle states.
+SUBMITTED = "submitted"
+RUNNING = "running"
+SUCCEEDED = "succeeded"
+FAILED = "failed"
+#: Derived (never stored): status says running but no worker holds the lock.
+INTERRUPTED = "interrupted"
+TERMINAL = frozenset({SUCCEEDED, FAILED})
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+class JobStore:
+    """The on-disk layout for detached jobs under ``<store>/jobs/``."""
+
+    def __init__(self, store_root: Path) -> None:
+        self._jobs = Path(store_root) / "jobs"
+
+    def _within_jobs(self, candidate: Path, job_id: str) -> Path:
+        # Containment guard (same shape as the output-file writer): the resolved path
+        # must stay inside the jobs directory. Redundant after _safe_job_id, but it is
+        # the explicit, recognized way to prove the path is not user-steerable.
+        resolved = candidate.resolve()
+        base = self._jobs.resolve()
+        if base != resolved and base not in resolved.parents:
+            raise ValueError(f"job id escapes the jobs directory: {job_id!r}")
+        return resolved
+
+    def job_dir(self, job_id: str) -> Path:
+        return self._within_jobs(self._jobs / _safe_job_id(job_id), job_id)
+
+    def lock_path(self, job_id: str) -> Path:
+        return self._within_jobs(self._jobs / "locks" / f"{_safe_job_id(job_id)}.lock", job_id)
+
+    def events_path(self, job_id: str) -> Path:
+        return self.job_dir(job_id) / "events.jsonl"
+
+    def _spec_path(self, job_id: str) -> Path:
+        return self.job_dir(job_id) / "spec.json"
+
+    def _status_path(self, job_id: str) -> Path:
+        return self.job_dir(job_id) / "status.json"
+
+    def exists(self, job_id: str) -> bool:
+        try:
+            return self._status_path(job_id).exists() or self._spec_path(job_id).exists()
+        except ValueError:
+            return False  # an invalid id never names a real job
+
+    def list_ids(self) -> List[str]:
+        if not self._jobs.exists():
+            return []
+        return sorted(p.name for p in self._jobs.iterdir() if p.is_dir() and p.name != "locks")
+
+    def write_spec(self, job_id: str, spec: dict) -> None:
+        self.job_dir(job_id).mkdir(parents=True, exist_ok=True)
+        self._write_json(self._spec_path(job_id), spec)
+
+    def read_spec(self, job_id: str) -> dict:
+        return json.loads(self._spec_path(job_id).read_text(encoding="utf-8"))
+
+    def read_status(self, job_id: str) -> Optional[dict]:
+        try:
+            return json.loads(self._status_path(job_id).read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return None
+
+    def update_status(self, job_id: str, **fields: object) -> dict:
+        """Merge ``fields`` into the job's status.json (creating it), and return it."""
+        status = self.read_status(job_id) or {"job": job_id}
+        status.update(fields)
+        self.job_dir(job_id).mkdir(parents=True, exist_ok=True)
+        self._write_json(self._status_path(job_id), status)
+        return status
+
+    @staticmethod
+    def _write_json(path: Path, data: dict) -> None:
+        # ``path`` is built only from a job id validated by _safe_job_id (allowlist
+        # ``[a-z0-9]{1,64}``) and confined by _within_jobs, so it cannot escape the jobs
+        # directory; ``data`` is gmlcache's own job record (it intentionally stores the run
+        # spec). The taint engine cannot follow the validation across the call chain, so this
+        # verified false positive is suppressed.
+        tmp = path.with_suffix(path.suffix + ".tmp")
+        tmp.write_text(json.dumps(data, indent=2), encoding="utf-8")  # NOSONAR(S2083)
+        tmp.replace(path)  # NOSONAR(S2083)
+
+
+# -- liveness lock (SQLite BEGIN EXCLUSIVE; OS-released on process death) ------
+
+
+@contextmanager
+def hold_job_lock(lock_path: Path) -> Iterator[None]:
+    """Hold the job's exclusive lock for the duration of the block. Raises
+    :class:`StoreLocked` if another worker already owns this job."""
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    connection = sqlite3.connect(lock_path, timeout=0)
+    try:
+        connection.execute("BEGIN EXCLUSIVE")
+    except sqlite3.OperationalError as exc:
+        connection.close()
+        raise StoreLocked(f"job {lock_path.stem} is already owned by a running worker") from exc
+    try:
+        yield
+    finally:
+        try:
+            connection.rollback()
+        finally:
+            connection.close()
+
+
+def job_lock_held(lock_path: Path) -> bool:
+    """Probe: is a worker currently holding this job's lock? (acquire-and-release;
+    held ⇒ a live worker owns the job, free ⇒ no worker is running it)."""
+    if not lock_path.exists():
+        return False
+    try:
+        connection = sqlite3.connect(lock_path, timeout=0)
+    except sqlite3.Error:
+        return False
+    try:
+        connection.execute("BEGIN EXCLUSIVE")
+        connection.rollback()
+        return False
+    except sqlite3.OperationalError:
+        return True
+    finally:
+        connection.close()
+
+
+def derived_state(status: Optional[dict], lock_held: bool) -> str:
+    """The reported state: terminal as stored; a stored ``running`` with no live
+    worker (lock free) is reported as :data:`INTERRUPTED`."""
+    if status is None:
+        return "unknown"
+    state = str(status.get("state", "unknown"))
+    if state == RUNNING and not lock_held:
+        return INTERRUPTED
+    return state
+
+
+# -- detached spawn -----------------------------------------------------------
+
+
+def spawn_worker(store_root: Path, job_id: str, token: Optional[str] = None) -> None:
+    """Launch a detached ``gmlcache`` worker for ``job_id``. The child is fully
+    detached (new session / process group, no console, I/O to devnull), so it
+    outlives this command. Cross-platform (POSIX setsid; Windows DETACHED_PROCESS).
+
+    If ``token`` is given, it is handed to the worker through its **environment**
+    (``GMLCACHE_TOKEN``) so a detached run can write to an encrypted store — never on
+    disk. The worker holds it in memory for the run, exactly as a sync call would."""
+    argv = [sys.executable, "-m", "generic_ml_cache_cli", "__worker", str(store_root), job_id]
+    env = None
+    if token is not None:
+        env = dict(os.environ)
+        env["GMLCACHE_TOKEN"] = token
+    devnull = subprocess.DEVNULL
+    if os.name == "nt":
+        flags = subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP  # type: ignore[attr-defined]
+        subprocess.Popen(
+            argv,
+            stdin=devnull,
+            stdout=devnull,
+            stderr=devnull,
+            creationflags=flags,
+            close_fds=True,
+            env=env,
+        )
+    else:
+        subprocess.Popen(
+            argv,
+            stdin=devnull,
+            stdout=devnull,
+            stderr=devnull,
+            start_new_session=True,
+            close_fds=True,
+            env=env,
+        )
+
+
+def append_event(events_path: Path, kind: str, **fields: object) -> None:
+    """Append one NDJSON progress event to the job's durable event log (best-effort).
+    Same format as the run stream, so ``watch`` reads one log whatever wrote it."""
+    writer = StreamWriter(events_path)
+    try:
+        writer.event(kind, **fields)
+    finally:
+        writer.close()
+
+
+def now() -> str:
+    return _now()