Add official OpenEnv echo_env sample

README.md

@@ -1,10 +1,160 @@
 ---
-title: Openenv Echo Docs
-emoji: 😻
-colorFrom: yellow
+title: Echo Environment Server
+emoji: 🔊
+colorFrom: blue
 colorTo: blue
 sdk: docker
 pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 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"]

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

openenv.yaml

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

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]>=0.2.1",
+    "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" }

server/Dockerfile

@@ -0,0 +1,80 @@
+# 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"
+
+# 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"]

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"]

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()

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