hud-python 0.5.41

SDK for the HUD platform.

HUD is a platform for building RL environments for AI agents. Define agent-callable tools, write evaluation scenarios, run evals at scale, and train models on the results.

To learn more, check out our Documentation and API Reference.

Install

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

Get your API key at [hud.ai](https://hud.ai) and set it:

```bash
export HUD_API_KEY=your-key-here

Get your API key at hud.ai/project/api-keys.

Or install as a library: pip install hud-python

Environments

An environment is the harness an agent operates in. It packages tools (functions agents can call) and scenarios (how agents are evaluated) into a single deployable unit. Each environment spins up fresh and isolated for every evaluation.

from hud import Environment

env = Environment("my-env")

@env.scenario("count")
async def count(word: str, letter: str):
    # PROMPT — send a question to the agent.
    # The agent runs its reasoning loop and returns an answer.
    answer = yield f"How many '{letter}' in '{word}'?"

    # SCORE — check the agent's answer against the correct count.
    # Return a reward: 1.0 for correct, 0.0 for wrong.
    correct = str(word.lower().count(letter.lower()))
    yield 1.0 if answer and correct in answer else 0.0

A scenario has two yields. The first sends a prompt — the agent runs between the yields, calling tools and reasoning. The second checks the result and returns a reward (0.0 to 1.0). → Core Concepts

Run an Agent

import hud
from hud.agents import create_agent

task = env("count", word="strawberry", letter="r")
agent = create_agent("claude-sonnet-4-5")

async with hud.eval(task) as ctx:
    result = await agent.run(ctx)

print(f"Reward: {result.reward}")  # 1.0 if agent answers "3"

create_agent() picks the right agent class and native tools for each model. → Environments

Workflow

hud init my-env          # Scaffold environment
cd my-env
hud dev env:env -w env.py    # Run locally with hot-reload
hud eval tasks.py claude     # Run evals locally
hud deploy                   # Deploy to platform
hud sync tasks my-taskset    # Sync tasks to platform

Once deployed, run evals at scale from the CLI or the platform UI:

hud eval my-taskset claude --remote --full

→ Deploy · Testing & Evaluation

Pre-built Tools

HUD ships tools for computer control, shell execution, file editing, browser automation, and web search. Add them to any environment:

from hud.tools import AnthropicComputerTool, BashTool, EditTool

env.add_tool(AnthropicComputerTool())  # Mouse, keyboard, screenshots
env.add_tool(BashTool())               # Persistent bash shell
env.add_tool(EditTool())               # File viewing and editing

HUD adapts each tool to the model's native format — Claude gets computer_20250124, OpenAI gets computer_use_preview, Gemini gets ComputerUse. → Tools Reference

Model Gateway

Use Claude, GPT, Gemini, or Grok through one OpenAI-compatible endpoint:

from openai import AsyncOpenAI
import os

client = AsyncOpenAI(
    base_url="https://inference.hud.ai",
    api_key=os.environ["HUD_API_KEY"]
)

response = await client.chat.completions.create(
    model="claude-sonnet-4-5",  # or gpt-4o, gemini-2.5-pro (https://hud.ai/models)
    messages=[{"role": "user", "content": "Hello!"}]
)

Every call is traced at hud.ai. → Models

Links

• 📖 Documentation
• ⌨️ CLI Reference
• 🏆 Leaderboards
• 🌐 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 · Tools · Environments

Citation

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

MIT License · LICENSE