from dataclasses import dataclass
@dataclass(frozen=True)
class Config:
seed: int = 42
data_path: str = “data/train.csv”
output_dir: str = “outputs”
config = Config()
print(config)

notebook_final.ipynb
notebook_final_v2.ipynb
try_again.py
submit_latest.csv

projects/ai-competition-review/
├── README.md
├── solution.md
├── configs/
├── data/
├── src/
├── outputs/
├── submissions/
└── reports/

python --version
uv --version
git --version

mkdir -p ~/Code/ustc-ai/week11-ai-competition-review
cd ~/Code/ustc-ai/week11-ai-competition-review
uv init --name week11-ai-competition-review
uv venv
source .venv/bin/activate.fish
uv add pandas numpy scikit-learn joblib
code .

mkdir -p configs data/raw data/processed src/competition_project outputs/models submissions reports notebooks

week11-ai-competition-review/
├── configs/
│   └── baseline.toml
├── data/
│   ├── raw/
│   │   ├── train.csv
│   │   └── test.csv
│   └── processed/
├── src/
│   └── competition_project/
│       ├── __init__.py
│       ├── config.py
│       ├── data.py
│       ├── features.py
│       ├── model.py
│       ├── train.py
│       ├── infer.py
│       └── utils.py
├── outputs/
│   └── models/
├── submissions/
├── reports/
│   └── experiments.md
├── notebooks/
├── README.md
└── solution.md

cp ~/Downloads/my-competition-messy/train.csv data/raw/train.csv
cp ~/Downloads/my-competition-messy/test.csv data/raw/test.csv
cp ~/Downloads/my-competition-messy/best_notes.ipynb notebooks/eda_original.ipynb

[paths]
train_csv = "data/raw/train.csv"
test_csv = "data/raw/test.csv"
model_path = "outputs/models/baseline.joblib"
submission_path = "submissions/baseline_submission.csv"
[target]
column = “target”
id_column = “id”
[train]
seed = 42
valid_size = 0.2
[model]
type = “random_forest”
n_estimators = 300
max_depth = 8

[target]
column = "target"
id_column = "id"

from __future__ import annotations
import tomllib
from pathlib import Path
from typing import Any
def load_config(path: str | Path) -> dict[str, Any]:
config_path = Path(path)
with config_path.open(“rb”) as file:
return tomllib.load(file)

from __future__ import annotations
import os
import random
from pathlib import Path
import numpy as np
def seed_everything(seed: int) -> None:
os.environ[“PYTHONHASHSEED”] = str(seed)
random.seed(seed)
np.random.seed(seed)
def ensure_parent(path: str | Path) -> None:
Path(path).parent.mkdir(parents=True, exist_ok=True)

from __future__ import annotations
import pandas as pd
def read_train_test(train_csv: str, test_csv: str) -> tuple[pd.DataFrame, pd.DataFrame]:
train = pd.read_csv(train_csv)
test = pd.read_csv(test_csv)
return train, test
def split_features_target(
train: pd.DataFrame,
target_column: str,
) -> tuple[pd.DataFrame, pd.Series]:
y = train[target_column]
x = train.drop(columns=[target_column])
return x, y

from __future__ import annotations
import pandas as pd
from sklearn.compose import ColumnTransformer
from sklearn.impute import SimpleImputer
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import OneHotEncoder, StandardScaler
def build_preprocessor(features: pd.DataFrame) -> ColumnTransformer:
numeric_columns = features.select_dtypes(include=[“number”, “bool”]).columns.tolist()
categorical_columns = [column for column in features.columns if column not in numeric_columns]
plain numeric_pipeline = Pipeline(
steps=[
(“imputer”, SimpleImputer(strategy=“median”)),
(“scaler”, StandardScaler()),
]
)
categorical_pipeline = Pipeline(
steps=[
(“imputer”, SimpleImputer(strategy=“most_frequent”)),
(“one_hot”, OneHotEncoder(handle_unknown=“ignore”)),
]
)
plain return ColumnTransformer(
transformers=[
(“numeric”, numeric_pipeline, numeric_columns),
(“categorical”, categorical_pipeline, categorical_columns),
]
)

