initial base program that we will work on

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,85 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+# Multi-stage build using openenv-base
+# This Dockerfile is flexible and works for both:
+# - In-repo environments (with local src/core)
+# - Standalone environments (with openenv-core from pip)
+# The build script (openenv build) handles context detection and sets appropriate build args.
+
+ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
+FROM ghcr.io/meta-pytorch/openenv-base:latest AS builder
+
+WORKDIR /app
+
+# Build argument to control whether we're building standalone or in-repo
+ARG BUILD_MODE=in-repo
+
+# Copy environment code (always at root of build context)
+COPY . /app/env
+
+# For in-repo builds, openenv-core is already in the pyproject.toml dependencies
+# For standalone builds, openenv-core will be installed from pip via pyproject.toml
+WORKDIR /app/env
+
+# Ensure uv is available (for local builds where base image lacks it)
+RUN if ! command -v uv >/dev/null 2>&1; then \
+        curl -LsSf https://astral.sh/uv/install.sh | sh && \
+        mv /root/.local/bin/uv /usr/local/bin/uv && \
+        mv /root/.local/bin/uvx /usr/local/bin/uvx; \
+    fi
+
+# Install git for building from git repos (build-time only)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install dependencies using uv sync
+# First pass: install dependencies without the project (for better caching)
+# Second pass: install the project itself
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh && \
+    install -m 0755 /root/.local/bin/uv /usr/local/bin/uv && \
+    install -m 0755 /root/.local/bin/uvx /usr/local/bin/uvx
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --no-install-project --no-editable; \
+    else \
+        uv sync --no-install-project --no-editable; \
+    fi
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --no-editable; \
+    else \
+        uv sync --no-editable; \
+    fi
+
+# Final runtime stage
+FROM ghcr.io/meta-pytorch/openenv-base:latest
+
+WORKDIR /app
+
+# Copy the virtual environment from builder
+COPY --from=builder /app/env/.venv /app/.venv
+
+# Copy the environment code
+COPY --from=builder /app/env /app/env
+
+# Set PATH to use the virtual environment
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Set PYTHONPATH so imports work correctly
+ENV PYTHONPATH="/app/env:$PYTHONPATH"
+ENV ENABLE_WEB_INTERFACE=true
+
+# Health check using Python (more portable than curl/wget)
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')" || exit 1
+
+# Run the FastAPI server
+# The module path is constructed to work with the /app/env structure
+CMD ["sh", "-c", "cd /app/env && uvicorn server.app:app --host 0.0.0.0 --port 8000"]

README.md

@@ -0,0 +1,177 @@
+---
+title: Echo Environment Server
+emoji: 🔊
+colorFrom: blue
+colorTo: green
+sdk: docker
+pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv-0.2.3
+  - openenv
+---
+
+## Hugging Face Space Deployment
+
+This Space is built from OpenEnv environment `echo_env`.
+
+- Space URL: `https://huggingface.co/spaces/openenv/echo_env`
+- OpenEnv pinned ref: `0.2.3`
+- Hub tag: `openenv`
+
+### Connecting from Code
+
+```python
+from envs.echo_env import EchoEnv
+
+env = EchoEnv(base_url="https://huggingface.co/spaces/openenv/echo_env")
+```
+
+# Echo Environment
+
+A simple test environment that echoes back messages. Perfect for testing the env APIs as well as demonstrating environment usage patterns.
+
+## Quick Start
+
+The simplest way to use the Echo environment is through the `EchoEnv` class. The client is **async by default**:
+
+```python
+import asyncio
+from echo_env import EchoAction, EchoEnv
+
+async def main():
+    # Create environment from Docker image
+    client = await EchoEnv.from_docker_image("echo-env:latest")
+
+    async with client:
+        # Reset
+        result = await client.reset()
+        print(f"Reset: {result.observation.echoed_message}")
+
+        # Send multiple messages
+        messages = ["Hello, World!", "Testing echo", "Final message"]
+
+        for msg in messages:
+            result = await client.step(EchoAction(message=msg))
+            print(f"Sent: '{msg}'")
+            print(f"  → Echoed: '{result.observation.echoed_message}'")
+            print(f"  → Length: {result.observation.message_length}")
+            print(f"  → Reward: {result.reward}")
+
+asyncio.run(main())
+```
+
+For **synchronous usage**, use the `.sync()` wrapper:
+
+```python
+from echo_env import EchoAction, EchoEnv
+
+with EchoEnv(base_url="http://localhost:8000").sync() as client:
+    result = client.reset()
+    result = client.step(EchoAction(message="Hello!"))
+    print(result.observation.echoed_message)
+```
+
+The `EchoEnv.from_docker_image()` method handles:
+- Starting the Docker container
+- Waiting for the server to be ready
+- Connecting to the environment
+- Container cleanup when the context manager exits
+
+## Building the Docker Image
+
+Before using the environment, you need to build the Docker image:
+
+```bash
+# From project root
+docker build -t echo-env:latest -f envs/echo_env/server/Dockerfile .
+```
+
+## Environment Details
+
+### Action
+**EchoAction**: Contains a single field
+- `message` (str) - The message to echo back
+
+### Observation
+**EchoObservation**: Contains the echo response and metadata
+- `echoed_message` (str) - The message echoed back
+- `message_length` (int) - Length of the message
+- `reward` (float) - Reward based on message length (length × 0.1)
+- `done` (bool) - Always False for echo environment
+- `metadata` (dict) - Additional info like step count
+
+### Reward
+The reward is calculated as: `message_length × 0.1`
+- "Hi" → reward: 0.2
+- "Hello, World!" → reward: 1.3
+- Empty message → reward: 0.0
+
+## Advanced Usage
+
+### Connecting to an Existing Server
+
+If you already have an Echo environment server running, you can connect directly:
+
+```python
+from echo_env import EchoAction, EchoEnv
+
+# Async usage
+async with EchoEnv(base_url="http://localhost:8000") as client:
+    result = await client.reset()
+    result = await client.step(EchoAction(message="Hello!"))
+
+# Sync usage
+with EchoEnv(base_url="http://localhost:8000").sync() as client:
+    result = client.reset()
+    result = client.step(EchoAction(message="Hello!"))
+```
+
+Note: When connecting to an existing server, closing the client will NOT stop the server.
+
+## Development & Testing
+
+### Direct Environment Testing
+
+Test the environment logic directly without starting the HTTP server:
+
+```bash
+# From the server directory
+python3 envs/echo_env/server/test_echo_env.py
+```
+
+This verifies that:
+- Environment resets correctly
+- Step executes actions properly
+- State tracking works
+- Rewards are calculated correctly
+
+### Running the Full Example
+
+Run the complete example that demonstrates the full workflow:
+
+```bash
+python3 examples/local_echo_env.py
+```
+
+This example shows:
+- Creating an environment from a Docker image
+- Resetting and stepping through the environment
+- Automatic cleanup with `close()`
+
+## Project Structure
+
+```
+echo_env/
+├── __init__.py            # Module exports
+├── README.md              # This file
+├── client.py              # EchoEnv client implementation
+├── models.py              # Action and Observation models
+└── server/
+    ├── __init__.py        # Server module exports
+    ├── echo_environment.py  # Core environment logic
+    ├── app.py             # FastAPI application
+    ├── test_echo_env.py   # Direct environment tests
+    └── Dockerfile         # Container image definition
+```

__init__.py

@@ -0,0 +1,29 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Echo Environment - A pure MCP environment for testing and demonstration.
+
+This environment exposes all functionality through MCP tools:
+- `echo_message(message)`: Echo back the provided message
+- `echo_with_length(message)`: Echo back the message with its length
+
+Example:
+    >>> from echo_env import EchoEnv
+    >>>
+    >>> with EchoEnv(base_url="http://localhost:8000") as env:
+    ...     env.reset()
+    ...     tools = env.list_tools()
+    ...     result = env.call_tool("echo_message", message="Hello!")
+    ...     print(result)  # "Hello!"
+"""
+
+# Re-export MCP types for convenience
+from openenv.core.env_server.mcp_types import CallToolAction, ListToolsAction
+
+from .client import EchoEnv
+
+__all__ = ["EchoEnv", "CallToolAction", "ListToolsAction"]

build/lib/build/lib/server/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Echo environment server components."""
+
+from .echo_environment import EchoEnvironment
+
+__all__ = ["EchoEnvironment"]

build/lib/build/lib/server/app.py

