openenv-testing/android_env-pr-162

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- **HTTPEnvClient**: Generic HTTP client for interacting with remote environments26- **HTTPEnvServer**: FastAPI-based server wrapper for exposing environments over HTTP27- **Container Providers**: Pluggable architecture for running containers (Docker, Kubernetes, etc.)28- **Type System**: Strongly-typed Action/Observation/State interfaces29- **Web Interface**: Optional web UI for interacting with environments30 31## Installation32 33```bash34pip install openenv-core35```36 37For development:38```bash39pip install openenv-core[dev]40```41 42## Quick Start43 44### Creating an Environment Client45 46```python47from openenv_core import HTTPEnvClient, StepResult48from dataclasses import dataclass49 50@dataclass51class MyAction:52    text: str53 54@dataclass55class MyObservation:56    response: str57 58class MyEnvClient(HTTPEnvClient[MyAction, MyObservation]):59    def _step_payload(self, action: MyAction) -> dict:60        return {"text": action.text}61 62    def _parse_result(self, payload: dict) -> StepResult[MyObservation]:63        obs_data = payload["observation"]64        return StepResult(65            observation=MyObservation(**obs_data),66            reward=payload.get("reward"),67            done=payload.get("done", False)68        )69 70    def _parse_state(self, payload: dict) -> Any:71        return payload72 73# Use with Docker74env = MyEnvClient.from_docker_image("my-env:latest")75result = env.reset()76step_result = env.step(MyAction(text="hello"))77env.close()78```79 80### Creating an Environment Server81 82```python83from openenv_core.env_server import Environment, HTTPEnvServer, create_app84from dataclasses import dataclass85 86@dataclass87class MyAction:88    text: str89 90@dataclass91class MyObservation:92    response: str93    reward: float = 0.094    done: bool = False95 96class MyEnvironment(Environment):97    def reset(self) -> MyObservation:98        return MyObservation(response="Ready")99 100    def step(self, action: MyAction) -> MyObservation:101        return MyObservation(102            response=f"Echo: {action.text}",103            reward=1.0,104            done=False105        )106 107# Create FastAPI app108env = MyEnvironment()109app = create_app(env, MyAction, MyObservation)110 111# Run with: uvicorn module:app --host 0.0.0.0 --port 8000112```113 114## Container Providers115 116OpenEnv Core supports multiple container providers:117 118### Local Docker Provider119 120```python121from openenv_core.containers.runtime import LocalDockerProvider122 123provider = LocalDockerProvider()124base_url = provider.start_container("my-env:latest")125provider.wait_for_ready(base_url)126# Use environment...127provider.stop_container()128```129 130### Kubernetes Provider (Coming Soon)131 132```python133from openenv_core.containers.runtime import KubernetesProvider134 135provider = KubernetesProvider(namespace="envs")136base_url = provider.start_container("my-env:latest")137# Use environment...138provider.stop_container()139```140 141 142## API Reference143 144### HTTPEnvClient145 146Base class for environment clients with these abstract methods:147 148- `_step_payload(action)`: Convert action to JSON149- `_parse_result(payload)`: Parse response to StepResult150- `_parse_state(payload)`: Parse state response151 152### HTTPEnvServer153 154Server wrapper with these methods:155 156- `register_routes(app)`: Register endpoints on FastAPI app157- `_deserialize_action(data)`: Convert JSON to Action158- `_serialize_observation(obs)`: Convert Observation to JSON159 160### Environment Interface161 162Base interface for environment implementations:163 164- `reset()`: Reset environment and return initial observation165- `step(action)`: Execute action and return observation166- `state`: Property returning current environment state167 168## License169 170This project is licensed under the BSD-3-Clause License - see the LICENSE file for details.171 172## Contributing173 174Contributions are welcome! Please see the main OpenEnv repository for contribution guidelines.175 176## Links177 178- **Homepage**: https://github.com/facebookresearch/OpenEnv179- **Documentation**: https://github.com/facebookresearch/OpenEnv/blob/main/README.md180- **Bug Tracker**: https://github.com/facebookresearch/OpenEnv/issues181