Upload folder using huggingface_hub

Dockerfile

@@ -0,0 +1,65 @@
+# 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.
+
+# =============================================================================
+# OpenSpiel Environment Dockerfile
+# =============================================================================
+#
+# Uses a pre-built OpenSpiel base image to avoid long build times (~30-60 min).
+# The base image contains compiled OpenSpiel (C++ and Python bindings).
+#
+# DEFAULT (recommended for HuggingFace Spaces):
+#   Uses pre-built image from GHCR - no C++ compilation needed
+#
+# BUILD YOUR OWN BASE IMAGE (if you need custom OpenSpiel configuration):
+#   1. Build the base image first (takes ~30-60 min):
+#      docker build -t openspiel-base:latest -f server/Dockerfile.openspiel-base .
+#   2. Then build with your local base image:
+#      docker build --build-arg OPENSPIEL_BASE_IMAGE=openspiel-base:latest -t openspiel-env .
+#
+# =============================================================================
+
+# Default: use pre-built image from GHCR (skips C++ compilation)
+ARG OPENSPIEL_BASE_IMAGE=ghcr.io/meta-pytorch/openenv-openspiel-base:sha-e622c7e
+FROM ${OPENSPIEL_BASE_IMAGE}
+
+WORKDIR /app
+
+# Install git (needed for pip install from git repos in pyproject.toml)
+RUN apt-get update && apt-get install -y --no-install-recommends git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy environment code (context is the environment directory)
+COPY . /app/env
+
+# Install Python dependencies from pyproject.toml
+WORKDIR /app/env
+RUN pip3 install --no-cache-dir .
+
+WORKDIR /app
+
+# Copy README for web interface documentation
+COPY README.md /app/README.md
+
+# Python path configuration
+# - /repo and /repo/build/python: OpenSpiel paths from base image
+# - /app/env: Environment code
+ENV PYTHONPATH=/repo:/repo/build/python:/app/env
+
+# OpenSpiel-specific environment variables (can be overridden at runtime)
+ENV OPENSPIEL_GAME=catch
+ENV OPENSPIEL_AGENT_PLAYER=0
+ENV OPENSPIEL_OPPONENT_POLICY=random
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=120s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+EXPOSE 8000
+
+# Run the FastAPI server
+ENV ENABLE_WEB_INTERFACE=true
+CMD ["uvicorn", "server.app:app", "--host", "0.0.0.0", "--port", "8000", "--timeout-keep-alive", "120"]

README.md

@@ -1,10 +1,381 @@
 ---
-title: Openspiel Env
-emoji: 🦀
-colorFrom: pink
-colorTo: pink
+title: OpenSpiel Environment Server
+emoji: 🎮
+colorFrom: blue
+colorTo: purple
 sdk: docker
 pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# OpenSpiel Environment