@@ -0,0 +1,57 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+FastAPI application for the Echo Environment.
+
+This module creates an HTTP server that exposes the EchoEnvironment
+over HTTP and WebSocket endpoints, compatible with EnvClient.
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn server.app:app --host 0.0.0.0 --port 8000 --workers 4
+
+    # Or run directly:
+    uv run --project . server
+"""
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.http_server import create_app
+    from ..models import EchoAction, EchoObservation
+    from .echo_environment import EchoEnvironment
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.http_server import create_app
+    from models import EchoAction, EchoObservation
+    from server.echo_environment import EchoEnvironment
+
+# Create the app with web interface and README integration
+# Pass the class (factory) instead of an instance for WebSocket session support
+app = create_app(EchoEnvironment, EchoAction, EchoObservation, env_name="echo_env")
+
+
+def main():
+    """
+    Entry point for direct execution via uv run or python -m.
+
+    This function enables running the server without Docker:
+        uv run --project . server
+        python -m envs.echo_env.server.app
+        openenv serve echo_env
+
+    """
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+
+
+if __name__ == "__main__":
+    main()

build/lib/build/lib/server/echo_environment.py

@@ -0,0 +1,102 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Echo Environment Implementation.
+
+A simple test environment that echoes back messages sent to it.
+Perfect for testing HTTP server infrastructure.
+"""
+
+from uuid import uuid4
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.interfaces import Environment
+    from openenv.core.env_server.types import State
+    from ..models import EchoAction, EchoObservation
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.interfaces import Environment
+    from openenv.core.env_server.types import State
+    from models import EchoAction, EchoObservation
+
+
+class EchoEnvironment(Environment):
+    """
+    A simple echo environment that echoes back messages.
+
+    This environment is designed for testing the HTTP server infrastructure.
+    It maintains minimal state and simply echoes back whatever message it receives.
+
+    Example:
+        >>> env = EchoEnvironment()
+        >>> obs = env.reset()
+        >>> print(obs.echoed_message)  # "Echo environment ready!"
+        >>>
+        >>> obs = env.step(EchoAction(message="Hello"))
+        >>> print(obs.echoed_message)  # "Hello"
+        >>> print(obs.message_length)  # 5
+    """
+
+    def __init__(self):
+        """Initialize the echo environment."""
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._reset_count = 0
+
+    def reset(self) -> EchoObservation:
+        """
+        Reset the environment.
+
+        Returns:
+            EchoObservation with a ready message
+        """
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._reset_count += 1
+
+        return EchoObservation(
+            echoed_message="Echo environment ready!",
+            message_length=0,
+            done=False,
+            reward=0.0,
+        )
+
+    def step(self, action: EchoAction) -> EchoObservation:  # type: ignore[override]
+        """
+        Execute a step in the environment by echoing the message.
+
+        Args:
+            action: EchoAction containing the message to echo
+
+        Returns:
+            EchoObservation with the echoed message and its length
+        """
+        self._state.step_count += 1
+
+        message = action.message
+        length = len(message)
+
+        # Simple reward: longer messages get higher rewards
+        reward = length * 0.1
+
+        return EchoObservation(
+            echoed_message=message,
+            message_length=length,
+            done=False,
+            reward=reward,
+            metadata={"original_message": message, "step": self._state.step_count},
+        )
+
+    @property
+    def state(self) -> State:
+        """
+        Get the current environment state.
+
+        Returns:
+            Current State with episode_id and step_count
+        """
+        return self._state

build/lib/echo_env/__init__.py

@@ -0,0 +1,29 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Echo Environment - A pure MCP environment for testing and demonstration.
+
+This environment exposes all functionality through MCP tools:
+- `echo_message(message)`: Echo back the provided message
+- `echo_with_length(message)`: Echo back the message with its length
+
+Example:
+    >>> from echo_env import EchoEnv
+    >>>
+    >>> with EchoEnv(base_url="http://localhost:8000") as env:
+    ...     env.reset()
+    ...     tools = env.list_tools()
+    ...     result = env.call_tool("echo_message", message="Hello!")
+    ...     print(result)  # "Hello!"
+"""
+
+from .client import EchoEnv
+
+# Re-export MCP types for convenience
+from openenv.core.env_server.mcp_types import CallToolAction, ListToolsAction
+
+__all__ = ["EchoEnv", "CallToolAction", "ListToolsAction"]

build/lib/echo_env/client.py

@@ -0,0 +1,81 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Echo Environment Client.
+
+This module provides the client for connecting to an Echo Environment server.
+EchoEnv extends MCPToolClient to provide tool-calling style interactions.
+
+Example:
+    >>> with EchoEnv(base_url="http://localhost:8000") as env:
+    ...     env.reset()
+    ...
+    ...     # Discover tools
+    ...     tools = env.list_tools()
+    ...     print([t.name for t in tools])  # ['echo_message', 'echo_with_length']
+    ...
+    ...     # Call tools
+    ...     result = env.call_tool("echo_message", message="Hello!")
+    ...     print(result)  # "Hello!"
+    ...
+    ...     result = env.call_tool("echo_with_length", message="Test")
+    ...     print(result)  # {"message": "Test", "length": 4}
+"""
+
+from openenv.core.mcp_client import MCPToolClient
+
+
+class EchoEnv(MCPToolClient):
+    """
+    Client for the Echo Environment.
+
+    This client provides a simple interface for interacting with the Echo
+    Environment via MCP tools. It inherits all functionality from MCPToolClient:
+    - `list_tools()`: Discover available tools
+    - `call_tool(name, **kwargs)`: Call a tool by name
+    - `reset(**kwargs)`: Reset the environment
+    - `step(action)`: Execute an action (for advanced use)
+
+    Example:
+        >>> # Connect to a running server
+        >>> with EchoEnv(base_url="http://localhost:8000") as env:
+        ...     env.reset()
+        ...
+        ...     # List available tools
+        ...     tools = env.list_tools()
+        ...     for tool in tools:
+        ...         print(f"{tool.name}: {tool.description}")
+        ...
+        ...     # Echo a message
+        ...     result = env.call_tool("echo_message", message="Hello!")
+        ...     print(result)  # "Hello!"
+        ...
+        ...     # Echo with length
+        ...     result = env.call_tool("echo_with_length", message="Test")
+        ...     print(result)  # {"message": "Test", "length": 4}
+
+    Example with Docker:
+        >>> # Automatically start container and connect
+        >>> env = EchoEnv.from_docker_image("echo-env:latest")
+        >>> try:
+        ...     env.reset()
+        ...     tools = env.list_tools()
+        ...     result = env.call_tool("echo_message", message="Hello!")
+        ... finally:
+        ...     env.close()
+
+    Example with HuggingFace Space:
+        >>> # Run from HuggingFace Space
+        >>> env = EchoEnv.from_env("openenv/echo-env")
+        >>> try:
+        ...     env.reset()
+        ...     result = env.call_tool("echo_message", message="Hello!")
+        ... finally:
+        ...     env.close()
+    """
+
+    pass  # MCPToolClient provides all needed functionality

build/lib/echo_env/server/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Echo environment server components."""
+
+from .echo_environment import EchoEnvironment
+
+__all__ = ["EchoEnvironment"]

build/lib/echo_env/server/app.py

@@ -0,0 +1,60 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+FastAPI application for the Echo Environment.
+
+This module creates an HTTP server that exposes the EchoEnvironment
+over HTTP and WebSocket endpoints, compatible with MCPToolClient.
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn server.app:app --host 0.0.0.0 --port 8000 --workers 4
+
+    # Or run directly:
+    uv run --project . server
+"""
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.http_server import create_app
+    from openenv.core.env_server.mcp_types import CallToolAction, CallToolObservation
+    from .echo_environment import EchoEnvironment
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.http_server import create_app
+    from openenv.core.env_server.mcp_types import CallToolAction, CallToolObservation
+    from server.echo_environment import EchoEnvironment
+
+# Create the app with web interface and README integration
+# Pass the class (factory) instead of an instance for WebSocket session support
+# Use MCP types for action/observation since this is a pure MCP environment
+app = create_app(
+    EchoEnvironment, CallToolAction, CallToolObservation, env_name="echo_env"
+)
+
+
+def main():
+    """
+    Entry point for direct execution via uv run or python -m.
+
+    This function enables running the server without Docker:
+        uv run --project . server
+        python -m envs.echo_env.server.app
+        openenv serve echo_env
+
+    """
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+
+
+if __name__ == "__main__":
+    main()

