- openenv¶

TextArena Environment¶

An OpenEnv wrapper for TextArena game environments. Supports text-based games like Wordle, providing a standardized API for agent interaction.

[!NOTE] Generic wrapper for any TextArena game inside OpenEnv. This module exposes the TextArena Env interface through the standard HTTP server/client APIs used by other OpenEnv environments, enabling quick experimentation with the full suite of word, reasoning, and multi-agent games.

Quick Start¶

The simplest way to use the TextArena environment is through the TextArenaEnv class:

from textarena_env import TextArenaAction, TextArenaEnv

try:
    # Create environment from Docker image
    env = TextArenaEnv.from_docker_image("textarena-env:latest")

    # Reset to start a new episode
    result = env.reset()
    print(f"Game prompt:\n{result.observation.prompt}")

    # Play a few turns (example: Wordle guesses)
    guesses = ["[crane]", "[slate]", "[audio]"]

    for guess in guesses:
        result = env.step(TextArenaAction(message=guess))

        # Check messages for feedback
        for message in result.observation.messages:
            print(f"Response: {message.content}")

        print(f"Reward: {result.reward}")
        print(f"Done: {result.done}")

        if result.done:
            break

finally:
    # Always clean up
    env.close()

That's it! The TextArenaEnv.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 textarena_env directory
cd envs/textarena_env
docker build -t textarena-env:latest -f server/Dockerfile .

Testing the Gradio UI locally¶

With the web interface enabled, the server serves a Gradio UI at /web. If your openenv-core supports gradio_builder, you get two tabs (see Customizing the Web UI):

Playground – default OpenEnv UI (Reset, Step, Get state, Quick Start, README).
Custom – Wordle-style HTML block (see server/gradio_ui.py; uses Gradio 6 gr.HTML to render the block).

Option A – From the OpenEnv repo root (recommended for the Custom tab)

Use the core that includes the tabbed interface and custom builder:

cd envs/textarena_env
ENABLE_WEB_INTERFACE=true PYTHONPATH=../../src uv run uvicorn server.app:app --host 0.0.0.0 --port 8000

Option B – From the environment directory only

cd envs/textarena_env
ENABLE_WEB_INTERFACE=true uv run server

Or:

ENABLE_WEB_INTERFACE=true uv run uvicorn server.app:app --host 0.0.0.0 --port 8000

Then open http://localhost:8000/web. Use the Playground tab to Reset and Step with guesses (e.g. [crane], [stone]). If you ran with Option A, the Custom tab shows the Wordle-style demo block.

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>

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¶

TextArenaAction: Contains a single field - message (str) - The message/action to send to the game

Observation¶

TextArenaObservation: Contains the game state and response

prompt (str) - Game instructions and context
messages (List[TextArenaMessage]) - Conversation history with the game
current_player_id (int) - ID of the current player
legal_players (List[int]) - List of valid player IDs
info (Dict) - Additional game metadata
reward (float) - Reward for the current step (inherited from Observation)
done (bool) - Whether the episode has ended (inherited from Observation)

TextArenaMessage¶

Each message in the conversation has:

sender_id (int) - ID of the message sender
content (str) - The message content
category (str) - Message type (e.g., "PROMPT", "MESSAGE")

State¶

TextArenaState: Server-side state snapshot

episode_id (str) - Unique identifier for the current episode
step_count (int) - Number of steps taken in the current episode
env_id (str) - The TextArena environment ID (e.g., "Wordle-v0")
num_players (int) - Number of players in the game
max_turns (Optional[int]) - Maximum turns allowed
turn (int) - Current turn number
last_reward (float) - Most recent reward
last_info (Dict) - Most recent info dictionary
raw_state (Dict) - Raw TextArena state snapshot

Reward¶

Rewards are determined by the underlying TextArena game. For example: - Wordle-v0: Positive reward for winning, includes reward signals for green/yellow letter matches

Advanced Usage¶

Connecting to an Existing Server¶

If you already have a TextArena environment server running, you can connect directly:

from textarena_env import TextArenaEnv, TextArenaAction

# Connect to existing server
env = TextArenaEnv(base_url="<ENV_HTTP_URL_HERE>")

# Use as normal
result = env.reset()
result = env.step(TextArenaAction(message="[crane]"))

# Close connection (does NOT stop the server)
env.close()

Environment Configuration¶

The server supports configuration via environment variables:

TEXTARENA_ENV_ID - Game to load (default: "Wordle-v0")
TEXTARENA_NUM_PLAYERS - Number of players (default: 1)
TEXTARENA_MAX_TURNS - Maximum turns per episode
TEXTARENA_DOWNLOAD_NLTK - Download NLTK data (default: "1")
TEXTARENA_KW_* - Pass additional kwargs to TextArena (e.g., TEXTARENA_KW_difficulty=hard)

Development & Testing¶

Direct Environment Testing¶

Test the environment logic directly without starting the HTTP server:

from textarena_env.server.environment import TextArenaEnvironment
from textarena_env.models import TextArenaAction

# Create environment directly
env = TextArenaEnvironment(env_id="Wordle-v0", num_players=1)

# Test reset
obs = env.reset()
print(f"Prompt: {obs.prompt}")

# Test step
obs = env.step(TextArenaAction(message="[crane]"))
print(f"Done: {obs.done}, Reward: {obs.reward}")

Running Locally¶

Run the server locally for development:

# Install dependencies
uv venv && source .venv/bin/activate
uv pip install -e .

# Start the server
python -m uvicorn server.app:app --reload

Or using the CLI entry point:

uv run --project . server --port 8000

Project Structure¶

textarena_env/
├── __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              # TextArenaEnv client implementation
├── models.py              # Action, Observation, and State models
├── rewards.py             # Reward provider utilities
└── server/
    ├── __init__.py        # Server module exports
    ├── environment.py     # Core TextArenaEnvironment implementation
    ├── app.py             # FastAPI application
    └── Dockerfile         # Container image definition