[ENHANCEMENT] Restructure package for simplified installation

[burtenshaw]

This PR solves this issue. In short, that the package is not straightforward or conventional to install or import.

DX changes

The PR has a significant amount of new lines, made mostly out of grepping and moving. The fundamental change is this:

User will install like this:

# install everything
pip install openenv
pip install git+https://github.com/meta-pytorch/OpenEnv.git

# install a subset of dependencies
pip install openenv[core]
pip install openenv[cli]

User can use the core library in their envs like so:

from openenv.core.client_types import StepResult
from openenv.core.http_env_client import HTTPEnvClient
from coding_env.models import CodeAction, CodeObservation, CodeState

And install in the env tomls with openenv[core], openenv, or git+https://github.com/meta-pytorch/OpenEnv.git, without a subdirectory reference.

Implementation

The Changes to implement this are:

• Collapsed the repo into a single distributable openenv package: CLI + runtime live under src/openenv/. Following Python conventions and simplifying toml definition.
• openenv_core is now a shim.
• and extras ([core], [cli], [all]) express optional deps in `pyproject.toml.
• Moved sample environments out of src/ into top-level envs/
• updated the CLI template to use openenv.core
• updated docs to import from openenv.core and depend on openenv[core],
• Updated README, guides, scripts, and tests to the new layout

Changes

Before

OpenEnv/
├── pyproject.toml          # publishes CLI-only “openenv” package
├── src/
│   ├── __init__.py
│   ├── core/               # separate openenv-core package (its own pyproject)
│   │   ├── client_types.py
│   │   ├── env_server/
│   │   ├── http_env_client.py
│   │   └── tools/
│   ├── envs/               # example environments bundled inside src/
│   │   ├── echo_env/
│   │   ├── coding_env/
│   │   └── ...
│   └── openenv_cli/        # CLI package exposed by root pyproject
│       ├── __main__.py
│       ├── commands/
│       └── templates/
└── tests/

After

After (single openenv namespace + externalized envs)
OpenEnv/
├── pyproject.toml          # publishes unified “openenv” (core + CLI)
├── src/
│   └── openenv/
│       ├── __init__.py     # namespace package
│       ├── core/           # runtime modules now under openenv.core
│       │   ├── client_types.py
│       │   ├── env_server/
│       │   ├── http_env_client.py
│       │   └── tools/
│       ├── cli/            # CLI lives under openenv.cli
│       │   ├── __main__.py
│       │   ├── commands/
│       │   └── templates/
│       └── ...
├── openenv_core/           # compatibility shim re-exporting openenv.core
├── envs/                   # sample/template environments (not packaged)
│   ├── echo_env/
│   ├── coding_env/
│   └── ...
└── tests/

[rycerzes]

LGTM! Having a deprecation warning of sorts would be beneficial
Also I think the dependency grouping in the updated pyproject.toml needs clarification.
Right now, core contains all the server dependencies (FastAPI, Pydantic, Uvicorn, Requests), but it’s declared under optional-dependencies. That makes it seem like core is required for normal usage, yet it's not installed by default.

[pankit-eng]

thanks @burtenshaw for the change. Will review this. do you mind mentioning the detailed project structure before vs after this change in the PR description? It ll make the review a bit easier. Thanks!

[pankit-eng]

@burtenshaw - whats your take on the each env's version? We don't want the repo to be a host of multiple versions of envs, given this repo is purpose-built to be framework.

[burtenshaw]

Agreed. We should just host the latest version of a limited set of envs.

[burtenshaw]

thanks @burtenshaw for the change. Will review this. do you mind mentioning the detailed project structure before vs after this change in the PR description? It ll make the review a bit easier. Thanks!

@pankit-eng That's added to the description. Let me know what you think.

[burtenshaw]

@rycerzes

LGTM! Having a deprecation warning of sorts would be beneficial

I would skip this for this early version of the lib.

Also I think the dependency grouping in the updated pyproject.toml needs clarification. Right now, core contains all the server dependencies (FastAPI, Pydantic, Uvicorn, Requests), but it’s declared under optional-dependencies. That makes it seem like core is required for normal usage, yet it's not installed by default.

Understood. My thinking here was to expose an optional 'minimal' install for envs that just use openenv.core and not openenv.cli

[rycerzes]

@burtenshaw
Fair point on the deprecation warning. On the dependency grouping - having core as optional when it contains FastAPI, Pydantic, Uvicorn, and Requests (which seem essential for the server/framework) is a bit counterintuitive. Could you consider either making these part of the default install?

[burtenshaw]

On the dependency grouping - having core as optional when it contains FastAPI, Pydantic, Uvicorn, and Requests (which seem essential for the server/framework) is a bit counterintuitive. Could you consider either making these part of the default install?

@rycerzes Ok. They already included within dependencies (see here). [project.optional-dependencies].core is a mechanism to negate cli dependencies.

That said, I am not wedded to seperation I just thought it was convenient for docker builds to skips the extra cli dependencies. Do you find it confusing?

[rycerzes]

@burtenshaw

Ah got it, makes sense now. The naming just threw me off - openenv[core] reads like "minimal install". If the default install includes everything, then nvm, current setup is fine. Docker build optimization is worth it.

[burtenshaw]

Ah got it, makes sense now. The naming just threw me off - openenv[core] reads like "minimal install". If the default install includes everything, then nvm, current setup is fine. Docker build optimization is worth it.

Understood. I'll review the docs to make sure it's clear.

[burtenshaw]

Thanks for the review @pankit-eng, I'll merge to release and ping relevant PRs.