ruthless-efficiency 0.2.0__py3-none-any.whl

ruthless/__init__.py

@@ -0,0 +1,74 @@
+"""Ruthless Efficiency — general optimisation/search substrate.
+
+This module is the curated public API: import the supported surface from `ruthless` directly
+(`from ruthless import Candidate, RandomConfig, RandomSearchStrategy, InProcessBackend`). Deep
+submodule paths (e.g. `ruthless.strategies.random_.strategy`) are implementation detail and may move
+before `1.0`. The optuna/evolve strategies and the compute backends live behind their extras and are
+imported from their own namespaces (`ruthless.strategies.optuna_`, `ruthless.strategies.evolve_`,
+`ruthless.backends`) so that `import ruthless` stays dependency-light (core only)."""
+
+from __future__ import annotations
+
+from ruthless.backend import ComputeBackend, InProcessBackend
+from ruthless.config import (
+    Choice,
+    EvolveConfig,
+    FloatRange,
+    IntRange,
+    OptunaConfig,
+    RandomConfig,
+    RuthlessConfig,
+)
+from ruthless.errors import (
+    FatalEvaluationError,
+    OptimizationError,
+    TransientEvaluationError,
+    classify_metric,
+)
+from ruthless.guards import penalty_metrics
+from ruthless.objective import CachedObjective, Objective
+from ruthless.remote import RemoteObjective, RemoteRef
+from ruthless.report import render_json, render_summary_md
+from ruthless.result import Candidate, Evaluation, Metrics, Result
+from ruthless.strategies.random_.strategy import RandomSearchStrategy
+from ruthless.strategy import Direction, SearchStrategy
+from ruthless.testing import assert_cache_equivalence
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "CachedObjective",
+    # value types
+    "Candidate",
+    "Choice",
+    "ComputeBackend",
+    "Direction",
+    "Evaluation",
+    "EvolveConfig",
+    "FatalEvaluationError",
+    "FloatRange",
+    "InProcessBackend",
+    "IntRange",
+    "Metrics",
+    # ports
+    "Objective",
+    # errors + guards
+    "OptimizationError",
+    "OptunaConfig",
+    "RandomConfig",
+    # built-in strategy
+    "RandomSearchStrategy",
+    "RemoteObjective",
+    "RemoteRef",
+    "Result",
+    # config surface
+    "RuthlessConfig",
+    "SearchStrategy",
+    "TransientEvaluationError",
+    "assert_cache_equivalence",
+    "classify_metric",
+    "penalty_metrics",
+    # reporting + cache-equivalence harness
+    "render_json",
+    "render_summary_md",
+]

ruthless/_io.py

@@ -0,0 +1,37 @@
+"""Tiny filesystem helper shared across the core, strategies, and backends.
+
+`program_to_path` gives every caller a UNIFORM `program_path` contract — a filesystem path to a
+`.py` file holding `Candidate.program`, or `None` when there is none — so no caller ever passes raw
+source around. It lives in the pure core (stdlib-only) so both `ruthless.backends` and
+`ruthless.strategies` can reuse it without crossing the one-way dependency boundary (strategies must
+not import backends)."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+from ruthless.result import Candidate
+
+
+@contextmanager
+def program_to_path(candidate: Candidate) -> Iterator[str | None]:
+    """Yield a temp `.py` path holding `candidate.program`, or `None` if there is none.
+
+    The temp file is removed on exit (best-effort). Callers get a path-or-None they can hand to a
+    `train_and_evaluate(..., program_path=...)` entrypoint without branching on raw source."""
+    if candidate.program is None:
+        yield None
+        return
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False, encoding="utf-8") as tmp:
+        tmp.write(candidate.program)
+        path = tmp.name
+    try:
+        yield path
+    finally:
+        try:
+            os.unlink(path)
+        except OSError:
+            pass

ruthless/_logging.py

@@ -0,0 +1,10 @@
+"""Observability: namespaced loggers under "ruthless.*". The library NEVER configures root logging
+or adds handlers — consumers attach their own (spec M3)."""
+
+from __future__ import annotations
+
+import logging
+
+
+def get_logger(name: str) -> logging.Logger:
+    return logging.getLogger(f"ruthless.{name}")

ruthless/backend.py

@@ -0,0 +1,34 @@
+"""ComputeBackend port + the in-process backend. A backend is the INTER-candidate dispatch path
+(one evaluation → one compute resource). It returns the objective's metrics verbatim — it does NOT
+inspect metric values; the strategy validates its own SCORED metric (review C-C). `timeout` is part
+of the port from day one (review H-C); InProcessBackend documents-and-ignores it (only the remote
+backends in Plan 1B enforce per-candidate timeout + the transient-retry contract)."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from ruthless.objective import Objective
+from ruthless.result import Candidate, Metrics
+
+
+@runtime_checkable
+class ComputeBackend(Protocol):
+    def evaluate(self, candidate: Candidate, objective: Objective, *, timeout: float | None = None) -> Metrics: ...
+    def available(self) -> bool: ...
+
+
+class InProcessBackend:
+    """The default core backend: calls ``objective.evaluate(candidate)`` in the current process.
+
+    For pure/CPU objectives that need no remote dispatch. ``timeout`` is accepted for port
+    compatibility and ignored (there is no in-process cancellation); the remote backends in the
+    ``[backends]`` extra enforce it.
+    """
+
+    def evaluate(self, candidate: Candidate, objective: Objective, *, timeout: float | None = None) -> Metrics:
+        # timeout ignored in-process (no cross-process cancellation here); enforced by remote backends in 1B.
+        return objective.evaluate(candidate)
+
+    def available(self) -> bool:
+        return True

