hud-python 0.2.9__tar.gz → 0.3.0__tar.gz

{hud_python-0.2.9 → hud_python-0.3.0}/.github/workflows/ci.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.11", "3.12", "3.13"]
 
     steps:
       - name: Check out code
@@ -23,7 +23,20 @@ jobs:
       - name: Install Python
         run: uv python install ${{ matrix.python-version }}
 
+      - name: Setup virtual display
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y xvfb
+          Xvfb :99 -screen 0 1920x1080x24 -ac &
+          sleep 3
+      
+      - name: Install Playwright browsers
+        run: uv run --with=".[dev]" playwright install chromium
+      
       - name: Run tests
+        env:
+          DISPLAY: :99
+          XAUTHORITY: /dev/null
         run: uv run --python ${{ matrix.python-version }} --with=".[dev]" pytest --rootdir=hud --cov --cov-report=''
 
   lint-ruff:

{hud_python-0.2.9 → hud_python-0.3.0}/.gitignore

@@ -27,3 +27,5 @@ test.json
 TODO.md
 
 .coverage
+
+*.log

{hud_python-0.2.9 → hud_python-0.3.0}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: hud-python
-Version: 0.2.9
-Summary: SDK for the HUD evaluation platform.
+Version: 0.3.0
+Summary: SDK for the HUD platform.
 Project-URL: Homepage, https://github.com/hud-evals/hud-sdk
 Project-URL: Bug Tracker, https://github.com/hud-evals/hud-sdk/issues
-Project-URL: Documentation, https://hud.so
+Project-URL: Documentation, https://docs.hud.so
 Author-email: HUD SDK <founders@hud.so>
 License: MIT License
         
@@ -31,11 +31,10 @@ License-File: LICENSE
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Python: <3.14,>=3.10
+Requires-Python: <3.14,>=3.11
 Requires-Dist: aiodocker>=0.24.0
 Requires-Dist: anthropic
 Requires-Dist: dotenv>=0.9.9
@@ -43,12 +42,15 @@ Requires-Dist: httpx<1,>=0.23.0
 Requires-Dist: inspect-ai>=0.3.80
 Requires-Dist: ipykernel
 Requires-Dist: langchain
+Requires-Dist: langchain-anthropic
 Requires-Dist: langchain-openai
-Requires-Dist: mcp
+Requires-Dist: mcp-use>=1.3.7
+Requires-Dist: mcp==1.12.2
 Requires-Dist: numpy
 Requires-Dist: openai
 Requires-Dist: pathspec>=0.12.1
 Requires-Dist: pillow>=11.1.0
+Requires-Dist: pyautogui>=0.9.54
 Requires-Dist: pydantic-settings<3,>=2
 Requires-Dist: pydantic<3,>=2
 Requires-Dist: textdistance<5,>=4.5.0
@@ -62,6 +64,7 @@ Requires-Dist: ipython<9; extra == 'dev'
 Requires-Dist: jupyter-client; extra == 'dev'
 Requires-Dist: jupyter-core; extra == 'dev'
 Requires-Dist: openai; extra == 'dev'
+Requires-Dist: playwright; extra == 'dev'
 Requires-Dist: pyright==1.1.401; extra == 'dev'
 Requires-Dist: pytest-asyncio; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'

hud_python-0.3.0/environments/README.md

