Upload folder using huggingface_hub

Dockerfile

@@ -17,7 +17,6 @@ WORKDIR /app
 
 # Build argument to control whether we're building standalone or in-repo
 ARG BUILD_MODE=in-repo
-ARG ENV_NAME=textarena
 
 # Copy environment code (always at root of build context)
 COPY . /app/env
@@ -33,16 +32,14 @@ RUN if ! command -v uv >/dev/null 2>&1; then \
         mv /root/.local/bin/uvx /usr/local/bin/uvx; \
     fi
 
-# Install system libraries required by TextArena (cv2 needs libGL, glib)
-# Also install git for building from git repos
+# Install git for building from git repos (build-time only)
 RUN apt-get update && apt-get install -y --no-install-recommends \
-    libgl1 \
-    libglib2.0-0 \
     git \
     && rm -rf /var/lib/apt/lists/*
-    
+
 # Install dependencies using uv sync
-# If uv.lock exists, use it; otherwise resolve on the fly
+# First pass: install dependencies without the project (for better caching)
+# Second pass: install the project itself
 RUN --mount=type=cache,target=/root/.cache/uv \
     if [ -f uv.lock ]; then \
         uv sync --frozen --no-install-project --no-editable; \
@@ -62,6 +59,12 @@ FROM ${BASE_IMAGE}
 
 WORKDIR /app
 
+# Install runtime system libraries required by TextArena (cv2 needs libGL, glib)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libgl1 \
+    libglib2.0-0 \
+    && rm -rf /var/lib/apt/lists/*
+
 # Copy the virtual environment from builder
 COPY --from=builder /app/env/.venv /app/.venv
 
@@ -74,9 +77,9 @@ ENV PATH="/app/.venv/bin:$PATH"
 # Set PYTHONPATH so imports work correctly
 ENV PYTHONPATH="/app/env:$PYTHONPATH"
 
-# Health check
+# Health check using Python (more portable than curl/wget)
 HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
-    CMD curl -f http://localhost:8000/health || exit 1
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')" || exit 1
 
 # Run the FastAPI server
 # The module path is constructed to work with the /app/env structure

README.md

@@ -13,36 +13,45 @@ tags:
 
 # TextArena Environment
 
-A simple test environment that echoes back messages. Perfect for testing the env APIs as well as demonstrating environment usage patterns.
+An OpenEnv wrapper for [TextArena](https://github.com/textarena/textarena) game environments. Supports text-based games like Wordle, providing a standardized API for agent interaction.
+
+> [!NOTE]
+> Generic wrapper for any [TextArena](https://www.textarena.ai/docs/overview) 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:
 
 ```python
-from textarena import TextArenaAction, TextArenaEnv
+from textarena_env import TextArenaAction, TextArenaEnv
 
 try:
     # Create environment from Docker image
-    textarenaenv = TextArenaEnv.from_docker_image("textarena-env:latest")
+    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))
 
-    # Reset
-    result = textArenaEnv.reset()
-    print(f"Reset: {result.observation.echoed_message}")
+        # Check messages for feedback
+        for message in result.observation.messages:
+            print(f"Response: {message.content}")
 
-    # Send multiple messages
-    messages = ["Hello, World!", "Testing echo", "Final message"]
+        print(f"Reward: {result.reward}")
+        print(f"Done: {result.done}")
 
-    for msg in messages:
-        result = textArenaEnv.step(TextArenaAction(message=msg))
-        print(f"Sent: '{msg}'")
-        print(f"  → Echoed: '{result.observation.echoed_message}'")
-        print(f"  → Length: {result.observation.message_length}")
-        print(f"  → Reward: {result.reward}")
+        if result.done:
+            break
 
 finally:
     # Always clean up
-    textArenaEnv.close()
+    env.close()
 ```
 
 That's it! The `TextArenaEnv.from_docker_image()` method handles:
@@ -118,22 +127,48 @@ The deployed space includes:
 ## Environment Details
 
 ### Action
+
 **TextArenaAction**: Contains a single field
-- `message` (str) - The message to echo back
+- `message` (str) - The message/action to send to the game
 
 ### Observation
-**TextArenaObservation**: Contains the echo response and metadata
-- `echoed_message` (str) - The message echoed back
-- `message_length` (int) - Length of the message
-- `reward` (float) - Reward based on message length (length × 0.1)
-- `done` (bool) - Always False for echo environment
-- `metadata` (dict) - Additional info like step count
+
+**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
-The reward is calculated as: `message_length × 0.1`
-- "Hi" → reward: 0.2
-- "Hello, World!" → reward: 1.3
-- Empty message → reward: 0.0
+
+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
 
@@ -142,17 +177,28 @@ The reward is calculated as: `message_length × 0.1`
 If you already have a TextArena environment server running, you can connect directly:
 
 ```python
-from textarena import TextArenaEnv
+from textarena_env import TextArenaEnv, TextArenaAction
 
 # Connect to existing server
-textarenaenv = TextArenaEnv(base_url="<ENV_HTTP_URL_HERE>")
+env = TextArenaEnv(base_url="<ENV_HTTP_URL_HERE>")
 
 # Use as normal
-result = textarenaenv.reset()
-result = textarenaenv.step(TextArenaAction(message="Hello!"))
+result = env.reset()
+result = env.step(TextArenaAction(message="[crane]"))
+
+# Close connection (does NOT stop the server)
+env.close()
 ```
 
-Note: When connecting to an existing server, `textarenaenv.close()` will NOT stop the server.
+### 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
 
@@ -160,16 +206,21 @@ Note: When connecting to an existing server, `textarenaenv.close()` will NOT sto
 
 Test the environment logic directly without starting the HTTP server:
 
-```bash
-# From the server directory
-python3 server/textarena_environment.py
-```
+```python
+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)
 
-This verifies that:
-- Environment resets correctly
-- Step executes actions properly
-- State tracking works
-- Rewards are calculated correctly
+# 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
 
@@ -180,24 +231,31 @@ Run the server locally for development:
 uv venv && source .venv/bin/activate
 uv pip install -e .
 
-# Start the server (use python -m to ensure venv Python is used)
+# Start the server
 python -m uvicorn server.app:app --reload
 ```
 
+Or using the CLI entry point:
+
+```bash
+uv run --project . server --port 8000
+```
+
 ## Project Structure
 
 ```
-textarena/
+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 and Observation models
+├── models.py              # Action, Observation, and State models
+├── rewards.py             # Reward provider utilities
 └── server/
     ├── __init__.py        # Server module exports
-    ├── textarena_environment.py  # Core environment logic
+    ├── environment.py     # Core TextArenaEnvironment implementation
     ├── app.py             # FastAPI application
     └── Dockerfile         # Container image definition
 ```

client.py

@@ -35,13 +35,13 @@ class TextArenaEnv(EnvClient[TextArenaAction, TextArenaObservation, TextArenaSta
 
     Example:
         >>> # Connect to a running server
-        >>> client = TextArenaEnv(base_url="http://localhost:8000")
+        >>> client = TextArenaEnv(base_url="<ENV_HTTP_URL_HERE>")
         >>> result = client.reset()
-        >>> print(result.observation.echoed_message)
+        >>> print(result.observation.prompt)
         >>>
-        >>> # Send a message
-        >>> result = client.step(TextArenaAction(message="Hello!"))
-        >>> print(result.observation.echoed_message)
+        >>> # Send an action
+        >>> result = client.step(TextArenaAction(message="[crane]"))
+        >>> print(result.observation.messages)
         >>> print(result.reward)
 
     Example with Docker:

models.py

@@ -7,15 +7,15 @@
 """
 Data models for the TextArena Environment.
 
-The textarena environment is a simple test environment that echoes back messages.
+This module defines the action, observation, and state models for interacting
+with TextArena game environments (e.g., Wordle-v0).
 """
 
 from __future__ import annotations
 
-from pydantic import Field
+from pydantic import BaseModel, Field
 from typing import Any, Dict, List, Optional
 
-from pydantic import BaseModel, Field
 
 from openenv.core.env_server.types import Action, Observation, State
 
@@ -43,10 +43,12 @@ class TextArenaObservation(Observation):
     legal_players: List[int] = Field(default_factory=list)
     info: Dict[str, Any] = Field(default_factory=dict)
 
-    
+
 class TextArenaState(State):
     """Structured state snapshot for the server."""
 
+    episode_id: Optional[str] = None
+    step_count: int = 0
     env_id: str
     num_players: int
     max_turns: Optional[int] = None
@@ -54,4 +56,3 @@ class TextArenaState(State):
     last_reward: float = 0.0
     last_info: Dict[str, Any] = Field(default_factory=dict)
     raw_state: Dict[str, Any] = Field(default_factory=dict)
-

pyproject.toml

@@ -40,13 +40,11 @@ dev = [
 
 [project.scripts]
 # Server entry point - enables running via: uv run --project . server
-# or: python -m textarena.server.app
-server = "textarena.server.app:main"
+# or: python -m textarena_env.server.app
+server = "textarena_env.server.app:main"
 
 [tool.setuptools]
 # Explicitly list packages - "textarena_env" maps to current dir
 packages = ["textarena_env", "textarena_env.server"]
 package-dir = {"textarena_env" = ".", "textarena_env.server" = "server"}
 
-
-

rewards.py

@@ -17,7 +17,9 @@ class RewardProvider(Protocol):
     def reset(self) -> None:
         """Clear any internal state before a new episode."""
 
-    def compute(self, *, action: TextArenaAction, observation: TextArenaObservation) -> Dict[str, float]:
+    def compute(
+        self, *, action: TextArenaAction, observation: TextArenaObservation
+    ) -> Dict[str, float]:
         """Return a mapping of reward names to float values for the step."""
 
 
@@ -92,12 +94,16 @@ class _WordleRewardProvider:
     def reset(self) -> None:
         self._guess_history.clear()
 
-    def compute(self, *, action: TextArenaAction, observation: TextArenaObservation) -> Dict[str, float]:
+    def compute(
+        self, *, action: TextArenaAction, observation: TextArenaObservation
+    ) -> Dict[str, float]:
         guess = extract_guess(action.message)
         feedback = extract_wordle_feedback(observation)
 
         normalized_guess = guess if guess and guess != "[dunno]" else ""
-        previous_occurrences = self._guess_history.get(normalized_guess, 0) if normalized_guess else 0
+        previous_occurrences = (
+            self._guess_history.get(normalized_guess, 0) if normalized_guess else 0
+        )
 
         green_score = 0.0
         yellow_score = 0.0

server/app.py

@@ -71,7 +71,7 @@ def main(host: str = "0.0.0.0", port: int = 8000):
     This function enables running the server without Docker:
         uv run --project . server
         uv run --project . server --port 8001
-        python -m textarena.server.app
+        python -m textarena_env.server.app
 
     Args:
         host: Host address to bind to (default: "0.0.0.0")
@@ -79,7 +79,7 @@ def main(host: str = "0.0.0.0", port: int = 8000):
 
     For production deployments, consider using uvicorn directly with
     multiple workers:
-        uvicorn textarena.server.app:app --workers 4
+        uvicorn textarena_env.server.app:app --workers 4
     """
     import uvicorn
 

server/environment.py

@@ -38,6 +38,17 @@ except ImportError:
 
 _TEXTARENA_MODULE: Any | None = None
 _TEXTARENA_IMPORT_ERROR: Exception | None = None
+_NLTK_DOWNLOADED: bool = False
+
+
+def _ensure_nltk_data() -> None:
+    """Download NLTK data once per process."""
+    global _NLTK_DOWNLOADED
+    if _NLTK_DOWNLOADED:
+        return
+    nltk.download("words", quiet=True)
+    nltk.download("averaged_perceptron_tagger_eng", quiet=True)
+    _NLTK_DOWNLOADED = True
 
 
 def _import_textarena() -> Any:
@@ -85,8 +96,7 @@ class TextArenaEnvironment(Environment):
         ta = _import_textarena()
 
         if download_nltk:
-            nltk.download("words", quiet=True)
-            nltk.download("averaged_perceptron_tagger_eng", quiet=True)
+            _ensure_nltk_data()
 
         self.env_id = env_id
         self.num_players = num_players
@@ -104,10 +114,20 @@ class TextArenaEnvironment(Environment):
         self._reward_providers: List[RewardProvider] = build_reward_providers(env_id)
         self._last_reward_signals: Dict[str, float] = {}
 
+        # Initialize environment state - TextArena envs require reset() to be called
+        # before step() can be used, as the internal state object isn't created until reset.
+        # This ensures the environment is always in a valid state after construction.
+        self._ta_env.reset(num_players=self.num_players)
+
     # ------------------------------------------------------------------
     # Environment interface
     # ------------------------------------------------------------------
-    def reset(self) -> TextArenaObservation:
+    def reset(
+        self,
+        seed: Optional[int] = None,
+        episode_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> TextArenaObservation:
         # TextArena observation wrappers (LLMObservationWrapper, etc.) accumulate
         # observations in self.full_observations across resets. Since we can't modify TextArena,
         # we need to manually clear this state to prevent history accumulation.
@@ -125,7 +145,7 @@ class TextArenaEnvironment(Environment):
         for provider in self._reward_providers:
             provider.reset()
 
-        self._state.episode_id = str(uuid4())
+        self._state.episode_id = episode_id if episode_id is not None else str(uuid4())
         self._state.step_count = 0
         self._state.turn = 0
         self._state.last_reward = 0.0

server/run_local.sh

@@ -1,4 +1,4 @@
-export TEXTARENA_ENV_ID="Sudoku-v0" 
+export TEXTARENA_ENV_ID="Wordle-v0" 
 export TEXTARENA_NUM_PLAYERS=1
 
 # Run the server

uv.lock

@@ -301,11 +301,11 @@ wheels = [
 
 [[package]]
 name = "filelock"
-version = "3.20.2"
+version = "3.20.3"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/c1/e0/a75dbe4bca1e7d41307323dad5ea2efdd95408f74ab2de8bd7dba9b51a1a/filelock-3.20.2.tar.gz", hash = "sha256:a2241ff4ddde2a7cebddf78e39832509cb045d18ec1a09d7248d6bfc6bfbbe64", size = 19510, upload-time = "2026-01-02T15:33:32.582Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/1d/65/ce7f1b70157833bf3cb851b556a37d4547ceafc158aa9b34b36782f23696/filelock-3.20.3.tar.gz", hash = "sha256:18c57ee915c7ec61cff0ecf7f0f869936c7c30191bb0cf406f1341778d0834e1", size = 19485, upload-time = "2026-01-09T17:55:05.421Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/9a/30/ab407e2ec752aa541704ed8f93c11e2a5d92c168b8a755d818b74a3c5c2d/filelock-3.20.2-py3-none-any.whl", hash = "sha256:fbba7237d6ea277175a32c54bb71ef814a8546d8601269e1bfc388de333974e8", size = 16697, upload-time = "2026-01-02T15:33:31.133Z" },
+    { url = "https://files.pythonhosted.org/packages/b5/36/7fb70f04bf00bc646cd5bb45aa9eddb15e19437a28b8fb2b4a5249fac770/filelock-3.20.3-py3-none-any.whl", hash = "sha256:4b0dda527ee31078689fc205ec4f1c1bf7d56cf88b6dc9426c4f230e46c2dce1", size = 16701, upload-time = "2026-01-09T17:55:04.334Z" },
 ]
 
 [[package]]
@@ -1206,11 +1206,11 @@ wheels = [
 
 [[package]]
 name = "urllib3"
-version = "2.6.2"
+version = "2.6.3"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/1e/24/a2a2ed9addd907787d7aa0355ba36a6cadf1768b934c652ea78acbd59dcd/urllib3-2.6.2.tar.gz", hash = "sha256:016f9c98bb7e98085cb2b4b17b87d2c702975664e4f060c6532e64d1c1a5e797", size = 432930, upload-time = "2025-12-11T15:56:40.252Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/c7/24/5f1b3bdffd70275f6661c76461e25f024d5a38a46f04aaca912426a2b1d3/urllib3-2.6.3.tar.gz", hash = "sha256:1b62b6884944a57dbe321509ab94fd4d3b307075e0c2eae991ac71ee15ad38ed", size = 435556, upload-time = "2026-01-07T16:24:43.925Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/6d/b9/4095b668ea3678bf6a0af005527f39de12fb026516fb3df17495a733b7f8/urllib3-2.6.2-py3-none-any.whl", hash = "sha256:ec21cddfe7724fc7cb4ba4bea7aa8e2ef36f607a4bab81aa6ce42a13dc3f03dd", size = 131182, upload-time = "2025-12-11T15:56:38.584Z" },
+    { url = "https://files.pythonhosted.org/packages/39/08/aaaad47bc4e9dc8c725e68f9d04865dbcb2052843ff09c97b08904852d84/urllib3-2.6.3-py3-none-any.whl", hash = "sha256:bf272323e553dfb2e87d9bfd225ca7b0f467b919d7bbd355436d3fd37cb0acd4", size = 131584, upload-time = "2026-01-07T16:24:42.685Z" },
 ]
 
 [[package]]