Merge pull request #184 from meta-pytorch/add-browsergym-example

[ENHANCEMENT] BrowserGym Env

Author: burtenshaw

examples/browsergym_example.py

@@ -1,16 +1,14 @@
 """BrowserGym MiniWoB example with Qwen deciding the next action.
 
-This is an inference example for the BrowserGym environment. It uses the OpenAI 
-client and a vision language model to decide the next action. We use Hugging Face 
-Inference Providers API to access the model, but you can use any other provider that 
+This is an inference example for the BrowserGym environment. It uses the OpenAI
+client and a vision language model to decide the next action. We use Hugging Face
+Inference Providers API to access the model, but you can use any other provider that
 is compatible with the OpenAI API.
 
 Prerequisites:
-- Clone the MiniWoB++ tasks repository.
-- Serve the HTML bundle with `python -m http.server 8888` inside the
-  `miniwob-plusplus/miniwob/html` directory.
-- Export the MiniWoB URL (must include the `/miniwob/` suffix):
-    `export MINIWOB_URL=http://host.docker.internal:8888/miniwob/`
+- (Optional) Export the MiniWoB URL if you are hosting the tasks yourself
+  (must include the `/miniwob/` suffix); the BrowserGym Docker image now
+  serves the MiniWoB bundle internally on port 8888.
 - Export your Hugging Face token for the router:
     `export HF_TOKEN=your_token_here`
 
@@ -99,10 +97,12 @@ def extract_clickable_elements(observation) -> List[Dict[str, str]]:
 
         bbox = props.get("bbox") or []
         bbox_str = ", ".join(bbox) if bbox else "?"
-        clickables.append({
-            "bid": str(bid),
-            "bbox": bbox_str,
-        })
+        clickables.append(
+            {
+                "bid": str(bid),
+                "bbox": bbox_str,
+            }
+        )
 
     # Keep a stable ordering for readability
     clickables.sort(key=lambda item: item["bid"])
@@ -170,18 +170,16 @@ def parse_model_action(response_text: str) -> str:
 
 
 def main() -> None:
-
     client = OpenAI(base_url=API_BASE_URL, api_key=API_KEY)
 
-    env = BrowserGymEnv.from_hub(
-        "browsergym-env:latest",
+    env = BrowserGymEnv.from_docker_image(
+        image="browsergym-env:latest",
         env_vars={
             "BROWSERGYM_BENCHMARK": "miniwob",
             "BROWSERGYM_TASK_NAME": "click-test",
         },
-        ports={8000: 8000},
     )
-    
+
     history: List[str] = []
 
     try:
@@ -227,9 +225,7 @@ def main() -> None:
                 response_text = completion.choices[0].message.content or ""
             # pylint: disable=broad-except
             except Exception as exc:  # noqa: BLE001
-                failure_msg = (
-                    f"Model request failed ({exc}). Using fallback action."
-                )
+                failure_msg = f"Model request failed ({exc}). Using fallback action."
                 print(failure_msg)
                 response_text = FALLBACK_ACTION
 
@@ -242,8 +238,7 @@ def main() -> None:
             reward = result.reward or 0.0
             error_flag = " ERROR" if observation.last_action_error else ""
             history_line = (
-                f"Step {step}: {action_str} -> reward {reward:+.2f}"
-                f"{error_flag}"
+                f"Step {step}: {action_str} -> reward {reward:+.2f}{error_flag}"
             )
             history.append(history_line)
             print(

src/envs/browsergym_env/server/Dockerfile

@@ -37,21 +37,29 @@ RUN pip install --no-cache-dir -r /tmp/browsergym_requirements.txt && \
 # Install Playwright browsers (Chromium by default)
 RUN playwright install chromium
 
+# Install MiniWoB++ tasks
+RUN pip install browsergym-miniwob
+RUN git clone --depth 1 https://github.com/Farama-Foundation/miniwob-plusplus.git /app/miniwob-plusplus
+
 # Copy OpenEnv core and browsergym_env code
 WORKDIR /app
 COPY src/core/ /app/src/core/
 COPY src/envs/browsergym_env/ /app/src/envs/browsergym_env/
 COPY src/envs/browsergym_env/README.md /app/README.md
+RUN chmod +x /app/src/envs/browsergym_env/server/start.sh
 
 # Set environment variables
 ENV PYTHONPATH=/app/src
 ENV PYTHONUNBUFFERED=1
 ENV BROWSERGYM_BENCHMARK=miniwob
-ENV BROWSERGYM_TASK_NAME=""
+ENV BROWSERGYM_TASK_NAME="click-test"
 ENV BROWSERGYM_HEADLESS=true
 ENV BROWSERGYM_VIEWPORT_WIDTH=1280
 ENV BROWSERGYM_VIEWPORT_HEIGHT=720
 ENV BROWSERGYM_TIMEOUT=10000
+ENV MINIWOB_HTML_DIR=/app/miniwob-plusplus/miniwob/html
+ENV MINIWOB_HTTP_PORT=8888
+ENV MINIWOB_URL=http://127.0.0.1:8888/miniwob/
 
 # For WebArena tasks, these should be set by the user when running the container:
 # ENV SHOPPING=
@@ -63,8 +71,9 @@ ENV BROWSERGYM_TIMEOUT=10000
 # ENV HOMEPAGE=
 
 EXPOSE 8000
+EXPOSE 8888
 
 HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
     CMD curl -f http://localhost:8000/health || exit 1
 
-CMD ["uvicorn", "envs.browsergym_env.server.app:app", "--host", "0.0.0.0", "--port", "8000"]
+CMD ["/app/src/envs/browsergym_env/server/start.sh"]

src/envs/browsergym_env/server/app.py

@@ -16,6 +16,7 @@
 viewport_width = int(os.environ.get("BROWSERGYM_VIEWPORT_WIDTH", "1280"))
 viewport_height = int(os.environ.get("BROWSERGYM_VIEWPORT_HEIGHT", "720"))
 timeout = float(os.environ.get("BROWSERGYM_TIMEOUT", "10000"))
+port = int(os.environ.get("BROWSERGYM_PORT", "8000"))
 
 # Create the environment instance
 env = BrowserGymEnvironment(
@@ -38,4 +39,4 @@
 if __name__ == "__main__":
     import uvicorn
 
-    uvicorn.run(app, host="0.0.0.0", port=8000)
+    uvicorn.run(app, host="0.0.0.0", port=port)

src/envs/browsergym_env/server/browsergym_environment.py

@@ -9,6 +9,7 @@
 """
 
 import importlib
