hud-python 0.3.3__tar.gz → 0.3.5__tar.gz

{hud_python-0.3.3 → hud_python-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hud-python
-Version: 0.3.3
+Version: 0.3.5
 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

{hud_python-0.3.3 → hud_python-0.3.5}/environments/README.md

@@ -74,15 +74,38 @@ docker build -t my-environment .
 docker run --rm -it my-environment     # look for the log line on stderr
 ```
 
+### Recommended Environment Structure
+
+For Python-based MCP environments, use this standard structure:
+
+```
+my-environment/
+├── Dockerfile
+├── pyproject.toml
+├── README.md
+└── src/
+    └── my_module/           # Your Python package
+        ├── __init__.py
+        ├── server.py        # MCP server (Phase 2)
+        ├── setup/           # Setup functions (Phase 3)
+        ├── evaluators/      # Evaluation logic (Phase 3)
+        └── problems/        # Problem definitions (Phase 3)
+```
+
+This structure enables:
+- Clean separation of concerns
+- Easy volume mounting for development (Phase 5)
+- Standard Python packaging with `pip install -e .`
+
 • **One Dockerfile only** – no docker-compose.  
-• If you’re building a GUI environment, start from `hudpython/novnc-base:latest` instead and leave VNC configuration for later phases.
+• If you're building a GUI environment, start from `hudpython/novnc-base:latest` instead and leave VNC configuration for later phases.
 
 Checkpoint reached?  Congratulations – move on.
 
 👉 Quick sanity check: `python environments/docker_debug.py my-environment:latest` (verifies Phase 1 automatically)
 
 Need inspiration?  Skim the real Dockerfiles used in the example browser environments:
-• [`simple_browser/Dockerfile`](./simple_browser/Dockerfile)
+• [`browser/Dockerfile`](./browser/Dockerfile)
 • [`remote_browser/Dockerfile`](./remote_browser/Dockerfile)
 They follow the exact same pattern – a single file, logs to stderr, nothing fancy.
 
@@ -315,28 +338,74 @@ Those messages are displayed live on app.hud.so alongside resource graphs – pe
 
 ### 4. Live telemetry (`telemetry://live`) (Optional)
 
-Expose a resource named `telemetry://live` exactly like in `environments/simple_browser/src/hud_controller/server.py` to return live url to be displayed on app.hud.so.
+Expose a resource named `telemetry://live` exactly like in `environments/browser/src/hud_controller/server.py` to return live url to be displayed on app.hud.so.
 
 Once all of the above works you can unleash *hundreds* of concurrent agents on your new environment.
 
 ---
 
-## Phase 5 – Automated Iteration with *cursor-mcp*
+## Phase 5 – Takeoff: Automatic environment improvement with Cursor Agent
+
+To enable rapid development without constant Docker rebuilds, use the unified Dockerfile's development mode. This allows you to edit code locally and see changes immediately in the running MCP server, and use Cursor Agent to automate iteration.
+
+### Setting up Development Mode
+
+#### 1. Update Your Dockerfile
+
+First, modify your Dockerfile to support a `DEV_MODE` build argument to simplify transitioning between dev and build:
+
+```dockerfile
+# Add this at the top of your Dockerfile
+ARG DEV_MODE=false
+
+# ... your existing setup ...
 
-[`cursor-mcp`](https://github.com/hud-evals/cursor-mcp) turns the edit → build → restart → test loop into a single key-press and adds tools to Cursor Agent that can drive the whole workflow for you. The agent reads the MCP spec, your code, and the live server state, then proposes fixes or new tests on its own. It then has access to the MCP tools the environment provides, enabling it to test all functionality, which completes the iteration loop.
+# Conditionally handle source for dev mode -- this should reflect your environment structure
+RUN if [ "$DEV_MODE" = "true" ]; then \
+        mkdir -p /app/src/your_module && \
+        echo "# Stub for editable install" > /app/src/your_module/__init__.py; \
+    fi
 
-1. Add an entry to `.cursor/mcp.json`:
+# Copy source (will be overridden by volume mount in dev mode but necessary for the build in the Phase 1 recommended setup)
+COPY src/ ./src/
+
+# Install in editable mode still works!
+RUN pip install -e .
+
+# ... your existing setup ...
+```
+
+The key insight: In dev mode, we create stub files so the package can be installed, but the actual source will come from the volume mount.
+
+#### 2. Build the Development Image
+
+```bash
+docker build --build-arg DEV_MODE=true -t my-environment:dev .
+```
+
+#### 3. Configure Cursor Agent for development
+
+Add a development configuration to `.cursor/mcp.json` that includes the volume mount:
 
 ```jsonc
 {
   "mcp_config": {
-    "env": {
+    // If your production config looks like this,
+    "my-environment": {
       "command": "docker",
       "args": ["run", "--rm", "-i", "my-environment:latest"]
     },
-    "cursor-manager": {
-      "command": "uvx",
-      "args": ["cursor-mcp"]
+    // This is how you make the dev mode config:
+    "my-environment-dev": {
+      "command": "docker",
+      "args": [
+        "run", "--rm", "-i",
+        "-v", "%cd%/src:/app/src:rw",  // Windows
+        // "-v", "$(pwd)/src:/app/src:rw",  // Linux/Mac
+        "-e", "PYTHONPATH=/app/src",  // Required for module imports in the Phase 1 like setup
+        // Add your environment variables here
+        "my-environment:dev" // dev instead of latest!
+      ]
     }
   }
 }
@@ -345,36 +414,36 @@ Once all of the above works you can unleash *hundreds* of concurrent agents on y
 2. Follow the cursor rules below: rebuild, refresh, test, reflect, repeat.
 3. Keep the agent open for any messages or issues.
 
-### Cursor rules – paste this once
+### 4. Cursor rules – paste this once
 
-Inside `.cursor/rules/mcp_environment_iteration.mdc` add (or verify) the following so the agent always knows the expected loop:
+Inside `.cursor/rules/hud_environment_iteration.mdc` add (or verify) the following so the agent always knows the expected iteration loop:
 
 ```mdc
 ---
-description: When making an environment that launches and MCP server this is the iteration loop
+description: Improve an MCP environment
 alwaysApply: false
 ---
-Setting up (also refer to environments/README.md):
-1. Follow each environment's README.md or any other steps to set it up for the MCP server to be able to directly launch it (such as building the dockerfile)
-2. Run local tests to make sure the initialize without immediate errors and stays alive until properly closed. If the server crashes within the first few seconds then the manager will not pick up on it. In this case please go back and either debug the docker run directly, or the mcp server by piping an initialization request.
-3. When the server initialization is stable, use the cursor-manager tool to see the current list of tools and add it if necessary. Take note of the name.
-4. When working, tell the user to send another message to refresh your list of tools.
-
-After setting up, when iterating (will not require a user message ever):
-1. Look at the environment project and refine/edit/fix files
-2. Follow its README to set it up for the MCP server (such as building the dockerfile)
-3. Use the cursor-manager tool to refresh this server (by name)
-4. See its status using cursor-manager, if it's running then follow with step 5. If it fails, then check the logs using cursor-manager and go back to step 1, but ask the user to reset.
-5. Use the tools from that server (by name) to test the functionality and edge cases, reflect on the success of your TODOs and think of new things to fix. If the tools are unavailable but the status is running, then ask the user to refresh the user message.
-6. Review your TODOs, update with new TODOs
-7. Repeat until reached user's high level goals, or generally extremely happy with the final result
-
-In general:
-1. Try to avoid running direct docker or mcp commands and use the tools. If you want to run a docker command or python mcp server command then ask permission and only use if otherwise completely impossible.
-2. If at any point the docker build starts breaking on initialize, return to setting up properly 
+Setup
+1. Make sure the user has set up the mcp config for the environment by seeing if you have access to the tools by the given name (i.e. my-environment-dev), and make sure the title is in dev mode. If not, ask the user to make a dev version!
+2. Make sure you can find the source folder for this environment. Explore its contents and README.
+3. Clarify the objectives and ask follow up questions on the initial query to determine precise implementation details.
+
+Iteration
+1. Use the exposed tools by the environment to interact with it. This means navigating around with a computer, editing, launching commands, whatever means accessible to you. If there are any exposed resources, try to access them to determine the structure of the calls.
+2. Based on the objectives, test and verify the functionality of different tools and parts of the environment. If any tool call responds with an error, note it down. If any interaction with the environment is wrong, unexpected, incomplete, or parts of the environment are not developed fully, note it down. If any new problem sets up wrong or evaluation does not match the expected outcome, note it down. All of these inconsistencies you should note down in your TODOs.
+3. Then, based on the TODOs, view the source folder and find the places where those errors would occur. Think about the system and how to fix it. Then fix it.
+4. After you've fixed your TODO items, go back to step 2 and test them. Test through all of your available tools, and use feedback (such as screenshots) to determine your progress. If they now work as expected, mark them as complete. If not, continue the loop from step 2. Be extremely careful, scrupolous and attentive to all details. Never assume something is working unless you've tested it fully for all of its edge cases.
+5. The only time you can exit this iteration loop is if you're adding a *new* tool, a new import package to the environment, need additional environment variables, or if there is no feasible way to create input conditions to test something. In this case, ask the user for help and recap your progress. If you're simply changing tools, changing code, and still have more realistic TODOs, the environment will refresh automatically and you should continue working. In *all* other cases, you must continue this iteration loop until you can come up with no more TODOs. You must not halt.
 ```
 
-The result: fast, autonomous turnaround times even for complex GUI environments.
+### 5. Prompt the agent
+
+```txt
+Context: In the my-environment folder, I have a browser app environment. I've built a tool to interact with it called my-environment-dev.
+Interaction: There are multiple tools to setup and evaluate the environment. There are also interaction tools for you to be able to move around it, and a screenshot tool to see the state. Use all of the available tools.
+Objective: Please test if all setup, evaluation functions are working. This means you should come up with new problem definitions to test all functionality on. Be creative in how you pick edge cases to test on.
+Rules: @hud_environment_iteration.mdc
+```
 
 ---
 
@@ -411,7 +480,7 @@ class TodoBasic:
         return {"function": "todo_completed", "args": {"expected_count": 2}}
 ```
 
-Decorators keep registration *next to the implementation* and avoid manual bookkeeping.  The server simply exposes the combined metadata through an MCP **resource**.  Follow `environments/simple_browser/src/hud_controller/problems/registry.py` as a template and expose the JSON with `@mcp.resource("problems://registry")`.
+Decorators keep registration *next to the implementation* and avoid manual bookkeeping.  The server simply exposes the combined metadata through an MCP **resource**.  Follow `environments/browser/src/hud_controller/problems/registry.py` as a template and expose the JSON with `@mcp.resource("problems://registry")`.
 
 ### Other finishing touches
 

{hud_python-0.3.3/environments/simple_browser → hud_python-0.3.5/environments/browser}/.gitignore

@@ -97,4 +97,6 @@ logs/
 *.log
 
 # Docker
-.dockerignore.local 
+.dockerignore.local 
+
+gcp.json

{hud_python-0.3.3 → hud_python-0.3.5}/environments/docker_debug.py

@@ -233,6 +233,12 @@ async def debug_mcp_docker(image: str) -> None:
 
     logger.info(f"\n{Colors.BOLD}🔍 Docker MCP Server Debugger{Colors.ENDC}")
     logger.info(f"{Colors.GRAY}Image: {image}{Colors.ENDC}")
+
+    # Show extra docker args if provided
+    extra_args = getattr(__builtins__, "_docker_extra_args", [])
+    if extra_args:
+        logger.info(f"{Colors.GRAY}Extra args: {' '.join(extra_args)}{Colors.ENDC}")
+
     logger.info(f"{Colors.GRAY}Time: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}{Colors.ENDC}")
 
     # Explain color coding
@@ -253,7 +259,9 @@ async def debug_mcp_docker(image: str) -> None:
     log_phase(1, "Basic Docker Container Test")
 
     try:
-        cmd = ["docker", "run", "--rm", image, "echo", "Container OK"]
+        # Get extra docker args if provided
+        extra_args = getattr(__builtins__, "_docker_extra_args", [])
+        cmd = ["docker", "run", "--rm"] + extra_args + [image, "echo", "Container OK"]
         log_command(cmd)
 
         result = subprocess.run(cmd, capture_output=True, text=True, timeout=10)
@@ -293,7 +301,9 @@ async def debug_mcp_docker(image: str) -> None:
     }
 
     try:
