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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: generic-ml-cache-cli
-Version: 0.5.0
+Version: 0.6.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.6.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.6.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.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "generic-ml-cache-cli"
-version = "0.5.0"
+version = "0.6.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.6.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.6.0}/src/generic_ml_cache_cli/cli.py

@@ -195,6 +195,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 +878,71 @@ 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
+
+
+#: events where a real client call ran (vs. HIT, which replayed, or an offline MISS).
+_EXECUTED_EVENTS = {"record", "run", "would_hit", "would_miss"}
+
+
+def _cmd_session_report(args: argparse.Namespace) -> int:
+    store_root = _store_root()
+    if store_root is None:
+        return 4
+    counts = build_use_cases(store_root).metrics.session_event_counts(args.session_id)
+    invocations = sum(counts.values())
+    executions = sum(n for event, n in counts.items() if event in _EXECUTED_EVENTS)
+    hits = counts.get("hit", 0)
+
+    if args.json:
+        import json
+
+        print(
+            json.dumps(
+                {
+                    "session": args.session_id,
+                    "invocations": invocations,
+                    "executions": executions,
+                    "hits": hits,
+                    "events": counts,
+                },
+                indent=2,
+            )
+        )
+        return 0
+
+    if invocations == 0:
+        print(f"no events recorded for session {args.session_id!r}")
+        return 0
+    print(f"session     : {args.session_id}")
+    print(f"invocations : {invocations}")
+    print(f"executions  : {executions}  (real client calls)")
+    print(f"hits        : {hits}  (served from cache)")
+    breakdown = ", ".join(f"{event}={counts[event]}" for event in sorted(counts))
+    print(f"events      : {breakdown}")
+    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 +970,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 +1136,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 +1325,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.6.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.6.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.6.0/tests/test_session_cli.py

@@ -0,0 +1,97 @@
+# 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" in out
+    assert "executions  : 1" in out
+    assert "hits        : 1" in out
+
+
+def test_session_report_json(capsys):
+    import json
+
+    main(_RUN + ["--session", "wf"])
+    capsys.readouterr()
+    assert main(["session", "report", "wf", "--json"]) == 0
+    data = json.loads(capsys.readouterr().out)
+    assert data == {
+        "session": "wf",
+        "invocations": 1,
+        "executions": 1,
+        "hits": 0,
+        "events": {"record": 1},
+    }
+
+
+def test_session_report_unknown_session_is_clean(capsys):
+    assert main(["session", "report", "nope"]) == 0
+    assert "no events" in capsys.readouterr().out