ruthless/backends/__init__.py

@@ -0,0 +1,67 @@
+"""Compute backends ([backends] extra) + the create_backend factory.
+
+A single backend name builds one backend; a comma-separated `type` builds one per name wrapped in a
+priority-ordered BackendPool. Concrete-backend imports are DEFERRED inside the factories so the heavy
+per-backend deps (huggingface_hub, docker, torch) load only when that backend is actually used."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ruthless.backend import ComputeBackend
+from ruthless.config import BackendConfig
+
+if TYPE_CHECKING:
+    pass
+
+__all__ = ["create_backend"]
+
+
+def _make_local_cuda(cfg: BackendConfig, timeout: int) -> ComputeBackend:
+    from ruthless.backends.local_cuda import LocalCudaBackend
+
+    return LocalCudaBackend(device=cfg.device)
+
+
+def _make_docker(cfg: BackendConfig, timeout: int) -> ComputeBackend:
+    from ruthless.backends.docker import DockerBackend
+
+    return DockerBackend(docker_image=cfg.docker_image or "")
+
+
+def _make_hf_jobs(cfg: BackendConfig, timeout: int) -> ComputeBackend:
+    from ruthless.backends.hf_jobs import HFJobsBackend
+
+    return HFJobsBackend(hf_flavor=cfg.hf_flavor or "l40sx1", timeout=timeout)
+
+
+def _make_remote_ssh(cfg: BackendConfig, timeout: int) -> ComputeBackend:
+    from ruthless.backends.remote_ssh import RemoteSSHBackend
+
+    return RemoteSSHBackend(
+        host=cfg.ssh_host or "",
+        user=cfg.ssh_user or "",
+        remote_dir=cfg.ssh_remote_dir or "",
+        python_path=cfg.ssh_python_path or "",
+        timeout=timeout,
+        device=cfg.device,
+    )
+
+
+_REGISTRY = {
+    "local_cuda": _make_local_cuda,
+    "docker": _make_docker,
+    "hf_jobs": _make_hf_jobs,
+    "remote_ssh": _make_remote_ssh,
+}
+
+
+def create_backend(config: BackendConfig, *, timeout: int = 900) -> ComputeBackend:
+    """Build a ComputeBackend (or BackendPool) from a validated BackendConfig."""
+    types = [t.strip() for t in config.type.split(",") if t.strip()]
+    backends = [_REGISTRY[t](config, timeout) for t in types]
+    if len(backends) == 1:
+        return backends[0]
+    from ruthless.backends.pool import BackendPool
+
+    return BackendPool(backends)

ruthless/backends/base.py

@@ -0,0 +1,55 @@
+"""Helpers shared by the compute backends ([backends] extra). The ComputeBackend port lives in
+ruthless.backend (1A, core); backends import it from there. These helpers replace the lakehouse
+fail_metrics() swallowing with the 1A error taxonomy (raise Fatal/Transient, never record a sentinel).
+
+`program_to_path` and the cross-wire failure-marker vocabulary live in the core (`ruthless._io`,
+`ruthless.wire`) so strategies can reuse them without importing backends; they are re-exported here
+for the backends that already import them from this module."""
+
+from __future__ import annotations
+
+import json
+
+from ruthless._io import program_to_path
+from ruthless.errors import FatalEvaluationError
+from ruthless.remote import RemoteObjective
+from ruthless.wire import is_failure_marker
+
+__all__ = ["is_objective_failure", "parse_last_json_line", "program_to_path", "require_remote"]
+
+
+def is_objective_failure(metrics: dict) -> bool:
+    """True if a parsed worker metrics dict is actually a node-side objective-failure marker (H1).
+
+    Thin alias over `ruthless.wire.is_failure_marker` (the single definition of the marker shape)."""
+    return is_failure_marker(metrics)
+
+
+def parse_last_json_line(stdout: str) -> dict[str, float]:
+    """Return the last non-empty line of `stdout` parsed as a JSON metrics dict.
+
+    Mirrors the lakehouse remote backends: the worker prints exactly one JSON line; earlier lines
+    may be stray warnings. Raises FatalEvaluationError if no JSON object line is present. Scans from
+    the end without materialising an intermediate filtered list."""
+    for raw_line in reversed(stdout.splitlines()):
+        line = raw_line.strip()
+        if line.startswith("{") and line.endswith("}"):
+            try:
+                return json.loads(line)
+            except json.JSONDecodeError:
+                continue
+    raise FatalEvaluationError(f"no JSON metrics line in worker stdout (last 200 chars): {stdout[-200:]!r}")
+
+
+def require_remote(objective: object, *, backend: str) -> RemoteObjective:
+    """Return the objective narrowed to RemoteObjective, or raise FatalEvaluationError if it is not one.
+
+    Compute backends cannot ship an arbitrary in-process Objective to a node — the objective must opt
+    in to remote execution by exposing `remote_ref` (and `epochs`/`seed`). Returning the narrowed
+    objective lets callers read `.remote_ref`/`.epochs`/`.seed` without a separate isinstance assert."""
+    if not isinstance(objective, RemoteObjective):
+        raise FatalEvaluationError(
+            f"{backend} requires a RemoteObjective (with .remote_ref/.epochs/.seed); "
+            f"got {type(objective).__name__}. Use InProcessBackend for non-remote objectives."
+        )
+    return objective

ruthless/backends/docker.py

@@ -0,0 +1,20 @@
+"""DockerBackend — not-yet-implemented stub (ported from the lakehouse stub, bridged to the 1A port).
+Under the unified error model a not-implemented backend is a fatal config error, never a silently
+recorded sentinel score."""
+
+from __future__ import annotations
+
+from ruthless.errors import FatalEvaluationError
+from ruthless.objective import Objective
+from ruthless.result import Candidate, Metrics
+
+
+class DockerBackend:
+    def __init__(self, docker_image: str = "") -> None:
+        self._docker_image = docker_image
+
+    def evaluate(self, candidate: Candidate, objective: Objective, *, timeout: float | None = None) -> Metrics:
+        raise FatalEvaluationError("DockerBackend is not implemented (Plan 1B stub); use local_cuda/remote_ssh/hf_jobs")
+
+    def available(self) -> bool:
+        return False

ruthless/backends/hf_jobs.py

@@ -0,0 +1,215 @@
+"""HFJobsBackend — runs an objective's remote entrypoint on Hugging Face Jobs.
+
+Ported from the lakehouse backend, bridged to the 1A port. Submits a PEP-723 UV worker script via
+`huggingface_hub.run_uv_job`, polls until completion, and parses the JSON metrics line from the job
+logs. The `shared.wheel` lakehouse coupling is SEVERED: the worker's install spec is the injected
+`RemoteRef.package` and the import target is `RemoteRef.entrypoint` (no `evolve.targets.<target>`).
+
+Per the unified error model it RAISES rather than recording a sentinel: timeout -> cancel +
+TransientEvaluationError; job ERROR/CANCELED/DELETED -> FatalEvaluationError; no metrics line or a
+node-side objective-failure marker -> FatalEvaluationError."""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import tempfile
+import time
+from pathlib import Path
+from typing import Any
+
+from ruthless._logging import get_logger
+from ruthless.backends.base import is_objective_failure, parse_last_json_line, require_remote
+from ruthless.errors import FatalEvaluationError, TransientEvaluationError
+from ruthless.objective import Objective
+from ruthless.remote import RemoteObjective, RemoteRef
+from ruthless.result import Candidate, Metrics
+from ruthless.wire import ERROR_TEXT_KEY, ERROR_TEXT_SURFACE_LIMIT
+
+_log = get_logger("backends.hf_jobs")
+_POLL_INTERVAL = 15  # seconds
+
+
+def _build_worker_script(ref: RemoteRef) -> str:
+    """Build the PEP-723 UV worker script, interpolating the injected install spec + entrypoint.
+
+    Replaces the lakehouse module-level f-string that baked in `shared.wheel.WHEEL_BASE_URL`. The
+    failure-marker keys emitted below (`combined_score`/`error`/`_error_text`) are the cross-wire
+    contract defined in `ruthless.wire`; they are written as literals here because this script runs as
+    a self-contained worker on a fresh node — keep them in sync with `ruthless.wire`."""
+    if ref.package is None:
+        raise FatalEvaluationError(
+            "HFJobsBackend requires RemoteRef.package (the node is fresh; it must install something)"
+        )
+    return f'''\
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#     "{ref.package}",
+# ]
+# ///
+"""HF Jobs worker — generic ruthless remote entrypoint runner."""
+
+import base64
+import importlib
+import json
+import logging
+import os
+import sys
+
+logging.basicConfig(stream=sys.stderr, level=logging.INFO, format="%(name)s %(message)s")
+_log = logging.getLogger("hf_jobs_worker")
+
+
+def main() -> None:
+    config_b64 = os.environ.get("EVOLVE_CANDIDATE_CONFIG", "")
+    if not config_b64:
+        print(json.dumps({{"combined_score": 0.0, "error": 1.0, "_error_text": "missing EVOLVE_CANDIDATE_CONFIG"}}))
+        sys.exit(0)
+
+    candidate_config = json.loads(base64.b64decode(config_b64).decode())
+    device = os.environ.get("EVOLVE_DEVICE", "cuda:0")
+    epochs = int(os.environ.get("EVOLVE_EPOCHS", "5"))
+    seed = int(os.environ.get("EVOLVE_SEED", "42"))
+    entrypoint = os.environ["EVOLVE_ENTRYPOINT"]
+
+    program_path = None
+    program_b64 = os.environ.get("EVOLVE_PROGRAM")
+    if program_b64:
+        program_path = "/tmp/ruthless_program.py"
+        with open(program_path, "w") as fh:
+            fh.write(base64.b64decode(program_b64).decode())
+
+    module_path, _, attr = entrypoint.partition(":")
+    fn = getattr(importlib.import_module(module_path), attr)
+    try:
+        metrics = fn(
+            candidate_config=candidate_config, device=device, epochs=epochs, seed=seed, program_path=program_path
+        )
+    except Exception:
+        import traceback
+        metrics = {{"combined_score": 0.0, "error": 1.0, "_error_text": traceback.format_exc()}}
+
+    print(json.dumps(metrics))
+
+
+if __name__ == "__main__":
+    main()
+'''
+
+
+class HFJobsBackend:
+    """Runs an objective's remote entrypoint on Hugging Face Jobs (the ``[backends]`` extra).
+
+    Submits a PEP-723 UV worker script via ``huggingface_hub.run_uv_job``, polls to completion, and
+    parses the JSON metrics line from the job logs. The worker installs ``RemoteRef.package`` and
+    imports ``RemoteRef.entrypoint``. Enforces ``timeout`` (cancel + ``TransientEvaluationError``);
+    a job ERROR/CANCELED/DELETED or a node-side objective-failure marker → ``FatalEvaluationError``.
+
+    Args:
+        hf_flavor: HF Jobs hardware flavor (e.g. ``"l40sx1"``).
+        timeout: Per-candidate timeout in seconds (also the job submission timeout).
+        namespace: HF namespace to run the job under (defaults to the token owner).
+    """
+
+    def __init__(self, hf_flavor: str = "l40sx1", timeout: int = 6000, namespace: str | None = None) -> None:
+        self._hf_flavor = hf_flavor
+        self._timeout = timeout
+        self._namespace = namespace
+        # The worker script depends only on ref.package, which is constant across a run's candidates;
+        # cache it so we don't re-template the multi-KB f-string on every evaluation.
+        self._worker_script_cache: dict[str | None, str] = {}
+
+    def _worker_script(self, ref: RemoteRef) -> str:
+        if ref.package not in self._worker_script_cache:
+            self._worker_script_cache[ref.package] = _build_worker_script(ref)
+        return self._worker_script_cache[ref.package]
+
+    def evaluate(self, candidate: Candidate, objective: Objective, *, timeout: float | None = None) -> Metrics:
+        obj = require_remote(objective, backend="HFJobsBackend")
+        # objective-crash markers and job failures raise (below); transport/submission errors -> Transient.
+        try:
+            return self._evaluate_impl(candidate, obj, obj.remote_ref)
+        except (FatalEvaluationError, TransientEvaluationError):
+            raise
+        except Exception as exc:  # submission / API / network -> transient
+            raise TransientEvaluationError(f"HF Jobs submission/poll error: {exc}") from exc
+
+    def _evaluate_impl(self, candidate: Candidate, objective: RemoteObjective, ref: RemoteRef) -> Metrics:
+        from huggingface_hub import HfApi
+
+        api = HfApi()
+        script = self._worker_script(ref)
+
+        env: dict[str, str] = {
+            "EVOLVE_CANDIDATE_CONFIG": base64.b64encode(json.dumps(dict(candidate.params)).encode()).decode(),
+            "EVOLVE_DEVICE": "cuda:0",
+            "EVOLVE_EPOCHS": str(objective.epochs),
+            "EVOLVE_SEED": str(objective.seed),
+            "EVOLVE_ENTRYPOINT": ref.entrypoint,
+        }
+        if candidate.program is not None:
+            env["EVOLVE_PROGRAM"] = base64.b64encode(candidate.program.encode()).decode()
+
+        # The worker script only needs to exist on disk during submission (run_uv_job reads + uploads
+        # it); the temp dir is cleaned up before polling so it does not accumulate one dir per trial.
+        with tempfile.TemporaryDirectory(prefix="ruthless_hfjob_") as tmp_dir:
+            script_file = Path(tmp_dir) / "worker.py"
+            script_file.write_text(script, encoding="utf-8")
+            job_info = api.run_uv_job(
+                script=str(script_file),
+                env=env,
+                secrets={"HF_TOKEN": self._get_hf_token()},
+                flavor=self._hf_flavor,
+                timeout=f"{self._timeout}s",
+                namespace=self._namespace,
+            )
+        _log.info("hf_job_submitted", extra={"job_id": job_info.id, "flavor": self._hf_flavor})
+        return self._poll_job(api, job_info.id)
+
+    @staticmethod
+    def _get_hf_token() -> str:
+        from huggingface_hub import get_token
+
+        return get_token() or ""
+
+    def _poll_job(self, api: Any, job_id: str) -> Metrics:
+        from huggingface_hub._jobs_api import JobStage
+
+        deadline = time.monotonic() + self._timeout
+        while time.monotonic() < deadline:
+            info = api.inspect_job(job_id=job_id, namespace=self._namespace)
+            stage = info.status.stage
+            if stage == JobStage.COMPLETED:
+                return self._parse_metrics(api, job_id, candidate_id=job_id)
+            if stage in (JobStage.ERROR, JobStage.CANCELED, JobStage.DELETED):
+                msg = info.status.message or "unknown"
+                raise FatalEvaluationError(f"HF Job {job_id} failed: stage={stage.value}, message={msg}")
+            time.sleep(_POLL_INTERVAL)
+
+        try:
+            api.cancel_job(job_id=job_id, namespace=self._namespace)
+        except Exception:  # noqa: BLE001 - best-effort cancel; the timeout is reported regardless
+            _log.warning("cancel_failed", extra={"job_id": job_id})
+        raise TransientEvaluationError(f"HF Job {job_id} timed out after {self._timeout}s")
+
+    def _parse_metrics(self, api: Any, job_id: str, *, candidate_id: str) -> Metrics:
+        logs = "\n".join(api.fetch_job_logs(job_id=job_id, namespace=self._namespace))
+        metrics = parse_last_json_line(logs)
+        if is_objective_failure(metrics):
+            detail = str(metrics.get(ERROR_TEXT_KEY, ""))[:ERROR_TEXT_SURFACE_LIMIT]
+            raise FatalEvaluationError(f"objective crashed in HF Job {job_id}: {detail}")
+        return metrics
+
+    def available(self) -> bool:
+        if not os.environ.get("HF_TOKEN"):
+            return False
+        try:
+            from huggingface_hub import HfApi
+
+            HfApi().whoami()
+            return True
+        except Exception:  # noqa: BLE001 - availability probe: any failure means "not available"
+            _log.warning("hf_unavailable")
+            return False

ruthless/backends/local_cuda.py

@@ -0,0 +1,74 @@
+"""LocalCudaBackend — runs the objective's remote entrypoint IN-PROCESS on a local CUDA device.
+Bridged to the 1A port: resolves objective.remote_ref.entrypoint (module:callable) and calls the
+standard train_and_evaluate(candidate_config, device, epochs, seed, program_path)."""
+
+from __future__ import annotations
+
+import importlib
+import threading
+
+from ruthless.backends.base import program_to_path, require_remote
+from ruthless.errors import FatalEvaluationError
+from ruthless.objective import Objective
+from ruthless.result import Candidate, Metrics
+
+
+def _resolve(entrypoint: str):
+    module_path, _, attr = entrypoint.partition(":")
+    if not attr:
+        raise FatalEvaluationError(f"remote_ref.entrypoint must be 'module:callable', got {entrypoint!r}")
+    return getattr(importlib.import_module(module_path), attr)
+
+
+class LocalCudaBackend:
+    """Runs an objective's remote entrypoint IN-PROCESS on a local CUDA device.
+
+    Resolves ``objective.remote_ref.entrypoint`` (``module:callable``) and invokes the standard
+    ``train_and_evaluate(candidate_config, device, epochs, seed, program_path)`` at ``device``.
+
+    Timeout: like :class:`~ruthless.backend.InProcessBackend`, this backend runs in-process and does
+    NOT enforce the ``timeout`` argument — there is no in-process cancellation, so it is accepted for
+    port compatibility and ignored. Only the cross-process backends (:class:`RemoteSSHBackend`,
+    :class:`HFJobsBackend`) enforce a per-candidate timeout.
+
+    Args:
+        device: CUDA device string the entrypoint runs on (e.g. ``"cuda:0"``).
+    """
+
+    def __init__(self, device: str = "cuda:0") -> None:
+        self._device = device
+        self._available_cached: bool | None = None
+        self._available_lock = threading.Lock()  # guards the lazy probe (safe on free-threaded builds)
+
+    def evaluate(self, candidate: Candidate, objective: Objective, *, timeout: float | None = None) -> Metrics:
+        # timeout is ignored in-process (no cancellation here); enforced only by the remote backends.
+        obj = require_remote(objective, backend="LocalCudaBackend")
+        fn = _resolve(obj.remote_ref.entrypoint)
+        with program_to_path(candidate) as program_path:  # uniform: temp .py path or None
+            try:
+                return fn(
+                    candidate_config=dict(candidate.params),  # consumers get a plain, mutable dict
+                    device=self._device,
+                    epochs=obj.epochs,
+                    seed=obj.seed,
+                    program_path=program_path,
+                )
+            except Exception as exc:  # H1: any objective crash -> Fatal (surfaced, never a recorded score)
+                raise FatalEvaluationError(
+                    f"objective entrypoint {obj.remote_ref.entrypoint!r} crashed on {candidate.id}: {exc}"
+                ) from exc
+
+    def available(self) -> bool:
+        # Double-checked lazy probe: keep the heavy `torch` import deferred (don't import it at
+        # construction just to memoise), but guard the one-time init so concurrent callers on a
+        # free-threaded (no-GIL) build can't race on `_available_cached`.
+        if self._available_cached is None:
+            with self._available_lock:
+                if self._available_cached is None:
+                    try:
+                        import torch  # type: ignore[import-not-found]  # consumer dependency; not a ruthless dep
+
+                        self._available_cached = bool(torch.cuda.is_available())
+                    except ImportError:
+                        self._available_cached = False
+        return self._available_cached