-        cmd = ["docker", "run", "--rm", "-i", image]
+        # Get extra docker args if provided
+        extra_args = getattr(__builtins__, "_docker_extra_args", [])
+        cmd = ["docker", "run", "--rm", "-i"] + extra_args + [image]
         log_command(cmd)
 
         log_stdio(f"Sending: {json.dumps(init_request)}")
@@ -395,7 +405,11 @@ async def debug_mcp_docker(image: str) -> None:
     try:
         from hud.mcp import MCPClient
 
-        mcp_config = {"test": {"command": "docker", "args": ["run", "--rm", "-i", image]}}
+        # Get extra docker args if provided
+        extra_args = getattr(__builtins__, "_docker_extra_args", [])
+        mcp_config = {
+            "test": {"command": "docker", "args": ["run", "--rm", "-i"] + extra_args + [image]}
+        }
 
         cmd = ["docker"] + mcp_config["test"]["args"]
         log_command(cmd)
@@ -618,12 +632,18 @@ async def debug_mcp_docker(image: str) -> None:
 
         log_info(f"Baseline: Memory={baseline_memory:.1f}MB, CPU={baseline_cpu:.1f}%")
 
+        # Get extra docker args if provided
+        extra_args = getattr(__builtins__, "_docker_extra_args", [])
+
         # Create multiple concurrent clients
         log_info("Creating 3 concurrent MCP clients...")
 
         for i in range(3):
             client_config = {
-                f"test_concurrent_{i}": {"command": "docker", "args": ["run", "--rm", "-i", image]}
+                f"test_concurrent_{i}": {
+                    "command": "docker",
+                    "args": ["run", "--rm", "-i"] + extra_args + [image],
+                }
             }
 
             concurrent_client = MCPClient(mcp_config=client_config, verbose=False)
