spedrox-sac/echo-env

1---2title: Echo Environment Server3emoji: 🔊4colorFrom: blue5colorTo: blue6sdk: docker7pinned: false8app_port: 78609base_path: /web10tags:11  - openenv12---13 14# Echo Environment15 16A simple test environment that echoes back messages. Perfect for testing the env APIs as well as demonstrating environment usage patterns.17 18## Quick Start19 20The simplest way to use the Echo environment is through the `EchoEnv` class. The client is **async by default**:21 22```python23import asyncio24from echo_env import EchoAction, EchoEnv25 26async def main():27    # Create environment from Docker image28    client = await EchoEnv.from_docker_image("echo-env:latest")29 30    async with client:31        # Reset32        result = await client.reset()33        print(f"Reset: {result.observation.echoed_message}")34 35        # Send multiple messages36        messages = ["Hello, World!", "Testing echo", "Final message"]37 38        for msg in messages:39            result = await client.step(EchoAction(message=msg))40            print(f"Sent: '{msg}'")41            print(f"  → Echoed: '{result.observation.echoed_message}'")42            print(f"  → Length: {result.observation.message_length}")43            print(f"  → Reward: {result.reward}")44 45asyncio.run(main())46```47 48For **synchronous usage**, use the `.sync()` wrapper:49 50```python51from echo_env import EchoAction, EchoEnv52 53with EchoEnv(base_url="http://localhost:7860").sync() as client:54    result = client.reset()55    result = client.step(EchoAction(message="Hello!"))56    print(result.observation.echoed_message)57```58 59The `EchoEnv.from_docker_image()` method handles:60- Starting the Docker container61- Waiting for the server to be ready62- Connecting to the environment63- Container cleanup when the context manager exits64 65## Building the Docker Image66 67Before using the environment, you need to build the Docker image:68 69```bash70# From project root71docker build -t echo-env:latest -f envs/echo_env/server/Dockerfile .72```73 74## Environment Details75 76### Action77**EchoAction**: Contains a single field78- `message` (str) - The message to echo back79 80### Observation81**EchoObservation**: Contains the echo response and metadata82- `echoed_message` (str) - The message echoed back83- `message_length` (int) - Length of the message84- `reward` (float) - Reward based on message length (length × 0.1)85- `done` (bool) - Always False for echo environment86- `metadata` (dict) - Additional info like step count87 88### Reward89The reward is calculated as: `message_length × 0.1`90- "Hi" → reward: 0.291- "Hello, World!" → reward: 1.392- Empty message → reward: 0.093 94## Advanced Usage95 96### Connecting to an Existing Server97 98If you already have an Echo environment server running, you can connect directly:99 100```python101from echo_env import EchoAction, EchoEnv102 103# Async usage104async with EchoEnv(base_url="http://localhost:7860") as client:105    result = await client.reset()106    result = await client.step(EchoAction(message="Hello!"))107 108# Sync usage109with EchoEnv(base_url="http://localhost:7860").sync() as client:110    result = client.reset()111    result = client.step(EchoAction(message="Hello!"))112```113 114Note: When connecting to an existing server, closing the client will NOT stop the server.115 116## Development & Testing117 118### Direct Environment Testing119 120Test the environment logic directly without starting the HTTP server:121 122```bash123# From the server directory124python3 envs/echo_env/server/test_echo_env.py125```126 127This verifies that:128- Environment resets correctly129- Step executes actions properly130- State tracking works131- Rewards are calculated correctly132 133### Running the Full Example134 135Run the complete example that demonstrates the full workflow:136 137```bash138python3 examples/local_echo_env.py139```140 141This example shows:142- Creating an environment from a Docker image143- Resetting and stepping through the environment144- Automatic cleanup with `close()`145 146## Project Structure147 148```149echo_env/150├── __init__.py            # Module exports151├── README.md              # This file152├── client.py              # EchoEnv client implementation153├── models.py              # Action and Observation models154└── server/155    ├── __init__.py        # Server module exports156    ├── echo_environment.py  # Core environment logic157    ├── app.py             # FastAPI application158    ├── test_echo_env.py   # Direct environment tests159    └── Dockerfile         # Container image definition160```161