cultivating-ml-agent: Instructions file for Codex

AGENTS.md — Autonomous ML Learning Agent Instructions

This file guides Claude Code (or any AI coding agent) to autonomously execute ML competition workflows using the Cultivating ML Agent framework.

Overview

This project provides a knowledge-driven MLOps framework for training ML agents from novice to competition-level performance. It combines:

1. Framework code (framework/) — Reusable Python modules for config, logging, validation, MLflow tracking
2. Skills library (skills/examples/) — 19 crystallized patterns from real competitions
3. Main guide (docs/cultivating-ml-agent-expert.md) — Methodology (1088 lines)
4. Templates (templates/) — Skill creation templates

When Agent Is Activated

Upon installation, the agent should:

1. Read this file for operational instructions
2. Browse skills/examples/ for available domain knowledge
3. Use framework/ modules for pipeline structure
4. Follow the five-stage learning loop for continuous improvement

Agent Workflow

Starting a New Competition

Follow this exact sequence:

1. Read competition overview (metric, data format, submission format)
2. Copy framework/config_template.yaml → config.yaml, fill in competition details
3. Copy framework/script_template.py → scripts/run_r01_baseline.py
4. Run EDA: data shapes, class balance, missing values, feature types
5. Build baseline (single model, no feature engineering)
6. Submit to LB — this is your floor score
7. Iteratively improve: R02, R03, ... with clear naming

Per-Experiment Workflow (5-Stage Pipeline)

Every experiment script (run_r{NN}_{name}.py) MUST follow this structure:

Stage 0: Configuration
  - load_config("config.yaml", overrides={...})
  - get_logger("R{NN}_{name}")
  - argparse: --smoke, --no-mlflow, --override

Stage 1: Data Loading
  - Load train/test/sample_submission
  - Log shapes: log.data_shape("train", df)
  - Validate: validate_pipeline(train, test, cfg)

Stage 2: Feature Engineering
  - Create features
  - Validate: validate_features(df, FEATURE_COLS)
  - Log feature count and names

Stage 3: Model Training
  - Train with CV (5-fold default)
  - Log CV score: log.metric("CV", score)
  - Save model artifact
  - Save OOF predictions for stacking

Stage 4: Prediction + Submission
  - Generate predictions
  - get_submission_filename() for naming
  - validate_and_save() for format checking
  - evaluation_gate() to block regressions
  - Submit to Kaggle LB