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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: generic-ml-cache-cli
-Version: 0.5.0
+Version: 0.7.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.5.0
+Requires-Dist: generic-ml-cache-core>=0.7.0
 Provides-Extra: dev
 Requires-Dist: coverage>=7; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
@@ -33,7 +33,12 @@ Requires-Dist: ruff>=0.15; extra == 'dev'
 Requires-Dist: vulture>=2; extra == 'dev'
 Description-Content-Type: text/markdown
 
-# gmlcache
+<p align="center">
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/danielslobozian/generic-ml-cache/main/docs/images/gmlcache-lockup-dark.png">
+  <img src="https://raw.githubusercontent.com/danielslobozian/generic-ml-cache/main/docs/images/gmlcache-lockup.png" alt="gmlcache" width="300">
+</picture>
+</p>
 
 #### Detached ML Execution Cache — the terminal client
 
@@ -43,6 +48,11 @@ Description-Content-Type: text/markdown
 `gmlcache` runs, records, and replays detached ML workloads — record a real client (or
 API) call once, replay it forever by its content key, offline and byte-for-byte.
 
+> **Single-user, local — not a gateway.** gmlcache runs on your machine, as you, across the
+> subscriptions and APIs you already hold. It is **not** a multi-user router and **not** a way
+> to share one subscription — see
+> [Positioning](https://github.com/danielslobozian/generic-ml-cache/blob/main/docs/design/positioning.md).
+
 <p align="center">
 <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>

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

@@ -1,4 +1,9 @@
-# gmlcache
+<p align="center">
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/danielslobozian/generic-ml-cache/main/docs/images/gmlcache-lockup-dark.png">
+  <img src="https://raw.githubusercontent.com/danielslobozian/generic-ml-cache/main/docs/images/gmlcache-lockup.png" alt="gmlcache" width="300">
+</picture>
+</p>
 
 #### Detached ML Execution Cache — the terminal client
 
@@ -8,6 +13,11 @@
 `gmlcache` runs, records, and replays detached ML workloads — record a real client (or
 API) call once, replay it forever by its content key, offline and byte-for-byte.
 
+> **Single-user, local — not a gateway.** gmlcache runs on your machine, as you, across the
+> subscriptions and APIs you already hold. It is **not** a multi-user router and **not** a way
+> to share one subscription — see
+> [Positioning](https://github.com/danielslobozian/generic-ml-cache/blob/main/docs/design/positioning.md).
+
 <p align="center">
 <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>

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "generic-ml-cache-cli"
-version = "0.5.0"
+version = "0.7.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.5.0", "argcomplete>=3,<4"]
+dependencies = ["generic-ml-cache-core>=0.7.0", "argcomplete>=3,<4"]
 
 [project.urls]
 Homepage = "https://github.com/danielslobozian/generic-ml-cache"

{generic_ml_cache_cli-0.5.0 → generic_ml_cache_cli-0.7.0}/src/generic_ml_cache_cli/cli.py

@@ -45,6 +45,7 @@ from generic_ml_cache_core.application.domain.model.run.cache_mode import CacheM
 from generic_ml_cache_core.application.domain.model.run.persistence_depth import PersistenceDepth
 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.usecase.session_report import build_session_report
 from generic_ml_cache_core.application.port.inbound.run_managed_local_execution_command import (
     RunManagedLocalExecutionCommand,
 )
@@ -195,6 +196,7 @@ def _cmd_run(args: argparse.Namespace) -> int:
         persistence_depth=persistence_depth,
         record_on_error=args.record_on_error,
         tags=list(getattr(args, "tag", None) or []),
+        session_id=_resolve_session(args),
     )
 
     def executable_override(client: str):
@@ -877,6 +879,141 @@ def _cmd_invalidate(args: argparse.Namespace) -> int:
     return 0
 
 