build/lib/echo_env/server/echo_environment.py

@@ -0,0 +1,196 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Echo Environment Implementation.
+
+A pure MCP environment that echoes back messages sent to it.
+This demonstrates how to build an MCPEnvironment with inline FastMCP tools.
+
+All interactions happen through MCP tools:
+- `echo_message(message)`: Echo back the provided message
+- `echo_with_length(message)`: Echo back the message with its length
+
+Example:
+    >>> from openenv.core.env_server.mcp_types import ListToolsAction, CallToolAction
+    >>> env = EchoEnvironment()
+    >>> env.reset()
+    >>>
+    >>> # List available tools
+    >>> obs = env.step(ListToolsAction())
+    >>> print([t.name for t in obs.tools])  # ["echo_message", "echo_with_length"]
+    >>>
+    >>> # Call a tool
+    >>> obs = env.step(CallToolAction(tool_name="echo_message", arguments={"message": "Hi!"}))
+    >>> print(obs.result)  # "Hi!"
+"""
+
+from typing import Any, Optional
+from uuid import uuid4
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.mcp_environment import MCPEnvironment
+    from openenv.core.env_server.types import Action, Observation, State
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.mcp_environment import MCPEnvironment
+    from openenv.core.env_server.types import Action, Observation, State
+
+from fastmcp import FastMCP
+
+
+class EchoEnvironment(MCPEnvironment):
+    """
+    A pure MCP echo environment that echoes back messages.
+
+    This environment exposes all functionality through MCP tools:
+    - `echo_message`: Echo back the provided message
+    - `echo_with_length`: Echo back the message with its length
+
+    The environment inherits MCP support (ListToolsAction, CallToolAction)
+    from the MCPEnvironment base class. No legacy action types are supported.
+
+    Example using MCPToolClient:
+        >>> from openenv.core.mcp_client import MCPToolClient
+        >>>
+        >>> with MCPToolClient(base_url="http://localhost:8000") as env:
+        ...     env.reset()
+        ...     tools = env.list_tools()
+        ...     print([t.name for t in tools])
+        ...     result = env.call_tool("echo_message", message="Hello!")
+        ...     print(result)
+    """
+
+    def __init__(self):
+        """Initialize the echo environment with MCP server and tools."""
+        # Create MCP server and define tools inline
+        mcp = FastMCP("echo_env")
+
+        @mcp.tool
+        def echo_message(message: str) -> str:
+            """
+            Echo back the provided message.
+
+            Args:
+                message: The message to echo back
+
+            Returns:
+                The same message that was provided
+            """
+            return message
+
+        @mcp.tool
+        def echo_with_length(message: str) -> dict:
+            """
+            Echo back the message with its length.
+
+            Args:
+                message: The message to echo back
+
+            Returns:
+                Dictionary with the message and its length
+            """
+            return {"message": message, "length": len(message)}
+
+        # Pass the MCP server to the base class
+        super().__init__(mcp)
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._reset_count = 0
+
+    def reset(
+        self,
+        seed: Optional[int] = None,
+        episode_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Observation:
+        """
+        Reset the environment.
+
+        Args:
+            seed: Optional random seed (unused in echo env)
+            episode_id: Optional episode ID to use
+            **kwargs: Additional reset options
+
+        Returns:
+            Observation indicating the environment is ready
+        """
+        self._state = State(
+            episode_id=episode_id or str(uuid4()),
+            step_count=0,
+        )
+        self._reset_count += 1
+
+        return Observation(
+            done=False,
+            reward=0.0,
+            metadata={"status": "ready", "message": "Echo environment ready!"},
+        )
+
+    def _step_impl(
+        self,
+        action: Action,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> Observation:
+        """
+        Handle non-MCP actions.
+
+        This environment only supports MCP actions (ListToolsAction, CallToolAction).
+        Any other action type returns an error observation.
+
+        Args:
+            action: The action to execute
+            timeout_s: Optional timeout (unused)
+            **kwargs: Additional arguments
+
+        Returns:
+            Observation with error for unknown action types
+        """
+        return Observation(
+            done=False,
+            reward=0.0,
+            metadata={
+                "error": f"Unknown action type: {type(action).__name__}. "
+                "Use ListToolsAction or CallToolAction for MCP interactions."
+            },
+        )
+
+    def step(
+        self,
+        action: Action,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> Observation:
+        """
+        Execute a step in the environment.
+
+        Delegates to base class for MCP actions. Increments step count for all actions.
+
+        Args:
+            action: The MCP action to execute (ListToolsAction or CallToolAction)
+            timeout_s: Optional timeout for the action
+            **kwargs: Additional arguments
+
+        Returns:
+            Observation from the action execution
+        """
+        # Increment step count for all actions
+        self._state.step_count += 1
+
+        # Let the base class handle MCP actions and non-MCP routing
+        return super().step(action, timeout_s=timeout_s, **kwargs)
+
+    @property
+    def state(self) -> State:
+        """
+        Get the current environment state.
+
+        Returns:
+            Current State with episode_id and step_count
+        """
+        return self._state

build/lib/server/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Echo environment server components."""
+
+from .echo_environment import EchoEnvironment
+
+__all__ = ["EchoEnvironment"]

build/lib/server/app.py

@@ -0,0 +1,57 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+FastAPI application for the Echo Environment.
+
+This module creates an HTTP server that exposes the EchoEnvironment
+over HTTP and WebSocket endpoints, compatible with EnvClient.
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn server.app:app --host 0.0.0.0 --port 8000 --workers 4
+
+    # Or run directly:
+    uv run --project . server
+"""
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.http_server import create_app
+    from ..models import EchoAction, EchoObservation
+    from .echo_environment import EchoEnvironment
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.http_server import create_app
+    from models import EchoAction, EchoObservation
+    from server.echo_environment import EchoEnvironment
+
+# Create the app with web interface and README integration
+# Pass the class (factory) instead of an instance for WebSocket session support
+app = create_app(EchoEnvironment, EchoAction, EchoObservation, env_name="echo_env")
+
+
+def main():
+    """
+    Entry point for direct execution via uv run or python -m.
+
+    This function enables running the server without Docker:
+        uv run --project . server
+        python -m envs.echo_env.server.app
+        openenv serve echo_env
+
+    """
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+
+
+if __name__ == "__main__":
+    main()

build/lib/server/echo_environment.py

@@ -0,0 +1,102 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Echo Environment Implementation.
+
+A simple test environment that echoes back messages sent to it.
+Perfect for testing HTTP server infrastructure.
+"""
+
+from uuid import uuid4
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.interfaces import Environment
+    from openenv.core.env_server.types import State
+    from ..models import EchoAction, EchoObservation
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.interfaces import Environment
+    from openenv.core.env_server.types import State
+    from models import EchoAction, EchoObservation
+
+
+class EchoEnvironment(Environment):
+    """
+    A simple echo environment that echoes back messages.
+
+    This environment is designed for testing the HTTP server infrastructure.
+    It maintains minimal state and simply echoes back whatever message it receives.
+
+    Example:
+        >>> env = EchoEnvironment()
+        >>> obs = env.reset()
+        >>> print(obs.echoed_message)  # "Echo environment ready!"
+        >>>
+        >>> obs = env.step(EchoAction(message="Hello"))
+        >>> print(obs.echoed_message)  # "Hello"
+        >>> print(obs.message_length)  # 5
+    """
+
+    def __init__(self):
+        """Initialize the echo environment."""
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._reset_count = 0
+
+    def reset(self) -> EchoObservation:
+        """
+        Reset the environment.
+
+        Returns:
+            EchoObservation with a ready message
+        """
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._reset_count += 1
+
+        return EchoObservation(
+            echoed_message="Echo environment ready!",
+            message_length=0,
+            done=False,
+            reward=0.0,
+        )
+
+    def step(self, action: EchoAction) -> EchoObservation:  # type: ignore[override]
+        """
+        Execute a step in the environment by echoing the message.
+
+        Args:
+            action: EchoAction containing the message to echo
+
+        Returns:
+            EchoObservation with the echoed message and its length
+        """
+        self._state.step_count += 1
+
+        message = action.message
+        length = len(message)
+
+        # Simple reward: longer messages get higher rewards
+        reward = length * 0.1
+
+        return EchoObservation(
+            echoed_message=message,
+            message_length=length,
+            done=False,
+            reward=reward,
+            metadata={"original_message": message, "step": self._state.step_count},
+        )
+
+    @property
+    def state(self) -> State:
+        """
+        Get the current environment state.
+
+        Returns:
+            Current State with episode_id and step_count
+        """
+        return self._state

