jambu-gpu 0.1.0__py3-none-any.whl

jambu_gpu/core/policy.py

@@ -0,0 +1,233 @@
+"""Lifecycle policy (spec sections 10-13, 25).
+
+This module is the SINGLE SOURCE OF TRUTH for "may this instance stay
+billable?".  It is deliberately stdlib-only and dependency-free because its
+source is inlined verbatim into the remote watchdog agent that runs on the
+rented instance (see jambu_gpu/watchdog/builder.py).  Do not import anything
+from the rest of the package here.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+# --- normalized runtime state (spec section 8) -------------------------------
+
+PROVISIONING = "provisioning"
+STARTING = "starting"
+READY = "ready"
+BUSY = "busy"
+IDLE = "idle"
+STOPPED = "stopped"
+FAILED = "failed"
+DESTROYED = "destroyed"
+UNKNOWN = "unknown"
+
+# --- actions -----------------------------------------------------------------
+
+ACTION_NONE = "none"
+ACTION_STOP = "stop"
+ACTION_DESTROY = "destroy"
+
+# --- reasons (recorded on every automatic shutdown, spec criterion 12) --------
+
+REASON_IDLE = "idle_timeout"
+REASON_MAX_LIFETIME = "max_lifetime"
+REASON_BUDGET = "budget_exceeded"
+
+
+@dataclass
+class Workload:
+    """A registered unit of useful work (spec section 12)."""
+
+    id: str
+    started_at: float
+    last_heartbeat: float
+    label: str = ""
+    state: str = "running"  # running | queued | finished | failed
+
+    def is_pending(self) -> bool:
+        return self.state in ("running", "queued")
+
+    def is_stale(self, now: float, grace: float) -> bool:
+        """Heartbeat vanished for longer than the grace period (spec section 13)."""
+        if not self.is_pending():
+            return False
+        if self.state == "queued":
+            return False
+        return (now - self.last_heartbeat) > grace
+
+
+@dataclass
+class PolicyConfig:
+    idle_timeout_s: Optional[float] = None
+    max_lifetime_s: Optional[float] = None
+    heartbeat_grace_s: float = 300.0
+    auto_stop: bool = True
+    auto_destroy: bool = False
+    allow_indefinite_lock: bool = False
+    stop_supported: bool = True
+    destroy_supported: bool = True
+    # False when a stopped instance keeps costing real money (spec section 25).
+    stop_eliminates_billing: bool = True
+    # Cost guardrails (spec section 17).
+    hourly_cost_usd: Optional[float] = None
+    max_session_cost_usd: Optional[float] = None
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "PolicyConfig":
+        known = {f for f in cls.__dataclass_fields__}  # type: ignore[attr-defined]
+        return cls(**{k: v for k, v in data.items() if k in known})
+
+    def to_dict(self) -> dict:
+        return {f: getattr(self, f) for f in self.__dataclass_fields__}  # type: ignore[attr-defined]
+
+
+@dataclass
+class Snapshot:
+    """Everything the policy needs to decide. Times are unix seconds."""
+
+    now: float
+    created_at: float
+    last_activity: float
+    workloads: list = field(default_factory=list)  # list[Workload]
+    starting: bool = False
+    locked: bool = False
+    locked_until: Optional[float] = None
+    provider_state: str = READY
+
+    # -- derived helpers ----------------------------------------------------
+
+    def lock_active(self, cfg: PolicyConfig) -> bool:
+        if not self.locked:
+            return False
+        if self.locked_until is None:
+            # An indefinite lock only holds when the project explicitly allows it.
+            return bool(cfg.allow_indefinite_lock)
+        return self.locked_until > self.now
+
+    def lock_expired(self, cfg: PolicyConfig) -> bool:
+        if not self.locked:
+            return False
+        if self.locked_until is None:
+            return not cfg.allow_indefinite_lock
+        return self.locked_until <= self.now
+
+    def pending(self, cfg: PolicyConfig) -> list:
+        """Workloads that still count as useful work."""
+        return [
+            w
+            for w in self.workloads
+            if w.is_pending() and not w.is_stale(self.now, cfg.heartbeat_grace_s)
+        ]
+
+    def stale(self, cfg: PolicyConfig) -> list:
+        return [w for w in self.workloads if w.is_stale(self.now, cfg.heartbeat_grace_s)]
+
+    def idle_seconds(self, cfg: PolicyConfig) -> float:
+        """Seconds since the last thing that counted as activity."""
+        if self.pending(cfg) or self.starting:
+            return 0.0
+        marks = [self.last_activity]
+        for w in self.workloads:
+            marks.append(w.last_heartbeat)
+        return max(0.0, self.now - max(marks))
+
+    def age_seconds(self) -> float:
+        return max(0.0, self.now - self.created_at)
+
+
+@dataclass
+class Decision:
+    action: str = ACTION_NONE
+    reason: Optional[str] = None
+    detail: dict = field(default_factory=dict)
+
+    @property
+    def terminates(self) -> bool:
+        return self.action in (ACTION_STOP, ACTION_DESTROY)
+
+    def to_dict(self) -> dict:
+        return {"action": self.action, "reason": self.reason, "detail": dict(self.detail)}
+
+
+def derive_state(snapshot: Snapshot, cfg: PolicyConfig) -> str:
+    """Normalized observed state of a live instance."""
+    if snapshot.provider_state in (STOPPED, DESTROYED, FAILED, PROVISIONING):
+        return snapshot.provider_state
+    if snapshot.starting:
+        return STARTING
+    if snapshot.pending(cfg):
+        return BUSY
+    if snapshot.provider_state == READY:
+        return IDLE if snapshot.idle_seconds(cfg) > 0 else READY
+    return snapshot.provider_state
+
+
+def _terminal_action(cfg: PolicyConfig) -> str:
+    """Pick the cheapest supported action that actually stops the bleeding."""
+    if cfg.auto_destroy:
+        return ACTION_DESTROY if cfg.destroy_supported else ACTION_NONE
+    if not cfg.auto_stop:
+        return ACTION_NONE
+    if cfg.stop_supported and cfg.stop_eliminates_billing:
+        return ACTION_STOP
+    # Stopping does not (or cannot) end billing: escalate only when allowed to.
+    if not cfg.stop_supported:
+        return ACTION_DESTROY if cfg.destroy_supported else ACTION_NONE
+    return ACTION_STOP
+
+
+def evaluate(snapshot: Snapshot, cfg: PolicyConfig) -> Decision:
+    """Core lifecycle rule (spec section 10). Pure function, no side effects."""
+    detail: dict[str, Any] = {
+        "state": derive_state(snapshot, cfg),
+        "age_seconds": round(snapshot.age_seconds(), 1),
+        "idle_seconds": round(snapshot.idle_seconds(cfg), 1),
+        "pending_workloads": len(snapshot.pending(cfg)),
+        "stale_workloads": len(snapshot.stale(cfg)),
+        "locked": snapshot.lock_active(cfg),
+    }
+
+    if snapshot.provider_state in (STOPPED, DESTROYED):
+        return Decision(ACTION_NONE, "already_terminal", detail)
+
+    locked = snapshot.lock_active(cfg)
+
+    # max_lifetime wins over everything except an active lock.
+    if cfg.max_lifetime_s is not None and snapshot.age_seconds() > cfg.max_lifetime_s:
+        if locked:
+            return Decision(ACTION_NONE, "locked", detail)
+        action = _terminal_action(cfg)
+        if action == ACTION_NONE:
+            return Decision(ACTION_NONE, "max_lifetime_no_action", detail)
+        return Decision(action, REASON_MAX_LIFETIME, detail)
+
+    # Session budget ceiling.
+    if cfg.max_session_cost_usd is not None and cfg.hourly_cost_usd:
+        spent = cfg.hourly_cost_usd * snapshot.age_seconds() / 3600.0
+        detail["session_cost_usd"] = round(spent, 4)
+        if spent > cfg.max_session_cost_usd:
+            if locked:
+                return Decision(ACTION_NONE, "locked", detail)
+            action = _terminal_action(cfg)
+            if action != ACTION_NONE:
+                return Decision(action, REASON_BUDGET, detail)
+
+    if locked:
+        return Decision(ACTION_NONE, "locked", detail)
+
+    # Useful work in flight is never interrupted (spec criterion 5).
+    if snapshot.starting:
+        return Decision(ACTION_NONE, "startup_in_progress", detail)
+    if snapshot.pending(cfg):
+        return Decision(ACTION_NONE, "workload_active", detail)
+
+    if cfg.idle_timeout_s is not None and snapshot.idle_seconds(cfg) > cfg.idle_timeout_s:
+        action = _terminal_action(cfg)
+        if action == ACTION_NONE:
+            return Decision(ACTION_NONE, "idle_no_action", detail)
+        return Decision(action, REASON_IDLE, detail)
+
+    return Decision(ACTION_NONE, "within_policy", detail)

jambu_gpu/core/state.py

@@ -0,0 +1,361 @@
+"""Observed runtime state (spec section 9).
+
+jambu.yaml is the desired-state SoT; ``.jambu/state.json`` is what we last
+observed. This module owns reading/writing it atomically, plus the on-disk
+process lock that keeps two CLI invocations from provisioning twice.
+"""
+
+from __future__ import annotations
+
+import fcntl
+import json
+import os
+import tempfile
+import time
+import uuid
+from contextlib import contextmanager
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Iterator, Optional
+
+from .errors import StateError
+from .models import Instance, InstanceState
+from .policy import Workload as PolicyWorkload
+
+STATE_VERSION = 1
+
+
+def utc_now() -> float:
+    return time.time()
+
+
+def to_iso(ts: Optional[float]) -> Optional[str]:
+    if ts is None:
+        return None
+    return datetime.fromtimestamp(ts, tz=timezone.utc).isoformat(timespec="seconds").replace(
+        "+00:00", "Z"
+    )
+
+
+def from_iso(value: Any) -> Optional[float]:
+    if value is None or value == "":
+        return None
+    if isinstance(value, (int, float)):
+        return float(value)
+    text = str(value).replace("Z", "+00:00")
+    try:
+        return datetime.fromisoformat(text).timestamp()
+    except ValueError as exc:
+        raise StateError(f"invalid timestamp in state file: {value!r}") from exc
+
+
+@dataclass
+class WorkloadRecord:
+    id: str
+    label: str = ""
+    command: list[str] = field(default_factory=list)
+    state: str = "running"  # running | queued | finished | failed
+    started_at: float = field(default_factory=utc_now)
+    last_heartbeat: float = field(default_factory=utc_now)
+    finished_at: Optional[float] = None
+    returncode: Optional[int] = None
+    pid: Optional[int] = None
+
+    def to_policy(self) -> PolicyWorkload:
+        return PolicyWorkload(
+            id=self.id,
+            started_at=self.started_at,
+            last_heartbeat=self.last_heartbeat,
+            label=self.label,
+            state=self.state,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        data = asdict(self)
+        data["started_at"] = to_iso(self.started_at)
+        data["last_heartbeat"] = to_iso(self.last_heartbeat)
+        data["finished_at"] = to_iso(self.finished_at)
+        return data
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "WorkloadRecord":
+        return cls(
+            id=data["id"],
+            label=data.get("label", ""),
+            command=list(data.get("command") or []),
+            state=data.get("state", "running"),
+            started_at=from_iso(data.get("started_at")) or utc_now(),
+            last_heartbeat=from_iso(data.get("last_heartbeat")) or utc_now(),
+            finished_at=from_iso(data.get("finished_at")),
+            returncode=data.get("returncode"),
+            pid=data.get("pid"),
+        )
+
+
+@dataclass
+class WatchdogInfo:
+    installed: bool = False
+    url: Optional[str] = None
+    token: Optional[str] = None
+    port: Optional[int] = None
+    last_contact: Optional[float] = None
+    last_error: Optional[str] = None
+
+    def to_dict(self) -> dict[str, Any]:
+        data = asdict(self)
+        data["last_contact"] = to_iso(self.last_contact)
+        return data
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "WatchdogInfo":
+        return cls(
+            installed=bool(data.get("installed")),
+            url=data.get("url"),
+            token=data.get("token"),
+            port=data.get("port"),
+            last_contact=from_iso(data.get("last_contact")),
+            last_error=data.get("last_error"),
+        )
+
+
+@dataclass
+class RuntimeState:
+    provider: str = ""
+    instance_id: Optional[str] = None
+    fingerprint: Optional[str] = None
+    state: str = InstanceState.DESTROYED.value
+    created_at: Optional[float] = None
+    last_activity: Optional[float] = None
+    locked: bool = False
+    locked_until: Optional[float] = None
+    lock_reason: str = ""
+    starting: bool = False
+    model_id: Optional[str] = None
+    endpoint: Optional[str] = None
+    hourly_cost_usd: Optional[float] = None
+    session_cost_usd: float = 0.0
+    # Billable-time bookkeeping (spec section 25): session_cost_usd must
+    # reflect actual running time, not wall-clock time since creation - a
+    # stopped instance costs nothing in compute-hours even if `status` is
+    # checked hours later. `billed_seconds` accumulates completed billable
+    # periods (e.g. before a stop); `running_since` marks an open one.
+    billed_seconds: float = 0.0
+    running_since: Optional[float] = None
+    instance: Optional[Instance] = None
+    workloads: dict[str, WorkloadRecord] = field(default_factory=dict)
+    watchdog: WatchdogInfo = field(default_factory=WatchdogInfo)
+
+    # -- helpers ------------------------------------------------------------
+
+    def has_instance(self) -> bool:
+        return bool(self.instance_id) and self.state != InstanceState.DESTROYED.value
+
+    def touch(self) -> None:
+        self.last_activity = utc_now()
+
+    def accrued_billable_seconds(self, now: Optional[float] = None) -> float:
+        """Total seconds actually spent in a billable-compute state.
+
+        Unlike ``now - created_at``, this excludes time spent stopped -
+        checking `status` long after an instance auto-stopped must not keep
+        inflating the reported cost.
+        """
+        now = now if now is not None else utc_now()
+        open_period = max(0.0, now - self.running_since) if self.running_since is not None else 0.0
+        return self.billed_seconds + open_period
+
+    def mark_billable(self, is_billable: bool, now: Optional[float] = None) -> None:
+        """Record a transition into/out of a billable-compute state.
+
+        Call this every time reconciliation observes the current state -
+        it's a no-op unless billable-ness actually changed since the last call.
+        """
+        now = now if now is not None else utc_now()
+        was_billable = self.running_since is not None
+        if is_billable and not was_billable:
+            self.running_since = now
+        elif not is_billable and was_billable:
+            self.billed_seconds += max(0.0, now - self.running_since)
+            self.running_since = None
+
+    def pending_workloads(self) -> list[WorkloadRecord]:
+        return [w for w in self.workloads.values() if w.state in ("running", "queued")]
+
+    def prune_workloads(self, keep: int = 25) -> None:
+        finished = sorted(
+            (w for w in self.workloads.values() if w.state not in ("running", "queued")),
+            key=lambda w: w.finished_at or w.started_at,
+        )
+        for record in finished[:-keep] if len(finished) > keep else []:
+            self.workloads.pop(record.id, None)
+
+    def clear_instance(self, state: str = InstanceState.DESTROYED.value) -> None:
+        # Close out any open billable period and freeze the final total into
+        # session_cost_usd (the historical record of the finished session)
+        # before resetting the counters for whatever instance comes next.
+        self.mark_billable(False)
+        if self.hourly_cost_usd:
+            self.session_cost_usd = round(self.hourly_cost_usd * self.billed_seconds / 3600.0, 4)
+        self.instance_id = None
+        self.instance = None
+        self.endpoint = None
+        self.state = state
+        self.starting = False
+        self.locked = False
+        self.locked_until = None
+        self.watchdog = WatchdogInfo()
+        self.billed_seconds = 0.0
+        self.running_since = None
+        for record in self.workloads.values():
+            if record.state in ("running", "queued"):
+                record.state = "failed"
+                record.finished_at = utc_now()
+
+    # -- serialization ------------------------------------------------------
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "version": STATE_VERSION,
+            "provider": self.provider,
+            "instance_id": self.instance_id,
+            "fingerprint": self.fingerprint,
+            "state": self.state,
+            "created_at": to_iso(self.created_at),
+            "last_activity": to_iso(self.last_activity),
+            "locked": self.locked,
+            "locked_until": to_iso(self.locked_until),
+            "lock_reason": self.lock_reason,
+            "starting": self.starting,
+            "model_id": self.model_id,
+            "endpoint": self.endpoint,
+            "hourly_cost_usd": self.hourly_cost_usd,
+            "session_cost_usd": round(self.session_cost_usd, 4),
+            "billed_seconds": round(self.billed_seconds, 1),
+            "running_since": to_iso(self.running_since),
+            "instance": self.instance.to_dict() if self.instance else None,
+            "workloads": {k: v.to_dict() for k, v in self.workloads.items()},
+            "watchdog": self.watchdog.to_dict(),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "RuntimeState":
+        instance_data = data.get("instance")
+        return cls(
+            provider=data.get("provider", ""),
+            instance_id=data.get("instance_id"),
+            fingerprint=data.get("fingerprint"),
+            state=data.get("state", InstanceState.DESTROYED.value),
+            created_at=from_iso(data.get("created_at")),
+            last_activity=from_iso(data.get("last_activity")),
+            locked=bool(data.get("locked")),
+            locked_until=from_iso(data.get("locked_until")),
+            lock_reason=data.get("lock_reason", ""),
+            starting=bool(data.get("starting")),
+            model_id=data.get("model_id"),
+            endpoint=data.get("endpoint"),
+            hourly_cost_usd=data.get("hourly_cost_usd"),
+            session_cost_usd=float(data.get("session_cost_usd") or 0.0),
+            billed_seconds=float(data.get("billed_seconds") or 0.0),
+            running_since=from_iso(data.get("running_since")),
+            instance=Instance.from_dict(instance_data) if instance_data else None,
+            workloads={
+                k: WorkloadRecord.from_dict(v) for k, v in (data.get("workloads") or {}).items()
+            },
+            watchdog=WatchdogInfo.from_dict(data.get("watchdog") or {}),
+        )
+
+
+class StateStore:
+    """Atomic reader/writer for ``.jambu/state.json``."""
+
+    def __init__(self, state_dir: Path) -> None:
+        self._depth = 0  # flock is per-open-file-description: keep it reentrant
+        self.dir = Path(state_dir)
+        self.path = self.dir / "state.json"
+        self.lock_path = self.dir / "runtime.lock"
+        self.logs_dir = self.dir / "logs"
+
+    def ensure_dirs(self) -> None:
+        self.dir.mkdir(parents=True, exist_ok=True)
+        self.logs_dir.mkdir(parents=True, exist_ok=True)
+        gitignore = self.dir / ".gitignore"
+        if not gitignore.exists():
+            gitignore.write_text("*\n")
+
+    def exists(self) -> bool:
+        return self.path.is_file()
+
+    def load(self) -> RuntimeState:
+        if not self.path.is_file():
+            return RuntimeState()
+        try:
+            data = json.loads(self.path.read_text() or "{}")
+        except json.JSONDecodeError as exc:
+            raise StateError(f"{self.path} is corrupt: {exc}") from exc
+        if not data:
+            return RuntimeState()
+        return RuntimeState.from_dict(data)
+
+    def save(self, state: RuntimeState) -> None:
+        self.ensure_dirs()
+        payload = json.dumps(state.to_dict(), indent=2, sort_keys=False) + "\n"
+        fd, tmp = tempfile.mkstemp(dir=str(self.dir), prefix=".state-", suffix=".json")
+        try:
+            with os.fdopen(fd, "w") as handle:
+                handle.write(payload)
+                handle.flush()
+                os.fsync(handle.fileno())
+            os.replace(tmp, self.path)
+        finally:
+            if os.path.exists(tmp):
+                os.unlink(tmp)
+
+    @contextmanager
+    def transaction(self, timeout: float = 30.0) -> Iterator[RuntimeState]:
+        """Exclusive read-modify-write. Guarantees `setup` cannot race itself."""
+        with self.process_lock(timeout=timeout):
+            state = self.load()
+            yield state
+            self.save(state)
+
+    @contextmanager
+    def process_lock(self, timeout: float = 30.0) -> Iterator[None]:
+        if self._depth > 0:
+            self._depth += 1
+            try:
+                yield
+            finally:
+                self._depth -= 1
+            return
+        self.ensure_dirs()
+        handle = open(self.lock_path, "a+")
+        deadline = time.time() + timeout
+        try:
+            while True:
+                try:
+                    fcntl.flock(handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+                    break
+                except BlockingIOError:
+                    if time.time() >= deadline:
+                        raise StateError(
+                            "another gpu command is holding the runtime lock "
+                            f"({self.lock_path}); retry when it finishes"
+                        ) from None
+                    time.sleep(0.2)
+            handle.seek(0)
+            handle.truncate()
+            handle.write(f"{os.getpid()} {to_iso(utc_now())}\n")
+            handle.flush()
+            self._depth = 1
+            yield
+        finally:
+            self._depth = 0
+            try:
+                fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+            finally:
+                handle.close()
+
+
+def new_workload_id() -> str:
+    return uuid.uuid4().hex[:12]

jambu_gpu/core/tool_parsers.py

@@ -0,0 +1,63 @@
+"""model.id -> vLLM ``--tool-call-parser`` heuristics.
+
+Lives in ``core`` (not ``runtime``) because both the vLLM runtime and
+``core/model_inspect.py`` need it, and ``core`` must not depend on
+``runtime`` (Provider != Runtime != Core stays a one-way dependency).
+
+Source: https://docs.vllm.ai/en/latest/features/tool_calling/ - keep this in
+sync when vLLM adds parsers; override with runtime.tool_call_parser for
+anything not recognized here (fine-tunes, quantized repos, etc.).
+"""
+
+from __future__ import annotations
+
+_TOOL_PARSER_HINTS: tuple[tuple[str, str], ...] = (
+    ("llama-4", "llama4_pythonic"),
+    ("llama4", "llama4_pythonic"),
+    ("llama-3", "llama3_json"),
+    ("llama3", "llama3_json"),
+    ("hermes", "hermes"),
+    ("qwen2.5", "hermes"),
+    ("qwen-2.5", "hermes"),
+    ("qwen3-coder", "qwen3_xml"),
+    ("qwen3_coder", "qwen3_xml"),
+    # Qwen3.5/3.6/3.8 (hybrid Gated-DeltaNet architecture, vLLM >=0.17) emit
+    # tool calls in the SAME XML function/parameter format as Qwen3-Coder, not
+    # Hermes' JSON-in-XML format - confirmed empirically on
+    # empero-ai/Qwythos-9B-v2 (Qwen3.5-based): with --tool-call-parser hermes
+    # the model's <tool_call><function=x><parameter=y>...</tool_call> output
+    # landed as inert text in `content`; switching to qwen3_xml parses it into
+    # a real `tool_calls` array. Applies to this whole "point release" Qwen3.x
+    # family, unlike the original dash-versioned Qwen3 (e.g. Qwen3-8B), which
+    # does use hermes per Qwen's own docs.
+    ("qwen3.8", "qwen3_xml"),
+    ("qwen3_8", "qwen3_xml"),
+    ("qwen3.6", "qwen3_xml"),
+    ("qwen3_6", "qwen3_xml"),
+    ("qwen3.5", "qwen3_xml"),
+    ("qwen3_5", "qwen3_xml"),
+    ("qwen3", "hermes"),  # original dash-versioned Qwen3 (e.g. Qwen3-8B): hermes
+    ("mistral", "mistral"),
+    ("mixtral", "mistral"),
+    ("granite-4", "granite4"),
+    ("granite4", "granite4"),
+    ("granite", "granite"),
+    ("internlm", "internlm"),
+    ("jamba", "jamba"),
+    ("xlam", "xlam"),
+    ("toolace", "pythonic"),
+    ("deepseek-v3.1", "deepseek_v31"),
+    ("deepseek-v3", "deepseek_v3"),
+    ("glm-4.5", "glm45"),
+    ("glm-4.7", "glm47"),
+    ("functiongemma", "functiongemma"),
+)
+
+
+def guess_tool_call_parser(model_id: str) -> "str | None":
+    """Best-effort ``--tool-call-parser`` guess from a HuggingFace repo id."""
+    lowered = model_id.lower()
+    for needle, parser in _TOOL_PARSER_HINTS:
+        if needle in lowered:
+            return parser
+    return None

jambu_gpu/providers/__init__.py

@@ -0,0 +1,4 @@
+from .base import GPUProvider, WatchdogSpec
+from .registry import ProviderRegistry, registry
+
+__all__ = ["GPUProvider", "WatchdogSpec", "ProviderRegistry", "registry"]