hud-python 0.6.0__tar.gz → 0.6.2__tar.gz

{hud_python-0.6.0 → hud_python-0.6.2}/.gitignore

@@ -7,6 +7,10 @@ __pycache__
 .pytest_cache
 dist/
 build/
+# The broad build/ rule above also matches docs/v6/build/, which is real docs
+# content (linked from docs.json). Keep tracking it so docs.hud.ai/v6/build/*
+# does not 404.
+!docs/v6/build/
 *.egg-info/
 uv.lock
 

{hud_python-0.6.0 → hud_python-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hud-python
-Version: 0.6.0
+Version: 0.6.2
 Summary: SDK for the HUD platform.
 Project-URL: Homepage, https://github.com/hud-evals/hud-python
 Project-URL: Bug Tracker, https://github.com/hud-evals/hud-python/issues

{hud_python-0.6.0 → hud_python-0.6.2}/cookbooks/rl-training/README.md

@@ -18,22 +18,30 @@ each `optim_step` closes the on-policy loop.
 
 ## Run
 
-Needs `HUD_API_KEY` and `HUD_MODEL` (a trainable gateway model).
+Needs `HUD_API_KEY` (from your environment or `.env`). List the gateway models
+on your account, pick a trainable one (the **Trainable** column marks them), and
+set it as the `MODEL` constant at the top of `simple_train.py` /
+`ppo_custom_loss.py`:
+
+```bash
+hud models list          # Name | Model (API) | ID | Provider | Agent | Trainable
+```
 
 **Train on a deployed taskset (the real flow).** You've built a taskset and
-pushed it (`hud deploy` + `hud sync`); now train on it. Point `HUD_TASKSET` at it
-and rollouts run on **remote HUD boxes** — nothing local:
+pushed it (`hud deploy` + `hud sync`); now train on it. Set the `TASKSET`
+constant in `common.py` to its name/id and rollouts run on **remote HUD
+boxes** — nothing local:
 
 ```bash
-HUD_MODEL=<trainable-model> HUD_TASKSET=<taskset-name-or-id> uv run simple_train.py --steps 10
-HUD_MODEL=<trainable-model> HUD_TASKSET=<taskset-name-or-id> uv run ppo_custom_loss.py --steps 10
+uv run simple_train.py --steps 10
+uv run ppo_custom_loss.py --steps 10
 ```
 
-**Quickstart (self-contained).** Leave `HUD_TASKSET` unset and a tiny local
+**Quickstart (self-contained).** Leave `TASKSET` empty and a tiny local
 arithmetic taskset runs against the bundled `env.py`:
 
 ```bash
-HUD_MODEL=<trainable-model> uv run simple_train.py --steps 10
+uv run simple_train.py --steps 10
 ```
 
 The swap is `common.py`'s `load_taskset_and_runtime()` — `Taskset.from_api(name)`

hud_python-0.6.2/hud/cli/init.py

@@ -0,0 +1,147 @@
+"""``hud init``: scaffold a new HUD environment package.
+
+By default (or in a non-interactive shell) it writes a minimal local scaffold —
+no network, no API key. With ``--preset`` (or via the interactive picker) it
+downloads one of the starter environments from GitHub instead — the same set the
+platform's *environments/new* flow offers. See :mod:`hud.cli.presets`.
+"""
+
+from __future__ import annotations
+
+import shutil
+import sys
+import tarfile
+from pathlib import Path
+from typing import Any
+
+import httpx
+import typer
+
+from hud.utils.hud_console import HUDConsole
+
+from .presets import ENVIRONMENT_PRESETS, PRESETS_BY_ID, EnvironmentPreset, materialize_preset
+from .templates import DOCKERFILE_HUD, ENV_PY, PYPROJECT_TOML, TASKS_PY
+
+_LOCAL_SCAFFOLD = "__local__"
+
+
+def _python_name(name: str) -> str:
+    """Normalize a package name into a Python-identifier-ish env name."""
+    name = name.replace("-", "_").replace(" ", "_")
+    return "".join(c if c.isalnum() or c == "_" else "_" for c in name)
+
+
+def _resolve_preset(preset: str | None, hud_console: HUDConsole) -> EnvironmentPreset | None:
+    """Pick the starter: an explicit ``--preset`` id, an interactive choice, or
+    ``None`` for the minimal local scaffold."""
+    if preset is not None:
+        chosen = PRESETS_BY_ID.get(preset)
+        if chosen is None:
+            available = ", ".join(PRESETS_BY_ID)
+            hud_console.error(f"Unknown preset {preset!r}. Available: {available}")
+            raise typer.Exit(1)
+        return chosen
+
+    # No flag: pick interactively when we have a TTY, else the local scaffold.
+    if not (sys.stdin.isatty() and sys.stdout.isatty()):
+        return None
+
+    choices: list[str | dict[str, Any]] = [
+        {"name": "Minimal (local scaffold, no download)", "value": _LOCAL_SCAFFOLD},
+        *({"name": f"{p.name} — {p.description}", "value": p.id} for p in ENVIRONMENT_PRESETS),
+    ]
+    selected = hud_console.select("Choose a starter", choices, default=0)
+    return None if selected == _LOCAL_SCAFFOLD else PRESETS_BY_ID[selected]
+
+
+def _write_local_scaffold(target: Path, env_name: str, hud_console: HUDConsole) -> None:
+    """Write the bundled minimal env package into ``target``."""
+    files = {
+        "pyproject.toml": PYPROJECT_TOML.format(name=env_name.replace("_", "-")),
+        "env.py": ENV_PY.format(env_name=env_name),
+        "tasks.py": TASKS_PY.format(env_name=env_name),
+        "Dockerfile.hud": DOCKERFILE_HUD,
+    }
+    target.mkdir(parents=True, exist_ok=True)
+    for filename, content in files.items():
+        (target / filename).write_text(content)
+        hud_console.status_item(filename, "✓")
+
+
+def init_command(
+    name: str = typer.Argument(..., help="Environment name (directory to create)"),
+    directory: str = typer.Option(".", "--dir", "-d", help="Parent directory"),
+    force: bool = typer.Option(False, "--force", "-f", help="Overwrite existing files"),
+    preset: str | None = typer.Option(
+        None,
+        "--preset",
+        "-p",
+        help="Starter preset to download from GitHub (e.g. blank, coding, browser, "
+        "deepresearch, rubrics, remote-browser). Omit for an interactive picker; in a "
+        "non-interactive shell, omitting it writes the minimal local scaffold.",
+    ),
+) -> None:
+    """🚀 Create a new HUD environment package.
+
+    [not dim]With no --preset, writes a minimal local scaffold (env.py, tasks.py,
+    Dockerfile.hud, pyproject.toml) — or, in a TTY, lets you pick a starter. With
+    --preset, downloads that starter from GitHub.
+
+    Examples:
+        hud init my-env                  # interactive picker (or local scaffold)
+        hud init my-env --preset coding  # download the coding starter
+        hud init my-env --dir envs       # create ./envs/my-env[/not dim]
+    """
+    hud_console = HUDConsole()
+
+    target = Path(directory) / name
+    if target.exists() and any(target.iterdir()) and not force:
+        hud_console.error(f"{target} already exists and is not empty (use --force)")
+        raise typer.Exit(1)
+
+    chosen = _resolve_preset(preset, hud_console)
+
+    hud_console.header(f"HUD Init: {name}")
+    if chosen is not None:
+        hud_console.info(f"Downloading {chosen.owner}/{chosen.repo} …")
+        created = not target.exists()
+        try:
+            materialize_preset(chosen, target)
+        except (httpx.HTTPError, tarfile.TarError, ValueError, OSError) as exc:
+            # Don't leave a half-written tree behind — it would trip the
+            # non-empty-directory guard on the next run. Only remove a directory
+            # this run created (never a dir the user already had).
+            if created and target.exists():
+                shutil.rmtree(target, ignore_errors=True)
+            hud_console.error(f"Failed to fetch preset {chosen.id!r}: {exc}")
+            raise typer.Exit(1) from exc
+        hud_console.status_item(f"{chosen.owner}/{chosen.repo}", "✓")
+    else:
+        _write_local_scaffold(target, _python_name(name), hud_console)
+
+    hud_console.section_title("Next Steps")
+    hud_console.info("")
+    hud_console.command_example(f"cd {target}", "1. Enter the package")
+    hud_console.info("")
+    if chosen is not None:
+        hud_console.info("2. Read the README for this starter's setup + tasks.")
+        hud_console.info("")
+        hud_console.command_example("hud eval tasks.py claude", "3. Run an agent over the tasks")
+        hud_console.info("")
+        hud_console.info("4. Deploy for scale")
+        hud_console.info("   hud deploy, then run many evals in parallel.")
+    else:
+        hud_console.info("2. Define task definitions in env.py")
+        hud_console.info("   A @env.template is an async generator: it yields a prompt, then")
+        hud_console.info("   (after the agent answers) yields a reward.")
+        hud_console.info("")
+        hud_console.info("3. List the tasks to run in tasks.py")
+        hud_console.info("   Call a task with args to bind a runnable Task.")
+        hud_console.info("")
+        hud_console.command_example("hud eval tasks.py claude", "4. Run an agent over them")
+        hud_console.info("")
+        hud_console.info("5. Deploy for scale")
+        hud_console.info("   hud deploy, then run many evals in parallel.")
+    hud_console.info("")
+    hud_console.info("Tip: Install the HUD skill so your coding agent can help you build:")
+    hud_console.command_example("npx skills add docs.hud.ai", "Install HUD skill")

{hud_python-0.6.0 → hud_python-0.6.2}/hud/cli/models.py

@@ -56,14 +56,18 @@ def list_models(
     table = Table()
     table.add_column("Name", style="cyan")
     table.add_column("Model (API)", style="green")
+    table.add_column("ID", style="blue", no_wrap=True)
     table.add_column("Provider", style="yellow")
     table.add_column("Agent", style="magenta")
+    table.add_column("Trainable", style="green", justify="center")
     for model in models_list:
         table.add_row(
             model.name or model.id or "-",
             model.model_name or model.id or "-",
+            model.id or "-",
             model.provider.name or "-",
             model.sdk_agent_type or "-",
+            "✓" if model.is_trainable else "",
         )
     console.print(table)
     console.print(f"\n[dim]Gateway: {settings.hud_gateway_url}[/dim]")

hud_python-0.6.2/hud/cli/presets.py

@@ -0,0 +1,139 @@
+"""Starter presets for ``hud init`` — the same set offered by the platform's
+*environments/new* flow.
+
+Each preset is a standalone public GitHub repo under ``hud-evals``. ``hud init``
+downloads the repo tarball (no ``git`` required) and extracts it into the target
+directory. Keep this list in sync with the frontend's ``ENVIRONMENT_TEMPLATES``
+(``app/(auth)/environments/components/EnvironmentTemplates.tsx``).
+"""
+
+from __future__ import annotations
+
+import io
+import os
+import tarfile
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+import httpx
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class EnvironmentPreset:
+    """A starter environment sourced from a public GitHub repo."""
+
+    id: str
+    name: str
+    description: str
+    owner: str
+    repo: str
+
+
+ENVIRONMENT_PRESETS: tuple[EnvironmentPreset, ...] = (
+    EnvironmentPreset(
+        "blank",
+        "Blank",
+        "Minimal starting point for a custom environment.",
+        "hud-evals",
+        "hud-blank",
+    ),
+    EnvironmentPreset(
+        "browser",
+        "Browser",
+        "Local browser automation environment.",
+        "hud-evals",
+        "hud-browser",
+    ),
+    EnvironmentPreset(
+        "deepresearch",
+        "Deep Research",
+        "Deep research environment with Exa search integration.",
+        "hud-evals",
+        "hud-deepresearch",
+    ),
+    EnvironmentPreset(
+        "cua",
+        "Computer Use",
+        "Computer-use agent (CUA) desktop environment.",
+        "hud-evals",
+        "cua-template",
+    ),
+    EnvironmentPreset(
+        "autonomous-businesses",
+        "Autonomous Businesses",
+        "Autonomous business simulation environment.",
+        "hud-evals",
+        "autonomous-businesses-template",
+    ),
+    EnvironmentPreset(
+        "verilog",
+        "Verilog",
+        "Verilog hardware-design environment.",
+        "hud-evals",
+        "verilog-template",
+    ),
+)
+
+PRESETS_BY_ID: dict[str, EnvironmentPreset] = {p.id: p for p in ENVIRONMENT_PRESETS}
+
+_TARBALL_TIMEOUT = 60.0
+
+
+def _is_within(root: Path, path: Path) -> bool:
+    try:
+        path.relative_to(root)
+        return True
+    except ValueError:
+        return False
+
+
+def _download_tarball(preset: EnvironmentPreset) -> bytes:
+    """Fetch the repo's ``main`` archive from codeload (no API rate limit)."""
+    headers: dict[str, str] = {}
+    token = os.environ.get("GITHUB_TOKEN")
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+
+    url = f"https://codeload.github.com/{preset.owner}/{preset.repo}/tar.gz/refs/heads/main"
+    with httpx.Client(follow_redirects=True, timeout=_TARBALL_TIMEOUT) as client:
+        resp = client.get(url, headers=headers)
+        resp.raise_for_status()
+        return resp.content
+
+
+def materialize_preset(preset: EnvironmentPreset, target: Path) -> None:
+    """Download ``preset``'s repo archive and extract it into ``target``.
+
+    Uses ``codeload.github.com`` (not the rate-limited API) for the repo's
+    ``main`` branch — no ``git`` required. Strips the archive's top-level
+    ``<repo>-main/`` component and refuses any entry that would escape ``target``
+    (path-traversal guard). Honors ``GITHUB_TOKEN`` if set.
+    """
+    payload = _download_tarball(preset)
+
+    target.mkdir(parents=True, exist_ok=True)
+    target_root = target.resolve()
+    with tarfile.open(fileobj=io.BytesIO(payload), mode="r:gz") as tar:
+        for member in tar.getmembers():
+            # GitHub wraps everything in a "<repo>-<sha>/" top-level dir; drop it.
+            parts = member.name.split("/", 1)
+            if len(parts) < 2 or not parts[1]:
+                continue
+            dest = (target_root / parts[1]).resolve()
+            if not _is_within(target_root, dest):
+                raise ValueError(f"unsafe path in archive: {member.name!r}")
+            if member.isdir():
+                dest.mkdir(parents=True, exist_ok=True)
+            elif member.isfile():
+                dest.parent.mkdir(parents=True, exist_ok=True)
+                source = tar.extractfile(member)
+                if source is not None:
+                    dest.write_bytes(source.read())
+                    # Preserve the archive's executable bits so entrypoints and
+                    # scripts stay runnable (no-op on Windows).
+                    if member.mode & 0o111:
+                        dest.chmod(dest.stat().st_mode | (member.mode & 0o111))
+            # Symlinks and other special members are intentionally skipped.

{hud_python-0.6.0 → hud_python-0.6.2}/hud/cli/tests/test_init.py

@@ -14,7 +14,7 @@ if TYPE_CHECKING:
 
 
 def test_init_scaffolds_a_runnable_package(tmp_path: Path) -> None:
-    init_command(name="my-cool-env", directory=str(tmp_path), force=False)
+    init_command(name="my-cool-env", directory=str(tmp_path), force=False, preset=None)
 
     target = tmp_path / "my-cool-env"
     assert {p.name for p in target.iterdir()} == {
@@ -36,7 +36,7 @@ def test_init_refuses_to_clobber_nonempty_directory(tmp_path: Path) -> None:
     (target / "precious.txt").write_text("data")
 
     with pytest.raises(typer.Exit):
-        init_command(name="taken", directory=str(tmp_path), force=False)
+        init_command(name="taken", directory=str(tmp_path), force=False, preset=None)
 
     assert (target / "precious.txt").read_text() == "data"
 
@@ -46,6 +46,6 @@ def test_init_force_overwrites_existing_files(tmp_path: Path) -> None:
     target.mkdir()
     (target / "env.py").write_text("old")
 
-    init_command(name="env", directory=str(tmp_path), force=True)
+    init_command(name="env", directory=str(tmp_path), force=True, preset=None)
 
     assert "Environment" in (target / "env.py").read_text()

{hud_python-0.6.0 → hud_python-0.6.2}/hud/utils/gateway.py

@@ -35,6 +35,7 @@ class GatewayModelInfo(BaseModel):
     name: str | None = None
     model_name: str | None = None
     sdk_agent_type: str | None = None
+    is_trainable: bool = False
     provider: GatewayProviderInfo = Field(default_factory=GatewayProviderInfo)
 
 

{hud_python-0.6.0 → hud_python-0.6.2}/hud/version.py

@@ -4,4 +4,4 @@ Version information for the HUD SDK.
 
 from __future__ import annotations
 
-__version__ = "0.5.41"
+__version__ = "0.6.2"

{hud_python-0.6.0 → hud_python-0.6.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "hud-python"
-version = "0.6.0"
+version = "0.6.2"
 description = "SDK for the HUD platform."
 readme = "README.md"
 requires-python = ">=3.11, <3.13"

hud_python-0.6.0/hud/cli/init.py

@@ -1,76 +0,0 @@
-"""``hud init``: scaffold a new HUD environment package.
-
-Purely local — writes the v6 template files into a fresh directory. No
-network, no API key, no prompts.
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-import typer
-
-from hud.utils.hud_console import HUDConsole
-
-from .templates import DOCKERFILE_HUD, ENV_PY, PYPROJECT_TOML, TASKS_PY
-
-
-def _python_name(name: str) -> str:
-    """Normalize a package name into a Python-identifier-ish env name."""
-    name = name.replace("-", "_").replace(" ", "_")
-    return "".join(c if c.isalnum() or c == "_" else "_" for c in name)
-
-
-def init_command(
-    name: str = typer.Argument(..., help="Environment name (directory to create)"),
-    directory: str = typer.Option(".", "--dir", "-d", help="Parent directory"),
-    force: bool = typer.Option(False, "--force", "-f", help="Overwrite existing files"),
-) -> None:
-    """🚀 Create a new HUD environment package.
-
-    [not dim]Writes env.py (tasks + capabilities), tasks.py, Dockerfile.hud, and
-    pyproject.toml into a new directory.
-
-    Examples:
-        hud init my-env             # create ./my-env
-        hud init my-env --dir envs  # create ./envs/my-env[/not dim]
-    """
-    hud_console = HUDConsole()
-
-    target = Path(directory) / name
-    if target.exists() and any(target.iterdir()) and not force:
-        hud_console.error(f"{target} already exists and is not empty (use --force)")
-        raise typer.Exit(1)
-
-    env_name = _python_name(name)
-    files = {
-        "pyproject.toml": PYPROJECT_TOML.format(name=env_name.replace("_", "-")),
-        "env.py": ENV_PY.format(env_name=env_name),
-        "tasks.py": TASKS_PY.format(env_name=env_name),
-        "Dockerfile.hud": DOCKERFILE_HUD,
-    }
-
-    hud_console.header(f"HUD Init: {env_name}")
-    target.mkdir(parents=True, exist_ok=True)
-    for filename, content in files.items():
-        (target / filename).write_text(content)
-        hud_console.status_item(filename, "✓")
-
-    hud_console.section_title("Next Steps")
-    hud_console.info("")
-    hud_console.command_example(f"cd {target}", "1. Enter the package")
-    hud_console.info("")
-    hud_console.info("2. Define task definitions in env.py")
-    hud_console.info("   A @env.template is an async generator: it yields a prompt, then")
-    hud_console.info("   (after the agent answers) yields a reward.")
-    hud_console.info("")
-    hud_console.info("3. List the tasks to run in tasks.py")
-    hud_console.info("   Call a task with args to bind a runnable Task.")
-    hud_console.info("")
-    hud_console.command_example("hud eval tasks.py claude", "4. Run an agent over them")
-    hud_console.info("")
-    hud_console.info("5. Deploy for scale")
-    hud_console.info("   hud deploy, then run many evals in parallel.")
-    hud_console.info("")
-    hud_console.info("Tip: Install the HUD skill so your coding agent can help you build:")
-    hud_console.command_example("npx skills add docs.hud.ai", "Install HUD skill")