openenv/echo_env

1---2title: Echo Environment Server3emoji: 🔊4colorFrom: blue5colorTo: green6sdk: docker7pinned: false8app_port: 80009base_path: /web10tags:11  - openenv-v0.8.012  - openenv13---14 15## Hugging Face Space Deployment16 17This Space is built from OpenEnv environment `echo_env`.18 19- Space URL: `https://huggingface.co/spaces/openenv/echo_env`20- OpenEnv pinned ref: `v0.8.0`21- Hub tag: `openenv`22 23### Connecting from Code24 25```bash26pip install git+https://huggingface.co/spaces/openenv/echo_env27```28 29```python30from echo_env import EchoEnv31 32with EchoEnv(base_url="https://openenv-echo-env.hf.space").sync() as env:33    result = env.reset()34```35 36# Echo Environment37 38A simple test environment that echoes back messages. Perfect for testing the env APIs as well as demonstrating environment usage patterns.39 40Try it on the [`openenv/echo_env`](https://huggingface.co/spaces/openenv/echo_env) Space, or connect a client to `https://openenv-echo-env.hf.space`.41 42## Quick Start43 44The simplest way to use the Echo environment is through the `EchoEnv` class. The client is **async by default**:45 46```python47import asyncio48from echo_env import CallToolAction, EchoEnv49 50async def main():51    # Create environment from Docker image52    client = await EchoEnv.from_docker_image("echo-env:latest")53 54    async with client:55        await client.reset()56 57        # Send multiple messages58        messages = ["Hello, World!", "Testing echo", "Final message"]59 60        for msg in messages:61            result = await client.step(62                CallToolAction(63                    tool_name="echo_message",64                    arguments={"message": msg},65                )66            )67            print(f"Sent: '{msg}'")68            print(f"  → Echoed: '{result.observation.result}'")69            print(f"  → Reward: {result.reward}")70 71asyncio.run(main())72```73 74For **synchronous usage**, use the `.sync()` wrapper:75 76```python77from echo_env import CallToolAction, EchoEnv78 79with EchoEnv(base_url="http://localhost:8000").sync() as client:80    client.reset()81    result = client.step(82        CallToolAction(83            tool_name="echo_message",84            arguments={"message": "Hello!"},85        )86    )87    print(result.observation.result)88```89 90The `EchoEnv.from_docker_image()` method handles:91- Starting the Docker container92- Waiting for the server to be ready93- Connecting to the environment94- Container cleanup when the context manager exits95 96## Building the Docker Image97 98Before using the environment, you need to build the Docker image:99 100```bash101# From project root102docker build -t echo-env:latest -f envs/echo_env/server/Dockerfile .103```104 105## Environment Details106 107### Tools108- `echo_message(message)` - Echo the provided message109- `echo_with_length(message)` - Echo the message and include its length110 111### Observation112**CallToolObservation**: Contains the tool result and metadata113- `result` - The tool return value114- `reward` (float) - Reward returned by the environment115- `done` (bool) - Always `False` for the echo environment116- `metadata` (dict) - Additional info like step count117 118### Reward119The echo environment returns `0.0` reward for tool calls. It is intended as a120minimal MCP integration example rather than a reward-shaping reference.121 122## Advanced Usage123 124### Connecting to an Existing Server125 126If you already have an Echo environment server running, you can connect directly:127 128```python129from echo_env import CallToolAction, EchoEnv130 131# Async usage132async with EchoEnv(base_url="http://localhost:8000") as client:133    await client.reset()134    result = await client.step(135        CallToolAction(136            tool_name="echo_message",137            arguments={"message": "Hello!"},138        )139    )140 141# Sync usage142with EchoEnv(base_url="http://localhost:8000").sync() as client:143    client.reset()144    result = client.step(145        CallToolAction(146            tool_name="echo_message",147            arguments={"message": "Hello!"},148        )149    )150```151 152Note: When connecting to an existing server, closing the client will NOT stop the server.153 154## Development & Testing155 156### Direct Environment Testing157 158Test the environment logic directly without starting the HTTP server:159 160```bash161# From the server directory162python3 envs/echo_env/server/test_echo_env.py163```164 165This verifies that:166- Environment resets correctly167- Step executes actions properly168- State tracking works169- Rewards are calculated correctly170 171### Running the Full Example172 173Run the complete example that demonstrates the full workflow:174 175```bash176python3 examples/local_echo_env.py177```178 179This example shows:180- Creating an environment from a Docker image181- Resetting and stepping through the environment182- Automatic cleanup with `close()`183 184## Project Structure185 186```187echo_env/188├── __init__.py            # Module exports189├── README.md              # This file190├── client.py              # EchoEnv client implementation191├── models.py              # Action and Observation models192└── server/193    ├── __init__.py        # Server module exports194    ├── echo_environment.py  # Core environment logic195    ├── app.py             # FastAPI application196    ├── test_echo_env.py   # Direct environment tests197    └── Dockerfile         # Container image definition198```199