openenv/repl

1# <img width="35" height="35" alt="image" src="https://github.com/user-attachments/assets/2700a971-e5d6-4036-b03f-2f89c9791609" /> OpenEnv: Agentic Execution Environments2 3An e2e framework for creating, deploying and using isolated execution environments for agentic RL training, built using Gymnasium style simple APIs. OpenEnv provides a standard for interacting with agentic execution environments via simple Gymnasium style APIs - step(), reset(), state(). Users of agentic execution environments can interact with the environment during RL training loops using these simple APIs.4 5In addition to making it easier for researchers and RL framework writers, we also provide tools for environment creators making it easier for them to create richer environments and make them available over familiar protocols like HTTP and packaged using canonical technologies like docker. Environment creators can use the OpenEnv framework to create environments that are isolated, secure, and easy to deploy and use.6 7 8## Overview9`openenv.core` provides the foundational building blocks for creating and interacting with containerized environments over HTTP. It enables you to build agent environments that can be deployed as Docker containers and accessed via a simple HTTP API.10 11> ⚠️ **Early Development Warning** OpenEnv is currently in an experimental12> stage. You should expect bugs, incomplete features, and APIs that may change13> in future versions. The project welcomes bugfixes, but to make sure things are14> well coordinated you should discuss any significant change before starting the15> work. It's recommended that you signal your intention to contribute in the16> issue tracker, either by filing a new issue or by claiming an existing one.17 18 19# OpenEnv Core20 21Core components for OpenEnv - a framework for building HTTP-based agentic environments.22 23## Features24 25- **EnvClient**: Async-first client for interacting with remote environments26- **SyncEnvClient**: Synchronous wrapper via `.sync()` for sync codebases27- **HTTPEnvServer**: FastAPI-based server wrapper for exposing environments over HTTP/WebSocket28- **Container Providers**: Pluggable architecture for running containers (Docker, Kubernetes, etc.)29- **Type System**: Strongly-typed Action/Observation/State interfaces30- **Web Interface**: Optional web UI for interacting with environments31 32## Installation33 34```bash35pip install "openenv[core]"36```37 38For development:39```bash40pip install "openenv[core]"41```42 43## Quick Start44 45### Creating an Environment Client46 47EnvClient is **async by default**. Use `async with` and `await` for all operations:48 49```python50import asyncio51from openenv.core import EnvClient, StepResult52from dataclasses import dataclass53from typing import Any54 55@dataclass56class MyAction:57    text: str58 59@dataclass60class MyObservation:61    response: str62 63class MyEnvClient(EnvClient[MyAction, MyObservation, Any]):64    def _step_payload(self, action: MyAction) -> dict:65        return {"text": action.text}66 67    def _parse_result(self, payload: dict) -> StepResult[MyObservation]:68        obs_data = payload["observation"]69        return StepResult(70            observation=MyObservation(**obs_data),71            reward=payload.get("reward"),72            done=payload.get("done", False)73        )74 75    def _parse_state(self, payload: dict) -> Any:76        return payload77 78# Async usage (recommended)79async def main():80    client = await MyEnvClient.from_docker_image("my-env:latest")81    async with client:82        result = await client.reset()83        step_result = await client.step(MyAction(text="hello"))84 85asyncio.run(main())86 87# Sync usage (via .sync() wrapper)88with MyEnvClient(base_url="http://localhost:8000").sync() as client:89    result = client.reset()90    step_result = client.step(MyAction(text="hello"))91```92 93### Creating an Environment Server94 95```python96from openenv.core.env_server import Environment, HTTPEnvServer, create_app97from dataclasses import dataclass98 99@dataclass100class MyAction:101    text: str102 103@dataclass104class MyObservation:105    response: str106    reward: float = 0.0107    done: bool = False108 109class MyEnvironment(Environment):110    def reset(self) -> MyObservation:111        return MyObservation(response="Ready")112 113    def step(self, action: MyAction) -> MyObservation:114        return MyObservation(115            response=f"Echo: {action.text}",116            reward=1.0,117            done=False118        )119 120# Create FastAPI app121env = MyEnvironment()122app = create_app(env, MyAction, MyObservation)123 124# Run with: uvicorn module:app --host 0.0.0.0 --port 8000125```126 127## Container Providers128 129OpenEnv Core supports multiple container providers:130 131### Local Docker Provider132 133```python134from openenv.core.containers.runtime import LocalDockerProvider135 136provider = LocalDockerProvider()137base_url = provider.start_container("my-env:latest")138provider.wait_for_ready(base_url)139# Use environment...140provider.stop_container()141```142 143### Kubernetes Provider (Coming Soon)144 145```python146from openenv.core.containers.runtime import KubernetesProvider147 148provider = KubernetesProvider(namespace="envs")149base_url = provider.start_container("my-env:latest")150# Use environment...151provider.stop_container()152```153 154 155## API Reference156 157### EnvClient158 159Async base class for environment clients. Key methods:160 161- `async connect()`: Establish WebSocket connection162- `async reset(**kwargs)`: Reset environment163- `async step(action)`: Execute action164- `async state()`: Get current state165- `async close()`: Close connection and cleanup166- `sync()`: Return a SyncEnvClient wrapper for synchronous usage167 168Abstract methods to implement:169- `_step_payload(action)`: Convert action to JSON170- `_parse_result(payload)`: Parse response to StepResult171- `_parse_state(payload)`: Parse state response172 173### SyncEnvClient174 175Synchronous wrapper around EnvClient. Use `client.sync()` to get one:176 177```python178sync_client = async_client.sync()179with sync_client:180    result = sync_client.reset()181    result = sync_client.step(action)182```183 184### HTTPEnvServer185 186Server wrapper with these methods:187 188- `register_routes(app)`: Register endpoints on FastAPI app189- `_deserialize_action(data)`: Convert JSON to Action190- `_serialize_observation(obs)`: Convert Observation to JSON191 192### Environment Interface193 194Base interface for environment implementations:195 196- `reset()`: Reset environment and return initial observation197- `step(action)`: Execute action and return observation198- `state`: Property returning current environment state199 200## License201 202This project is licensed under the BSD-3-Clause License - see the LICENSE file for details.203 204## Contributing205 206Contributions are welcome! Please see the main OpenEnv repository for contribution guidelines.207 208## Links209 210- **Homepage**: https://github.com/meta-pytorch/OpenEnv211- **Documentation**: https://github.com/meta-pytorch/OpenEnv/blob/main/README.md212- **Bug Tracker**: https://github.com/meta-pytorch/OpenEnv/issues213