client.py

@@ -0,0 +1,81 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Echo Environment Client.
+
+This module provides the client for connecting to an Echo Environment server.
+EchoEnv extends MCPToolClient to provide tool-calling style interactions.
+
+Example:
+    >>> with EchoEnv(base_url="http://localhost:8000") as env:
+    ...     env.reset()
+    ...
+    ...     # Discover tools
+    ...     tools = env.list_tools()
+    ...     print([t.name for t in tools])  # ['echo_message', 'echo_with_length']
+    ...
+    ...     # Call tools
+    ...     result = env.call_tool("echo_message", message="Hello!")
+    ...     print(result)  # "Hello!"
+    ...
+    ...     result = env.call_tool("echo_with_length", message="Test")
+    ...     print(result)  # {"message": "Test", "length": 4}
+"""
+
+from openenv.core.mcp_client import MCPToolClient
+
+
+class EchoEnv(MCPToolClient):
+    """
+    Client for the Echo Environment.
+
+    This client provides a simple interface for interacting with the Echo
+    Environment via MCP tools. It inherits all functionality from MCPToolClient:
+    - `list_tools()`: Discover available tools
+    - `call_tool(name, **kwargs)`: Call a tool by name
+    - `reset(**kwargs)`: Reset the environment
+    - `step(action)`: Execute an action (for advanced use)
+
+    Example:
+        >>> # Connect to a running server
+        >>> with EchoEnv(base_url="http://localhost:8000") as env:
+        ...     env.reset()
+        ...
+        ...     # List available tools
+        ...     tools = env.list_tools()
+        ...     for tool in tools:
+        ...         print(f"{tool.name}: {tool.description}")
+        ...
+        ...     # Echo a message
+        ...     result = env.call_tool("echo_message", message="Hello!")
+        ...     print(result)  # "Hello!"
+        ...
+        ...     # Echo with length
+        ...     result = env.call_tool("echo_with_length", message="Test")
+        ...     print(result)  # {"message": "Test", "length": 4}
+
+    Example with Docker:
+        >>> # Automatically start container and connect
+        >>> env = EchoEnv.from_docker_image("echo-env:latest")
+        >>> try:
+        ...     env.reset()
+        ...     tools = env.list_tools()
+        ...     result = env.call_tool("echo_message", message="Hello!")
+        ... finally:
+        ...     env.close()
+
+    Example with HuggingFace Space:
+        >>> # Run from HuggingFace Space
+        >>> env = EchoEnv.from_env("openenv/echo-env")
+        >>> try:
+        ...     env.reset()
+        ...     result = env.call_tool("echo_message", message="Hello!")
+        ... finally:
+        ...     env.close()
+    """
+
+    pass  # MCPToolClient provides all needed functionality

envs/echo_env/README.md

@@ -0,0 +1,160 @@
+---
+title: Echo Environment Server
+emoji: 🔊
+colorFrom: blue
+colorTo: blue
+sdk: docker
+pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
+---
+
+# Echo Environment
+
+A simple test environment that echoes back messages. Perfect for testing the env APIs as well as demonstrating environment usage patterns.
+
+## Quick Start
+
+The simplest way to use the Echo environment is through the `EchoEnv` class. The client is **async by default**:
+
+```python
+import asyncio
+from echo_env import EchoAction, EchoEnv
+
+async def main():
+    # Create environment from Docker image
+    client = await EchoEnv.from_docker_image("echo-env:latest")
+
+    async with client:
+        # Reset
+        result = await client.reset()
+        print(f"Reset: {result.observation.echoed_message}")
+
+        # Send multiple messages
+        messages = ["Hello, World!", "Testing echo", "Final message"]
+
+        for msg in messages:
+            result = await client.step(EchoAction(message=msg))
+            print(f"Sent: '{msg}'")
+            print(f"  → Echoed: '{result.observation.echoed_message}'")
+            print(f"  → Length: {result.observation.message_length}")
+            print(f"  → Reward: {result.reward}")
+
+asyncio.run(main())
+```
+
+For **synchronous usage**, use the `.sync()` wrapper:
+
+```python
+from echo_env import EchoAction, EchoEnv
+
+with EchoEnv(base_url="http://localhost:8000").sync() as client:
+    result = client.reset()
+    result = client.step(EchoAction(message="Hello!"))
+    print(result.observation.echoed_message)
+```
+
+The `EchoEnv.from_docker_image()` method handles:
+- Starting the Docker container
+- Waiting for the server to be ready
+- Connecting to the environment
+- Container cleanup when the context manager exits
+
+## Building the Docker Image
+
+Before using the environment, you need to build the Docker image:
+
+```bash
+# From project root
+docker build -t echo-env:latest -f envs/echo_env/server/Dockerfile .
+```
+
+## Environment Details
+
+### Action
+**EchoAction**: Contains a single field
+- `message` (str) - The message to echo back
+
+### Observation
+**EchoObservation**: Contains the echo response and metadata
+- `echoed_message` (str) - The message echoed back
+- `message_length` (int) - Length of the message
+- `reward` (float) - Reward based on message length (length × 0.1)
+- `done` (bool) - Always False for echo environment
+- `metadata` (dict) - Additional info like step count
+
+### Reward
+The reward is calculated as: `message_length × 0.1`
+- "Hi" → reward: 0.2
+- "Hello, World!" → reward: 1.3
+- Empty message → reward: 0.0
+
+## Advanced Usage
+
+### Connecting to an Existing Server
+
+If you already have an Echo environment server running, you can connect directly:
+
+```python
+from echo_env import EchoAction, EchoEnv
+
+# Async usage
+async with EchoEnv(base_url="http://localhost:8000") as client:
+    result = await client.reset()
+    result = await client.step(EchoAction(message="Hello!"))
+
+# Sync usage
+with EchoEnv(base_url="http://localhost:8000").sync() as client:
+    result = client.reset()
+    result = client.step(EchoAction(message="Hello!"))
+```
+
+Note: When connecting to an existing server, closing the client will NOT stop the server.
+
+## Development & Testing
+
+### Direct Environment Testing
+
+Test the environment logic directly without starting the HTTP server:
+
+```bash
+# From the server directory
+python3 envs/echo_env/server/test_echo_env.py
+```
+
+This verifies that:
+- Environment resets correctly
+- Step executes actions properly
+- State tracking works
+- Rewards are calculated correctly
+
+### Running the Full Example
+
+Run the complete example that demonstrates the full workflow:
+
+```bash
+python3 examples/local_echo_env.py
+```
+
+This example shows:
+- Creating an environment from a Docker image
+- Resetting and stepping through the environment
+- Automatic cleanup with `close()`
+
+## Project Structure
+
+```
+echo_env/
+├── __init__.py            # Module exports
+├── README.md              # This file
+├── client.py              # EchoEnv client implementation
+├── models.py              # Action and Observation models
+└── server/
+    ├── __init__.py        # Server module exports
+    ├── echo_environment.py  # Core environment logic
+    ├── app.py             # FastAPI application
+    ├── test_echo_env.py   # Direct environment tests
+    └── Dockerfile         # Container image definition
+```

envs/echo_env/__init__.py

@@ -0,0 +1,29 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Echo Environment - A pure MCP environment for testing and demonstration.
+
+This environment exposes all functionality through MCP tools:
+- `echo_message(message)`: Echo back the provided message
+- `echo_with_length(message)`: Echo back the message with its length
+
+Example:
+    >>> from echo_env import EchoEnv
+    >>>
+    >>> with EchoEnv(base_url="http://localhost:8000") as env:
+    ...     env.reset()
+    ...     tools = env.list_tools()
+    ...     result = env.call_tool("echo_message", message="Hello!")
+    ...     print(result)  # "Hello!"
+"""
+
+# Re-export MCP types for convenience
+from openenv.core.env_server.mcp_types import CallToolAction, ListToolsAction
+
+from .client import EchoEnv
+
+__all__ = ["EchoEnv", "CallToolAction", "ListToolsAction"]

