generic-ml-cache-core 0.2.0__py3-none-any.whl

generic_ml_cache_core/adapter/out/client/isolation.py

@@ -0,0 +1,396 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Run a client in an isolated folder and capture exactly what it produced.
+
+Isolation is correctness, not just hygiene: only by running the client in a
+folder of our own can we attribute created/modified files to *the run* rather
+than to whatever the user already had lying around. Before/after diffing in a
+shared folder would be unsound.
+
+Flow:
+    1. make a fresh temp folder
+    2. adapter.prepare(...) writes the client's input files there
+    3. snapshot the folder  <-- baseline includes step-2 files, so they are
+                                NOT mistaken for client output
+    4. launch the client (cwd = the folder)
+    5. snapshot again; diff against the baseline -> captured files
+    6. delete the folder
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import signal
+import subprocess
+import sys
+import tempfile
+import threading
+from pathlib import Path
+from typing import Callable, Dict, List, Optional
+
+from generic_ml_cache_core.application.domain.model.run.client_run_result import (
+    ClientRunResult,
+    GeneratedFile,
+)
+from generic_ml_cache_core.application.domain.model.usage.token_usage import TokenUsage
+from generic_ml_cache_core.application.port.out.base import ClientAdapter
+from generic_ml_cache_core.common.errors import CommandLineTooLong, RunInterrupted
+from generic_ml_cache_core.adapter.out.client.prime_directive import build_system_prompt
+from generic_ml_cache_core.stream import StreamWriter
+
+
+def _snapshot(root: Path) -> Dict[str, str]:
+    """Map each file's POSIX-relative path -> sha256 of its bytes."""
+    snap: Dict[str, str] = {}
+    for path in root.rglob("*"):
+        if path.is_file() and not path.is_symlink():
+            rel = path.relative_to(root).as_posix()
+            snap[rel] = hashlib.sha256(path.read_bytes()).hexdigest()
+    return snap
+
+
+def _capture_changes(root: Path, baseline: Dict[str, str]) -> List[GeneratedFile]:
+    """Return files that were created or modified, sorted by path.
+
+    Deletions are intentionally ignored (the client started in an effectively
+    empty folder, so there is nothing meaningful to delete).
+    """
+    after = _snapshot(root)
+    captured: List[GeneratedFile] = []
+    for rel in sorted(after):
+        if baseline.get(rel) != after[rel]:
+            captured.append(GeneratedFile(name=rel, content=(root / rel).read_bytes()))
+    return captured
+
+
+def _terminate_group(proc: subprocess.Popen) -> None:
+    """Tear down the client and everything it spawned. The client runs in its own
+    process group / session, so one signal to the group reaches grandchildren too --
+    no orphans left behind. Best-effort: a race where the child already exited is
+    fine (that is exactly what we wanted)."""
+    if proc.poll() is not None:
+        return
+    try:
+        if os.name == "posix":
+            os.killpg(os.getpgid(proc.pid), signal.SIGTERM)
+        else:  # Windows has no killpg; terminate the child process directly
+            proc.terminate()
+    except (ProcessLookupError, PermissionError, OSError):
+        pass
+
+
+def _command_line_limit() -> tuple[str, int, str]:
+    """The binding command-line size limit for this OS, as (scope, bytes, label).
+
+    ``scope`` is ``"arg"`` when the limit is on a single argument (Linux's
+    ``MAX_ARG_STRLEN``) or ``"total"`` when it is on the whole argument area
+    (Windows' ``CreateProcess`` cap; other POSIX ``ARG_MAX``). These are the real
+    OS limits, so a call measured at or above one would fail at launch anyway --
+    catching it here just makes the failure legible.
+    """
+    if os.name == "nt":
+        return ("total", 32_767, "the Windows command-line limit")
+    if sys.platform.startswith("linux"):
+        return ("arg", 128 * 1024, "the Linux per-argument limit (MAX_ARG_STRLEN)")
+    try:
+        arg_max = int(os.sysconf("SC_ARG_MAX"))
+    except (ValueError, OSError):
+        arg_max = 1024 * 1024
+    return ("total", arg_max, "this OS's total argument limit (ARG_MAX)")
+
+
+def _check_command_line_size(argv: List[str]) -> None:
+    """Fail legibly if the assembled command line would exceed the OS limit.
+
+    Only a client that carries the prompt in argv (cursor-agent) can approach this;
+    claude and codex put the prompt on stdin, so their command line stays small and
+    this never fires for them.
+    """
+    scope, limit, label = _command_line_limit()
+    sizes = [len(arg.encode("utf-8")) for arg in argv]
+    measured = max(sizes) if scope == "arg" else sum(sizes) + len(argv)
+    # Headroom for the executable path, separators and OS bookkeeping.
+    if measured >= limit - 4096:
+        raise CommandLineTooLong(
+            f"the launched command is ~{measured // 1024} KiB, over {label} "
+            f"(~{limit // 1024} KiB). This client takes the prompt as a command-line "
+            "argument (it has no stdin path), so a prompt this large cannot be launched "
+            "here. Declare large content as input files (--input-file) and reference "
+            "them in a short prompt, or use a tier backed by a client that reads the "
+            "prompt on stdin (claude/codex)."
+        )
+
+
+def _communicate_streaming(
+    proc: subprocess.Popen,
+    stdin_text: Optional[str],
+    timeout: float | None,
+    on_line: Callable[[str], None],
+) -> tuple[str, str]:
+    """Like ``proc.communicate()``, but hand each stdout line to ``on_line`` as it
+    arrives so a live consumer sees progress in real time.
+
+    Stdin is fed and stderr drained on worker threads to avoid the classic pipe
+    deadlock, and stdout is read line by line on a third thread. This is the
+    portable approach -- it uses threads, not ``select``/``poll`` on file
+    descriptors (POSIX-only) -- so it behaves the same on Linux, macOS and Windows.
+    Raises ``subprocess.TimeoutExpired`` on timeout, matching ``communicate()`` so
+    the caller's teardown path is unchanged.
+    """
+    out_lines: List[str] = []
+    err_chunks: List[str] = []
+
+    def _feed_stdin() -> None:
+        if stdin_text is not None and proc.stdin is not None:
+            try:
+                proc.stdin.write(stdin_text)
+            except (OSError, ValueError):
+                pass
+        if proc.stdin is not None:
+            try:
+                proc.stdin.close()
+            except (OSError, ValueError):
+                pass
+
+    def _read_stderr() -> None:
+        if proc.stderr is None:
+            return
+        try:
+            for chunk in proc.stderr:
+                err_chunks.append(chunk)
+        except (OSError, ValueError):
+            pass
+
+    def _read_stdout() -> None:
+        if proc.stdout is None:
+            return
+        try:
+            for line in proc.stdout:
+                out_lines.append(line)
+                try:
+                    on_line(line)
+                except Exception:
+                    pass  # the live view must never break the run
+        except (OSError, ValueError):
+            pass
+
+    workers = [
+        threading.Thread(target=_feed_stdin, daemon=True),
+        threading.Thread(target=_read_stderr, daemon=True),
+        threading.Thread(target=_read_stdout, daemon=True),
+    ]
+    for w in workers:
+        w.start()
+    proc.wait(timeout=timeout)  # raises TimeoutExpired -> caller tears down
+    for w in workers:
+        w.join(timeout=5)
+    return "".join(out_lines), "".join(err_chunks)
+
+
+def _run_client(
+    argv: List[str],
+    cwd: Path,
+    stdin_payload: Optional[str],
+    timeout: float | None,
+    env: Optional[dict] = None,
+    on_line: Optional[Callable[[str], None]] = None,
+) -> tuple[str, str, int]:
+    """Launch the client in its own process group and wait, while honoring a stop
+    signal from the caller (the workflow engine, DESIGN cross-app clean stop).
+
+    On SIGTERM/SIGINT the whole group is torn down and ``RunInterrupted`` is raised,
+    so the caller records no execution (an interrupted call is not a result). A
+    timeout keeps the prior contract: kill the group and re-raise ``TimeoutExpired``.
+
+    Signal handlers can only be installed on the main thread; off it (a host that
+    embeds the cache on a worker thread) we still run and still tear down on timeout
+    -- we simply cannot catch a process signal there, which is the host's to manage.
+    """
+    group_kwargs: dict = (
+        {"start_new_session": True}
+        if os.name == "posix"
+        else {"creationflags": subprocess.CREATE_NEW_PROCESS_GROUP}
+    )
+    use_stdin = stdin_payload is not None
+    proc = subprocess.Popen(
+        argv,
+        cwd=str(cwd),
+        stdin=subprocess.PIPE if use_stdin else None,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        env=env,
+        **group_kwargs,
+    )
+
+    stopped: dict[str, int | None] = {"signum": None}
+    previous: dict[int, object] = {}
+    installed: List[int] = []
+
+    def _on_stop(signum, _frame):
+        # Killing the child makes communicate() return on its own; we record the
+        # signal and raise *after* it returns, never from inside the handler.
+        stopped["signum"] = signum
+        _terminate_group(proc)
+
+    if threading.current_thread() is threading.main_thread():
+        for sig in (signal.SIGINT, signal.SIGTERM):
+            try:
+                previous[sig] = signal.signal(sig, _on_stop)
+                installed.append(sig)
+            except (ValueError, OSError, RuntimeError):
+                pass  # not settable on this platform/context; carry on without it
+
+    try:
+        if on_line is None:
+            out, err = proc.communicate(input=stdin_payload if use_stdin else None, timeout=timeout)
+        else:
+            out, err = _communicate_streaming(
+                proc, stdin_payload if use_stdin else None, timeout, on_line
+            )
+    except subprocess.TimeoutExpired:
+        _terminate_group(proc)
+        if on_line is None:
+            proc.communicate()  # reap the killed child so no zombie lingers
+        else:
+            # the reader threads hit EOF on the kill; reap without re-reading pipes
+            try:
+                proc.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                pass
+        raise
+    finally:
+        for sig in installed:
+            signal.signal(sig, previous[sig])
+
+    if stopped["signum"] is not None:
+        raise RunInterrupted(
+            f"client run was stopped (signal {stopped['signum']}) before it completed"
+        )
+    return out or "", err or "", proc.returncode
+
+
+def record_real_call(
+    adapter: ClientAdapter,
+    executable: str,
+    model: str,
+    effort: str,
+    context: str,
+    prompt: str,
+    user_system_prompt: str | None = None,
+    timeout: float | None = None,
+    allowed_read_paths: Optional[List[str]] = None,
+    add_dir_paths: Optional[List[str]] = None,
+    client_args: Optional[List[str]] = None,
+    grants: Optional[List[str]] = None,
+    stream_path: Optional[str] = None,
+) -> ClientRunResult:
+    """Execute the client once in isolation and capture its full result.
+
+    The prime directive is injected here (record time) and is deliberately NOT
+    returned as part of the cached input -- it is operational scaffolding. When
+    ``allowed_read_paths`` is given (declared input files and/or allow-path
+    folders), the directive is widened to let the client read those paths. When
+    ``add_dir_paths`` is given, the adapter may *additionally* open a hard
+    per-client read door for those folders (e.g. Claude's ``--add-dir``).
+    """
+    system_prompt = build_system_prompt(user_system_prompt, allowed_read_paths)
+
+    # Opt-in live progress: an NDJSON event file the cache writes as the call runs.
+    # Display-only -- it never changes what is recorded (see stream.py).
+    writer = StreamWriter(Path(stream_path)) if stream_path else None
+    on_line: Optional[Callable[[str], None]] = None
+    if writer is not None:
+        writer.event(
+            "run.start",
+            client=adapter.name,
+            model=model,
+            effort=effort or None,
+            grants=",".join(sorted(set(grants or []))) or None,
+        )
+
+        def _emit(line: str) -> None:
+            event = adapter.stream_event(line)
+            if event:
+                writer.event(event.pop("kind"), **event)
+
+        on_line = _emit
+
+    try:
+        with (
+            tempfile.TemporaryDirectory(prefix="gmlc-run-") as tmp,
+            tempfile.TemporaryDirectory(prefix="gmlc-home-") as home_tmp,
+        ):
+            run_dir = Path(tmp)
+            # The config home is a SEPARATE folder from run_dir, so the settings
+            # file and any seeded credentials are never snapshotted into the
+            # stored record and are deleted with the run. Capabilities are enabled by the
+            # file written here, not by argv flags (v0.0.16; see docs/reference/grants.md).
+            config_home = Path(home_tmp)
+            adapter.prepare(run_dir, context, prompt, system_prompt)
+            baseline = _snapshot(run_dir)
+
+            argv = adapter.build_argv(
+                executable,
+                run_dir,
+                model,
+                effort,
+                context,
+                prompt,
+                system_prompt,
+                client_args or [],
+                grants or [],
+            )
+            argv += adapter.read_access_argv(add_dir_paths or [])
+            # Forced operational flags a client requires for a grant its file cannot
+            # express (Cursor's --force for external network egress).
+            argv += adapter.grant_argv(grants or [])
+            # Render the client's config file into the redirected home and collect
+            # the env (CODEX_HOME/CLAUDE_CONFIG_DIR/CURSOR_CONFIG_DIR) the run needs.
+            grant_env = adapter.grant_setup(run_dir, config_home, grants or [])
+            run_env = {**os.environ, **grant_env} if grant_env else None
+            stdin_payload = adapter.stdin_payload(context, prompt, system_prompt)
+
+            # Fail legibly before the OS rejects an oversize command line (only a
+            # client that carries the prompt in argv -- cursor -- can hit this).
+            _check_command_line_size(argv)
+
+            # A stop signal here raises RunInterrupted, unwinding before any capture
+            # or record write -- an interrupted call leaves no half-written record.
+            stdout, stderr, returncode = _run_client(
+                argv, run_dir, stdin_payload, timeout, run_env, on_line
+            )
+
+            files = _capture_changes(run_dir, baseline)
+
+        # The client ran in its structured (JSON) output mode, so raw stdout carries
+        # the answer *and* the usage. The adapter lifts the clean answer back out
+        # (what the caller sees on stdout) and reads the normalized usage from the
+        # same output. parse_output degrades on its own if the output is unexpected.
+        parsed = adapter.parse_output(stdout)
+
+        if writer is not None:
+            writer.event(
+                "run.end",
+                exit=returncode,
+                files=len(files),
+                input_tokens=parsed.usage.input_tokens if parsed.usage else None,
+                output_tokens=parsed.usage.output_tokens if parsed.usage else None,
+            )
+
+        # Translate the adapter's parsed usage (its own type) into the core
+        # TokenUsage at this boundary; the dict shape is identical.
+        token_usage = (
+            TokenUsage.from_dict(parsed.usage.to_dict()) if parsed.usage is not None else None
+        )
+        return ClientRunResult(
+            exit_code=returncode,
+            stdout=parsed.text,
+            stderr=stderr,
+            files=files,
+            token_usage=token_usage,
+        )
+    finally:
+        if writer is not None:
+            writer.close()