+# -- sessions ---------------------------------------------------------------
+
+
+def _resolve_session(args: argparse.Namespace) -> Optional[str]:
+    """The session id for this run: the --session flag, else GMLCACHE_SESSION. A session
+    groups a workflow's calls; it is journal metadata, never part of the cache key."""
+    flag = getattr(args, "session", None)
+    return flag if flag else (os.environ.get("GMLCACHE_SESSION") or None)
+
+
+def _cmd_session_start(args: argparse.Namespace) -> int:
+    import secrets
+
+    # Print only the id, so it is scriptable: SESSION=$(gmlcache session start)
+    print(secrets.token_hex(8))
+    return 0
+
+
+_TOKEN_BLOCKS = " ▏▎▍▌▋▊▉█"
+
+
+def _activity_bar(value: int, maxval: int, width: int = 10) -> str:
+    if maxval <= 0:
+        return " " * width
+    filled = value / maxval * width
+    full = int(filled)
+    bar = "█" * full + (_TOKEN_BLOCKS[int((filled - full) * 8)] if full < width else "")
+    return (bar + " " * width)[:width]
+
+
+def _comma(n: int) -> str:
+    return f"{n:,}"
+
+
+def _render_session_report(report) -> str:
+    lines = [f"session     : {report.session_id}"]
+    if report.span_start:
+        span = (
+            report.span_start
+            if report.day_count == 1
+            else f"{report.span_start} → {report.span_end}"
+        )
+        plural = "" if report.day_count == 1 else "s"
+        lines.append(f"span        : {span}  ({report.day_count} day{plural})")
+    lines.append(
+        f"invocations : {report.invocations}   "
+        f"executions : {report.executions}   hits : {report.hits}"
+    )
+    if report.unknown_usage:
+        lines.append(f"unknown     : {report.unknown_usage} execution(s) reported no usage")
+    if report.by_model:
+        lines.append("")
+        lines.append("by provider / model:")
+        for m in report.by_model:
+            lines.append(
+                f"  {m.client + ' / ' + m.model:<16} spent {_comma(m.spent_tokens):>9} tok"
+                f" (in {_comma(m.spent_input):>8} · out {_comma(m.spent_output):>7})"
+                f"   saved {_comma(m.saved_tokens):>9} tok   {m.executions} exec · {m.hits} hit"
+            )
+    if report.by_day:
+        lines.append("")
+        lines.append("by day (activity):")
+        maxinv = max(d.invocations for d in report.by_day)
+        for d in report.by_day:
+            lines.append(
+                f"  {d.day}  {_activity_bar(d.invocations, maxinv)}  {d.invocations:>3} calls"
+                f"   ({d.executions} exec · {d.hits} hit)"
+            )
+    return "\n".join(lines)
+
+
+def _session_report_json(report) -> dict:
+    return {
+        "session": report.session_id,
+        "invocations": report.invocations,
+        "executions": report.executions,
+        "hits": report.hits,
+        "unknown_usage": report.unknown_usage,
+        "span": {"start": report.span_start, "end": report.span_end, "days": report.day_count},
+        "by_model": [
+            {
+                "client": m.client,
+                "model": m.model,
+                "spent_input": m.spent_input,
+                "spent_output": m.spent_output,
+                "spent_tokens": m.spent_tokens,
+                "saved_tokens": m.saved_tokens,
+                "executions": m.executions,
+                "hits": m.hits,
+            }
+            for m in report.by_model
+        ],
+        "by_day": [
+            {
+                "day": d.day,
+                "invocations": d.invocations,
+                "executions": d.executions,
+                "hits": d.hits,
+            }
+            for d in report.by_day
+        ],
+    }
+
+
+def _cmd_session_report(args: argparse.Namespace) -> int:
+    store_root = _store_root()
+    if store_root is None:
+        return 4
+    wired = build_use_cases(store_root)
+    events = wired.metrics.session_events(args.session_id)
+    # Join each event's execution to its token usage (the current execution per key).
+    usage_by_key = {}
+    for key in {e.execution_key for e in events if e.execution_key}:
+        execution = wired.repository.find_current(key)
+        if execution is not None:
+            usage_by_key[key] = execution.token_usage
+    report = build_session_report(args.session_id, events, usage_by_key)
+
+    if args.json:
+        import json
+
+        print(json.dumps(_session_report_json(report), indent=2))
+        return 0
+    if report.invocations == 0:
+        print(f"no events recorded for session {args.session_id!r}")
+        return 0
+    print(_render_session_report(report))
+    return 0
+
+
+def _cmd_session(args: argparse.Namespace) -> int:
+    print("usage: gmlcache session start | gmlcache session report <id>", file=sys.stderr)
+    return 2
+
+
 def _use_color() -> bool:
     """Colour only when writing to a real terminal and NO_COLOR is unset, so piped
     or redirected output never carries escape codes (the conventional contract)."""
