Kaggle Codex Agent

简介

这是一个辅助做 Kaggle 实验的轻量 agent 项目骨架。你只需要在 ideas/idea.md 里写实验想法，Codex 会按照 AGENTS.md 的规则修改 Kaggle kernel、metadata 和工具脚本；Kaggle CLI 负责把代码推到 Kaggle 远程运行。运行失败时，Codex 可以下载日志、定位错误并继续修复。

This is a lightweight agent scaffold for Kaggle experimentation. You write experiment ideas in ideas/idea.md; Codex follows AGENTS.md to update the Kaggle kernel, metadata, and helper tools; the Kaggle CLI pushes the kernel to Kaggle for remote execution. When a run fails, Codex can download logs, inspect the error, and iterate.

当前模板包含一个可运行的 Spaceship Titanic baseline，并支持参考用户选择的 public notebook 或本地资料。

The starter template includes a runnable Spaceship Titanic baseline and supports user-selected public notebooks or local reference files.

核心流程 / Workflow

1. 在 ideas/idea.md 写实验想法。
   Write the experiment idea in ideas/idea.md.
2. 让 Codex 读取 AGENTS.md，修改 kaggle_kernel/kernel.py 和必要配置。
   Let Codex read AGENTS.md and update kaggle_kernel/kernel.py plus required metadata.
3. 本地只做轻量检查。
   Run only lightweight local checks.
4. 用 Kaggle CLI 推到 Kaggle 远程运行。
   Push the kernel to Kaggle with the Kaggle CLI.
5. 下载输出和日志，让 Codex 根据日志继续迭代。
   Download outputs and logs, then let Codex iterate from the logs.

首次配置 / First-Time Setup

编辑 kaggle_kernel/kernel-metadata.json：

Edit kaggle_kernel/kernel-metadata.json:

• 把 your-kaggle-username/spaceship-titanic-codex-agent 换成你的 Kaggle 用户名和 kernel slug。
  Replace your-kaggle-username/spaceship-titanic-codex-agent with your Kaggle username and kernel slug.
• 根据比赛修改 competition_sources。
  Replace or update competition_sources for your target competition.

示例 / Example:

"id": "your-kaggle-username/spaceship-titanic-codex-agent",
"competition_sources": ["spaceship-titanic"]

安装并认证 Kaggle CLI：

Install and authenticate the Kaggle CLI:

python -m pip install kaggle

把 Kaggle API token 放在 Kaggle CLI 默认配置目录。不要把 kaggle.json 放进本仓库。

Place your Kaggle API token in the default Kaggle CLI config directory. Do not put kaggle.json in this repository.

写实验想法 / Write An Experiment Idea

编辑 / Edit:

ideas/idea.md

然后运行 / Then run:

powershell -ExecutionPolicy Bypass -File tools/run_codex.ps1

管理 Kaggle 数据源 / Manage Kaggle Sources

python tools/kaggle_meta.py show
python tools/kaggle_meta.py add dataset username/dataset-slug
python tools/kaggle_meta.py add competition competition-slug
python tools/kaggle_meta.py add kernel username/kernel-slug
python tools/kaggle_meta.py add model username/model-slug/framework/variation-slug/version-number

参考资源区 / Reference Resources

你可以把希望 Codex 参考的 public notebook、笔记、论文或代码片段放进 resources/。

Put public notebooks, notes, papers, or snippets that Codex may reference under resources/.

拉取 Kaggle 参考 notebook：

Pull a Kaggle reference notebook:

powershell -ExecutionPolicy Bypass -File tools/pull_reference_kernel.ps1 -KernelRef username/notebook-slug

手动资料放到：

Put manual notes or files under:

resources/local/

重建资源索引：

Rebuild the resource index:

python tools/index_resources.py

然后可以在 ideas/idea.md 里写：

Then write something like this in ideas/idea.md:

Reference the resources area, borrow useful feature engineering ideas, but keep the current kernel simple.

Codex 会先读 resources/RESOURCE_INDEX.md，再打开相关资源文件。

Codex should read resources/RESOURCE_INDEX.md first and then open only relevant files.

本地检查 / Local Checks

一键检查 / One command:

powershell -ExecutionPolicy Bypass -File tools/check_project.ps1

手动检查 / Manual checks:

python -m py_compile kaggle_kernel/kernel.py
python -m json.tool kaggle_kernel/kernel-metadata.json

推到 Kaggle / Push To Kaggle

powershell -ExecutionPolicy Bypass -File tools/push_kernel.ps1

如果比赛和账号允许，可以指定加速器：

Specify an accelerator if the competition and account allow it:

powershell -ExecutionPolicy Bypass -File tools/push_kernel.ps1 -Accelerator NvidiaTeslaT4

查看 Kaggle 结果 / Check Kaggle Results

kaggle kernels status your-kaggle-username/spaceship-titanic-codex-agent
kaggle kernels output your-kaggle-username/spaceship-titanic-codex-agent -p outputs\spaceship-titanic-codex-agent -o

忽略的本地文件 / Ignored Local Files

默认忽略这些不应该提交的本地产物：

The default ignore rules exclude local artifacts that should not be committed:

• outputs/
• data/
• resources/kaggle_notebooks/
• resources/local/
• resources/RESOURCE_INDEX.md
• kaggle.json, .env, model weights, archives, generated submissions, and large binary artifacts

这些规则用于避免把运行输出、下载的 notebook、私有数据和凭据提交到版本控制。

These rules keep generated outputs, downloaded notebooks, private data, and credentials out of version control.