Standardize Environment Directory Structure

[rycerzes]

This proposal aims to standardize directory and dependency management across all environments in OpenEnv, following patterns from prime-environments, while keeping the current client/server + Docker model.

Goal

Establish a consistent, modular structure with pyproject.toml as the single source of truth for dependencies, improving CI/CD and maintainability.

Current Issues

• Some environments lack a requirements.txt
• Dependencies are often hardcoded in Dockerfiles
• Root and environment-level dependencies are mixed
  Example (current):

src/envs/{env_name}_env/
├── __init__.py
├── client.py
├── models.py
├── README.md
└── server/
    ├── app.py
    ├── Dockerfile  # installs deps inline
    ├── requirements.txt  # sometimes missing
    └── {env_name}_environment.py

Proposed

src/envs/{env_name}_env/
├── pyproject.toml           # dependencies here
├── README.md
├── __init__.py
├── client.py
├── models.py
├── outputs/                 # logs/evals (gitignored)
├── server/
│   ├── app.py
│   ├── Dockerfile
│   └── {env_name}_environment.py
└── [optional] utils/, rewards.py, build_docker.sh

Root:

OpenEnv/
├── pyproject.toml
├── uv.lock
└── src/envs/

Key Points

• Each environment maintains its own pyproject.toml
• requirements.txt is generated automatically during CI/Docker builds
• Docker images install from the generated file, not inline
• Standard outputs/ directory for logs/evals
• Shared dev deps live in the root pyproject.toml

To be considered

1. Should requirements.txt generation happen locally or only in CI?
2. Should a shared openenv-core for common utilities be introduced?
3. Should this structure be enforced via a template for new environments?

Example Workflow

uv sync --group dev
cd src/envs/atari_env
uv pip install -e .
uv pip compile pyproject.toml -o server/requirements.txt
docker build -t openenv-atari server/

[rycerzes]

@init27 @jspisak @Darktex please take a look at this

[burtenshaw]

src/envs/{env_name}_env/pyproject.toml : This makes sense. IMO, the most advantage would be on the client side, where the user can add client classes to their env without the OpenEnv repo.

I'm unsure if we need to strictly enforce a pyproject.toml for the docker build, since many envs may not use entirely python, but I can see that it is a useful option.

When we have docs, I would propose adding an example with this approach and integrating with #144 .

[rycerzes]

That makes sense. Having pyproject.toml mainly benefits environments with client-side extensions or Python-heavy builds. For non-Python or mixed setups, we can treat it as optional and continue relying on the existing Docker workflows.

I’ll note this nuance in the proposal and add an example integration once docs and #144 are ready.

Also, for the root pyproject.toml, we can scope dependencies to the base environment, keeping only shared or infra-level dependencies like fastapi, uvicorn, and ruff.

Example:

Root pyproject.toml

[project]
name = "openenv"
version = "0.1.1"
description = "A unified framework for reinforcement learning environments"
readme = "README.md"
requires-python = "~=3.12.0"
dependencies = [
    # Core shared dependencies across all environments
    "fastapi>=0.115.0",
    "pydantic>=2.0.0",
]

[dependency-groups]
dev = [
    "ipykernel>=6.29.5",
    "ipywidgets>=8.1.7",
    "pre-commit>=4.2.0",
    "pytest>=8.4.1",
    "ruff>=0.12.1",
]

[tool.ruff.lint]
select = ["F", "I"]
ignore = ["F722", "F821"]

[tool.ruff]
line-length = 120

Then we can move heavy or env-specific dependencies like torch, smolagents, etc., into each environment’s local pyproject.toml.
For example, an env’s file might look like:

env specific pyproject.toml

[build-system]
requires = ["setuptools>=45", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "openenv-example-env"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
    "torch>=1.9.0",
    "numpy>=1.19.0",
    "requests>=2.25.0",
    "fastapi>=0.104.0",
    "uvicorn>=0.24.0",
    "smolagents>=1.22.0,<2"
]

[tool.setuptools]
package-dir = {"" = "src"}

[tool.setuptools.packages.find]
where = ["src"]

[zkwentz]

Timing of this is great with #144. Didn't have an opportunity to coordinate, but before we go through the process of converting existing example environments in this repo into "valid OpenEnvs" according to the CLI we should close this issue and align on what we think a "valid OpenEnv" is.

As of #144, a valid OpenEnv is:

src/envs/{__ENV_NAME__}
├── __init__.py
├── client.py
├── models.py
├── openenv.yaml
├── README.md
└── server
    ├── __ENV_NAME___environment.py
    ├── __init__.py
    ├── app.py
    ├── Dockerfile
    └── requirements.txt

Which is quite close to what you laid out, and I prefer your pyproject approach to requirements.txt approach.

You kicked this off, so full credit to you: can you open a PR to add pyproject at root and server to the template and test it against openenv init <env_name>?

[init27]

Btw @rycerzes was one of our top competitors and solved Mario in the hackathon :)

[rycerzes]

Thanks @zkwentz! I'll open a PR to update the template with the pyproject.toml approach.

My plan:

1. Add pyproject.toml to both root and server template in [v2] Add OpenEnv CLI for managing environments (incl. push to Hugging Face Env Hub)  #144
2. Update the CLI validation to recognize pyproject.toml as an alternative to requirements.txt
3. Test with openenv init <env_name> to ensure the structure works end-to-end

Also should we make requirements.txt optional entirely?

Will have something up shortly!

[zkwentz]

Also should we make requirements.txt optional entirely?

I think so, yes.

Re: timing, sooner the better :) We have a backlog of env PRs that I'd love to give an openenv convert script and let them update to your standardized template here and then they can go direct to HF.

[burtenshaw]

@rycerzes One thing that we might want to build on top of this is the ability to start an env as a uv script. Which we could add to the toml like this:

[project.scripts]
server = "envs.echo_env.server.app:main"

The the user would be able to do:

uv run --project ./echo_env server --host 0.0.0.0 --port 8000
uv pip install ./echo_env

Which would give them a running server and client code.

[rycerzes]

@burtenshaw

Good point. I'll add this to the template:

[project.scripts]
server = "envs.{env_name}_env.server.app:main"

Should we include additional script entries for Docker builds or tests, or keep it limited to the server entry point?

[zkwentz]

Should we include additional script entries for Docker builds or tests, or keep it limited to the server entry point?

Good idea, yes but I think we need to bike-shed it a bit? We're probably closer on Docker than testing.

Going to add two tasks here:

• Docker builds as part of project scripts
• Testing with templatized tests as part of project scripts.

[burtenshaw]

Docker builds as part of project scripts

@zkwentz Sorry. I should've been clearer. IMO, we need to expose a pure python server runtime with dependency management without docker. This is convenient for users in notebook runtimes and on clusters.