Metadata-Version: 2.4
Name: hud-python
Version: 0.5.38
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
Project-URL: Documentation, https://docs.hud.ai
Author-email: HUD <founders@hud.ai>
License: MIT License
        
        Copyright (c) 2025 Human Union Data, Inc
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: <3.13,>=3.11
Requires-Dist: a2a-sdk>=0.3.24
Requires-Dist: blessed>=1.20.0
Requires-Dist: fastmcp==3.0.2
Requires-Dist: httpx<1,>=0.23.0
Requires-Dist: mcp<2.0,>=1.24.0
Requires-Dist: openai>=2.26.0
Requires-Dist: packaging>=21.0
Requires-Dist: prompt-toolkit==3.0.51
Requires-Dist: pydantic-settings<3,>=2.2
Requires-Dist: pydantic<3,>=2.6
Requires-Dist: questionary==2.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: scarf-sdk>=0.1.0
Requires-Dist: toml>=0.10.2
Requires-Dist: typer>=0.9.0
Requires-Dist: watchfiles>=0.21.0
Provides-Extra: agent
Requires-Dist: anthropic>=0.78.0; extra == 'agent'
Requires-Dist: google-genai; extra == 'agent'
Requires-Dist: langchain>=1.1.0; extra == 'agent'
Requires-Dist: mcp-use==1.5.0; extra == 'agent'
Requires-Dist: openai-agents; extra == 'agent'
Requires-Dist: pillow>=11.1.0; extra == 'agent'
Requires-Dist: tornado>=6.5.2; extra == 'agent'
Provides-Extra: agents
Requires-Dist: anthropic>=0.78.0; extra == 'agents'
Requires-Dist: google-genai; extra == 'agents'
Requires-Dist: langchain>=1.1.0; extra == 'agents'
Requires-Dist: mcp-use==1.5.0; extra == 'agents'
Requires-Dist: openai-agents; extra == 'agents'
Requires-Dist: pillow>=11.1.0; extra == 'agents'
Requires-Dist: tornado>=6.5.2; extra == 'agents'
Provides-Extra: bedrock
Requires-Dist: anthropic[bedrock]>=0.78.0; extra == 'bedrock'
Provides-Extra: dev
Requires-Dist: anthropic>=0.78.0; extra == 'dev'
Requires-Dist: dotenv>=0.9.9; extra == 'dev'
Requires-Dist: google-adk; extra == 'dev'
Requires-Dist: google-genai; extra == 'dev'
Requires-Dist: ipykernel; extra == 'dev'
Requires-Dist: ipython<9; extra == 'dev'
Requires-Dist: jupyter-client; extra == 'dev'
Requires-Dist: jupyter-core; extra == 'dev'
Requires-Dist: langchain>=1.1.0; extra == 'dev'
Requires-Dist: llama-index-core; extra == 'dev'
Requires-Dist: mcp-use==1.5.0; extra == 'dev'
Requires-Dist: openai-agents; extra == 'dev'
Requires-Dist: pillow>=11.1.0; extra == 'dev'
Requires-Dist: playwright; extra == 'dev'
Requires-Dist: pyautogui>=0.9.54; extra == 'dev'
Requires-Dist: pyright==1.1.407; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest-mock; extra == 'dev'
Requires-Dist: pytest>=8.1.1; extra == 'dev'
Requires-Dist: ruff<0.15.0,>=0.11.8; extra == 'dev'
Requires-Dist: tornado>=6.5.2; extra == 'dev'
Description-Content-Type: text/markdown

<div align="left">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/hud-evals/hud-python/main/docs/logo/hud_logo_dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/hud-evals/hud-python/main/docs/logo/hud_logo.svg">
    <img src="https://raw.githubusercontent.com/hud-evals/hud-python/main/docs/logo/hud_logo.svg" alt="HUD" width="150" style="margin-bottom: 24px;"/>
  </picture>
</div>

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](https://docs.hud.ai) and [API Reference](https://docs.hud.ai/reference).

[![PyPI](https://img.shields.io/pypi/v/hud-python?style=flat-square)](https://pypi.org/project/hud-python/)
[![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)
[![Add docs to Cursor](https://img.shields.io/badge/Add%20docs%20to-Cursor-black?style=flat-square)](https://cursor.com/en/install-mcp?name=docs-hud-python&config=eyJ1cmwiOiJodHRwczovL2RvY3MuaHVkLmFpL21jcCJ9)
[![Discord](https://img.shields.io/discord/1327447144772407390?label=Discord&logo=discord&style=flat-square)](https://discord.gg/wkjtmHYYjm)
[![X Follow](https://img.shields.io/twitter/follow/hud_evals?style=social)](https://x.com/intent/user?screen_name=hud_evals)
[![Scarf](https://static.scarf.sh/a.png?x-pxid=6530ff33-4945-452b-81f9-626872593933)](https://scarf.sh)
[![Docs](https://img.shields.io/badge/docs-hud.ai-blue?style=flat-square)](https://docs.hud.ai)

## Install

```bash
# 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](https://hud.ai/project/api-keys).

> Or install as a library: `pip install hud-python`

![Agent running on SheetBench](https://raw.githubusercontent.com/hud-evals/hud-python/main/docs/src/images/trace_sheet.gif)

## 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.

```python
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](https://docs.hud.ai/concepts)

## Run an Agent

```python
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](https://docs.hud.ai/quick-links/environments)

## Workflow

```bash
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](https://hud.ai):

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

→ [Deploy](https://docs.hud.ai/quick-links/deploy) · [Testing & Evaluation](https://docs.hud.ai/advanced/testing-environments)

## Pre-built Tools

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

```python
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](https://docs.hud.ai/tools/computer)

## Model Gateway

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

```python
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](https://hud.ai). → [Models](https://docs.hud.ai/quick-links/models)

## Links

- 📖 [Documentation](https://docs.hud.ai)
- ⌨️ [CLI Reference](https://docs.hud.ai/reference/cli/overview)
- 🏆 [Leaderboards](https://hud.ai/leaderboards)
- 🌐 [Environment Templates](https://hud.ai/environments)
- 🤖 [Supported Models](https://hud.ai/models)
- 💬 [Discord](https://discord.gg/wkjtmHYYjm)

## Enterprise

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

[📅 Book a call](https://cal.com/jay-hud) · [📧 founders@hud.ai](mailto:founders@hud.ai)

## Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md).

Key areas: [Agents](hud/agents/) · [Tools](hud/tools/) · [Environments](https://hud.ai/environments)

<a href="https://github.com/hud-evals/hud-python/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=hud-evals/hud-python&max=50" />
</a>

## Citation

```bibtex
@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](LICENSE)
