generate-openenv-env

# /generate-openenv-env Build a production-ready OpenEnv environment from a use-case prompt. ## Execute Workflow When invoked, execute this workflow end-to-end. ### 1. Parse the use case and name the environment Derive a repo path in the form `envs/<name>_env/`. - Normalize to snake_case. - Keep names short and domain-specific. - Example: "generate an env for the library textarena" -> `envs/textarena_env/`. ### 2. Research the target library/API before coding Gather the minimum interface facts needed to implement `reset`, `step`, and state serialization. - Search local docs/examples first. - Search upstream docs/repo for the target library when local context is insufficient. - Extract only implementation-critical details: - installation/dependency requirements - environment creation API - action format - observation format - reward and done semantics - special setup (model files, downloads, auth, etc.) ### 3. Mine matching OpenEnv examples Select 2-3 existing environments as implementation templates. - Always read `references/openenv-tutorial-01-environments.md` (Part 10) and `references/openenv-docs-environment-builder.md`. - Prefer `envs/textarena_env` for external-library wrappers with richer state. - Add one simpler baseline (for example `envs/snake_env` or `envs/echo_env`) to keep the implementation minimal. - Follow patterns, do not copy blindly. - Exclude generated or vendored files when mining examples (`.venv/`, `build/`, `site-packages/`, `__pycache__/`). For a compact checklist and mapping, read `references/env-generation-checklist.md`. ### 4. Ask focused implementation questions Ask only the questions that materially affect architecture. Use the question bank in `references/env-generation-checklist.md`. Cover at least: - action space contract - observation fields needed by agents - reward design and terminal conditions - episode/session configuration knobs - deployment target and dependency constraints If answers are unavailable, proceed with explicit assumptions and document them. ### 5. Choose the environment archetype Choose one archetype before scaffolding: - Typed step/reset environment (default): use `EnvClient` + typed `Action/Observation[/State]` models. - MCP tool environment: use `MCPEnvironment` + `MCPToolClient` and MCP action/observation types. - Specialized client flow (rare): only when the standard clients cannot express required behavior (for example local+remote hybrid clients). ### 6. Scaffold the environment Use the CLI to scaffold: ```bash PYTHONPATH=src uv run openenv init <name>_env --output-dir envs ``` This generates all files with correct placeholders replaced, including `pyproject.toml`, `Dockerfile`, and `uv.lock`. If the CLI is unavailable (import errors, missing dependencies), create the structure manually matching: ```text envs/<name>_env/ ├── __init__.py ├── client.py ├── models.py ├── openenv.yaml ├── pyproject.toml └── server/ ├── __init__.py ├── app.py ├── <name>_environment.py └── Dockerfile ``` Use `assets/openenv_env_template/` as a reference for file contents when scaffolding manually. ### 7. Implement with OpenEnv contracts Implement these files in order: 1. `models.py` 2. `server/<name>_environment.py` 3. `server/app.py` 4. `client.py` 5. `openenv.yaml` 6. `README.md` Use these standards: - Use typed models (Action/Observation/State). - Use `create_app(<factory_or_class>, ActionType, ObservationType, env_name=...)` in `server/app.py`. Pass a class or factory callable, not an instantiated environment. - **Dual-import pattern** (required in `server/app.py` and `server/<name>_environment.py`): Use `try: from ..models import X / except ImportError: from models import X`. Relative imports work in-repo (`PYTHONPATH=src:envs`); bare imports work in Docker (`PYTHONPATH=/app/env`). The same pattern applies to intra-server imports (e.g., `from .foo import Bar` vs `from server.foo import Bar`). - `client.py` uses `EnvClient[ActionType, ObservationType, State]` (three type parameters). - Keep server logic in `server/`, keep client parsing in `client.py`. - Expose config through environment variables when behavior is likely to vary. - Keep reward logic inside the environment. - Prefer reset/step signatures compatible with `Environment`: - `reset(seed=None, episode_id=None, **kwargs)` - `step(action, timeout_s=None, **kwargs)` - Set `SUPPORTS_CONCURRENT_SESSIONS=True` only when isolation is real. Set `max_concurrent_envs` in `create_app` accordingly (1 when `False`, >1 when `True`). - For MCP/tool-call UIs that send stringified JSON arguments, add action validators/parsers in `server/app.py`. - Export public client/models symbols in `__init__.py`. - Keep `openenv.yaml` aligned with current scaffold format (`spec_version: 1`, `name`, `type`, `runtime`, `app`, `port`). - Avoid training/evaluation code paths in this skill. ### 8. Validate before handoff Run the narrowest useful checks: ```bash # Verify in-repo imports work (catches missing dual-import pattern) PYTHONPATH=src:envs uv run python -c "from envs.<name>_env.server.<name>_environment import <ClassName>Environment" # Build and validate cd envs/<name>_env openenv build openenv validate --level static --skip-build PYTHONPATH=src:envs uv run pytest envs/<name>_env -q ``` If tests do not exist, run a smoke check: ```bash PYTHONPATH=src:envs uv run uvicorn envs.<name>_env.server.app:app --port 8000 curl http://localhost:8000/health openenv validate --url http://localhost:8000 ``` ### 9. Deliver with assumptions and gaps Report: - files created/updated - chosen archetype (typed vs MCP vs specialized) - assumptions made due to missing answers - validation commands executed and outcomes - remaining risks or follow-up questions ## Guardrails - Do not route into model training/evaluation workflows. - Do not invent library APIs; confirm against source docs. - Do not skip reading at least one existing OpenEnv env before implementation. - Do not copy outdated manifest patterns from older envs (`name/version/action/observation`-only manifests). - Do not copy build artifacts or virtualenv files from example envs. - Do not set `max_concurrent_envs > 1` unless the environment explicitly supports concurrent sessions.