@@ -0,0 +1,163 @@
+# HUD MCP Environment Requirements
+
+Quick guide for creating HUD-compatible MCP environments.
+
+## Required MCP Tools
+
+### 1. `setup` Tool
+```python
+@mcp.tool()
+async def setup(config: dict) -> dict:
+    """Initialize environment from task.setup config (any format)."""
+    # Handle config however your environment needs
+    return {"status": "success"}  # Return format is flexible
+```
+
+### 2. `evaluate` Tool  
+```python
+@mcp.tool()
+async def evaluate(config: dict) -> dict:
+    """Evaluate task completion from task.evaluate config."""
+    # Your evaluation logic
+    return {
+        "reward": 1.0,    # Required: 0.0-1.0 score
+        "done": True,     # Required: completion flag
+        "info": {}        # Optional: metadata
+    }
+```
+
+### 3. Interaction Tool(s)
+At least one tool for agent interaction during task execution:
+
+```python
+# Option A: Use HUD computer tool
+from hud.tools import HudComputerTool
+from hud.tools.helper import register_instance_tool
+
+register_instance_tool(mcp, "computer", HudComputerTool())
+
+# Option B: Custom API tool
+@mcp.tool()
+async def api_request(url: str, method: str = "GET", data: dict = None) -> dict:
+    # Your API logic
+    pass
+```
+
+**Note**: `setup` and `evaluate` are **lifecycle** MCP tools that:
+- Are **automatically discovered** by the MCP client (always available to framework)  
+- Are **filtered out** from LLM conversation (not in `allowed_tools`)
+- Are **called programmatically** by the agent during task execution
+
+Only include **interaction tools** in `allowed_tools`: `computer`, `anthropic_computer`, `api_request`, etc.
+
+## Config Flexibility
+
+Task configs can be **any format**:
+```python
+task.setup = {"function": "reset", "args": {}}
+task.setup = {"id": "task_123"}
+task.setup = {"name": "problem_name"}
+task.setup = "simple_string"
+task.setup = ["step1", "step2"]
+# Your environment decides what formats to support
+```
+
+## Minimal Example
+
+```python
+from fastmcp import FastMCP
+from hud.tools import HudComputerTool
+from hud.tools.helper import register_instance_tool
+
+mcp = FastMCP("My Environment")
+
+@mcp.tool()
+async def setup(config: dict) -> dict:
+    return {"status": "success"}
+
+@mcp.tool() 
+async def evaluate(config: dict) -> dict:
+    return {"reward": 1.0, "done": True, "info": {}}
+
+@mcp.initialize()
+async def init():
+    register_instance_tool(mcp, "computer", HudComputerTool())
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+## Testing Your Environment
+
+### Unified Agent Interface
+
+```python
+import asyncio
+from hud.mcp_agent import ClaudeMCPAgent
+from hud import Task
+from mcp_use import MCPClient
+
+async def test_environment():
+    # Connect to your environment
+    config = {"mcpServers": {"env": {"command": "python", "args": ["my_env.py"]}}}
+    client = MCPClient.from_dict(config)
+    
+    # Create agent (only specify interaction tools)
+    agent = ClaudeMCPAgent(
+        client=client,
+        model="claude-sonnet-4-20250514",
+        allowed_tools=["computer", "api_request"]  # Interaction tools only
+    )
+    
+    # Simple query
+    result = await agent.run("Take a screenshot and describe what you see")
+    print(f"Query result: {result}")
+    
+    # Full task with lifecycle
+    task = Task(
+        prompt="Complete the todo app workflow",
+        setup={"function": "todo_seed", "args": {"num_items": 3}},
+        evaluate={"function": "todo_completed", "args": {"expected_count": 1}}
+    )
+    
+    eval_result = await agent.run(task)
+    print(f"Task result: {eval_result}")
+    # Returns: {"reward": 1.0, "done": True, "info": {...}}
+    
+    await client.close_all_sessions()
+
+# Run the test
+asyncio.run(test_environment())
+```
+
+### Direct MCP Tool Testing
+
+```python
+from mcp_use import MCPClient
+
+# Test individual tools
+config = {"mcpServers": {"env": {"command": "python", "args": ["my_env.py"]}}}
+client = MCPClient.from_dict(config)
+session = await client.create_session("env")
+
+# Test setup/evaluate tools directly
+setup_result = await session.connector.call_tool("setup", {"function": "test_setup"})
+eval_result = await session.connector.call_tool("evaluate", {"function": "test_eval"})
+```
+
+## Key Features
+
+✨ **Unified Interface**: Single `agent.run()` method handles both simple queries and full task lifecycle  
+🔄 **Automatic Lifecycle**: Setup → Execute → Evaluate phases managed automatically  
+📋 **Flexible Config**: Support any setup/evaluate config format your environment needs  
+🔧 **Easy Integration**: Import HUD tools with `register_instance_tool()`  
+🛡️ **Smart Tool Filtering**: Lifecycle tools auto-discovered but hidden from LLM conversation  
+
+## Examples
+
+### Environment Examples
+- [`simple_browser/`](./simple_browser/) - Computer tool + GUI automation
+- [`qa_controller/`](./qa_controller/) - Text-based environment
+
+### Usage Examples  
+- [`simple_task_example.py`](../examples/agents_tools/simple_task_example.py) - Complete demo with simple_browser environment

hud_python-0.3.0/environments/simple_browser/.dockerignore

@@ -0,0 +1,52 @@
+# Git
+.git
+.gitignore
+
+# Node
+app/frontend/node_modules
+app/frontend/.next
+app/frontend/build
+app/frontend/dist
+apps/*/frontend/node_modules
+apps/*/frontend/.next
+apps/*/frontend/build
+apps/*/frontend/dist
+*.log
+
+# Python
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.egg-info
+.pytest_cache
+.mypy_cache
+.coverage
+.venv
+venv
+env
+apps/*/.venv
+apps/*/backend/.venv
+apps/*/backend/venv
+
+# Database
+app/backend/*.db
+app/backend/*.sqlite
+apps/*/backend/*.db
+apps/*/backend/*.sqlite
+
+# IDE
+.vscode
+.idea
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Documentation
+*.md
+!app/README.md
+!launch/README.md 

hud_python-0.3.0/environments/simple_browser/.gitignore

@@ -0,0 +1,100 @@
+# Dependencies
+node_modules/
+.pnp
+.pnp.js
+
+# Testing
+coverage/
+.coverage
+.pytest_cache/
+htmlcov/
+
+# Next.js
+.next/
+out/
+build/
+*.tsbuildinfo
+next-env.d.ts
+
+# Production
+dist/
+
+# Misc
+.DS_Store
+*.pem
+Thumbs.db
+
+# Debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# Local env files
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Vercel
+.vercel
+
+# TypeScript
+*.tsbuildinfo
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+.venv/
+ENV/
+env.bak/
+venv.bak/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# uv
+.venv/
+uv.lock
+
+# Database
+*.db
+*.sqlite
+*.sqlite3
+app.db
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.project
+.classpath
+.c9/
+*.launch
+.settings/
+*.sublime-workspace
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Logs
+logs/
+*.log
+
+# Docker
+.dockerignore.local 

hud_python-0.3.0/environments/simple_browser/DEPLOYMENT.md

@@ -0,0 +1,159 @@
+# Deployment Guide for HUD Browser Environment
+
+This guide explains how to build and deploy the simple browser environment for use with the HUD MCP server.
+
+## Quick Start
+
+To use this environment with the HUD MCP server, configure your MCP client:
+
+```python
+config = {
+    "mcpServers": {
+        "browser": {
+            "url": "https://mcp.hud.so/api/v3/mcp",
+            "headers": {
+                "Authorization": f"Bearer {HUD_API_KEY}",
+                "Mcp-Image": "your-username/hud-browser:latest"  # Your published image
+            }
+        }
+    }
+}
+```
+
+## What's in the Image
+
+The `hud-browser` image contains:
+- **Chromium Browser** with Playwright for automation
+- **MCP Server** running in stdio mode with computer tools
+- **VNC Server** for remote viewing (port 8080)
+- **Pre-built Web Apps** (e.g., todo app with Next.js frontend and FastAPI backend)
+
+## Building and Publishing the Image
+
+### Option 1: Docker Hub (Public/Private)
+
+```bash
+# Build the image
+docker build -t your-username/hud-browser:latest environments/simple_browser/
+
+# Push to Docker Hub
+docker login
+docker push your-username/hud-browser:latest
+
+# Use in MCP client
+"Mcp-Image": "your-username/hud-browser:latest"
+```
+
+### Option 2: GitHub Container Registry
+
+```bash
+# Build and tag
+docker build -t ghcr.io/your-org/hud-browser:latest environments/simple_browser/
+
+# Login and push
+echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin
+docker push ghcr.io/your-org/hud-browser:latest
+
+# Use in MCP client
+"Mcp-Image": "ghcr.io/your-org/hud-browser:latest"
+```
+
+### Option 3: Google Container Registry (GCR)
+
+```bash
+# Build and tag
+docker build -t gcr.io/your-project/hud-browser:latest environments/simple_browser/
+
+# Configure auth and push
+gcloud auth configure-docker
+docker push gcr.io/your-project/hud-browser:latest
+
+# Use in MCP client
+"Mcp-Image": "gcr.io/your-project/hud-browser:latest"
+```
+
+### Option 4: AWS Elastic Container Registry (ECR)
+
+```bash
+# Build the image
+docker build -t hud-browser:latest environments/simple_browser/
+
+# Tag for ECR
+docker tag hud-browser:latest 123456789012.dkr.ecr.us-east-1.amazonaws.com/hud-browser:latest
+
+# Login and push
+aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com
+docker push 123456789012.dkr.ecr.us-east-1.amazonaws.com/hud-browser:latest
+
+# Use in MCP client
+"Mcp-Image": "123456789012.dkr.ecr.us-east-1.amazonaws.com/hud-browser:latest"
+```
+
+### Option 5: Private Registry
+
+```bash
+# Build and tag for your registry
+docker build -t registry.company.com/hud-browser:latest environments/simple_browser/
+
+# Push to private registry
+docker push registry.company.com/hud-browser:latest
+
+# Use in MCP client
+"Mcp-Image": "registry.company.com/hud-browser:latest"
+```
+
+## Configuring the Environment
+
+Environment variables are passed through headers with the `Env-` prefix. The header name is transformed to create the environment variable:
+- The `Env-` prefix is removed
+- Dashes are converted to underscores
+- The name is converted to uppercase
+
+For example: `Env-launch-apps` → `LAUNCH_APPS`
+
+### Available Environment Variables
+
+- `LAUNCH_APPS` - Comma-separated list of apps to launch (default: none)
+- `BROWSER_URL` - URL to navigate browser to (default: https://google.com)
+- `WAIT_FOR_APPS` - Wait for apps before browser navigation (default: true)
+- `FRONTEND_PORT_START` - Starting port for frontend services (default: 3000)
+- `BACKEND_PORT_START` - Starting port for backend services (default: 5000)
+- `MCP_TRANSPORT` - MCP server transport mode: stdio or streamable-http (default: stdio)
+
+### Example: Launch with Todo App
+
+```python
+config = {
+    "mcpServers": {
+        "browser": {
+            "url": "https://mcp.hud.so/api/v3/mcp",
+            "headers": {
+                "Authorization": f"Bearer {HUD_API_KEY}",
+                "Mcp-Image": "your-username/hud-browser:latest",
+                "Env-launch-apps": "todo",
+                "Env-browser-url": "http://localhost:3000"
+            }
+        }
+    }
+}
+```
+
+### Example: Multiple Apps with Custom Ports
+
+```python
+config = {
+    "mcpServers": {
+        "browser": {
+            "url": "https://mcp.hud.so/api/v3/mcp",
+            "headers": {
+                "Authorization": f"Bearer {HUD_API_KEY}",
+                "Mcp-Image": "your-username/hud-browser:latest",
+                "Env-launch-apps": "todo,calendar",
+                "Env-frontend-port-start": "3000",
+                "Env-backend-port-start": "5000",
+                "Env-wait-for-apps": "true"
+            }
+        }
+    }
+}
+```

hud_python-0.3.0/environments/simple_browser/Dockerfile

@@ -0,0 +1,38 @@
+FROM hudpython/novnc-base:latest
+# Install package
+WORKDIR /app
+COPY pyproject.toml .
+COPY src/ ./src/
+RUN uv pip install --system --break-system-packages -e .
+
+# Copy apps
+COPY apps/ /app/apps/
+
+# Make launch scripts executable
+RUN find /app/apps -name "launch.py" -type f -exec chmod +x {} \;
+
+# Pre-install npm dependencies for all frontend apps
+RUN for app in /app/apps/*/frontend; do \
+        if [ -f "$app/package.json" ]; then \
+            echo "Installing npm dependencies for $app"; \
+            cd "$app" && npm install; \
+            echo "Building Next.js app in $app"; \
+            npm run build || echo "Build failed for $app (might not be Next.js)"; \
+            cd -; \
+        fi \
+    done
+
+# Set defaults
+ENV MCP_TRANSPORT="stdio"
+ENV HUD_LOG_STREAM="stderr"
+ENV PYTHONUNBUFFERED="1"
+
+# Expose all the ports we need
+EXPOSE 8080 8040-8050 3000-3010 5000-5010
+
+# Copy and use start script
+COPY start.sh /app/start.sh
+RUN chmod +x /app/start.sh
+
+# Run via start script to ensure X11 is ready
+CMD ["/app/start.sh"]