Spaces:
Sleeping
Sleeping
| 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/<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 | |
| **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="<ENV_HTTP_URL_HERE>") | |
| # 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 <repo_root>/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 | |