pl-ml-project-template

name	pl-ml-project-template
description	Scaffold a PyTorch Lightning project for classification, regression, or timeseries research. Triggers on "新建项目", "initialize project", "scaffold", "create PL project". Not for LLM/PEFT/RAG/agent stacks.

PL ML Project Template

Use this skill when the user wants a reusable PyTorch Lightning project structure for standard supervised research tasks.

Supported template types:

• classification
• regression
• timeseries

Do not use this skill for:

• LLM pretraining or instruction tuning
• PEFT / LoRA / QLoRA projects
• RAG, agents, MCP services
• inference-serving repositories
• pure scikit-learn projects that do not need Lightning

Workflow

1. Confirm the target task type from the user request or infer the closest one:
   • image/tabular category prediction -> classification
   • continuous target prediction -> regression
   • sequential prediction / sensor forecasting -> timeseries
2. Run scripts/init_project.py to scaffold the project.
3. Tell the user which files must be edited first:
   • configs/default.yaml
   • data/dataset/standard_dataset.py
   • model/standard_model.py
   • model/model_interface.py
4. If the task is domain-specific, adapt metrics and losses after scaffold generation rather than inventing a brand new structure.

Commands

Initialize a classification project:

python scripts/init_project.py /path/to/project --task-type classification

Initialize a regression project:

python scripts/init_project.py /path/to/project --task-type regression

Initialize a time series project:

python scripts/init_project.py /path/to/project --task-type timeseries

Overwrite existing template files only when explicitly requested:

python scripts/init_project.py /path/to/project --task-type timeseries --force

Generated Scripts

Script	Purpose	Command
scripts/train.sh	Train model	make train
scripts/test.sh	Test model	make test
scripts/visualize.py	Plot training curves to figures/	make visualize
scripts/export_results.py	Results JSON → LaTeX table	make export
scripts/run_all.sh	One-click reproduce: train→test→viz→export	make all
scripts/ablation.sh	Ablation study with parameter sweep	make ablation

Open-Source Readiness

The scaffold generates all files needed for a publishable repo:

• README.md with quick start, structure, citation
• Makefile for one-command workflows
• .env.example for environment configuration
• .gitignore covering logs, checkpoints, secrets
• docs/doc/ for paper materials with naming convention
• results/ for experiment outputs

Document Version Convention

Files in docs/doc/ follow: YYYY-MM-DD_description_vN.ext

• Example: 2026-04-27_ablation_results_v1.tex
• Increment vN for revisions, never reuse version numbers

Design Notes

This skill intentionally follows a project-interface pattern:

• main.py stays thin
• data/data_interface.py owns the LightningDataModule
• model/model_interface.py owns the LightningModule
• dataset and model files remain replaceable units

Naming convention:

• file names use snake_case
• classes use CamelCase
• standard_model.py -> StandardModel
• standard_dataset.py -> StandardDataset

Read references/template-design.md when you need the rationale or want to extend the scaffold.

Post-Scaffold Verification

After scaffolding, run a quick smoke test:

cd /path/to/project
python -c "from model import MInterface; from data import DInterface; print('OK')"

If using a GPU environment, also verify training wiring:

python main.py --max_epochs 1 --devices 1

Common Pitfalls

Problem	Cause	Fix
ModuleNotFoundError on import	File named my_net.py but class is MyNetwork	Class must be MyNet — strict snake_case → CamelCase conversion
Model not found	--model_name doesn't match file name	--model_name foo_bar expects model/foo_bar.py with class FooBar
Config not applied	CLI args override YAML	YAML only fills args that are None; explicit CLI wins
train=True/False ignored	Dataset __init__ doesn't accept train param	Add train parameter to your custom dataset