gpu4agents 0.5.0__py3-none-any.whl

gpu4agents/cli/inspect.py

@@ -0,0 +1,207 @@
+"""`gpu inspect-model` - where jambu.yaml's numbers actually come from.
+
+Fetches the two public HuggingFace documents that answer "what should
+compute.gpu / runtime look like for this model" (see
+gpu4agents/core/model_inspect.py for exactly which fields), and prints a
+ready-to-paste gpu_runtime: snippet plus the reasoning behind each value.
+
+`--add-profile` closes the loop: instead of hand-writing a new full jambu.yaml
+per model (which only ever grows, never shrinks, and duplicates across every
+project directory), it writes the model-specific fragment straight into the
+shared jambu.models.yaml catalog under a name - `model_profile: <name>` in a
+project's jambu.yaml is then the only thing that ever needs to change.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+import yaml
+from rich.text import Text
+
+from rich.table import Table
+
+from ..core.config import CATALOG_FILENAMES, find_catalog, load_catalog
+from ..core.credentials import CredentialResolver
+from ..core.errors import ConfigError, JambuError
+from ..core.model_inspect import inspect_model
+from ._common import console, get_context, handle, print_json
+
+
+def inspect_model_command(
+    ctx: typer.Context,
+    repo_id: str = typer.Argument(
+        ..., help="HuggingFace repo id to inspect, e.g. Qwen/Qwen2.5-7B-Instruct."
+    ),
+    revision: str = typer.Option("main", "--revision", help="Repo revision/branch/tag."),
+    hf_token_env: str = typer.Option(
+        "HF_TOKEN", "--hf-token-env", help="Env var holding a token for gated repos."
+    ),
+    add_profile: str = typer.Option(
+        "",
+        "--add-profile",
+        help=(
+            "Write the result straight into jambu.models.yaml under this name "
+            "instead of just printing a snippet (creates the catalog if none "
+            "exists yet). Use model_profile: <name> in jambu.yaml to consume it."
+        ),
+    ),
+    catalog_path_opt: Optional[Path] = typer.Option(
+        None,
+        "--catalog",
+        help=f"Catalog file to write to with --add-profile (default: nearest {CATALOG_FILENAMES[0]}, or a new one here).",
+    ),
+    force: bool = typer.Option(
+        False, "--force", help="With --add-profile, overwrite an existing profile of that name."
+    ),
+) -> None:
+    """Inspect a HuggingFace repo and suggest jambu.yaml values for it.
+
+    Reads exactly two public documents, cited in the output:
+
+    \b
+      https://huggingface.co/api/models/<repo>            (param count, dtype)
+      https://huggingface.co/<repo>/raw/<rev>/config.json  (architecture, context)
+
+    This is a starting point, not an oracle - the VRAM figure is weights plus
+    a flat margin for KV cache/activations (which depend on context length
+    and concurrency this command has no way to know). Confirm with
+    `gpu offers` and a real health check before trusting it in production.
+    """
+    context = get_context(ctx)
+    resolver = CredentialResolver(Path.cwd())
+    token = resolver.get(hf_token_env)
+
+    try:
+        result = inspect_model(repo_id, revision=revision, token=token)
+    except JambuError as exc:
+        handle(exc)
+        return
+
+    if add_profile:
+        try:
+            target = _write_profile(result, add_profile, catalog_path_opt, force=force)
+        except JambuError as exc:
+            handle(exc)
+            return
+        if context.json:
+            print_json({**result.to_dict(), "profile_name": add_profile, "catalog_path": str(target)})
+        else:
+            console.print(Text(f"+ wrote profile '{add_profile}' to {target}", style="green"))
+            console.print(f"  use it with: model_profile: {add_profile}")
+        return
+
+    if context.json:
+        print_json(result.to_dict())
+        return
+
+    console.print(f"[bold]{result.repo_id}[/bold] @ {result.revision}")
+    console.print(
+        f"  architecture   {', '.join(result.architectures) or '?'} "
+        f"(model_type: {result.model_type or '?'})"
+    )
+    if result.total_params:
+        console.print(
+            f"  parameters     {result.total_params / 1e9:.2f}B "
+            f"({result.param_dtype or '?'}"
+            + (f", quantization: {result.quant_method}" if result.quant_method else "")
+            + ")"
+        )
+        console.print(
+            f"  weight size    ~{result.weight_gb:.1f} GB "
+            f"-> suggested min_vram_gb: {result.suggested_min_vram_gb}"
+        )
+    else:
+        console.print(Text("  parameters     unknown (no safetensors metadata)", style="yellow"))
+    console.print(f"  context        native {result.max_position_embeddings or '?'}")
+    console.print(
+        f"  tool calling   {result.suggested_tool_call_parser or '(no parser guessed)'}"
+    )
+    if result.gated:
+        console.print(Text("  gated          yes - a real HF token is required", style="yellow"))
+    if result.is_hybrid_attention:
+        console.print(
+            Text("  hybrid attention  yes - needs Ampere-or-newer GPU", style="yellow")
+        )
+
+    for note in result.notes:
+        console.print(Text(f"  ! {note}", style="yellow"))
+
+    console.print("\n[bold]Sources[/bold]")
+    console.print(f"  https://huggingface.co/api/models/{repo_id}")
+    console.print(f"  https://huggingface.co/{repo_id}/raw/{revision}/config.json")
+
+    console.print("\n[bold]Suggested gpu_runtime: snippet[/bold]")
+    console.print(result.to_yaml_snippet())
+    console.print(
+        Text(
+            f"\nTip: `gpu inspect-model {repo_id} --add-profile <name>` writes this "
+            "straight into your model catalog instead of a one-off file.",
+            style="dim",
+        )
+    )
+
+
+def profiles_command(
+    ctx: typer.Context,
+    catalog_path_opt: Optional[Path] = typer.Option(
+        None, "--catalog", help=f"Catalog to list (default: nearest {CATALOG_FILENAMES[0]})."
+    ),
+) -> None:
+    """List the model profiles available in the model catalog (jambu.models.yaml)."""
+    context = get_context(ctx)
+    target = catalog_path_opt or find_catalog(Path.cwd())
+    if target is None or not target.is_file():
+        if context.json:
+            print_json({"catalog": None, "profiles": {}})
+        else:
+            console.print(
+                Text(
+                    f"no {CATALOG_FILENAMES[0]} found in this directory or any parent. "
+                    "Create one with `gpu inspect-model <repo> --add-profile <name>`.",
+                    style="yellow",
+                )
+            )
+        return
+
+    try:
+        catalog = load_catalog(target)
+    except JambuError as exc:
+        handle(exc)
+        return
+
+    if context.json:
+        print_json({"catalog": str(target), "profiles": catalog})
+        return
+
+    table = Table(title=f"Model profiles ({target})", title_justify="left")
+    for column in ("PROFILE", "MODEL", "MIN VRAM", "TOOL CALLING"):
+        table.add_column(column)
+    for name, fragment in sorted(catalog.items()):
+        if not isinstance(fragment, dict):
+            continue
+        model_id = (fragment.get("model") or {}).get("id", "?")
+        vram = ((fragment.get("compute") or {}).get("gpu") or {}).get("min_vram_gb", "-")
+        runtime = fragment.get("runtime") or {}
+        tool_calling = runtime.get("tool_call_parser") or runtime.get("tool_calling", "-")
+        table.add_row(name, str(model_id), str(vram), str(tool_calling))
+    console.print(table)
+    console.print(Text(f"  use with: model_profile: <name> in jambu.yaml", style="dim"))
+
+
+def _write_profile(result, name: str, catalog_path_opt: Optional[Path], *, force: bool) -> Path:
+    if catalog_path_opt:
+        target = catalog_path_opt
+    else:
+        target = find_catalog(Path.cwd()) or (Path.cwd() / CATALOG_FILENAMES[0])
+
+    catalog: dict = load_catalog(target) if target.is_file() else {}
+    if name in catalog and not force:
+        raise ConfigError(
+            f"profile '{name}' already exists in {target} (use --force to overwrite)"
+        )
+    catalog[name] = result.to_profile_fragment()
+    target.write_text(yaml.safe_dump(catalog, sort_keys=False))
+    return target

gpu4agents/cli/lifecycle.py

@@ -0,0 +1,127 @@
+"""`gpu lock|unlock|stop|destroy|guard` - lifecycle control."""
+
+from __future__ import annotations
+
+import typer
+from rich.text import Text
+
+from ..core.durations import parse_duration
+from ..core.errors import ConfigError, JambuError
+from ..core.state import to_iso
+from ._common import console, get_context, handle, print_json
+
+
+def lock_command(
+    ctx: typer.Context,
+    duration: str = typer.Option(
+        "", "--for", help="Lock TTL, e.g. 2h. Omit to use lifecycle.lock.default_ttl."
+    ),
+    reason: str = typer.Option("", "--reason", help="Why the instance must stay up."),
+) -> None:
+    """Prevent automatic shutdown until the lock expires (spec section 11)."""
+    context = get_context(ctx)
+    try:
+        engine = context.engine()
+        if duration:
+            ttl = parse_duration(duration)
+        else:
+            ttl = engine.config.lock_default_ttl_s
+        result = engine.lock(ttl, reason=reason)
+    except ValueError as exc:
+        handle(ConfigError(str(exc)))
+        return
+    except JambuError as exc:
+        handle(exc)
+        return
+
+    if context.json:
+        print_json(result)
+        return
+    until = result.get("locked_until")
+    console.print(
+        Text(
+            f"+ locked until {to_iso(until)}" if until else "+ locked indefinitely",
+            style="yellow",
+        )
+    )
+
+
+def unlock_command(ctx: typer.Context) -> None:
+    """Resume normal lifecycle rules."""
+    context = get_context(ctx)
+    try:
+        result = context.engine().unlock()
+    except JambuError as exc:
+        handle(exc)
+        return
+    if context.json:
+        print_json(result)
+        return
+    console.print(Text("+ unlocked; idle and lifetime rules resume", style="green"))
+
+
+def stop_command(
+    ctx: typer.Context,
+    reason: str = typer.Option("manual", "--reason", help="Recorded with the stop event."),
+) -> None:
+    """Stop the compute resource (idempotent)."""
+    context = get_context(ctx)
+    try:
+        result = context.engine().stop(reason=reason)
+    except JambuError as exc:
+        handle(exc)
+        return
+    if context.json:
+        print_json(result)
+
+
+def destroy_command(
+    ctx: typer.Context,
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip the confirmation prompt."),
+    reason: str = typer.Option("manual", "--reason", help="Recorded with the destroy event."),
+) -> None:
+    """Destroy the remote resource (idempotent)."""
+    context = get_context(ctx)
+    try:
+        engine = context.engine()
+        if not yes and not context.json:
+            state = engine.store.load()
+            if state.instance_id:
+                confirm = typer.confirm(
+                    f"destroy instance {state.instance_id} on {engine.provider.display_name}?"
+                )
+                if not confirm:
+                    console.print("aborted")
+                    raise typer.Exit(1)
+        result = engine.destroy(reason=reason)
+    except JambuError as exc:
+        handle(exc)
+        return
+    if context.json:
+        print_json(result)
+
+
+def guard_command(
+    ctx: typer.Context,
+    dry_run: bool = typer.Option(
+        False, "--dry-run", help="Evaluate the policy without enforcing it."
+    ),
+) -> None:
+    """Evaluate the lifecycle rule now (external controller path, spec section 14).
+
+    The remote watchdog already does this on the instance. Use this from cron
+    or CI as a second, independent enforcement path.
+    """
+    context = get_context(ctx)
+    try:
+        result = context.engine().guard_tick(apply=not dry_run)
+    except JambuError as exc:
+        handle(exc)
+        return
+    if context.json:
+        print_json(result)
+        return
+    action = result.get("action")
+    reason = result.get("reason")
+    style = "yellow" if action != "none" else "green"
+    console.print(Text(f"{action}: {reason}", style=style))

gpu4agents/cli/main.py

@@ -0,0 +1,163 @@
+"""gpu entrypoint."""
+
+from __future__ import annotations
+
+import shlex
+import sys
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from ..core.errors import JambuError
+from . import account
+from . import agent as agent_cli
+from . import inspect as inspect_cli
+from . import lifecycle, providers, run, setup, status, validate
+from ._common import Context, err_console, get_context, print_json
+
+app = typer.Typer(
+    name="gpu",
+    help=(
+        "GPU for Agents: rent a GPU, serve a model, run the work; the machine stops "
+        "when nothing uses it.\n\n"
+        "jambu.yaml is the desired-state source of truth; .gpu/state.json is what "
+        "was last observed."
+    ),
+    no_args_is_help=True,
+    add_completion=False,
+    rich_markup_mode="rich",
+)
+
+
+def _print_version(value: bool) -> None:
+    if value:
+        from .. import __version__
+
+        print(__version__)
+        raise typer.Exit()
+
+
+@app.callback()
+def main_callback(
+    ctx: typer.Context,
+    config: Optional[Path] = typer.Option(
+        None, "--config", "-c", help="Path to jambu.yaml (default: nearest one upwards)."
+    ),
+    json_output: bool = typer.Option(
+        False, "--json", help="Machine-readable output on stdout."
+    ),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Verbose diagnostics."),
+    version: bool = typer.Option(
+        False, "--version", callback=_print_version, is_eager=True, help="Print the version and exit."
+    ),
+) -> None:
+    context = Context()
+    context.config_path = config
+    context.json = json_output
+    context.verbose = verbose
+    ctx.obj = context
+
+
+app.command("init")(setup.init_command)
+app.command("inspect-model")(inspect_cli.inspect_model_command)
+app.command("profiles")(inspect_cli.profiles_command)
+app.command("providers")(providers.providers_command)
+app.command("validate")(validate.validate_command)
+app.command("offers")(setup.offers_command)
+app.command("setup")(setup.setup_command)
+app.command(
+    "run",
+    context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+)(run.run_command)
+app.command("status")(status.status_command)
+app.command("logs")(status.logs_command)
+app.command("events")(status.events_command)
+app.command("lock")(lifecycle.lock_command)
+app.command("unlock")(lifecycle.unlock_command)
+app.command("stop")(lifecycle.stop_command)
+app.command("destroy")(lifecycle.destroy_command)
+app.command("guard")(lifecycle.guard_command)
+app.command("ls")(account.ls_command)
+app.command("sweep")(account.sweep_command)
+app.command("mcp")(agent_cli.mcp_command)
+app.add_typer(agent_cli.agent_app, name="agent")
+
+
+@app.command("endpoint")
+def endpoint_command(ctx: typer.Context) -> None:
+    """Print the model endpoint URL (handy for shell pipelines)."""
+    context = get_context(ctx)
+    try:
+        state = context.engine().store.load()
+    except JambuError as exc:
+        err_console.print(f"error: {exc}")
+        raise typer.Exit(getattr(exc, "exit_code", 1)) from exc
+    if not state.endpoint:
+        err_console.print("error: no endpoint; run `gpu setup` first")
+        raise typer.Exit(3)
+    print(state.endpoint)
+
+
+@app.command("env")
+def env_command(
+    ctx: typer.Context,
+    fmt: str = typer.Option(
+        "shell", "--format", "-f", help="shell (export lines), dotenv or json."
+    ),
+) -> None:
+    """Print how to reach the model (base URL, API key, model) without starting anything.
+
+    `eval "$(gpu env)"` sets OPENAI_BASE_URL, OPENAI_API_KEY and JAMBU_MODEL_ID,
+    which every OpenAI SDK reads. Exit code 3 when there is no endpoint.
+    """
+    context = get_context(ctx)
+    if fmt not in ("shell", "dotenv", "json"):
+        err_console.print("error: --format must be shell, dotenv or json")
+        raise typer.Exit(2)
+    try:
+        engine = context.engine()
+        conn = engine.connection(engine.store.load())
+    except JambuError as exc:
+        err_console.print(f"error: {exc}")
+        raise typer.Exit(getattr(exc, "exit_code", 1)) from exc
+    if context.json or fmt == "json":
+        print_json(conn)
+        if not conn["endpoint"]:
+            raise typer.Exit(3)
+        return
+    if not conn["endpoint"]:
+        err_console.print("error: no endpoint; run `gpu setup` first")
+        raise typer.Exit(3)
+    values = {
+        "OPENAI_BASE_URL": conn["base_url"],
+        "OPENAI_API_KEY": conn["api_key"],
+        "JAMBU_GPU_ENDPOINT": conn["endpoint"],
+        "JAMBU_MODEL_ID": conn["model"],
+    }
+    prefix = "export " if fmt == "shell" else ""
+    for key, value in values.items():
+        print(f"{prefix}{key}={shlex.quote(str(value))}")
+
+
+@app.command("version")
+def version_command() -> None:
+    """Print the CLI version."""
+    from .. import __version__
+
+    print(__version__)
+
+
+def main() -> None:
+    try:
+        app()
+    except JambuError as exc:  # safety net: errors are normalized, never tracebacks
+        err_console.print(f"error: {exc}")
+        sys.exit(getattr(exc, "exit_code", 1))
+    except KeyboardInterrupt:
+        err_console.print("interrupted")
+        sys.exit(130)
+
+
+if __name__ == "__main__":
+    main()

gpu4agents/cli/providers.py

@@ -0,0 +1,96 @@
+"""`gpu providers` - capability matrix (spec section 7)."""
+
+from __future__ import annotations
+
+import typer
+from rich.table import Table
+from rich.text import Text
+
+from ..core.credentials import CredentialResolver
+from ..core.errors import ConfigError
+from ..providers.registry import load_builtin_providers
+from ._common import get_context, print_json
+
+
+def providers_command(ctx: typer.Context) -> None:
+    """List available providers and what each one can do."""
+    context = get_context(ctx)
+    registry = load_builtin_providers()
+
+    try:
+        config = context.config()
+        project_dir = config.project_dir
+        profile = config.provider.profile
+        selected = config.provider.name
+    except ConfigError:
+        config = None
+        project_dir = None
+        profile = "default"
+        selected = None
+
+    resolver = CredentialResolver(project_dir, profile=profile)
+    rows = []
+    for provider_cls in registry.classes():
+        missing = [n for n in provider_cls.required_credentials if not resolver.get(n)]
+        rows.append(
+            {
+                "provider": provider_cls.name,
+                "display_name": provider_cls.display_name,
+                "selected": provider_cls.name == selected,
+                "status": "configured" if not missing else "unavailable",
+                "missing_credentials": missing,
+                "required_credentials": list(provider_cls.required_credentials),
+                "capabilities": dict(provider_cls.capabilities.__dict__),
+            }
+        )
+
+    if context.json:
+        print_json({"providers": rows})
+        return
+
+    table = Table(title="Providers", title_justify="left")
+    table.add_column("PROVIDER")
+    table.add_column("STATUS")
+    table.add_column("GPU")
+    table.add_column("STOP")
+    table.add_column("DESTROY")
+    table.add_column("SSH")
+    table.add_column("PORTS")
+    table.add_column("SPOT")
+    table.add_column("PRICING")
+    for row in rows:
+        caps = row["capabilities"]
+        name = Text(row["provider"] + (" *" if row["selected"] else ""))
+        status = Text(
+            row["status"],
+            style="green" if row["status"] == "configured" else "yellow",
+        )
+        table.add_row(
+            name,
+            status,
+            _yn(caps["gpu_selection"]),
+            _yn(caps["stop"]),
+            _yn(caps["destroy"]),
+            _yn(caps["ssh"]),
+            _yn(caps["public_ports"]),
+            _yn(caps["spot_instances"]),
+            _yn(caps["pricing_query"]),
+        )
+    from ._common import console
+
+    console.print(table)
+    for row in rows:
+        if row["missing_credentials"]:
+            console.print(
+                Text(
+                    f"  {row['provider']}: set "
+                    + ", ".join(row["missing_credentials"]),
+                    style="yellow",
+                )
+            )
+    if selected:
+        console.print(Text(f"  * selected in jambu.yaml ({selected})", style="dim"))
+
+
+def _yn(value: bool) -> str:
+    return "yes" if value else "no"

gpu4agents/cli/run.py

@@ -0,0 +1,38 @@
+"""`gpu run` - execute a workload against a guaranteed runtime (spec section 16)."""
+
+from __future__ import annotations
+
+from typing import List
+
+import typer
+
+from ..core.errors import JambuError, WorkloadFailed
+from ._common import get_context, handle, print_json, register_project
+
+
+def run_command(
+    ctx: typer.Context,
+    command: List[str] = typer.Argument(
+        ...,
+        help=(
+            "Command to execute, e.g. `python experiments/run.py`. Flags are passed "
+            "through; put `--` first if one collides with a gpu option."
+        ),
+    ),
+    label: str = typer.Option("", "--label", help="Human label recorded with the workload."),
+) -> None:
+    """Ensure the runtime is READY, then run the command with heartbeat tracking."""
+    context = get_context(ctx)
+    try:
+        engine = context.engine()
+        register_project(context)  # `run` provisions when nothing is up
+        engine.run(list(command), label=label)
+    except WorkloadFailed as exc:
+        if context.json:
+            print_json({"ok": False, "returncode": exc.returncode})
+        raise typer.Exit(exc.returncode) from exc
+    except JambuError as exc:
+        handle(exc)
+        return
+    if context.json:
+        print_json({"ok": True, "returncode": 0})