docs/openenv_cheatsheet.md

OpenEnv Quick Reference

CLI Commands

openenv init <env_name>          # Scaffold new environment
openenv validate                 # Validate openenv.yaml + spec compliance
openenv push --repo-id user/env  # Deploy to HuggingFace Spaces

openenv.yaml Format

spec_version: 1
name: code_review_env
type: space
runtime: fastapi
app: server.app:app
port: 8000

3-Component Pattern

File	Purpose
models.py	Pydantic BaseModel: Action, Observation, State
server/environment.py	Core logic: reset(), step(), state property
client.py	EnvClient for HTTP/WebSocket interaction
server/app.py	create_fastapi_app(Env, Action, Obs, State)
Dockerfile	Container spec

Environment Interface

class MyEnvironment:
    def reset(self) -> Observation:      # Start new episode
    def step(self, action: Action) -> Observation:  # Process action
    @property
    def state(self) -> State:            # Internal state for grading

Observation Must Include

class MyObservation(BaseModel):
    reward: float    # [0.0, 1.0]
    done: bool       # Episode complete?
    info: dict       # Metadata

Deployment Flow

1. uvicorn server.app:app --reload (local)
2. docker build -t env . && docker run -p 8000:8000 env (container)
3. openenv push --repo-id user/env (HF Spaces)

Pre-Submission Checklist

• openenv validate passes
• docker build && docker run works
• HF Space returns 200 on ping + responds to reset()
• Baseline inference script runs and produces scores
• 3+ tasks with graders, scores in 0.0-1.0