envs/echo_env/build/lib/build/lib/server/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Echo environment server components."""
+
+from .echo_environment import EchoEnvironment
+
+__all__ = ["EchoEnvironment"]

envs/echo_env/build/lib/build/lib/server/app.py

@@ -0,0 +1,57 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+FastAPI application for the Echo Environment.
+
+This module creates an HTTP server that exposes the EchoEnvironment
+over HTTP and WebSocket endpoints, compatible with EnvClient.
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn server.app:app --host 0.0.0.0 --port 8000 --workers 4
+
+    # Or run directly:
+    uv run --project . server
+"""
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.http_server import create_app
+    from ..models import EchoAction, EchoObservation
+    from .echo_environment import EchoEnvironment
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.http_server import create_app
+    from models import EchoAction, EchoObservation
+    from server.echo_environment import EchoEnvironment
+
+# Create the app with web interface and README integration
+# Pass the class (factory) instead of an instance for WebSocket session support
+app = create_app(EchoEnvironment, EchoAction, EchoObservation, env_name="echo_env")
+
+
+def main():
+    """
+    Entry point for direct execution via uv run or python -m.
+
+    This function enables running the server without Docker:
+        uv run --project . server
+        python -m envs.echo_env.server.app
+        openenv serve echo_env
+
+    """
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+
+
+if __name__ == "__main__":
+    main()

envs/echo_env/build/lib/build/lib/server/echo_environment.py

@@ -0,0 +1,102 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Echo Environment Implementation.
+
+A simple test environment that echoes back messages sent to it.
+Perfect for testing HTTP server infrastructure.
+"""
+
+from uuid import uuid4
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.interfaces import Environment
+    from openenv.core.env_server.types import State
+    from ..models import EchoAction, EchoObservation
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.interfaces import Environment
+    from openenv.core.env_server.types import State
+    from models import EchoAction, EchoObservation
+
+
+class EchoEnvironment(Environment):
+    """
+    A simple echo environment that echoes back messages.
+
+    This environment is designed for testing the HTTP server infrastructure.
+    It maintains minimal state and simply echoes back whatever message it receives.
+
+    Example:
+        >>> env = EchoEnvironment()
+        >>> obs = env.reset()
+        >>> print(obs.echoed_message)  # "Echo environment ready!"
+        >>>
+        >>> obs = env.step(EchoAction(message="Hello"))
+        >>> print(obs.echoed_message)  # "Hello"
+        >>> print(obs.message_length)  # 5
+    """
+
+    def __init__(self):
+        """Initialize the echo environment."""
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._reset_count = 0
+
+    def reset(self) -> EchoObservation:
+        """
+        Reset the environment.
+
+        Returns:
+            EchoObservation with a ready message
+        """
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._reset_count += 1
+
+        return EchoObservation(
+            echoed_message="Echo environment ready!",
+            message_length=0,
+            done=False,
+            reward=0.0,
+        )
+
+    def step(self, action: EchoAction) -> EchoObservation:  # type: ignore[override]
+        """
+        Execute a step in the environment by echoing the message.
+
+        Args:
+            action: EchoAction containing the message to echo
+
+        Returns:
+            EchoObservation with the echoed message and its length
+        """
+        self._state.step_count += 1
+
+        message = action.message
+        length = len(message)
+
+        # Simple reward: longer messages get higher rewards
+        reward = length * 0.1
+
+        return EchoObservation(
+            echoed_message=message,
+            message_length=length,
+            done=False,
+            reward=reward,
+            metadata={"original_message": message, "step": self._state.step_count},
+        )
+
+    @property
+    def state(self) -> State:
+        """
+        Get the current environment state.
+
+        Returns:
+            Current State with episode_id and step_count
+        """
+        return self._state

envs/echo_env/build/lib/echo_env/__init__.py

@@ -0,0 +1,29 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Echo Environment - A pure MCP environment for testing and demonstration.
+
+This environment exposes all functionality through MCP tools:
+- `echo_message(message)`: Echo back the provided message
+- `echo_with_length(message)`: Echo back the message with its length
+
+Example:
+    >>> from echo_env import EchoEnv
+    >>>
+    >>> with EchoEnv(base_url="http://localhost:8000") as env:
+    ...     env.reset()
+    ...     tools = env.list_tools()
+    ...     result = env.call_tool("echo_message", message="Hello!")
+    ...     print(result)  # "Hello!"
+"""
+
+from .client import EchoEnv
+
+# Re-export MCP types for convenience
+from openenv.core.env_server.mcp_types import CallToolAction, ListToolsAction
+
+__all__ = ["EchoEnv", "CallToolAction", "ListToolsAction"]

envs/echo_env/build/lib/echo_env/client.py

@@ -0,0 +1,81 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Echo Environment Client.
+
+This module provides the client for connecting to an Echo Environment server.
+EchoEnv extends MCPToolClient to provide tool-calling style interactions.
+
+Example:
+    >>> with EchoEnv(base_url="http://localhost:8000") as env:
+    ...     env.reset()
+    ...
+    ...     # Discover tools
+    ...     tools = env.list_tools()
+    ...     print([t.name for t in tools])  # ['echo_message', 'echo_with_length']
+    ...
+    ...     # Call tools
+    ...     result = env.call_tool("echo_message", message="Hello!")
+    ...     print(result)  # "Hello!"
+    ...
+    ...     result = env.call_tool("echo_with_length", message="Test")
+    ...     print(result)  # {"message": "Test", "length": 4}
+"""
+
+from openenv.core.mcp_client import MCPToolClient
+
+
+class EchoEnv(MCPToolClient):
+    """
+    Client for the Echo Environment.
+
+    This client provides a simple interface for interacting with the Echo
+    Environment via MCP tools. It inherits all functionality from MCPToolClient:
+    - `list_tools()`: Discover available tools
+    - `call_tool(name, **kwargs)`: Call a tool by name
+    - `reset(**kwargs)`: Reset the environment
+    - `step(action)`: Execute an action (for advanced use)
+
+    Example:
+        >>> # Connect to a running server
+        >>> with EchoEnv(base_url="http://localhost:8000") as env:
+        ...     env.reset()
+        ...
+        ...     # List available tools
+        ...     tools = env.list_tools()
+        ...     for tool in tools:
+        ...         print(f"{tool.name}: {tool.description}")
+        ...
+        ...     # Echo a message
+        ...     result = env.call_tool("echo_message", message="Hello!")
+        ...     print(result)  # "Hello!"
+        ...
+        ...     # Echo with length
+        ...     result = env.call_tool("echo_with_length", message="Test")
+        ...     print(result)  # {"message": "Test", "length": 4}
+
+    Example with Docker:
+        >>> # Automatically start container and connect
+        >>> env = EchoEnv.from_docker_image("echo-env:latest")
+        >>> try:
+        ...     env.reset()
+        ...     tools = env.list_tools()
+        ...     result = env.call_tool("echo_message", message="Hello!")
+        ... finally:
+        ...     env.close()
+
+    Example with HuggingFace Space:
+        >>> # Run from HuggingFace Space
+        >>> env = EchoEnv.from_env("openenv/echo-env")
+        >>> try:
+        ...     env.reset()
+        ...     result = env.call_tool("echo_message", message="Hello!")
+        ... finally:
+        ...     env.close()
+    """
+
+    pass  # MCPToolClient provides all needed functionality

envs/echo_env/build/lib/echo_env/server/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Echo environment server components."""
+
+from .echo_environment import EchoEnvironment
+
+__all__ = ["EchoEnvironment"]

envs/echo_env/build/lib/echo_env/server/app.py

