kaggle-tabular-forge 是一个面向 Kaggle 表格赛的可复用实验框架。它的核心不是黑箱 AutoML，而是：用严格的 CV/OOF 证据、可追踪 artifact、实验 registry 和安全 gate，把特征、模型、ensemble 假设一步步锻造成可信结果。
项目受到 NVIDIA/KGMON S6E3 这类高吞吐竞赛系统启发：人类制定策略，LLM 辅助提出假设，所有结论都必须经过 OOF 和 artifact 证明。
项目已经完成从 P0 到 P4 的最小闭环：从规则基座、OOF 证据流水线、配置驱动实验，到候选池、轻量 ensemble 和 matrix-driven candidate factory 都已经有可运行 MVP。当前 README 以“如何理解和复用这个框架”为主，而不是只描述早期 P1/P2 原型。
阶段边界如下：
- P0：项目基座、规则和验收标准，回答“Agent 与实验边界是否清楚？”
- P1：实验证据流水线，回答“能否跑出可审计的 OOF、submission 和 registry？”
- P2：配置驱动实验工作台，回答“能否批量运行、比较和追踪多个实验？”
- P3：候选池与轻量 ensemble，回答“能否从可信候选中安全构造融合结果？”当前 MVP 已实现。
- P4：候选实验工厂，回答“能否从 matrix 配置批量生产可信 P2 候选？”当前 MVP 已实现。
当前仓库已经具备：
uv/pyproject.toml管理的 Python 3.11+ 项目环境。ktabCLI：validate-config、smoke、run、compare、ensemble、factory。- 配置 schema 校验与 config snapshot / config hash。
- tiny fixture 驱动的 smoke / unit / integration 测试。
- StratifiedKFold OOF baseline 与 Logistic Regression baseline。
- 可选 LightGBM / XGBoost / CatBoost 依赖入口。
- OOF、submission、metrics、manifest、registry 等 artifact 写入。
- P3 OOF-backed ensemble 与 P4 matrix-driven candidate factory。
- pytest 与 ruff 作为基础质量门槛。
项目执行流程遵循 Goal → Config → Evidence → Registry → Review 的闭环：先由人类给出目标，再由配置驱动实验，最后用 OOF、artifact 和 registry 判断结果是否可信。
flowchart LR
A["输入 /goal<br/>明确 competition、objective、budget"] --> B["自动发现上下文<br/>configs / registry / artifacts"]
B --> C["校验配置<br/>schema + path + target + metric"]
C --> D{"配置是否可运行？"}
D -- "否" --> E["补齐缺失信息<br/>停止执行，等待确认"]
D -- "是" --> F["运行实验<br/>ktab run / smoke / factory"]
F --> G["生成证据<br/>OOF、metrics、manifest、submission"]
G --> H["写入 registry<br/>config hash + score + artifact path"]
H --> I["比较候选<br/>ktab compare / ensemble"]
I --> J{"是否通过 gate？"}
J -- "否" --> K["记录 hypothesis<br/>调整配置后重跑"]
J -- "是" --> L["沉淀可信候选<br/>进入候选池或融合流程"]
K --> B
安装依赖并运行基础校验：
cd E:\Github\kaggle-tabular-forge
uv sync --group dev
uv run pytest
uv run ruff check .查看 CLI：
uv run ktab --help校验配置：
uv run ktab validate-config `
--config configs\competition.example.yaml `
--schema configs\schemas\competition.schema.json运行 P1 tiny smoke。这个命令只使用仓库内 fixture，不依赖真实 Kaggle 数据：
uv run ktab smoke `
--data-dir tests\fixtures\data\churn_tiny `
--artifact-root artifacts `
--competition churn_tiny `
--experiment-id p1-local-smoke `
--target Churn `
--id-column id `
--n-splits 3 `
--seed 42运行 P2 配置驱动实验：
uv run ktab run --config configs\experiments\p02_churn_logistic_basic.example.yaml运行 LightGBM 示例前，先安装可选依赖：
uv sync --group dev --extra lgbm
uv run ktab run --config configs\experiments\p02_churn_lgbm_basic.example.yaml比较某个 competition 下已经完成且具备 OOF 证据的实验。<competition_slug> 应与运行实验时写入 registry 的 competition 名称一致：
uv run ktab compare --artifact-root artifacts --competition <competition_slug> --top-n 10运行 P3 ensemble。注意：示例配置会读取 registry 中已完成的 parent experiments；如果 parent artifact 不存在，需要先运行对应实验或修改配置中的 parent：
uv run ktab ensemble --config configs\ensembles\p03_candidate_ensemble.example.yaml运行 P4 candidate factory。建议先 dry-run，确认将要展开的 experiment_id 与 artifact 路径，再去掉 --dry-run 执行真实批量实验：
uv run ktab factory --config configs\matrices\p04_churn_candidate_factory.example.yaml --dry-run
uv run ktab factory --config configs\matrices\p04_churn_candidate_factory.example.yaml --max-runs 3生成的本地 artifact 会写入：
artifacts/
├── experiments/<competition>/<experiment_id>/ # metrics、manifest、fold metrics、review
├── oof/<competition>/<experiment_id>/ # oof.parquet
├── submissions/<competition>/<experiment_id>/ # submission.csv
└── registry/<competition>/ # experiment_registry.csv
artifacts/ 和真实 data/ 默认不提交到 git。
/goal 是给人类和 Agent 使用的高层意图格式：人类只描述目标、比赛和预算，系统再从 configs、registry 与已有 artifact 中发现 metric、target、路径、CV 默认值、当前最佳实验和可复用证据。
推荐格式：
/goal objective=<objective> competition=<competition_slug> request="<intent>" budget=<budget>
示例：
/goal objective=build_baseline competition=<competition_slug> request="build first honest baseline with OOF artifacts" budget=single_fold
约定上，competition 不应绑定 README 中的某个固定 Kaggle 项目名称；它只是 registry、artifact 和本地数据路径使用的 slug。完整契约见 docs/goal_contract.md。
项目把测试数据分成两层：仓库内 fixture 和 本地真实比赛数据。前者用于验证代码路径是否可靠，后者用于真实建模与提交文件生成。两者职责不同，不能混用。
默认测试只使用仓库内的 tiny fixture，不依赖任何外部下载、Kaggle 凭据或私有数据。它的作用是做 smoke test：确认 CLI、配置解析、CV/OOF、artifact 写入和 registry 更新这些基础链路能跑通。
tests/fixtures/data/<fixture_name>/
├── train.csv # 小型训练集，包含 target 与 id column
├── test.csv # 小型测试集，不包含 target
└── sample_submission.csv # 提交文件模板，列结构与测试集 id 对齐
当前仓库提供的 fixture 示例：
tests/fixtures/data/churn_tiny/
├── train.csv
├── test.csv
└── sample_submission.csv
fixture 只服务于自动化测试和最小链路验证，不代表真实比赛的数据规模、特征分布、缺失模式或目标难度。
真实 Kaggle 数据不进入 git，统一放在本地 data/ 目录下，并通过配置文件显式指向。推荐使用与具体赛题解耦的目录约定：
data/<competition_slug>/raw/
├── train.csv
├── test.csv
└── sample_submission.csv
例如，任意一个表格赛题都可以映射到自己的 competition_slug：
data/<competition_slug>/raw/train.csv
data/<competition_slug>/raw/test.csv
data/<competition_slug>/raw/sample_submission.csv
train.csv应包含目标列和样本 ID 列；目标列名、ID 列名和评价指标由 config 指定。test.csv应包含与训练集兼容的特征列和样本 ID 列，但不应包含目标列。sample_submission.csv用于校验提交文件的 ID 顺序、列名和行数，不应被模型逻辑当作训练信号。- 不同 Kaggle 赛题只需要新增对应的
competition_slug和 config，不应改动测试 fixture 或核心代码。 - 如果某个赛题有额外文件、分组列、时间列或多目标标签，应在该赛题的 config / docs 中说明，而不是写死到 README 的通用路径里。
一个实验只有具备对应证据时才算可信：
- config
- command
- CV protocol
- OOF predictions
- fold metrics
- test predictions 或 submission
- feature/model manifests
- leakage review
- reproducibility metadata
- experiment registry record
没有 OOF/CV 证据、日志和可复现命令时，任何结论都只能算 hypothesis。
入口文档：
- AGENTS.md：Agent 不可违反的规则与任务路由。
- README.md：人类入口、项目定位、执行流程、快速命令、数据契约与 FAQ。
- configs/README.md：配置示例、阶段入口与重复运行注意事项。
核心契约：
- docs/README.md：文档索引与渐进式披露导航。
- docs/goal_contract.md：
/goal输入与验收。 - docs/artifact_contract.md：artifact 布局、OOF 对齐与可追踪性。
- docs/leakage_rules.md：泄漏与 public leaderboard 使用边界。
- docs/testing_strategy.md：测试层级、fixture 策略与 local data 边界。
阶段路线图：
- docs/p00_project_foundation.md：P0 项目基座、规则与验收标准。
- docs/p01_evidence_pipeline.md：P1 最小可运行证据流水线。
- docs/p02_experiment_workbench.md：P2 配置驱动实验工作台。
- docs/p03_candidate_ensemble.md：P3 候选池与轻量 ensemble 方案。
- docs/p04_candidate_factory.md：P4 候选实验工厂。
方法论与系统设计：
- docs/kgmon_methodology.md：方法论与阶段路线图。
- docs/agent_protocol.md：Agent 角色、输入输出与任务图。
- docs/agent_integration.md：Codex 多 Agent / Skill / MCP 集成想法。
- docs/feature_catalog.md：特征家族与风险标签。
- docs/model_zoo.md：模型家族与依赖分组。
- docs/stacking.md：OOF-backed ensemble、hill climbing、stacking。
- docs/environment_notes.md：环境、依赖、Windows/WSL/Kaggle 边界。
实验记录与补充材料：
- docs/experiments/：历史实验记录、建模笔记与验证复盘。
- docs/evaluation/：baseline checklist 与评估材料。
- docs/config/：环境与配置笔记。
- docs/testing/：smoke test plan 等测试材料。
当前仓库是一个面向 Kaggle 表格赛的 evidence-first 实验框架，核心内容分为 configs/、src/ktabforge/、tests/ 和 docs/ 四层：配置描述“要跑什么”，源码负责“怎么跑”，测试验证“能否稳定跑”，文档沉淀“为什么这样跑”。
kaggle-tabular-forge/
├── AGENTS.md # Agent 协作规则、任务边界与安全约束
├── README.md # 中文项目入口：定位、流程、数据契约、FAQ
├── README.en.md # 英文 README，与中文 README 保持结构对齐
├── pyproject.toml # uv / Python 项目配置、依赖分组、CLI 入口
├── uv.lock # uv 锁定文件，保证依赖可复现
├── .gitignore # 忽略 artifacts、data、缓存和本地临时文件
│
├── configs/ # 人类可编辑配置层：比赛、实验、模型、路径、矩阵
│ ├── README.md # 配置目录说明
│ ├── competition.example.yaml # 比赛级配置：target、id、metric、路径等
│ ├── experiment.example.yaml # 单实验配置模板
│ ├── feature_catalog.example.yaml # 特征目录模板
│ ├── model_zoo.example.yaml # 模型族与依赖分组模板
│ ├── paths.example.yaml # 本地路径约定模板
│ ├── stacking.example.yaml # stacking / ensemble 配置模板
│ ├── agents.example.yaml # Agent 协作配置模板
│ ├── goal.example.yaml # /goal 契约配置模板
│ ├── experiments/ # 可直接运行的 P2 实验配置
│ │ ├── p02_churn_logistic_basic.example.yaml
│ │ └── p02_churn_lgbm_basic.example.yaml
│ ├── ensembles/ # P3 候选融合配置
│ │ └── p03_candidate_ensemble.example.yaml
│ ├── matrices/ # P4 批量候选实验矩阵
│ │ └── p04_churn_candidate_factory.example.yaml
│ ├── goals/ # 阶段性 goal 示例
│ │ ├── p03_candidate_ensemble.goal.yaml
│ │ └── p04_candidate_factory.goal.yaml
│ └── schemas/ # JSON Schema：配置校验边界
│ ├── competition.schema.json
│ ├── experiment.schema.json
│ ├── feature_catalog.schema.json
│ ├── goal.schema.json
│ ├── matrix.schema.json
│ ├── model_zoo.schema.json
│ ├── paths.schema.json
│ └── stacking.schema.json
│
├── src/ktabforge/ # Python 包源码：ktab CLI 与实验流水线
│ ├── __init__.py
│ ├── __main__.py # python -m ktabforge 入口
│ ├── cli.py # `ktab` 命令行入口
│ ├── config/ # 配置加载、schema 校验、实验矩阵解析
│ ├── data/ # train/test/submission 读取与数据 schema
│ ├── cv/ # CV protocol 与 splitters
│ ├── features/ # 基础特征与特征集合定义
│ ├── models/ # baseline、logistic、LightGBM、XGBoost 与模型注册
│ ├── metrics/ # 统一 scoring 与指标适配
│ ├── pipeline/ # evidence-first 实验主流程与 run context
│ ├── artifacts/ # OOF、submission、manifest、checksum、layout 写入
│ ├── registry/ # experiment registry 读写与比较基础
│ ├── candidates/ # 候选池与候选对齐检查
│ ├── ensembles/ # averaging / ensemble runner
│ ├── factory/ # candidate factory：矩阵展开、运行、结果汇总
│ ├── reports/ # compare 报告与实验对比输出
│ ├── safety/ # leakage review、gate 与安全检查
│ └── utils/ # env、git、hashing、logging、time 等通用工具
│
├── tests/ # 自动化测试：从导入 smoke 到端到端实验链路
│ ├── fixtures/data/churn_tiny/ # 仓库内 tiny fixture，不绑定真实 Kaggle 赛题
│ │ ├── train.csv
│ │ ├── test.csv
│ │ └── sample_submission.csv
│ ├── smoke/ # 最小导入与项目可用性测试
│ ├── unit/ # 配置、CV、矩阵等单元测试
│ └── integration/ # CLI、P2/P3/P4 实验链路集成测试
│
└── docs/ # 设计文档、阶段路线图、实验复盘与方法论
├── README.md # 文档索引
├── goal_contract.md # /goal 输入与验收契约
├── artifact_contract.md # artifact 布局、OOF 对齐与可追踪性
├── leakage_rules.md # 泄漏与 public leaderboard 使用边界
├── testing_strategy.md # 测试层级与 fixture 策略
├── p00_project_foundation.md # P0 项目基座
├── p01_evidence_pipeline.md # P1 证据流水线
├── p02_experiment_workbench.md # P2 实验工作台
├── p03_candidate_ensemble.md # P3 候选融合
├── p04_candidate_factory.md # P4 候选工厂
├── experiments/ # 实验记录、验证笔记、建模复盘
├── evaluation/ # baseline checklist 与评估材料
├── config/ # 环境与配置笔记
└── testing/ # smoke test plan 等测试材料
推荐阅读顺序：
- 先看
README.md，理解项目定位、执行流程和数据契约。 - 再看
configs/README.md与configs/*.example.yaml，理解如何声明比赛、实验和路径。 - 需要跑实验时，从
configs/experiments/或configs/matrices/选择模板，再用ktab run/ktab factory执行。 - 需要理解结果可信度时，优先看
docs/artifact_contract.md、docs/leakage_rules.md和生成的 registry / manifest。 - 需要改源码时，从
src/ktabforge/cli.py进入，再顺着pipeline/、artifacts/、registry/查执行链路。
- 只以本地
uv run pytest、uv run ruff check .和完整 artifact 作为最低验收，不能只看 public leaderboard 或单次提交结果。 - 任何模型改进都必须保留对应的 config、command、OOF、fold metrics、manifest、leakage review 和 registry record。
- 默认不提交
artifacts/、真实data/、Kaggle token、API key 或包含私有路径的临时文件。 - 不把 public leaderboard 当作调参目标；它只能作为赛后校准或异常排查信号。
- 不默认使用
reset --hard、删除 registry 或覆盖 OOF 证据；需要回滚时优先保留历史实验记录。 - 如果本地仓库已有 dirty worktree，先确认变更归属，再决定继续、stash 或隔离 clone。
Kaggle 表格赛的核心风险不是“模型不够复杂”，而是离线验证不可信。OOF 是 out-of-fold 预测：每个训练样本都只由没见过它的 fold 模型预测，因此它更接近真实泛化误差。没有 OOF 的分数提升，更像未经审计的 hypothesis。
本项目追求的是可复用、可解释、可复盘的实验系统，而不是一次性的黑箱搜索。AutoML 可以作为候选生成器，但每个候选仍必须通过统一的 CV、artifact、registry 和 leakage gate，才能进入可信候选池。
artifacts/ 通常包含 OOF、submission、metrics、manifest 和 registry，体积会快速膨胀，也可能带有本地路径或比赛数据痕迹。默认策略是代码和契约入库，大型实验产物留在本地或外部存储，并通过 manifest/registry 保持可追踪。
Public LB 只覆盖测试集的一部分，且容易被反复提交过拟合。更稳健的流程是先信任本地 CV/OOF，再用 Public LB 做 sanity check；如果两者背离，应优先排查泄漏、分布漂移、split 设计和 submission 对齐。
config hash 相当于实验“指纹”，registry 相当于实验“账本”。前者用于确认某个结果到底由哪组参数产生，后者用于横向比较和回溯，避免后续只记得分数、忘记过程。