cookiecutter-mlops-package: Instructions file for Codex

AGENTS.md

Context and rules for AI agents working in this repository. Humans should start with README.md.

Project overview

• Name: cookiecutter-mlops-package — a Cookiecutter template that scaffolds MLOps Python packages.
• Layout: {{cookiecutter.repository}}/ holds the template sources (raw Jinja); tests/test_cookiecutter.py bakes the template and runs the generated project's full toolchain.
• Language: Python 3.14+ (pyproject.toml), managed with uv.
• Reference: mlops-python-package is the reference implementation. Shared configuration files should differ from it only by cookiecutter variables; diff against it before changing the template.

Setup & core commands

All work goes through mise (see mise.toml); git hooks (lefthook.yml) and CI call the same tasks.

• Everything: mise run all — format, check, test. This is the gate; CI runs this exact task and nothing else. There is no build step: [tool.uv] package = false, this repository is a test suite, not a distribution.
• Install: mise install provisions the pinned toolchain (run_auto_install is off), then mise run install syncs the virtualenv (uv sync) and installs git hooks.
• Format: mise run format — ruff (import sort + format, including Python inside Markdown) and dprint (JSON/Markdown/TOML/YAML).
• Check: mise run check — ruff lint, ty types, pip-audit deps, dprint/validate-pyproject/uv lock format, gitleaks secrets, trivy filesystem scan, actionlint + zizmor workflows.
• Test: mise run test — pytest bakes the template and runs mise trust/mise install/git init/mise run all/... inside the generated project. Needs docker running and takes several minutes.

Definition of done

A change is complete only when, locally, mise run all passes warning-free — which includes the bake test actually generating a project and passing that project's own gate. Fix root causes — never weaken an assertion, add a skip/xfail, loosen a type, or suppress a lint error to force a green result.