Add minesweeper env and example

[acharyaanusha]

Summary

This PR adds a new Minesweeper game environment to OpenEnv, providing a classic grid-based puzzle game for reinforcement learning agents. The environment challenges agents to reveal all non-mine cells without triggering any mines, using strategies based on number clues and flag placement.

Motivation

Minesweeper is a well-known logical puzzle that requires:

• Strategic thinking and planning
• Risk assessment and decision-making under uncertainty
• Multi-step reasoning based on partial information
• Balance between exploration (revealing cells) and exploitation (using known information)

This environment is valuable for:

• Testing RL agents on logical reasoning tasks
• Evaluating agents' ability to handle uncertainty and risk
• Benchmarking decision-making in partially observable environments
• Educational purposes and demonstrations

Changes

Core Implementation

• Environment Logic: Full Minesweeper game implementation with configurable grid size and mine count
• Action Space: Two action types:
  • reveal: Uncover a cell to see its value
  • flag: Place/remove flag on suspected mine locations
• Observation Space: 2D grid showing:
  • Unrevealed cells (-1)
  • Number clues (0-8) indicating adjacent mines
  • Flagged cells ('F')
  • Mines ('*', only shown on game over)
• Reward System:
  • +1.0 for revealing safe cells
  • +0.5 for correctly flagging mines
  • -10.0 for hitting mines (game over)
  • Small penalties for invalid actions
• Game States: ONGOING, WON, LOST

Features

• Recursive Reveal: Automatically reveals adjacent cells when a cell with zero adjacent mines is uncovered
• State Management: Full game state tracking with episode IDs and step counts
• HTTP API: FastAPI-based server for remote environment access
• Type Safety: Pydantic models for all actions and observations

Docker Support

• Multi-stage Dockerfile based on openenv-base image
• Build script (build_docker.sh) for easy local development
• Health check endpoint for container orchestration
• Optimized layer caching for faster builds

Testing

• Comprehensive test suite with 13 test cases covering:
  • Server setup and initialization
  • Action execution (reveal, flag, toggle)
  • Edge cases (invalid positions, already revealed cells)
  • Game state transitions
  • Reset functionality
  • HTTP serialization handling
• All tests passing ✅

Documentation

• Detailed README with:
  • Quick start guide
  • Action and observation specifications
  • Reward structure
  • Configuration options
  • Usage examples
  • Docker instructions
• Example agent script demonstrating full gameplay

CI/CD Integration

• Added to GitHub Actions build matrix
• Automated Docker image building for linux/amd64 and linux/arm64
• Automated publishing to GitHub Container Registry

Files Changed

New Files (14 files, 1,552 insertions)

Environment Core:

• src/envs/minesweeper_env/__init__.py - Module exports and public API
• src/envs/minesweeper_env/client.py - HTTP client for remote environment access
• src/envs/minesweeper_env/models.py - Pydantic models for actions, observations, and state
• src/envs/minesweeper_env/openenv.yaml - Environment metadata and configuration
• src/envs/minesweeper_env/pyproject.toml - Package dependencies and build configuration

Server Implementation:

• src/envs/minesweeper_env/server/__init__.py - Server module exports
• src/envs/minesweeper_env/server/app.py - FastAPI application and HTTP endpoints
• src/envs/minesweeper_env/server/minesweeper_environment.py - Core game logic and environment implementation

Docker & Build:

• src/envs/minesweeper_env/server/Dockerfile - Multi-stage container image definition
• src/envs/minesweeper_env/server/build_docker.sh - Build script for local development

Documentation & Examples:

• src/envs/minesweeper_env/README.md - Comprehensive environment documentation
• examples/minesweeper_agent.py - Example agent demonstrating environment usage

Testing:

• tests/envs/test_minesweeper_env.py - Test suite with 13 test cases

Modified Files (1 file)

CI/CD:

• .github/workflows/docker-build.yml - Added minesweeper-env to build matrix for automated Docker image building

Usage Example

from envs.minesweeper_env import MinesweeperAction, MinesweeperEnv

# Create environment from Docker image
env = MinesweeperEnv.from_docker_image("minesweeper-env:latest")

try:
    # Reset
    result = env.reset()
    print(f"Board: {result.observation.board_height}x{result.observation.board_width}")
    print(f"Mines: {result.observation.num_mines}")
    
    # Reveal a cell
    result = env.step(MinesweeperAction(row=2, col=2, action_type="reveal"))
    
    # Place a flag
    result = env.step(MinesweeperAction(row=0, col=0, action_type="flag"))
    
finally:
    env.close()

Testing

Run the test suite:

python tests/envs/test_minesweeper_env.py

Build and run the Docker image:

./build_docker.sh latest
docker run -p 8000:8000 minesweeper-env:latest