Standardize Environment Directory Structure #145

.gitignore

@@ -95,3 +95,17 @@ Desktop.ini
 *claude*
 *Claude*
 *CLAUDE*
+
+# OpenEnv-specific
+# Environment outputs (logs, evaluations, etc.)
+**/outputs/
+outputs/
+
+# Generated requirements files from pyproject.toml
+**/server/requirements.txt.generated
+
+# UV root lock file (env lock files should be committed)
+/uv.lock
+.uv/
+
+*.backup*/

README.md

@@ -134,12 +134,44 @@ my_env/
 ├── client.py             # Implement YourEnv(HTTPEnvClient)
 ├── README.md             # Document your environment
 ├── openenv.yaml          # Environment manifest
+├── pyproject.toml        # Dependencies and package configuration
+├── outputs/              # Runtime outputs (logs, evals) - gitignored
+│   ├── logs/
+│   └── evals/
 └── server/
     ├── your_environment.py  # Implement YourEnvironment(Environment)
     ├── app.py               # Create FastAPI app
+    ├── requirements.txt     # Dependencies for Docker (can be generated)
     └── Dockerfile           # Define container image
 ```
 
+#### Dependency Management
+
+OpenEnv uses `pyproject.toml` as the primary dependency specification:
+
+- **Environment-level `pyproject.toml`**: Each environment defines its own dependencies
+- **Root-level `pyproject.toml`**: Contains shared core dependencies (fastapi, pydantic, uvicorn)
+- **Server `requirements.txt`**: Can be auto-generated from `pyproject.toml` for Docker builds
+
+**Development Workflow:**
+
+```bash
+# Install environment in editable mode
+pip install -e ./my_env
+
+# Or using uv (faster)
+uv pip install -e ./my_env
+
+# Run server locally without Docker
+uv run --project ./my_env server --host 0.0.0.0 --port 8000
+```
+
+**Benefits:**
+- ✅ **Client-side extensions**: Modify client classes locally without repo changes
+- ✅ **Better dependency management**: Clear separation between environments
+- ✅ **Flexible workflows**: Use pip, uv, or Docker for different scenarios
+- ✅ **CI/CD ready**: Automated dependency generation and validation
+
 See [`src/envs/README.md`](src/envs/README.md) for a complete guide on building environments.
 
 ### For Environment Users

pyproject.toml

@@ -4,19 +4,21 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "openenv"
-version = "0.1.0"
+version = "0.1.1"
+description = "A unified framework for reinforcement learning environments"
+readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
-    "torch>=1.9.0",
-    "numpy>=1.19.0",
-    "requests>=2.25.0",
+    # Core shared dependencies across all environments
     "fastapi>=0.104.0",
+    "pydantic>=2.0.0",
     "uvicorn>=0.24.0",
-    "smolagents>=1.22.0,<2",
+    "requests>=2.25.0",
+    # CLI dependencies
     "typer>=0.9.0",
     "rich>=13.0.0",
     "pyyaml>=6.0",
-    "huggingface_hub>=0.20.0"
+    "huggingface_hub>=0.20.0",
 ]
 
 [project.scripts]

src/core/containers/images/Dockerfile

@@ -8,38 +8,52 @@
 # OpenEnv Base Image
 #
 # This is the standard base image for all OpenEnv environment servers.
-# It includes the minimal dependencies needed to run HTTP environment servers.
+# It includes the minimal dependencies needed to run HTTP environment servers
+# and uv for fast dependency management.
 #
-# Build: docker build -t openenv-base:latest -f src/core/containers/images/Dockerfile .
-# Tag:   docker tag openenv-base:latest openenv-base:0.1.0
+# Build from repo root: docker build -t openenv-base:latest -f src/core/containers/images/Dockerfile .
+# Tag:   docker tag openenv-base:latest openenv-base:0.2.0
 #
 
+FROM ghcr.io/astral-sh/uv:0.5.27-python3.11-bookworm-slim AS builder
+
+# Set working directory
+WORKDIR /app
+
+# Copy core pyproject.toml and lockfile for dependency installation
+COPY src/core/pyproject.toml src/core/uv.lock* ./
+
+# Install core dependencies using uv with cache mount
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv pip install --system -r pyproject.toml
+
+# Final runtime stage
 FROM python:3.11-slim
 
 # Set metadata
 LABEL maintainer="OpenEnv Team"
-LABEL description="Base image for OpenEnv based environment servers"
-LABEL version="0.1.0"
+LABEL description="Base image for OpenEnv based environment servers with uv"
+LABEL version="0.2.0"
 
 # Install system dependencies
 RUN apt-get update && apt-get install -y --no-install-recommends \
     curl \
+    ca-certificates \
     && rm -rf /var/lib/apt/lists/*
 
-# Install Python dependencies that all environments need
-RUN pip install --no-cache-dir \
-    "fastapi>=0.104.0" \
-    "uvicorn[standard]>=0.24.0" \
-    "requests>=2.25.0" \
-    "wsproto>=1.0.0" \
-    smolagents
+# Copy uv from builder
+COPY --from=builder /usr/local/bin/uv /usr/local/bin/uvx /usr/local/bin/
+
+# Copy installed Python packages from builder
+COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
 
 # Set working directory
 WORKDIR /app
 
 # Default environment variables
 ENV PYTHONPATH=/app/src
 ENV PYTHONUNBUFFERED=1
+ENV UV_SYSTEM_PYTHON=1
 
 # Default expose port (can be overridden)
 EXPOSE 8000

src/core/pyproject.toml

@@ -7,17 +7,18 @@ name = "openenv-core"
 version = "0.1.0"
 description = "Core components for OpenEnv - HTTP-based agentic environments"
 readme = "README.md"
-requires-python = ">=3.8"
+requires-python = ">=3.10"
 license = {text = "BSD-3-Clause"}
 authors = [
     {name = "Meta Platforms, Inc.", email = "[email protected]"}
 ]
 keywords = ["environment", "agent", "http", "docker", "fastapi"]
 
 dependencies = [
-    "requests>=2.25.0",
     "fastapi>=0.104.0",
-    "uvicorn>=0.24.0",
+    "pydantic>=2.0.0",
+    "uvicorn[standard]>=0.24.0",
+    "requests>=2.25.0",
 ]
 
 [project.optional-dependencies]