@@ -904,34 +1041,48 @@ def _paint(text: str, *codes: str) -> str:
 
 
 def render_banner(color: bool = False) -> str:
-    """The boxed gmlcache banner. Width is derived from the content, so any version
-    string or tagline stays aligned. ``color`` adds teal ANSI; off yields plain text."""
+    """The boxed gmlcache banner: the cache mark (four hollow bars; the top one is
+    the accent 'hit') beside the title, version, and tagline. Width is derived from
+    the content so everything stays aligned. ``color`` adds ANSI; off yields plain."""
     title = "gmlcache"
     ver = __version__
-    tag = "record · replay · check · tokens"
+    tag = "record · replay · check · sessions · encryption"
+
+    # The mark: four hollow bars -- thin walls (▏ ▕) around a double-line body (═),
+    # widths echoing the logo. The first bar is the accent ("hit"); the rest are dim.
+    bars = ["▏" + "═" * n + "▕" for n in (11, 7, 10, 5)]
+    bar_w = max(len(b) for b in bars)
 
     if color:
-        rule = _TEAL  # teal box
-        name = _BOLD  # bold title
-        vers = _TEAL_BRIGHT  # bright-teal version
-        sub = _GREY  # dim-grey tagline
-        off = _RESET
+        rule, name, vers, sub, off = _TEAL, _BOLD, _TEAL_BRIGHT, _GREY, _RESET
+        bar_colors = [_GREEN, _GREY, _GREY, _GREY]
     else:
         rule = name = vers = sub = off = ""
+        bar_colors = ["", "", "", ""]
 
+    left_pad, gap = "  ", "  "
+    texts = ["", tag, "", ""]  # the tagline sits on the second bar row
+
+    body_w = max(len(left_pad) + bar_w + len(gap) + len(t) for t in texts)
     left_top = f"─ {title} "
     right_top = f" {ver} ─"
-    inner = max(len(left_top) + 6 + len(right_top), len(tag) + 4)
+    inner = max(len(left_top) + 6 + len(right_top), body_w + 1)
     top_dashes = inner - len(left_top) - len(right_top)
-    pad_right = inner - 2 - len(tag)
 
     top = (
         f"{rule}┌─ {off}{name}{title}{off}"
         f"{rule} {'─' * top_dashes} {off}{vers}{ver}{off}{rule} ─┐{off}"
     )
-    mid = f"{rule}│{off}  {sub}{tag}{off}{' ' * pad_right}{rule}│{off}"
+    rows = []
+    for bar, bar_color, text in zip(bars, bar_colors, texts):
+        bar_cell = f"{bar_color}{bar}{off}" + " " * (bar_w - len(bar))
+        used = len(left_pad) + bar_w + len(gap) + len(text)
+        rows.append(
+            f"{rule}│{off}{left_pad}{bar_cell}{gap}{sub}{text}{off}"
+            f"{' ' * (inner - used)}{rule}│{off}"
+        )
     bot = f"{rule}└{'─' * inner}┘{off}"
-    return "\n".join([top, mid, bot])
+    return "\n".join([top, *rows, bot])
 
 
 class _BannerParser(argparse.ArgumentParser):
@@ -1056,6 +1207,9 @@ def build_parser() -> argparse.ArgumentParser:
     run.add_argument(
         "--token", help="encryption token for an encrypted store (or set GMLCACHE_TOKEN)"
     )
