hud-python 0.6.8.dev0

SDK for the HUD platform.

HUD is a platform for building RL environments for AI agents, across coding, browser, computer-use, and robotics. Define an environment, write tasks, and run them as evals and training across any model, at any scale.

To learn more, see the documentation and environment reference.

Install

# Install the CLI (recommended)
uv tool install hud-python --python 3.12

# …or as a library
pip install hud-python

Get your API key at hud.ai/project/api-keys and set it:

hud set HUD_API_KEY=your-key-here
# or: export HUD_API_KEY=your-key-here

Then scaffold your first environment:

hud init my-env

The protocol

HUD is protocol-first. An agent and an environment exchange just three things: a manifest (the environment's capabilities and tasks), tasks.start that returns the prompt, and tasks.grade that returns the reward. In between, the agent just works, driving the capabilities itself. HUD owns only that thin envelope, so any model or harness plugs into any environment.

sequenceDiagram
    participant Agent
    participant Env as Environment
    participant Caps as Capabilities (ssh · mcp · cdp · rfb · robot)
    Agent->>Env: manifest exchange
    Env-->>Agent: capabilities + tasks
    Agent->>Env: tasks.start
    Env-->>Agent: prompt
    rect rgb(238,238,238)
    Note over Agent,Caps: the agent works, driving capabilities directly
    Agent->>Caps: shell · browser · GUI · tools · robot
    Caps-->>Agent: observations
    end
    Agent->>Env: tasks.grade
    Env-->>Agent: reward

Because the protocol only exposes capabilities (never a fixed agent), an environment outlives any single harness: new harnesses and models keep running against the same environments, benchmarks, and tasks.

Package & run anywhere

A built image is the end product for your tasks: one build packs every task from a single definition. The recommended path is hud deploy, which builds and registers your environment on HUD in one step; then sync a taskset and run remotely:

hud deploy
hud sync tasks my-taskset
hud eval my-taskset --remote

For local iteration, the same protocol works against a container on your laptop:

docker build -f Dockerfile.hud -t my-env .
docker run -d --name run1 -p 8765:8765 my-env
hud task start fix_bug --url tcp://127.0.0.1:8765
hud task grade fix_bug --url tcp://127.0.0.1:8765 --answer "..."
docker rm -f run1

→ Run & deploy

Environments & templates

A template is an async generator registered with @env.template(): yield a prompt, receive the agent's answer, yield a reward. Calling the template mints a runnable Task; one function spans a whole dataset of variants. The simplest needs no capabilities — just a prompt and a grader:

from hud import Environment

env = Environment(name="letter-count")

@env.template()
async def count_letter(word: str = "strawberry", letter: str = "r"):
    answer = yield f"How many '{letter}'s are in '{word}'? Reply with just the number."
    yield 1.0 if answer and str(word.count(letter)) in answer else 0.0

tasks = [count_letter(word=w) for w in ("strawberry", "raspberry", "blueberry")]

Run it immediately against any model:

hud eval tasks.py claude --group 3

Each graded evaluation is a trace (the SDK's live handle is a Run). With HUD_API_KEY set, every rollout is recorded on hud.ai. Tasks that need a shell, browser, GUI, or robot declare capabilities (below); everything else — variants, grading, batching — stays identical.

→ Quickstart · Tasks & tasksets

Capabilities & harnesses

A capability is a connection the environment exposes; a harness attaches its own tools to it. The same environment serves a one-shot Q&A or a full computer-use rollout, depending on which capabilities the harness opens.

Protocol	What it exposes
ssh	Shell + files in a sandboxed workspace (env.workspace(root))
mcp	Tools over the Model Context Protocol
cdp	Browser control over the Chrome DevTools Protocol
rfb	Full computer-use over VNC: screen + keyboard/mouse
robot (beta)	Schema-driven robot observation/action loop over WebSocket

Ships natively: Claude, OpenAI (Responses), OpenAI-compatible endpoints, and Gemini via create_agent("claude-sonnet-4-5") (or gpt-…, gemini-…). The harness wires capability-backed tools for the model you choose at run time.

Bring your own: a harness attaches to a capability and defines a tool spec — wrap browser-use on cdp, a VLA policy on robot, or your own agent on ssh / mcp. No protocol work required.

→ Capabilities · Models · Robots

Deploy on the platform

From the platform UI you can run batches, compare models on the same taskset, and inspect every trace.

→ Run & deploy

Train on rewards

Every rollout returns a Run carrying a trace_id and a reward, so the tasks you evaluate are already training data. Run a group per task and pass the graded runs to TrainingClient.step():

from hud import TrainingClient
from hud.agents import create_agent
from hud.eval import Job

agent = create_agent("arith-rl", completion_kwargs={"extra_body": {"return_token_ids": True}})
trainer = TrainingClient("arith-rl")
taskset, runtime = ...  # your Taskset and where rollouts run

session = await Job.start("arith-rl", group=8)
start = len(session.runs)
await taskset.run(agent, runtime=runtime, group=8, job=session)
await trainer.step(session.runs[start:], learning_rate=1e-5, group_size=8)

HUD is the environment-and-reward source for your own GRPO/PPO loop — the same environment trains any model, text or multimodal, unchanged.

→ Training · Designing tasks for signal

Links

• Documentation
• Quickstart
• CLI reference
• Environment templates
• Supported models
• Discord

Enterprise

Building agents at scale? We work with teams on custom environments, benchmarks, and training.

📅 Book a call · 📧 [e-mail]

Contributing

We welcome contributions! See CONTRIBUTING.md.

Key areas: Agents · Environments · Capabilities · Eval

Citation

@software{hud2025agentevalplatform,
  author = {HUD and Jay Ram and Lorenss Martinsons and Parth Patel and Govind Pimpale and Dylan Bowman and Jaideep Chawla and Nguyen Nhat Minh},
  title  = {HUD: An Evaluation and RL Environments Platform for Agents},
  date   = {2025-04},
  url    = {https://github.com/hud-evals/hud-python},
  langid = {en}
}

MIT License · LICENSE