from __future__ import annotations
from sklearn.ensemble import RandomForestClassifier
from sklearn.linear_model import LogisticRegression
def build_model(config: dict):
model_type = config[“model”][“type”]
seed = config[“train”][“seed”]
plain if model_type == “random_forest”:
return RandomForestClassifier(
n_estimators=config[“model”][“n_estimators”],
max_depth=config[“model”][“max_depth”],
random_state=seed,
n_jobs=-1,
)
plain if model_type == “logistic_regression”:
return LogisticRegression(max_iter=1000, random_state=seed)
plain raise ValueError(f”unsupported model type: {model_type}”)

from __future__ import annotations
import argparse
from pathlib import Path
import joblib
import pandas as pd
from sklearn.metrics import accuracy_score, f1_score
from sklearn.model_selection import train_test_split
from sklearn.pipeline import Pipeline
from competition_project.config import load_config
from competition_project.data import read_train_test, split_features_target
from competition_project.features import build_preprocessor
from competition_project.model import build_model
from competition_project.utils import ensure_parent, seed_everything
def parse_args() -> argparse.Namespace:
parser = argparse.ArgumentParser()
parser.add_argument(“—config”, type=Path, default=Path(“configs/baseline.toml”))
return parser.parse_args()
def main() -> None:
args = parse_args()
config = load_config(args.config)
seed_everything(config[“train”][“seed”])
plain train, _ = read_train_test(config[“paths”][“train_csv”], config[“paths”][“test_csv”])
features, target = split_features_target(train, config[“target”][“column”])
plain drop_columns = [config[“target”].get(“id_column”)]
drop_columns = [column for column in drop_columns if column and column in features.columns]
features = features.drop(columns=drop_columns)
plain x_train, x_valid, y_train, y_valid = train_test_split(
features,
target,
test_size=config[“train”][“valid_size”],
stratify=target if target.nunique() < 20 else None,
random_state=config[“train”][“seed”],
)
pipeline = Pipeline(
    steps=[
        (&quot;preprocess&quot;, build_preprocessor(x_train)),
        (&quot;model&quot;, build_model(config)),
    ]
)
pipeline.fit(x_train, y_train)
predictions = pipeline.predict(x_valid)

metrics = {
    &quot;accuracy&quot;: accuracy_score(y_valid, predictions),
    &quot;f1_macro&quot;: f1_score(y_valid, predictions, average=&quot;macro&quot;),
}
print(metrics)

model_path = Path(config[&quot;paths&quot;][&quot;model_path&quot;])
ensure_parent(model_path)
joblib.dump({&quot;pipeline&quot;: pipeline, &quot;config&quot;: config, &quot;metrics&quot;: metrics}, model_path)

report_path = Path(&quot;reports/baseline_metrics.csv&quot;)
ensure_parent(report_path)
pd.DataFrame([metrics]).to_csv(report_path, index=False)
print(f&quot;model saved to {model_path}&quot;)
print(f&quot;metrics saved to {report_path}&quot;)
if name == “main”:
main()

source .venv/bin/activate.fish
set -gx PYTHONPATH src
python -m competition_project.train --config configs/baseline.toml

from __future__ import annotations
import argparse
from pathlib import Path
import joblib
import pandas as pd
from competition_project.utils import ensure_parent
def parse_args() -> argparse.Namespace:
parser = argparse.ArgumentParser()
parser.add_argument(“—model”, type=Path, default=Path(“outputs/models/baseline.joblib”))
parser.add_argument(“—test”, type=Path, default=Path(“data/raw/test.csv”))
parser.add_argument(“—output”, type=Path, default=Path(“submissions/baseline_submission.csv”))
return parser.parse_args()
def main() -> None:
args = parse_args()
artifact = joblib.load(args.model)
pipeline = artifact[“pipeline”]
config = artifact[“config”]
plain test = pd.read_csv(args.test)
id_column = config[“target”].get(“id_column”)
ids = test[id_column] if id_column in test.columns else pd.Series(range(len(test)), name=“id”)
features = test.drop(columns=[id_column]) if id_column in test.columns else test
plain predictions = pipeline.predict(features)
submission = pd.DataFrame({id_column or “id”: ids, config[“target”][“column”]: predictions})
plain ensure_parent(args.output)
submission.to_csv(args.output, index=False)
print(f”submission saved to {args.output}”)
if name == “main”:
main()

