openenv 0.2.0__tar.gz → 0.2.1__tar.gz

{openenv-0.2.0/src/openenv.egg-info → openenv-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openenv
-Version: 0.2.0
+Version: 0.2.1
 Summary: A unified framework for reinforcement learning environments
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -17,6 +17,7 @@ Requires-Dist: openai>=2.7.2
 Requires-Dist: tomli>=2.3.0
 Requires-Dist: tomli-w>=1.2.0
 Requires-Dist: websockets>=15.0.1
+Requires-Dist: fastmcp>=2.0.0
 Provides-Extra: core
 Requires-Dist: fastapi>=0.104.0; extra == "core"
 Requires-Dist: pydantic>=2.0.0; extra == "core"
@@ -49,10 +50,49 @@ An e2e framework for creating, deploying and using isolated execution environmen
 
 **🚀 Featured Example:** Train LLMs to play BlackJack using [torchforge](https://github.com/meta-pytorch/torchforge) (PyTorch's agentic RL framework): [`examples/grpo_blackjack/`](examples/grpo_blackjack/)
 
+**🔥 GPU Mode Tutorial:** End to end tutorial from [GPU Mode](gpu-mode-tutorial/README.md) blog post.
+
+## Quick Start
+
+Install the OpenEnv core package:
+
+```bash
+pip install openenv
+```
+
+Install an environment client (e.g., Echo):
+
+```bash
+pip install git+https://huggingface.co/spaces/openenv/echo_env
+```
+
+Then use the environment:
+
+```python
+from echo_env import EchoAction, EchoEnv
+
+# Connect to a running Space
+client = EchoEnv(base_url="https://openenv-echo-env.hf.space")
+
+# Reset the environment
+result = client.reset()
+print(result.observation.echoed_message)  # "Echo environment ready!"
+
+# Send messages
+result = client.step(EchoAction(message="Hello, World!"))
+print(result.observation.echoed_message)  # "Hello, World!"
+print(result.reward)  # 1.3 (based on message length)
+
+# Cleanup
+client.close()
+```
+
+For a detailed quick start, check out the [docs page](https://meta-pytorch.org/OpenEnv/quickstart/).
+
 ## OpenEnv on partner platforms:
 
 - [Lightning AI Studio](https://lightning.ai/environments?section=featured)
-- [TRL example](https://huggingface.co/docs/trl/main/en/openenv)
+- [TRL example](https://huggingface.co/docs/trl/openenv)
 - [Unsloth Google Colab](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/OpenEnv_gpt_oss_(20B)_Reinforcement_Learning_2048_Game.ipynb)
 - [ART example](https://art.openpipe.ai/integrations/openenv-integration)
 - [Oumi example](https://github.com/oumi-ai/oumi/blob/main/notebooks/Oumi%20-%20OpenEnv%20GRPO%20with%20trl.ipynb)
@@ -87,10 +127,10 @@ Below is a list of active and historical RFCs for OpenEnv. RFCs are proposals fo
 │                    Client Application                   │
 │  ┌────────────────┐              ┌──────────────────┐   │
 │  │  EchoEnv       │              │  CodingEnv       │   │
-│  │ (HTTPEnvClient)│              │  (HTTPEnvClient) │   │
+│  │  (EnvClient)   │              │   (EnvClient)    │   │
 │  └────────┬───────┘              └────────┬─────────┘   │
 └───────────┼───────────────────────────────┼─────────────┘
-            │ HTTP                          │ HTTP
+            │ WebSocket                     │ WebSocket
             │ (reset, step, state)          │
 ┌───────────▼───────────────────────────────▼─────────────┐
 │              Docker Containers (Isolated)               │
@@ -137,9 +177,9 @@ Base class for implementing environment logic:
 - **`step(action)`**: Execute an `Action`, returns resulting `Observation`
 - **`state()`**: Access episode metadata (`State` with episode_id, step_count, etc.)
 
-#### 3. HTTPEnvClient (Client-Side)
-Base class for HTTP communication:
-- Handles HTTP requests to environment server
+#### 3. EnvClient (Client-Side)
+Base class for environment communication:
+- Handles WebSocket connections to environment server
 - Contains a utility to spin up a docker container locally for the corresponding environment
 - Type-safe action/observation parsing
 
@@ -172,7 +212,7 @@ my_env/
 ├── .dockerignore        # Docker build exclusions
 ├── __init__.py           # Export YourAction, YourObservation, YourEnv
 ├── models.py             # Define Action, Observation, State dataclasses
-├── client.py             # Implement YourEnv(HTTPEnvClient)
+├── client.py             # Implement YourEnv(EnvClient)
 ├── README.md             # Document your environment
 ├── openenv.yaml          # Environment manifest
 ├── pyproject.toml        # Dependencies and package configuration
@@ -219,10 +259,11 @@ See [`envs/README.md`](envs/README.md) for a complete guide on building environm
 ### For Environment Users
 
 To use an environment:
-1. Import from `envs.your_env`: `from envs.echo_env import EchoAction, EchoEnv`
-2. Create client: `client = EchoEnv.from_docker_image("echo-env:latest")`
-3. Interact: `client.reset()`, `client.step(action)`, `client.state()`
-4. Cleanup: `client.close()`
+1. Install the client: `pip install git+https://huggingface.co/spaces/openenv/echo-env`
+2. Import: `from echo_env import EchoAction, EchoEnv`
+3. Create client: `client = EchoEnv(base_url="https://openenv-echo-env.hf.space")`
+4. Interact: `client.reset()`, `client.step(action)`, `client.state()`
+5. Cleanup: `client.close()`
 
 See example scripts in `examples/` directory.
 
@@ -253,37 +294,56 @@ For detailed options: `openenv init --help` and `openenv push --help`.
 3. **Container Isolation**: Each environment runs in its own container
 4. **Simple APIs**: Minimal, intuitive interfaces
 
-## Quick Start
+## Development
 
-### Using the Echo Environment(Example)
+### Installation
 
-```python
-from envs.echo_env import EchoAction, EchoEnv
+```bash
+# Clone the repository
+git clone https://github.com/meta-pytorch/OpenEnv.git
+cd OpenEnv
 
-# Automatically start container and connect
-client = EchoEnv.from_docker_image("echo-env:latest")
+# Install core package in editable mode
+pip install -e .
+# Or using uv (faster)
+uv pip install -e .
+```
 
-# Reset the environment
-result = client.reset()
-print(result.observation.echoed_message)  # "Echo environment ready!"
+### Running Tests
 
-# Send messages
-result = client.step(EchoAction(message="Hello, World!"))
-print(result.observation.echoed_message)  # "Hello, World!"
-print(result.reward)  # 1.3 (based on message length)
+OpenEnv uses a modular dependency structure: the core package is minimal, and each environment has its own dependencies. This means some tests require environment-specific packages.
 
-# Cleanup
-client.close()  # Stops and removes container
+```bash
+# Install pytest (required for running tests)
+uv pip install pytest
+
+# Run all tests (skips tests requiring uninstalled dependencies)
+PYTHONPATH=src:envs uv run pytest tests/ -v --tb=short
+
+# Run a specific test file
+PYTHONPATH=src:envs uv run pytest tests/envs/test_echo_environment.py -v
 ```
 
+**To run environment-specific tests**, install that environment's dependencies:
+
+```bash
+# Example: Install coding_env with dev dependencies (includes smolagents + pytest)
+uv pip install -e "envs/coding_env[dev]"
+
+# Then run coding_env tests
+PYTHONPATH=src:envs uv run pytest tests/envs/test_python_codeact_rewards.py -v
+```
+
+Tests will be automatically skipped if their required dependencies aren't installed.
+
 ## Requirements
 
-- Python 3.11+
+- Python 3.10+
 - Docker Desktop or Docker Engine
 - FastAPI >= 0.104.0
 - Uvicorn >= 0.24.0
 - Requests >= 2.25.0
-- smolagents (for coding environment)
+- Environment-specific dependencies (e.g., smolagents for coding_env)
 
 ## Supported RL Tools
 The goal of this project is to support a broad set of open and closed tools to help standardize the agentic RL community. If you have a project that supports OpenEnv environments, please put up a PR to add your tool name along with a link to your documentation.
@@ -292,7 +352,7 @@ The goal of this project is to support a broad set of open and closed tools to h
 See GRPO BlackJack training example: [`examples/grpo_blackjack/`](examples/grpo_blackjack/)
 
 ### TRL
-See the [TRL example](https://huggingface.co/docs/trl/main/en/openenv) on how to integrate OpenEnv environments with GRPO training.
+See the [TRL example](https://huggingface.co/docs/trl/openenv) on how to integrate OpenEnv environments with GRPO training.
 
 ### Unsloth
 See the 2048 game example based on gpt-oss: [Colab notebook](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/OpenEnv_gpt_oss_(20B)_Reinforcement_Learning_2048_Game.ipynb)
@@ -328,7 +388,7 @@ See: [`envs/coding_env/README.md`](envs/coding_env/README.md)
 ## Community Support & Acknowledgments
 This is an open and community-centric project. If you would like to add your name here, please put up a pull request and tag @jspisak for review. Ty!!
 
-Supporters include: Meta-PyTorch, Hugging Face, [Patronus AI](https://patronus.ai), [Surge AI](https://surgehq.ai), [LastMile AI](https://www.lastmileai.dev), Unsloth AI, Reflection AI, vLLM, SkyRL (UC-Berkeley), LightningAI, Axolotl AI, Stanford Scaling Intelligence Lab, Mithril, [OpenMined](https://openmined.org/), [Fleet AI](https://fleetai.com), [Halluminate](https://halluminate.ai/), [Turing](https://www.turing.com/) ..
+Supporters include: Meta-PyTorch, Hugging Face, [Scaler AI Labs](https://scalerailabs.com), [Patronus AI](https://patronus.ai), [Surge AI](https://surgehq.ai), [LastMile AI](https://www.lastmileai.dev), Unsloth AI, Reflection AI, vLLM, SkyRL (UC-Berkeley), LightningAI, Axolotl AI, Stanford Scaling Intelligence Lab, Mithril, [OpenMined](https://openmined.org/), [Fleet AI](https://fleetai.com), [Halluminate](https://halluminate.ai/), [Turing](https://www.turing.com/), [Scale AI](https://scale.com/) ..
 
 And we'd also like to acknowledge the team at Farama Foundation as the OpenEnv API was heavily inspired by the work you all have done on Gymnasium. Cheers!
 

{openenv-0.2.0 → openenv-0.2.1}/README.md

@@ -11,10 +11,49 @@ An e2e framework for creating, deploying and using isolated execution environmen
 
 **🚀 Featured Example:** Train LLMs to play BlackJack using [torchforge](https://github.com/meta-pytorch/torchforge) (PyTorch's agentic RL framework): [`examples/grpo_blackjack/`](examples/grpo_blackjack/)
 
+**🔥 GPU Mode Tutorial:** End to end tutorial from [GPU Mode](gpu-mode-tutorial/README.md) blog post.
+
+## Quick Start
+
+Install the OpenEnv core package:
+
+```bash
+pip install openenv
+```
+
+Install an environment client (e.g., Echo):
+
+```bash
+pip install git+https://huggingface.co/spaces/openenv/echo_env
+```
+
+Then use the environment:
+
+```python
+from echo_env import EchoAction, EchoEnv
+
+# Connect to a running Space
+client = EchoEnv(base_url="https://openenv-echo-env.hf.space")
+
+# Reset the environment
+result = client.reset()
+print(result.observation.echoed_message)  # "Echo environment ready!"
+
+# Send messages
+result = client.step(EchoAction(message="Hello, World!"))
+print(result.observation.echoed_message)  # "Hello, World!"
+print(result.reward)  # 1.3 (based on message length)
+
+# Cleanup
+client.close()
+```
+
+For a detailed quick start, check out the [docs page](https://meta-pytorch.org/OpenEnv/quickstart/).
+
 ## OpenEnv on partner platforms:
 
 - [Lightning AI Studio](https://lightning.ai/environments?section=featured)
-- [TRL example](https://huggingface.co/docs/trl/main/en/openenv)
+- [TRL example](https://huggingface.co/docs/trl/openenv)
 - [Unsloth Google Colab](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/OpenEnv_gpt_oss_(20B)_Reinforcement_Learning_2048_Game.ipynb)
 - [ART example](https://art.openpipe.ai/integrations/openenv-integration)
 - [Oumi example](https://github.com/oumi-ai/oumi/blob/main/notebooks/Oumi%20-%20OpenEnv%20GRPO%20with%20trl.ipynb)
@@ -49,10 +88,10 @@ Below is a list of active and historical RFCs for OpenEnv. RFCs are proposals fo
 │                    Client Application                   │
 │  ┌────────────────┐              ┌──────────────────┐   │
 │  │  EchoEnv       │              │  CodingEnv       │   │
-│  │ (HTTPEnvClient)│              │  (HTTPEnvClient) │   │
+│  │  (EnvClient)   │              │   (EnvClient)    │   │
 │  └────────┬───────┘              └────────┬─────────┘   │
 └───────────┼───────────────────────────────┼─────────────┘
-            │ HTTP                          │ HTTP
+            │ WebSocket                     │ WebSocket
             │ (reset, step, state)          │
 ┌───────────▼───────────────────────────────▼─────────────┐
 │              Docker Containers (Isolated)               │
@@ -99,9 +138,9 @@ Base class for implementing environment logic:
 - **`step(action)`**: Execute an `Action`, returns resulting `Observation`
 - **`state()`**: Access episode metadata (`State` with episode_id, step_count, etc.)
 
-#### 3. HTTPEnvClient (Client-Side)
-Base class for HTTP communication:
-- Handles HTTP requests to environment server
+#### 3. EnvClient (Client-Side)
+Base class for environment communication:
+- Handles WebSocket connections to environment server
 - Contains a utility to spin up a docker container locally for the corresponding environment
 - Type-safe action/observation parsing
 
@@ -134,7 +173,7 @@ my_env/
 ├── .dockerignore        # Docker build exclusions
 ├── __init__.py           # Export YourAction, YourObservation, YourEnv
 ├── models.py             # Define Action, Observation, State dataclasses
-├── client.py             # Implement YourEnv(HTTPEnvClient)
+├── client.py             # Implement YourEnv(EnvClient)
 ├── README.md             # Document your environment
 ├── openenv.yaml          # Environment manifest
 ├── pyproject.toml        # Dependencies and package configuration
@@ -181,10 +220,11 @@ See [`envs/README.md`](envs/README.md) for a complete guide on building environm
 ### For Environment Users
 
 To use an environment:
-1. Import from `envs.your_env`: `from envs.echo_env import EchoAction, EchoEnv`
-2. Create client: `client = EchoEnv.from_docker_image("echo-env:latest")`
-3. Interact: `client.reset()`, `client.step(action)`, `client.state()`
-4. Cleanup: `client.close()`
+1. Install the client: `pip install git+https://huggingface.co/spaces/openenv/echo-env`
+2. Import: `from echo_env import EchoAction, EchoEnv`
+3. Create client: `client = EchoEnv(base_url="https://openenv-echo-env.hf.space")`
+4. Interact: `client.reset()`, `client.step(action)`, `client.state()`
+5. Cleanup: `client.close()`
 
 See example scripts in `examples/` directory.
 
@@ -215,37 +255,56 @@ For detailed options: `openenv init --help` and `openenv push --help`.
 3. **Container Isolation**: Each environment runs in its own container
 4. **Simple APIs**: Minimal, intuitive interfaces
 
-## Quick Start
+## Development
 
-### Using the Echo Environment(Example)
+### Installation
 
-```python
-from envs.echo_env import EchoAction, EchoEnv
+```bash
+# Clone the repository
+git clone https://github.com/meta-pytorch/OpenEnv.git
+cd OpenEnv
 
-# Automatically start container and connect
-client = EchoEnv.from_docker_image("echo-env:latest")
+# Install core package in editable mode
+pip install -e .
+# Or using uv (faster)
+uv pip install -e .
+```
 
-# Reset the environment
-result = client.reset()
-print(result.observation.echoed_message)  # "Echo environment ready!"
+### Running Tests
 
-# Send messages
-result = client.step(EchoAction(message="Hello, World!"))
-print(result.observation.echoed_message)  # "Hello, World!"
-print(result.reward)  # 1.3 (based on message length)
+OpenEnv uses a modular dependency structure: the core package is minimal, and each environment has its own dependencies. This means some tests require environment-specific packages.
 
-# Cleanup
-client.close()  # Stops and removes container
+```bash
+# Install pytest (required for running tests)
+uv pip install pytest
+
+# Run all tests (skips tests requiring uninstalled dependencies)
+PYTHONPATH=src:envs uv run pytest tests/ -v --tb=short
+
+# Run a specific test file
+PYTHONPATH=src:envs uv run pytest tests/envs/test_echo_environment.py -v
 ```
 
+**To run environment-specific tests**, install that environment's dependencies:
+
+```bash
+# Example: Install coding_env with dev dependencies (includes smolagents + pytest)
+uv pip install -e "envs/coding_env[dev]"
+
+# Then run coding_env tests
+PYTHONPATH=src:envs uv run pytest tests/envs/test_python_codeact_rewards.py -v
+```
+
+Tests will be automatically skipped if their required dependencies aren't installed.
+
 ## Requirements
 
-- Python 3.11+
+- Python 3.10+
 - Docker Desktop or Docker Engine
 - FastAPI >= 0.104.0
 - Uvicorn >= 0.24.0
 - Requests >= 2.25.0
-- smolagents (for coding environment)
+- Environment-specific dependencies (e.g., smolagents for coding_env)
 
 ## Supported RL Tools
 The goal of this project is to support a broad set of open and closed tools to help standardize the agentic RL community. If you have a project that supports OpenEnv environments, please put up a PR to add your tool name along with a link to your documentation.
@@ -254,7 +313,7 @@ The goal of this project is to support a broad set of open and closed tools to h
 See GRPO BlackJack training example: [`examples/grpo_blackjack/`](examples/grpo_blackjack/)
 
 ### TRL
-See the [TRL example](https://huggingface.co/docs/trl/main/en/openenv) on how to integrate OpenEnv environments with GRPO training.
+See the [TRL example](https://huggingface.co/docs/trl/openenv) on how to integrate OpenEnv environments with GRPO training.
 
 ### Unsloth
 See the 2048 game example based on gpt-oss: [Colab notebook](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/OpenEnv_gpt_oss_(20B)_Reinforcement_Learning_2048_Game.ipynb)
@@ -290,7 +349,7 @@ See: [`envs/coding_env/README.md`](envs/coding_env/README.md)
 ## Community Support & Acknowledgments
 This is an open and community-centric project. If you would like to add your name here, please put up a pull request and tag @jspisak for review. Ty!!
 
-Supporters include: Meta-PyTorch, Hugging Face, [Patronus AI](https://patronus.ai), [Surge AI](https://surgehq.ai), [LastMile AI](https://www.lastmileai.dev), Unsloth AI, Reflection AI, vLLM, SkyRL (UC-Berkeley), LightningAI, Axolotl AI, Stanford Scaling Intelligence Lab, Mithril, [OpenMined](https://openmined.org/), [Fleet AI](https://fleetai.com), [Halluminate](https://halluminate.ai/), [Turing](https://www.turing.com/) ..
+Supporters include: Meta-PyTorch, Hugging Face, [Scaler AI Labs](https://scalerailabs.com), [Patronus AI](https://patronus.ai), [Surge AI](https://surgehq.ai), [LastMile AI](https://www.lastmileai.dev), Unsloth AI, Reflection AI, vLLM, SkyRL (UC-Berkeley), LightningAI, Axolotl AI, Stanford Scaling Intelligence Lab, Mithril, [OpenMined](https://openmined.org/), [Fleet AI](https://fleetai.com), [Halluminate](https://halluminate.ai/), [Turing](https://www.turing.com/), [Scale AI](https://scale.com/) ..
 
 And we'd also like to acknowledge the team at Farama Foundation as the OpenEnv API was heavily inspired by the work you all have done on Gymnasium. Cheers!
 

{openenv-0.2.0 → openenv-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "openenv"
-version = "0.2.0"
+version = "0.2.1"
 description = "A unified framework for reinforcement learning environments"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -25,6 +25,8 @@ dependencies = [
     "tomli>=2.3.0",
     "tomli-w>=1.2.0",
     "websockets>=15.0.1",
+    # MCP support
+    "fastmcp>=2.0.0",
 ]
 
 [project.optional-dependencies]
@@ -78,3 +80,10 @@ exclude_lines = [
     "if __name__ == .__main__.:",
     "if TYPE_CHECKING:",
 ]
+
+[tool.pytest.ini_options]
+markers = [
+    "docker: Tests that require Docker to be running",
+    "network: Tests that require network access (HuggingFace, etc.)",
+    "integration: Integration tests with external resources",
+]

{openenv-0.2.0 → openenv-0.2.1}/src/openenv/__init__.py

@@ -4,7 +4,10 @@ Unified OpenEnv package bundling the CLI and core runtime.
 
 from importlib import metadata
 
-__all__ = ["core", "cli"]
+from .auto import AutoAction, AutoEnv
+from .core import GenericEnvClient, GenericAction
+
+__all__ = ["core", "cli", "AutoEnv", "AutoAction", "GenericEnvClient", "GenericAction"]
 
 try:
     __version__ = metadata.version("openenv")  # type: ignore[arg-type]

openenv-0.2.1/src/openenv/auto/__init__.py

@@ -0,0 +1,39 @@
+# 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.
+
+"""
+OpenEnv Auto Module
+===================
+
+Provides HuggingFace-style auto-discovery API for OpenEnv environments.
+
+This module enables automatic environment and action class loading without
+manual imports:
+
+    >>> from openenv import AutoEnv, AutoAction
+    >>>
+    >>> # Load environment from installed package or HuggingFace Hub
+    >>> env = AutoEnv.from_name("coding-env")
+    >>>
+    >>> # Get action class
+    >>> CodeAction = AutoAction.from_name("coding")
+    >>> action = CodeAction(code="print('Hello!')")
+
+Classes:
+    AutoEnv: Automatic environment client selection and instantiation
+    AutoAction: Automatic action class selection
+
+The auto-discovery system works by:
+1. Discovering installed openenv-* packages via importlib.metadata
+2. Loading environment manifests (openenv.yaml) from package resources
+3. Supporting HuggingFace Hub repositories for remote environments
+4. Caching discovery results for performance
+"""
+
+from .auto_action import AutoAction
+from .auto_env import AutoEnv
+
+__all__ = ["AutoEnv", "AutoAction"]