first-commit

AI-Trainer

@@ -0,0 +1 @@
+Subproject commit f3f4b7149046a184ad5e5495f093ff66f9ebb8bf

DesktopRL Environment.txt

@@ -0,0 +1,8 @@
+cd "C:\Users\Vivek\Desktop\RL Environment\ai_contest_arena"
+docker build -t ai_contest_arena-env:latest .
+docker run -d -p 8000:8000 --name contest_arena ai_contest_arena-env:latest
+
+$env:API_BASE_URL = "https://router.huggingface.co/v1"
+$env:HF_TOKEN     = "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"
+$env:MODEL_NAME   = "google/gemma-4-31B-it:novita"
+python inference.py

README.md

@@ -0,0 +1,83 @@
+# Meta OpenEnv Hackathon — AI Agent Submission
+
+## Overview
+
+This project is a production-ready AI agent built for the **Meta OpenEnv Hackathon**. The agent competes in a 3-round coding challenge against an OpenAI GPT-4o-mini judge, receiving Python coding tasks and submitting solutions for evaluation.
+
+---
+
+## Agent: `inference.py`
+
+The core agent logic lives entirely in `inference.py`. It runs a 3-round loop that:
+
+1. Calls the local OpenEnv server's `/reset` endpoint to fetch a new coding task
+2. Sends the task to a powerful LLM to generate a Python solution
+3. Submits the solution back to the `/step` endpoint and retrieves the score
+
+### API Payload Compatibility
+
+The agent uses the exact payload format required by the Meta OpenEnv REST API:
+
+```json
+{"action": {"answer": "<agent_answer>"}}
+```
+
+This nested structure matches the server's strict Pydantic model validation, completely preventing `422 Unprocessable Entity` errors that arise from incorrect top-level keys or flat payload formats.
+
+---
+
+## Model: Qwen/Qwen2.5-72B-Instruct
+
+The agent uses **`Qwen/Qwen2.5-72B-Instruct`** via the **Hugging Face Router API** (`https://router.huggingface.co/v1`), accessed through an OpenAI-compatible client.
+
+Key reasons for this choice:
+
+- The HF Router endpoint is the current active inference gateway — the legacy `api-inference.huggingface.co/v1` endpoint has been deprecated and returns `410 Gone` errors
+- Qwen 2.5 72B delivers state-of-the-art Python code generation, significantly outperforming smaller models on structured coding tasks
+- The OpenAI-compatible interface ensures zero-downtime, stable connections with clean error handling
+
+---
+
+## Task Parsing
+
+The agent safely parses tasks from multiple possible server response shapes:
+
+- `response["observation"]["echoed_message"]`
+- `response["observation"]["task_prompt"]`
+- `response["echoed_message"]`
+- Raw JSON fallback via `json.dumps(resp)`
+
+This makes the agent resilient to any OpenEnv server version or configuration.
+
+---
+
+## Setup
+
+### 1. Install dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+### 2. Set environment variables
+
+```powershell
+$env:HF_TOKEN = "hf_your_token_here"
+$env:OPENAI_API_KEY = "sk-your_key_here"
+```
+
+### 3. Start the OpenEnv server, then run the agent
+
+```bash
+python inference.py
+```
+
+---
+
+## Requirements
+
+| Package      | Version  |
+|--------------|----------|
+| requests     | 2.31.0   |
+| openai       | 1.14.0   |
+| pydantic     | 2.6.4    |

ai_contest_arena/.dockerignore

@@ -0,0 +1,44 @@
+# Python virtual environments (Windows & Unix)
+.venv/
+venv/
+env/
+ENV/
+.env/
+
+# uv cache
+.uv/
+
+# Python cache
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+
+# Distribution / packaging
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Test & coverage artifacts
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE / editor
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS artefacts
+.DS_Store
+Thumbs.db
+
+# Git
+.git/
+.gitignore
+
+# Inference script (runs outside the container)
+inference.py

ai_contest_arena/Dockerfile

