hanabhi/gridworld-env

1On this page we will walk you through the process of using an OpenEnv environment. If you want to build your own environment, please see the [Building an Environment](environment-builder.md) page.2 3## Installation4 5To install the OpenEnv package, you can use the following command:6 7```bash8pip install openenv-core9```10 11!!! note12    This installs both the `openenv` CLI and the `openenv.core` runtime. Environment projects can depend on `openenv-core[core]` if they only need the server/client libraries.13 14### Using the Echo Environment (Example)15 16Let's start by using the Echo Environment. This is a simple environment that echoes back messages.17 18Install the echo environment client package:19 20```bash21pip install git+https://huggingface.co/spaces/openenv/echo-env 22```23 24Then you can use the environment. The client is **async by default**:25 26```python27import asyncio28from echo_env import EchoAction, EchoEnv29 30async def main():31    async with EchoEnv(base_url="https://openenv-echo-env.hf.space") as client:32        # Reset the environment33        result = await client.reset()34        print(result.observation.echoed_message)  # "Echo environment ready!"35 36        # Send messages37        result = await client.step(EchoAction(message="Hello, World!"))38        print(result.observation.echoed_message)  # "Hello, World!"39        print(result.reward)  # 1.3 (based on message length)40 41asyncio.run(main())42```43 44For **synchronous usage**, use the `.sync()` wrapper:45 46```python47from echo_env import EchoAction, EchoEnv48 49with EchoEnv(base_url="https://openenv-echo-env.hf.space").sync() as client:50    result = client.reset()51    result = client.step(EchoAction(message="Hello, World!"))52    print(result.observation.echoed_message)53```54 55### Using environments from Hugging Face56 57You can also use environments from Hugging Face. To do this, you can use the `from_env` method of the environment class.58 59```python60import asyncio61from echo_env import EchoEnv62 63async def main():64    # Pulls from Hugging Face and starts a container65    client = await EchoEnv.from_env("openenv/echo_env")66    async with client:67        result = await client.reset()68        print(result.observation)69 70asyncio.run(main())71```72 73In the background, the environment will be pulled from Hugging Face and a container will be started on your local machine.74 75You can also connect to the remote space on Hugging Face by passing the base URL to the environment class.76 77```python78async with EchoEnv(base_url="https://openenv-echo-env.hf.space") as client:79    result = await client.reset()80```81 82### Using Docker containers83 84You can also use environments from Docker containers. To do this, you can use the `from_docker_image` method of the environment class.85 86```python87import asyncio88from echo_env import EchoEnv89 90async def main():91    client = await EchoEnv.from_docker_image("registry.hf.space/openenv-echo-env:latest")92    async with client:93        result = await client.reset()94        print(result.observation)95 96asyncio.run(main())97```98 99In the background, the environment will be pulled from Docker Hub and a container will be started on your local machine.100 101As above, you can also connect to the docker container by passing the base URL to the environment class.102 103```sh104docker run -p 8000:8000 registry.hf.space/openenv-echo-env:latest105```106 107Then you can use the environment via its HTTP interface.108 109```python110# Async111async with EchoEnv(base_url="http://localhost:8000") as client:112    result = await client.reset()113 114# Or sync115with EchoEnv(base_url="http://localhost:8000").sync() as client:116    result = client.reset()117```118 119### Using AutoEnv and AutoAction (Recommended)120 121The `AutoEnv` and `AutoAction` classes provide a HuggingFace-style auto-discovery API that automatically selects and instantiates the correct environment client and action classes without manual imports.122 123!!! note124    `AutoEnv.from_env()` returns a synchronous client by default for convenience. For async usage, use the client class directly.125 126```python127from openenv import AutoEnv, AutoAction128 129# Load environment from installed package (returns sync client)130env = AutoEnv.from_env("echo-env")131 132# Get the action class133EchoAction = AutoAction.from_env("echo-env")134 135# Use them together (sync API)136with env.sync() as client:137    result = client.reset()138    result = client.step(EchoAction(message="Hello!"))139    print(result.observation.echoed_message)  # "Hello!"140```141 142AutoEnv supports multiple name formats - all of these work:143 144```python145env = AutoEnv.from_env("echo")       # Short name146env = AutoEnv.from_env("echo-env")   # With suffix147env = AutoEnv.from_env("echo_env")   # Underscore variant148```149 150You can also load environments directly from HuggingFace Hub:151 152```python153# From Hub repo ID - auto-downloads and installs if needed154env = AutoEnv.from_env("meta-pytorch/coding-env")155CodeAction = AutoAction.from_env("meta-pytorch/coding-env")156 157# If the Space is running, connects directly without local Docker158# If not, falls back to local Docker mode159```160 161To see all available environments:162 163```python164AutoEnv.list_environments()165AutoAction.list_actions()166```167 168### Using environments from a local directory169 170You can also use environments from a local directory. To do this, navigate to the directory of the environment and start the server.171 172```bash173cd path/to/echo-env174 175# manage dependencies with uv176uv venv177source .venv/bin/activate178uv pip install -e .179 180# start the server181uv run server --host 0.0.0.0 --port 8000182# or183uvicorn server.app:app --host 0.0.0.0 --port 8000184```185 186Then you can use the environment via its HTTP interface.187 188```python189from echo_env import EchoEnv190 191# Async (recommended)192async with EchoEnv(base_url="http://localhost:8000") as client:193    result = await client.reset()194 195# Or sync196with EchoEnv(base_url="http://localhost:8000").sync() as client:197    result = client.reset()198```199 200## Async vs Sync: When to Use Each201 202OpenEnv clients are **async by default** to support efficient concurrent operations. Use:203 204- **Async (`async with`, `await`)**: Best for production, parallel environments, and integration with async frameworks205- **Sync (`.sync()` wrapper)**: Convenient for scripts, notebooks, and synchronous codebases206 207```python208# Async - parallel environment interactions209async def run_parallel():210    async with EchoEnv(base_url="...") as env1, EchoEnv(base_url="...") as env2:211        # Run in parallel212        result1, result2 = await asyncio.gather(213            env1.step(action1),214            env2.step(action2)215        )216 217# Sync - simple sequential usage218with EchoEnv(base_url="...").sync() as env:219    result = env.step(action)220```221 222## Nice work! You've now used an OpenEnv environment.223 224Your next steps are to:225 226- [Check out the environments](environments.md)227- [Try out the end-to-end tutorial](https://colab.research.google.com/github/meta-pytorch/OpenEnv/blob/main/examples/OpenEnv_Tutorial.ipynb)228- [Build your own environment](environment-builder.md)229