generic_ml_cache_core/adapter/out/client/local_client_runner.py

@@ -0,0 +1,54 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""LocalClientRunner: the ClientRunnerPort over the isolated client machinery."""
+
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+from generic_ml_cache_core.adapter.out.client.isolation import record_real_call
+from generic_ml_cache_core.adapter.out.client.registry import get_adapter
+from generic_ml_cache_core.application.domain.model.run.client_run_request import ClientRunRequest
+from generic_ml_cache_core.application.domain.model.run.client_run_result import ClientRunResult
+from generic_ml_cache_core.application.port.out.client_runner_port import ClientRunnerPort
+
+
+class LocalClientRunner(ClientRunnerPort):
+    """Runs a managed local client in isolation and returns its raw result.
+
+    Wraps the isolation machinery (``record_real_call``): it resolves the client
+    adapter and executable, opens the read-door for the declared input files and
+    allow-path folders, launches the client, and returns the captured
+    ``ClientRunResult``. The executable override (per client) and the timeout are
+    injected from the composition root's config.
+    """
+
+    def __init__(
+        self,
+        executable_override: Optional[Callable[[str], Optional[str]]] = None,
+        timeout: Optional[float] = None,
+    ) -> None:
+        self._executable_override = executable_override or (lambda _client: None)
+        self._timeout = timeout
+
+    def run(self, client_run_request: ClientRunRequest) -> ClientRunResult:
+        adapter = get_adapter(client_run_request.client)
+        executable = adapter.resolve_executable(
+            self._executable_override(client_run_request.client)
+        )
+        return record_real_call(
+            adapter=adapter,
+            executable=executable,
+            model=client_run_request.model,
+            effort=client_run_request.effort,
+            context=client_run_request.context,
+            prompt=client_run_request.prompt,
+            user_system_prompt=client_run_request.user_system_prompt,
+            timeout=self._timeout,
+            allowed_read_paths=sorted(
+                [*client_run_request.input_file_paths, *client_run_request.allow_paths]
+            ),
+            add_dir_paths=sorted(client_run_request.allow_paths),
+            client_args=list(client_run_request.client_args),
+            grants=list(client_run_request.grants),
+        )

generic_ml_cache_core/adapter/out/client/passthrough_client_runner.py

@@ -0,0 +1,47 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""PassthroughClientRunner: the PassthroughRunnerPort over a direct launch."""
+
+from __future__ import annotations
+
+import subprocess
+from typing import Callable, List, Optional
+
+from generic_ml_cache_core.adapter.out.client.registry import get_adapter
+from generic_ml_cache_core.application.domain.model.run.client_run_result import ClientRunResult
+from generic_ml_cache_core.application.port.out.passthrough_runner_port import PassthroughRunnerPort
+
+_TEXT_ENCODING = "utf-8"
+
+
+class PassthroughClientRunner(PassthroughRunnerPort):
+    """Runs a client with its opaque native args, in the caller's own folder.
+
+    No isolation, no file capture: it resolves the client executable, forwards the
+    native arguments verbatim, and captures stdout/stderr/exit. Output bytes are
+    decoded leniently so unusual client output never crashes the run. The
+    executable override and timeout are injected from the composition root.
+    """
+
+    def __init__(
+        self,
+        executable_override: Optional[Callable[[str], Optional[str]]] = None,
+        timeout: Optional[float] = None,
+    ) -> None:
+        self._executable_override = executable_override or (lambda _client: None)
+        self._timeout = timeout
+
+    def run(self, client: str, native_args: List[str]) -> ClientRunResult:
+        adapter = get_adapter(client)
+        executable = adapter.resolve_executable(self._executable_override(client))
+        completed = subprocess.run(
+            [executable, *native_args],
+            capture_output=True,
+            timeout=self._timeout,
+            check=False,
+        )
+        return ClientRunResult(
+            exit_code=completed.returncode,
+            stdout=completed.stdout.decode(_TEXT_ENCODING, errors="replace"),
+            stderr=completed.stderr.decode(_TEXT_ENCODING, errors="replace"),
+        )