@@ -689,11 +709,14 @@ async def debug_mcp_docker(image: str) -> None:
 
         # Still test basic concurrent connections
         try:
+            # Get extra docker args if provided
+            extra_args = getattr(__builtins__, "_docker_extra_args", [])
+
             for i in range(3):
                 client_config = {
                     f"test_concurrent_{i}": {
                         "command": "docker",
-                        "args": ["run", "--rm", "-i", image],
+                        "args": ["run", "--rm", "-i"] + extra_args + [image],
                     }
                 }
 
@@ -734,10 +757,29 @@ async def debug_mcp_docker(image: str) -> None:
 
 
 if __name__ == "__main__":
-    if len(sys.argv) != 2:
-        print("Usage: python docker_debug.py <docker-image>")
+    import warnings
+    import gc
+
+    if len(sys.argv) < 2:
+        print("Usage: python docker_debug.py <docker-image> [docker-args...]")
         print("Example: python docker_debug.py hudpython/gmail-clone:latest")
+        print(
+            "Example: python docker_debug.py my-env:latest -e BROWSER_PROVIDER=browserbase -e API_KEY=xxx"
+        )
         sys.exit(1)
 
     docker_image = sys.argv[1]
+    docker_extra_args = sys.argv[2:] if len(sys.argv) > 2 else []
+
+    # Suppress cleanup warnings
+    warnings.filterwarnings("ignore", category=ResourceWarning)
+
+    # Store extra args globally so they can be used in docker commands
+    import builtins
+
+    setattr(builtins, "_docker_extra_args", docker_extra_args)
+
     asyncio.run(debug_mcp_docker(docker_image))
