Merge pull request #181 from Lawhy/search_env

[New Env] Add web search env with Google Search (via Serper api)

Author: burtenshaw

docs/environments.md

@@ -203,6 +203,25 @@ The OpenEnv community has built a catalog of ready-to-run environments that cove
     </div>
   </div>
 
+  <div class="environment-card">
+    <div class="environment-card__body">
+      <span class="environment-card__tag">Web Search</span>
+      <p class="environment-card__description">
+        Web search environment for RL research with configurable grids, partial observability, and customizable rewards.
+      </p>
+    </div>
+    <div class="environment-card__links">
+      <a class="environment-card__icon" href="/OpenEnv/environments/websearch/" aria-label="Web Search docs">
+        <svg viewBox="0 0 24 24" aria-hidden="true" focusable="false">
+          <path d="M6 3c-1.1 0-2 .9-2 2v14c0 1.1.9 2 2 2h12c1.1 0 2-.9 2-2V9l-6-6H6zm8 1.5L18.5 9H14V4.5z" fill="currentColor"/>
+        </svg>
+      </a>
+      <a class="environment-card__icon environment-card__icon--hf" href="https://huggingface.co/spaces/lawhy/web_search" target="_blank" rel="noreferrer noopener" aria-label="Web Search on Hugging Face">
+        <img src="https://huggingface.co/front/assets/huggingface_logo-noborder.svg" alt="" aria-hidden="true" />
+      </a>
+    </div>
+  </div>
+
 </div>
 
 > Want to publish your own environment? Head over to the [Build Your Own Environment](environment-builder.md) guide for a step-by-step walkthrough.

docs/environments/websearch.md

@@ -0,0 +1,2 @@
+--8<-- "../../src/envs/websearch_env/README.md"
+

src/envs/websearch_env/README.md