+
+Integration of OpenSpiel games with the OpenEnv framework. [OpenSpiel](https://github.com/google-deepmind/open_spiel) is DeepMind's collection of 70+ game environments for RL research.
+
+## Supported Games
+
+This environment supports 6 games across different categories:
+
+### Single-Player Games (No Opponent)
+1. **Catch** - Move horizontally to catch a falling ball
+2. **Cliff Walking** - Navigate grid without falling off cliff (Sutton & Barto benchmark)
+3. **2048** - Classic tile-merging puzzle game
+4. **Blackjack** - Simplified blackjack (HIT/STAND only)
+
+### Multi-Player Games (with Bot Opponent)
+5. **Tic-Tac-Toe** - Classic 3x3 game
+6. **Kuhn Poker** - 2-player simplified poker (game theory benchmark)
+
+## Quick Start
+
+The simplest way to use the OpenSpiel environment is through the `OpenSpielEnv` class:
+
+```python
+from openspiel_env import OpenSpielEnv, OpenSpielAction
+
+try:
+    # Create environment from Docker image
+    env = OpenSpielEnv.from_docker_image("openspiel-env:latest")
+
+    # Reset to start a new episode
+    result = env.reset()
+    print(f"Initial state: {result.observation.info_state}")
+    print(f"Legal actions: {result.observation.legal_actions}")
+
+    # Play until done
+    while not result.done:
+        action_id = result.observation.legal_actions[0]
+        result = env.step(OpenSpielAction(action_id=action_id))
+        print(f"Reward: {result.reward}, Done: {result.done}")
+
+finally:
+    # Always clean up
+    env.close()
+```
+
+That's it! The `OpenSpielEnv.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
+
+OpenSpiel requires compilation from C++ source. The Docker build uses a **pre-built base image** by default to avoid long build times.
+
+### Default Build (Recommended)
+
+From the **environment directory** (`envs/openspiel_env/`):
+
+```bash
+# Uses pre-built base image from GHCR (fast, ~1-2 min)
+docker build -t openspiel-env:latest -f server/Dockerfile .
+```
+
+This uses the pre-built `ghcr.io/meta-pytorch/openenv-openspiel-base` image which already contains compiled OpenSpiel.
+
+### Building Your Own Base Image (Optional)
+
+If you need to customize OpenSpiel or can't access the pre-built image:
+
+```bash
+# Step 1: Build the base image (compiles OpenSpiel, ~30-60 min)
+docker build -t openspiel-base:latest -f server/Dockerfile.openspiel-base .
+
+# Step 2: Build the environment using your local base image
+docker build -t openspiel-env:latest \
+  --build-arg OPENSPIEL_BASE_IMAGE=openspiel-base: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 (envs/openspiel_env/)
+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/openspiel-env
+
+# Push as a private space
+openenv push --private
+
+# Combine options
+openenv push --repo-id my-org/openspiel-env --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
+
+> **Note**: The default Dockerfile uses a pre-built base image with OpenSpiel already compiled, so deployment is fast and works with standard CPU hardware. If you build your own base image, compilation requires more resources and time.
+
+## Running Specific Games
+
+```bash
+# Catch (default)
+docker run -p 8000:8000 openspiel-env:latest
+
+# Tic-Tac-Toe with random opponent
+docker run -p 8000:8000 -e OPENSPIEL_GAME=tic_tac_toe openspiel-env:latest
+
+# Kuhn Poker
+docker run -p 8000:8000 -e OPENSPIEL_GAME=kuhn_poker openspiel-env:latest
+
+# 2048
+docker run -p 8000:8000 -e OPENSPIEL_GAME=2048 openspiel-env:latest
+
+# Blackjack
+docker run -p 8000:8000 -e OPENSPIEL_GAME=blackjack openspiel-env:latest
+
+# Cliff Walking
+docker run -p 8000:8000 -e OPENSPIEL_GAME=cliff_walking openspiel-env:latest
+```
+
+## Environment Details
+
+### Action
+**OpenSpielAction**: Contains the action to take
+- `action_id` (int) - Action ID to execute
+- `game_name` (str) - Game name (default: "catch")
+- `game_params` (Dict) - Optional game parameters
+
+### Observation
+**OpenSpielObservation**: Contains the game state
+- `info_state` (List[float]) - Agent's information state vector
+- `legal_actions` (List[int]) - Legal action IDs
+- `game_phase` (str) - "initial", "playing", or "terminal"
+- `current_player_id` (int) - Current player (-1 for simultaneous)
+- `opponent_last_action` (Optional[int]) - Last opponent action
+- `done` (bool) - Whether the episode has ended
+- `reward` (Optional[float]) - Reward for the last action
+
+### State
+**OpenSpielState**: Server-side state snapshot
+- `episode_id` (str) - Unique identifier for the current episode
+- `step_count` (int) - Number of steps taken
+- `game_name` (str) - Game name
+- `agent_player` (int) - Agent's player ID
+- `opponent_policy` (str) - Opponent policy name
+- `num_players` (int) - Total players
+
+## Configuration
+
+### Environment Variables
+
+- `OPENSPIEL_GAME`: Game name (default: "catch")
+- `OPENSPIEL_AGENT_PLAYER`: Player ID for agent (default: 0)
+- `OPENSPIEL_OPPONENT_POLICY`: Opponent policy for multi-player games
+  - `random`: Uniform random (default)
+  - `first`: Always picks first legal action
+  - `last`: Always picks last legal action
+
+### Example: Tic-Tac-Toe with Fixed Opponent
+
+```bash
+docker run -p 8000:8000 \
+  -e OPENSPIEL_GAME=tic_tac_toe \
+  -e OPENSPIEL_OPPONENT_POLICY=first \
+  openspiel-env:latest
+```
+
+## Advanced Usage
+
+### Connecting to an Existing Server
+
+If you already have an OpenSpiel environment server running:
+
+```python
+from openspiel_env import OpenSpielEnv, OpenSpielAction
+
+# Connect to existing server
+env = OpenSpielEnv(base_url="http://localhost:8000")
+
+# Use as normal
+result = env.reset()
+result = env.step(OpenSpielAction(action_id=result.observation.legal_actions[0]))
+
+# Close connection (does NOT stop the server)
+env.close()
+```
+
+### Connecting to HuggingFace Space
+
+```python
+from openspiel_env import OpenSpielEnv, OpenSpielAction
+
+# Connect to remote Space
+env = OpenSpielEnv(base_url="https://your-username-openspiel.hf.space")
+
+result = env.reset()
+print(f"Game: {result.observation.game_phase}")
+print(f"Legal actions: {result.observation.legal_actions}")
+
+result = env.step(OpenSpielAction(action_id=result.observation.legal_actions[0]))
+env.close()
+```
+
+## Game-Specific Information
+
+### 1. Catch
+- **Type**: Single-player
+- **Action Space**: 3 actions (left, stay, right)
+- **Observation**: 5x5 grid flattened (25 dimensions)
+- **Reward**: +1 for catching ball, 0 otherwise
+- **Episode Length**: ~10 steps
+
+### 2. Tic-Tac-Toe
+- **Type**: 2-player turn-based, perfect information
+- **Players**: Agent (X) vs Random Bot (O)
+- **Action Space**: 9 positions
+- **Observation**: 27 dimensions (3x3 board + game state)
+- **Reward**: +1 win, -1 loss, 0 draw/mid-game
+
+### 3. Kuhn Poker
+- **Type**: 2-player turn-based, imperfect information
+- **Players**: Agent vs Random Bot
+- **Action Space**: 2 actions (pass/fold, bet/call)
+- **Observation**: 6 dimensions (card + betting history)
+- **Reward**: Pot winnings (typically -1, 0, +1, +2)
+- **Notes**: THE benchmark for imperfect-information RL
+
+### 4. Cliff Walking
+- **Type**: Single-player grid world
+- **Action Space**: 4 actions (up, down, left, right)
+- **Observation**: Position encoding
+- **Reward**: -1 per step, -100 for falling off cliff
+- **Notes**: Classic RL benchmark from Sutton & Barto
+
+### 5. 2048
+- **Type**: Single-player puzzle
+- **Action Space**: 4 actions (up, down, left, right)
+- **Observation**: 4x4 grid with tile values
+- **Reward**: Points from merging tiles
+- **Notes**: Stochastic tile spawning
+
+### 6. Blackjack
+- **Type**: Single-player vs dealer
+- **Action Space**: 2 actions (HIT, STAND)
+- **Observation**: Player hand + dealer's visible card
+- **Reward**: +1 win, -1 loss, 0 draw
+- **Notes**: Simplified version, no double/split
+
+## Development & Testing
+
+### Direct Environment Testing
+
+Test the environment logic directly without starting the HTTP server (requires OpenSpiel installed locally):
+
+```python
+from openspiel_env.server.openspiel_environment import OpenSpielEnvironment
+from openspiel_env.models import OpenSpielAction
+
+# Create environment directly
+env = OpenSpielEnvironment(game_name="catch")
+
+# Test reset
+obs = env.reset()
+print(f"Info state: {obs.info_state}")
+
+# Test step
+obs = env.step(OpenSpielAction(action_id=0))
+print(f"Done: {obs.done}, Reward: {obs.reward}")
+```
+
+### Running Locally
+
+Run the server locally for development (requires OpenSpiel installed):
+
+```bash
+# From the environment directory
+cd envs/openspiel_env
+
+# 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:
+
+```bash
+uv run --project . server --port 8000
+```
+
+### Automated Testing (All 6 Games)
+
+```bash
+./test_docker_all_games.sh
+```
+
+This script will build and test all 6 supported games in Docker.
+
+## Project Structure
+
+```
+openspiel_env/
+├── __init__.py                    # Module exports
+├── README.md                      # This file
+├── openenv.yaml                   # OpenEnv manifest
+├── pyproject.toml                 # Project metadata and dependencies
+├── client.py                      # OpenSpielEnv client implementation
+├── models.py                      # Action, Observation, and State models
+├── test_docker_all_games.sh       # Automated test script
+└── server/
+    ├── __init__.py                # Server module exports
+    ├── openspiel_environment.py   # Core OpenSpielEnvironment implementation
+    ├── opponent_policies.py       # Opponent policies (random, fixed)
+    ├── app.py                     # FastAPI application
+    ├── Dockerfile                 # Environment container (uses pre-built base)
+    └── Dockerfile.openspiel-base  # Base image with compiled OpenSpiel
+```
+
+## Limitations
+
+- **Simultaneous-move games**: Only agent_player=0 supported
+- **Multi-agent training**: Single agent only (no self-play yet)
+- **Opponent policies**: Random and fixed only (no MCTS yet)
+- **Build time**: Building your own base image takes ~30-60 min (compiles OpenSpiel C++). Using the pre-built image is fast (~1-2 min) and works with standard hardware.
+
+## References
+
+- [OpenSpiel Paper (2019)](https://arxiv.org/abs/1908.09453)
+- [OpenSpiel GitHub](https://github.com/google-deepmind/open_spiel)
+- [OpenSpiel Documentation](https://openspiel.readthedocs.io/)

__init__.py

@@ -0,0 +1,26 @@
+# 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.
+
+"""
+OpenSpiel Environment Integration.
+
+This module provides integration between OpenSpiel games and the OpenEnv framework.
+OpenSpiel (https://github.com/google-deepmind/open_spiel) is DeepMind's collection
+of environments and algorithms for research in RL in games.
+
+Supported games:
+- Catch (1P)
+- Tic-Tac-Toe (2P)
+- Kuhn Poker (2P, imperfect info)
+- Cliff Walking (1P)
+- 2048 (1P)
+- Blackjack (1P)
+"""
+
+from .client import OpenSpielEnv
+from .models import OpenSpielAction, OpenSpielObservation, OpenSpielState
+
+__all__ = ["OpenSpielEnv", "OpenSpielAction", "OpenSpielObservation", "OpenSpielState"]

client.py

@@ -0,0 +1,119 @@
+# 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.
+
+"""
+OpenSpielEnv Client.
+
+This module provides the client for connecting to an OpenSpiel Environment server
+via WebSocket for persistent sessions.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, TYPE_CHECKING
+
+from openenv.core.client_types import StepResult
+
+from openenv.core.env_client import EnvClient
+
+from .models import OpenSpielAction, OpenSpielObservation, OpenSpielState
+
+if TYPE_CHECKING:
+    from openenv.core.containers.runtime import ContainerProvider
+
+
+class OpenSpielEnv(EnvClient[OpenSpielAction, OpenSpielObservation, OpenSpielState]):
+    """
+    Client for OpenSpiel Environment.
+
+    This client maintains a persistent WebSocket connection to the environment
+    server, enabling efficient multi-step interactions with lower latency.
+
+    Example:
+        >>> # Connect to a running server
+        >>> with OpenSpielEnv(base_url="http://localhost:8000") as client:
+        ...     result = client.reset()
+        ...     print(result.observation.info_state)
+        ...
+        ...     result = client.step(OpenSpielAction(action_id=1, game_name="catch"))
+        ...     print(result.observation.reward)
+
+    Example with Docker:
+        >>> # Automatically start container and connect
+        >>> client = OpenSpielEnv.from_docker_image("openspiel-env:latest")
+        >>> try:
+        ...     result = client.reset()
+        ...     result = client.step(OpenSpielAction(action_id=0))
+        ... finally:
+        ...     client.close()
+    """
+
+    def _step_payload(self, action: OpenSpielAction) -> Dict[str, Any]:
+        """
+        Convert OpenSpielAction to JSON payload for step request.
+
+        Args:
+            action: OpenSpielAction instance.
+
+        Returns:
+            Dictionary representation suitable for JSON encoding.
+        """
+        return {
+            "action_id": action.action_id,
+            "game_name": action.game_name,
+            "game_params": action.game_params,
+        }
+
+    def _parse_result(
+        self, payload: Dict[str, Any]
+    ) -> StepResult[OpenSpielObservation]:
+        """
+        Parse server response into StepResult[OpenSpielObservation].
+
+        Args:
+            payload: JSON response from server.
+
+        Returns:
+            StepResult with OpenSpielObservation.
+        """
+        obs_data = payload.get("observation", {})
+
+        observation = OpenSpielObservation(
+            info_state=obs_data.get("info_state", []),
+            legal_actions=obs_data.get("legal_actions", []),
+            game_phase=obs_data.get("game_phase", "playing"),
+            current_player_id=obs_data.get("current_player_id", 0),
+            opponent_last_action=obs_data.get("opponent_last_action"),
+            done=payload.get("done", False),
+            reward=payload.get("reward"),
+            metadata=obs_data.get("metadata", {}),
+        )
+
+        return StepResult(
+            observation=observation,
+            reward=payload.get("reward"),
+            done=payload.get("done", False),
+        )
+
+    def _parse_state(self, payload: Dict[str, Any]) -> OpenSpielState:
+        """
+        Parse server response into OpenSpielState object.
+
+        Args:
+            payload: JSON response from /state endpoint.
+
+        Returns:
+            OpenSpielState object with environment state information.
+        """
+        return OpenSpielState(
+            episode_id=payload.get("episode_id"),
+            step_count=payload.get("step_count", 0),
+            game_name=payload.get("game_name", "unknown"),
+            agent_player=payload.get("agent_player", 0),
+            opponent_policy=payload.get("opponent_policy", "random"),
+            game_params=payload.get("game_params", {}),
+            num_players=payload.get("num_players", 1),
+        )

docker_issue.md

@@ -0,0 +1 @@
+# port issue? fix proxy?

models.py

@@ -0,0 +1,73 @@
+# 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.
+
+"""
+Data models for OpenSpiel Environment.
+
+This module defines the Action, Observation, and State types for OpenSpiel games.
+"""
+
+from __future__ import annotations
+from pydantic import Field
+
+from typing import Any, Dict, List, Optional
+
+from openenv.core.env_server import Action, Observation, State
+
+
+class OpenSpielAction(Action):
+    """
+    Action for OpenSpiel environments.
+
+    Attributes:
+        action_id: The integer action ID to take (from legal_actions).
+        game_name: Name of the OpenSpiel game (e.g., "catch", "tic_tac_toe").
+        game_params: Optional game-specific parameters (e.g., {"rows": 8, "columns": 6}).
+    """
+    action_id: int
+    game_name: str = "catch"
+    game_params: Dict[str, Any] = Field(default_factory=dict)
+
+
+class OpenSpielObservation(Observation):
+    """
+    Observation from OpenSpiel environment.
+
+    This represents what the agent sees after taking an action.
+    For single-player games, this is straightforward.
+    For multi-player games, this is from the perspective of the agent player.
+
+    Attributes:
+        info_state: Information state tensor (list of floats) for the agent.
+                   This contains all information available to the agent.
+        legal_actions: List of legal action IDs the agent can take.
+        game_phase: String describing the current phase (e.g., "playing", "terminal").
+        current_player_id: ID of the current player (-1 for simultaneous, player ID otherwise).
+        opponent_last_action: Last action taken by opponent (if available, None otherwise).
+    """
+    info_state: List[float]
+    legal_actions: List[int]
+    game_phase: str = "playing"
+    current_player_id: int = 0
+    opponent_last_action: Optional[int] = None
+
+
+class OpenSpielState(State):
+    """
+    State for OpenSpiel environment.
+
+    Attributes:
+        game_name: Name of the OpenSpiel game.
+        agent_player: Which player ID the agent controls (0 by default).
+        opponent_policy: Name of the opponent policy ("random", "fixed", etc.).
+        game_params: Game-specific parameters.
+        num_players: Total number of players in the game.
+    """
+    game_name: str = "catch"
+    agent_player: int = 0
+    opponent_policy: str = "random"
+    game_params: Dict[str, Any] = Field(default_factory=dict)
+    num_players: int = 1

openenv.yaml

@@ -0,0 +1,6 @@
+spec_version: 1
+name: openspiel_env
+type: space
+runtime: fastapi
+app: server.app:app
+port: 8000

pyproject.toml

@@ -0,0 +1,41 @@
+# 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.
+
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openenv-openspiel-env"
+version = "0.1.0"
+description = "OpenSpiel Environment for OpenEnv - integration with DeepMind's game research framework"
+requires-python = ">=3.10"
+dependencies = [
+    # Core OpenEnv dependencies (required for server functionality)
+    "openenv-core @ git+https://github.com/meta-pytorch/OpenEnv.git@main",
+    "fastapi>=0.115.0",
+    "pydantic>=2.0.0",
+    "uvicorn>=0.24.0",
+    "requests>=2.31.0",
+    # Note: OpenSpiel (pyspiel) is built from source in the Docker image
+    # and is not available as a pip package. The Docker build compiles it
+    # from https://github.com/google-deepmind/open_spiel
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.scripts]
+# Server entry point
+server = "openspiel_env.server.app:main"
+
+[tool.setuptools]
+include-package-data = true
+packages = ["openspiel_env", "openspiel_env.server"]
+package-dir = { "openspiel_env" = ".", "openspiel_env.server" = "server" }

server/Dockerfile.openspiel-base

@@ -0,0 +1,71 @@
+# 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.
+
+# Pre-built OpenSpiel base image
+# This image contains OpenSpiel compiled and ready to use
+# Built from: docker build -t openspiel-base:latest -f envs/openspiel_env/server/Dockerfile.openspiel-base .
+# In GitHub Actions, this is overridden to use the GHCR base image
+ARG BASE_IMAGE=openenv-base:latest
+FROM ${BASE_IMAGE}
+
+# Avoid interactive prompts during build
+ENV DEBIAN_FRONTEND=noninteractive
+ENV TZ=UTC
+
+# Install build dependencies (curl already installed by openenv-base)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    clang \
+    cmake \
+    git \
+    sudo \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set up OpenSpiel build directory
+RUN mkdir /repo
+WORKDIR /repo
+
+# Clone OpenSpiel
+RUN git clone https://github.com/google-deepmind/open_spiel.git .
+
+# Run OpenSpiel's installation script (downloads C++ dependencies)
+RUN ./install.sh
+
+# Install Python dependencies
+# First upgrade pip and setuptools, then install other packages
+RUN pip3 install --no-cache-dir --upgrade pip setuptools wheel
+RUN pip3 install --no-cache-dir --upgrade pbr testresources importlib_metadata
+RUN pip3 install --no-cache-dir --upgrade -r requirements.txt cmake
+
+# Build OpenSpiel with Python 3.11
+# Use the exact same Python executable as the base image
+# Disable gin_rummy to speed up build (complex game, not needed for basic usage)
+RUN mkdir -p build
+WORKDIR /repo/build
+RUN cmake -DPython3_EXECUTABLE=/usr/local/bin/python3 \
+    -DCMAKE_CXX_COMPILER=$(which clang++) \
+    -DOPEN_SPIEL_BUILD_WITH_GIN_RUMMY=OFF \
+    ../open_spiel
+RUN make -j$(nproc) pyspiel
+
+# Install OpenSpiel Python requirements
+WORKDIR /repo
+RUN pip3 install --no-cache-dir --upgrade -r requirements.txt
+
+# Set Python path for OpenSpiel
+ENV PYTHONPATH=/repo:/repo/build/python:${PYTHONPATH}
+
+# Test OpenSpiel import to verify ABI compatibility
+RUN python3 -c "import pyspiel; print('OpenSpiel import successful')" || echo "OpenSpiel import failed"
+
+# Clean up build dependencies to reduce image size
+RUN apt-get remove -y build-essential clang cmake git sudo || true && \
+    apt-get autoremove -y && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+# Set working directory back to /app (standard for openenv-base)
+WORKDIR /app

server/__init__.py

@@ -0,0 +1,7 @@
+# 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.
+
+"""Server-side implementation for OpenSpiel environments."""

server/app.py

@@ -0,0 +1,88 @@
+# 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.
+
+"""
+FastAPI application for the OpenSpiel Environment.
+
+This module creates an HTTP server that exposes OpenSpiel games
+over HTTP and WebSocket endpoints, compatible with EnvClient.
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn server.app:app --host 0.0.0.0 --port 8000 --workers 4
+
+    # Or run directly:
+    uv run --project . server
+
+Environment variables:
+    OPENSPIEL_GAME: Game name to serve (default: "catch")
+    OPENSPIEL_AGENT_PLAYER: Agent player ID (default: 0)
+    OPENSPIEL_OPPONENT_POLICY: Opponent policy (default: "random")
+"""
+
+import os
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.http_server import create_app
+    from ..models import OpenSpielAction, OpenSpielObservation
+    from .openspiel_environment import OpenSpielEnvironment
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.http_server import create_app
+    from models import OpenSpielAction, OpenSpielObservation
+    from server.openspiel_environment import OpenSpielEnvironment
+
+# Get game configuration from environment variables
+game_name = os.getenv("OPENSPIEL_GAME", "catch")
+agent_player = int(os.getenv("OPENSPIEL_AGENT_PLAYER", "0"))
+opponent_policy = os.getenv("OPENSPIEL_OPPONENT_POLICY", "random")
+
+
+# Factory function to create OpenSpielEnvironment instances
+def create_openspiel_environment():
+    """Factory function that creates OpenSpielEnvironment with config."""
+    return OpenSpielEnvironment(
+        game_name=game_name,
+        agent_player=agent_player,
+        opponent_policy=opponent_policy,
+    )
+
+
+# Create the FastAPI app with web interface and README integration
+# Pass the factory function instead of an instance for WebSocket session support
+app = create_app(
+    create_openspiel_environment,
+    OpenSpielAction,
+    OpenSpielObservation,
+    env_name="openspiel_env",
+)
+
+
+def main(host: str = "0.0.0.0", port: int = 8000):
+    """
+    Entry point for direct execution via uv run or python -m.
+
+    This function enables running the server without Docker:
+        uv run --project . server
+        uv run --project . server --port 8001
+        python -m openspiel_env.server.app
+
+    Args:
+        host: Host address to bind to (default: "0.0.0.0")
+        port: Port number to listen on (default: 8000)
+    """
+    import uvicorn
+
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    main()

server/build_docker.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+# 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.
+
+# Script to build the OpenSpiel environment Docker image
+# Usage: ./build_docker.sh [tag]
+#
+# Note: Requires envtorch-base:latest to be built first.
+# See: src/core/containers/images/README.md
+
+set -e
+
+TAG="${1:-latest}"
+IMAGE_NAME="openspiel-env:${TAG}"
+
+echo "🐳 Building OpenSpiel Environment Docker Image"
+echo "================================================"
+echo "Image: $IMAGE_NAME"
+echo ""
+
+# Get script directory
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+
+# Navigate to OpenEnv root (4 levels up from server/)
+OPENENV_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+
+echo "📁 OpenEnv root: $OPENENV_ROOT"
+echo ""
+
+# Build OpenSpiel environment image
+# Note: Docker will automatically pull ghcr.io/meta-pytorch/openenv-base:latest if needed
+echo "⏳ Building (this may take 5-10 minutes due to OpenSpiel compilation)..."
+docker build \
+    -f "$SCRIPT_DIR/Dockerfile" \
+    -t "$IMAGE_NAME" \
+    "$OPENENV_ROOT"
+
+if [ $? -eq 0 ]; then
+    echo ""
+    echo "✅ Build successful!"
+    echo ""
+    echo "🚀 Run with different games:"
+    echo ""
+    echo "  # Catch (default)"
+    echo "  docker run -p 8000:8000 $IMAGE_NAME"
+    echo ""
+    echo "  # Tic-Tac-Toe"
+    echo "  docker run -p 8000:8000 -e OPENSPIEL_GAME=tic_tac_toe $IMAGE_NAME"
+    echo ""
+    echo "  # Kuhn Poker"
+    echo "  docker run -p 8000:8000 -e OPENSPIEL_GAME=kuhn_poker $IMAGE_NAME"
+    echo ""
+    echo "  # Cliff Walking"
+    echo "  docker run -p 8000:8000 -e OPENSPIEL_GAME=cliff_walking $IMAGE_NAME"
+    echo ""
+    echo "  # 2048"
+    echo "  docker run -p 8000:8000 -e OPENSPIEL_GAME=2048 $IMAGE_NAME"
+    echo ""
+    echo "  # Blackjack"
+    echo "  docker run -p 8000:8000 -e OPENSPIEL_GAME=blackjack $IMAGE_NAME"
+    echo ""
+else
+    echo ""
+    echo "❌ Build failed!"
+    exit 1
+fi

server/openspiel_environment.py

@@ -0,0 +1,273 @@
+# 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.
+
+"""
+OpenSpiel Environment Server Implementation.
+
+This module wraps OpenSpiel's rl_environment.Environment and exposes it
+via the OpenEnv Environment interface.
+"""
+
+import uuid
+from typing import Any, Dict
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.interfaces import Environment
+    from ..models import OpenSpielAction, OpenSpielObservation, OpenSpielState
+    from .opponent_policies import get_opponent_policy, OpponentPolicy
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.interfaces import Environment
+    from models import OpenSpielAction, OpenSpielObservation, OpenSpielState
+    from server.opponent_policies import get_opponent_policy, OpponentPolicy
+
+# Import OpenSpiel
+try:
+    from open_spiel.python import rl_environment
+    import pyspiel
+except ImportError as e:
+    raise ImportError(
+        "OpenSpiel is not installed. "
+        "Please install it following instructions at: "
+        "https://github.com/google-deepmind/open_spiel"
+    ) from e
+
+
+class OpenSpielEnvironment(Environment):
+    """
+    OpenSpiel Environment wrapper for OpenEnv.
+
+    This environment wraps OpenSpiel games and provides a single-agent interface.
+    For multi-player games, the agent controls one player while opponent(s) use
+    a fixed policy (e.g., random).
+
+    Supported games:
+    - Single-player: catch, cliff_walking, 2048, blackjack
+    - Multi-player: tic_tac_toe, kuhn_poker
+
+    Args:
+        game_name: Name of the OpenSpiel game (e.g., "catch", "tic_tac_toe").
+        agent_player: Which player ID the agent controls (default 0).
+        opponent_policy: Policy for opponent players ("random", "first", etc.).
+        game_params: Optional game-specific parameters.
+
+    Example:
+        >>> env = OpenSpielEnvironment("catch")
+        >>> obs = env.reset()
+        >>> print(obs.info_state)  # Agent's observation
+        >>> obs = env.step(OpenSpielAction(action_id=1))
+        >>> print(obs.reward)
+    """
+
+    def __init__(
+        self,
+        game_name: str = "catch",
+        agent_player: int = 0,
+        opponent_policy: str = "random",
+        game_params: Dict[str, Any] | None = None,
+    ):
+        """Initialize OpenSpiel environment."""
+        super().__init__()
+
+        self.game_name = game_name
+        self.agent_player = agent_player
+        self.game_params = game_params or {}
+
+        # Create OpenSpiel environment
+        try:
+            self._ospiel_env = rl_environment.Environment(
+                game_name, **self.game_params
+            )
+        except Exception as e:
+            raise ValueError(
+                f"Failed to create OpenSpiel game '{game_name}': {e}"
+            ) from e
+
+        self.num_players = self._ospiel_env.num_players
+        self.is_turn_based = self._ospiel_env.is_turn_based
+
+        # Validate agent_player
+        if agent_player >= self.num_players:
+            raise ValueError(
+                f"agent_player={agent_player} >= num_players={self.num_players}"
+            )
+
+        # Set up opponent policy for multi-player games
+        self.opponent_policy_fn: OpponentPolicy | None = None
+        if self.num_players > 1:
+            self.opponent_policy_fn = get_opponent_policy(opponent_policy)
+
+        # Initialize state
+        self._state = OpenSpielState(
+            game_name=game_name,
+            agent_player=agent_player,
+            opponent_policy=opponent_policy,
+            game_params=self.game_params,
+            num_players=self.num_players,
+        )
+
+        # Track last opponent action for learning
+        self._last_opponent_action: int | None = None
+
+    def reset(self) -> OpenSpielObservation:
+        """
+        Reset the environment and return initial observation.
+
+        For multi-player games, this will autoplay opponent turns until
+        it's the agent's turn (or terminal state).
+
+        Returns:
+            Initial observation for the agent.
+        """
+        # Reset OpenSpiel environment
+        time_step = self._ospiel_env.reset()
+
+        # Reset state tracking
+        self._state.episode_id = str(uuid.uuid4())
+        self._state.step_count = 0
+        self._last_opponent_action = None
+
+        # Autoplay opponent turns until agent's turn
+        time_step = self._auto_play_opponents(time_step)
+
+        # Convert to OpenEnv observation
+        return self._make_observation(time_step)
+
+    def step(self, action: OpenSpielAction) -> OpenSpielObservation:  # type: ignore[override]
+        """
+        Execute agent's action and return resulting observation.
+
+        For multi-player games, this will:
+        1. Apply the agent's action
+        2. Autoplay opponent turns until it's the agent's turn again
+        3. Return the observation from the agent's perspective
+
+        Args:
+            action: OpenSpielAction containing the action_id to execute.
+
+        Returns:
+            Observation after action execution (and opponent turns if multi-player).
+
+        Raises:
+            ValueError: If action is not an OpenSpielAction.
+        """
+        if not isinstance(action, OpenSpielAction):
+            raise ValueError(f"Expected OpenSpielAction, got {type(action)}")
+
+        # Apply agent's action
+        if self.is_turn_based:
+            # Turn-based: single action
+            time_step = self._ospiel_env.step([action.action_id])
+        else:
+            # Simultaneous-move: need actions for all players
+            # For now, only support agent as player 0 in simultaneous games
+            if self.agent_player != 0:
+                raise NotImplementedError(
+                    "Simultaneous-move games only support agent_player=0"
+                )
+            # Get opponent actions
+            opponent_actions = []
+            for player_id in range(self.num_players):
+                if player_id == self.agent_player:
+                    opponent_actions.append(action.action_id)
+                else:
+                    legal_actions = time_step.observations["legal_actions"][player_id]
+                    opp_action = self.opponent_policy_fn.select_action(
+                        legal_actions, time_step.observations
+                    )
+                    opponent_actions.append(opp_action)
+            time_step = self._ospiel_env.step(opponent_actions)
+
+        self._state.step_count += 1
+
+        # Autoplay opponent turns (for turn-based games)
+        if self.is_turn_based:
+            time_step = self._auto_play_opponents(time_step)
+
+        # Convert to OpenEnv observation
+        return self._make_observation(time_step)
+
+    @property
+    def state(self) -> OpenSpielState:
+        """Get current environment state."""
+        return self._state
+
+    def _auto_play_opponents(self, time_step) -> Any:
+        """
+        Autoplay opponent turns until it's the agent's turn or game is terminal.
+
+        Args:
+            time_step: Current TimeStep from OpenSpiel environment.
+
+        Returns:
+            Updated TimeStep after opponent moves.
+        """
+        # Single-player games: nothing to do
+        if self.num_players == 1:
+            return time_step
+
+        # Multi-player games: play opponent turns
+        while (
+            not time_step.last()
+            and time_step.observations["current_player"] != self.agent_player
+        ):
+            current_player = time_step.observations["current_player"]
+            legal_actions = time_step.observations["legal_actions"][current_player]
+
+            # Select opponent action
+            opp_action = self.opponent_policy_fn.select_action(
+                legal_actions, time_step.observations
+            )
+            self._last_opponent_action = opp_action
+
+            # Apply opponent action
+            time_step = self._ospiel_env.step([opp_action])
+            self._state.step_count += 1
+
+        return time_step
+
+    def _make_observation(self, time_step) -> OpenSpielObservation:
+        """
+        Convert OpenSpiel TimeStep to OpenEnv Observation.
+
+        Args:
+            time_step: OpenSpiel TimeStep object.
+
+        Returns:
+            OpenSpielObservation for the agent.
+        """
+        # Extract agent's information
+        info_state = time_step.observations["info_state"][self.agent_player]
+        legal_actions = time_step.observations["legal_actions"][self.agent_player]
+        current_player_id = time_step.observations["current_player"]
+
+        # Determine game phase
+        if time_step.last():
+            game_phase = "terminal"
+        elif time_step.first():
+            game_phase = "initial"
+        else:
+            game_phase = "playing"
+
+        # Get reward for agent
+        reward = None
+        if time_step.rewards is not None:
+            reward = float(time_step.rewards[self.agent_player])
+
+        # Create observation
+        obs = OpenSpielObservation(
+            info_state=info_state.tolist() if hasattr(info_state, "tolist") else list(info_state),
+            legal_actions=legal_actions,
+            game_phase=game_phase,
+            current_player_id=current_player_id,
+            opponent_last_action=self._last_opponent_action,
+            done=time_step.last(),
+            reward=reward,
+        )
+
+        return obs

server/opponent_policies.py

@@ -0,0 +1,90 @@
+# 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.
+
+"""
+Opponent policies for multi-player OpenSpiel games.
+
+These policies are used to control non-agent players in multi-player games,
+allowing single-agent RL training against fixed or adaptive opponents.
+"""
+
+import random
+from typing import Any, Protocol
+
+
+class OpponentPolicy(Protocol):
+    """Protocol for opponent policies."""
+
+    def select_action(self, legal_actions: list[int], observations: dict[str, Any]) -> int:
+        """
+        Select an action for the opponent.
+
+        Args:
+            legal_actions: List of legal action IDs.
+            observations: Current observations from the environment.
+
+        Returns:
+            Selected action ID.
+        """
+        ...
+
+
+class RandomOpponent:
+    """Random opponent that selects uniformly from legal actions."""
+
+    def select_action(self, legal_actions: list[int], observations: dict[str, Any]) -> int:
+        """Select a random legal action."""
+        if not legal_actions:
+            raise ValueError("No legal actions available")
+        return random.choice(legal_actions)
+
+
+class FixedActionOpponent:
+    """Opponent that always selects the same action (e.g., first legal action)."""
+
+    def __init__(self, action_selector: str = "first"):
+        """
+        Initialize fixed action opponent.
+
+        Args:
+            action_selector: Which action to select ("first", "last", "middle").
+        """
+        self.action_selector = action_selector
+
+    def select_action(self, legal_actions: list[int], observations: dict[str, Any]) -> int:
+        """Select a fixed legal action based on selector."""
+        if not legal_actions:
+            raise ValueError("No legal actions available")
+
+        if self.action_selector == "first":
+            return legal_actions[0]
+        elif self.action_selector == "last":
+            return legal_actions[-1]
+        elif self.action_selector == "middle":
+            return legal_actions[len(legal_actions) // 2]
+        else:
+            return legal_actions[0]
+
+
+def get_opponent_policy(policy_name: str) -> OpponentPolicy:
+    """
+    Get an opponent policy by name.
+
+    Args:
+        policy_name: Name of the policy ("random", "first", "last", "middle").
+
+    Returns:
+        OpponentPolicy instance.
+
+    Raises:
+        ValueError: If policy_name is not recognized.
+    """
+    if policy_name == "random":
+        return RandomOpponent()
+    elif policy_name in ("first", "last", "middle"):
+        return FixedActionOpponent(action_selector=policy_name)
+    else:
+        raise ValueError(f"Unknown opponent policy: {policy_name}")

server/prepare_hf.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+# Custom HF deployment script for openspiel_env
+# OpenSpiel uses a different base image with C++ compilation
+
+set -e
+
+DOCKERFILE_PATH="$1"
+BASE_IMAGE_REF="$2"
+
+echo "OpenSpiel: Using custom Dockerfile preparation"
+
+# Cross-platform sed in-place editing
+sed_inplace() {
+    if sed --version >/dev/null 2>&1; then
+        # GNU sed (Linux)
+        sed -i "$@"
+    else
+        # BSD sed (macOS)
+        sed -i '' "$@"
+    fi
+}
+
+# Replace ARG with hardcoded FROM using the special OpenSpiel base
+sed_inplace 's|ARG OPENSPIEL_BASE_IMAGE=.*|FROM ghcr.io/meta-pytorch/openenv-openspiel-base:sha-e622c7e|g' "$DOCKERFILE_PATH"
+sed_inplace '/^FROM \${OPENSPIEL_BASE_IMAGE}/d' "$DOCKERFILE_PATH"
+
+echo "OpenSpiel: Modified Dockerfile to use GHCR OpenSpiel base image"
+echo "OpenSpiel builds can take 10-15 minutes due to C++ compilation"

test_docker_all_games.sh

@@ -0,0 +1,152 @@
+#!/bin/bash
+# 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.
+
+# Automated test script for all OpenSpiel games in Docker
+# Usage: ./test_docker_all_games.sh
+
+set -e
+
+# Colors for output
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Configuration
+IMAGE_NAME="openspiel-env:latest"
+CONTAINER_NAME="openspiel-test"
+PORT=8000
+HEALTH_CHECK_URL="http://localhost:${PORT}/health"
+MAX_WAIT=30
+
+# Games to test
+GAMES=("catch" "tic_tac_toe" "kuhn_poker" "cliff_walking" "2048" "blackjack")
+
+# Results tracking
+declare -a RESULTS
+PASSED=0
+FAILED=0
+
+echo -e "${BLUE}========================================${NC}"
+echo -e "${BLUE}OpenSpiel Docker Integration Test${NC}"
+echo -e "${BLUE}========================================${NC}"
+echo ""
+
+# Function to cleanup containers
+cleanup() {
+    echo -e "${YELLOW}Cleaning up containers...${NC}"
+    docker stop ${CONTAINER_NAME} 2>/dev/null || true
+    docker rm ${CONTAINER_NAME} 2>/dev/null || true
+}
+
+# Function to wait for server health
+wait_for_health() {
+    local game=$1
+    echo -e "  ⏳ Waiting for server to be ready..."
+
+    for i in $(seq 1 $MAX_WAIT); do
+        if curl -s -f ${HEALTH_CHECK_URL} > /dev/null 2>&1; then
+            echo -e "  ${GREEN}✓${NC} Server ready (${i}s)"
+            return 0
+        fi
+        sleep 1
+    done
+
+    echo -e "  ${RED}✗${NC} Server health check failed after ${MAX_WAIT}s"
+    return 1
+}
+
+# Function to test a game
+test_game() {
+    local game=$1
+    echo -e "\n${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+    echo -e "${BLUE}Testing: ${game}${NC}"
+    echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+
+    # Stop any existing container
+    cleanup
+
+    # Start container with game
+    echo -e "  🐳 Starting Docker container..."
+    docker run -d \
+        --name ${CONTAINER_NAME} \
+        -p ${PORT}:8000 \
+        -e OPENSPIEL_GAME=${game} \
+        ${IMAGE_NAME} > /dev/null
+
+    # Wait for server to be ready
+    if ! wait_for_health ${game}; then
+        echo -e "  ${RED}✗ FAILED${NC} - Server did not start"
+        RESULTS+=("${game}:FAILED:Server did not start")
+        FAILED=$((FAILED + 1))
+        cleanup
+        return 1
+    fi
+
+    # Run Python client test
+    echo -e "  🎮 Running Python client test..."
+    if NO_PROXY=localhost,127.0.0.1 HTTP_PROXY= HTTPS_PROXY= \
+       PYTHONPATH=$PWD/src:$PYTHONPATH \
+       python3 examples/openspiel_simple.py > /tmp/test_${game}.log 2>&1; then
+
+        # Check if episode completed successfully
+        if grep -q "Episode finished!" /tmp/test_${game}.log; then
+            echo -e "  ${GREEN}✓ PASSED${NC} - Episode completed successfully"
+            RESULTS+=("${game}:PASSED")
+            PASSED=$((PASSED + 1))
+        else
+            echo -e "  ${RED}✗ FAILED${NC} - Episode did not complete"
+            RESULTS+=("${game}:FAILED:Episode incomplete")
+            FAILED=$((FAILED + 1))
+        fi
+    else
+        echo -e "  ${RED}✗ FAILED${NC} - Python client error"
+        RESULTS+=("${game}:FAILED:Client error")
+        FAILED=$((FAILED + 1))
+    fi
+
+    # Cleanup
+    cleanup
+}
+
+# Run tests for all games
+for game in "${GAMES[@]}"; do
+    test_game ${game}
+done
+
+# Print summary
+echo -e "\n${BLUE}========================================${NC}"
+echo -e "${BLUE}Test Summary${NC}"
+echo -e "${BLUE}========================================${NC}"
+echo ""
+
+for result in "${RESULTS[@]}"; do
+    IFS=':' read -r game status message <<< "$result"
+    if [ "$status" == "PASSED" ]; then
+        echo -e "  ${GREEN}✓${NC} ${game}"
+    else
+        echo -e "  ${RED}✗${NC} ${game} - ${message}"
+    fi
+done
+
+echo ""
+echo -e "Total: ${PASSED} passed, ${FAILED} failed out of ${#GAMES[@]} games"
+echo ""
+
+# Exit with appropriate code
+if [ $FAILED -eq 0 ]; then
+    echo -e "${GREEN}========================================${NC}"
+    echo -e "${GREEN}All tests PASSED! 🎉${NC}"
+    echo -e "${GREEN}========================================${NC}"
+    exit 0
+else
+    echo -e "${RED}========================================${NC}"
+    echo -e "${RED}Some tests FAILED${NC}"
+    echo -e "${RED}========================================${NC}"
+    exit 1
+fi