@@ -0,0 +1,60 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+FastAPI application for the Echo Environment.
+
+This module creates an HTTP server that exposes the EchoEnvironment
+over HTTP and WebSocket endpoints, compatible with MCPToolClient.
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn server.app:app --host 0.0.0.0 --port 8000 --workers 4
+
+    # Or run directly:
+    uv run --project . server
+"""
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.http_server import create_app
+    from openenv.core.env_server.mcp_types import CallToolAction, CallToolObservation
+    from .echo_environment import EchoEnvironment
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.http_server import create_app
+    from openenv.core.env_server.mcp_types import CallToolAction, CallToolObservation
+    from server.echo_environment import EchoEnvironment
+
+# Create the app with web interface and README integration
+# Pass the class (factory) instead of an instance for WebSocket session support
+# Use MCP types for action/observation since this is a pure MCP environment
+app = create_app(
+    EchoEnvironment, CallToolAction, CallToolObservation, env_name="echo_env"
+)
+
+
+def main():
+    """
+    Entry point for direct execution via uv run or python -m.
+
+    This function enables running the server without Docker:
+        uv run --project . server
+        python -m envs.echo_env.server.app
+        openenv serve echo_env
+
+    """
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+
+
+if __name__ == "__main__":
+    main()

envs/echo_env/build/lib/echo_env/server/echo_environment.py

@@ -0,0 +1,196 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Echo Environment Implementation.
+
+A pure MCP environment that echoes back messages sent to it.
+This demonstrates how to build an MCPEnvironment with inline FastMCP tools.
+
+All interactions happen through MCP tools:
+- `echo_message(message)`: Echo back the provided message
+- `echo_with_length(message)`: Echo back the message with its length
+
+Example:
+    >>> from openenv.core.env_server.mcp_types import ListToolsAction, CallToolAction
+    >>> env = EchoEnvironment()
+    >>> env.reset()
+    >>>
+    >>> # List available tools
+    >>> obs = env.step(ListToolsAction())
+    >>> print([t.name for t in obs.tools])  # ["echo_message", "echo_with_length"]
+    >>>
+    >>> # Call a tool
+    >>> obs = env.step(CallToolAction(tool_name="echo_message", arguments={"message": "Hi!"}))
+    >>> print(obs.result)  # "Hi!"
+"""
+
+from typing import Any, Optional
+from uuid import uuid4
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.mcp_environment import MCPEnvironment
+    from openenv.core.env_server.types import Action, Observation, State
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.mcp_environment import MCPEnvironment
+    from openenv.core.env_server.types import Action, Observation, State
+
+from fastmcp import FastMCP
+
+
+class EchoEnvironment(MCPEnvironment):
+    """
+    A pure MCP echo environment that echoes back messages.
+
+    This environment exposes all functionality through MCP tools:
+    - `echo_message`: Echo back the provided message
+    - `echo_with_length`: Echo back the message with its length
+
+    The environment inherits MCP support (ListToolsAction, CallToolAction)
+    from the MCPEnvironment base class. No legacy action types are supported.
+
+    Example using MCPToolClient:
+        >>> from openenv.core.mcp_client import MCPToolClient
+        >>>
+        >>> with MCPToolClient(base_url="http://localhost:8000") as env:
+        ...     env.reset()
+        ...     tools = env.list_tools()
+        ...     print([t.name for t in tools])
+        ...     result = env.call_tool("echo_message", message="Hello!")
+        ...     print(result)
+    """
+
+    def __init__(self):
+        """Initialize the echo environment with MCP server and tools."""
+        # Create MCP server and define tools inline
+        mcp = FastMCP("echo_env")
+
+        @mcp.tool
+        def echo_message(message: str) -> str:
+            """
+            Echo back the provided message.
+
+            Args:
+                message: The message to echo back
+
+            Returns:
+                The same message that was provided
+            """
+            return message
+
+        @mcp.tool
+        def echo_with_length(message: str) -> dict:
+            """
+            Echo back the message with its length.
+
+            Args:
+                message: The message to echo back
+
+            Returns:
+                Dictionary with the message and its length
+            """
+            return {"message": message, "length": len(message)}
+
+        # Pass the MCP server to the base class
+        super().__init__(mcp)
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._reset_count = 0
+
+    def reset(
+        self,
+        seed: Optional[int] = None,
+        episode_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Observation:
+        """
+        Reset the environment.
+
+        Args:
+            seed: Optional random seed (unused in echo env)
+            episode_id: Optional episode ID to use
+            **kwargs: Additional reset options
+
+        Returns:
+            Observation indicating the environment is ready
+        """
+        self._state = State(
+            episode_id=episode_id or str(uuid4()),
+            step_count=0,
+        )
+        self._reset_count += 1
+
+        return Observation(
+            done=False,
+            reward=0.0,
+            metadata={"status": "ready", "message": "Echo environment ready!"},
+        )
+
+    def _step_impl(
+        self,
+        action: Action,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> Observation:
+        """
+        Handle non-MCP actions.
+
+        This environment only supports MCP actions (ListToolsAction, CallToolAction).
+        Any other action type returns an error observation.
+
+        Args:
+            action: The action to execute
+            timeout_s: Optional timeout (unused)
+            **kwargs: Additional arguments
+
+        Returns:
+            Observation with error for unknown action types
+        """
+        return Observation(
+            done=False,
+            reward=0.0,
+            metadata={
+                "error": f"Unknown action type: {type(action).__name__}. "
+                "Use ListToolsAction or CallToolAction for MCP interactions."
+            },
+        )
+
+    def step(
+        self,
+        action: Action,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> Observation:
+        """
+        Execute a step in the environment.
+
+        Delegates to base class for MCP actions. Increments step count for all actions.
+
+        Args:
+            action: The MCP action to execute (ListToolsAction or CallToolAction)
+            timeout_s: Optional timeout for the action
+            **kwargs: Additional arguments
+
+        Returns:
+            Observation from the action execution
+        """
+        # Increment step count for all actions
+        self._state.step_count += 1
+
+        # Let the base class handle MCP actions and non-MCP routing
+        return super().step(action, timeout_s=timeout_s, **kwargs)
+
+    @property
+    def state(self) -> State:
+        """
+        Get the current environment state.
+
+        Returns:
+            Current State with episode_id and step_count
+        """
+        return self._state

envs/echo_env/build/lib/server/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Echo environment server components."""
+
+from .echo_environment import EchoEnvironment
+
+__all__ = ["EchoEnvironment"]

envs/echo_env/build/lib/server/app.py

@@ -0,0 +1,57 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+FastAPI application for the Echo Environment.
+
+This module creates an HTTP server that exposes the EchoEnvironment
+over HTTP and WebSocket endpoints, compatible with EnvClient.
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn server.app:app --host 0.0.0.0 --port 8000 --workers 4
+
+    # Or run directly:
+    uv run --project . server
+"""
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.http_server import create_app
+    from ..models import EchoAction, EchoObservation
+    from .echo_environment import EchoEnvironment
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.http_server import create_app
+    from models import EchoAction, EchoObservation
+    from server.echo_environment import EchoEnvironment
+
+# Create the app with web interface and README integration
+# Pass the class (factory) instead of an instance for WebSocket session support
+app = create_app(EchoEnvironment, EchoAction, EchoObservation, env_name="echo_env")
+
+
+def main():
+    """
+    Entry point for direct execution via uv run or python -m.
+
+    This function enables running the server without Docker:
+        uv run --project . server
+        python -m envs.echo_env.server.app
+        openenv serve echo_env
+
+    """
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+
+
+if __name__ == "__main__":
+    main()

envs/echo_env/build/lib/server/echo_environment.py

@@ -0,0 +1,102 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Echo Environment Implementation.
+
+A simple test environment that echoes back messages sent to it.
+Perfect for testing HTTP server infrastructure.
+"""
+
+from uuid import uuid4
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.interfaces import Environment
+    from openenv.core.env_server.types import State
+    from ..models import EchoAction, EchoObservation
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.interfaces import Environment
+    from openenv.core.env_server.types import State
+    from models import EchoAction, EchoObservation
+
+
+class EchoEnvironment(Environment):
+    """
+    A simple echo environment that echoes back messages.
+
+    This environment is designed for testing the HTTP server infrastructure.
+    It maintains minimal state and simply echoes back whatever message it receives.
+
+    Example:
+        >>> env = EchoEnvironment()
+        >>> obs = env.reset()
+        >>> print(obs.echoed_message)  # "Echo environment ready!"
+        >>>
+        >>> obs = env.step(EchoAction(message="Hello"))
+        >>> print(obs.echoed_message)  # "Hello"
+        >>> print(obs.message_length)  # 5
+    """
+
+    def __init__(self):
+        """Initialize the echo environment."""
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._reset_count = 0
+
+    def reset(self) -> EchoObservation:
+        """
+        Reset the environment.
+
+        Returns:
+            EchoObservation with a ready message
+        """
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._reset_count += 1
+
+        return EchoObservation(
+            echoed_message="Echo environment ready!",
+            message_length=0,
+            done=False,
+            reward=0.0,
+        )
+
+    def step(self, action: EchoAction) -> EchoObservation:  # type: ignore[override]
+        """
+        Execute a step in the environment by echoing the message.
+
+        Args:
+            action: EchoAction containing the message to echo
+
+        Returns:
+            EchoObservation with the echoed message and its length
+        """
+        self._state.step_count += 1
+
+        message = action.message
+        length = len(message)
+
+        # Simple reward: longer messages get higher rewards
+        reward = length * 0.1
+
+        return EchoObservation(
+            echoed_message=message,
+            message_length=length,
+            done=False,
+            reward=reward,
+            metadata={"original_message": message, "step": self._state.step_count},
+        )
+
+    @property
+    def state(self) -> State:
+        """
+        Get the current environment state.
+
+        Returns:
+            Current State with episode_id and step_count
+        """
+        return self._state

envs/echo_env/client.py

@@ -0,0 +1,81 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Echo Environment Client.
+
+This module provides the client for connecting to an Echo Environment server.
+EchoEnv extends MCPToolClient to provide tool-calling style interactions.
+
+Example:
+    >>> with EchoEnv(base_url="http://localhost:8000") as env:
+    ...     env.reset()
+    ...
+    ...     # Discover tools
+    ...     tools = env.list_tools()
+    ...     print([t.name for t in tools])  # ['echo_message', 'echo_with_length']
+    ...
+    ...     # Call tools
+    ...     result = env.call_tool("echo_message", message="Hello!")
+    ...     print(result)  # "Hello!"
+    ...
+    ...     result = env.call_tool("echo_with_length", message="Test")
+    ...     print(result)  # {"message": "Test", "length": 4}
+"""
+
+from openenv.core.mcp_client import MCPToolClient
+
+
+class EchoEnv(MCPToolClient):
+    """
+    Client for the Echo Environment.
+
+    This client provides a simple interface for interacting with the Echo
+    Environment via MCP tools. It inherits all functionality from MCPToolClient:
+    - `list_tools()`: Discover available tools
+    - `call_tool(name, **kwargs)`: Call a tool by name
+    - `reset(**kwargs)`: Reset the environment
+    - `step(action)`: Execute an action (for advanced use)
+
+    Example:
+        >>> # Connect to a running server
+        >>> with EchoEnv(base_url="http://localhost:8000") as env:
+        ...     env.reset()
+        ...
+        ...     # List available tools
+        ...     tools = env.list_tools()
+        ...     for tool in tools:
+        ...         print(f"{tool.name}: {tool.description}")
+        ...
+        ...     # Echo a message
+        ...     result = env.call_tool("echo_message", message="Hello!")
+        ...     print(result)  # "Hello!"
+        ...
+        ...     # Echo with length
+        ...     result = env.call_tool("echo_with_length", message="Test")
+        ...     print(result)  # {"message": "Test", "length": 4}
+
+    Example with Docker:
+        >>> # Automatically start container and connect
+        >>> env = EchoEnv.from_docker_image("echo-env:latest")
+        >>> try:
+        ...     env.reset()
+        ...     tools = env.list_tools()
+        ...     result = env.call_tool("echo_message", message="Hello!")
+        ... finally:
+        ...     env.close()
+
+    Example with HuggingFace Space:
+        >>> # Run from HuggingFace Space
+        >>> env = EchoEnv.from_env("openenv/echo-env")
+        >>> try:
+        ...     env.reset()
+        ...     result = env.call_tool("echo_message", message="Hello!")
+        ... finally:
+        ...     env.close()
+    """
+
+    pass  # MCPToolClient provides all needed functionality

envs/echo_env/openenv.yaml

@@ -0,0 +1,6 @@
+spec_version: 1
+name: echo_env
+type: space
+runtime: fastapi
+app: server.app:app
+port: 8000

envs/echo_env/openenv_echo_env.egg-info/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: openenv-echo-env
+Version: 0.1.0
+Summary: Echo Environment for OpenEnv - simple test environment that echoes back messages
+Requires-Python: >=3.10
+Requires-Dist: openenv-core[core]>=0.2.1
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: uvicorn>=0.24.0
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"

envs/echo_env/openenv_echo_env.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+__init__.py
+client.py
+pyproject.toml
+./__init__.py
+./client.py
+openenv_echo_env.egg-info/PKG-INFO
+openenv_echo_env.egg-info/SOURCES.txt
+openenv_echo_env.egg-info/dependency_links.txt
+openenv_echo_env.egg-info/entry_points.txt
+openenv_echo_env.egg-info/requires.txt
+openenv_echo_env.egg-info/top_level.txt
+server/__init__.py
+server/app.py
+server/echo_environment.py

envs/echo_env/openenv_echo_env.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

envs/echo_env/openenv_echo_env.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+server = echo_env.server.app:main

envs/echo_env/openenv_echo_env.egg-info/requires.txt

@@ -0,0 +1,9 @@
+openenv-core[core]>=0.2.1
+fastapi>=0.115.0
+pydantic>=2.0.0
+uvicorn>=0.24.0
+requests>=2.31.0
+
+[dev]
+pytest>=8.0.0
+pytest-cov>=4.0.0

envs/echo_env/openenv_echo_env.egg-info/top_level.txt

@@ -0,0 +1 @@
+echo_env

envs/echo_env/pyproject.toml

@@ -0,0 +1,40 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openenv-echo-env"
+version = "0.1.0"
+description = "Echo Environment for OpenEnv - simple test environment that echoes back messages"
+requires-python = ">=3.10"
+dependencies = [
+    # Core OpenEnv dependencies (required for server functionality)
+    "openenv-core[core] @ git+https://github.com/meta-pytorch/OpenEnv.git@v0.2.3",
+    "fastapi>=0.115.0",
+    "pydantic>=2.0.0",
+    "uvicorn>=0.24.0",
+    "requests>=2.31.0",
+    # No additional environment-specific dependencies needed for echo_env
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.scripts]
+# Server entry point - enables running via: uv run --project . server
+# or: python -m echo_env.server.app
+server = "echo_env.server.app:main"
+
+[tool.setuptools]
+include-package-data = true
+packages = ["echo_env", "echo_env.server"]
+package-dir = { "echo_env" = ".", "echo_env.server" = "server" }

envs/echo_env/server/Dockerfile

@@ -0,0 +1,81 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+# Multi-stage build using openenv-base
+# This Dockerfile is flexible and works for both:
+# - In-repo environments (with local src/core)
+# - Standalone environments (with openenv-core from pip)
+# The build script (openenv build) handles context detection and sets appropriate build args.
+
+ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
+FROM ${BASE_IMAGE} AS builder
+
+WORKDIR /app
+
+# Build argument to control whether we're building standalone or in-repo
+ARG BUILD_MODE=in-repo
+
+# Copy environment code (always at root of build context)
+COPY . /app/env
+
+# For in-repo builds, openenv-core is already in the pyproject.toml dependencies
+# For standalone builds, openenv-core will be installed from pip via pyproject.toml
+WORKDIR /app/env
+
+# Ensure uv is available (for local builds where base image lacks it)
+RUN if ! command -v uv >/dev/null 2>&1; then \
+        curl -LsSf https://astral.sh/uv/install.sh | sh && \
+        mv /root/.local/bin/uv /usr/local/bin/uv && \
+        mv /root/.local/bin/uvx /usr/local/bin/uvx; \
+    fi
+
+# Install git for building from git repos (build-time only)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install dependencies using uv sync
+# First pass: install dependencies without the project (for better caching)
+# Second pass: install the project itself
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-install-project --no-editable; \
+    else \
+        uv sync --no-install-project --no-editable; \
+    fi
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-editable; \
+    else \
+        uv sync --no-editable; \
+    fi
+
+# Final runtime stage
+FROM ${BASE_IMAGE}
+
+WORKDIR /app
+
+# Copy the virtual environment from builder
+COPY --from=builder /app/env/.venv /app/.venv
+
+# Copy the environment code
+COPY --from=builder /app/env /app/env
+
+# Set PATH to use the virtual environment
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Set PYTHONPATH so imports work correctly
+ENV PYTHONPATH="/app/env:$PYTHONPATH"
+ENV ENABLE_WEB_INTERFACE=true
+
+# Health check using Python (more portable than curl/wget)
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')" || exit 1
+
+# Run the FastAPI server
+# The module path is constructed to work with the /app/env structure
+CMD ["sh", "-c", "cd /app/env && uvicorn server.app:app --host 0.0.0.0 --port 8000"]

envs/echo_env/server/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Echo environment server components."""
+
+from .echo_environment import EchoEnvironment
+
+__all__ = ["EchoEnvironment"]

envs/echo_env/server/app.py

@@ -0,0 +1,61 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+FastAPI application for the Echo Environment.
+
+This module creates an HTTP server that exposes the EchoEnvironment
+over HTTP and WebSocket endpoints, compatible with MCPToolClient.
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn server.app:app --host 0.0.0.0 --port 8000 --workers 4
+
+    # Or run directly:
+    uv run --project . server
+"""
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.http_server import create_app
+    from openenv.core.env_server.mcp_types import CallToolAction, CallToolObservation
+
+    from .echo_environment import EchoEnvironment
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.http_server import create_app
+    from openenv.core.env_server.mcp_types import CallToolAction, CallToolObservation
+    from server.echo_environment import EchoEnvironment
+
+# Create the app with web interface and README integration
+# Pass the class (factory) instead of an instance for WebSocket session support
+# Use MCP types for action/observation since this is a pure MCP environment
+app = create_app(
+    EchoEnvironment, CallToolAction, CallToolObservation, env_name="echo_env"
+)
+
+
+def main():
+    """
+    Entry point for direct execution via uv run or python -m.
+
+    This function enables running the server without Docker:
+        uv run --project . server
+        python -m envs.echo_env.server.app
+        openenv serve echo_env
+
+    """
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+
+
+if __name__ == "__main__":
+    main()

envs/echo_env/server/echo_environment.py

@@ -0,0 +1,211 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Echo Environment Implementation.
+
+A pure MCP environment that echoes back messages sent to it.
+This demonstrates how to build an MCPEnvironment with inline FastMCP tools.
+
+All interactions happen through MCP tools:
+- `echo_message(message)`: Echo back the provided message
+- `echo_with_length(message)`: Echo back the message with its length
+
+Example:
+    >>> from openenv.core.env_server.mcp_types import ListToolsAction, CallToolAction
+    >>> env = EchoEnvironment()
+    >>> env.reset()
+    >>>
+    >>> # List available tools
+    >>> obs = env.step(ListToolsAction())
+    >>> print([t.name for t in obs.tools])  # ["echo_message", "echo_with_length"]
+    >>>
+    >>> # Call a tool
+    >>> obs = env.step(CallToolAction(tool_name="echo_message", arguments={"message": "Hi!"}))
+    >>> print(obs.result)  # "Hi!"
+"""
+
+from typing import Any, Optional
+from uuid import uuid4
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.mcp_environment import MCPEnvironment
+    from openenv.core.env_server.types import Action, Observation, State
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.mcp_environment import MCPEnvironment
+    from openenv.core.env_server.types import Action, Observation, State
+
+from fastmcp import FastMCP
+
+
+class EchoEnvironment(MCPEnvironment):
+    """
+    A pure MCP echo environment that echoes back messages.
+
+    This environment exposes all functionality through MCP tools:
+    - `echo_message`: Echo back the provided message
+    - `echo_with_length`: Echo back the message with its length
+
+    The environment inherits MCP support (ListToolsAction, CallToolAction)
+    from the MCPEnvironment base class. No legacy action types are supported.
+
+    Example using MCPToolClient:
+        >>> from openenv.core.mcp_client import MCPToolClient
+        >>>
+        >>> with MCPToolClient(base_url="http://localhost:8000") as env:
+        ...     env.reset()
+        ...     tools = env.list_tools()
+        ...     print([t.name for t in tools])
+        ...     result = env.call_tool("echo_message", message="Hello!")
+        ...     print(result)
+    """
+
+    def __init__(self):
+        """Initialize the echo environment with MCP server and tools."""
+        # Create MCP server and define tools inline
+        mcp = FastMCP("echo_env")
+
+        @mcp.tool
+        def echo_message(message: str) -> str:
+            """
+            Echo back the provided message.
+
+            Args:
+                message: The message to echo back
+
+            Returns:
+                The same message that was provided
+            """
+            return message
+
+        @mcp.tool
+        def echo_with_length(message: str) -> dict:
+            """
+            Echo back the message with its length.
+
+            Args:
+                message: The message to echo back
+
+            Returns:
+                Dictionary with the message and its length
+            """
+            return {"message": message, "length": len(message)}
+
+        # Pass the MCP server to the base class
+        super().__init__(mcp)
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._reset_count = 0
+
+    def reset(
+        self,
+        seed: Optional[int] = None,
+        episode_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Observation:
+        """
+        Reset the environment.
+
+        Args:
+            seed: Optional random seed (unused in echo env)
+            episode_id: Optional episode ID to use
+            **kwargs: Additional reset options
+
+        Returns:
+            Observation indicating the environment is ready
+        """
+        self._state = State(
+            episode_id=episode_id or str(uuid4()),
+            step_count=0,
+        )
+        self._reset_count += 1
+
+        return Observation(
+            done=False,
+            reward=0.0,
+            metadata={"status": "ready", "message": "Echo environment ready!"},
+        )
+
+    def _step_impl(
+        self,
+        action: Action,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> Observation:
+        """
+        Handle non-MCP actions.
+
+        This environment only supports MCP actions (ListToolsAction, CallToolAction).
+        Any other action type returns an error observation.
+
+        Args:
+            action: The action to execute
+            timeout_s: Optional timeout (unused)
+            **kwargs: Additional arguments
+
+        Returns:
+            Observation with error for unknown action types
+        """
+        return Observation(
+            done=False,
+            reward=0.0,
+            metadata={
+                "error": f"Unknown action type: {type(action).__name__}. "
+                "Use ListToolsAction or CallToolAction for MCP interactions."
+            },
+        )
+
+    def step(
+        self,
+        action: Action,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> Observation:
+        """
+        Execute a step in the environment.
+
+        Delegates to base class for MCP actions. Increments step count for all actions.
+
+        Args:
+            action: The MCP action to execute (ListToolsAction or CallToolAction)
+            timeout_s: Optional timeout for the action
+            **kwargs: Additional arguments
+
+        Returns:
+            Observation from the action execution
+        """
+        # Increment step count for all actions
+        self._state.step_count += 1
+
+        # Let the base class handle MCP actions and non-MCP routing
+        return super().step(action, timeout_s=timeout_s, **kwargs)
+
+    async def step_async(
+        self,
+        action: Action,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> Observation:
+        """
+        Async step used by the WebSocket handler.
+
+        Increments step count then delegates to MCPEnvironment.step_async,
+        which routes MCP actions without going through run_async_safely.
+        """
+        self._state.step_count += 1
+        return await super().step_async(action, timeout_s=timeout_s, **kwargs)
+
+    @property
+    def state(self) -> State:
+        """
+        Get the current environment state.
+
+        Returns:
+            Current State with episode_id and step_count
+        """
+        return self._state

models.py

@@ -0,0 +1,34 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Data models for the Echo Environment.
+
+The Echo environment is a simple test environment that echoes back messages.
+"""
+
+from pydantic import Field
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.types import Action, Observation
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.types import Action, Observation
+
+
+class EchoAction(Action):
+    """Action for the Echo environment - just a message to echo."""
+
+    message: str = Field(..., min_length=1, description="Message to echo back")
+
+
+class EchoObservation(Observation):
+    """Observation from the Echo environment - the echoed message."""
+
+    echoed_message: str = Field(..., description="The echoed message from the environment")
+    message_length: int = Field(default=0, ge=0, description="Length of the echoed message")

openenv.yaml

@@ -0,0 +1,6 @@
+spec_version: 1
+name: echo_env
+type: space
+runtime: fastapi
+app: server.app:app
+port: 8000

openenv_echo_env.egg-info/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: openenv-echo-env
+Version: 0.1.0
+Summary: Echo Environment for OpenEnv - simple test environment that echoes back messages
+Requires-Python: >=3.10
+Requires-Dist: openenv-core[core]>=0.2.1
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: uvicorn>=0.24.0
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"

openenv_echo_env.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+__init__.py
+client.py
+pyproject.toml
+./__init__.py
+./client.py
+openenv_echo_env.egg-info/PKG-INFO
+openenv_echo_env.egg-info/SOURCES.txt
+openenv_echo_env.egg-info/dependency_links.txt
+openenv_echo_env.egg-info/entry_points.txt
+openenv_echo_env.egg-info/requires.txt
+openenv_echo_env.egg-info/top_level.txt
+server/__init__.py
+server/app.py
+server/echo_environment.py

openenv_echo_env.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

openenv_echo_env.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+server = echo_env.server.app:main

openenv_echo_env.egg-info/requires.txt

@@ -0,0 +1,9 @@
+openenv-core[core]>=0.2.1
+fastapi>=0.115.0
+pydantic>=2.0.0
+uvicorn>=0.24.0
+requests>=2.31.0
+
+[dev]
+pytest>=8.0.0
+pytest-cov>=4.0.0

openenv_echo_env.egg-info/top_level.txt

@@ -0,0 +1 @@
+echo_env