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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: generic-ml-cache-cli
-Version: 0.8.0
+Version: 0.9.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.8.0
+Requires-Dist: generic-ml-cache-core>=0.9.0
 Provides-Extra: dev
 Requires-Dist: coverage>=7; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
@@ -78,6 +78,7 @@ This installs the `gmlcache` command and pulls in the engine,
 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 alias  claude -- -p "…" --model sonnet                        # thin wrapper: cache a raw native call
 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

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

@@ -43,6 +43,7 @@ This installs the `gmlcache` command and pulls in the engine,
 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 alias  claude -- -p "…" --model sonnet                        # thin wrapper: cache a raw native call
 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

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

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

{generic_ml_cache_cli-0.8.0 → generic_ml_cache_cli-0.9.0}/src/generic_ml_cache_cli/cli.py

@@ -53,6 +53,9 @@ from generic_ml_cache_cli import async_jobs
 from generic_ml_cache_core.application.port.inbound.run_managed_local_execution_command import (
     RunManagedLocalExecutionCommand,
 )
+from generic_ml_cache_core.application.port.inbound.run_passthrough_execution_command import (
+    RunPassthroughExecutionCommand,
+)
 from generic_ml_cache_core.application.port.out.base import ClientAdapter
 from generic_ml_cache_core.common.errors import (
     CacheError,
@@ -185,13 +188,7 @@ def _resolve_managed_run(args: argparse.Namespace):
     settings = config.resolve_settings(
         file_cfg, mode_flag=args.mode, persist_flag=args.persist, timeout_flag=args.timeout
     )
-    # --offline / --force are explicit flags and win over the resolved mode.
-    if args.offline:
-        cache_mode = CacheMode.OFFLINE
-    elif args.force:
-        cache_mode = CacheMode.REFRESH
-    else:
-        cache_mode = CacheMode(str(settings["mode"][0]))
+    cache_mode = _resolve_cache_mode(args, settings)
 
     spec = {
         "client": args.client,
@@ -242,31 +239,29 @@ def _spec_executable_override(spec: dict):
     return lambda client: executable
 
 
-def _cmd_run(args: argparse.Namespace) -> int:
-    try:
-        spec, store_root, token = _resolve_managed_run(args)
-    except ConfigError as exc:
-        print(f"gmlc: {exc}", file=sys.stderr)
-        return 4
+def _resolve_cache_mode(args: argparse.Namespace, settings: dict) -> CacheMode:
+    """The cache mode for a run: --offline / --force are explicit flags and win over
+    the resolved (config/env/default) mode. Shared by managed `run` and `alias`."""
+    if args.offline:
+        return CacheMode.OFFLINE
+    if args.force:
+        return CacheMode.REFRESH
+    return CacheMode(str(settings["mode"][0]))
 
-    if getattr(args, "detach", False):
-        return _submit_detached(spec, store_root, token)
 
-    command = _command_from_spec(spec)
+def _run_cached_execution(execute):
+    """Run a wired ``execute()`` call, translating the failure modes shared by every
+    cached command into ``(None, exit_code)``; on success returns ``(execution, None)``.
+
+    Centralising the ladder keeps `run` and `alias` byte-identical on errors and means
+    the rarely-hit branches (interrupt, timeout) are covered once, by the `run` tests."""
     try:
-        wired = build_use_cases(
-            store_root,
-            _spec_executable_override(spec),
-            spec["timeout"],
-            encryption_token=token,
-            stream_path=getattr(args, "stream", None),
-        )
-        execution = wired.run_managed.execute(command)
+        return execute(), None
     except RunInterrupted as exc:
         # A requested stop, not a failure: nothing was recorded. Exit 130 is the
         # conventional "terminated by Ctrl-C".
         print(f"gmlc: {exc}", file=sys.stderr)
-        return 130
+        return None, 130
     except subprocess.TimeoutExpired as exc:
         # The real call ran past --timeout and was killed before any record. Exit
         # 124 is the timeout(1) convention, distinct from miss (3) and error (4).
@@ -274,28 +269,102 @@ def _cmd_run(args: argparse.Namespace) -> int:
             f"gmlc: real call exceeded the {exc.timeout}s timeout and was killed; nothing recorded",
             file=sys.stderr,
         )
-        return 124
+        return None, 124
     except CacheMiss as exc:
         print(f"gmlc: {exc}", file=sys.stderr)
-        return 3
+        return None, 3
     except (EncryptionTokenRequired, WrongEncryptionToken) as exc:
         print(f"gmlc: {exc} (set --token or GMLCACHE_TOKEN)", file=sys.stderr)
-        return 4
+        return None, 4
     except CacheError as exc:
+        print(f"gmlc: {exc}", file=sys.stderr)
+        return None, 4
+
+
+def _relay_execution(execution: MlExecution) -> int:
+    """Reproduce a (live or replayed) call's stdout, stderr and exit code exactly --
+    the quiet-mode fidelity contract shared by `run` and `alias`."""
+    sys.stdout.write(_artifact_text(execution, ArtifactType.STDOUT))
+    sys.stdout.flush()
+    sys.stderr.write(_artifact_text(execution, ArtifactType.STDERR))
+    sys.stderr.flush()
+    return _run_exit_code(execution)
+
+
+def _cmd_run(args: argparse.Namespace) -> int:
+    try:
+        spec, store_root, token = _resolve_managed_run(args)
+    except ConfigError as exc:
         print(f"gmlc: {exc}", file=sys.stderr)
         return 4
 
+    if getattr(args, "detach", False):
+        return _submit_detached(spec, store_root, token)
+
+    command = _command_from_spec(spec)
+    execution, error = _run_cached_execution(
+        lambda: build_use_cases(
+            store_root,
+            _spec_executable_override(spec),
+            spec["timeout"],
+            encryption_token=token,
+            stream_path=getattr(args, "stream", None),
+        ).run_managed.execute(command)
+    )
+    if error is not None:
+        return error
+
     # Materialise captured files into the cwd, exactly as the real client would.
     _apply_output_files(execution, Path.cwd())
 
     if getattr(args, "json", False):
         return _print_run_json(execution, command)
 
-    sys.stdout.write(_artifact_text(execution, ArtifactType.STDOUT))
-    sys.stdout.flush()
-    sys.stderr.write(_artifact_text(execution, ArtifactType.STDERR))
-    sys.stderr.flush()
-    return _run_exit_code(execution)
+    return _relay_execution(execution)
+
+
+def _cmd_alias(args: argparse.Namespace) -> int:
+    """`alias`: the thin native-client wrapper. Everything after the client is an
+    opaque native-argument tail, forwarded verbatim and keyed (by fingerprint) as
+    the cache identity. No isolation and no file capture -- a replay reproduces the
+    native call's stdout/stderr/exit, exactly as the default `run` does in quiet mode.
+    gmlcache's own options precede the client; the tail belongs to the native client."""
+    native_args = list(getattr(args, "native_args", None) or [])
+    # Accept an explicit `--` before the tail (`alias claude -- -p hi`) so a tail
+    # that opens with a dash never has to fight argparse; it is not a native arg.
+    if native_args and native_args[0] == "--":
+        native_args = native_args[1:]
+
+    try:
+        file_cfg = config.load()
+        settings = config.resolve_settings(
+            file_cfg, mode_flag=args.mode, persist_flag=args.persist, timeout_flag=args.timeout
+        )
+        executable = config.executable_for(file_cfg, args.client, flag=args.executable)
+    except ConfigError as exc:
+        print(f"gmlc: {exc}", file=sys.stderr)
+        return 4
+
+    command = RunPassthroughExecutionCommand(
+        client=args.client,
+        native_args=native_args,
+        cache_mode=_resolve_cache_mode(args, settings),
+        persistence_depth=PersistenceDepth(str(settings["persist"][0])),
+        record_on_error=bool(args.record_on_error),
+        session_id=_resolve_session(args),
+    )
+    store_root = Path(str(settings["store"][0]))
+    execution, error = _run_cached_execution(
+        lambda: build_use_cases(
+            store_root,
+            lambda _client: executable,
+            settings["timeout"][0],
+            encryption_token=_resolve_token(args),
+        ).run_passthrough.execute(command)
+    )
+    if error is not None:
+        return error
+    return _relay_execution(execution)
 
 
 def _submit_detached(spec: dict, store_root: Path, token: Optional[str]) -> int:
@@ -1506,6 +1575,44 @@ class _BannerParser(argparse.ArgumentParser):
         return render_banner(_use_color()) + "\n\n" + super().format_help()
 
 
+def _add_shared_run_options(parser: argparse.ArgumentParser) -> None:
+    """Add the run-resolution options shared by `run` and `alias` (mode, persistence,
+    record policy, the executable seam, encryption token, session, timeout). Both
+    commands resolve a cached call the same way, so they share this surface verbatim."""
+    parser.add_argument(
+        "--mode",
+        choices=[m.value for m in CacheMode],
+        default=None,
+        help="resolution mode (default: cache, or config/env)",
+    )
+    parser.add_argument(
+        "--persist",
+        choices=[d.value for d in PersistenceDepth],
+        default=None,
+        help=(
+            "how much to keep: meter (usage only, never replays), cache (+output, "
+            "the default), or dataset (+input) (default: cache, or config/env)"
+        ),
+    )
+    parser.add_argument("--offline", action="store_true", help="shortcut for --mode offline")
+    parser.add_argument("--force", action="store_true", help="shortcut for --mode refresh")
+    parser.add_argument(
+        "--record-on-error",
+        action="store_true",
+        help="also cache a call that fails (non-zero exit); default is to store only successes",
+    )
+    parser.add_argument("--executable", help="override the client executable (the seam)")
+    parser.add_argument(
+        "--token", help="encryption token for an encrypted store (or set GMLCACHE_TOKEN)"
+    )
+    parser.add_argument(
+        "--session", help="group this run under a session id (or set GMLCACHE_SESSION)"
+    )
+    parser.add_argument(
+        "--timeout", type=float, default=None, help="seconds before the real call is killed"
+    )
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = _BannerParser(
         prog="gmlcache",
@@ -1596,38 +1703,7 @@ def build_parser() -> argparse.ArgumentParser:
             "as the workflow engine reading usage. Files are still written to the cwd."
         ),
     )