source .venv/bin/activate.fish
set -gx PYTHONPATH src
python -m competition_project.infer --model outputs/models/baseline.joblib --test data/raw/test.csv --output submissions/baseline_submission.csv

.venv/
__pycache__/
*.pyc
.ipynb_checkpoints/
data/raw/
data/processed/
outputs/models/
submissions/*.csv

# Solution
Task

Competition / dataset name:
Prediction target:
Metric:

Data Cleaning

Missing values:
Categorical features:
Numeric features:

Baseline

Model:
Validation split:
Metric:

Improvements

Feature engineering tried:
Model changes tried:
Hyperparameters tried:

Result

Local validation:
Public leaderboard if available:
Private leaderboard if available:

My Contribution

I implemented:
I debugged:
I analyzed:

# Experiments





































ID
Date
Change
Valid Metric
Submission
Notes
exp001
2026-07-26
random forest baseline
fill
baseline_submission.csv
first clean run
exp002
2026-07-26
add feature group A
fill
compare with exp001

每次实验只记录一个主要变化。不要写“改了很多东西然后提升了”，那样无法复盘。
17. 练习

把 random_forest 改成 logistic_regression，记录指标差异。
增加一个简单特征，例如两个数值列的比值，并记录是否提升。
在 solution.md 中写清楚你负责的模块。如果原比赛中你只参与了一小部分，本周补做一个完整 baseline。
在 infer.py 里确认输出列名符合比赛提交格式。
把 notebook 中能复用的函数迁移到 src/competition_project/，notebook 只保留分析图和思路。

18. 验收检查
在项目根目录执行：
ompfish
source .venv/bin/activate.fish
set -gx PYTHONPATH src
test -f configs/baseline.toml; and test -f src/competition_project/train.py; and test -f src/competition_project/infer.py
test -f README.md; and test -f solution.md; and test -f reports/experiments.md
python -m competition_project.train --config configs/baseline.toml
python -m competition_project.infer --model outputs/models/baseline.joblib --test data/raw/test.csv --output submissions/baseline_submission.csv

通过标准：

train.py 可以训练并保存模型。
infer.py 可以读取模型并生成提交 CSV。
配置、随机种子、路径都不硬编码在 notebook 里。
solution.md 写清楚任务、方案、结果和你的贡献。
reports/experiments.md 至少有一条真实实验记录。

19. 常见错误
19.1 fish 环境没有激活
打开新终端后先执行：
ompfish
source .venv/bin/activate.fish

否则可能调用系统 Python，导致找不到 pandas 或 sklearn。
19.2 忘记设置 PYTHONPATH
如果看到 ModuleNotFoundError: No module named 'competition_project'，执行：
ompfish
set -gx PYTHONPATH src

然后重新运行 python -m competition_project.train。
19.3 配置文件 TOML 写错
TOML section 必须写成：
omptoml
[target]
column = "target"
id_column = "id"

不要漏掉左方括号。
19.4 训练和推理特征不一致
不要在 infer.py 里重新写一套预处理逻辑。正确做法是把预处理器和模型放在同一个 sklearn Pipeline 里，一起保存。
19.5 把数据和模型权重提交到 Git
先检查：
ompfish
git status --short

如果看到 data/raw/ 或 outputs/models/ 里的大文件准备提交，说明 .gitignore 没写好或文件已经被 Git 跟踪，需要先处理。
20. 下一步
进入 Week 12：把 Week 10 的深度学习项目或 Week 11 的比赛整理项目写成项目复盘报告。你会制作实验表、ablation、README、limitations，并学会用“证据”说明你的改进是否真的有效。
plain