openenv-core 0.1.0__tar.gz

openenv_core-0.1.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: openenv-core
+Version: 0.1.0
+Summary: Core components for OpenEnv - HTTP-based agentic environments
+Author-email: "Meta Platforms, Inc." <opensource@meta.com>
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/facebookresearch/OpenEnv
+Project-URL: Repository, https://github.com/facebookresearch/OpenEnv
+Project-URL: Documentation, https://github.com/facebookresearch/OpenEnv/blob/main/README.md
+Project-URL: Bug Tracker, https://github.com/facebookresearch/OpenEnv/issues
+Keywords: environment,agent,http,docker,fastapi
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Requires-Dist: fastapi>=0.104.0
+Requires-Dist: uvicorn>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+
+# OpenEnv Core
+
+Core components for OpenEnv - a framework for building HTTP-based agentic environments.
+
+## 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.
+
+## Features
+
+- **HTTPEnvClient**: Generic HTTP client for interacting with remote environments
+- **HTTPEnvServer**: FastAPI-based server wrapper for exposing environments over HTTP
+- **Container Providers**: Pluggable architecture for running containers (Docker, Kubernetes, etc.)
+- **Type System**: Strongly-typed Action/Observation/State interfaces
+- **Web Interface**: Optional web UI for interacting with environments
+
+## Installation
+
+```bash
+pip install openenv-core
+```
+
+For development:
+```bash
+pip install openenv-core[dev]
+```
+
+## Quick Start
+
+### Creating an Environment Client
+
+```python
+from openenv_core import HTTPEnvClient, StepResult
+from dataclasses import dataclass
+
+@dataclass
+class MyAction:
+    text: str
+
+@dataclass
+class MyObservation:
+    response: str
+
+class MyEnvClient(HTTPEnvClient[MyAction, MyObservation]):
+    def _step_payload(self, action: MyAction) -> dict:
+        return {"text": action.text}
+
+    def _parse_result(self, payload: dict) -> StepResult[MyObservation]:
+        obs_data = payload["observation"]
+        return StepResult(
+            observation=MyObservation(**obs_data),
+            reward=payload.get("reward"),
+            done=payload.get("done", False)
+        )
+
+    def _parse_state(self, payload: dict) -> Any:
+        return payload
+
+# Use with Docker
+env = MyEnvClient.from_docker_image("my-env:latest")
+result = env.reset()
+step_result = env.step(MyAction(text="hello"))
+env.close()
+```
+
+### Creating an Environment Server
+
+```python
+from openenv_core.env_server import Environment, HTTPEnvServer, create_app
+from dataclasses import dataclass
+
+@dataclass
+class MyAction:
+    text: str
+
+@dataclass
+class MyObservation:
+    response: str
+    reward: float = 0.0
+    done: bool = False
+
+class MyEnvironment(Environment):
+    def reset(self) -> MyObservation:
+        return MyObservation(response="Ready")
+
+    def step(self, action: MyAction) -> MyObservation:
+        return MyObservation(
+            response=f"Echo: {action.text}",
+            reward=1.0,
+            done=False
+        )
+
+# Create FastAPI app
+env = MyEnvironment()
+app = create_app(env, MyAction, MyObservation)
+
+# Run with: uvicorn module:app --host 0.0.0.0 --port 8000
+```
+
+## Container Providers
+
+OpenEnv Core supports multiple container providers:
+
+### Local Docker Provider
+
+```python
+from openenv_core.containers.runtime import LocalDockerProvider
+
+provider = LocalDockerProvider()
+base_url = provider.start_container("my-env:latest")
+provider.wait_for_ready(base_url)
+# Use environment...
+provider.stop_container()
+```
+
+### Kubernetes Provider (Coming Soon)
+
+```python
+from openenv_core.containers.runtime import KubernetesProvider
+
+provider = KubernetesProvider(namespace="envs")
+base_url = provider.start_container("my-env:latest")
+# Use environment...
+provider.stop_container()
+```
+
+## Architecture
+
+OpenEnv Core follows a client-server architecture:
+
+```
+┌─────────────────┐         HTTP          ┌─────────────────┐
+│                 │◄─────────────────────►│                 │
+│  HTTPEnvClient  │   /reset, /step       │  HTTPEnvServer  │
+│                 │   /state, /health     │                 │
+└─────────────────┘                       └─────────────────┘
+        │                                          │
+        │                                          │
+        ▼                                          ▼
+┌─────────────────┐                       ┌─────────────────┐
+│ Container       │                       │  Environment    │
+│ Provider        │                       │  Implementation │
+└─────────────────┘                       └─────────────────┘
+```
+
+## API Reference
+
+### HTTPEnvClient
+
+Base class for environment clients with these abstract methods:
+
+- `_step_payload(action)`: Convert action to JSON
+- `_parse_result(payload)`: Parse response to StepResult
+- `_parse_state(payload)`: Parse state response
+
+### HTTPEnvServer
+
+Server wrapper with these methods:
+
+- `register_routes(app)`: Register endpoints on FastAPI app
+- `_deserialize_action(data)`: Convert JSON to Action
+- `_serialize_observation(obs)`: Convert Observation to JSON
+
+### Environment Interface
+
+Base interface for environment implementations:
+
+- `reset()`: Reset environment and return initial observation
+- `step(action)`: Execute action and return observation
+- `state`: Property returning current environment state
+
+## License
+
+This project is licensed under the BSD-3-Clause License - see the LICENSE file for details.
+
+## Contributing
+
+Contributions are welcome! Please see the main OpenEnv repository for contribution guidelines.
+
+## Links
+
+- **Homepage**: https://github.com/facebookresearch/OpenEnv
+- **Documentation**: https://github.com/facebookresearch/OpenEnv/blob/main/README.md
+- **Bug Tracker**: https://github.com/facebookresearch/OpenEnv/issues