@@ -0,0 +1,235 @@
+---
+title: Web Search Environment Server
+emoji: 📡
+colorFrom: red
+colorTo: pink
+sdk: docker
+pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
+---
+
+# Web Search Environment
+
+A web search environment that searches the web with Google Search API (via Serper.dev).
+
+## Prerequisites
+
+### API Key Setup
+
+This environment requires a Serper.dev API key to function. 
+
+1. **Get your API Key:**
+   - Visit [Serper.dev](https://serper.dev/) and sign up for an account
+   - Navigate to your dashboard to get your API key
+   - Free tier includes 2,500 free searches
+
+2. **Configure the API Key:**
+
+   **For Local Development:**
+   ```bash
+   export SERPER_API_KEY="your-api-key-here"
+   ```
+
+   **For Docker:**
+   ```bash
+   docker run -e SERPER_API_KEY="your-api-key-here" web_search-env:latest
+   ```
+
+   **For Hugging Face Spaces (after deployment):**
+   - Navigate to your Space's settings page: `https://huggingface.co/spaces/USERNAME/SPACE_NAME/settings`
+   - Scroll to the "Repository secrets" section
+   - Click "New secret"
+   - Name: `SERPER_API_KEY`
+   - Value: Your Serper.dev API key
+   - Click "Add"
+   - The Space will automatically restart and use your API key
+
+   > **Important:** Never commit your API key to code. Always use environment variables or secrets management.
+
+## Quick Start
+
+The simplest way to use the Web Search environment is through the `WebSearchEnvironment` class:
+
+```python
+from envs.websearch_env.server.websearch_env_environment import WebSearchEnvironment
+from envs.websearch_env import WebSearchAction
+
+try:
+    # Create environment from Docker image
+    web_search_env = WebSearchEnvironment.from_docker_image("web_search-env:latest")
+
+    # Reset
+    result = web_search_env.reset()
+    print(f"Reset: {result.observation.content}")
+
+    # Send a search query
+    query = "What is the capital of China?"
+
+    result = web_search_env.step(WebSearchAction(query=query))
+    print(f"Formatted search result:", result.observation.content)
+    print(f"Individual web contents:", result.observation.web_contents)
+
+finally:
+    # Always clean up
+    web_search_env.close()
+```
+
+That's it! The `WebSearchEnvironment.from_docker_image()` method handles:
+- Starting the Docker container
+- Waiting for the server to be ready
+- Connecting to the environment
+- Container cleanup when you call `close()`
+
+## Building the Docker Image
+
+Before using the environment, you need to build the Docker image:
+
+```bash
+# From project root
+docker build -t web_search-env:latest -f server/Dockerfile .
+```
+
+## Deploying to Hugging Face Spaces
+
+You can easily deploy your OpenEnv environment to Hugging Face Spaces using the `openenv push` command:
+
+```bash
+# From the environment directory (where openenv.yaml is located)
+openenv push
+
+# Or specify options
+openenv push --namespace my-org --private
+```
+
+The `openenv push` command will:
+1. Validate that the directory is an OpenEnv environment (checks for `openenv.yaml`)
+2. Prepare a custom build for Hugging Face Docker space (enables web interface)
+3. Upload to Hugging Face (ensuring you're logged in)
+
+### Prerequisites
+
+- Authenticate with Hugging Face: The command will prompt for login if not already authenticated
+
+### Options
+
+- `--directory`, `-d`: Directory containing the OpenEnv environment (defaults to current directory)
+- `--repo-id`, `-r`: Repository ID in format 'username/repo-name' (defaults to 'username/env-name' from openenv.yaml)
+- `--base-image`, `-b`: Base Docker image to use (overrides Dockerfile FROM)
+- `--private`: Deploy the space as private (default: public)
+
+### Examples
+
+```bash
+# Push to your personal namespace (defaults to username/env-name from openenv.yaml)
+openenv push
+
+# Push to a specific repository
+openenv push --repo-id my-org/my-env
+
+# Push with a custom base image
+openenv push --base-image ghcr.io/meta-pytorch/openenv-base:latest
+
+# Push as a private space
+openenv push --private
+
+# Combine options
+openenv push --repo-id my-org/my-env --base-image custom-base:latest --private
+```
+
+After deployment, your space will be available at:
+`https://huggingface.co/spaces/<repo-id>`
+
+**⚠️ Important: Configure your API key!**
+After deployment, you must add your Serper.dev API key as a secret in the Space settings (see [API Key Setup](#api-key-setup) above). The environment will not work without it.
+
+The deployed space includes:
+- **Web Interface** at `/web` - Interactive UI for exploring the environment
+- **API Documentation** at `/docs` - Full OpenAPI/Swagger interface
+- **Health Check** at `/health` - Container health monitoring
+
+## Environment Details
+
+### Action
+**WebSearchAction**: Contains a single field
+- `query` (str) - The query to search for
+- `temp_api_key` (str) - Temporary Serper.dev API key if not set in envrionment variables.
+
+### Observation
+**WebSearchObservation**: Contains the echo response and metadata
+- `content` (str) - The formatted prompt that aggregates both query and web contents
+- `web_contents` (list) - List of web contents for top ranked web pages
+- `reward` (float) - Reward is not defined in this scenario
+- `done` (bool) - Always False for search environment
+- `metadata` (dict) - Additional info like step count
+
+### Reward
+The reward is undefined here.
+
+## Advanced Usage
+
+### Connecting to an Existing Server
+
+If you already have a Web Search environment server running, you can connect directly:
+
+```python
+from envs.websearch_env import WebSearchEnvironment
+
+# Connect to existing server
+web_search_env = WebSearchEnvironment(base_url="<ENV_HTTP_URL_HERE>")
+
+# Use as normal
+result = web_search_env.reset()
+result = web_search_env.step(WebSearchAction(query="What is the capital of China?"))
+```
+
+Note: When connecting to an existing server, `web_search_env.close()` will NOT stop the server.
+
+## Development & Testing
+
+### Direct Environment Testing
+
+Test the environment logic directly without starting the HTTP server:
+
+```bash
+# From the server directory
+python3 server/web_search_environment.py
+```
+
+This verifies that:
+- Environment resets correctly
+- Step executes actions properly
+- State tracking works
+- Rewards are calculated correctly
+
+### Running Locally
+
+Run the server locally for development:
+
+```bash
+# Make sure to set your API key first
+export SERPER_API_KEY="your-api-key-here"
+
+# Then run the server
+uvicorn server.app:app --reload
+```
+
+## Project Structure
+
+```
+web_search/
+├── __init__.py            # Module exports
+├── README.md              # This file
+├── openenv.yaml           # OpenEnv manifest
+├── pyproject.toml         # Project metadata and dependencies
+├── uv.lock                # Locked dependencies (generated)
+├── client.py              # WebSearchEnv client implementation
+├── models.py              # Action and Observation models
+└── server/
+    ├── __init__.py        # Server module exports
+    ├── websearch_env_environment.py  # Core environment logic
+    ├── app.py             # FastAPI application
+    └── Dockerfile         # Container image definition
+```

src/envs/websearch_env/__init__.py

@@ -0,0 +1,12 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""WebSearch Env Environment - A web search environment that uses Google Search API (via Serper.dev)."""
+
+from .client import WebSearchEnv
+from .models import WebSearchAction, WebSearchObservation
+
+__all__ = ["WebSearchAction", "WebSearchObservation", "WebSearchEnv"]

src/envs/websearch_env/client.py

@@ -0,0 +1,98 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+WebSearch Env Environment HTTP Client.
+
+This module provides the client for connecting to a WebSearch Env Environment server
+over HTTP.
+"""
+
+from typing import Dict
+
+from openenv_core.client_types import StepResult
+from openenv_core.env_server.types import State
+from openenv_core.http_env_client import HTTPEnvClient
+
+from .models import WebSearchAction, WebSearchObservation
+
+
+class WebSearchEnv(HTTPEnvClient[WebSearchAction, WebSearchObservation]):
+    """
+    HTTP client for the WebSearch Env Environment.
+
+    This client connects to a WebSearchEnvironment HTTP server and provides
+    methods to interact with it: reset(), step(), and state access.
+
+    Example:
+        >>> # Connect to a running server
+        >>> client = WebSearchEnv(base_url="http://localhost:8000")
+        >>> result = client.reset()
+        >>> print(result.observation.echoed_message)
+        >>>
+        >>> # Send a message
+        >>> result = client.step(WebSearchAction(message="Hello!"))
+        >>> print(result.observation.echoed_message)
+        >>> print(result.reward)
+
+    Example with Docker:
+        >>> # Automatically start container and connect
+        >>> client = WebSearchEnv.from_docker_image("WebSearch_env-env:latest")
+        >>> result = client.reset()
+        >>> result = client.step(WebSearchAction(message="Test"))
+    """
+
+    def _step_payload(self, action: WebSearchAction) -> Dict:
+        """
+        Convert WebSearchAction to JSON payload for step request.
+
+        Args:
+            action: WebSearchAction instance
+
+        Returns:
+            Dictionary representation suitable for JSON encoding
+        """
+        return {
+            "query": action.query,
+        }
+
+    def _parse_result(self, payload: Dict) -> StepResult[WebSearchObservation]:
+        """
+        Parse server response into StepResult[WebSearchObservation].
+
+        Args:
+            payload: JSON response from server
+
+        Returns:
+            StepResult with WebSearchObservation
+        """
+        obs_data = payload.get("observation", {})
+        observation = WebSearchObservation(
+            content=obs_data.get("content", ""),
+            web_contents=obs_data.get("web_contents", []),
+            metadata=obs_data.get("metadata", {}),
+        )
+
+        return StepResult(
+            observation=observation,
+            reward=payload.get("reward"),
+            done=payload.get("done", False),
+        )
+
+    def _parse_state(self, payload: Dict) -> State:
+        """
+        Parse server response into State object.
+
+        Args:
+            payload: JSON response from /state endpoint
+
+        Returns:
+            State object with episode_id and step_count
+        """
+        return State(
+            episode_id=payload.get("episode_id"),
+            step_count=payload.get("step_count", 0),
+        )