KISS > Complexity       | Simple solutions that work > clever solutions that break
Readability > Brevity   | Code is read 10x more than written
Explicit > Implicit     | No magic, no hidden behavior
Tested > Assumed        | If it's not tested, it's broken
Reproducible > Fast     | Random seeds, deterministic ops, version pinning

Classification (images)     → ResNet/EfficientNet (simple), ViT (SOTA)
Object Detection           → YOLOv8 (speed), DETR (accuracy), RT-DETR (balanced)
Segmentation              → U-Net (medical), Mask2Former (general), SAM (zero-shot)
Text Classification       → DistilBERT (fast), RoBERTa (accuracy)
Text Generation           → Llama/Mistral (open), GPT-4 (quality)
Embeddings               → sentence-transformers, text-embedding-3-large
Time Series              → TSMixer, PatchTST, temporal fusion transformer
Tabular                  → XGBoost (general), TabNet (interpretable), FT-Transformer
Anomaly Detection        → IsolationForest (simple), AutoEncoder (deep)
Recommendation           → Two-tower, NCF, LightFM (cold start)

project/
├── pyproject.toml          # Dependencies, build config (NO setup.py)
├── .env.example            # Environment template
├── .gitignore
├── Makefile               # Common commands
├── README.md
├── src/
│   └── {project_name}/
│       ├── __init__.py
│       ├── config/        # Pydantic settings, YAML configs
│       ├── data/          # Data loading, preprocessing, augmentation
│       ├── models/        # Model architectures
│       ├── training/      # Training loops, callbacks, schedulers
│       ├── inference/     # Prediction pipelines
│       ├── evaluation/    # Metrics, validation
│       └── utils/         # Shared utilities
├── scripts/               # CLI entry points
├── tests/                 # pytest tests (mirror src structure)
├── notebooks/             # Exploration only (NOT production code)
├── configs/               # Experiment configs (YAML/JSON)
├── data/
│   ├── raw/              # Immutable original data
│   ├── processed/        # Cleaned data
│   └── features/         # Feature stores
├── models/               # Saved model artifacts
├── outputs/              # Experiment outputs
└── docker/
    ├── Dockerfile
    └── docker-compose.yml

def train_model(
    model: nn.Module,
    train_loader: DataLoader,
    optimizer: torch.optim.Optimizer,
    epochs: int = 10,
    device: str = "cuda",
) -> dict[str, list[float]]:
    ...

from pydantic import BaseModel, Field

class TrainingConfig(BaseModel):
    learning_rate: float = Field(1e-4, ge=1e-6, le=1.0)
    batch_size: int = Field(32, ge=1)
    epochs: int = Field(10, ge=1)
    seed: int = 42
    
    model_config = {"frozen": True}  # Immutable

import structlog
logger = structlog.get_logger()

undefined

undefined

undefined

def train_epoch(
    model: nn.Module,
    loader: DataLoader,
    optimizer: torch.optim.Optimizer,
    criterion: nn.Module,
    device: torch.device,
    scaler: GradScaler | None = None,
) -> float:
    model.train()
    total_loss = 0.0
    
    for batch in tqdm(loader, desc="Training"):
        optimizer.zero_grad(set_to_none=True)  # More efficient
        
        inputs = batch["input"].to(device, non_blocking=True)
        targets = batch["target"].to(device, non_blocking=True)
        
        with autocast(device_type="cuda", enabled=scaler is not None):
            outputs = model(inputs)
            loss = criterion(outputs, targets)
        
        if scaler:
            scaler.scale(loss).backward()
            scaler.unscale_(optimizer)
            torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm=1.0)
            scaler.step(optimizer)
            scaler.update()
        else:
            loss.backward()
            torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm=1.0)
            optimizer.step()
        
        total_loss += loss.item()
    
    return total_loss / len(loader)