openenv_core-0.1.0/README.md

@@ -0,0 +1,184 @@
+# OpenEnv Core
+
+Core components for OpenEnv - a framework for building HTTP-based agentic environments.
+
+## 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.
+
+## Features
+
+- **HTTPEnvClient**: Generic HTTP client for interacting with remote environments
+- **HTTPEnvServer**: FastAPI-based server wrapper for exposing environments over HTTP
+- **Container Providers**: Pluggable architecture for running containers (Docker, Kubernetes, etc.)
+- **Type System**: Strongly-typed Action/Observation/State interfaces
+- **Web Interface**: Optional web UI for interacting with environments
+
+## Installation
+
+```bash
+pip install openenv-core
+```
+
+For development:
+```bash
+pip install openenv-core[dev]
+```
+
+## Quick Start
+
+### Creating an Environment Client
+
+```python
+from openenv_core import HTTPEnvClient, StepResult
+from dataclasses import dataclass
+
+@dataclass
+class MyAction:
+    text: str
+
+@dataclass
+class MyObservation:
+    response: str
+
+class MyEnvClient(HTTPEnvClient[MyAction, MyObservation]):
+    def _step_payload(self, action: MyAction) -> dict:
+        return {"text": action.text}
+
+    def _parse_result(self, payload: dict) -> StepResult[MyObservation]:
+        obs_data = payload["observation"]
+        return StepResult(
+            observation=MyObservation(**obs_data),
+            reward=payload.get("reward"),
+            done=payload.get("done", False)
+        )
+
+    def _parse_state(self, payload: dict) -> Any:
+        return payload
+
+# Use with Docker
+env = MyEnvClient.from_docker_image("my-env:latest")
+result = env.reset()
+step_result = env.step(MyAction(text="hello"))
+env.close()
+```
+
+### Creating an Environment Server
+
+```python
+from openenv_core.env_server import Environment, HTTPEnvServer, create_app
+from dataclasses import dataclass
+
+@dataclass
+class MyAction:
+    text: str
+
+@dataclass
+class MyObservation:
+    response: str
+    reward: float = 0.0
+    done: bool = False
+
+class MyEnvironment(Environment):
+    def reset(self) -> MyObservation:
+        return MyObservation(response="Ready")
+
+    def step(self, action: MyAction) -> MyObservation:
+        return MyObservation(
+            response=f"Echo: {action.text}",
+            reward=1.0,
+            done=False
+        )
+
+# Create FastAPI app
+env = MyEnvironment()
+app = create_app(env, MyAction, MyObservation)
+
+# Run with: uvicorn module:app --host 0.0.0.0 --port 8000
+```
+
+## Container Providers
+
+OpenEnv Core supports multiple container providers:
+
+### Local Docker Provider
+
+```python
+from openenv_core.containers.runtime import LocalDockerProvider
+
+provider = LocalDockerProvider()
+base_url = provider.start_container("my-env:latest")
+provider.wait_for_ready(base_url)
+# Use environment...
+provider.stop_container()
+```
+
+### Kubernetes Provider (Coming Soon)
+
+```python
+from openenv_core.containers.runtime import KubernetesProvider
+
+provider = KubernetesProvider(namespace="envs")
+base_url = provider.start_container("my-env:latest")
+# Use environment...
+provider.stop_container()
+```
+
+## Architecture
+
+OpenEnv Core follows a client-server architecture:
+
+```
+┌─────────────────┐         HTTP          ┌─────────────────┐
+│                 │◄─────────────────────►│                 │
+│  HTTPEnvClient  │   /reset, /step       │  HTTPEnvServer  │
+│                 │   /state, /health     │                 │
+└─────────────────┘                       └─────────────────┘
+        │                                          │
+        │                                          │
+        ▼                                          ▼
+┌─────────────────┐                       ┌─────────────────┐
+│ Container       │                       │  Environment    │
+│ Provider        │                       │  Implementation │
+└─────────────────┘                       └─────────────────┘
+```
+
+## API Reference
+
+### HTTPEnvClient
+
+Base class for environment clients with these abstract methods:
+
+- `_step_payload(action)`: Convert action to JSON
+- `_parse_result(payload)`: Parse response to StepResult
+- `_parse_state(payload)`: Parse state response
+
+### HTTPEnvServer
+
+Server wrapper with these methods:
+
+- `register_routes(app)`: Register endpoints on FastAPI app
+- `_deserialize_action(data)`: Convert JSON to Action
+- `_serialize_observation(obs)`: Convert Observation to JSON
+
+### Environment Interface
+
+Base interface for environment implementations:
+
+- `reset()`: Reset environment and return initial observation
+- `step(action)`: Execute action and return observation
+- `state`: Property returning current environment state
+
+## License
+
+This project is licensed under the BSD-3-Clause License - see the LICENSE file for details.
+
+## Contributing
+
+Contributions are welcome! Please see the main OpenEnv repository for contribution guidelines.
+
+## Links
+
+- **Homepage**: https://github.com/facebookresearch/OpenEnv
+- **Documentation**: https://github.com/facebookresearch/OpenEnv/blob/main/README.md
+- **Bug Tracker**: https://github.com/facebookresearch/OpenEnv/issues