+import os
 from typing import Any, Dict, Optional
 from uuid import uuid4
 
@@ -22,6 +23,17 @@
 )
 
 
+_MINIWOB_LOAD_HELP = (
+    "MiniWoB tasks require the MiniWoB HTML bundle to be served over HTTP. "
+    "The official BrowserGym Docker image handles this automatically by "
+    "serving the bundle on port 8888. For custom or non-Docker deployments, "
+    "clone the MiniWoB++ repository, start a static server inside "
+    "`miniwob-plusplus/miniwob/html` (e.g. `python -m http.server 8888`), and "
+    "set the MINIWOB_URL environment variable to the served base URL such as "
+    "`http://localhost:8888/miniwob/`."
+)
+
+
 class BrowserGymEnvironment(Environment):
     """BrowserGym environment wrapper for OpenEnv.
 
@@ -59,7 +71,7 @@ def __init__(
         self.viewport_width = viewport_width
         self.viewport_height = viewport_height
         self.timeout = timeout
-        self.gym_kwargs = gym_kwargs
+        self.gym_kwargs = dict(gym_kwargs)
 
         # Build environment ID
         if task_name:
@@ -69,10 +81,10 @@ def __init__(
 
         # force import the benchmark module
         benchmark_modules = {
-            "miniwob": "browsergym.envs.miniwob",
-            "webarena": "browsergym.envs.webarena",
-            "visualwebarena": "browsergym.envs.visualwebarena",
-            "workarena": "browsergym.envs.workarena",
+            "miniwob": "browsergym.miniwob",
+            "webarena": "browsergym.webarena",
+            "visualwebarena": "browsergym.visualwebarena",
+            "workarena": "browsergym.workarena",
         }
         module_path = benchmark_modules.get(benchmark)
         try:
@@ -81,10 +93,13 @@ def __init__(
             else:
                 importlib.import_module("browsergym")
         except ModuleNotFoundError as import_error:
-            raise ValueError(
-                f"Failed to import BrowserGym benchmark '{benchmark}': {import_error}\n"
-                f"Make sure the package browsergym-{benchmark} is installed."
-            ) from import_error
+            message = (
+                "Failed to import BrowserGym benchmark "
+                f"'{benchmark}': {import_error}\n"
+                "Install the matching browsergym package "
+                f"(e.g., browsergym-{benchmark})."
+            )
+            raise ValueError(message) from import_error
 
         # Create the BrowserGym environment
         try:
@@ -93,13 +108,16 @@ def __init__(
                 headless=headless,
                 viewport={"width": viewport_width, "height": viewport_height},
                 timeout=timeout,
-                **gym_kwargs,
+                **self.gym_kwargs,
             )
-        except Exception as e:
-            raise ValueError(
-                f"Failed to create BrowserGym environment '{self.env_id}': {e}\n"
-                f"Make sure the benchmark is installed (e.g., pip install browsergym-{benchmark})"
+        except Exception as e:  # noqa: BLE001 - gym.make
+            message = (
+                "Failed to create BrowserGym environment "
+                f"'{self.env_id}': {e}\n"
+                "Make sure the benchmark package is installed "
+                f"(e.g., pip install browsergym-{benchmark})."
             )
+            raise ValueError(message) from e
 
         # State tracking
         self._state = BrowserGymState(
@@ -140,7 +158,21 @@ def reset(
             reset_options["seed"] = seed
 
         # Reset the gym environment
-        obs, info = self.gym_env.reset(**reset_options)
+        try:
+            obs, info = self.gym_env.reset(**reset_options)
+        except AttributeError as err:
+            if "context" in str(err) and hasattr(self.gym_env, "close"):
+                # BrowserGym can leave partially initialized state after a
+                # failed reset. Close the hanging resources and try once more.
+                self.gym_env.close()
+                obs, info = self.gym_env.reset(**reset_options)
+            else:
+                raise
+        except Exception as err:  # noqa: BLE001 - browsergym
+            message = str(err)
+            if self.benchmark == "miniwob" and "core is not defined" in message:
+                raise ValueError(_MINIWOB_LOAD_HELP) from err
+            raise
 
         self._last_obs = obs
         self._last_info = info

src/envs/browsergym_env/server/start.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+MINIWOB_HTML_DIR=${MINIWOB_HTML_DIR:-/app/miniwob-plusplus/miniwob/html}
+MINIWOB_HTTP_PORT=${MINIWOB_HTTP_PORT:-8888}
+BROWSERGYM_PORT=${BROWSERGYM_PORT:-8000}
+
+if [ ! -d "${MINIWOB_HTML_DIR}" ]; then
+    echo "MiniWoB HTML directory not found at ${MINIWOB_HTML_DIR}" >&2
+    exit 1
+fi
+
+python -m http.server "${MINIWOB_HTTP_PORT}" --bind 0.0.0.0 --directory "${MINIWOB_HTML_DIR}" &
+HTTP_SERVER_PID=$!
+
+sleep 1
+if ! kill -0 "${HTTP_SERVER_PID}" 2>/dev/null; then
+    echo "Failed to start MiniWoB static server on port ${MINIWOB_HTTP_PORT}" >&2
+    exit 1
+fi
+
+cleanup() {
+    kill "${HTTP_SERVER_PID}" 2>/dev/null || true
+}
+
+trap cleanup EXIT INT TERM
+
+exec uvicorn envs.browsergym_env.server.app:app --host 0.0.0.0 --port "${BROWSERGYM_PORT}"
+