-    run.add_argument(
-        "--mode",
-        choices=[m.value for m in CacheMode],
-        default=None,
-        help="resolution mode (default: cache, or config/env)",
-    )
-    run.add_argument(
-        "--persist",
-        choices=[d.value for d in PersistenceDepth],
-        default=None,
-        help=(
-            "how much to keep: meter (usage only, never replays), cache (+output, "
-            "the default), or dataset (+input) (default: cache, or config/env)"
-        ),
-    )
-    run.add_argument("--offline", action="store_true", help="shortcut for --mode offline")
-    run.add_argument("--force", action="store_true", help="shortcut for --mode refresh")
-    run.add_argument(
-        "--record-on-error",
-        action="store_true",
-        help="also cache a call that fails (non-zero exit); default is to store only successes",
-    )
-    run.add_argument("--executable", help="override the client executable (the seam)")
-    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"
-    )
+    _add_shared_run_options(run)
     run.add_argument(
         "-v",
         "--verbose",
@@ -1656,6 +1732,31 @@ def build_parser() -> argparse.ArgumentParser:
     )
     run.set_defaults(func=_cmd_run)
 
+    aliasp = sub.add_parser(
+        "alias",
+        help=(
+            "thin native-client wrapper: cache a raw native invocation -- everything "
+            "after the client is passed to it verbatim and is the cache identity"
+        ),
+        description=(
+            "Run a client through the cache as a thin wrapper. gmlcache's own options "
+            "(below) come BEFORE the client; everything after the client is forwarded to "
+            "it verbatim and keyed (by fingerprint) as the cache identity. No options are "
+            "modelled or auto-completed. A replay reproduces the native call's stdout, "
+            "stderr and exit; generated files are written by the live call only (no capture). "
+            "Drop-in: alias claude='gmlcache alias claude'."
+        ),
+    )
+    _add_shared_run_options(aliasp)
+    aliasp.add_argument("client", choices=registered_names(), help="the native client to wrap")
+    aliasp.add_argument(
+        "native_args",
+        nargs=argparse.REMAINDER,
+        metavar="-- NATIVE_ARGS",
+        help="the native client arguments, forwarded verbatim (this is the cache identity)",
+    )
+    aliasp.set_defaults(func=_cmd_alias)
+
     # Internal: no help= so it never appears as a help row; metavar hides it from the list.
     worker = sub.add_parser("__worker")
     worker.add_argument("store_root")

