prime env init

Create a new environment template

Overview

The prime env init command scaffolds a new environment module with a basic template, including starter code, metadata, and documentation.

Usage

prime env init <env> [OPTIONS]

Arguments

env · string · required

Environment ID (will be normalized to use underscores for the package name).

Example: my-env creates environments/my_env/

Options

--path · string · default: "./environments"

Path to environments directory where the new environment will be created.

--rewrite-readme · flag

Overwrite README.md if it already exists.

--multi-file · flag

Create a multi-file package structure with __init__.py instead of a single-file module.

--openenv · flag

Initialize with the OpenEnv layout for tool-use environments. Creates proj/ directory with OpenEnv project structure.

Created Structure

Standard Environment

By default, creates a single-file module structure:

environments/my_env/
├── my_env.py           # Main implementation with load_environment()
├── pyproject.toml      # Dependencies and metadata
└── README.md           # Documentation template

Multi-File Environment

With --multi-file, creates a package structure:

environments/my_env/
├── my_env/
│   ├── __init__.py     # Exports load_environment
│   └── my_env.py       # Main implementation
├── pyproject.toml
└── README.md

OpenEnv Environment

With --openenv, creates an OpenEnv-based environment:

environments/my_env/
├── my_env.py           # Environment wrapper using vf.OpenEnvEnv
├── pyproject.toml      # With verifiers[openenv] dependency
├── README.md           # OpenEnv-specific documentation
└── proj/               # OpenEnv project directory
    ├── openenv.yaml    # OpenEnv manifest
    ├── pyproject.toml  # Project dependencies
    ├── server/
    │   ├── Dockerfile  # Container definition
    │   └── app.py      # FastAPI server
    └── README.md       # Project documentation

Examples

Create a Standard Environment

prime env init my-env

Output:

Created environments/my_env/
  my_env.py
  pyproject.toml
  README.md

Create a Multi-File Environment

prime env init complex-env --multi-file

Output:

Created environments/complex_env/
  complex_env/__init__.py
  complex_env/complex_env.py
  pyproject.toml
  README.md

Create an OpenEnv Environment

prime env init tool-env --openenv

Output:

Created environments/tool_env/
  tool_env.py
  pyproject.toml
  README.md
  proj/openenv.yaml
  proj/pyproject.toml
  proj/server/Dockerfile
  proj/server/app.py
  proj/README.md

Custom Path

prime env init my-env --path ~/my-envs

Creates the environment in ~/my-envs/my_env/.

Template Contents

Environment Implementation

The generated my_env.py contains a starter template:

import verifiers as vf

def load_environment(**kwargs) -> vf.Environment:
    """
    Loads a custom environment.
    """
    raise NotImplementedError("Implement your custom environment here.")

pyproject.toml

Defines the package metadata and dependencies:

[project]
name = "my-env"
description = "Your environment description here"
tags = ["placeholder-tag", "train", "eval"]
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
    "verifiers>=0.8.0",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build]
include = ["my_env.py", "pyproject.toml"]

[tool.verifiers.eval]
num_examples = 5
rollouts_per_example = 3

README.md

Provides a documentation template with sections for:

• Overview
• Datasets
• Task description
• Quickstart examples
• Environment arguments
• Metrics

Next Steps

After creating an environment:

1. Edit the environment code in my_env.py
2. Add dependencies to pyproject.toml if needed
3. Install the environment:
   prime env install my-env
   
4. Test with an evaluation:
   prime eval run my-env -m gpt-4.1-mini -n 5
   

OpenEnv Workflow

For OpenEnv environments, additional steps are required:

1. Implement the OpenEnv server in proj/server/app.py
2. Build the Docker image:
   uv run vf-build my-env
   
3. Install and test:
   prime env install my-env
   prime eval run my-env -m gpt-4.1-mini
   

See the Environments documentation for detailed implementation guidance.

Naming Conventions

• Environment IDs can use hyphens (e.g., my-env) or underscores (e.g., my_env)
• Package names normalize to underscores (e.g., my_env)
• Directory names match the package name (e.g., environments/my_env/)
• Module names match the package name (e.g., my_env.py)

Troubleshooting

Directory Already Exists

If the environment directory already exists, the command will skip creating existing files:

README.md already exists at environments/my_env/README.md, skipping...

Use --rewrite-readme to force overwrite the README.

Invalid Environment Name

Environment names must be valid Python package names. Avoid special characters and spaces.