--- title: Python Env Environment Server emoji: 🎶 colorFrom: purple colorTo: red sdk: docker pinned: false app_port: 8000 base_path: /web tags: - openenv --- # Python Code Review Environment This repository now hosts a deterministic OpenEnv benchmark for Python code review. Agents review snippets one step at a time and receive dense rewards, `done` flags, precision/recall/F1 metrics, and task-specific grading suitable for RL training or evaluation. Active task families: - `task_easy`: style and convention review - `task_medium`: logic bug detection - `task_hard`: security vulnerability audit Use the action schema in `models.py`, the runtime in `server/python_env_environment.py`, and the rollout loop in `inference.py` / `rollout.py` as the current source of truth. The remaining template sections below are legacy scaffolding and may lag behind the benchmark implementation. ## Quick Start The simplest way to use the Python Env environment is through the `PythonEnv` class: ```python from python_env import PythonAction, PythonEnv try: # Create environment from Docker image python_envenv = PythonEnv.from_docker_image("python_env-env:latest") # Reset result = python_envenv.reset() print(f"Reset: {result.observation.echoed_message}") # Send multiple messages messages = ["Hello, World!", "Testing echo", "Final message"] for msg in messages: result = python_envenv.step(PythonAction(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 python_envenv.close() ``` That's it! The `PythonEnv.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 python_env-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/` 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 **PythonAction**: Contains a single field - `message` (str) - The message to echo back ### Observation **PythonObservation**: 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 Python Env environment server running, you can connect directly: ```python from python_env import PythonEnv # Connect to existing server python_envenv = PythonEnv(base_url="") # Use as normal result = python_envenv.reset() result = python_envenv.step(PythonAction(message="Hello!")) ``` Note: When connecting to an existing server, `python_envenv.close()` will NOT stop the server. ### Using the Context Manager The client supports context manager usage for automatic connection management: ```python from python_env import PythonAction, PythonEnv # Connect with context manager (auto-connects and closes) with PythonEnv(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(PythonAction(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( PythonEnvironment, # Pass class, not instance PythonAction, PythonObservation, max_concurrent_envs=4, # Allow 4 concurrent sessions ) ``` Then multiple clients can connect simultaneously: ```python from python_env import PythonAction, PythonEnv from concurrent.futures import ThreadPoolExecutor def run_episode(client_id: int): with PythonEnv(base_url="http://localhost:8000") as env: result = env.reset() for i in range(10): result = env.step(PythonAction(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/python_env_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 ``` python_env/ ├── .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 # PythonEnv client ├── models.py # Action and Observation models └── server/ ├── __init__.py # Server module exports ├── python_env_environment.py # Core environment logic ├── app.py # FastAPI application (HTTP + WebSocket endpoints) └── Dockerfile # Container image definition ``` --------------------------------------- cd F:\python_env # Edit your environment implementation in server/python_env_environment.py # Edit your models in models.py # Install dependencies: uv sync # To integrate into OpenEnv repo: # 1. Copy this directory to /envs/python_env_env # 2. Build from repo root: docker build -t python_env_env:latest -f envs/python_env_env/server/Dockerfile . # 3. Run your image: docker run -p 8000:8000 python_env_env:latest