/envs/{env_name}_env")
+ console.print(f" # 2. Build from repo root: docker build -t {env_name}_env:latest -f envs/{env_name}_env/server/Dockerfile .")
console.print(f" # 3. Run your image: docker run -p 8000:8000 {env_name}_env:latest")
except Exception as e:
diff --git a/src/openenv_cli/commands/push.py b/src/openenv/cli/commands/push.py
similarity index 100%
rename from src/openenv_cli/commands/push.py
rename to src/openenv/cli/commands/push.py
diff --git a/src/openenv_cli/commands/serve.py b/src/openenv/cli/commands/serve.py
similarity index 100%
rename from src/openenv_cli/commands/serve.py
rename to src/openenv/cli/commands/serve.py
diff --git a/src/openenv_cli/commands/validate.py b/src/openenv/cli/commands/validate.py
similarity index 94%
rename from src/openenv_cli/commands/validate.py
rename to src/openenv/cli/commands/validate.py
index 96d64e58..1388f766 100644
--- a/src/openenv_cli/commands/validate.py
+++ b/src/openenv/cli/commands/validate.py
@@ -1,108 +1,108 @@
-# 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 validate command.
-
-This module provides the 'openenv validate' command to check if environments
-are properly configured for multi-mode deployment.
-"""
-
-from pathlib import Path
-
-import typer
-
-from openenv_cli._validation import (
- format_validation_report,
- get_deployment_modes,
- validate_multi_mode_deployment,
-)
-
-
-def validate(
- env_path: str | None = typer.Argument(
- None, help="Path to the environment directory (default: current directory)"
- ),
- verbose: bool = typer.Option(
- False, "--verbose", "-v", help="Show detailed information"
- ),
-) -> None:
- """
- Validate an environment for standardized structure and deployment readiness.
-
- This command checks if an environment is properly configured with:
- - Required files (pyproject.toml, openenv.yaml, server/app.py, etc.)
- - Docker deployment support
- - uv run server capability
- - python -m module execution
-
- Examples:
- # Validate current directory (recommended)
- $ cd my_env
- $ openenv validate
-
- # Validate with detailed output
- $ openenv validate --verbose
-
- # Validate specific environment
- $ openenv validate src/envs/echo_env
- """
- # Determine environment path (default to current directory)
- if env_path is None:
- env_path_obj = Path.cwd()
- else:
- env_path_obj = Path(env_path)
-
- if not env_path_obj.exists():
- typer.echo(f"Error: Path does not exist: {env_path_obj}", err=True)
- raise typer.Exit(1)
-
- if not env_path_obj.is_dir():
- typer.echo(f"Error: Path is not a directory: {env_path_obj}", err=True)
- raise typer.Exit(1)
-
- # Check for openenv.yaml to confirm this is an environment directory
- openenv_yaml = env_path_obj / "openenv.yaml"
- if not openenv_yaml.exists():
- typer.echo(
- f"Error: Not an OpenEnv environment directory (missing openenv.yaml): {env_path_obj}",
- err=True,
- )
- typer.echo(
- "Hint: Run this command from the environment root directory or specify the path",
- err=True,
- )
- raise typer.Exit(1)
-
- env_name = env_path_obj.name
- if env_name.endswith("_env"):
- base_name = env_name[:-4]
- else:
- base_name = env_name
-
- # Run validation
- is_valid, issues = validate_multi_mode_deployment(env_path_obj)
-
- # Show validation report
- report = format_validation_report(base_name, is_valid, issues)
- typer.echo(report)
-
- # Show deployment modes if verbose
- if verbose:
- typer.echo("\nSupported deployment modes:")
- modes = get_deployment_modes(env_path_obj)
- for mode, supported in modes.items():
- status = "[YES]" if supported else "[NO]"
- typer.echo(f" {status} {mode}")
-
- if is_valid:
- typer.echo("\nUsage examples:")
- typer.echo(f" cd {env_path_obj.name} && uv run server")
- typer.echo(f" cd {env_path_obj.name} && openenv build")
- typer.echo(f" cd {env_path_obj.name} && openenv push")
-
- if not is_valid:
- raise typer.Exit(1)
+# 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 validate command.
+
+This module provides the 'openenv validate' command to check if environments
+are properly configured for multi-mode deployment.
+"""
+
+from pathlib import Path
+
+import typer
+
+from openenv.cli._validation import (
+ format_validation_report,
+ get_deployment_modes,
+ validate_multi_mode_deployment,
+)
+
+
+def validate(
+ env_path: str | None = typer.Argument(
+ None, help="Path to the environment directory (default: current directory)"
+ ),
+ verbose: bool = typer.Option(
+ False, "--verbose", "-v", help="Show detailed information"
+ ),
+) -> None:
+ """
+ Validate an environment for standardized structure and deployment readiness.
+
+ This command checks if an environment is properly configured with:
+ - Required files (pyproject.toml, openenv.yaml, server/app.py, etc.)
+ - Docker deployment support
+ - uv run server capability
+ - python -m module execution
+
+ Examples:
+ # Validate current directory (recommended)
+ $ cd my_env
+ $ openenv validate
+
+ # Validate with detailed output
+ $ openenv validate --verbose
+
+ # Validate specific environment
+ $ openenv validate envs/echo_env
+ """
+ # Determine environment path (default to current directory)
+ if env_path is None:
+ env_path_obj = Path.cwd()
+ else:
+ env_path_obj = Path(env_path)
+
+ if not env_path_obj.exists():
+ typer.echo(f"Error: Path does not exist: {env_path_obj}", err=True)
+ raise typer.Exit(1)
+
+ if not env_path_obj.is_dir():
+ typer.echo(f"Error: Path is not a directory: {env_path_obj}", err=True)
+ raise typer.Exit(1)
+
+ # Check for openenv.yaml to confirm this is an environment directory
+ openenv_yaml = env_path_obj / "openenv.yaml"
+ if not openenv_yaml.exists():
+ typer.echo(
+ f"Error: Not an OpenEnv environment directory (missing openenv.yaml): {env_path_obj}",
+ err=True,
+ )
+ typer.echo(
+ "Hint: Run this command from the environment root directory or specify the path",
+ err=True,
+ )
+ raise typer.Exit(1)
+
+ env_name = env_path_obj.name
+ if env_name.endswith("_env"):
+ base_name = env_name[:-4]
+ else:
+ base_name = env_name
+
+ # Run validation
+ is_valid, issues = validate_multi_mode_deployment(env_path_obj)
+
+ # Show validation report
+ report = format_validation_report(base_name, is_valid, issues)
+ typer.echo(report)
+
+ # Show deployment modes if verbose
+ if verbose:
+ typer.echo("\nSupported deployment modes:")
+ modes = get_deployment_modes(env_path_obj)
+ for mode, supported in modes.items():
+ status = "[YES]" if supported else "[NO]"
+ typer.echo(f" {status} {mode}")
+
+ if is_valid:
+ typer.echo("\nUsage examples:")
+ typer.echo(f" cd {env_path_obj.name} && uv run server")
+ typer.echo(f" cd {env_path_obj.name} && openenv build")
+ typer.echo(f" cd {env_path_obj.name} && openenv push")
+
+ if not is_valid:
+ raise typer.Exit(1)
diff --git a/src/openenv_cli/templates/__init__.py b/src/openenv/cli/templates/__init__.py
similarity index 100%
rename from src/openenv_cli/templates/__init__.py
rename to src/openenv/cli/templates/__init__.py
diff --git a/src/openenv_cli/templates/openenv_env/.dockerignore b/src/openenv/cli/templates/openenv_env/.dockerignore
similarity index 100%
rename from src/openenv_cli/templates/openenv_env/.dockerignore
rename to src/openenv/cli/templates/openenv_env/.dockerignore
diff --git a/src/openenv_cli/templates/openenv_env/README.md b/src/openenv/cli/templates/openenv_env/README.md
similarity index 100%
rename from src/openenv_cli/templates/openenv_env/README.md
rename to src/openenv/cli/templates/openenv_env/README.md
diff --git a/src/openenv_cli/templates/openenv_env/__init__.py b/src/openenv/cli/templates/openenv_env/__init__.py
similarity index 100%
rename from src/openenv_cli/templates/openenv_env/__init__.py
rename to src/openenv/cli/templates/openenv_env/__init__.py
diff --git a/src/openenv_cli/templates/openenv_env/client.py b/src/openenv/cli/templates/openenv_env/client.py
similarity index 95%
rename from src/openenv_cli/templates/openenv_env/client.py
rename to src/openenv/cli/templates/openenv_env/client.py
index 34d35267..703b28a8 100644
--- a/src/openenv_cli/templates/openenv_env/client.py
+++ b/src/openenv/cli/templates/openenv_env/client.py
@@ -13,9 +13,9 @@
from typing import Any, Dict
-from openenv_core.client_types import StepResult
-from openenv_core.env_server.types import State
-from openenv_core.http_env_client import HTTPEnvClient
+from openenv.core.client_types import StepResult
+from openenv.core.env_server.types import State
+from openenv.core.http_env_client import HTTPEnvClient
from .models import __ENV_CLASS_NAME__Action, __ENV_CLASS_NAME__Observation
diff --git a/src/openenv_cli/templates/openenv_env/models.py b/src/openenv/cli/templates/openenv_env/models.py
similarity index 92%
rename from src/openenv_cli/templates/openenv_env/models.py
rename to src/openenv/cli/templates/openenv_env/models.py
index c2e40616..64010449 100644
--- a/src/openenv_cli/templates/openenv_env/models.py
+++ b/src/openenv/cli/templates/openenv_env/models.py
@@ -12,7 +12,7 @@
from dataclasses import dataclass
-from openenv_core.env_server.types import Action, Observation
+from openenv.core.env_server.types import Action, Observation
@dataclass(kw_only=True)
diff --git a/src/openenv_cli/templates/openenv_env/openenv.yaml b/src/openenv/cli/templates/openenv_env/openenv.yaml
similarity index 100%
rename from src/openenv_cli/templates/openenv_env/openenv.yaml
rename to src/openenv/cli/templates/openenv_env/openenv.yaml
diff --git a/src/openenv_cli/templates/openenv_env/pyproject.toml b/src/openenv/cli/templates/openenv_env/pyproject.toml
similarity index 77%
rename from src/openenv_cli/templates/openenv_env/pyproject.toml
rename to src/openenv/cli/templates/openenv_env/pyproject.toml
index 331f4851..55b90113 100644
--- a/src/openenv_cli/templates/openenv_env/pyproject.toml
+++ b/src/openenv/cli/templates/openenv_env/pyproject.toml
@@ -1,48 +1,43 @@
-# 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-__ENV_NAME__"
-version = "0.1.0"
-description = "__ENV_TITLE_NAME__ environment for OpenEnv"
-requires-python = ">=3.10"
-dependencies = [
- # Core OpenEnv dependencies (required for server functionality)
- # "openenv-core @ git+https://github.com/meta-pytorch/OpenEnv.git@main#subdirectory=src/core",
- "openenv-core>=0.1.0",
- "fastapi>=0.115.0",
- "pydantic>=2.0.0",
- "uvicorn>=0.24.0",
- "requests>=2.31.0",
- # Environment-specific dependencies
- # Add all dependencies needed for your environment here
- # Examples:
- # "numpy>=1.19.0",
- # "torch>=2.0.0",
- # "gymnasium>=0.29.0",
- # "openspiel>=1.0.0",
- # "smolagents>=1.22.0,<2",
-]
-
-[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 __ENV_NAME__.server.app
-server = "__ENV_NAME__.server.app:main"
-
-[tool.setuptools]
-include-package-data = true
-packages = ["__ENV_NAME__", "__ENV_NAME__.server"]
+# 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-__ENV_NAME__"
+version = "0.1.0"
+description = "__ENV_TITLE_NAME__ environment for OpenEnv"
+requires-python = ">=3.10"
+dependencies = [
+ # Core OpenEnv runtime (provides FastAPI server + HTTP client types)
+ "openenv[core]>=0.2.0",
+ # Environment-specific dependencies
+ # Add all dependencies needed for your environment here
+ # Examples:
+ # "numpy>=1.19.0",
+ # "torch>=2.0.0",
+ # "gymnasium>=0.29.0",
+ # "openspiel>=1.0.0",
+ # "smolagents>=1.22.0,<2",
+]
+
+[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 __ENV_NAME__.server.app
+server = "__ENV_NAME__.server.app:main"
+
+[tool.setuptools]
+include-package-data = true
+packages = ["__ENV_NAME__", "__ENV_NAME__.server"]
package-dir = { "__ENV_NAME__" = ".", "__ENV_NAME__.server" = "server" }
\ No newline at end of file
diff --git a/src/openenv_cli/templates/openenv_env/server/Dockerfile b/src/openenv/cli/templates/openenv_env/server/Dockerfile
similarity index 89%
rename from src/openenv_cli/templates/openenv_env/server/Dockerfile
rename to src/openenv/cli/templates/openenv_env/server/Dockerfile
index 0d53bc24..3d10ac76 100644
--- a/src/openenv_cli/templates/openenv_env/server/Dockerfile
+++ b/src/openenv/cli/templates/openenv_env/server/Dockerfile
@@ -6,8 +6,8 @@
# 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)
+# - In-repo environments (with local OpenEnv sources)
+# - Standalone environments (with openenv from PyPI/Git)
# The build script (openenv build) handles context detection and sets appropriate build args.
ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
@@ -27,8 +27,8 @@ ARG ENV_NAME=__ENV_NAME__
# 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
+# For in-repo builds, openenv is already vendored in the build context
+# For standalone builds, openenv will be installed via pyproject.toml
WORKDIR /app/env
# Ensure uv is available (for local builds where base image lacks it)
diff --git a/src/openenv_cli/templates/openenv_env/server/__ENV_NAME___environment.py b/src/openenv/cli/templates/openenv_env/server/__ENV_NAME___environment.py
similarity index 96%
rename from src/openenv_cli/templates/openenv_env/server/__ENV_NAME___environment.py
rename to src/openenv/cli/templates/openenv_env/server/__ENV_NAME___environment.py
index 63df6c01..e2a9ce0b 100644
--- a/src/openenv_cli/templates/openenv_env/server/__ENV_NAME___environment.py
+++ b/src/openenv/cli/templates/openenv_env/server/__ENV_NAME___environment.py
@@ -13,8 +13,8 @@
from uuid import uuid4
-from openenv_core.env_server.interfaces import Environment
-from openenv_core.env_server.types import State
+from openenv.core.env_server.interfaces import Environment
+from openenv.core.env_server.types import State
from models import __ENV_CLASS_NAME__Action, __ENV_CLASS_NAME__Observation
diff --git a/src/openenv_cli/templates/openenv_env/server/__init__.py b/src/openenv/cli/templates/openenv_env/server/__init__.py
similarity index 100%
rename from src/openenv_cli/templates/openenv_env/server/__init__.py
rename to src/openenv/cli/templates/openenv_env/server/__init__.py
diff --git a/src/openenv_cli/templates/openenv_env/server/app.py b/src/openenv/cli/templates/openenv_env/server/app.py
similarity index 86%
rename from src/openenv_cli/templates/openenv_env/server/app.py
rename to src/openenv/cli/templates/openenv_env/server/app.py
index 79baeb87..db216fb0 100644
--- a/src/openenv_cli/templates/openenv_env/server/app.py
+++ b/src/openenv/cli/templates/openenv_env/server/app.py
@@ -22,12 +22,14 @@
"""
try:
- from openenv_core.env_server.http_server import create_app
+ from openenv.core.env_server.http_server import create_app
except Exception as e: # pragma: no cover
- raise ImportError("openenv_core is required for the web interface. Install dependencies with '\n uv sync\n'") from e
+ raise ImportError(
+ "openenv is required for the web interface. Install dependencies with '\n uv sync\n'"
+ ) from e
+from __ENV_NAME__.models import __ENV_CLASS_NAME__Action, __ENV_CLASS_NAME__Observation
from .__ENV_NAME___environment import __ENV_CLASS_NAME__Environment
-from models import __ENV_CLASS_NAME__Action, __ENV_CLASS_NAME__Observation
# Create the environment instance
env = __ENV_CLASS_NAME__Environment()
diff --git a/src/openenv/cli/templates/openenv_env/server/requirements.txt b/src/openenv/cli/templates/openenv_env/server/requirements.txt
new file mode 100644
index 00000000..65b1c22b
--- /dev/null
+++ b/src/openenv/cli/templates/openenv_env/server/requirements.txt
@@ -0,0 +1,6 @@
+openenv[core]>=0.2.0
+fastapi>=0.115.0
+uvicorn>=0.24.0
+
+
+
diff --git a/src/core/README.md b/src/openenv/core/README.md
similarity index 93%
rename from src/core/README.md
rename to src/openenv/core/README.md
index f71ea1c1..2251e10a 100644
--- a/src/core/README.md
+++ b/src/openenv/core/README.md
@@ -6,7 +6,7 @@ In addition to making it easier for researchers and RL framework writers, we als
## Overview
-`openenv-core` provides the foundational building blocks for creating and interacting with containerized environments over HTTP. It enables you to build agent environments that can be deployed as Docker containers and accessed via a simple HTTP API.
+`openenv.core` provides the foundational building blocks for creating and interacting with containerized environments over HTTP. It enables you to build agent environments that can be deployed as Docker containers and accessed via a simple HTTP API.
> ⚠️ **Early Development Warning** OpenEnv is currently in an experimental
> stage. You should expect bugs, incomplete features, and APIs that may change
@@ -31,12 +31,12 @@ Core components for OpenEnv - a framework for building HTTP-based agentic enviro
## Installation
```bash
-pip install openenv-core
+pip install "openenv[core]"
```
For development:
```bash
-pip install openenv-core[dev]
+pip install "openenv[core]"
```
## Quick Start
@@ -44,7 +44,7 @@ pip install openenv-core[dev]
### Creating an Environment Client
```python
-from openenv_core import HTTPEnvClient, StepResult
+from openenv.core import HTTPEnvClient, StepResult
from dataclasses import dataclass
@dataclass
@@ -80,7 +80,7 @@ env.close()
### Creating an Environment Server
```python
-from openenv_core.env_server import Environment, HTTPEnvServer, create_app
+from openenv.core.env_server import Environment, HTTPEnvServer, create_app
from dataclasses import dataclass
@dataclass
@@ -118,7 +118,7 @@ OpenEnv Core supports multiple container providers:
### Local Docker Provider
```python
-from openenv_core.containers.runtime import LocalDockerProvider
+from openenv.core.containers.runtime import LocalDockerProvider
provider = LocalDockerProvider()
base_url = provider.start_container("my-env:latest")
@@ -130,7 +130,7 @@ provider.stop_container()
### Kubernetes Provider (Coming Soon)
```python
-from openenv_core.containers.runtime import KubernetesProvider
+from openenv.core.containers.runtime import KubernetesProvider
provider = KubernetesProvider(namespace="envs")
base_url = provider.start_container("my-env:latest")
diff --git a/src/core/__init__.py b/src/openenv/core/__init__.py
similarity index 100%
rename from src/core/__init__.py
rename to src/openenv/core/__init__.py
diff --git a/src/core/client_types.py b/src/openenv/core/client_types.py
similarity index 100%
rename from src/core/client_types.py
rename to src/openenv/core/client_types.py
diff --git a/src/core/containers/__init__.py b/src/openenv/core/containers/__init__.py
similarity index 100%
rename from src/core/containers/__init__.py
rename to src/openenv/core/containers/__init__.py
diff --git a/src/core/containers/images/Dockerfile b/src/openenv/core/containers/images/Dockerfile
similarity index 100%
rename from src/core/containers/images/Dockerfile
rename to src/openenv/core/containers/images/Dockerfile
diff --git a/src/core/containers/images/README.md b/src/openenv/core/containers/images/README.md
similarity index 92%
rename from src/core/containers/images/README.md
rename to src/openenv/core/containers/images/README.md
index bc286446..2a91b330 100644
--- a/src/core/containers/images/README.md
+++ b/src/openenv/core/containers/images/README.md
@@ -48,7 +48,7 @@ FROM openenv-base:latest
# Copy only environment-specific files
COPY src/core/ /app/src/core/
-COPY src/envs/my_env/ /app/src/envs/my_env/
+COPY envs/my_env/ /app/envs/my_env/
# Run the server
CMD ["uvicorn", "envs.my_env.server.app:app", "--host", "0.0.0.0", "--port", "8000"]
@@ -69,7 +69,7 @@ CMD ["uvicorn", "envs.my_env.server.app:app", "--host", "0.0.0.0", "--port", "80
docker build -t openenv-base:latest -f src/core/containers/images/Dockerfile .
# Step 2: Build echo environment (uses base)
-docker build -t echo-env:latest -f src/envs/echo_env/server/Dockerfile .
+docker build -t echo-env:latest -f envs/echo_env/server/Dockerfile .
# Step 3: Run echo environment
docker run -p 8000:8000 echo-env:latest
@@ -88,5 +88,5 @@ When dependencies need updating:
docker build -t openenv-base:latest -f src/core/containers/images/Dockerfile .
# Rebuild environments (they automatically use new base)
-docker build -t echo-env:latest -f src/envs/echo_env/server/Dockerfile .
+docker build -t echo-env:latest -f envs/echo_env/server/Dockerfile .
```
diff --git a/src/core/containers/runtime/__init__.py b/src/openenv/core/containers/runtime/__init__.py
similarity index 100%
rename from src/core/containers/runtime/__init__.py
rename to src/openenv/core/containers/runtime/__init__.py
diff --git a/src/core/containers/runtime/providers.py b/src/openenv/core/containers/runtime/providers.py
similarity index 100%
rename from src/core/containers/runtime/providers.py
rename to src/openenv/core/containers/runtime/providers.py
diff --git a/src/core/containers/test_local_docker_provider.py b/src/openenv/core/containers/test_local_docker_provider.py
similarity index 99%
rename from src/core/containers/test_local_docker_provider.py
rename to src/openenv/core/containers/test_local_docker_provider.py
index e435ff6d..27169f2d 100644
--- a/src/core/containers/test_local_docker_provider.py
+++ b/src/openenv/core/containers/test_local_docker_provider.py
@@ -17,7 +17,7 @@
import requests
-from core.containers.runtime import LocalDockerProvider
+from openenv.core.containers.runtime import LocalDockerProvider
# TODO: Remove this test or make it a functional test sicne this will be tested in e2e test for echo env
def test_local_docker_provider():
diff --git a/src/core/env_server/__init__.py b/src/openenv/core/env_server/__init__.py
similarity index 66%
rename from src/core/env_server/__init__.py
rename to src/openenv/core/env_server/__init__.py
index 79e66535..4e1c2d7a 100644
--- a/src/core/env_server/__init__.py
+++ b/src/openenv/core/env_server/__init__.py
@@ -9,7 +9,13 @@
from .base_transforms import CompositeTransform, NullTransform
from .http_server import HTTPEnvServer, create_app, create_fastapi_app
from .interfaces import Environment, Message, ModelTokenizer, Transform
-from .types import Action, Observation, State
+from .route_config import GetEndpointConfig
+from .serialization import (
+ deserialize_action,
+ deserialize_action_with_preprocessing,
+ serialize_observation,
+)
+from .types import Action, Observation, State, SchemaResponse, HealthResponse
from .web_interface import create_web_interface_app, WebInterfaceManager
__all__ = [
@@ -22,6 +28,8 @@
"Action",
"Observation",
"State",
+ "SchemaResponse",
+ "HealthResponse",
# Base transforms
"CompositeTransform",
"NullTransform",
@@ -32,4 +40,10 @@
# Web Interface
"create_web_interface_app",
"WebInterfaceManager",
+ # Serialization utilities
+ "deserialize_action",
+ "deserialize_action_with_preprocessing",
+ "serialize_observation",
+ # Route configuration
+ "GetEndpointConfig",
]
diff --git a/src/core/env_server/base_transforms.py b/src/openenv/core/env_server/base_transforms.py
similarity index 100%
rename from src/core/env_server/base_transforms.py
rename to src/openenv/core/env_server/base_transforms.py
diff --git a/src/openenv/core/env_server/http_server.py b/src/openenv/core/env_server/http_server.py
new file mode 100644
index 00000000..7fa7c0f3
--- /dev/null
+++ b/src/openenv/core/env_server/http_server.py
@@ -0,0 +1,457 @@
+# 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.
+
+"""
+HTTP server wrapper for Environment instances.
+
+This module provides utilities to wrap any Environment subclass and expose it
+over HTTP endpoints that HTTPEnvClient can consume.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import os
+from concurrent.futures import ThreadPoolExecutor
+from typing import Optional, Type
+
+from fastapi import Body, FastAPI, HTTPException, status
+from pydantic import ValidationError
+
+from .interfaces import Environment
+from .route_config import (
+ GetEndpointConfig,
+ register_get_endpoints,
+)
+from .serialization import deserialize_action, serialize_observation
+from .types import (
+ Action,
+ Observation,
+ ResetRequest,
+ ResetResponse,
+ State,
+ StepRequest,
+ StepResponse,
+ EnvironmentMetadata,
+ SchemaResponse,
+ HealthResponse,
+)
+
+
+class HTTPEnvServer:
+ """
+ HTTP server wrapper for Environment instances.
+
+ This class wraps an Environment and exposes its reset(), step(), and state
+ methods as HTTP endpoints compatible with HTTPEnvClient.
+
+ The server expects:
+ - Action deserialization: Converts JSON dict to Action subclass
+ - Observation serialization: Converts Observation subclass to JSON dict
+
+ Example:
+ >>> from core.env_server import HTTPEnvServer
+ >>> from envs.coding_env.server import CodeExecutionEnvironment
+ >>>
+ >>> env = CodeExecutionEnvironment()
+ >>> server = HTTPEnvServer(env)
+ >>>
+ >>> # Register routes with FastAPI
+ >>> from fastapi import FastAPI
+ >>> app = FastAPI()
+ >>> server.register_routes(app)
+ """
+
+ def __init__(
+ self,
+ env: Environment,
+ action_cls: Type[Action],
+ observation_cls: Type[Observation],
+ ):
+ """
+ Initialize HTTP server wrapper.
+
+ Args:
+ env: The Environment instance to wrap
+ action_cls: The Action subclass this environment expects
+ observation_cls: The Observation subclass this environment returns
+ """
+ self.env = env
+ self.action_cls = action_cls
+ self.observation_cls = observation_cls
+ # Create thread pool for running sync code in async context
+ # This is needed for environments using sync libraries (e.g., Playwright sync API)
+ self._executor = ThreadPoolExecutor(max_workers=1)
+
+ async def _run_sync_in_thread_pool(self, func, *args, **kwargs):
+ """Run a synchronous function in the thread pool executor."""
+ loop = asyncio.get_event_loop()
+ return await loop.run_in_executor(self._executor, lambda: func(*args, **kwargs))
+
+ def _get_valid_kwargs(self, sig, kwargs, skip_params=None):
+ """Filter kwargs to only include parameters accepted by the function signature."""
+ if skip_params is None:
+ skip_params = set()
+
+ valid_kwargs = {}
+
+ has_kwargs = any(
+ p.kind == inspect.Parameter.VAR_KEYWORD for p in sig.parameters.values()
+ )
+
+ for k, v in kwargs.items():
+ if k in sig.parameters or has_kwargs:
+ if k not in skip_params:
+ valid_kwargs[k] = v
+
+ return valid_kwargs
+
+ def register_routes(self, app: FastAPI) -> None:
+ """
+ Register HTTP routes on a FastAPI application.
+
+ Args:
+ app: FastAPI application instance
+ """
+
+ # Helper function to handle reset endpoint
+ async def reset_handler(
+ request: ResetRequest = Body(default_factory=ResetRequest),
+ ) -> ResetResponse:
+ """Reset endpoint - returns initial observation."""
+ # Handle optional parameters
+ # Start with all fields from the request, including extra ones
+ kwargs = request.model_dump(exclude_unset=True)
+
+ # Pass arguments only if environment accepts them
+ sig = inspect.signature(self.env.reset)
+ valid_kwargs = self._get_valid_kwargs(sig, kwargs)
+
+ # Run synchronous reset in thread pool to avoid blocking event loop
+ observation = await self._run_sync_in_thread_pool(
+ self.env.reset, **valid_kwargs
+ )
+ return ResetResponse(**serialize_observation(observation))
+
+ # Helper function to handle step endpoint
+ async def step_handler(request: StepRequest) -> StepResponse:
+ """Step endpoint - executes action and returns observation."""
+ action_data = request.action
+
+ # Deserialize action with Pydantic validation
+ try:
+ action = deserialize_action(action_data, self.action_cls)
+ except ValidationError as e:
+ # Return HTTP 422 with detailed validation errors
+ raise HTTPException(
+ status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=e.errors()
+ )
+
+ # Handle optional parameters
+ # Start with all fields from the request, including extra ones, but exclude 'action'
+ kwargs = request.model_dump(exclude_unset=True, exclude={"action"})
+
+ # Pass arguments only if environment accepts them
+ sig = inspect.signature(self.env.step)
+ valid_kwargs = self._get_valid_kwargs(sig, kwargs, skip_params={"action"})
+
+ # Run synchronous step in thread pool to avoid blocking event loop
+ observation = await self._run_sync_in_thread_pool(
+ self.env.step, action, **valid_kwargs
+ )
+
+ # Return serialized observation
+ return StepResponse(**serialize_observation(observation))
+
+ # Register routes using the helpers
+ @app.post(
+ "/reset",
+ response_model=ResetResponse,
+ tags=["Environment Control"],
+ summary="Reset the environment",
+ description="""
+Reset the environment to its initial state and return the first observation.
+
+You can optionally provide a seed for reproducibility and an episode_id for tracking.
+ """,
+ responses={
+ 200: {
+ "description": "Environment reset successfully",
+ "content": {
+ "application/json": {
+ "example": {
+ "observation": {"status": "ready", "data": {}},
+ "reward": None,
+ "done": False,
+ }
+ }
+ },
+ }
+ },
+ )
+ async def reset(
+ request: ResetRequest = Body(default_factory=ResetRequest),
+ ) -> ResetResponse:
+ return await reset_handler(request)
+
+ @app.post(
+ "/step",
+ response_model=StepResponse,
+ tags=["Environment Control"],
+ summary="Execute an action in the environment",
+ description="""
+Execute an action in the environment and receive the resulting observation.
+
+The action must conform to the environment's action schema, which can be
+retrieved from the `/schema` endpoint. If the action is invalid,
+the endpoint will return HTTP 422 with detailed validation errors.
+
+The response includes:
+- **observation**: The environment's response to the action
+- **reward**: Optional reward signal (float or None)
+- **done**: Boolean indicating if the episode has terminated
+ """,
+ responses={
+ 200: {
+ "description": "Action executed successfully",
+ "content": {
+ "application/json": {
+ "example": {
+ "observation": {"status": "success", "data": {}},
+ "reward": 1.0,
+ "done": False,
+ }
+ }
+ },
+ },
+ 422: {
+ "description": "Validation error - invalid action format or values",
+ "content": {
+ "application/json": {
+ "example": {
+ "detail": [
+ {
+ "type": "string_too_short",
+ "loc": ["body", "action", "message"],
+ "msg": "String should have at least 1 character",
+ "input": "",
+ }
+ ]
+ }
+ }
+ },
+ },
+ 500: {"description": "Internal server error during action execution"},
+ },
+ )
+ async def step(request: StepRequest) -> StepResponse:
+ return await step_handler(request)
+
+ # Configure and register GET endpoints declaratively
+ get_endpoints = [
+ GetEndpointConfig(
+ path="/state",
+ handler=lambda: self.env.state,
+ response_model=State,
+ tag="State Management",
+ summary="Get current environment state",
+ description="""
+Retrieve the current internal state of the environment.
+
+This endpoint allows inspection of the environment state without modifying it.
+The structure of the state object is defined by the environment's State model.
+ """,
+ ),
+ GetEndpointConfig(
+ path="/metadata",
+ handler=self.env.get_metadata,
+ response_model=EnvironmentMetadata,
+ tag="Environment Info",
+ summary="Get environment metadata",
+ description="""
+Get metadata about this environment.
+
+Returns information about the environment including name, description,
+version, author, and documentation links.
+ """,
+ ),
+ GetEndpointConfig(
+ path="/health",
+ handler=lambda: HealthResponse(status="healthy"),
+ response_model=HealthResponse,
+ tag="Health",
+ summary="Health check",
+ description="Check if the environment server is running and healthy.",
+ ),
+ ]
+ register_get_endpoints(app, get_endpoints)
+
+ # Register combined schema endpoint
+ @app.get(
+ "/schema",
+ response_model=SchemaResponse,
+ tags=["Schema"],
+ summary="Get all JSON schemas",
+ description="""
+Get JSON schemas for actions, observations, and state in a single response.
+
+Returns a combined schema object containing:
+- **action**: JSON schema for actions accepted by this environment
+- **observation**: JSON schema for observations returned by this environment
+- **state**: JSON schema for environment state objects
+
+This is more efficient than calling individual schema endpoints and provides
+all schema information needed to interact with the environment.
+ """,
+ responses={
+ 200: {
+ "description": "Combined schemas retrieved successfully",
+ "content": {
+ "application/json": {
+ "example": {
+ "action": {
+ "type": "object",
+ "properties": {"message": {"type": "string"}},
+ },
+ "observation": {
+ "type": "object",
+ "properties": {"response": {"type": "string"}},
+ },
+ "state": {
+ "type": "object",
+ "properties": {"step_count": {"type": "integer"}},
+ },
+ }
+ }
+ },
+ }
+ },
+ )
+ async def get_schemas() -> SchemaResponse:
+ """Return all schemas in one response."""
+ return SchemaResponse(
+ action=self.action_cls.model_json_schema(),
+ observation=self.observation_cls.model_json_schema(),
+ state=State.model_json_schema(),
+ )
+
+
+def create_app(
+ env: Environment,
+ action_cls: Type[Action],
+ observation_cls: Type[Observation],
+ env_name: Optional[str] = None,
+) -> FastAPI:
+ """
+ Create a FastAPI application with or without web interface.
+
+ This function creates a FastAPI app with the web interface enabled by default,
+ including README integration for better user experience.
+
+ Args:
+ env: The Environment instance to serve
+ action_cls: The Action subclass this environment expects
+ observation_cls: The Observation subclass this environment returns
+ env_name: Optional environment name for README loading
+
+ Returns:
+ FastAPI application instance with or without web interface and README integration
+ """
+ # Check if web interface should be enabled
+ # This can be controlled via environment variable or build argument
+ enable_web = os.getenv("ENABLE_WEB_INTERFACE", "false").lower() in (
+ "true",
+ "1",
+ "yes",
+ )
+
+ if enable_web:
+ # Import web interface only when needed
+ from .web_interface import create_web_interface_app
+
+ return create_web_interface_app(env, action_cls, observation_cls, env_name)
+ else:
+ # Use standard FastAPI app without web interface
+ return create_fastapi_app(env, action_cls, observation_cls)
+
+
+def create_fastapi_app(
+ env: Environment,
+ action_cls: Type[Action],
+ observation_cls: Type[Observation],
+) -> FastAPI:
+ """Create a FastAPI application with comprehensive documentation."""
+ try:
+ from fastapi import FastAPI
+ except ImportError:
+ raise ImportError(
+ "FastAPI is required. Install with: pip install fastapi uvicorn"
+ )
+
+ app = FastAPI(
+ title="OpenEnv Environment HTTP API",
+ version="1.0.0",
+ description="""
+# OpenEnv Environment HTTP API
+
+HTTP API for interacting with OpenEnv environments through a standardized interface.
+
+## Features
+
+* **Environment Reset**: Initialize or restart episodes
+* **Action Execution**: Send actions and receive observations
+* **State Inspection**: Query current environment state
+* **Schema Access**: Retrieve JSON schemas for actions and observations
+
+## Workflow
+
+1. Call `/reset` to start a new episode and get initial observation
+2. Call `/step` repeatedly with actions to interact with environment
+3. Episode ends when observation returns `done: true`
+4. Call `/state` anytime to inspect current environment state
+
+## Documentation
+
+* **Swagger UI**: Available at `/docs`
+* **ReDoc**: Available at `/redoc`
+* **OpenAPI Schema**: Available at `/openapi.json`
+ """,
+ openapi_tags=[
+ {
+ "name": "Environment Control",
+ "description": "Core operations for environment interaction (reset, step)",
+ },
+ {
+ "name": "State Management",
+ "description": "Operations for inspecting environment state",
+ },
+ {
+ "name": "Environment Info",
+ "description": "Information about the environment",
+ },
+ {
+ "name": "Schema",
+ "description": "JSON Schema endpoints for actions, observations, and state",
+ },
+ {"name": "Health", "description": "Service health and status checks"},
+ ],
+ docs_url="/docs",
+ redoc_url="/redoc",
+ openapi_url="/openapi.json",
+ contact={
+ "name": "OpenEnv Team",
+ "url": "https://github.com/meta-pytorch/OpenEnv",
+ },
+ license_info={
+ "name": "BSD-3-Clause",
+ "url": "https://github.com/meta-pytorch/OpenEnv/blob/main/LICENSE",
+ },
+ )
+
+ server = HTTPEnvServer(env, action_cls, observation_cls)
+ server.register_routes(app)
+ return app
diff --git a/src/core/env_server/interfaces.py b/src/openenv/core/env_server/interfaces.py
similarity index 74%
rename from src/core/env_server/interfaces.py
rename to src/openenv/core/env_server/interfaces.py
index caa2d76d..b438cd66 100644
--- a/src/core/env_server/interfaces.py
+++ b/src/openenv/core/env_server/interfaces.py
@@ -1,118 +1,144 @@
-# 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.
-
-from abc import ABC, abstractmethod
-from typing import Any, Protocol, TypedDict
-
-from .types import Action, Observation, State
-
-
-class Message(TypedDict):
- """A message in a conversation.
-
- Compatible with Huggingface chat template format.
- """
-
- role: str
- content: str
-
-
-class ModelTokenizer(Protocol):
- """Protocol for tokenizers that support chat templates.
-
- This protocol defines the interface that tokenizers must implement
- to work with chat-based environments. It's compatible with
- Huggingface transformers tokenizers.
- """
-
- def apply_chat_template(
- self,
- conversation: list[Message],
- tokenize: bool = True,
- return_tensors: str | None = None,
- **kwargs: Any,
- ) -> Any:
- """Apply a chat template to format and optionally tokenize a conversation.
-
- Args:
- conversation: List of message dictionaries with 'role' and 'content'
- tokenize: Whether to tokenize the output
- return_tensors: Format for returned tensors ('pt' for PyTorch)
- **kwargs: Additional arguments
-
- Returns:
- Formatted and optionally tokenized conversation
- """
- ...
-
- def decode(
- self, token_ids: Any, skip_special_tokens: bool = False, **kwargs: Any
- ) -> str:
- """Decode token IDs back to text.
-
- Args:
- token_ids: Token IDs to decode
- skip_special_tokens: Whether to skip special tokens in output
- **kwargs: Additional arguments
-
- Returns:
- Decoded text string
- """
- ...
-
-
-class Transform(ABC):
- """Transform observations to add rewards, metrics, or other modifications.
-
- Transforms follow the TorchRL pattern where they take an observation
- and return a (potentially modified) observation. This allows for
- flexible reward computation and observation augmentation.
- """
-
- @abstractmethod
- def __call__(self, observation: Observation) -> Observation:
- """Transform an observation.
-
- Args:
- observation: The input observation
-
- Returns:
- The transformed observation
- """
- pass
-
-
-class Environment(ABC):
- """Base class for all environment servers following Gym/Gymnasium API.
-
- Args:
- transform: Optional transform to apply to observations
- """
-
- def __init__(self, transform: Transform | None = None):
- self.transform = transform
-
- @abstractmethod
- def reset(self) -> Observation:
- """Reset the environment and return initial observation."""
- pass
-
- @abstractmethod
- def step(self, action: Action) -> Observation:
- """Take a step in the environment."""
- pass
-
- @property
- @abstractmethod
- def state(self) -> State:
- """Get the current environment state."""
- pass
-
- def _apply_transform(self, observation: Observation) -> Observation:
- """Apply transform if one is provided."""
- if self.transform is not None:
- return self.transform(observation)
- return observation
+# 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.
+
+from abc import ABC, abstractmethod
+from typing import Any, Optional, Protocol, TypedDict
+
+from .types import Action, Observation, State, EnvironmentMetadata
+
+
+class Message(TypedDict):
+ """A message in a conversation.
+
+ Compatible with Huggingface chat template format.
+ """
+
+ role: str
+ content: str
+
+
+class ModelTokenizer(Protocol):
+ """Protocol for tokenizers that support chat templates.
+
+ This protocol defines the interface that tokenizers must implement
+ to work with chat-based environments. It's compatible with
+ Huggingface transformers tokenizers.
+ """
+
+ def apply_chat_template(
+ self,
+ conversation: list[Message],
+ tokenize: bool = True,
+ return_tensors: str | None = None,
+ **kwargs: Any,
+ ) -> Any:
+ """Apply a chat template to format and optionally tokenize a conversation.
+
+ Args:
+ conversation: List of message dictionaries with 'role' and 'content'
+ tokenize: Whether to tokenize the output
+ return_tensors: Format for returned tensors ('pt' for PyTorch)
+ **kwargs: Additional arguments
+
+ Returns:
+ Formatted and optionally tokenized conversation
+ """
+ ...
+
+ def decode(
+ self, token_ids: Any, skip_special_tokens: bool = False, **kwargs: Any
+ ) -> str:
+ """Decode token IDs back to text.
+
+ Args:
+ token_ids: Token IDs to decode
+ skip_special_tokens: Whether to skip special tokens in output
+ **kwargs: Additional arguments
+
+ Returns:
+ Decoded text string
+ """
+ ...
+
+
+class Transform(ABC):
+ """Transform observations to add rewards, metrics, or other modifications.
+
+ Transforms follow the TorchRL pattern where they take an observation
+ and return a (potentially modified) observation. This allows for
+ flexible reward computation and observation augmentation.
+ """
+
+ @abstractmethod
+ def __call__(self, observation: Observation) -> Observation:
+ """Transform an observation.
+
+ Args:
+ observation: The input observation
+
+ Returns:
+ The transformed observation
+ """
+ pass
+
+
+class Environment(ABC):
+ """Base class for all environment servers following Gym/Gymnasium API.
+
+ Args:
+ transform: Optional transform to apply to observations
+ """
+
+ def __init__(self, transform: Transform | None = None):
+ self.transform = transform
+
+ @abstractmethod
+ def reset(
+ self,
+ seed: Optional[int] = None,
+ episode_id: Optional[str] = None,
+ **kwargs: Any,
+ ) -> Observation:
+ """Reset the environment and return initial observation."""
+ pass
+
+ @abstractmethod
+ def step(
+ self,
+ action: Action,
+ timeout_s: Optional[float] = None,
+ **kwargs: Any,
+ ) -> Observation:
+ """Take a step in the environment."""
+ pass
+
+ @property
+ @abstractmethod
+ def state(self) -> State:
+ """Get the current environment state."""
+ pass
+
+ def get_metadata(self) -> EnvironmentMetadata:
+ """
+ Get metadata about this environment.
+
+ Override this method to provide custom metadata for the environment.
+ Default implementation returns basic metadata derived from class name.
+
+ Returns:
+ EnvironmentMetadata with environment information
+ """
+ return EnvironmentMetadata(
+ name=self.__class__.__name__,
+ description=f"{self.__class__.__name__} environment",
+ version="1.0.0",
+ )
+
+ def _apply_transform(self, observation: Observation) -> Observation:
+ """Apply transform if one is provided."""
+ if self.transform is not None:
+ return self.transform(observation)
+ return observation
diff --git a/src/openenv/core/env_server/route_config.py b/src/openenv/core/env_server/route_config.py
new file mode 100644
index 00000000..08807c68
--- /dev/null
+++ b/src/openenv/core/env_server/route_config.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.
+
+"""
+Route configuration utilities for declarative FastAPI route registration.
+
+This module provides utilities to reduce boilerplate in route registration
+by using configuration objects instead of repeated function calls.
+"""
+
+from dataclasses import dataclass
+from typing import Callable, List, Type
+
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+
+@dataclass
+class GetEndpointConfig:
+ """Configuration for a simple GET endpoint."""
+
+ path: str
+ handler: Callable[[], BaseModel | dict]
+ response_model: Type[BaseModel] | type[dict]
+ tag: str
+ summary: str
+ description: str
+
+
+def register_get_endpoints(app: FastAPI, configs: List[GetEndpointConfig]) -> None:
+ """
+ Register multiple GET endpoints from configuration.
+
+ Args:
+ app: FastAPI application instance
+ configs: List of GET endpoint configurations
+ """
+ for config in configs:
+ # Capture handler in a closure to avoid non-serializable default parameter
+ def make_endpoint(
+ handler: Callable[[], BaseModel | dict],
+ ) -> Callable[[], BaseModel | dict]:
+ async def endpoint() -> BaseModel | dict:
+ return handler()
+
+ return endpoint
+
+ app.get(
+ config.path,
+ response_model=config.response_model,
+ tags=[config.tag],
+ summary=config.summary,
+ description=config.description,
+ )(make_endpoint(config.handler))
diff --git a/src/openenv/core/env_server/serialization.py b/src/openenv/core/env_server/serialization.py
new file mode 100644
index 00000000..a97a0528
--- /dev/null
+++ b/src/openenv/core/env_server/serialization.py
@@ -0,0 +1,139 @@
+# 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.
+
+"""
+Shared serialization and deserialization utilities for OpenEnv HTTP servers.
+
+This module provides common utilities for converting between JSON dictionaries
+and Pydantic models (Action/Observation) to eliminate code duplication across
+HTTP server and web interface implementations.
+"""
+
+from typing import Any, Dict, Type
+
+from .types import Action, Observation
+
+
+def deserialize_action(
+ action_data: Dict[str, Any], action_cls: Type[Action]
+) -> Action:
+ """
+ Convert JSON dict to Action instance using Pydantic validation.
+
+ This is a basic deserialization that works for most environments.
+ For special cases (e.g., tensor fields, custom type conversions),
+ use deserialize_action_with_preprocessing().
+
+ Args:
+ action_data: Dictionary containing action data
+ action_cls: The Action subclass to instantiate
+
+ Returns:
+ Action instance
+
+ Raises:
+ ValidationError: If action_data is invalid for the action class
+
+ Note:
+ This uses Pydantic's model_validate() for automatic validation.
+ """
+ return action_cls.model_validate(action_data)
+
+
+def deserialize_action_with_preprocessing(
+ action_data: Dict[str, Any], action_cls: Type[Action]
+) -> Action:
+ """
+ Convert JSON dict to Action instance with preprocessing for special types.
+
+ This version handles common type conversions needed for web interfaces:
+ - Converting lists/strings to tensors for 'tokens' field
+ - Converting string action_id to int
+ - Other custom preprocessing as needed
+
+ Args:
+ action_data: Dictionary containing action data
+ action_cls: The Action subclass to instantiate
+
+ Returns:
+ Action instance
+
+ Raises:
+ ValidationError: If action_data is invalid for the action class
+ """
+ processed_data = {}
+
+ for key, value in action_data.items():
+ if key == "tokens" and isinstance(value, (list, str)):
+ # Convert list or string to tensor
+ if isinstance(value, str):
+ # If it's a string, try to parse it as a list of numbers
+ try:
+ import json
+
+ value = json.loads(value)
+ except Exception:
+ # If parsing fails, treat as empty list
+ value = []
+ if isinstance(value, list):
+ try:
+ import torch
+
+ processed_data[key] = torch.tensor(value, dtype=torch.long)
+ except ImportError:
+ # If torch not available, keep as list
+ processed_data[key] = value
+ else:
+ processed_data[key] = value
+ elif key == "action_id" and isinstance(value, str):
+ # Convert action_id from string to int
+ try:
+ processed_data[key] = int(value)
+ except ValueError:
+ # If conversion fails, keep original value
+ processed_data[key] = value
+ else:
+ processed_data[key] = value
+
+ return action_cls.model_validate(processed_data)
+
+
+def serialize_observation(observation: Observation) -> Dict[str, Any]:
+ """
+ Convert Observation instance to JSON-compatible dict using Pydantic.
+
+ Args:
+ observation: Observation instance
+
+ Returns:
+ Dictionary compatible with HTTPEnvClient._parse_result()
+
+ The format matches what HTTPEnvClient expects:
+ {
+ "observation": {...}, # Observation fields
+ "reward": float | None,
+ "done": bool,
+ }
+ """
+ # Use Pydantic's model_dump() for serialization
+ obs_dict = observation.model_dump(
+ exclude={
+ "reward",
+ "done",
+ "metadata",
+ } # Exclude these from observation dict
+ )
+
+ # Extract reward and done directly from the observation
+ reward = observation.reward
+ done = observation.done
+
+ # Return in HTTPEnvClient expected format
+ return {
+ "observation": obs_dict,
+ "reward": reward,
+ "done": done,
+ }
diff --git a/src/openenv/core/env_server/types.py b/src/openenv/core/env_server/types.py
new file mode 100644
index 00000000..c3ee689c
--- /dev/null
+++ b/src/openenv/core/env_server/types.py
@@ -0,0 +1,214 @@
+# 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.
+
+from typing import Any, Dict, Optional, Union
+from pydantic import BaseModel, Field, ConfigDict
+
+
+# Type aliases
+Scalar = Union[int, float, bool]
+
+
+class Action(BaseModel):
+ """Base class for all environment actions.
+
+ All action subclasses should inherit from this base class.
+ Uses Pydantic for automatic validation and serialization.
+ """
+
+ model_config = ConfigDict(
+ extra="forbid", # Reject unknown fields
+ validate_assignment=True, # Validate on field assignment
+ arbitrary_types_allowed=True, # Allow numpy arrays, torch tensors, etc.
+ )
+
+ metadata: Dict[str, Any] = Field(
+ default_factory=dict, description="Additional metadata for the action"
+ )
+
+
+class Observation(BaseModel):
+ """Base class for all environment observations.
+
+ All observation subclasses should inherit from this base class.
+ Uses Pydantic for automatic validation and serialization.
+ """
+
+ model_config = ConfigDict(
+ extra="forbid",
+ validate_assignment=True,
+ arbitrary_types_allowed=True,
+ )
+
+ done: bool = Field(default=False, description="Whether the episode has terminated")
+ reward: bool | int | float | None = Field(
+ default=None, description="Reward signal from the last action"
+ )
+ metadata: Dict[str, Any] = Field(
+ default_factory=dict, description="Additional metadata for the observation"
+ )
+
+
+class ResetRequest(BaseModel):
+ """Request model for environment reset."""
+
+ model_config = ConfigDict(
+ extra="allow", # Allow extra fields for custom reset parameters
+ json_schema_extra={"examples": [{"seed": 42, "episode_id": "episode-001"}, {}]},
+ )
+
+ seed: Optional[int] = Field(
+ default=None, ge=0, description="Random seed for reproducible episodes"
+ )
+ episode_id: Optional[str] = Field(
+ default=None, max_length=255, description="Custom episode identifier"
+ )
+
+
+class ResetResponse(BaseModel):
+ """Response model for environment reset."""
+
+ model_config = ConfigDict(extra="forbid")
+
+ observation: Dict[str, Any] = Field(
+ ..., description="Initial observation from the environment"
+ )
+ reward: Optional[float] = Field(
+ default=None, description="Initial reward (typically None at reset)"
+ )
+ done: bool = Field(
+ default=False, description="Whether episode is already done (typically False)"
+ )
+
+
+class StepRequest(BaseModel):
+ """Request model for environment step."""
+
+ model_config = ConfigDict(
+ extra="allow", # Allow extra fields for custom step parameters
+ json_schema_extra={
+ "examples": [
+ {"action": {"value": 1}, "timeout_s": 30.0},
+ {"action": {"value": 1}, "render": True, "verbose": False},
+ ]
+ },
+ )
+
+ action: Dict[str, Any] = Field(
+ ...,
+ description="Action to execute, must conform to environment's action schema",
+ )
+ timeout_s: Optional[float] = Field(
+ default=None,
+ gt=0,
+ description="Optional timeout in seconds for action execution",
+ )
+ request_id: Optional[str] = Field(
+ default=None,
+ max_length=255,
+ description="Optional request identifier for tracking",
+ )
+
+
+class StepResponse(BaseModel):
+ """Response model for environment step."""
+
+ model_config = ConfigDict(extra="forbid")
+
+ observation: Dict[str, Any] = Field(
+ ..., description="Observation resulting from the action"
+ )
+ reward: Optional[float] = Field(
+ default=None, description="Reward signal from the action"
+ )
+ done: bool = Field(default=False, description="Whether the episode has terminated")
+
+
+class State(BaseModel):
+ """Base class for environment state.
+
+ Represents internal environment state, separate from observations.
+ """
+
+ model_config = ConfigDict(
+ extra="allow", # Allow extra fields for flexibility
+ validate_assignment=True,
+ arbitrary_types_allowed=True,
+ )
+
+ episode_id: Optional[str] = Field(
+ default=None, description="Unique identifier for the current episode"
+ )
+ step_count: int = Field(
+ default=0,
+ ge=0, # Greater than or equal to 0
+ description="Number of steps taken in the current episode",
+ )
+
+
+class CodeExecResult(BaseModel):
+ """Result of code execution containing stdout, stderr, and exit code."""
+
+ model_config = ConfigDict(
+ extra="forbid",
+ validate_assignment=True,
+ )
+
+ stdout: str = Field(description="Standard output from code execution")
+ stderr: str = Field(description="Standard error from code execution")
+ exit_code: int = Field(description="Exit code from code execution")
+
+
+class EnvironmentMetadata(BaseModel):
+ """Metadata about an environment for documentation and UI purposes."""
+
+ model_config = ConfigDict(
+ extra="forbid",
+ validate_assignment=True,
+ )
+
+ name: str = Field(description="Name of the environment")
+ description: str = Field(description="Description of what the environment does")
+ readme_content: Optional[str] = Field(
+ default=None, description="Content of the README file for the environment"
+ )
+ version: Optional[str] = Field(
+ default=None, description="Version of the environment"
+ )
+ author: Optional[str] = Field(default=None, description="Author of the environment")
+ documentation_url: Optional[str] = Field(
+ default=None, description="URL to the environment's documentation"
+ )
+
+
+class SchemaResponse(BaseModel):
+ """Response model for the combined schema endpoint."""
+
+ model_config = ConfigDict(
+ extra="forbid",
+ validate_assignment=True,
+ )
+
+ action: Dict[str, Any] = Field(
+ description="JSON schema for actions accepted by this environment"
+ )
+ observation: Dict[str, Any] = Field(
+ description="JSON schema for observations returned by this environment"
+ )
+ state: Dict[str, Any] = Field(
+ description="JSON schema for environment state objects"
+ )
+
+
+class HealthResponse(BaseModel):
+ """Response model for health check endpoint."""
+
+ model_config = ConfigDict(
+ extra="forbid",
+ validate_assignment=True,
+ )
+
+ status: str = Field(description="Health status of the environment server")
diff --git a/src/core/env_server/web_interface.py b/src/openenv/core/env_server/web_interface.py
similarity index 78%
rename from src/core/env_server/web_interface.py
rename to src/openenv/core/env_server/web_interface.py
index 3c36aa1d..b370cfa5 100644
--- a/src/core/env_server/web_interface.py
+++ b/src/openenv/core/env_server/web_interface.py
@@ -1,1613 +1,1591 @@
-# 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.
-
-"""
-Web interface for OpenEnv environments.
-
-This module provides a web-based interface for interacting with OpenEnv environments,
-including a two-pane layout for HumanAgent interaction and state observation.
-"""
-
-from __future__ import annotations
-
-import json
-import time
-from dataclasses import asdict, dataclass
-from typing import Any, Dict, List, Optional, Type
-from datetime import datetime
-
-from fastapi import FastAPI, WebSocket, WebSocketDisconnect, Request
-from fastapi.responses import HTMLResponse, FileResponse
-from fastapi.staticfiles import StaticFiles
-from pydantic import BaseModel
-
-from .interfaces import Environment
-from .types import Action, Observation, State, EnvironmentMetadata
-
-
-def load_environment_metadata(env: Environment, env_name: Optional[str] = None) -> EnvironmentMetadata:
- """
- Load environment metadata including README content.
-
- Args:
- env: The environment instance
- env_name: Optional environment name for README file lookup
-
- Returns:
- EnvironmentMetadata with loaded information
- """
- # Try to get metadata from environment if it has a method for it
- if hasattr(env, 'get_metadata'):
- return env.get_metadata()
-
- # Default metadata
- metadata = EnvironmentMetadata(
- name=env_name or env.__class__.__name__,
- description=f"{env.__class__.__name__} environment",
- version="1.0.0"
- )
-
- # Try to load README from file system
- readme_content = _load_readme_from_filesystem(env_name)
- if readme_content:
- metadata.readme_content = readme_content
-
- return metadata
-
-
-def _load_readme_from_filesystem(env_name: Optional[str]) -> Optional[str]:
- """
- Load README content from the filesystem.
-
- Tries multiple locations:
- 1. Container filesystem: /app/README.md
- 2. Local development: src/envs/{env_name}/README.md
- 3. Environment variable: ENV_README_PATH
- """
- import os
- from pathlib import Path
-
- # Try container filesystem first
- container_readme = Path("/app/README.md")
- if container_readme.exists():
- try:
- return container_readme.read_text(encoding='utf-8')
- except Exception:
- pass
-
- # Try environment variable path
- custom_path = os.environ.get("ENV_README_PATH")
- if custom_path and Path(custom_path).exists():
- try:
- return Path(custom_path).read_text(encoding='utf-8')
- except Exception:
- pass
-
- # Try local development path
- if env_name:
- local_readme = Path(f"src/envs/{env_name}/README.md")
- if local_readme.exists():
- try:
- return local_readme.read_text(encoding='utf-8')
- except Exception:
- pass
-
- return None
-
-
-@dataclass
-class ActionLog:
- """Log entry for an action taken."""
- timestamp: str
- action: Dict[str, Any]
- observation: Dict[str, Any]
- reward: Optional[float]
- done: bool
- step_count: int
-
-
-@dataclass
-class EpisodeState:
- """Current episode state for the web interface."""
- episode_id: Optional[str]
- step_count: int
- current_observation: Optional[Dict[str, Any]]
- action_logs: List[ActionLog]
- is_reset: bool = True
-
-
-class WebInterfaceManager:
- """Manages the web interface for an environment."""
-
- def __init__(
- self,
- env: Environment,
- action_cls: Type[Action],
- observation_cls: Type[Observation],
- metadata: Optional[EnvironmentMetadata] = None,
- ):
- self.env = env
- self.action_cls = action_cls
- self.observation_cls = observation_cls
- self.metadata = metadata or EnvironmentMetadata(
- name=env.__class__.__name__,
- description=f"{env.__class__.__name__} environment"
- )
- self.episode_state = EpisodeState(
- episode_id=None,
- step_count=0,
- current_observation=None,
- action_logs=[]
- )
- self.connected_clients: List[WebSocket] = []
-
- async def connect_websocket(self, websocket: WebSocket):
- """Connect a new WebSocket client."""
- await websocket.accept()
- self.connected_clients.append(websocket)
-
- # Send current state to the new client
- await self._send_state_update()
-
- async def disconnect_websocket(self, websocket: WebSocket):
- """Disconnect a WebSocket client."""
- if websocket in self.connected_clients:
- self.connected_clients.remove(websocket)
-
- async def _send_state_update(self):
- """Send current state to all connected clients."""
- if not self.connected_clients:
- return
-
- state_data = {
- "type": "state_update",
- "episode_state": asdict(self.episode_state)
- }
-
- # Send to all connected clients
- disconnected_clients = []
- for client in self.connected_clients:
- try:
- await client.send_text(json.dumps(state_data))
- except:
- disconnected_clients.append(client)
-
- # Remove disconnected clients
- for client in disconnected_clients:
- self.connected_clients.remove(client)
-
- async def reset_environment(self) -> Dict[str, Any]:
- """Reset the environment and update state."""
- observation = self.env.reset()
- state = self.env.state
-
- # Update episode state
- self.episode_state.episode_id = state.episode_id
- self.episode_state.step_count = 0
- self.episode_state.current_observation = asdict(observation)
- self.episode_state.action_logs = []
- self.episode_state.is_reset = True
-
- # Send state update
- await self._send_state_update()
-
- return {
- "observation": asdict(observation),
- "reward": observation.reward,
- "done": observation.done,
- }
-
- async def step_environment(self, action_data: Dict[str, Any]) -> Dict[str, Any]:
- """Execute a step in the environment and update state."""
- # Deserialize action
- action = self._deserialize_action(action_data)
-
- # Execute step
- observation = self.env.step(action)
- state = self.env.state
-
- # Create action log
- action_log = ActionLog(
- timestamp=datetime.now().isoformat(),
- action=asdict(action),
- observation=asdict(observation),
- reward=observation.reward,
- done=observation.done,
- step_count=state.step_count
- )
-
- # Update episode state
- self.episode_state.episode_id = state.episode_id
- self.episode_state.step_count = state.step_count
- self.episode_state.current_observation = asdict(observation)
- self.episode_state.action_logs.append(action_log)
- self.episode_state.is_reset = False
-
- # Send state update
- await self._send_state_update()
-
- return {
- "observation": asdict(observation),
- "reward": observation.reward,
- "done": observation.done,
- }
-
- def get_state(self) -> Dict[str, Any]:
- """Get current environment state."""
- state = self.env.state
- return asdict(state)
-
- def _deserialize_action(self, action_data: Dict[str, Any]) -> Action:
- """Convert JSON dict to Action instance."""
- metadata = action_data.pop("metadata", {})
-
- # Handle tensor fields that come from JSON as lists
- processed_data = {}
- for key, value in action_data.items():
- if key == "tokens" and isinstance(value, (list, str)):
- # Convert list or string to tensor
- if isinstance(value, str):
- # If it's a string, try to parse it as a list of numbers
- try:
- import json
- value = json.loads(value)
- except:
- # If parsing fails, treat as empty list
- value = []
- if isinstance(value, list):
- import torch
- processed_data[key] = torch.tensor(value, dtype=torch.long)
- else:
- processed_data[key] = value
- elif key == "action_id" and isinstance(value, str):
- # Convert action_id from string to int
- try:
- processed_data[key] = int(value)
- except ValueError:
- # If conversion fails, keep original value
- processed_data[key] = value
- else:
- processed_data[key] = value
-
- action = self.action_cls(**processed_data)
- action.metadata = metadata
- return action
-
-
-def create_web_interface_app(
- env: Environment,
- action_cls: Type[Action],
- observation_cls: Type[Observation],
- env_name: Optional[str] = None,
-) -> FastAPI:
- """
- Create a FastAPI application with web interface for the given environment.
-
- Args:
- env: The Environment instance to serve
- action_cls: The Action subclass this environment expects
- observation_cls: The Observation subclass this environment returns
- env_name: Optional environment name for README loading
-
- Returns:
- FastAPI application instance with web interface
- """
- from .http_server import create_fastapi_app
-
- # Create the base environment app
- app = create_fastapi_app(env, action_cls, observation_cls)
-
- # Load environment metadata
- metadata = load_environment_metadata(env, env_name)
-
- # Create web interface manager
- web_manager = WebInterfaceManager(env, action_cls, observation_cls, metadata)
-
- # Add web interface routes
- @app.get("/web", response_class=HTMLResponse)
- async def web_interface():
- """Serve the web interface."""
- return get_web_interface_html(action_cls, web_manager.metadata)
-
- @app.get("/web/metadata")
- async def web_metadata():
- """Get environment metadata."""
- return asdict(web_manager.metadata)
-
- @app.websocket("/ws")
- async def websocket_endpoint(websocket: WebSocket):
- """WebSocket endpoint for real-time updates."""
- await web_manager.connect_websocket(websocket)
- try:
- while True:
- # Keep connection alive
- await websocket.receive_text()
- except WebSocketDisconnect:
- await web_manager.disconnect_websocket(websocket)
-
- @app.post("/web/reset")
- async def web_reset():
- """Reset endpoint for web interface."""
- return await web_manager.reset_environment()
-
- @app.post("/web/step")
- async def web_step(request: Dict[str, Any]):
- """Step endpoint for web interface."""
- # Check if this is a message-based request (chat environment)
- if "message" in request:
- message = request["message"]
- # Convert message to action using the environment's message_to_action method
- action = web_manager.env.message_to_action(message)
- action_data = {"tokens": action.tokens.tolist()}
- else:
- action_data = request.get("action", {})
-
- return await web_manager.step_environment(action_data)
-
- @app.get("/web/state")
- async def web_state():
- """State endpoint for web interface."""
- return web_manager.get_state()
-
- return app
-
-
-def get_web_interface_html(action_cls: Type[Action], metadata: Optional[EnvironmentMetadata] = None) -> str:
- """Generate the HTML for the web interface."""
-
- # Check if this is a chat environment by looking for tokens field
- is_chat_env = False
- if hasattr(action_cls, '__dataclass_fields__'):
- for field_name, field_info in action_cls.__dataclass_fields__.items():
- if field_name == 'tokens' and hasattr(field_info.type, '__name__') and 'Tensor' in field_info.type.__name__:
- is_chat_env = True
- break
-
- # Get action fields for dynamic form generation with enhanced metadata
- action_fields = _extract_action_fields(action_cls)
-
- return f"""
-
-
-
- OpenEnv Web Interface
-
-
-
-
-
-
-
-
-
- {_generate_instructions_section(metadata)}
-
-
- {_generate_action_interface(action_fields, is_chat_env)}
-
-
-
- Reset Environment
- Get State
-
-
-
-
-
Current State
-
-
- Status:
- Not initialized
-
-
- Episode ID:
- -
-
-
- Step Count:
- 0
-
-
-
-
-
-
-
-
-
-
-
-
-
Current Observation
-
- No observation yet
-
-
-
-
-
-
Action History
-
- No actions taken yet
-
-
-
-
-
\1 ', html_content, flags=re.MULTILINE)
- html_content = re.sub(r'^## (.*?)$', r'\1 ', html_content, flags=re.MULTILINE)
- html_content = re.sub(r'^### (.*?)$', r'\1 ', html_content, flags=re.MULTILINE)
-
- # Convert code blocks
- html_content = re.sub(r'```(.*?)\n(.*?)\n```', r'\2\1', html_content)
-
- # Convert bold and italic
- html_content = re.sub(r'\*\*(.*?)\*\*', r'\1 ', html_content)
- html_content = re.sub(r'\*(.*?)\*', r'\1 ', html_content)
-
- # Convert lists
- html_content = re.sub(r'^- (.*?)$', r'\1 ', html_content, flags=re.MULTILINE)
- html_content = re.sub(r'(.* )', r'', html_content, flags=re.DOTALL)
-
- # Convert line breaks
- html_content = html_content.replace('\n', '
-
Chat Interface
-
-
-
System
-
Chat environment ready. Send a message to start the conversation.
-
-
-
-
-
Take Action
-
-
- '''
-
-def _generate_action_form_fields(action_fields: List[Dict[str, Any]]) -> str:
- """Generate HTML form fields for action input with enhanced metadata."""
- if not action_fields:
- return 'No action fields available
'
-
- fields_html = []
- for field in action_fields:
- field_html = _generate_single_field(field)
- fields_html.append(field_html)
-
- return '\n'.join(fields_html)
-
-
-def _generate_single_field(field: Dict[str, Any]) -> str:
- """Generate HTML for a single form field with enhanced metadata."""
- field_name = field['name']
- field_type = field['type']
- required = field['required']
- placeholder = field.get('placeholder', '')
- help_text = field.get('help_text', '')
- choices = field.get('choices', [])
- min_value = field.get('min_value')
- max_value = field.get('max_value')
- default_value = field.get('default_value')
-
- # Build label with required indicator
- label_text = field_name.replace('_', ' ').title()
- if required:
- label_text += ' * '
-
- # Build input attributes
- input_attrs = []
- if required:
- input_attrs.append('required')
- if placeholder:
- input_attrs.append(f'placeholder="{placeholder}"')
- if min_value is not None:
- input_attrs.append(f'min="{min_value}"')
- if max_value is not None:
- input_attrs.append(f'max="{max_value}"')
- if default_value is not None:
- input_attrs.append(f'value="{default_value}"')
-
- attrs_str = ' '.join(input_attrs)
-
- if field_type == 'checkbox':
- return f'''
-
-
-
- {f'{help_text} ' if help_text else ''}
-
- '''
-
- elif field_type == 'select':
- options_html = []
- if not required:
- options_html.append(f'-- Select {label_text} -- ')
-
- for choice in choices:
- selected = 'selected' if str(choice) == str(default_value) else ''
- options_html.append(f'{choice} ')
-
- return f'''
-
- {label_text}:
-
- {''.join(options_html)}
-
- {f'{help_text} ' if help_text else ''}
-
- '''
-
- elif field_type == 'tensor':
- return f'''
-
- {label_text} (comma-separated integers):
- {help_text or 'Enter token IDs as comma-separated integers (e.g., 1,2,3,4,5)'}
-
- '''
-
- elif field_type == 'text' and ('message' in field_name.lower() or 'code' in field_name.lower()):
- return f'''
-
- {label_text}:
-
- {f'{help_text} ' if help_text else ''}
-
- '''
-
- else:
- return f'''
-
- {label_text}:
- {help_text} ' if help_text else ''}
-
- '''
+# 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.
+
+"""
+Web interface for OpenEnv environments.
+
+This module provides a web-based interface for interacting with OpenEnv environments,
+including a two-pane layout for HumanAgent interaction and state observation.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional, Type
+from datetime import datetime
+
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+from fastapi.responses import HTMLResponse
+from pydantic import BaseModel, Field, ConfigDict
+
+from .interfaces import Environment
+from .serialization import deserialize_action_with_preprocessing, serialize_observation
+from .types import Action, Observation, State, EnvironmentMetadata
+
+
+def load_environment_metadata(
+ env: Environment, env_name: Optional[str] = None
+) -> EnvironmentMetadata:
+ """
+ Load environment metadata including README content.
+
+ Args:
+ env: The environment instance
+ env_name: Optional environment name for README file lookup
+
+ Returns:
+ EnvironmentMetadata with loaded information
+ """
+ # Try to get metadata from environment if it has a method for it
+ if hasattr(env, "get_metadata"):
+ return env.get_metadata()
+
+ # Default metadata
+ metadata = EnvironmentMetadata(
+ name=env_name or env.__class__.__name__,
+ description=f"{env.__class__.__name__} environment",
+ version="1.0.0",
+ )
+
+ # Try to load README from file system
+ readme_content = _load_readme_from_filesystem(env_name)
+ if readme_content:
+ metadata.readme_content = readme_content
+
+ return metadata
+
+
+def _load_readme_from_filesystem(env_name: Optional[str]) -> Optional[str]:
+ """
+ Load README content from the filesystem.
+
+ Tries multiple locations:
+ 1. Container filesystem: /app/README.md
+ 2. Local development: src/envs/{env_name}/README.md
+ 3. Environment variable: ENV_README_PATH
+ """
+ import os
+ from pathlib import Path
+
+ # Try container filesystem first
+ container_readme = Path("/app/README.md")
+ if container_readme.exists():
+ try:
+ return container_readme.read_text(encoding="utf-8")
+ except Exception:
+ pass
+
+ # Try environment variable path
+ custom_path = os.environ.get("ENV_README_PATH")
+ if custom_path and Path(custom_path).exists():
+ try:
+ return Path(custom_path).read_text(encoding="utf-8")
+ except Exception:
+ pass
+
+ # Try local development path
+ if env_name:
+ local_readme = Path(f"src/envs/{env_name}/README.md")
+ if local_readme.exists():
+ try:
+ return local_readme.read_text(encoding="utf-8")
+ except Exception:
+ pass
+
+ return None
+
+
+class ActionLog(BaseModel):
+ """Log entry for an action taken."""
+
+ model_config = ConfigDict(extra="forbid", validate_assignment=True)
+
+ timestamp: str = Field(description="Timestamp when action was taken")
+ action: Dict[str, Any] = Field(description="Action that was taken")
+ observation: Dict[str, Any] = Field(description="Observation returned from action")
+ reward: Optional[float] = Field(
+ default=None, description="Reward received from action"
+ )
+ done: bool = Field(description="Whether the episode is done after this action")
+ step_count: int = Field(description="Step count when this action was taken")
+
+
+class EpisodeState(BaseModel):
+ """Current episode state for the web interface."""
+
+ model_config = ConfigDict(extra="forbid", validate_assignment=True)
+
+ episode_id: Optional[str] = Field(default=None, description="Current episode ID")
+ step_count: int = Field(description="Current step count in episode")
+ current_observation: Optional[Dict[str, Any]] = Field(
+ default=None, description="Current observation"
+ )
+ action_logs: List[ActionLog] = Field(
+ default_factory=list, description="List of action logs"
+ )
+ is_reset: bool = Field(
+ default=True, description="Whether the episode has been reset"
+ )
+
+
+class WebInterfaceManager:
+ """Manages the web interface for an environment."""
+
+ def __init__(
+ self,
+ env: Environment,
+ action_cls: Type[Action],
+ observation_cls: Type[Observation],
+ metadata: Optional[EnvironmentMetadata] = None,
+ ):
+ self.env = env
+ self.action_cls = action_cls
+ self.observation_cls = observation_cls
+ self.metadata = metadata or EnvironmentMetadata(
+ name=env.__class__.__name__,
+ description=f"{env.__class__.__name__} environment",
+ )
+ self.episode_state = EpisodeState(
+ episode_id=None, step_count=0, current_observation=None, action_logs=[]
+ )
+ self.connected_clients: List[WebSocket] = []
+
+ async def connect_websocket(self, websocket: WebSocket):
+ """Connect a new WebSocket client."""
+ await websocket.accept()
+ self.connected_clients.append(websocket)
+
+ # Send current state to the new client
+ await self._send_state_update()
+
+ async def disconnect_websocket(self, websocket: WebSocket):
+ """Disconnect a WebSocket client."""
+ if websocket in self.connected_clients:
+ self.connected_clients.remove(websocket)
+
+ async def _send_state_update(self):
+ """Send current state to all connected clients."""
+ if not self.connected_clients:
+ return
+
+ state_data = {
+ "type": "state_update",
+ "episode_state": self.episode_state.model_dump(),
+ }
+
+ # Send to all connected clients
+ disconnected_clients = []
+ for client in self.connected_clients:
+ try:
+ await client.send_text(json.dumps(state_data))
+ except Exception:
+ disconnected_clients.append(client)
+
+ # Remove disconnected clients
+ for client in disconnected_clients:
+ self.connected_clients.remove(client)
+
+ async def reset_environment(self) -> Dict[str, Any]:
+ """Reset the environment and update state."""
+ observation: Observation = self.env.reset()
+ state: State = self.env.state
+
+ # Serialize observation once using shared utility
+ serialized = serialize_observation(observation)
+
+ # Update episode state
+ self.episode_state.episode_id = state.episode_id
+ self.episode_state.step_count = 0
+ self.episode_state.current_observation = serialized["observation"]
+ self.episode_state.action_logs = []
+ self.episode_state.is_reset = True
+
+ # Send state update
+ await self._send_state_update()
+
+ return serialized
+
+ async def step_environment(self, action_data: Dict[str, Any]) -> Dict[str, Any]:
+ """Execute a step in the environment and update state."""
+ # Deserialize action with preprocessing for web interface special cases
+ action: Action = deserialize_action_with_preprocessing(
+ action_data, self.action_cls
+ )
+
+ # Execute step
+ observation: Observation = self.env.step(action)
+ state: State = self.env.state
+
+ # Serialize observation once using shared utility
+ serialized = serialize_observation(observation)
+
+ # Create action log
+ action_log = ActionLog(
+ timestamp=datetime.now().isoformat(),
+ action=action.model_dump(exclude={"metadata"}),
+ observation=serialized["observation"],
+ reward=observation.reward,
+ done=observation.done,
+ step_count=state.step_count,
+ )
+
+ # Update episode state
+ self.episode_state.episode_id = state.episode_id
+ self.episode_state.step_count = state.step_count
+ self.episode_state.current_observation = serialized["observation"]
+ self.episode_state.action_logs.append(action_log)
+ self.episode_state.is_reset = False
+
+ # Send state update
+ await self._send_state_update()
+
+ return serialized
+
+ def get_state(self) -> Dict[str, Any]:
+ """Get current environment state."""
+ state: State = self.env.state
+ return state.model_dump()
+
+
+def create_web_interface_app(
+ env: Environment,
+ action_cls: Type[Action],
+ observation_cls: Type[Observation],
+ env_name: Optional[str] = None,
+) -> FastAPI:
+ """
+ Create a FastAPI application with web interface for the given environment.
+
+ Args:
+ env: The Environment instance to serve
+ action_cls: The Action subclass this environment expects
+ observation_cls: The Observation subclass this environment returns
+ env_name: Optional environment name for README loading
+
+ Returns:
+ FastAPI application instance with web interface
+ """
+ from .http_server import create_fastapi_app
+
+ # Create the base environment app
+ app = create_fastapi_app(env, action_cls, observation_cls)
+
+ # Load environment metadata
+ metadata = load_environment_metadata(env, env_name)
+
+ # Create web interface manager
+ web_manager = WebInterfaceManager(env, action_cls, observation_cls, metadata)
+
+ # Add web interface routes
+ @app.get("/web", response_class=HTMLResponse)
+ async def web_interface():
+ """Serve the web interface."""
+ return get_web_interface_html(action_cls, web_manager.metadata)
+
+ @app.get("/web/metadata")
+ async def web_metadata():
+ """Get environment metadata."""
+ return web_manager.metadata.model_dump()
+
+ @app.websocket("/ws")
+ async def websocket_endpoint(websocket: WebSocket):
+ """WebSocket endpoint for real-time updates."""
+ await web_manager.connect_websocket(websocket)
+ try:
+ while True:
+ # Keep connection alive
+ await websocket.receive_text()
+ except WebSocketDisconnect:
+ await web_manager.disconnect_websocket(websocket)
+
+ @app.post("/web/reset")
+ async def web_reset():
+ """Reset endpoint for web interface."""
+ return await web_manager.reset_environment()
+
+ @app.post("/web/step")
+ async def web_step(request: Dict[str, Any]):
+ """Step endpoint for web interface."""
+ # Check if this is a message-based request (chat environment)
+ if "message" in request:
+ message = request["message"]
+ # Convert message to action using the environment's message_to_action method
+ action = web_manager.env.message_to_action(message)
+ action_data = {"tokens": action.tokens.tolist()}
+ else:
+ action_data = request.get("action", {})
+
+ return await web_manager.step_environment(action_data)
+
+ @app.get("/web/state")
+ async def web_state():
+ """State endpoint for web interface."""
+ return web_manager.get_state()
+
+ return app
+
+
+def get_web_interface_html(
+ action_cls: Type[Action], metadata: Optional[EnvironmentMetadata] = None
+) -> str:
+ """Generate the HTML for the web interface."""
+
+ # Check if this is a chat environment by looking for tokens field
+ is_chat_env = False
+ if hasattr(action_cls, "model_fields"):
+ for field_name, field_info in action_cls.model_fields.items():
+ if (
+ field_name == "tokens"
+ and hasattr(field_info.annotation, "__name__")
+ and "Tensor" in field_info.annotation.__name__
+ ):
+ is_chat_env = True
+ break
+
+ # Get action fields for dynamic form generation with enhanced metadata
+ action_fields = _extract_action_fields(action_cls)
+
+ return f"""
+
+
+
+ OpenEnv Web Interface
+
+
+
+
+
+
+
+
+
+ {_generate_instructions_section(metadata)}
+
+
+ {_generate_action_interface(action_fields, is_chat_env)}
+
+
+
+ Reset Environment
+ Get State
+
+
+
+
+
Current State
+
+
+ Status:
+ Not initialized
+
+
+ Episode ID:
+ -
+
+
+ Step Count:
+ 0
+
+
+
+
+
+
+
+
+
+
+
+
+
Current Observation
+
+ No observation yet
+
+
+
+
+
+
Action History
+
+ No actions taken yet
+
+
+
+
+
\1 ", html_content, flags=re.MULTILINE
+ )
+ html_content = re.sub(
+ r"^## (.*?)$", r"\1 ", html_content, flags=re.MULTILINE
+ )
+ html_content = re.sub(
+ r"^### (.*?)$", r"\1 ", html_content, flags=re.MULTILINE
+ )
+
+ # Convert code blocks
+ html_content = re.sub(
+ r"```(.*?)\n(.*?)\n```",
+ r"\2\1", html_content)
+
+ # Convert bold and italic
+ html_content = re.sub(r"\*\*(.*?)\*\*", r"\1 ", html_content)
+ html_content = re.sub(r"\*(.*?)\*", r"\1 ", html_content)
+
+ # Convert lists
+ html_content = re.sub(
+ r"^- (.*?)$", r"\1 ", html_content, flags=re.MULTILINE
+ )
+ html_content = re.sub(
+ r"(.* )", r"", html_content, flags=re.DOTALL
+ )
+
+ # Convert line breaks
+ html_content = html_content.replace("\n", "
+
Chat Interface
+
+
+
System
+
Chat environment ready. Send a message to start the conversation.
+
+
+
+
+
Take Action
+
+
+ """
+
+
+def _generate_action_form_fields(action_fields: List[Dict[str, Any]]) -> str:
+ """Generate HTML form fields for action input with enhanced metadata."""
+ if not action_fields:
+ return "No action fields available
"
+
+ fields_html = []
+ for field in action_fields:
+ field_html = _generate_single_field(field)
+ fields_html.append(field_html)
+
+ return "\n".join(fields_html)
+
+
+def _generate_single_field(field: Dict[str, Any]) -> str:
+ """Generate HTML for a single form field with enhanced metadata."""
+ field_name = field["name"]
+ field_type = field["type"]
+ required = field["required"]
+ placeholder = field.get("placeholder", "")
+ help_text = field.get("help_text", "")
+ choices = field.get("choices", [])
+ min_value = field.get("min_value")
+ max_value = field.get("max_value")
+ default_value = field.get("default_value")
+ min_length = field.get("min_length")
+ max_length = field.get("max_length")
+ pattern = field.get("pattern")
+
+ # Build label with required indicator
+ label_text = field_name.replace("_", " ").title()
+ if required:
+ label_text += ' * '
+
+ # Build input attributes
+ input_attrs = []
+ if required:
+ input_attrs.append("required")
+ if placeholder:
+ input_attrs.append(f'placeholder="{placeholder}"')
+ if min_value is not None:
+ input_attrs.append(f'min="{min_value}"')
+ if max_value is not None:
+ input_attrs.append(f'max="{max_value}"')
+ if min_length is not None:
+ input_attrs.append(f'minlength="{min_length}"')
+ if max_length is not None:
+ input_attrs.append(f'maxlength="{max_length}"')
+ if pattern is not None:
+ input_attrs.append(f'pattern="{pattern}"')
+ if default_value is not None:
+ input_attrs.append(f'value="{default_value}"')
+
+ attrs_str = " ".join(input_attrs)
+
+ if field_type == "checkbox":
+ checked = "checked" if default_value is True else ""
+ return f'''
+
+
+
+ {f'{help_text} ' if help_text else ""}
+
+ '''
+
+ elif field_type == "select":
+ options_html = []
+ if not required:
+ options_html.append(f'-- Select {label_text} -- ')
+
+ for choice in choices:
+ selected = "selected" if str(choice) == str(default_value) else ""
+ options_html.append(
+ f'{choice} '
+ )
+
+ return f'''
+
+ {label_text}:
+
+ {"".join(options_html)}
+
+ {f'{help_text} ' if help_text else ""}
+
+ '''
+
+ elif field_type == "tensor":
+ return f'''
+
+ {label_text} (comma-separated integers):
+ {help_text or "Enter token IDs as comma-separated integers (e.g., 1,2,3,4,5)"}
+
+ '''
+
+ elif field_type == "textarea":
+ return f'''
+
+ {label_text}:
+
+ {f'{help_text} ' if help_text else ""}
+
+ '''
+
+ else:
+ return f'''
+
+ {label_text}:
+ {help_text} ' if help_text else ""}
+
+ '''
diff --git a/src/core/http_env_client.py b/src/openenv/core/http_env_client.py
similarity index 76%
rename from src/core/http_env_client.py
rename to src/openenv/core/http_env_client.py
index 16bbfa5d..007ef6a5 100644
--- a/src/core/http_env_client.py
+++ b/src/openenv/core/http_env_client.py
@@ -1,203 +1,236 @@
-"""
-core/runner_env.py
-Minimal HTTP-based environment client.
-- Talks to a single env worker exposing: POST /reset, POST /step
-
-Future hooks (commented below) for:
-- episode_id, seed on reset
-- request_id on step
-- custom headers (auth/trace)
-"""
-
-from __future__ import annotations
-
-from abc import ABC, abstractmethod
-from typing import Any, Dict, Generic, Optional, Type, TYPE_CHECKING, TypeVar
-
-import requests
-
-from .client_types import StepResult
-from .containers.runtime import LocalDockerProvider
-
-if TYPE_CHECKING:
- from .containers.runtime import ContainerProvider
-
-ActT = TypeVar("ActT")
-ObsT = TypeVar("ObsT")
-EnvClientT = TypeVar("EnvClientT", bound="HTTPEnvClient")
-
-
-class HTTPEnvClient(ABC, Generic[ActT, ObsT]):
- def __init__(
- self,
- base_url: str,
- request_timeout_s: float = 15.0,
- default_headers: Optional[Dict[str, str]] = None,
- provider: Optional["ContainerProvider"] = None,
- ):
- self._base = base_url.rstrip("/")
- self._timeout = float(request_timeout_s)
- self._http = requests.Session()
- self._headers = default_headers or {}
- self._provider = provider
-
- @classmethod
- def from_docker_image(
- cls: Type[EnvClientT],
- image: str,
- provider: Optional["ContainerProvider"] = None,
- **kwargs: Any,
- ) -> EnvClientT:
- """
- Create an environment client by spinning up a Docker container locally.
-
- This is a development utility that:
- 1. Starts a Docker container from the specified image
- 2. Waits for the server to be ready
- 3. Creates and returns a client instance connected to the container
-
- Note: The container lifecycle management is left to the user or higher-level
- orchestration. The container will keep running until manually stopped.
-
- Args:
- image: Docker image name to run (e.g., "echo-env:latest")
- provider: Container provider to use (defaults to LocalDockerProvider)
- **kwargs: Additional arguments to pass to provider.start_container()
- (e.g., env_vars, port)
-
- Returns:
- An instance of the client class connected to the running container
-
- Example:
- >>> from envs.coding_env.client import CodingEnv
- >>> from envs.coding_env.models import CodeAction
- >>>
- >>> # Create environment from image
- >>> env = CodingEnv.from_docker_image("coding-env:latest")
- >>>
- >>> # Create environment with custom env vars
- >>> env = CodingEnv.from_docker_image(
- ... "coding-env:latest",
- ... env_vars={"MY_VAR": "value"}
- ... )
- >>>
- >>> # Use the environment
- >>> result = env.reset()
- >>> print(result.observation)
- >>>
- >>> step_result = env.step(CodeAction(code="print('hello')"))
- >>> print(step_result.observation.stdout)
- >>>
- >>> # Cleanup (optional)
- >>> env.close()
- """
-
- # Use default provider if none provided
- if provider is None:
- provider = LocalDockerProvider()
-
- # 1. Start container with optional kwargs (e.g., env_vars, port)
- base_url = provider.start_container(image, **kwargs)
-
- # 2. Wait for server to be ready
- provider.wait_for_ready(base_url)
-
- # 3. Create and return client instance with provider reference
- return cls(base_url=base_url, provider=provider)
-
- @classmethod
- def from_hub(cls: Type[EnvClientT], repo_id: str, provider: Optional["ContainerProvider"] = None, **kwargs: Any) -> EnvClientT:
- """
- Create an environment client by pulling from a Hugging Face model hub.
- """
-
- if provider is None:
- provider = LocalDockerProvider()
-
- if "tag" in kwargs:
- tag = kwargs["tag"]
- else:
- tag = "latest"
-
- base_url = f"registry.hf.space/{repo_id.replace('/', '-')}:{tag}"
-
- return cls.from_docker_image(image=base_url, provider=provider)
-
- @abstractmethod
- def _step_payload(self, action: ActT) -> dict:
- """Convert an Action object to the JSON body expected by the env server."""
- raise NotImplementedError
-
- @abstractmethod
- def _parse_result(self, payload: dict) -> StepResult[ObsT]:
- """Convert a JSON response from the env server to StepResult[ObsT]."""
- raise NotImplementedError
-
- @abstractmethod
- def _parse_state(self, payload: dict) -> Any:
- """Convert a JSON response from the state endpoint to a State object."""
- raise NotImplementedError
-
- # ---------- Environment Server Interface Methods ----------
- def reset(self) -> StepResult[ObsT]:
- body: Dict[str, Any] = {}
- # TODO: later:
- # body["seed"] = seed
- # body["episode_id"] = episode_id
- r = self._http.post(
- f"{self._base}/reset",
- json=body,
- headers=self._headers,
- timeout=self._timeout,
- )
- r.raise_for_status()
- return self._parse_result(r.json())
-
- def step(self, action: ActT) -> StepResult[ObsT]:
- body: Dict[str, Any] = {
- "action": self._step_payload(action),
- "timeout_s": int(self._timeout),
- }
- # TODO: later:
- # body["request_id"] = str(uuid.uuid4())
- # body["episode_id"] = current_episode_id
- r = self._http.post(
- f"{self._base}/step",
- json=body,
- headers=self._headers,
- timeout=self._timeout,
- )
- r.raise_for_status()
- return self._parse_result(r.json())
-
- def state(self) -> Any:
- """
- Get the current environment state from the server.
-
- Returns:
- State object with environment state information (e.g., episode_id, step_count)
-
- Example:
- >>> client = EchoEnv.from_docker_image("echo-env:latest")
- >>> result = client.reset()
- >>> state = client.state()
- >>> print(state.episode_id)
- >>> print(state.step_count)
- """
- r = self._http.get(
- f"{self._base}/state",
- headers=self._headers,
- timeout=self._timeout,
- )
- r.raise_for_status()
- return self._parse_state(r.json())
-
- def close(self) -> None:
- """
- Close the environment and clean up resources.
-
- If this client was created via from_docker_image(), this will stop
- and remove the associated container.
- """
- if self._provider is not None:
- self._provider.stop_container()
+"""
+core/runner_env.py
+Minimal HTTP-based environment client.
+- Talks to a single env worker exposing: POST /reset, POST /step
+
+Future hooks (commented below) for:
+- episode_id, seed on reset
+- request_id on step
+- custom headers (auth/trace)
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Generic, Optional, Type, TYPE_CHECKING, TypeVar
+
+import requests
+
+from .client_types import StepResult
+from .containers.runtime import LocalDockerProvider
+
+if TYPE_CHECKING:
+ from .containers.runtime import ContainerProvider
+
+ActT = TypeVar("ActT")
+ObsT = TypeVar("ObsT")
+EnvClientT = TypeVar("EnvClientT", bound="HTTPEnvClient")
+
+
+class HTTPEnvClient(ABC, Generic[ActT, ObsT]):
+ def __init__(
+ self,
+ base_url: str,
+ request_timeout_s: float = 15.0,
+ default_headers: Optional[Dict[str, str]] = None,
+ provider: Optional["ContainerProvider"] = None,
+ ):
+ self._base = base_url.rstrip("/")
+ self._timeout = float(request_timeout_s)
+ self._http = requests.Session()
+ self._headers = default_headers or {}
+ self._provider = provider
+
+ @classmethod
+ def from_docker_image(
+ cls: Type[EnvClientT],
+ image: str,
+ provider: Optional["ContainerProvider"] = None,
+ **kwargs: Any,
+ ) -> EnvClientT:
+ """
+ Create an environment client by spinning up a Docker container locally.
+
+ This is a development utility that:
+ 1. Starts a Docker container from the specified image
+ 2. Waits for the server to be ready
+ 3. Creates and returns a client instance connected to the container
+
+ Note: The container lifecycle management is left to the user or higher-level
+ orchestration. The container will keep running until manually stopped.
+
+ Args:
+ image: Docker image name to run (e.g., "echo-env:latest")
+ provider: Container provider to use (defaults to LocalDockerProvider)
+ **kwargs: Additional arguments to pass to provider.start_container()
+ (e.g., env_vars, port)
+
+ Returns:
+ An instance of the client class connected to the running container
+
+ Example:
+ >>> from envs.coding_env.client import CodingEnv
+ >>> from envs.coding_env.models import CodeAction
+ >>>
+ >>> # Create environment from image
+ >>> env = CodingEnv.from_docker_image("coding-env:latest")
+ >>>
+ >>> # Create environment with custom env vars
+ >>> env = CodingEnv.from_docker_image(
+ ... "coding-env:latest",
+ ... env_vars={"MY_VAR": "value"}
+ ... )
+ >>>
+ >>> # Use the environment
+ >>> result = env.reset()
+ >>> print(result.observation)
+ >>>
+ >>> step_result = env.step(CodeAction(code="print('hello')"))
+ >>> print(step_result.observation.stdout)
+ >>>
+ >>> # Cleanup (optional)
+ >>> env.close()
+ """
+
+ # Use default provider if none provided
+ if provider is None:
+ provider = LocalDockerProvider()
+
+ # 1. Start container with optional kwargs (e.g., env_vars, port)
+ base_url = provider.start_container(image, **kwargs)
+
+ # 2. Wait for server to be ready
+ provider.wait_for_ready(base_url)
+
+ # 3. Create and return client instance with provider reference
+ return cls(base_url=base_url, provider=provider)
+
+ @classmethod
+ def from_hub(
+ cls: Type[EnvClientT],
+ repo_id: str,
+ provider: Optional["ContainerProvider"] = None,
+ **kwargs: Any,
+ ) -> EnvClientT:
+ """
+ Create an environment client by pulling from a Hugging Face model hub.
+ """
+
+ if provider is None:
+ provider = LocalDockerProvider()
+
+ if "tag" in kwargs:
+ tag = kwargs["tag"]
+ else:
+ tag = "latest"
+
+ base_url = f"registry.hf.space/{repo_id.replace('/', '-')}:{tag}"
+
+ return cls.from_docker_image(image=base_url, provider=provider)
+
+ @abstractmethod
+ def _step_payload(self, action: ActT) -> dict:
+ """Convert an Action object to the JSON body expected by the env server."""
+ raise NotImplementedError
+
+ @abstractmethod
+ def _parse_result(self, payload: dict) -> StepResult[ObsT]:
+ """Convert a JSON response from the env server to StepResult[ObsT]."""
+ raise NotImplementedError
+
+ @abstractmethod
+ def _parse_state(self, payload: dict) -> Any:
+ """Convert a JSON response from the state endpoint to a State object."""
+ raise NotImplementedError
+
+ # ---------- Environment Server Interface Methods ----------
+ def reset(self, **kwargs: Any) -> StepResult[ObsT]:
+ """
+ Reset the environment with optional parameters.
+
+ Args:
+ **kwargs: Optional parameters passed to the environment's reset method.
+ Common parameters include:
+ - seed: Random seed for reproducibility
+ - episode_id: Custom episode identifier
+ - Any environment-specific reset parameters
+
+ Returns:
+ StepResult containing initial observation
+
+ Example:
+ >>> env.reset(seed=42, episode_id="ep-001")
+ """
+ body: Dict[str, Any] = kwargs.copy()
+ r = self._http.post(
+ f"{self._base}/reset",
+ json=body,
+ headers=self._headers,
+ timeout=self._timeout,
+ )
+ r.raise_for_status()
+ return self._parse_result(r.json())
+
+ def step(self, action: ActT, **kwargs: Any) -> StepResult[ObsT]:
+ """
+ Execute an action in the environment with optional parameters.
+
+ Args:
+ action: The action to execute
+ **kwargs: Optional parameters passed to the environment's step method.
+ Common parameters include:
+ - timeout_s: Execution timeout in seconds
+ - request_id: Request identifier for tracking
+ - render: Whether to render the environment
+ - Any environment-specific step parameters
+
+ Returns:
+ StepResult containing observation, reward, and done status
+
+ Example:
+ >>> env.step(action, timeout_s=30.0, request_id="req-123", render=True)
+ """
+ body: Dict[str, Any] = {
+ "action": self._step_payload(action),
+ **kwargs # Forward all additional parameters
+ }
+ r = self._http.post(
+ f"{self._base}/step",
+ json=body,
+ headers=self._headers,
+ timeout=self._timeout,
+ )
+ r.raise_for_status()
+ return self._parse_result(r.json())
+
+ def state(self) -> Any:
+ """
+ Get the current environment state from the server.
+
+ Returns:
+ State object with environment state information (e.g., episode_id, step_count)
+
+ Example:
+ >>> client = EchoEnv.from_docker_image("echo-env:latest")
+ >>> result = client.reset()
+ >>> state = client.state()
+ >>> print(state.episode_id)
+ >>> print(state.step_count)
+ """
+ r = self._http.get(
+ f"{self._base}/state",
+ headers=self._headers,
+ timeout=self._timeout,
+ )
+ r.raise_for_status()
+ return self._parse_state(r.json())
+
+ def close(self) -> None:
+ """
+ Close the environment and clean up resources.
+
+ If this client was created via from_docker_image(), this will stop
+ and remove the associated container.
+ """
+ if self._provider is not None:
+ self._provider.stop_container()
diff --git a/src/core/tools/__init__.py b/src/openenv/core/tools/__init__.py
similarity index 100%
rename from src/core/tools/__init__.py
rename to src/openenv/core/tools/__init__.py
diff --git a/src/core/tools/git_server_client.py b/src/openenv/core/tools/git_server_client.py
similarity index 100%
rename from src/core/tools/git_server_client.py
rename to src/openenv/core/tools/git_server_client.py
diff --git a/src/core/tools/local_python_executor.py b/src/openenv/core/tools/local_python_executor.py
similarity index 99%
rename from src/core/tools/local_python_executor.py
rename to src/openenv/core/tools/local_python_executor.py
index 1ebcf6b6..b88d9c19 100644
--- a/src/core/tools/local_python_executor.py
+++ b/src/openenv/core/tools/local_python_executor.py
@@ -28,7 +28,7 @@
from smolagents import LocalPythonExecutor
-from core.env_server.types import CodeExecResult
+from openenv.core.env_server.types import CodeExecResult
logger = logging.getLogger(__name__)
logger.addHandler(logging.NullHandler())
diff --git a/src/openenv_core/__init__.py b/src/openenv_core/__init__.py
new file mode 100644
index 00000000..7ca80c62
--- /dev/null
+++ b/src/openenv_core/__init__.py
@@ -0,0 +1,49 @@
+"""
+Compatibility shim for the historical ``openenv_core`` package.
+
+The core runtime now lives under ``openenv.core``. Importing from the old
+package path will continue to work but emits a ``DeprecationWarning`` so
+downstream users can migrate at their own pace.
+"""
+
+from __future__ import annotations
+
+import importlib
+import sys
+import warnings
+from types import ModuleType
+from typing import Dict
+
+_TARGET_PREFIX = "openenv.core"
+_TARGET_MODULE = importlib.import_module(_TARGET_PREFIX)
+
+warnings.warn(
+ "openenv_core is deprecated; import from openenv.core instead.",
+ DeprecationWarning,
+ stacklevel=2,
+)
+
+__all__ = getattr(_TARGET_MODULE, "__all__", [])
+
+
+def __getattr__(name: str):
+ return getattr(_TARGET_MODULE, name)
+
+
+def __dir__():
+ return sorted(set(dir(_TARGET_MODULE)))
+
+
+def _alias(name: str) -> None:
+ target = f"{_TARGET_PREFIX}.{name}"
+ sys.modules[f"{__name__}.{name}"] = importlib.import_module(target)
+
+
+for _child in ("client_types", "containers", "env_server", "http_env_client", "tools"):
+ try:
+ _alias(_child)
+ except ModuleNotFoundError: # pragma: no cover - defensive
+ continue
+
+
+
diff --git a/src/pyproject.toml b/src/pyproject.toml
deleted file mode 100644
index 06723711..00000000
--- a/src/pyproject.toml
+++ /dev/null
@@ -1,61 +0,0 @@
-[build-system]
-requires = ["setuptools>=45", "wheel"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "openenv-core"
-version = "0.1.1"
-description = "Core components and cli for OpenEnv - HTTP-based agentic environments"
-readme = "./core/README.md"
-requires-python = ">=3.10"
-license = {text = "BSD-3-Clause"}
-authors = [
- {name = "Meta Platforms, Inc.", email = "opensource@meta.com"}
-]
-keywords = ["environment", "agent", "http", "docker", "fastapi"]
-
-dependencies = [
- "fastapi>=0.104.0",
- "pydantic>=2.0.0",
- "uvicorn[standard]>=0.24.0",
- "requests>=2.25.0",
- "typer>=0.12.0",
- "pyyaml>=6.0.0",
- "huggingface_hub>=0.24.0",
- "rich>=13.0.0",
- "tomli>=2.0.1",
- "tomli-w>=1.0.0",
-]
-
-[project.optional-dependencies]
-dev = [
- "pytest>=7.0.0",
- "black>=23.0.0",
- "ruff>=0.1.0",
- "mypy>=1.0.0",
-]
-
-[project.scripts]
-openenv = "openenv_cli.__main__:main"
-
-[project.urls]
-Homepage = "https://github.com/facebookresearch/OpenEnv"
-Repository = "https://github.com/facebookresearch/OpenEnv"
-Documentation = "https://github.com/facebookresearch/OpenEnv/blob/main/README.md"
-"Bug Tracker" = "https://github.com/facebookresearch/OpenEnv/issues"
-
-[tool.setuptools]
-package-dir = { "openenv_core" = "core", "openenv_cli" = "openenv_cli"}
-packages = [
- "openenv_core",
- "openenv_core.containers",
- "openenv_core.containers.runtime",
- "openenv_core.env_server",
- "openenv_core.tools",
- "openenv_cli",
- "openenv_cli.commands",
- "openenv_cli.templates"
-]
-
-[tool.setuptools.package-data]
-"openenv_cli" = ["templates/**/*"]
diff --git a/tests/test_cli/test_init.py b/tests/test_cli/test_init.py
index 47a7bbf6..99bb1db9 100644
--- a/tests/test_cli/test_init.py
+++ b/tests/test_cli/test_init.py
@@ -14,7 +14,7 @@
import typer
from typer.testing import CliRunner
-from openenv_cli.__main__ import app
+from openenv.cli.__main__ import app
runner = CliRunner()
@@ -361,7 +361,7 @@ def test_init_requirements_file(tmp_path: Path) -> None:
req_content = requirements.read_text()
assert "fastapi" in req_content
assert "uvicorn" in req_content
- assert "openenv-core>=0.1.0" in req_content
+ assert "openenv[core]>=0.2.0" in req_content
def test_init_validates_empty_env_name(tmp_path: Path) -> None:
diff --git a/tests/test_cli/test_main.py b/tests/test_cli/test_main.py
index 48945ad4..c763c423 100644
--- a/tests/test_cli/test_main.py
+++ b/tests/test_cli/test_main.py
@@ -12,7 +12,7 @@
import pytest
from typer.testing import CliRunner
-from openenv_cli.__main__ import app, main
+from openenv.cli.__main__ import app, main
runner = CliRunner()
@@ -20,7 +20,7 @@
def test_main_handles_keyboard_interrupt() -> None:
"""Test that main handles KeyboardInterrupt gracefully."""
- with patch("openenv_cli.__main__.app") as mock_app:
+ with patch("openenv.cli.__main__.app") as mock_app:
mock_app.side_effect = KeyboardInterrupt()
with pytest.raises(SystemExit) as exc_info:
@@ -31,7 +31,7 @@ def test_main_handles_keyboard_interrupt() -> None:
def test_main_handles_generic_exception() -> None:
"""Test that main handles generic exceptions gracefully."""
- with patch("openenv_cli.__main__.app") as mock_app:
+ with patch("openenv.cli.__main__.app") as mock_app:
mock_app.side_effect = ValueError("Test error")
with pytest.raises(SystemExit) as exc_info:
@@ -44,7 +44,7 @@ def test_main_entry_point() -> None:
"""Test that main() can be called as entry point."""
# This tests the if __name__ == "__main__" block indirectly
# by ensuring main() function works
- with patch("openenv_cli.__main__.app") as mock_app:
+ with patch("openenv.cli.__main__.app") as mock_app:
main()
mock_app.assert_called_once()
diff --git a/tests/test_cli/test_push.py b/tests/test_cli/test_push.py
index 70b62817..c4808b7b 100644
--- a/tests/test_cli/test_push.py
+++ b/tests/test_cli/test_push.py
@@ -15,7 +15,7 @@
import typer
from typer.testing import CliRunner
-from openenv_cli.__main__ import app
+from openenv.cli.__main__ import app
runner = CliRunner()
@@ -109,9 +109,9 @@ def test_push_authenticates_with_hf(tmp_path: Path) -> None:
"""Test that push ensures Hugging Face authentication."""
_create_test_openenv_env(tmp_path)
- with patch("openenv_cli.commands.push.whoami") as mock_whoami, \
- patch("openenv_cli.commands.push.login") as mock_login, \
- patch("openenv_cli.commands.push.HfApi") as mock_hf_api_class:
+ with patch("openenv.cli.commands.push.whoami") as mock_whoami, \
+ patch("openenv.cli.commands.push.login") as mock_login, \
+ patch("openenv.cli.commands.push.HfApi") as mock_hf_api_class:
# Mock whoami to return user info
mock_whoami.return_value = {"name": "testuser"}
@@ -136,9 +136,9 @@ def test_push_enables_web_interface_in_dockerfile(tmp_path: Path) -> None:
"""Test that push enables web interface in Dockerfile."""
_create_test_openenv_env(tmp_path)
- with patch("openenv_cli.commands.push.whoami") as mock_whoami, \
- patch("openenv_cli.commands.push.login") as mock_login, \
- patch("openenv_cli.commands.push.HfApi") as mock_hf_api_class:
+ with patch("openenv.cli.commands.push.whoami") as mock_whoami, \
+ patch("openenv.cli.commands.push.login") as mock_login, \
+ patch("openenv.cli.commands.push.HfApi") as mock_hf_api_class:
mock_whoami.return_value = {"name": "testuser"}
mock_login.return_value = None # Prevent actual login prompt
@@ -171,9 +171,9 @@ def test_push_updates_readme_frontmatter(tmp_path: Path) -> None:
"""
(tmp_path / "README.md").write_text(readme_content)
- with patch("openenv_cli.commands.push.whoami") as mock_whoami, \
- patch("openenv_cli.commands.push.login") as mock_login, \
- patch("openenv_cli.commands.push.HfApi") as mock_hf_api_class:
+ with patch("openenv.cli.commands.push.whoami") as mock_whoami, \
+ patch("openenv.cli.commands.push.login") as mock_login, \
+ patch("openenv.cli.commands.push.HfApi") as mock_hf_api_class:
mock_whoami.return_value = {"name": "testuser"}
mock_login.return_value = None # Prevent actual login prompt
@@ -195,9 +195,9 @@ def test_push_uses_repo_id_option(tmp_path: Path) -> None:
"""Test that push respects --repo-id option."""
_create_test_openenv_env(tmp_path)
- with patch("openenv_cli.commands.push.whoami") as mock_whoami, \
- patch("openenv_cli.commands.push.login") as mock_login, \
- patch("openenv_cli.commands.push.HfApi") as mock_hf_api_class:
+ with patch("openenv.cli.commands.push.whoami") as mock_whoami, \
+ patch("openenv.cli.commands.push.login") as mock_login, \
+ patch("openenv.cli.commands.push.HfApi") as mock_hf_api_class:
mock_whoami.return_value = {"name": "testuser"}
mock_login.return_value = None # Prevent actual login prompt
@@ -221,9 +221,9 @@ def test_push_uses_default_repo_id(tmp_path: Path) -> None:
"""Test that push uses default repo-id from username and env name."""
_create_test_openenv_env(tmp_path, env_name="test_env")
- with patch("openenv_cli.commands.push.whoami") as mock_whoami, \
- patch("openenv_cli.commands.push.login") as mock_login, \
- patch("openenv_cli.commands.push.HfApi") as mock_hf_api_class:
+ with patch("openenv.cli.commands.push.whoami") as mock_whoami, \
+ patch("openenv.cli.commands.push.login") as mock_login, \
+ patch("openenv.cli.commands.push.HfApi") as mock_hf_api_class:
mock_whoami.return_value = {"name": "testuser"}
mock_login.return_value = None # Prevent actual login prompt
@@ -247,9 +247,9 @@ def test_push_uses_private_option(tmp_path: Path) -> None:
"""Test that push respects --private option."""
_create_test_openenv_env(tmp_path)
- with patch("openenv_cli.commands.push.whoami") as mock_whoami, \
- patch("openenv_cli.commands.push.login") as mock_login, \
- patch("openenv_cli.commands.push.HfApi") as mock_hf_api_class:
+ with patch("openenv.cli.commands.push.whoami") as mock_whoami, \
+ patch("openenv.cli.commands.push.login") as mock_login, \
+ patch("openenv.cli.commands.push.HfApi") as mock_hf_api_class:
mock_whoami.return_value = {"name": "testuser"}
mock_login.return_value = None # Prevent actual login prompt
@@ -273,9 +273,9 @@ def test_push_uses_base_image_option(tmp_path: Path) -> None:
"""Test that push respects --base-image option."""
_create_test_openenv_env(tmp_path)
- with patch("openenv_cli.commands.push.whoami") as mock_whoami, \
- patch("openenv_cli.commands.push.login") as mock_login, \
- patch("openenv_cli.commands.push.HfApi") as mock_hf_api_class:
+ with patch("openenv.cli.commands.push.whoami") as mock_whoami, \
+ patch("openenv.cli.commands.push.login") as mock_login, \
+ patch("openenv.cli.commands.push.HfApi") as mock_hf_api_class:
mock_whoami.return_value = {"name": "testuser"}
mock_login.return_value = None # Prevent actual login prompt
@@ -299,9 +299,9 @@ def test_push_uses_directory_option(tmp_path: Path) -> None:
env_dir.mkdir()
_create_test_openenv_env(env_dir)
- with patch("openenv_cli.commands.push.whoami") as mock_whoami, \
- patch("openenv_cli.commands.push.login") as mock_login, \
- patch("openenv_cli.commands.push.HfApi") as mock_hf_api_class:
+ with patch("openenv.cli.commands.push.whoami") as mock_whoami, \
+ patch("openenv.cli.commands.push.login") as mock_login, \
+ patch("openenv.cli.commands.push.HfApi") as mock_hf_api_class:
mock_whoami.return_value = {"name": "testuser"}
mock_login.return_value = None # Prevent actual login prompt
@@ -323,9 +323,9 @@ def test_push_handles_missing_dockerfile(tmp_path: Path) -> None:
# Remove Dockerfile
(tmp_path / "server" / "Dockerfile").unlink()
- with patch("openenv_cli.commands.push.whoami") as mock_whoami, \
- patch("openenv_cli.commands.push.login") as mock_login, \
- patch("openenv_cli.commands.push.HfApi") as mock_hf_api_class:
+ with patch("openenv.cli.commands.push.whoami") as mock_whoami, \
+ patch("openenv.cli.commands.push.login") as mock_login, \
+ patch("openenv.cli.commands.push.HfApi") as mock_hf_api_class:
mock_whoami.return_value = {"name": "testuser"}
mock_login.return_value = None # Prevent actual login prompt
@@ -350,9 +350,9 @@ def test_push_handles_missing_readme(tmp_path: Path) -> None:
# Remove README
(tmp_path / "README.md").unlink()
- with patch("openenv_cli.commands.push.whoami") as mock_whoami, \
- patch("openenv_cli.commands.push.login") as mock_login, \
- patch("openenv_cli.commands.push.HfApi") as mock_hf_api_class:
+ with patch("openenv.cli.commands.push.whoami") as mock_whoami, \
+ patch("openenv.cli.commands.push.login") as mock_login, \
+ patch("openenv.cli.commands.push.HfApi") as mock_hf_api_class:
mock_whoami.return_value = {"name": "testuser"}
mock_login.return_value = None # Prevent actual login prompt
@@ -375,9 +375,9 @@ def test_push_initializes_hf_api_without_token(tmp_path: Path) -> None:
"""Test that push initializes HfApi without token parameter."""
_create_test_openenv_env(tmp_path)
- with patch("openenv_cli.commands.push.whoami") as mock_whoami, \
- patch("openenv_cli.commands.push.login") as mock_login, \
- patch("openenv_cli.commands.push.HfApi") as mock_hf_api_class:
+ with patch("openenv.cli.commands.push.whoami") as mock_whoami, \
+ patch("openenv.cli.commands.push.login") as mock_login, \
+ patch("openenv.cli.commands.push.HfApi") as mock_hf_api_class:
mock_whoami.return_value = {"name": "testuser"}
mock_login.return_value = None # Prevent actual login prompt
@@ -402,9 +402,9 @@ def test_push_validates_repo_id_format(tmp_path: Path) -> None:
"""Test that push validates repo-id format."""
_create_test_openenv_env(tmp_path)
- with patch("openenv_cli.commands.push.whoami") as mock_whoami, \
- patch("openenv_cli.commands.push.login") as mock_login, \
- patch("openenv_cli.commands.push.HfApi") as mock_hf_api_class:
+ with patch("openenv.cli.commands.push.whoami") as mock_whoami, \
+ patch("openenv.cli.commands.push.login") as mock_login, \
+ patch("openenv.cli.commands.push.HfApi") as mock_hf_api_class:
mock_whoami.return_value = {"name": "testuser"}
mock_login.return_value = None # Prevent actual login prompt
@@ -451,9 +451,9 @@ class MockUser:
def __init__(self):
self.name = "testuser"
- with patch("openenv_cli.commands.push.whoami") as mock_whoami, \
- patch("openenv_cli.commands.push.login") as mock_login, \
- patch("openenv_cli.commands.push.HfApi") as mock_hf_api_class:
+ with patch("openenv.cli.commands.push.whoami") as mock_whoami, \
+ patch("openenv.cli.commands.push.login") as mock_login, \
+ patch("openenv.cli.commands.push.HfApi") as mock_hf_api_class:
mock_whoami.return_value = MockUser()
mock_login.return_value = None # Prevent actual login prompt
@@ -475,9 +475,9 @@ def test_push_handles_authentication_failure(tmp_path: Path) -> None:
"""Test that push handles authentication failure."""
_create_test_openenv_env(tmp_path)
- with patch("openenv_cli.commands.push.whoami") as mock_whoami, \
- patch("openenv_cli.commands.push.login") as mock_login, \
- patch("openenv_cli.commands.push.HfApi") as mock_hf_api_class:
+ with patch("openenv.cli.commands.push.whoami") as mock_whoami, \
+ patch("openenv.cli.commands.push.login") as mock_login, \
+ patch("openenv.cli.commands.push.HfApi") as mock_hf_api_class:
# First whoami call fails (not authenticated)
# Login also fails
@@ -502,9 +502,9 @@ def test_push_handles_whoami_missing_username(tmp_path: Path) -> None:
"""Test that push handles whoami response without username."""
_create_test_openenv_env(tmp_path)
- with patch("openenv_cli.commands.push.whoami") as mock_whoami, \
- patch("openenv_cli.commands.push.login") as mock_login, \
- patch("openenv_cli.commands.push.HfApi") as mock_hf_api_class:
+ with patch("openenv.cli.commands.push.whoami") as mock_whoami, \
+ patch("openenv.cli.commands.push.login") as mock_login, \
+ patch("openenv.cli.commands.push.HfApi") as mock_hf_api_class:
# Return dict without name, fullname, or username
mock_whoami.return_value = {}
@@ -532,9 +532,9 @@ def test_push_handles_readme_without_frontmatter(tmp_path: Path) -> None:
# Create README without frontmatter
(tmp_path / "README.md").write_text("# Test Environment\nNo frontmatter here.\n")
- with patch("openenv_cli.commands.push.whoami") as mock_whoami, \
- patch("openenv_cli.commands.push.login") as mock_login, \
- patch("openenv_cli.commands.push.HfApi") as mock_hf_api_class:
+ with patch("openenv.cli.commands.push.whoami") as mock_whoami, \
+ patch("openenv.cli.commands.push.login") as mock_login, \
+ patch("openenv.cli.commands.push.HfApi") as mock_hf_api_class:
mock_whoami.return_value = {"name": "testuser"}
mock_login.return_value = None # Prevent actual login prompt
@@ -556,9 +556,9 @@ def test_push_handles_hf_api_create_repo_error(tmp_path: Path) -> None:
"""Test that push handles HF API create_repo error."""
_create_test_openenv_env(tmp_path)
- with patch("openenv_cli.commands.push.whoami") as mock_whoami, \
- patch("openenv_cli.commands.push.login") as mock_login, \
- patch("openenv_cli.commands.push.HfApi") as mock_hf_api_class:
+ with patch("openenv.cli.commands.push.whoami") as mock_whoami, \
+ patch("openenv.cli.commands.push.login") as mock_login, \
+ patch("openenv.cli.commands.push.HfApi") as mock_hf_api_class:
mock_whoami.return_value = {"name": "testuser"}
mock_login.return_value = None # Prevent actual login prompt
@@ -582,9 +582,9 @@ def test_push_handles_hf_api_upload_error(tmp_path: Path) -> None:
"""Test that push handles HF API upload_folder error."""
_create_test_openenv_env(tmp_path)
- with patch("openenv_cli.commands.push.whoami") as mock_whoami, \
- patch("openenv_cli.commands.push.login") as mock_login, \
- patch("openenv_cli.commands.push.HfApi") as mock_hf_api_class:
+ with patch("openenv.cli.commands.push.whoami") as mock_whoami, \
+ patch("openenv.cli.commands.push.login") as mock_login, \
+ patch("openenv.cli.commands.push.HfApi") as mock_hf_api_class:
mock_whoami.return_value = {"name": "testuser"}
mock_login.return_value = None # Prevent actual login prompt
@@ -610,9 +610,9 @@ def test_push_handles_base_image_not_found_in_dockerfile(tmp_path: Path) -> None
# Create Dockerfile without FROM line
(tmp_path / "server" / "Dockerfile").write_text("RUN echo 'test'\nCMD [\"echo\", \"test\"]\n")
- with patch("openenv_cli.commands.push.whoami") as mock_whoami, \
- patch("openenv_cli.commands.push.login") as mock_login, \
- patch("openenv_cli.commands.push.HfApi") as mock_hf_api_class:
+ with patch("openenv.cli.commands.push.whoami") as mock_whoami, \
+ patch("openenv.cli.commands.push.login") as mock_login, \
+ patch("openenv.cli.commands.push.HfApi") as mock_hf_api_class:
mock_whoami.return_value = {"name": "testuser"}
mock_login.return_value = None # Prevent actual login prompt
+ 