+
+    # Force cleanup to avoid warnings
+    gc.collect()

hud_python-0.3.5/environments/remote_browser/.gitignore

@@ -0,0 +1 @@
+gcp.json

hud_python-0.3.5/environments/remote_browser/Dockerfile

@@ -0,0 +1,40 @@
+# Build argument to control dev vs production mode
+ARG DEV_MODE=false
+
+# Use our HUD base browser image with Playwright and uv pre-installed
+FROM hudpython/base-browser:latest
+
+# Create app-specific working directory
+WORKDIR /app
+
+# Copy project files
+COPY pyproject.toml ./
+
+# Conditionally copy source or create stub for development
+RUN if [ "$DEV_MODE" = "true" ]; then \
+        echo "Dev mode: Creating stub for editable install" && \
+        mkdir -p /app/src/hud_controller && \
+        echo "# Stub for package installation" > /app/src/hud_controller/__init__.py; \
+    else \
+        echo "Production mode: Source will be copied"; \
+    fi
+
+# Copy source only in production mode (this is a no-op if DEV_MODE=true but doesn't hurt)
+COPY src/ ./src/ 
+
+# Install the package using the existing venv at /opt/venv
+# The --python flag tells uv to use this specific Python instead of creating a new venv
+RUN uv pip install --python /opt/venv -e .
+
+# Create directories for logs and data
+RUN mkdir -p /app/logs /app/data
+
+# Environment variables (PATH and VIRTUAL_ENV already set by base image)
+ENV PYTHONUNBUFFERED=1
+ENV LOG_LEVEL=INFO
+
+# Google Cloud Platform Credentials for Sheets functionality (here for Windows builds)
+ENV GCP_CREDENTIALS_JSON=""
+
+# Run the command directly - it's installed in /opt/venv which is in PATH
+CMD ["hud-remote-browser"]

