.cursorrules (deprecated)

1# AI/ML Python Projects — Cursor Rules
2# Production ML: PyTorch, data pipelines, experiment tracking, and deployment
3 
4# Project Context
5You are building an AI/ML project with Python. The project uses PyTorch for model training,
6handles data pipelines with proper validation, tracks experiments systematically, and follows
7production ML engineering practices. Code is type-hinted, tested, and reproducible.
8 
9# Project Structure
10```
11project/
12  src/
13    data/
14      datasets.py           # PyTorch Dataset classes
15      transforms.py         # Data augmentation and preprocessing
16      loaders.py            # DataLoader configurations
17      validation.py         # Data quality checks
18    models/
19      architectures/        # Model definitions
20        resnet.py
21        transformer.py
22      losses.py             # Custom loss functions
23      metrics.py            # Evaluation metrics
24    training/
25      trainer.py            # Training loop
26      callbacks.py          # Training callbacks (early stopping, checkpointing)
27      optimizers.py         # Optimizer configurations
28    inference/
29      predictor.py          # Inference pipeline
30      postprocess.py        # Output postprocessing
31    utils/
32      config.py             # Configuration management
33      logging.py            # Experiment logging
34      reproducibility.py    # Seed setting, deterministic mode
35  configs/
36    train_config.yaml       # Training hyperparameters
37    model_config.yaml       # Model architecture config
38  scripts/
39    train.py                # Training entry point
40    evaluate.py             # Evaluation script
41    export.py               # Model export (ONNX, TorchScript)
42  notebooks/
43    exploration.ipynb       # Data exploration (not production code)
44  tests/
45    test_data.py
46    test_models.py
47    test_training.py
48```
49 
50# PyTorch Model Patterns
51- Inherit from `nn.Module`. Always call `super().__init__()`.
52- Type hint all method signatures:
53```python
54  class ClassificationHead(nn.Module):
55      def __init__(self, in_features: int, num_classes: int, dropout: float = 0.1) -> None:
56          super().__init__()
57          self.dropout = nn.Dropout(dropout)
58          self.fc = nn.Linear(in_features, num_classes)
59 
60      def forward(self, x: torch.Tensor) -> torch.Tensor:
61          x = self.dropout(x)
62          return self.fc(x)
63```
64- Use `nn.Sequential` or `nn.ModuleList` for dynamic layer construction — never regular Python lists.
65- Register buffers for non-parameter tensors: `self.register_buffer('mean', torch.zeros(3))`.
66- Use `@torch.no_grad()` for inference methods.
67- DON'T: Use numpy operations inside `forward()` — they break autograd.
68- DON'T: Create tensors in `forward()` without sending to the correct device.
69 
70# Data Pipeline Patterns
71- Create custom `Dataset` classes with proper `__len__` and `__getitem__`:
72```python
73  class ImageDataset(Dataset):
74      def __init__(self, root: Path, transform: Compose | None = None) -> None:
75          self.paths = sorted(root.glob("*.jpg"))
76          self.transform = transform
77 
78      def __len__(self) -> int:
79          return len(self.paths)
80 
81      def __getitem__(self, idx: int) -> dict[str, torch.Tensor]:
82          image = read_image(str(self.paths[idx]))
83          if self.transform:
84              image = self.transform(image)
85          label = self._extract_label(self.paths[idx])
86          return {"image": image, "label": label}
87```
88- Validate data before training: check for NaNs, correct shapes, label distribution.
89- Use `DataLoader` with `num_workers > 0` and `pin_memory=True` for GPU training.
90- Implement data augmentation in transforms, not in the dataset class.
91- Cache preprocessed data when preprocessing is expensive.
92- DON'T: Load entire dataset into memory — use lazy loading in `__getitem__`.
93- DON'T: Use random transforms without seeding for reproducibility.
94 
95# Training Loop Best Practices
96- Use a structured training loop with proper phases:
97```python
98  def train_epoch(
99      model: nn.Module,
100      loader: DataLoader,
101      optimizer: Optimizer,
102      criterion: nn.Module,
103      device: torch.device,
104  ) -> dict[str, float]:
105      model.train()
106      total_loss = 0.0
107      correct = 0
108      total = 0
109 
110      for batch in loader:
111          inputs = batch["image"].to(device, non_blocking=True)
112          targets = batch["label"].to(device, non_blocking=True)
113 
114          optimizer.zero_grad(set_to_none=True)  # More efficient than zero_grad()
115          outputs = model(inputs)
116          loss = criterion(outputs, targets)
117          loss.backward()
118          torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm=1.0)
119          optimizer.step()
120 
121          total_loss += loss.item() * inputs.size(0)
122          correct += (outputs.argmax(dim=1) == targets).sum().item()
123          total += inputs.size(0)
124 
125      return {"loss": total_loss / total, "accuracy": correct / total}
126```
127- Use gradient clipping to prevent exploding gradients.
128- Use `optimizer.zero_grad(set_to_none=True)` for better memory efficiency.
129- Use `torch.cuda.amp` for mixed precision training (significant speedup):
130```python
131  scaler = GradScaler()
132  with autocast(device_type='cuda'):
133      outputs = model(inputs)
134      loss = criterion(outputs, targets)
135  scaler.scale(loss).backward()
136  scaler.step(optimizer)
137  scaler.update()
138```
139- Save checkpoints with model state, optimizer state, epoch, and metrics.
140 
141# Experiment Tracking
142- Use Weights & Biases (wandb), MLflow, or TensorBoard for experiment tracking.
143- Log ALL hyperparameters at experiment start:
144```python
145  wandb.init(project="my-project", config={
146      "learning_rate": 3e-4,
147      "batch_size": 32,
148      "epochs": 100,
149      "architecture": "resnet50",
150      "optimizer": "AdamW",
151      "weight_decay": 0.01,
152      "scheduler": "cosine",
153  })
154```
155- Log metrics every epoch: train loss, val loss, learning rate, custom metrics.
156- Log artifacts: model checkpoints, confusion matrices, sample predictions.
157- Name experiments descriptively: `resnet50-lr3e4-bs32-cosine-augv2`.
158- DON'T: Manually track experiments in spreadsheets — use proper tooling.
159- DON'T: Overwrite previous experiment results.
160 
161# Configuration Management
162- Use YAML or TOML files for configuration, not hardcoded values:
163```yaml
164  # configs/train_config.yaml
165  training:
166    epochs: 100
167    batch_size: 32
168    learning_rate: 0.0003
169    weight_decay: 0.01
170    scheduler: cosine
171    warmup_epochs: 5
172  model:
173    architecture: resnet50
174    pretrained: true
175    num_classes: 10
176    dropout: 0.1
177```
178- Parse configs with Pydantic for validation:
179```python
180  class TrainingConfig(BaseModel):
181      epochs: int = Field(ge=1)
182      batch_size: int = Field(ge=1)
183      learning_rate: float = Field(gt=0)
184```
185- Support config overrides via CLI arguments.
186- Save the full config with every experiment for reproducibility.
187 
188# Reproducibility
189- Set seeds explicitly at the start of every experiment:
190```python
191  def set_seed(seed: int) -> None:
192      random.seed(seed)
193      np.random.seed(seed)
194      torch.manual_seed(seed)
195      torch.cuda.manual_seed_all(seed)
196      torch.backends.cudnn.deterministic = True
197      torch.backends.cudnn.benchmark = False
198```
199- Pin dependency versions in `requirements.txt` or `pyproject.toml`.
200- Use `torch.use_deterministic_algorithms(True)` when exact reproducibility is required.
201- Log the git commit hash with every experiment.
202- Save train/val/test split definitions (indices or file lists), not just random seeds.
203 
204# Model Evaluation
205- Always evaluate on a held-out test set that was NEVER used during training or validation.
206- Report multiple metrics: accuracy, precision, recall, F1, AUC-ROC (as appropriate).
207- Use confusion matrices for classification tasks.
208- Report confidence intervals or standard deviation across multiple runs.
209- Analyze failure cases — don't just report aggregate metrics.
210 
211# Model Export and Deployment
212- Export models to ONNX or TorchScript for production serving:
213```python
214  # ONNX export
215  dummy_input = torch.randn(1, 3, 224, 224, device=device)
216  torch.onnx.export(model, dummy_input, "model.onnx", opset_version=17)
217```
218- Validate exported model outputs match PyTorch model outputs.
219- Version models with metadata: architecture, training config, metrics, data version.
220- Use batch inference for throughput, single inference for latency.
221 
222# Notebook Discipline
223- Notebooks are for exploration ONLY — never production code.
224- Move any code that works into proper Python modules.
225- Clear all outputs before committing notebooks.
226- Keep notebooks numbered and documented: `01-data-exploration.ipynb`, `02-baseline-model.ipynb`.
227 
228# Testing ML Code
229- Test data loading: correct shapes, dtypes, value ranges.
230- Test model forward pass: output shape matches expected for given input.
231- Test training step: loss decreases after one gradient update on a small batch.
232- Test data transforms: correct output shapes, value ranges, augmentation effects.
233- Use small datasets and few epochs for fast testing.
234- Test edge cases: empty batch, single sample, maximum sequence length.
235 
236# Common Mistakes to Avoid
237- DON'T: Train and evaluate on the same data split.
238- DON'T: Tune hyperparameters on the test set — use a validation set.
239- DON'T: Use Python lists for tensors in `forward()` — use `nn.ModuleList`.
240- DON'T: Forget to call `model.eval()` during inference.
241- DON'T: Forget to move data to the same device as the model.
242- DON'T: Ignore data leakage between train and validation splits.
243- DON'T: Skip normalization or standardization of input features.
244