Repository Guidelines
Project Structure & Module Organization
Core code lives in src/openpi/ with domain folders such as models/, policies/, training/, shared/, and serving/. Reusable client/runtime code is in packages/openpi-client/src/openpi_client/. Operational entry points are under scripts/ (for example train_pi0_fast_ricl.py, serve_policy_ricl.py). Data preparation utilities are in preprocessing/. Integration examples for robots and environments are in examples/. Small tracked assets are in assets/; large checkpoints and collected demos are intentionally gitignored.
Build, Test, and Development Commands
GIT_LFS_SKIP_SMUDGE=1 uv sync: install workspace dependencies without downloading large LFS payloads.source .venv/bin/activate: activate the local virtual environment.uv run pytest: run tests acrosssrc,scripts, andpackages.uv run pytest -m "not manual": run CI-friendly tests only.uv run ruff check .: lint code (configured inpyproject.toml).uv run ruff format .: apply formatting.pre-commit run --all-files: run configured hooks (uv-lock, Ruff) before pushing.
Coding Style & Naming Conventions
Use Python with 4-space indentation and a maximum line length of 120. Follow Ruff defaults plus repo rules in pyproject.toml. Prefer snake_case for files, functions, and variables; PascalCase for classes; UPPER_SNAKE_CASE for constants. Keep module boundaries clear (training logic in src/openpi/training/, policy logic in src/openpi/policies/).
Testing Guidelines
Place tests as *_test.py, typically beside the code they validate. Use pytest fixtures/parametrization for deterministic unit coverage. Mark long-running or environment-dependent tests with @pytest.mark.manual. During development, run focused tests (example: uv run pytest src/openpi/models/model_test.py), then run the full suite before opening a PR.
Commit & Pull Request Guidelines
Recent history uses short, single-line summaries (example: ricl_openpi_edited for capstone). Keep commit subjects concise and descriptive; add scope when helpful (example: training: fix demo-group retrieval path). PRs should include purpose, key changes, validation commands run, and any data/checkpoint assumptions. Link related issues/discussions and include logs or screenshots when behavior changes are observable.
Data & Configuration Tips
Do not commit generated artifacts in ignored paths such as checkpoints/, wandb/, preprocessing/collected_demos_training/, or preprocessing/collected_demos/. Keep collected-task folder naming consistent with preprocessing expectations: {YYYY-MM-DD}_{task_prompt}.