generic_ml_cache_core/adapter/out/client/prime_directive.py

@@ -0,0 +1,53 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The prime directive: a system prompt injected at *record* time only.
+
+This text is handed to the client when a real call is recorded. It is the soft
+half of the isolation guarantee (the hard half is: the client always runs inside
+the cache's own throwaway folder). It is NEVER written into the stored record, because
+it is not part of the cached input -- it is operational scaffolding.
+"""
+
+from __future__ import annotations
+
+PRIME_DIRECTIVE = (
+    "PRIME DIRECTIVE (operational sandbox):\n"
+    "You are running inside an isolated working folder created solely for this "
+    "task. You may read and write ONLY within the current working directory and "
+    "its subfolders. You must not read from, write to, or otherwise touch any "
+    "path outside this folder (no absolute paths to the user's home, no parent "
+    "directories, no system locations).\n"
+    "If the context or prompt asks you to touch anything outside this folder, do "
+    "NOT attempt it and do NOT wait or ask for permission: print a one-line "
+    "explanation to stderr and exit immediately with a non-zero status.\n"
+    "All inputs you need have been provided to you. Produce your outputs as files "
+    "in this folder and/or on stdout."
+)
+
+
+def build_system_prompt(
+    user_system_prompt: str | None = None,
+    allowed_read_paths: list[str] | None = None,
+) -> str:
+    """Compose the directive with an optional caller-supplied system prompt.
+
+    The directive always comes first so it cannot be overridden by trailing text.
+    When ``allowed_read_paths`` is given (declared input files and/or allow-path
+    folders), the directive is widened to permit reading exactly those paths --
+    nothing else outside the folder, and never writing to them. Like the rest of
+    the directive, this is record-time scaffolding and is never stored in the
+    stored record.
+    """
+    directive = PRIME_DIRECTIVE
+    if allowed_read_paths:
+        listed = "\n".join(f"  - {p}" for p in allowed_read_paths)
+        directive = (
+            f"{directive}\n"
+            "DECLARED READ PATHS: you MAY additionally READ the following specific "
+            "files and folders even though they sit outside this folder. You may "
+            "NOT write to them, and you may NOT read anything else outside the "
+            "folder:\n" + listed
+        )
+    if user_system_prompt:
+        return f"{directive}\n\n---\n\n{user_system_prompt}"
+    return directive

generic_ml_cache_core/adapter/out/client/registry.py

@@ -0,0 +1,34 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Registry mapping client names to adapters.
+
+Built-in adapters self-register on import. Third parties (and the test-suite)
+can register their own adapters via :func:`register` -- that is how a fake
+client is plugged in without shipping it in the package.
+"""
+
+from __future__ import annotations
+
+from typing import Dict
+
+from generic_ml_cache_core.application.port.out.base import ClientAdapter
+from generic_ml_cache_core.common.errors import UnknownClient
+
+_REGISTRY: Dict[str, ClientAdapter] = {}
+
+
+def register(adapter: ClientAdapter) -> ClientAdapter:
+    _REGISTRY[adapter.name] = adapter
+    return adapter
+
+
+def get_adapter(name: str) -> ClientAdapter:
+    try:
+        return _REGISTRY[name]
+    except KeyError:
+        known = ", ".join(sorted(_REGISTRY)) or "(none)"
+        raise UnknownClient(f"unknown client {name!r}; registered: {known}")
+
+
+def registered_names() -> list[str]:
+    return sorted(_REGISTRY)

generic_ml_cache_core/adapter/out/clock/__init__.py

@@ -0,0 +1 @@
+"""Hexagonal layer package."""

generic_ml_cache_core/adapter/out/clock/system_clock.py

@@ -0,0 +1,16 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""SystemClock: the real wall-clock implementation of ClockPort."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from generic_ml_cache_core.application.port.out.clock_port import ClockPort
+
+
+class SystemClock(ClockPort):
+    """Reads the operating system clock, in UTC."""
+
+    def now(self) -> datetime:
+        return datetime.now(timezone.utc)

generic_ml_cache_core/adapter/out/fingerprint/__init__.py

@@ -0,0 +1 @@
+"""Hexagonal layer package."""

generic_ml_cache_core/adapter/out/fingerprint/filesystem_file_fingerprint.py

@@ -0,0 +1,30 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""FilesystemFileFingerprint: read a file and fingerprint it at the edge."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from generic_ml_cache_core.application.port.out.file_fingerprint_port import FileFingerprintPort
+from generic_ml_cache_core.common.checksum import file_content_fingerprint
+from generic_ml_cache_core.common.errors import InputFileError
+
+
+class FilesystemFileFingerprint(FileFingerprintPort):
+    """Fingerprint a declared input file off the local filesystem.
+
+    Reads the bytes and applies the imported core rule, returning only the
+    checksum. The content stays inside this adapter — it never crosses back to
+    the use case. The rule is imported from the core, never reimplemented here.
+    """
+
+    def fingerprint(self, path: str) -> str:
+        file_path = Path(path)
+        if not file_path.is_file():
+            raise InputFileError(f"input file not found: {path}")
+        try:
+            content = file_path.read_bytes()
+        except OSError as error:
+            raise InputFileError(f"cannot read input file {path}: {error}") from error
+        return file_content_fingerprint(content)

generic_ml_cache_core/adapter/out/metrics/__init__.py

@@ -0,0 +1 @@
+"""Hexagonal layer package."""