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 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:

   export SERPER_API_KEY="your-api-key-here"
   

   For Docker:

   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:

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:

# From the websearch_env directory
cd envs/websearch_env
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:

# 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

# 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 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:

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:

# 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:

# 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