+    run.add_argument(
+        "--session", help="group this run under a session id (or set GMLCACHE_SESSION)"
+    )
     run.add_argument(
         "--timeout", type=float, default=None, help="seconds before the real call is killed"
     )
@@ -1242,6 +1396,16 @@ def build_parser() -> argparse.ArgumentParser:
     invalidatep.add_argument("--yes", action="store_true", help="confirm the irreversible wipe")
     invalidatep.set_defaults(func=_cmd_invalidate)
 
+    session = sub.add_parser("session", help="group a workflow's runs under a session id")
+    session_sub = session.add_subparsers(dest="session_command")
+    session_start = session_sub.add_parser("start", help="generate a new session id and print it")
+    session_start.set_defaults(func=_cmd_session_start)
+    session_report = session_sub.add_parser("report", help="summarise a session's activity")
+    session_report.add_argument("session_id", help="the session id to report on")
+    session_report.add_argument("--json", action="store_true", help="emit machine-readable JSON")
+    session_report.set_defaults(func=_cmd_session_report)
+    session.set_defaults(func=_cmd_session)
+
     init = sub.add_parser(
         "init",
         help="create the config file in the default location (if absent), then show the store",

{generic_ml_cache_cli-0.5.0 → generic_ml_cache_cli-0.7.0}/tests/conftest.py

@@ -118,7 +118,13 @@ def _isolate_config(monkeypatch, tmp_path):
     monkeypatch.setenv("GMLCACHE_CONFIG", str(tmp_path / "no-such-config.ini"))
     monkeypatch.setenv("XDG_DATA_HOME", str(tmp_path / "xdg-data"))
     monkeypatch.setenv("LOCALAPPDATA", str(tmp_path / "localappdata"))
-    for var in ("GMLCACHE_MODE", "GMLCACHE_PERSIST", "GMLCACHE_TIMEOUT", "GMLCACHE_TOKEN"):
+    for var in (
+        "GMLCACHE_MODE",
+        "GMLCACHE_PERSIST",
+        "GMLCACHE_TIMEOUT",
+        "GMLCACHE_TOKEN",
+        "GMLCACHE_SESSION",
+    ):
         monkeypatch.delenv(var, raising=False)
 
 

{generic_ml_cache_cli-0.5.0 → generic_ml_cache_cli-0.7.0}/tests/test_cli.py

@@ -134,8 +134,11 @@ def test_run_rejects_retired_location_flags(tmp_path):
 def test_render_banner_lines_align():
     from generic_ml_cache_cli.cli import render_banner
 
-    widths = {len(line) for line in render_banner(color=False).splitlines()}
-    assert len(widths) == 1  # all three box lines are the same width
+    lines = render_banner(color=False).splitlines()
+    widths = {len(line) for line in lines}
+    assert len(widths) == 1  # every box line (top, four mark rows, bottom) is one width
+    assert len(lines) == 6  # the mark adds four bar rows inside the box
+    assert "═" in render_banner(color=False)  # the hollow mark renders
 
 
 def test_render_banner_color_is_opt_in():
@@ -162,7 +165,7 @@ def test_bare_invocation_prints_help_not_an_error(capsys):
     out = capsys.readouterr().out
     assert rc == 0
     assert "gmlcache" in out
-    assert "record · replay · check · tokens" in out
+    assert "record · replay · check · sessions · encryption" in out
     assert "usage:" in out
 
 
@@ -176,7 +179,7 @@ def test_help_flag_shows_the_banner(capsys):
     with pytest.raises(SystemExit) as excinfo:
         main(["-h"])
     assert excinfo.value.code == 0
-    assert "record · replay · check · tokens" in capsys.readouterr().out
+    assert "record · replay · check · sessions · encryption" in capsys.readouterr().out
 
 
 # --- list (grouped by client/model) ---------------------------------------

generic_ml_cache_cli-0.7.0/tests/test_session_cli.py

@@ -0,0 +1,111 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""CLI tests for sessions: run --session / GMLCACHE_SESSION and `session start`."""
+
+from __future__ import annotations
+
+import glob
+import sqlite3
+
+from generic_ml_cache_cli.cli import main
+
+_RUN = ["run", "--client", "fake", "--model", "m1", "--effort", "high", "--prompt", "STDOUT hi"]
+
+
+def _session_ids(tmp_path):
+    dbs = glob.glob(str(tmp_path / "**" / "registry.sqlite3"), recursive=True)
+    if not dbs:
+        return []
+    conn = sqlite3.connect(dbs[0])
+    try:
+        return [r[0] for r in conn.execute("SELECT session_id FROM access_events ORDER BY id")]
+    finally:
+        conn.close()
+
+
+def test_run_with_session_flag_records_the_session_id(tmp_path, capsys):
+    assert main(_RUN + ["--session", "workflow-1"]) == 0
+    capsys.readouterr()
+    assert _session_ids(tmp_path) == ["workflow-1"]
+
+
+def test_run_reads_session_from_env(tmp_path, capsys, monkeypatch):
+    monkeypatch.setenv("GMLCACHE_SESSION", "env-session")
+    assert main(_RUN) == 0
+    capsys.readouterr()
+    assert _session_ids(tmp_path) == ["env-session"]
+
+
+def test_flag_wins_over_env(tmp_path, capsys, monkeypatch):
+    monkeypatch.setenv("GMLCACHE_SESSION", "env-session")
+    assert main(_RUN + ["--session", "flag-session"]) == 0
+    capsys.readouterr()
+    assert _session_ids(tmp_path) == ["flag-session"]
+
+
+def test_run_without_a_session_records_null(tmp_path, capsys):
+    assert main(_RUN) == 0
+    capsys.readouterr()
+    assert _session_ids(tmp_path) == [None]
+
+
+def test_session_start_prints_a_scriptable_id(capsys):
+    assert main(["session", "start"]) == 0
+    out = capsys.readouterr().out.strip()
+    assert out and " " not in out  # a single bare id, usable as $(gmlcache session start)
+    # two starts yield distinct ids
+    main(["session", "start"])
+    assert capsys.readouterr().out.strip() != out
+
+
+def test_bare_session_shows_usage(capsys):
+    assert main(["session"]) == 2
+    assert "session start" in capsys.readouterr().err
+
+
+def test_session_report_rolls_up_invocations_executions_hits(capsys):
+    run = _RUN + ["--session", "wf"]
+    main(run)  # miss -> record (a real execution)
+    main(run)  # same input -> hit (no execution)
+    capsys.readouterr()
+
+    assert main(["session", "report", "wf"]) == 0
+    out = capsys.readouterr().out
+    assert "invocations : 2   executions : 1   hits : 1" in out
+    assert "by provider / model:" in out and "fake / m1" in out
+    assert "by day (activity):" in out
+    # no dollars anywhere in the render (cost is a client-specific advisory estimate)
+    assert "$" not in out and "cost" not in out.lower()
+
+
+def test_session_report_json(capsys):
+    import json
+
+    main(_RUN + ["--session", "wf"])  # one record (the fake client reports no usage)
+    capsys.readouterr()
+    assert main(["session", "report", "wf", "--json"]) == 0
+    out = capsys.readouterr().out
+    assert "cost" not in out.lower() and "usd" not in out.lower() and "$" not in out
+    data = json.loads(out)
+    assert data["session"] == "wf"
+    assert (data["invocations"], data["executions"], data["hits"]) == (1, 1, 0)
+    assert data["unknown_usage"] == 1
+    assert data["span"]["days"] == 1
+    assert data["by_model"] == [
+        {
+            "client": "fake",
+            "model": "m1",
+            "spent_input": 0,
+            "spent_output": 0,
+            "spent_tokens": 0,
+            "saved_tokens": 0,
+            "executions": 1,
+            "hits": 0,
+        }
+    ]
+    assert len(data["by_day"]) == 1 and data["by_day"][0]["invocations"] == 1
+
+
+def test_session_report_unknown_session_is_clean(capsys):
+    assert main(["session", "report", "nope"]) == 0
+    assert "no events" in capsys.readouterr().out