generic_ml_cache_cli-0.9.0/tests/test_alias.py

@@ -0,0 +1,118 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Alias mode (`gmlcache alias <client> -- <native args>`).
+
+The thin native-client wrapper: everything after the client is an opaque tail,
+forwarded verbatim and keyed (by fingerprint) as the cache identity. No isolation,
+no file capture -- a replay reproduces the native call's stdout/stderr/exit.
+
+The ``fake`` adapter's executable is the Python interpreter, so a native tail of
+``-c <snippet>`` runs that snippet -- a portable stand-in for a real native call.
+"""
+
+from __future__ import annotations
+
+from generic_ml_cache_core.common.errors import CacheError
+
+from generic_ml_cache_cli.cli import _run_cached_execution, main
+
+# `fake`'s executable is sys.executable (python), so these tails run python directly.
+# Write raw bytes via the stdout/stderr buffer so the output is identical on every OS
+# (text-mode Python on Windows would translate "\n" -> "\r\n"); the cache relays bytes
+# verbatim, so this is also the faithful thing to assert.
+_HELLO = ["-c", "import sys; sys.stdout.buffer.write(b'hello\\n')"]
+_BYE = ["-c", "import sys; sys.stdout.buffer.write(b'bye\\n')"]
+_FAIL = ["-c", "import sys; sys.stderr.buffer.write(b'boom\\n'); sys.exit(7)"]
+
+
+def test_alias_runs_the_native_call_and_relays_output(capsys):
+    assert main(["alias", "fake", *_HELLO]) == 0
+    assert capsys.readouterr().out == "hello\n"
+
+
+def test_alias_replays_an_identical_tail_from_cache(capsys):
+    # First call records; a non-deterministic source proves the second is a replay.
+    tail = ["-c", "import os; print(os.getpid())"]
+    assert main(["alias", "fake", *tail]) == 0
+    first = capsys.readouterr().out
+    assert main(["alias", "fake", *tail]) == 0
+    second = capsys.readouterr().out
+    assert first == second  # a fresh run would print a different pid
+
+
+def test_alias_keys_on_the_raw_tail(capsys):
+    assert main(["alias", "fake", *_HELLO]) == 0
+    assert capsys.readouterr().out == "hello\n"
+    # A different tail is a different identity -> its own call, its own output.
+    assert main(["alias", "fake", *_BYE]) == 0
+    assert capsys.readouterr().out == "bye\n"
+
+
+def test_alias_offline_miss_is_exit_3(capsys):
+    rc = main(["alias", "--offline", "fake", "-c", "print('never recorded')"])
+    assert rc == 3
+    assert "offline miss" in capsys.readouterr().err
+
+
+def test_alias_force_refreshes_a_recorded_call(capsys):
+    tail = ["-c", "import os; print(os.getpid())"]
+    assert main(["alias", "fake", *tail]) == 0
+    recorded = capsys.readouterr().out
+    assert main(["alias", "--force", "fake", *tail]) == 0
+    refreshed = capsys.readouterr().out
+    assert recorded != refreshed  # --force re-ran the native call
+
+
+def test_alias_relays_a_native_failure_verbatim(capsys):
+    # The native exit code and stderr surface exactly; nothing is rewritten.
+    assert main(["alias", "fake", *_FAIL]) == 7
+    assert capsys.readouterr().err == "boom\n"
+
+
+def test_alias_never_serves_a_recorded_failure_as_a_hit(capsys):
+    # --record-on-error keeps the failed call as history, but the cache never serves
+    # a failure as a hit -- a later offline call still misses (exit 3).
+    assert main(["alias", "--record-on-error", "fake", *_FAIL]) == 7
+    capsys.readouterr()
+    assert main(["alias", "--offline", "fake", *_FAIL]) == 3
+    assert "offline miss" in capsys.readouterr().err
+
+
+def test_alias_accepts_an_explicit_double_dash_separator(capsys):
+    # `alias fake -- <tail>` strips the separator; identity matches the bare form.
+    assert main(["alias", "fake", "--", *_HELLO]) == 0
+    assert capsys.readouterr().out == "hello\n"
+    # Same call without the separator hits the cache (offline proves it).
+    assert main(["alias", "--offline", "fake", *_HELLO]) == 0
+    assert capsys.readouterr().out == "hello\n"
+
+
+def test_alias_does_not_interpret_native_flags_as_its_own(capsys):
+    # `--offline` AFTER the client is native (here, ignored by python -c), not a
+    # gmlcache flag: the call runs and records rather than failing as an offline miss.
+    assert (
+        main(["alias", "fake", "-c", "import sys; sys.stdout.buffer.write(b'ok\\n')", "--offline"])
+        == 0
+    )
+    assert capsys.readouterr().out == "ok\n"
+
+
+def test_alias_strips_a_redundant_double_dash_from_the_tail(capsys):
+    # argparse's REMAINDER already eats the first `--`; a second literal `--` (a tail
+    # that genuinely begins with `--`) is stripped by alias itself, so it is forwarded
+    # cleanly. `python -- -c <snippet>` would fail, so a clean `ok` proves the strip.
+    rc = main(["alias", "fake", "--", "--", "-c", "import sys; sys.stdout.buffer.write(b'ok\\n')"])
+    assert rc == 0
+    assert capsys.readouterr().out == "ok\n"
+
+
+def test_run_cached_execution_maps_a_cache_error_to_exit_4(capsys):
+    # The shared ladder's catch-all: any CacheError that is not a more specific
+    # subclass becomes a clean exit 4, never an uncaught traceback.
+    def boom():
+        raise CacheError("something went wrong")
+
+    execution, code = _run_cached_execution(boom)
+    assert execution is None
+    assert code == 4
+    assert "something went wrong" in capsys.readouterr().err