Skip to content

AGENTS.md

Latest commit

 

History

History
51 lines (37 loc) · 5.43 KB

AGENTS.md

File metadata and controls

51 lines (37 loc) · 5.43 KB
Raw

AGENTS.md

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

Project overview

  • Name: bikes — a production-shaped MLOps package that predicts hourly bike rental demand.
  • Description: reference implementation for the MLOps Coding Course, generated from cookiecutter-mlops-package.
  • Language: Python 3.14+ (pyproject.toml), managed with uv.
  • Stack: MLflow (tracking, registry, projects, evaluation), scikit-learn, pandas, Pydantic + Pandera validation, OmegaConf YAML configs, loguru.
  • Skills: the reusable practices behind this package are published as Agent Skills in mlops-coding-skills. Install them from there rather than vendoring a copy here — a copy drifts, and this repository already lost a month to proving it.

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, build. This is the gate; CI runs this exact task, plus a clean-tree check.
  • Install: mise run install — sync the virtualenv (uv sync --all-groups) and install 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, hadolint Dockerfile, actionlint + zizmor workflows.
  • Test: mise run test — pytest with coverage (fails under 100%); mise run test:parallel is a faster, coverage-free local loop.
  • Build: mise run build — uv build (wheel + sdist); mise run build:image builds the Docker image.
  • Docs: mise run docs — pdoc API reference into docs/.
  • MLflow jobs: mise run project runs the connected PipelineJob (tune → train → evaluate → promote → infer → explain); mise run project:run <name> runs one (confs/<name>.yaml).

Pipeline invariants

  • Training uses the full tuning model configuration plus validated selected parameters. Evaluation, promotion and downstream consumers use the exact registered candidate version. Failed evaluation preserves the champion alias. Standalone promotion requires a positive explicit version.
  • Input datasets and signatures exclude casual and registered; raw counts remain in data/hour.csv for analysis. Retrain historical registered models to adopt the new serving signature.

Definition of done

A change is complete only when, locally, mise run format is clean, mise run check reports no findings, and mise run test is green with new/changed behavior covered by a test. Fix root causes — never weaken an assertion, add a skip/xfail, loosen a type, or suppress a lint error to force a green result.

Conventions & idioms

  • Errors with context: raise specific exceptions and chain with raise ... from err; never use a bare except or silently swallow errors.
  • Config over hardcoding: jobs and objects are Pydantic models parsed from OmegaConf YAML in confs/; validate and fail fast. Dataframes are validated at boundaries with Pandera schemas (core/schemas.py).
  • Typing: modern annotations (list[str], X | Y); keep ty check clean. import typing as T is the project convention.
  • Logging: loguru via LoggerService; no bare prints in library code.
  • MLflow: tracking and registry run on a SQLite backend (sqlite:///mlflow.db); artifact files stay on disk under ./mlruns. This is the same SQLAlchemy store shape as a production Postgres and the store the model registry is designed for, so moving up is a MLFLOW_TRACKING_URI change, not a rewrite. Models are logged with name= and referenced by models:/name@alias or models:/name/version.
  • Commits: Conventional Commits (feat:, fix:, refactor:, chore:); no attribution in commit messages. Releases use git-cliff (cliff.toml) to generate CHANGELOG.md.

Repository layout

  • src/bikes/ — package: core/ (metrics, models, schemas), io/ (configs, datasets, registries, services), jobs/ (pipeline, tuning, training, promotion, inference, evaluations, explanations), utils/ (searchers, signers, splitters), plus settings.py, scripts.py, __main__.py.
  • confs/ — one OmegaConf YAML per MLflow job; tests/ — pytest suite mirroring src/ with fixtures in conftest.py.
  • data/ — bike sharing datasets (Parquet splits and source CSV); notebooks/ — exploration notebooks (plotly comes from the notebook dependency group); .env.example — MLflow URIs to copy into .env, which mise.toml sources.
  • pyproject.toml — dependencies and ruff/ty/pytest config; mise.toml/mise.lock — tasks and pinned, locked tools; lefthook.yml — git hooks; dprint.jsonc/trivy.yaml/cliff.toml — formatter, scanner, changelog config.
  • .github/ — workflows/ (ci.yml runs mise run all, cd.yml runs the gate before publishing docs and promotes a scanned image digest, security.yml rescans the full history weekly), dependabot.yml, rulesets/main.json.
  • Dockerfile/docker-compose.yml/MLproject — container image, local MLflow server, and MLflow Projects reproducible runs (--env-manager=local reuses the uv environment, so there is no python_env.yaml).