{"id":7293,"library":"hud-python","title":"HUD Python SDK (Evaluations and RL Environments)","description":"HUD is a platform for building Reinforcement Learning (RL) environments for AI agents. It allows users to define agent-callable tools, write evaluation scenarios, run evaluations at scale, and train models on the results. The Python SDK, currently at version 0.5.35, is actively developed with frequent releases, often multiple times a month, providing tools for creating and evaluating AI agents.","status":"active","version":"0.5.35","language":"en","source_language":"en","source_url":"https://github.com/hud-evals/hud-python","tags":["AI","MLOps","evaluation","LLM","RL","agents"],"install":[{"cmd":"pip install hud-python","lang":"bash","label":"Install with pip"},{"cmd":"uv tool install hud-python --python 3.12","lang":"bash","label":"Install CLI with uv (recommended)"}],"dependencies":[{"reason":"Requires Python 3.11 or 3.12 for compatibility.","package":"python","optional":false}],"imports":[{"note":"Used to define RL environments and scenarios.","symbol":"Environment","correct":"from hud import Environment"},{"note":"Used to instantiate AI agents for evaluation.","symbol":"create_agent","correct":"from hud.agents import create_agent"},{"note":"Context manager for running evaluations on tasks.","symbol":"hud.eval","correct":"import hud; async with hud.eval(task) as ctx:"}],"quickstart":{"code":"import os\nfrom hud import Environment\nfrom hud.agents import create_agent\n\n# Ensure your HUD_API_KEY is set as an environment variable\n# Example: export HUD_API_KEY=\"your_api_key_here\"\nhud_api_key = os.environ.get('HUD_API_KEY', '')\n\n# Define an environment\nenv = Environment(\"my-first-env\")\n\n# Define a scenario using a tool\n@env.tool()\ndef add(a: int, b: int) -> int:\n    \"\"\"Adds two numbers.\"\"\"\n    return a + b\n\n@env.scenario(\"sum-check\")\nasync def sum_check(num1: int, num2: int):\n    # Prompt the agent to use the 'add' tool\n    answer = yield f\"What is the sum of {num1} and {num2}? Use the 'add' tool.\"\n    correct = num1 + num2\n    # Score the agent's answer\n    yield 1.0 if str(correct) in str(answer) else 0.0\n\nasync def run_evaluation():\n    # Create a task for the scenario\n    task = env(\"sum-check\", num1=5, num2=7)\n\n    # Create an agent (e.g., using a model via HUD's gateway)\n    agent = create_agent(\"gpt-4o\") # or \"claude-sonnet-4-5\", etc.\n\n    print(f\"Running task: {task.scenario_slug} with {agent.model}\")\n    async with hud.eval(task) as ctx:\n        result = await agent.run(ctx)\n        print(f\"Agent response: {result.response}\")\n        print(f\"Reward: {result.reward}\")\n\nif __name__ == \"__main__\":\n    import asyncio\n    if not hud_api_key:\n        print(\"Error: HUD_API_KEY environment variable not set. Please set it to run the quickstart.\")\n    else:\n        asyncio.run(run_evaluation())\n","lang":"python","description":"This quickstart demonstrates defining a HUD environment with a custom tool and a scenario, then running an AI agent against that scenario using `hud.eval()`. Ensure your `HUD_API_KEY` environment variable is set for authentication."},"warnings":[{"fix":"For AI agent evaluations, use `pip install hud-python` and `import hud`. For the runtime sensor, refer to `hud-sdk` documentation.","message":"The `hud-python` library (for AI agent evaluations and RL environments) is distinct from `hud-sdk` (a runtime code sensor) on PyPI. Ensure you install and import from the correct package based on your use case.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Set `export HUD_ENABLE=true` in your environment or service configuration before running your application.","message":"The `HUD_ENABLE` environment variable must be explicitly set to `true` (case-insensitive) for the SDK to initialize and run correctly. If undefined or set to any other value, Hud components will not be active.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consult the latest CLI documentation for `hud build` and `hud analyze` to ensure correct usage, especially when working with HTTP mode.","message":"Changes in CLI commands like `hud build` and `hud analyze` have been introduced to distinguish between HTTP mode and stdio, which might alter expected behavior or require updates to existing scripts.","severity":"breaking","affected_versions":">=0.5.31"},{"fix":"Update to `hud-python` version 0.5.34 or newer to use the `hud sync` command for managing local and platform environments/tasks.","message":"The `hud sync` command was introduced in version 0.5.34 for syncing local environments and tasks to the HUD platform. Users on older versions will not have access to this functionality.","severity":"gotcha","affected_versions":"<0.5.34"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install hud-python` (or `uv tool install hud-python --python 3.12` for CLI) to install the library.","cause":"The `hud-python` library is either not installed or not installed in the active Python environment.","error":"ModuleNotFoundError: No module named 'hud'"},{"fix":"Ensure `export HUD_API_KEY=\"your_valid_key_here\"` is set with a correct, non-empty API key obtained from `hud.ai`.","cause":"The `HUD_API_KEY` environment variable is set but contains an invalid or empty value, preventing authentication with the HUD platform.","error":"E0004 - Hud init ran, HUD_KEY invalid"},{"fix":"Set `export HUD_ENABLE=true` in your environment or service configuration.","cause":"The `HUD_ENABLE` environment variable is not defined, which is required for the SDK to initialize.","error":"Did not load as HUD_ENABLE is undefined. Please set HUD_ENABLE=true to run Hud."},{"fix":"Ensure `HUD_TAGS` is a valid JSON-formatted string, e.g., `export HUD_TAGS='{\"env\":\"dev\", \"owner\":\"team_x\"}'`.","cause":"The optional `HUD_TAGS` environment variable is provided but its value is not a valid JSON string, which is required for metadata tagging.","error":"E0007 - Hud init ran, HUD_TAGS invalid JSON"}]}