@@ -0,0 +1,80 @@
+# 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.
+
+# Multi-stage build using openenv-base
+# This Dockerfile is flexible and works for both:
+# - In-repo environments (with local OpenEnv sources)
+# - Standalone environments (with openenv from PyPI/Git)
+# The build script (openenv build) handles context detection and sets appropriate build args.
+
+ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
+FROM ${BASE_IMAGE} AS builder
+
+WORKDIR /app
+
+# Ensure git is available (required for installing dependencies from VCS)
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends git && \
+    rm -rf /var/lib/apt/lists/*
+
+# Build argument to control whether we're building standalone or in-repo
+ARG BUILD_MODE=in-repo
+ARG ENV_NAME=ai_contest_arena
+
+# Copy environment code (always at root of build context)
+COPY . /app/env
+
+# For in-repo builds, openenv is already vendored in the build context
+# For standalone builds, openenv will be installed via pyproject.toml
+WORKDIR /app/env
+
+# Ensure uv is available (for local builds where base image lacks it)
+RUN if ! command -v uv >/dev/null 2>&1; then \
+        curl -LsSf https://astral.sh/uv/install.sh | sh && \
+        mv /root/.local/bin/uv /usr/local/bin/uv && \
+        mv /root/.local/bin/uvx /usr/local/bin/uvx; \
+    fi
+    
+# Install dependencies using uv sync
+# If uv.lock exists, use it; otherwise resolve on the fly
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-install-project --no-editable; \
+    else \
+        uv sync --no-install-project --no-editable; \
+    fi
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-editable; \
+    else \
+        uv sync --no-editable; \
+    fi
+
+# Final runtime stage
+FROM ${BASE_IMAGE}
+
+WORKDIR /app
+
+# Copy the virtual environment from builder
+COPY --from=builder /app/env/.venv /app/.venv
+
+# Copy the environment code
+COPY --from=builder /app/env /app/env
+
+# Set PATH to use the virtual environment
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Set PYTHONPATH so imports work correctly
+ENV PYTHONPATH="/app/env:$PYTHONPATH"
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Run the FastAPI server
+# The module path is constructed to work with the /app/env structure
+CMD ["sh", "-c", "cd /app/env && uvicorn server.app:app --host 0.0.0.0 --port 8000"]

ai_contest_arena/README.md

@@ -0,0 +1,255 @@
+---
+title: Ai Contest Arena Environment Server
+emoji: 🎻
+colorFrom: indigo
+colorTo: red
+sdk: docker
+pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
+---
+
+# Ai Contest Arena Environment
+
+A simple test environment that echoes back messages. Perfect for testing the env APIs as well as demonstrating environment usage patterns.
+
+## Quick Start
+
+The simplest way to use the Ai Contest Arena environment is through the `AiContestArenaEnv` class:
+
+```python
+from ai_contest_arena import AiContestArenaAction, AiContestArenaEnv
+
+try:
+    # Create environment from Docker image
+    ai_contest_arenaenv = AiContestArenaEnv.from_docker_image("ai_contest_arena-env:latest")
+
+    # Reset
+    result = ai_contest_arenaenv.reset()
+    print(f"Reset: {result.observation.echoed_message}")
+
+    # Send multiple messages
+    messages = ["Hello, World!", "Testing echo", "Final message"]
+
+    for msg in messages:
+        result = ai_contest_arenaenv.step(AiContestArenaAction(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}")
+
+finally:
+    # Always clean up
+    ai_contest_arenaenv.close()
+```
+
+That's it! The `AiContestArenaEnv.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:
+
+```bash
+# From project root
+docker build -t ai_contest_arena-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:
+
+```bash
+# 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
+
+```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/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
+- **WebSocket** at `/ws` - Persistent session endpoint for low-latency interactions
+
+## Environment Details
+
+### Action
+**AiContestArenaAction**: Contains a single field
+- `message` (str) - The message to echo back
+
+### Observation
+**AiContestArenaObservation**: 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
+
+### Reward
+The reward is calculated as: `message_length × 0.1`
+- "Hi" → reward: 0.2
+- "Hello, World!" → reward: 1.3
+- Empty message → reward: 0.0
+
+## Advanced Usage
+
+### Connecting to an Existing Server
+
+If you already have a Ai Contest Arena environment server running, you can connect directly:
+
+```python
+from ai_contest_arena import AiContestArenaEnv
+
+# Connect to existing server
+ai_contest_arenaenv = AiContestArenaEnv(base_url="<ENV_HTTP_URL_HERE>")
+
+# Use as normal
+result = ai_contest_arenaenv.reset()
+result = ai_contest_arenaenv.step(AiContestArenaAction(message="Hello!"))
+```
+
+Note: When connecting to an existing server, `ai_contest_arenaenv.close()` will NOT stop the server.
+
+### Using the Context Manager
+
+The client supports context manager usage for automatic connection management:
+
+```python
+from ai_contest_arena import AiContestArenaAction, AiContestArenaEnv
+
+# Connect with context manager (auto-connects and closes)
+with AiContestArenaEnv(base_url="http://localhost:8000") as env:
+    result = env.reset()
+    print(f"Reset: {result.observation.echoed_message}")
+    # Multiple steps with low latency
+    for msg in ["Hello", "World", "!"]:
+        result = env.step(AiContestArenaAction(message=msg))
+        print(f"Echoed: {result.observation.echoed_message}")
+```
+
+The client uses WebSocket connections for:
+- **Lower latency**: No HTTP connection overhead per request
+- **Persistent session**: Server maintains your environment state
+- **Efficient for episodes**: Better for many sequential steps
+
+### Concurrent WebSocket Sessions
+
+The server supports multiple concurrent WebSocket connections. To enable this,
+modify `server/app.py` to use factory mode:
+
+```python
+# In server/app.py - use factory mode for concurrent sessions
+app = create_app(
+    AiContestArenaEnvironment,  # Pass class, not instance
+    AiContestArenaAction,
+    AiContestArenaObservation,
+    max_concurrent_envs=4,  # Allow 4 concurrent sessions
+)
+```
+
+Then multiple clients can connect simultaneously:
+
+```python
+from ai_contest_arena import AiContestArenaAction, AiContestArenaEnv
+from concurrent.futures import ThreadPoolExecutor
+
+def run_episode(client_id: int):
+    with AiContestArenaEnv(base_url="http://localhost:8000") as env:
+        result = env.reset()
+        for i in range(10):
+            result = env.step(AiContestArenaAction(message=f"Client {client_id}, step {i}"))
+        return client_id, result.observation.message_length
+
+# Run 4 episodes concurrently
+with ThreadPoolExecutor(max_workers=4) as executor:
+    results = list(executor.map(run_episode, range(4)))
+```
+
+## Development & Testing
+
+### Direct Environment Testing
+
+Test the environment logic directly without starting the HTTP server:
+
+```bash
+# From the server directory
+python3 server/ai_contest_arena_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:
+
+```bash
+uvicorn server.app:app --reload
+```
+
+## Project Structure
+
+```
+ai_contest_arena/
+├── .dockerignore         # Docker build exclusions
+├── __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              # AiContestArenaEnv client
+├── models.py              # Action and Observation models
+└── server/
+    ├── __init__.py        # Server module exports
+    ├── ai_contest_arena_environment.py  # Core environment logic
+    ├── app.py             # FastAPI application (HTTP + WebSocket endpoints)
+    └── Dockerfile         # Container image definition
+```

ai_contest_arena/__init__.py

@@ -0,0 +1,16 @@
+# 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.
+
+"""Ai Contest Arena Environment."""
+
+from .client import AiContestArenaEnv
+from .models import AiContestArenaAction, AiContestArenaObservation
+
+__all__ = [
+    "AiContestArenaAction",
+    "AiContestArenaObservation",
+    "AiContestArenaEnv",
+]

ai_contest_arena/client.py

@@ -0,0 +1,99 @@
+# 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.
+
+"""Ai Contest Arena Environment Client."""
+
+from typing import Dict
+
+from openenv.core import EnvClient
+from openenv.core.client_types import StepResult
+from openenv.core.env_server.types import State
+
+from .models import AiContestArenaAction, AiContestArenaObservation
+
+
+class AiContestArenaEnv(
+    EnvClient[AiContestArenaAction, AiContestArenaObservation, State]
+):
+    """
+    Client for the Ai Contest Arena Environment.
+
+    This client maintains a persistent WebSocket connection to the environment server,
+    enabling efficient multi-step interactions with lower latency.
+    Each client instance has its own dedicated environment session on the server.
+
+    Example:
+        >>> # Connect to a running server
+        >>> with AiContestArenaEnv(base_url="http://localhost:8000") as client:
+        ...     result = client.reset()
+        ...     print(result.observation.echoed_message)
+        ...
+        ...     result = client.step(AiContestArenaAction(message="Hello!"))
+        ...     print(result.observation.echoed_message)
+
+    Example with Docker:
+        >>> # Automatically start container and connect
+        >>> client = AiContestArenaEnv.from_docker_image("ai_contest_arena-env:latest")
+        >>> try:
+        ...     result = client.reset()
+        ...     result = client.step(AiContestArenaAction(message="Test"))
+        ... finally:
+        ...     client.close()
+    """
+
+    def _step_payload(self, action: AiContestArenaAction) -> Dict:
+        """
+        Convert AiContestArenaAction to JSON payload for step message.
+
+        Args:
+            action: AiContestArenaAction instance
+
+        Returns:
+            Dictionary representation suitable for JSON encoding
+        """
+        return {
+            "message": action.message,
+        }
+
+    def _parse_result(self, payload: Dict) -> StepResult[AiContestArenaObservation]:
+        """
+        Parse server response into StepResult[AiContestArenaObservation].
+
+        Args:
+            payload: JSON response data from server
+
+        Returns:
+            StepResult with AiContestArenaObservation
+        """
+        obs_data = payload.get("observation", {})
+        observation = AiContestArenaObservation(
+            echoed_message=obs_data.get("echoed_message", ""),
+            message_length=obs_data.get("message_length", 0),
+            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) -> State:
+        """
+        Parse server response into State object.
+
+        Args:
+            payload: JSON response from state request
+
+        Returns:
+            State object with episode_id and step_count
+        """
+        return State(
+            episode_id=payload.get("episode_id"),
+            step_count=payload.get("step_count", 0),
+        )

ai_contest_arena/models.py

@@ -0,0 +1,35 @@
+# 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 the Multi-Agent Contest Arena Environment.
+
+Contestant A submits an answer (Action); the environment evaluates it
+against a Baseline (Contestant B) using an LLM-as-a-Judge.
+"""
+
+from openenv.core.env_server.types import Action, Observation, State
+from pydantic import Field
+
+
+class AiContestArenaAction(Action):
+    """Contestant A's submitted answer to the current task."""
+
+    answer: str = Field(..., description="Contestant A's solution to the current task")
+
+
+class AiContestArenaObservation(Observation):
+    """Observation returned after each step — task prompt and judge feedback."""
+
+    task_prompt: str = Field(default="", description="The task/problem to solve")
+    judge_feedback: str = Field(default="", description="LLM Judge's evaluation feedback")
+
+
+class AiContestArenaState(State):
+    """Full environment state — current task and latest judge feedback."""
+
+    current_task: str = Field(default="", description="The active task prompt")
+    judge_feedback: str = Field(default="", description="Latest judge feedback")

ai_contest_arena/openenv.yaml

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

ai_contest_arena/openenv_ai_contest_arena.egg-info/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: openenv-ai_contest_arena
+Version: 0.1.0
+Summary: Multi-Agent Contest Arena environment for OpenEnv
+Requires-Python: >=3.10
+Requires-Dist: openenv-core[core]>=0.2.2
+Requires-Dist: openai>=1.0.0
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"

ai_contest_arena/openenv_ai_contest_arena.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+README.md
+__init__.py
+client.py
+models.py
+pyproject.toml
+./__init__.py
+./client.py
+./models.py
+openenv_ai_contest_arena.egg-info/PKG-INFO
+openenv_ai_contest_arena.egg-info/SOURCES.txt
+openenv_ai_contest_arena.egg-info/dependency_links.txt
+openenv_ai_contest_arena.egg-info/entry_points.txt
+openenv_ai_contest_arena.egg-info/requires.txt
+openenv_ai_contest_arena.egg-info/top_level.txt
+server/__init__.py
+server/ai_contest_arena_environment.py
+server/app.py

ai_contest_arena/openenv_ai_contest_arena.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ai_contest_arena/openenv_ai_contest_arena.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+server = ai_contest_arena.server.app:main

ai_contest_arena/openenv_ai_contest_arena.egg-info/requires.txt

@@ -0,0 +1,7 @@
+openenv-core[core]>=0.2.2
+openai>=1.0.0
+requests>=2.28.0
+
+[dev]
+pytest>=8.0.0
+pytest-cov>=4.0.0

ai_contest_arena/openenv_ai_contest_arena.egg-info/top_level.txt

@@ -0,0 +1 @@
+ai_contest_arena

ai_contest_arena/pyproject.toml

@@ -0,0 +1,34 @@
+# 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-ai_contest_arena"
+version = "0.1.0"
+description = "Multi-Agent Contest Arena environment for OpenEnv"
+requires-python = ">=3.10"
+dependencies = [
+    "openenv-core[core]>=0.2.2",
+    "openai>=1.0.0",
+    "requests>=2.28.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.scripts]
+server = "ai_contest_arena.server.app:main"
+
+[tool.setuptools]
+include-package-data = true
+packages = ["ai_contest_arena", "ai_contest_arena.server"]
+package-dir = { "ai_contest_arena" = ".", "ai_contest_arena.server" = "server" }

ai_contest_arena/pyrightconfig.json

@@ -0,0 +1,8 @@
+{
+  "venvPath": ".",
+  "venv": ".venv",
+  "pythonVersion": "3.10",
+  "typeCheckingMode": "basic",
+  "reportMissingImports": "warning",
+  "reportMissingModuleSource": "none"
+}

ai_contest_arena/server/__init__.py

@@ -0,0 +1,11 @@
+# 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.
+
+"""Ai Contest Arena environment server components."""
+
+from .ai_contest_arena_environment import AiContestArenaEnvironment
+
+__all__ = ["AiContestArenaEnvironment"]

ai_contest_arena/server/ai_contest_arena_environment.py

@@ -0,0 +1,212 @@
+# 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.
+
+"""
+Multi-Agent Contest Arena Environment.
+
+Contestant A submits an answer; the LLM Judge evaluates it against
+Contestant B's pre-defined baseline answer and returns a reward in [0, 1].
+"""
+
+import os
+import random
+import re
+from uuid import uuid4
+
+from openenv.core.env_server.interfaces import Environment
+from openai import OpenAI
+
+try:
+    from ..models import AiContestArenaAction, AiContestArenaObservation, AiContestArenaState
+except ImportError:
+    from models import AiContestArenaAction, AiContestArenaObservation, AiContestArenaState
+
+JUDGE_API_BASE_URL = os.environ.get(
+    "JUDGE_API_BASE_URL",
+    os.environ.get("API_BASE_URL", "https://router.huggingface.co/v1"),
+)
+JUDGE_API_KEY = os.environ.get("JUDGE_API_KEY") or os.environ.get("HF_TOKEN")
+JUDGE_MODEL_NAME = os.environ.get(
+    "JUDGE_MODEL_NAME",
+    os.environ.get("MODEL_NAME", "google/gemma-4-31B-it:novita"),
+)
+
+
+TASKS = [
+    {
+        "difficulty": "Easy",
+        "prompt": "Write a Python function that returns the factorial of a non-negative integer n using recursion.",
+        "baseline": (
+            "def factorial(n):\n"
+            "    if n == 0:\n"
+            "        return 1\n"
+            "    return n * factorial(n - 1)"
+        ),
+    },
+    {
+        "difficulty": "Medium",
+        "prompt": (
+            "Write a Python function that finds all pairs in a list of integers that sum to a given target. "
+            "Return a list of tuples. Each pair should appear only once."
+        ),
+        "baseline": (
+            "def find_pairs(nums, target):\n"
+            "    seen, pairs = set(), []\n"
+            "    for n in nums:\n"
+            "        complement = target - n\n"
+            "        if complement in seen:\n"
+            "            pairs.append((complement, n))\n"
+            "        seen.add(n)\n"
+            "    return pairs"
+        ),
+    },
+    {
+        "difficulty": "Hard",
+        "prompt": (
+            "Implement a Python class `LRUCache` with a fixed capacity that supports "
+            "`get(key)` and `put(key, value)` operations in O(1) time."
+        ),
+        "baseline": (
+            "from collections import OrderedDict\n\n"
+            "class LRUCache:\n"
+            "    def __init__(self, capacity):\n"
+            "        self.cache = OrderedDict()\n"
+            "        self.capacity = capacity\n\n"
+            "    def get(self, key):\n"
+            "        if key not in self.cache:\n"
+            "            return -1\n"
+            "        self.cache.move_to_end(key)\n"
+            "        return self.cache[key]\n\n"
+            "    def put(self, key, value):\n"
+            "        if key in self.cache:\n"
+            "            self.cache.move_to_end(key)\n"
+            "        self.cache[key] = value\n"
+            "        if len(self.cache) > self.capacity:\n"
+            "            self.cache.popitem(last=False)"
+        ),
+    },
+]
+
+JUDGE_PROMPT = """\
+You are an impartial programming contest judge. Evaluate two solutions to the problem below.
+
+## Problem
+{problem}
+
+## Contestant A's Answer
+{answer_a}
+
+## Contestant B's Answer (Baseline)
+{answer_b}
+
+Score Contestant A's answer out of 10 based on:
+1. Correctness — does it solve the problem accurately?
+2. Reasoning — is the logic sound and efficient?
+3. Formatting — is the code clean and readable?
+
+Respond in this exact format:
+Score: <integer 0-10>
+Feedback: <one concise paragraph>
+"""
+
+
+def _get_judge_client() -> OpenAI:
+    if not JUDGE_API_KEY:
+        raise RuntimeError(
+            "Missing judge API key for judge evaluation. "
+            "Set JUDGE_API_KEY or HF_TOKEN in the environment for the ai_contest_arena server process."
+        )
+
+    return OpenAI(base_url=JUDGE_API_BASE_URL, api_key=JUDGE_API_KEY)
+
+
+def _call_judge(problem: str, answer_a: str, answer_b: str) -> tuple[float, str]:
+    """Call the LLM judge and return (normalized_reward, feedback)."""
+    client = _get_judge_client()
+    prompt = JUDGE_PROMPT.format(problem=problem, answer_a=answer_a, answer_b=answer_b)
+    try:
+        response = client.chat.completions.create(
+            model=JUDGE_MODEL_NAME,
+            messages=[{"role": "user", "content": prompt}],
+            max_tokens=512,
+            temperature=0.2,
+        )
+    except Exception as err:
+        raise RuntimeError(
+            "LLM judge call failed. Check API_BASE_URL and HF_TOKEN for the ai_contest_arena server process. "
+            f"Original error: {err}"
+        ) from err
+
+    text = response.choices[0].message.content or ""
+
+    match = re.search(r"Score:\s*(\d+)", text)
+    raw_score = int(match.group(1)) if match else 5
+    raw_score = max(0, min(10, raw_score))
+
+    # Normalize strictly to (0.0, 1.0) — never exactly 0 or 1
+    reward = (raw_score + 0.5) / 11.0
+
+    feedback_match = re.search(r"Feedback:\s*(.+)", text, re.DOTALL)
+    feedback = feedback_match.group(1).strip() if feedback_match else text.strip()
+
+    return reward, feedback
+
+
+class AiContestArenaEnvironment(Environment):
+    """
+    Multi-Agent Contest Arena.
+
+    On reset(), a random task (Easy / Medium / Hard) is selected.
+    On step(action), the LLM Judge scores Contestant A vs the baseline
+    and returns a reward strictly in (0.0, 1.0).
+    """
+
+    SUPPORTS_CONCURRENT_SESSIONS: bool = True
+
+    def __init__(self):
+        self._task: dict = {}
+        self._state = AiContestArenaState(episode_id=str(uuid4()), step_count=0)
+
+    def reset(self) -> AiContestArenaObservation:
+        self._task = random.choice(TASKS)
+        self._state = AiContestArenaState(
+            episode_id=str(uuid4()),
+            step_count=0,
+            current_task=self._task["prompt"],
+            judge_feedback="",
+        )
+        return AiContestArenaObservation(
+            task_prompt=self._task["prompt"],
+            judge_feedback="",
+            done=False,
+            reward=0.0,
+        )
+
+    def step(self, action: AiContestArenaAction) -> AiContestArenaObservation:
+        self._state.step_count += 1
+
+        if not hasattr(self, '_task') or not self._task or 'prompt' not in self._task:
+            self._task = random.choice(TASKS)
+
+        reward, feedback = _call_judge(
+            problem=self._task["prompt"],
+            answer_a=action.answer,
+            answer_b=self._task["baseline"],
+        )
+
+        self._state.judge_feedback = feedback
+
+        return AiContestArenaObservation(
+            task_prompt=self._task["prompt"],
+            judge_feedback=feedback,
+            done=True,
+            reward=reward,
+            metadata={"difficulty": self._task["difficulty"], "raw_reward": reward},
+        )
+
+    @property
+    def state(self) -> AiContestArenaState:
+        return self._state

ai_contest_arena/server/app.py

@@ -0,0 +1,56 @@
+# 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 Multi-Agent Contest Arena Environment.
+
+Endpoints:
+    POST /reset  — randomly select a task (Easy / Medium / Hard)
+    POST /step   — submit Contestant A's answer; LLM Judge scores it vs baseline
+    GET  /state  — current task and latest judge feedback
+    GET  /schema — action/observation schemas
+    WS   /ws     — WebSocket endpoint for persistent sessions
+
+Usage:
+    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+"""
+
+try:
+    from openenv.core.env_server.http_server import create_app
+except Exception as e:  # pragma: no cover
+    raise ImportError(
+        "openenv is required. Install dependencies with '\n    uv sync\n'"
+    ) from e
+
+try:
+    from ..models import AiContestArenaAction, AiContestArenaObservation
+    from .ai_contest_arena_environment import AiContestArenaEnvironment
+except ImportError:
+    from models import AiContestArenaAction, AiContestArenaObservation
+    from server.ai_contest_arena_environment import AiContestArenaEnvironment
+
+
+app = create_app(
+    AiContestArenaEnvironment,
+    AiContestArenaAction,
+    AiContestArenaObservation,
+    env_name="ai_contest_arena",
+    max_concurrent_envs=1,
+)
+
+
+def main(host: str = "0.0.0.0", port: int = 8000):
+    import uvicorn
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--port", type=int, default=8000)
+    args = parser.parse_args()
+    main(port=args.port)

ai_contest_arena/server/requirements.txt

@@ -0,0 +1,4 @@
+openenv-core[core]
+fastapi
+uvicorn
+openai

ai_contest_arena/task.json

@@ -0,0 +1,17 @@
+[
+  {
+    "id": "task_1_coding",
+    "prompt": "Write a Python function named `is_even(n)` that returns True if a number is even, and False if it is odd. Only output the code.",
+    "rubric": "The answer must contain a valid Python function named is_even. Return 1.0 if correct, else 0.0."
+  },
+  {
+    "id": "task_2_logic",
+    "prompt": "Explain the core concept of 'Quantum Computing' in exactly one simple sentence.",
+    "rubric": "The answer must be exactly one sentence and mention qubits or superposition/entanglement. Return 1.0 for perfect, 0.5 for okay, 0.0 for wrong."
+  },
+  {
+    "id": "task_3_general",
+    "prompt": "What is the capital city of France? Answer in one word.",
+    "rubric": "The answer must be 'Paris'. Return 1.0 if correct, else 0.0."
+  }
+]

ai_server_admin/Dockerfile

@@ -0,0 +1,80 @@
+# 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.
+
+# Multi-stage build using openenv-base
+# This Dockerfile is flexible and works for both:
+# - In-repo environments (with local OpenEnv sources)
+# - Standalone environments (with openenv from PyPI/Git)
+# The build script (openenv build) handles context detection and sets appropriate build args.
+
+ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
+FROM ${BASE_IMAGE} AS builder
+
+WORKDIR /app
+
+# Ensure git is available (required for installing dependencies from VCS)
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends git && \
+    rm -rf /var/lib/apt/lists/*
+
+# Build argument to control whether we're building standalone or in-repo
+ARG BUILD_MODE=in-repo
+ARG ENV_NAME=ai_server_admin
+
+# Copy environment code (always at root of build context)
+COPY . /app/env
+
+# For in-repo builds, openenv is already vendored in the build context
+# For standalone builds, openenv will be installed via pyproject.toml
+WORKDIR /app/env
+
+# Ensure uv is available (for local builds where base image lacks it)
+RUN if ! command -v uv >/dev/null 2>&1; then \
+        curl -LsSf https://astral.sh/uv/install.sh | sh && \
+        mv /root/.local/bin/uv /usr/local/bin/uv && \
+        mv /root/.local/bin/uvx /usr/local/bin/uvx; \
+    fi
+    
+# Install dependencies using uv sync
+# If uv.lock exists, use it; otherwise resolve on the fly
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-install-project --no-editable; \
+    else \
+        uv sync --no-install-project --no-editable; \
+    fi
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-editable; \
+    else \
+        uv sync --no-editable; \
+    fi
+
+# Final runtime stage
+FROM ${BASE_IMAGE}
+
+WORKDIR /app
+
+# Copy the virtual environment from builder
+COPY --from=builder /app/env/.venv /app/.venv
+
+# Copy the environment code
+COPY --from=builder /app/env /app/env
+
+# Set PATH to use the virtual environment
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Set PYTHONPATH so imports work correctly
+ENV PYTHONPATH="/app/env:$PYTHONPATH"
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Run the FastAPI server
+# The module path is constructed to work with the /app/env structure
+CMD ["sh", "-c", "cd /app/env && uvicorn server.app:app --host 0.0.0.0 --port 8000"]

ai_server_admin/README.md

@@ -0,0 +1,255 @@
+---
+title: Ai Server Admin Environment Server
+emoji: 🖥️
+colorFrom: green
+colorTo: yellow
+sdk: docker
+pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
+---
+
+# Ai Server Admin Environment
+
+A simple test environment that echoes back messages. Perfect for testing the env APIs as well as demonstrating environment usage patterns.
+
+## Quick Start
+
+The simplest way to use the Ai Server Admin environment is through the `AiServerAdminEnv` class:
+
+```python
+from ai_server_admin import AiServerAdminAction, AiServerAdminEnv
+
+try:
+    # Create environment from Docker image
+    ai_server_adminenv = AiServerAdminEnv.from_docker_image("ai_server_admin-env:latest")
+
+    # Reset
+    result = ai_server_adminenv.reset()
+    print(f"Reset: {result.observation.echoed_message}")
+
+    # Send multiple messages
+    messages = ["Hello, World!", "Testing echo", "Final message"]
+
+    for msg in messages:
+        result = ai_server_adminenv.step(AiServerAdminAction(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}")
+
+finally:
+    # Always clean up
+    ai_server_adminenv.close()
+```
+
+That's it! The `AiServerAdminEnv.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:
+
+```bash
+# From project root
+docker build -t ai_server_admin-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:
+
+```bash
+# 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
+
+```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/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
+- **WebSocket** at `/ws` - Persistent session endpoint for low-latency interactions
+
+## Environment Details
+
+### Action
+**AiServerAdminAction**: Contains a single field
+- `message` (str) - The message to echo back
+
+### Observation
+**AiServerAdminObservation**: 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
+
+### Reward
+The reward is calculated as: `message_length × 0.1`
+- "Hi" → reward: 0.2
+- "Hello, World!" → reward: 1.3
+- Empty message → reward: 0.0
+
+## Advanced Usage
+
+### Connecting to an Existing Server
+
+If you already have a Ai Server Admin environment server running, you can connect directly:
+
+```python
+from ai_server_admin import AiServerAdminEnv
+
+# Connect to existing server
+ai_server_adminenv = AiServerAdminEnv(base_url="<ENV_HTTP_URL_HERE>")
+
+# Use as normal
+result = ai_server_adminenv.reset()
+result = ai_server_adminenv.step(AiServerAdminAction(message="Hello!"))
+```
+
+Note: When connecting to an existing server, `ai_server_adminenv.close()` will NOT stop the server.
+
+### Using the Context Manager
+
+The client supports context manager usage for automatic connection management:
+
+```python
+from ai_server_admin import AiServerAdminAction, AiServerAdminEnv
+
+# Connect with context manager (auto-connects and closes)
+with AiServerAdminEnv(base_url="http://localhost:8000") as env:
+    result = env.reset()
+    print(f"Reset: {result.observation.echoed_message}")
+    # Multiple steps with low latency
+    for msg in ["Hello", "World", "!"]:
+        result = env.step(AiServerAdminAction(message=msg))
+        print(f"Echoed: {result.observation.echoed_message}")
+```
+
+The client uses WebSocket connections for:
+- **Lower latency**: No HTTP connection overhead per request
+- **Persistent session**: Server maintains your environment state
+- **Efficient for episodes**: Better for many sequential steps
+
+### Concurrent WebSocket Sessions
+
+The server supports multiple concurrent WebSocket connections. To enable this,
+modify `server/app.py` to use factory mode:
+
+```python
+# In server/app.py - use factory mode for concurrent sessions
+app = create_app(
+    AiServerAdminEnvironment,  # Pass class, not instance
+    AiServerAdminAction,
+    AiServerAdminObservation,
+    max_concurrent_envs=4,  # Allow 4 concurrent sessions
+)
+```
+
+Then multiple clients can connect simultaneously:
+
+```python
+from ai_server_admin import AiServerAdminAction, AiServerAdminEnv
+from concurrent.futures import ThreadPoolExecutor
+
+def run_episode(client_id: int):
+    with AiServerAdminEnv(base_url="http://localhost:8000") as env:
+        result = env.reset()
+        for i in range(10):
+            result = env.step(AiServerAdminAction(message=f"Client {client_id}, step {i}"))
+        return client_id, result.observation.message_length
+
+# Run 4 episodes concurrently
+with ThreadPoolExecutor(max_workers=4) as executor:
+    results = list(executor.map(run_episode, range(4)))
+```
+
+## Development & Testing
+
+### Direct Environment Testing
+
+Test the environment logic directly without starting the HTTP server:
+
+```bash
+# From the server directory
+python3 server/ai_server_admin_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:
+
+```bash
+uvicorn server.app:app --reload
+```
+
+## Project Structure
+
+```
+ai_server_admin/
+├── .dockerignore         # Docker build exclusions
+├── __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              # AiServerAdminEnv client
+├── models.py              # Action and Observation models
+└── server/
+    ├── __init__.py        # Server module exports
+    ├── ai_server_admin_environment.py  # Core environment logic
+    ├── app.py             # FastAPI application (HTTP + WebSocket endpoints)
+    └── Dockerfile         # Container image definition
+```

ai_server_admin/__init__.py

@@ -0,0 +1,16 @@
+# 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.
+
+"""Ai Server Admin Environment."""
+
+from .client import AiServerAdminEnv
+from .models import AiServerAdminAction, AiServerAdminObservation
+
+__all__ = [
+    "AiServerAdminAction",
+    "AiServerAdminObservation",
+    "AiServerAdminEnv",
+]

ai_server_admin/client.py

@@ -0,0 +1,99 @@
+# 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.
+
+"""Ai Server Admin Environment Client."""
+
+from typing import Dict
+
+from openenv.core import EnvClient
+from openenv.core.client_types import StepResult
+from openenv.core.env_server.types import State
+
+from .models import AiServerAdminAction, AiServerAdminObservation
+
+
+class AiServerAdminEnv(
+    EnvClient[AiServerAdminAction, AiServerAdminObservation, State]
+):
+    """
+    Client for the Ai Server Admin Environment.
+
+    This client maintains a persistent WebSocket connection to the environment server,
+    enabling efficient multi-step interactions with lower latency.
+    Each client instance has its own dedicated environment session on the server.
+
+    Example:
+        >>> # Connect to a running server
+        >>> with AiServerAdminEnv(base_url="http://localhost:8000") as client:
+        ...     result = client.reset()
+        ...     print(result.observation.echoed_message)
+        ...
+        ...     result = client.step(AiServerAdminAction(message="Hello!"))
+        ...     print(result.observation.echoed_message)
+
+    Example with Docker:
+        >>> # Automatically start container and connect
+        >>> client = AiServerAdminEnv.from_docker_image("ai_server_admin-env:latest")
+        >>> try:
+        ...     result = client.reset()
+        ...     result = client.step(AiServerAdminAction(message="Test"))
+        ... finally:
+        ...     client.close()
+    """
+
+    def _step_payload(self, action: AiServerAdminAction) -> Dict:
+        """
+        Convert AiServerAdminAction to JSON payload for step message.
+
+        Args:
+            action: AiServerAdminAction instance
+
+        Returns:
+            Dictionary representation suitable for JSON encoding
+        """
+        return {
+            "message": action.message,
+        }
+
+    def _parse_result(self, payload: Dict) -> StepResult[AiServerAdminObservation]:
+        """
+        Parse server response into StepResult[AiServerAdminObservation].
+
+        Args:
+            payload: JSON response data from server
+
+        Returns:
+            StepResult with AiServerAdminObservation
+        """
+        obs_data = payload.get("observation", {})
+        observation = AiServerAdminObservation(
+            echoed_message=obs_data.get("echoed_message", ""),
+            message_length=obs_data.get("message_length", 0),
+            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) -> State:
+        """
+        Parse server response into State object.
+
+        Args:
+            payload: JSON response from state request
+
+        Returns:
+            State object with episode_id and step_count
+        """
+        return State(
+            episode_id=payload.get("episode_id"),
+            step_count=payload.get("step_count", 0),
+        )

ai_server_admin/models.py

@@ -0,0 +1,27 @@
+# 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 the Ai Server Admin Environment.
+
+The ai_server_admin environment is a simple test environment that echoes back messages.
+"""
+
+from openenv.core.env_server.types import Action, Observation
+from pydantic import Field
+
+
+class AiServerAdminAction(Action):
+    """Action for the Ai Server Admin environment - just a message to echo."""
+
+    message: str = Field(..., description="Message to echo back")
+
+
+class AiServerAdminObservation(Observation):
+    """Observation from the Ai Server Admin environment - the echoed message."""
+
+    echoed_message: str = Field(default="", description="The echoed message")
+    message_length: int = Field(default=0, description="Length of the echoed message")

ai_server_admin/openenv.yaml

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

ai_server_admin/pyproject.toml

@@ -0,0 +1,45 @@
+# 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-ai_server_admin"
+version = "0.1.0"
+description = "Ai Server Admin environment for OpenEnv"
+requires-python = ">=3.10"
+dependencies = [
+    # Core OpenEnv runtime (provides FastAPI server + HTTP client types)
+    # install from github
+    # "openenv-core[core] @ git+https://github.com/meta-pytorch/OpenEnv.git",
+    "openenv-core[core]>=0.2.2",
+    # Environment-specific dependencies
+    # Add all dependencies needed for your environment here
+    # Examples:
+    # "numpy>=1.19.0",
+    # "torch>=2.0.0",
+    # "gymnasium>=0.29.0",
+    # "openspiel>=1.0.0",
+    # "smolagents>=1.22.0,<2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.scripts]
+# Server entry point - enables running via: uv run --project . server
+# or: python -m ai_server_admin.server.app
+server = "ai_server_admin.server.app:main"
+
+[tool.setuptools]
+include-package-data = true
+packages = ["ai_server_admin", "ai_server_admin.server"]
+package-dir = { "ai_server_admin" = ".", "ai_server_admin.server" = "server" }

ai_server_admin/pyrightconfig.json

@@ -0,0 +1,8 @@
+{
+  "venvPath": ".",
+  "venv": ".venv",
+  "pythonVersion": "3.10",
+  "typeCheckingMode": "basic",
+  "reportMissingImports": "warning",
+  "reportMissingModuleSource": "none"
+}

ai_server_admin/server/__init__.py

@@ -0,0 +1,11 @@
+# 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.
+
+"""Ai Server Admin environment server components."""
+
+from .ai_server_admin_environment import AiServerAdminEnvironment
+
+__all__ = ["AiServerAdminEnvironment"]

ai_server_admin/server/ai_server_admin_environment.py

@@ -0,0 +1,62 @@
+import os, json, random, requests
+from uuid import uuid4
+from openenv.core.env_server.interfaces import Environment
+from openenv.core.env_server.types import State
+
+try:
+    from ..models import AiServerAdminAction, AiServerAdminObservation
+except ImportError:
+    from models import AiServerAdminAction, AiServerAdminObservation
+
+class AiServerAdminEnvironment(Environment):
+    SUPPORTS_CONCURRENT_SESSIONS: bool = True
+
+    def __init__(self):
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self.current_task = None
+        tasks_path = os.path.join(os.path.dirname(__file__), "..", "tasks.json")
+        try:
+            with open(tasks_path, "r") as f: self.tasks = json.load(f)
+        except Exception:
+            with open("tasks.json", "r") as f: self.tasks = json.load(f)
+
+    def reset(self) -> AiServerAdminObservation:
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self.current_task = random.choice(self.tasks)
+        return AiServerAdminObservation(
+            echoed_message=f"[NEW TASK]: {self.current_task['prompt']}",
+            message_length=0, done=False, reward=0.0
+        )
+
+    def step(self, action: AiServerAdminAction) -> AiServerAdminObservation:
+        self._state.step_count += 1
+        agent_answer = action.message
+        reward = self._judge_code(agent_answer)
+        return AiServerAdminObservation(
+            echoed_message="Evaluation Complete.",
+            message_length=len(agent_answer), done=True, reward=reward,
+        )
+
+    def _judge_code(self, agent_answer: str) -> float:
+        openai_key = os.environ.get("OPENAI_API_KEY", "")
+        if not openai_key: return 0.5
+
+        headers = {"Authorization": f"Bearer {openai_key}", "Content-Type": "application/json"}
+        payload = {
+            "model": "gpt-4o-mini",
+            "messages": [
+                {"role": "system", "content": "You are a strict AI Judge. Evaluate the answer based on the rubric. Output ONLY a single float number between 0.0 and 1.0. No extra text."},
+                {"role": "user", "content": f"Task: {self.current_task['prompt']}\nRubric: {self.current_task['rubric']}\nAgent Answer: {agent_answer}"}
+            ]
+        }
+
+        try:
+            resp = requests.post("https://api.openai.com/v1/chat/completions", json=payload, headers=headers)
+            resp.raise_for_status()
+            score_str = resp.json()["choices"][0]["message"]["content"].strip()
+            return min(max(float(score_str), 0.0), 1.0)
+        except Exception:
+            return 0.0
+
+    @property
+    def state(self) -> State: return self._state

ai_server_admin/server/app.py

@@ -0,0 +1,84 @@
+# 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 Ai Server Admin Environment.
+
+This module creates an HTTP server that exposes the AiServerAdminEnvironment
+over HTTP and WebSocket endpoints, compatible with EnvClient.
+
+Endpoints:
+    - POST /reset: Reset the environment
+    - POST /step: Execute an action
+    - GET /state: Get current environment state
+    - GET /schema: Get action/observation schemas
+    - WS /ws: WebSocket endpoint for persistent sessions
+
+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:
+    python -m server.app
+"""
+
+try:
+    from openenv.core.env_server.http_server import create_app
+except Exception as e:  # pragma: no cover
+    raise ImportError(
+        "openenv is required for the web interface. Install dependencies with '\n    uv sync\n'"
+    ) from e
+
+try:
+    from ..models import AiServerAdminAction, AiServerAdminObservation
+    from .ai_server_admin_environment import AiServerAdminEnvironment
+except ModuleNotFoundError:
+    from models import AiServerAdminAction, AiServerAdminObservation
+    from server.ai_server_admin_environment import AiServerAdminEnvironment
+
+
+# Create the app with web interface and README integration
+app = create_app(
+    AiServerAdminEnvironment,
+    AiServerAdminAction,
+    AiServerAdminObservation,
+    env_name="ai_server_admin",
+    max_concurrent_envs=1,  # increase this number to allow more concurrent WebSocket sessions
+)
+
+
+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 ai_server_admin.server.app
+
+    Args:
+        host: Host address to bind to (default: "0.0.0.0")
+        port: Port number to listen on (default: 8000)
+
+    For production deployments, consider using uvicorn directly with
+    multiple workers:
+        uvicorn ai_server_admin.server.app:app --workers 4
+    """
+    import uvicorn
+
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--port", type=int, default=8000)
+    args = parser.parse_args()
+    main(port=args.port)

ai_server_admin/server/requirements.txt

@@ -0,0 +1,6 @@
+openenv[core]>=0.2.0
+fastapi>=0.115.0
+uvicorn>=0.24.0
+
+
+

inference.py

@@ -0,0 +1,86 @@
+import os, sys, requests, json, time
+from openai import OpenAI
+
+ENV_BASE_URL = "http://localhost:8000"
+
+def play_round(round_number):
+    print(f"\n{'='*50}\n🏁 ROUND {round_number} STARTS!\n{'='*50}")
+    
+    # 1. Get Task safely
+    try:
+        resp = requests.post(f"{ENV_BASE_URL}/reset", timeout=120).json()
+    except Exception as e:
+        sys.exit(f"🚨 Error: Cannot connect to OpenEnv Server. {e}")
+
+    task = ""
+    if isinstance(resp, dict):
+        if "observation" in resp and isinstance(resp["observation"], dict) and "echoed_message" in resp["observation"]:
+            task = resp["observation"]["echoed_message"]
+        elif "observation" in resp and isinstance(resp["observation"], dict) and "task_prompt" in resp["observation"]:
+             task = resp["observation"]["task_prompt"]
+        elif "echoed_message" in resp:
+            task = resp["echoed_message"]
+        else:
+            task = json.dumps(resp)
+    else:
+        task = str(resp)
+        
+    print(f"🔥 JUDGE ASKS:\n{task}\n")
+
+    # 2. Qwen Agent API Call (Working on HF Router)
+    print("🤖 Agent is thinking (Using Qwen 2.5)...")
+    hf_token = os.environ.get("HF_TOKEN", "")
+    if not hf_token:
+        print("🚨 WARNING: HF_TOKEN is missing. Please set it in your environment variables.")
+        
+    client = OpenAI(
+        base_url="https://router.huggingface.co/v1",
+        api_key=hf_token
+    )
+    
+    try:
+        completion = client.chat.completions.create(
+            model="Qwen/Qwen2.5-72B-Instruct",
+            messages=[
+                {"role": "system", "content": "You are a Python expert. Output ONLY valid Python code. No explanations, no markdown blocks like ```python."},
+                {"role": "user", "content": task}
+            ],
+        )
+        agent_answer = completion.choices[0].message.content.replace("```python", "").replace("```", "").strip()
+    except Exception as e:
+        print(f"🚨 HF API Error: {e}")
+        agent_answer = "def generic_answer(): pass"
+
+    print(f"🗣️ AGENT'S ANSWER (Snippet):\n{agent_answer[:150]}...\n")
+    
+    # 3. Submit to Server (Direct Payload)
+    print("⚖️ Submitting to Judge...")
+    payload = {"action": {"answer": agent_answer}}
+    try:
+        step_resp = requests.post(f"{ENV_BASE_URL}/step", json=payload, timeout=120)
+        
+        if step_resp.status_code == 200:
+            result = step_resp.json()
+            score = result.get("observation", {}).get("reward", result.get("reward", 0.0))
+        else:
+            print(f"🚨 Server Error! Status: {step_resp.status_code}")
+            print(f"🚨 Details: {step_resp.text}")
+            score = 0.0
+             
+    except Exception as e:
+        print(f"🚨 Server Communication Error: {e}")
+        score = 0.0
+        
+    print(f"🏆 ROUND {round_number} SCORE : {score} / 1.0")
+    return score
+
+def main():
+    print("🚀 [START] GEMMA AGENT vs OPENAI JUDGE")
+    total_score = 0
+    for i in range(1, 4):
+        total_score += play_round(i)
+        time.sleep(2) 
+    print(f"\n🎉🎉 MATCH FINISHED! FINAL TOTAL SCORE: {total_score} / 3.0 🎉🎉")
+
+if __name__ == "__main__":
+    main()

requirements.txt

@@ -0,0 +1,3 @@
+requests==2.33.1
+openai==2.7.2
+pydantic==2.11.7