hud_python-0.3.5/environments/remote_browser/README.md

@@ -0,0 +1,133 @@
+# HUD Remote Browser MCP Server
+
+This MCP server provides browser automation capabilities using various remote browser providers.
+
+## Running with Docker
+
+The Docker image supports both production and development modes using the same Dockerfile.
+
+### Building the Image
+
+```bash
+# Production build (default)
+docker build -t hud-remote-browser:latest .
+
+# Development build (for hot-reload with volume mounts)
+docker build --build-arg DEV_MODE=true -t hud-remote-browser:dev .
+```
+
+### Running in Production Mode
+
+```bash
+# Using AnchorBrowser
+docker run --rm -i \
+  -e BROWSER_PROVIDER=anchorbrowser \
+  -e ANCHOR_API_KEY=your-api-key \
+  hud-remote-browser:latest
+
+# Using BrowserBase
+docker run --rm -i \
+  -e BROWSER_PROVIDER=browserbase \
+  -e BROWSERBASE_API_KEY=your-api-key \
+  -e BROWSERBASE_PROJECT_ID=your-project-id \
+  hud-remote-browser:latest
+```
+
+### Running in Development Mode (Hot Reload)
+
+Development mode allows you to edit code locally and see changes immediately without rebuilding:
+
+```bash
+# Windows
+docker run --rm -i ^
+  -v "%cd%\src:/app/src:rw" ^
+  -e BROWSER_PROVIDER=anchorbrowser ^
+  -e ANCHOR_API_KEY=your-api-key ^
+  -e PYTHONPATH=/app ^
+  hud-remote-browser:dev
+
+# Linux/Mac
+docker run --rm -i \
+  -v "$(pwd)/src:/app/src:rw" \
+  -e BROWSER_PROVIDER=anchorbrowser \
+  -e ANCHOR_API_KEY=your-api-key \
+  -e PYTHONPATH=/app/src \
+  hud-remote-browser:dev
+```
+
+The `-v` flag mounts your local `src/` directory into the container, allowing instant code changes.
+
+## Supported Browser Providers
+
+- **anchorbrowser** - Requires `ANCHOR_API_KEY`
+- **browserbase** - Requires `BROWSERBASE_API_KEY` and `BROWSERBASE_PROJECT_ID`
+- **hyperbrowser** - Requires `HYPERBROWSER_API_KEY`
+- **steel** - Requires `STEEL_API_KEY`
+- **kernel** - No additional requirements
+
+## Environment Variables
+
+### Core Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `BROWSER_PROVIDER` | **Yes** | The browser provider to use |
+| `LOG_LEVEL` | No | Logging level (default: INFO) |
+
+### Provider-Specific Variables
+
+| Provider | Required Variables |
+|----------|-------------------|
+| anchorbrowser | `ANCHOR_API_KEY` |
+| browserbase | `BROWSERBASE_API_KEY`, `BROWSERBASE_PROJECT_ID` |
+| hyperbrowser | `HYPERBROWSER_API_KEY` |
+| steel | `STEEL_API_KEY` |
+
+### Optional Browser Settings
+
+| Variable | Description |
+|----------|-------------|
+| `HEADLESS` | Whether to run browser in headless mode |
+| `DEFAULT_TIMEOUT` | Default timeout for browser operations |
+| `WINDOW_WIDTH` | Browser window width |
+| `WINDOW_HEIGHT` | Browser window height |
+| `PROXY_URL` | HTTP proxy URL |
+
+### Google Cloud Platform (GCP) Credentials
+
+For Google Sheets functionality, you can provide GCP credentials in two formats:
+
+**Option A: Single JSON String**
+```bash
+-e GCP_CREDENTIALS_JSON='{"type":"service_account","project_id":"...","private_key":"..."}'
+```
+
+**Option B: Individual Fields**
+```bash
+-e GCP_TYPE="service_account" \
+-e GCP_PROJECT_ID="your-project-id" \
+-e GCP_PRIVATE_KEY_ID="your-key-id" \
+-e GCP_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n..." \
+-e GCP_CLIENT_EMAIL="your-service-account@project.iam.gserviceaccount.com" \
+-e GCP_CLIENT_ID="your-client-id" \
+-e GCP_AUTH_URI="https://accounts.google.com/o/oauth2/auth" \
+-e GCP_TOKEN_URI="https://oauth2.googleapis.com/token" \
+-e GCP_AUTH_PROVIDER_X509_CERT_URL="https://www.googleapis.com/oauth2/v1/certs" \
+-e GCP_CLIENT_X509_CERT_URL="https://www.googleapis.com/robot/v1/metadata/x509/..."
+```
+
+## MCP Protocol
+
+The server communicates via stdio using the MCP protocol. Example initialization:
+
+```bash
+echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {...}}' | \
+  docker run --rm -i -e BROWSER_PROVIDER=steel -e STEEL_API_KEY=... hud-remote-browser:latest
+```
+
+## Error Handling
+
+If `BROWSER_PROVIDER` is not set, the server will fail with:
+```
+BROWSER_PROVIDER environment variable is required. Supported providers: anchorbrowser, steel, browserbase, hyperbrowser, kernel
+```

{hud_python-0.3.3 → hud_python-0.3.5}/environments/remote_browser/pyproject.toml

@@ -4,7 +4,8 @@ version = "0.1.0"
 description = "HUD Remote Browser Controller with MCP tools for cloud browser providers"
 requires-python = ">=3.11,<3.13"
 dependencies = [
-    "hud-python",
+    "hud-python>=0.3.2",
+    "pyautogui",
     "playwright",
     "httpx",
     "typer",