Cifar100/AGENTS.md

Repository Guidelines

This document provides coding conventions and workflow guidance for contributing to the CIFAR-100 WideResNet classification project.

Project Structure & Module Organization

The project follows a standard src layout for clean packaging and distribution:

Cifar100/
├── src/cifar100/          # Core package modules
│   ├── config.py          # Model configuration presets (2GB/4GB/8GB)
│   ├── data.py            # Dataset loading and augmentation
│   ├── model.py           # WideResNet architecture implementation
│   ├── trainer.py         # Training and evaluation loops
│   └── visualizer.py      # Training metrics visualization
├── main.py                # Main training script entry point
├── test_memory.py         # GPU memory usage testing utility
├── plots/                 # Generated training visualization outputs
└── dist/                  # Build artifacts (wheel packages)

Key modules:

• config.py: Memory-optimized configurations for different GPU sizes
• model.py: WideResNet blocks with GELU activation, dropout, and label smoothing
• trainer.py: Gradient accumulation, label smoothing, early stopping logic
• visualizer.py: Matplotlib-based training curve plotting

Build, Test, and Development Commands

Installation:

# Recommended: Install with uv package manager
uv sync

# Alternative: Install with pip
pip install .

Run training:

python main.py

Memory testing:

python test_memory.py

Build distribution:

python -m build

Coding Style & Naming Conventions

• Indentation: 4 spaces (Python PEP 8 standard)
• Imports: Group standard library, third-party, and local imports separately
• Docstrings: Use triple quotes for module and function documentation
• Naming:
  • Classes: PascalCase (e.g., WideResNet, TrainingVisualizer)
  • Functions/methods: snake_case (e.g., train_epoch, get_config)
  • Constants: UPPER_SNAKE_CASE (e.g., CONFIG_4GB)
  • Private methods: prefix with underscore (e.g., _initialize_weights)
• File naming: Use snake_case for Python modules

Code patterns:

• Use torch.device for GPU/CPU device management
• Apply gradient accumulation via accumulation_steps parameter
• Include memory optimization: torch.cuda.empty_cache(), gc.collect()
• Use non_blocking=True for async GPU transfers

Testing Guidelines

This project does not currently have a formal test suite. For validation:

• Run test_memory.py to verify GPU memory usage across configurations
• Monitor training metrics (loss/accuracy) to validate model changes
• Check visualizations in plots/ directory after training runs

Manual validation checklist:

• Model loads without errors
• Training completes at least 10 epochs
• Memory usage stays within GPU limits
• Plots are generated correctly

Commit & Pull Request Guidelines

Commit message format (based on project history):

<type>: <brief description>

Types:
- docs: Documentation updates (README, comments)
- build: Build system or dependencies
- chore: Maintenance tasks (version bumps, cleanup)
- feat: New features
- fix: Bug fixes

Examples:

• docs: Update README.md with installation instructions
• build: Add build artifacts to dist/
• chore: Fix version badge repository link

Before committing:

1. Verify code runs without errors
2. Test memory usage if modifying model architecture
3. Update relevant documentation (README, docstrings)
4. Clean up any debug print statements

Configuration & Memory Management

Memory presets in config.py:

• 2gb: WRN-16-2, batch_size=32, accumulation_steps=4
• 4gb: WRN-22-4, batch_size=64, accumulation_steps=2 (default)
• 8gb: WRN-28-10, batch_size=128, accumulation_steps=1

To modify configuration:

config = get_config("4gb")  # Choose preset
# Or override specific parameters
config["learning_rate"] = 0.05

Memory optimization techniques used:

• Gradient accumulation to simulate larger batch sizes
• Periodic torch.cuda.empty_cache() calls
• cudnn.benchmark = True for performance
• Gradient clipping at max_norm=1.0