openenv_core-0.1.0/__init__.py

@@ -0,0 +1,19 @@
+# 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.
+
+"""Core components for agentic environments."""
+
+# Re-export main components from submodules for convenience
+from .env_server import *
+from .client_types import StepResult
+from .http_env_client import HTTPEnvClient
+
+# Note: MCP module doesn't export anything yet
+
+__all__ = [
+    "HTTPEnvClient",
+    "StepResult",
+]

openenv_core-0.1.0/client_types.py

@@ -0,0 +1,22 @@
+# Type definitions for EnvTorch
+from dataclasses import dataclass
+from typing import Any, Generic, Optional, TypeVar
+
+# Generic type for observations
+ObsT = TypeVar("ObsT")  # TypeVar for typehinting in IDEs
+
+
+@dataclass
+class StepResult(Generic[ObsT]):
+    """
+    Represents the result of one environment step.
+
+    Attributes:
+        observation: The environment's observation after the action.
+        reward: Scalar reward for this step (optional).
+        done: Whether the episode is finished.
+    """
+
+    observation: ObsT
+    reward: Optional[float] = None
+    done: bool = False

openenv_core-0.1.0/containers/__init__.py

@@ -0,0 +1,7 @@
+# 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.
+
+"""Container management for environment servers."""

openenv_core-0.1.0/containers/runtime/__init__.py

@@ -0,0 +1,15 @@
+# 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.
+
+"""Container runtime providers."""
+
+from .providers import ContainerProvider, KubernetesProvider, LocalDockerProvider
+
+__all__ = [
+    "ContainerProvider",
+    "LocalDockerProvider",
+    "KubernetesProvider",
+]