hud-python 0.6.0__py3-none-any.whl → 0.6.2__py3-none-any.whl

hud/cli/init.py

@@ -1,19 +1,29 @@
 """``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.
+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."""
@@ -21,19 +31,66 @@ def _python_name(name: str) -> str:
     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]Writes env.py (tasks + capabilities), tasks.py, Dockerfile.hud, and
-    pyproject.toml into a new directory.
+    [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             # create ./my-env
-        hud init my-env --dir envs  # create ./envs/my-env[/not dim]
+        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()
 
@@ -42,35 +99,49 @@ def init_command(
         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, "✓")
+    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("")
-    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.")
+    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/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/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/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/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/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.dist-info → hud_python-0.6.2.dist-info}/METADATA

@@ -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.dist-info → hud_python-0.6.2.dist-info}/RECORD

@@ -5,7 +5,7 @@ hud/conftest.py,sha256=HKbHvmFXLPX6KFSJgPFUAM22auclNNdFmHGwilNzg98,1012
 hud/server.py,sha256=NtSHIjBFr9lYvryfXrCa-VhwqnwkRy7n5fp_OuNhNOI,1235
 hud/settings.py,sha256=crfeQArM_8JnwmMdx0fcwL5xCvJMjeofGrGbpn0nW3c,6393
 hud/types.py,sha256=yOBFED8Ii7KA-8EzvmE3CU16LCXVigPnNjjl3kB8aRo,15326
-hud/version.py,sha256=naWlJd_xTGFOyiFYQITHg6lq2h2dyn0RtpT4oyuuLgY,105
+hud/version.py,sha256=oJ08yq_IrzFrsTHVgSPsBzDrwos8KumqvTVB-J2A0aM,104
 hud/agents/__init__.py,sha256=ISruomRkEw1-cWCncyCgqKeeueYZFeBvFJ62RBIBQI8,4866
 hud/agents/base.py,sha256=WgEOWUmMioXTxYe6cOvbqnbM4n989Z9kFEZIN6xJ3pU,659
 hud/agents/tool_agent.py,sha256=a0xsh2d8IwvmiPGMs9LCzghi61FHt4vMK_9sW8eNFbA,12557
@@ -95,9 +95,10 @@ hud/cli/cancel.py,sha256=MHRdZ6IoFy3iac9NtTT_c91IB_iQbYISsCb7ph7u298,3785
 hud/cli/client.py,sha256=cC23TUTo7w4S63jtk8SWkFWzG9h8Z2AKwYEqaefBWqg,2946
 hud/cli/deploy.py,sha256=QytQKmGY60YKNnQnhv0gXjMl9BVdwsvMRq0yZypVgpY,26082
 hud/cli/eval.py,sha256=GKvncjJ1AhMiBwsCn8jndAP_IdOe14HYC5AMnsAg3PE,33801
-hud/cli/init.py,sha256=_wLWnbREPYQpS1lfofdaxRfAKCY407O78EhYJBsjfQg,2974
+hud/cli/init.py,sha256=6k3svrqeX19VuQ9cRuTTIojq5L5yRS51YscnXRuayRc,6464
 hud/cli/login.py,sha256=3DhM_FfvfjP-cdfCj596kPo0bE9L3eQdz520X0oWqbc,7961
-hud/cli/models.py,sha256=WuRFExVt8rbqXGvDgJOi0mw8Uqq-VKYmSEBEDyEnJJE,8570
+hud/cli/models.py,sha256=NInyi2I5x-GFBpcTdjvfTI3f3eWC_U-E-SgWJUxbQz8,8770
+hud/cli/presets.py,sha256=qZmc_GKwdnRNJqxRqrg-MDUhN1Vh1JcDB4nJ94_AXLw,4523
 hud/cli/serve.py,sha256=074y6dGh1yPxr6m8MScKpYPXo2SX38zWbq2uZUrXl9k,3757
 hud/cli/sync.py,sha256=rvbcAM7ZfXOrlxRT3Zpp25Y-UkFbPqTuOzrcHAH1tK4,16927
 hud/cli/task.py,sha256=eYByPZHCqSy1GFiyZOVHNNqDFxvHaSLUGNQZ7o9kdz4,8111
@@ -109,7 +110,7 @@ hud/cli/tests/test_cli_more_wrappers.py,sha256=EEFrqTMg3yknQdmb8hWcHJAbinGAOGyqx
 hud/cli/tests/test_deploy.py,sha256=1b_2iviob4b_RFVun01cwCl3i4FmO2MaCrFs7PfzOSI,13983
 hud/cli/tests/test_eval_bedrock.py,sha256=UBGakgIV4kzXUj0Jtbr3t05xBss66YPqruKsovUYyoo,1900
 hud/cli/tests/test_eval_config.py,sha256=Cl4kHc6qykaFt_lmsjyzKZRjsoTdomQBgZ5pYKQLMLQ,7932
-hud/cli/tests/test_init.py,sha256=nzQagJmavThJqd3pgbCDalaW2wyveoVuLEQH1n-CLYw,1440
+hud/cli/tests/test_init.py,sha256=s8ipywnOztV_E4WHuBAqeGGEzcbW2jbIM1RUvEF-yr8,1479
 hud/cli/tests/test_main_module.py,sha256=PyfuSdqI-4Zt-kd16FMj2XHEHrw7SQ75YLJbQPdcIco,1223
 hud/cli/tests/test_sync_export.py,sha256=wd4ICZlNr_7XMw8MfNJuC8v0-lhywsjG7DnZE1zpJek,735
 hud/cli/utils/__init__.py,sha256=L6s0oNzY2LugGp9faodCPnjzM-ZUorUH05-HmYOq5hY,35
@@ -204,7 +205,7 @@ hud/train/client.py,sha256=_CiUXwHmx_E6vvmpZFAxInz8Nxur0_oJjN6BnLix18U,8260
 hud/train/types.py,sha256=QEc_cC0UDCjvHOpFqIyEzuK5IUCBPY33mc6zokfqUDk,6598
 hud/utils/__init__.py,sha256=Tr7Zf9j-MW-mWw7SOezTI7cyp6MpG9vErZ9jEWTujAo,295
 hud/utils/exceptions.py,sha256=eP8nLMltYe4BvnHzqaG5uq-1EPaAkZ2tCjzuxHugC8s,6938
-hud/utils/gateway.py,sha256=NVXe6sYIGxKrevGInOfUF_usfEkMuvQqJIp9aubBUEI,2913
+hud/utils/gateway.py,sha256=CbhrzWi9Nf-woqqrZ8tsEf36QEjzOOIJEcI9Go4jHFg,2944
 hud/utils/hints.py,sha256=HrwAbMjjsCGgvR2bJTXmMeabMV5P__uHCb0lID6Jp04,5607
 hud/utils/hud_console.py,sha256=bzVxUjWq6Np7ZOV8TR8ASXkVAw81O8MsfDaismds0AE,15860
 hud/utils/modules.py,sha256=iUfoIAFdEf_2JAE9I0qsC0ODWz4ILOgDzRy8kcmVDTE,2463
@@ -220,8 +221,8 @@ hud/utils/tests/test_platform.py,sha256=mwhyFkUBvgmHRc43vQ_JgAAW2N9fIaxkQhVo-GB4
 hud/utils/tests/test_requests.py,sha256=ENK6P5xLTuSgWDcCau4zCj_5zPV_EooGwU4P8YYl5Gw,9109
 hud/utils/tests/test_serialization.py,sha256=GY4NiFUJtwLSYQWA0n1zme-Ul4DnBLByHCOOkxn2kLM,819
 hud/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-hud_python-0.6.0.dist-info/METADATA,sha256=IySjNzZJmuHvDVz0w5uEa-HrP4ZLqgODk9OMKu2rupg,12304
-hud_python-0.6.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-hud_python-0.6.0.dist-info/entry_points.txt,sha256=jJbodNFg1m0-CDofe5AHvB4zKBq7sSdP97-ohaQ3ae4,63
-hud_python-0.6.0.dist-info/licenses/LICENSE,sha256=yIzBheVUf86FC1bztAcr7RYWWNxyd3B-UJQ3uddg1HA,1078
-hud_python-0.6.0.dist-info/RECORD,,
+hud_python-0.6.2.dist-info/METADATA,sha256=3vYSE1DBNZV7N4pIXSiZzbJejgOR196u8V40EpkvX2g,12304
+hud_python-0.6.2.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+hud_python-0.6.2.dist-info/entry_points.txt,sha256=jJbodNFg1m0-CDofe5AHvB4zKBq7sSdP97-ohaQ3ae4,63
+hud_python-0.6.2.dist-info/licenses/LICENSE,sha256=yIzBheVUf86FC1bztAcr7RYWWNxyd3B-UJQ3uddg1HA,1078
+hud_python-0.6.2.dist-info/RECORD,,