Training API v2.1.1

Release Notes - v2.1.1 (Pre-Release)

Release Date: December 21, 2025

---

🎉 What's New in v2.1.1

This pre-release introduces the Training API - a simple way to train and evaluate your models on common datasets like MNIST, CIFAR-10, and CIFAR-100 without writing boilerplate training loops.

---

✨ New Features

Training API

Train your hybrid models with just a few lines of code:

from torchvision_customizer import HybridBuilder, Trainer

# Build a customized model
model = HybridBuilder().from_torchvision(
    "resnet18",
    weights="IMAGENET1K_V1",
    patches={"layer3": {"wrap": "se"}},
    num_classes=10,
)

# Create trainer and train on CIFAR-10
trainer = Trainer(model, device='auto')
metrics = trainer.fit_cifar10(epochs=10, lr=0.001)

print(metrics.summary())

Trainer Class

Method	Description
fit(train_loader, val_loader)	Train on custom data loaders
fit_mnist(epochs, batch_size, lr)	Train on MNIST dataset
fit_cifar10(epochs, batch_size, lr)	Train on CIFAR-10 dataset
fit_cifar100(epochs, batch_size, lr)	Train on CIFAR-100 dataset
evaluate(data_loader)	Evaluate model on any data loader

Quick Training Function

For even simpler usage, use quick_train():

from torchvision_customizer import HybridBuilder, quick_train

model = HybridBuilder().from_torchvision("resnet18", num_classes=10)
metrics = quick_train(model, dataset='cifar10', epochs=5)

Supported Features

• Optimizers: Adam, AdamW, SGD (with momentum)
• Schedulers: Cosine Annealing, Step LR, OneCycle
• Device: Automatic CPU/CUDA detection
• Data Augmentation: Built-in for CIFAR datasets
• Metrics: Training loss, accuracy, validation loss/accuracy, timing

TrainingMetrics Class

Track your training progress with detailed metrics:

metrics = trainer.fit_cifar10(epochs=10)

print(f"Best accuracy: {metrics.best_val_acc:.2%}")
print(f"Best epoch: {metrics.best_epoch}")
print(metrics.summary())

---

🐛 Bug Fixes

Hybrid Builder - Parameter Detection

Issue: When wrapping blocks like CBAM or ECA, the builder incorrectly passed in_channels to blocks that only accept channels.

Fix: Smart parameter detection using inspect.signature() to determine which parameters each block accepts.

# Now works correctly
model = HybridBuilder().from_torchvision(
    "resnet18",
    patches={"layer3": {"wrap": "cbam_block"}},  # ✅ Fixed
    num_classes=10,
)

Stage Patterns - MBConv Support

Issue: Stage class didn't recognize mbconv or fused_mbconv patterns.

Fix: Added support for EfficientNet-style blocks:

from torchvision_customizer import Stage

# Now works
stage = Stage(channels=64, blocks=3, pattern='mbconv')
stage = Stage(channels=64, blocks=3, pattern='fused_mbconv')

Recipe Parser - Parameter Shortcuts

Issue: Documentation mentioned shortcuts like k and s but they weren't implemented.

Fix: Added parameter shortcuts that expand automatically:

Shortcut	Expands To
k	kernel_size
s	stride
p	padding
g	groups
e	expansion
r	reduction
d	dropout

# Both work now
recipe = Recipe(stem="conv(64, k=7, s=2)")  # Using shortcuts
recipe = Recipe(stem="conv(64, kernel_size=7, stride=2)")  # Full names

Stem Class - kernel_size Alias

Issue: Stem class only accepted kernel but recipe parser expanded k to kernel_size.

Fix: Added kernel_size as an alias for kernel:

# Both work now
stem = Stem(64, kernel=7)
stem = Stem(64, kernel_size=7)  # ✅ New alias

---

📁 New Files

File	Description
torchvision_customizer/hybrid/trainer.py	Training API implementation
tests/test_trainer.py	Tests for trainer module
examples/train_mnist.py	MNIST training example
examples/train_cifar10.py	CIFAR-10 training example
examples/quick_train_example.py	Quick training examples

---

📦 Installation

pip install git+https://github.com/codewithdark-git/torchvision-customizer.git

---

🔄 Upgrade from v2.1.0

v2.1.1 is fully backward compatible with v2.1.0. Simply update your installation:

pip install --upgrade git+https://github.com/codewithdark-git/torchvision-customizer.git

---

📋 Full Changelog

See CHANGELOG.md for complete version history.

---

🙏 Contributors

• @codewithdark-git

Hybrid Models v2.1.0

Version 2.1.0 introduces Hybrid Models - the ability to load torchvision pre-trained models and customize them with your own blocks, attention mechanisms, and architectural modifications. This release also adds new building blocks, enhanced YAML recipes, and a CLI for rapid prototyping.

---

✨ Key Features

1. Hybrid Builder 🔧

Load any torchvision pre-trained model and customize it while preserving maximum weights.

from torchvision_customizer import HybridBuilder

builder = HybridBuilder()
model = builder.from_torchvision(
    "resnet50",
    weights="IMAGENET1K_V2",
    patches={
        "layer3": {"wrap": "se"},           # Add SE attention
        "layer4": {"wrap": "cbam_block"},   # Add CBAM
    },
    num_classes=100,
    dropout=0.3,
)

# Freeze backbone for fine-tuning
model.freeze_backbone(unfreeze_stages=[3])  # Keep last stage trainable

Supported Backbones:

• ResNet family (18, 34, 50, 101, 152)
• EfficientNet (B0-B7, V2)
• ConvNeXt (Tiny, Small, Base, Large)
• MobileNet (V2, V3)
• VGG (11, 13, 16, 19)
• DenseNet (121, 169, 201)
• Vision Transformer (ViT)
• Swin Transformer

2. Weight Utilities 📦

Smart weight loading with mismatch tolerance and detailed reports.

from torchvision_customizer import partial_load, transfer_weights

# Load weights with mismatch tolerance
report = partial_load(model, state_dict, ignore_mismatch=True)
print(report.summary())
# Output:
# Loaded:           95% of parameters
# Shape Mismatch:   12 parameters
# Newly Initialized: 5 parameters

# Transfer weights between models
transfer_weights(pretrained, custom, exclude_patterns=['fc', 'classifier'])

3. New Building Blocks 🧱

Block	Description	Use Case
CBAMBlock	Convolutional Block Attention Module	Feature recalibration
ECABlock	Efficient Channel Attention	Lightweight attention
DropPath	Stochastic Depth regularization	Training deeper networks
Mish	Self-regularizing activation	Smoother gradients
GeM	Generalized Mean Pooling	Image retrieval
MBConv	Mobile Inverted Bottleneck	EfficientNet-style blocks
FusedMBConv	Fused MBConv (EfficientNetV2)	Faster training
LayerScale	Per-channel scaling	Vision Transformers

from torchvision_customizer import CBAMBlock, ECABlock, DropPath

# Apply CBAM attention
cbam = CBAMBlock(channels=256, reduction=16)

# Efficient channel attention
eca = ECABlock(channels=512)

# Stochastic depth for residual
drop_path = DropPath(drop_prob=0.2)
out = x + drop_path(residual)

4. Enhanced YAML Recipes 📝

JSONSchema validation, inheritance, and macro expansion.

# my_model.yaml
name: ResNet50-SE-Custom
version: "1.0.0"

# Macros for reuse
macros:
  attention: se
  dropout: 0.3

# Use pretrained backbone
backbone:
  name: resnet50
  weights: IMAGENET1K_V2
  patches:
    layer3:
      wrap:
        type: "@attention"
        params:
          reduction: 16
    layer4:
      wrap: cbam_block

# Custom head
head:
  num_classes: 100
  dropout: "@dropout"

Recipe Inheritance:

# my_custom.yaml
extends: resnet_base  # Built-in template or file path
stages:
  - pattern: residual
    channels: 128
    blocks: 4
    attention: se  # Add attention to stages

5. CLI Prototyper 🖥️

Command-line tools for rapid model development.

# Build model from recipe
tvc build --yaml my_model.yaml --output model.pt

# Benchmark performance
tvc benchmark --yaml my_model.yaml --device cuda --batch-size 32

# Validate recipe
tvc validate --yaml my_model.yaml --strict

# Export to ONNX
tvc export --yaml my_model.yaml --format onnx --output model.onnx

# List available backbones
tvc list-backbones

# List available blocks
tvc list-blocks --category attention

# Create recipe from template
tvc create-recipe --template hybrid_resnet_se --output custom.yaml

---

🆕 New Modules

Module	Purpose
torchvision_customizer.hybrid	Hybrid model building
torchvision_customizer.hybrid.weight_utils	Weight loading utilities
torchvision_customizer.hybrid.extractor	Backbone structure extraction
torchvision_customizer.recipe.schema	JSONSchema validation
torchvision_customizer.recipe.yaml_loader	Enhanced YAML loading
torchvision_customizer.cli	Command-line interface

---

🛠️ API Additions

# New top-level imports
from torchvision_customizer import (
    # Hybrid
    HybridBuilder,
    partial_load,
    transfer_weights,
    extract_tiers,
    get_backbone_info,
    
    # New blocks
    CBAMBlock,
    ECABlock,
    DropPath,
    Mish,
    GeM,
    MBConv,
    FusedMBConv,
)

# Recipe enhancements
from torchvision_customizer.recipe import (
    load_yaml_recipe,
    load_yaml_config,
    save_yaml_recipe,
    validate_recipe_config,
    expand_macros,
    list_templates,
    create_recipe_from_template,
)

---

📊 Quick Example: Fine-tune ResNet50 with Attention

from torchvision_customizer import HybridBuilder

# Create hybrid model
builder = HybridBuilder()
model = builder.from_torchvision(
    "resnet50",
    weights="IMAGENET1K_V2",
    patches={
        "layer3": {"wrap": "se"},
        "layer4": {"wrap": "cbam_block"},
    },
    num_classes=10,
    freeze_backbone=True,
    unfreeze_stages=[3],  # Only train last stage + head
)

# Print model info
print(model.explain())

# Training loop
for images, labels in dataloader:
    outputs = model(images)
    loss = criterion(outputs, labels)
    # ...

---

📦 Dependencies

New optional dependencies for v2.1:

• pyyaml>=6.0 (for YAML recipes)
• jsonschema>=4.0 (optional, for strict validation)

---

🔄 Migration from v2.0

v2.1 is fully backward compatible with v2.0. All existing code will continue to work:

# v2.0 code still works
from torchvision_customizer import Stem, Stage, Head
model = Stem(64) >> Stage(128, blocks=3) >> Head(10)

# v2.0 templates still work  
from torchvision_customizer import resnet
model = resnet(layers=50, num_classes=1000)

# v2.0 recipes still work
from torchvision_customizer import Recipe, build_recipe
recipe = Recipe(stem="conv(64)", stages=["residual(128) x 3"], head="linear(10)")
model = build_recipe(recipe)

---

🔗 Contributors

• @codewithdark-git (Architecture & Implementation)

---

📈 What's Next (v2.2 Roadmap)

• ONNX optimization and quantization
• AutoML architecture search integration
• Multi-GPU training utilities
• Pre-built fine-tuning pipelines
• Hugging Face Hub integration

---

📚 Full Changelog

Added:

• HybridBuilder for pre-trained model customization
• Weight utilities (partial_load, transfer_weights)
• 12 new building blocks (CBAM, ECA, DropPath, Mish, GeM, MBConv, etc.)
• YAML recipe schema validation
• Recipe inheritance and macros
• CLI (tvc command)
• Backbone extraction utilities

Improved:

• Registry now includes 30+ blocks
• Better error messages for validation failures
• Documentation updates

Fixed:

• Minor type hint corrections
• Windows compatibility improvements

⭐ Star us on GitHub • 🐛 Report Bug • 💬 Discussions

The 3-Tier API Architecture

Release Notes v2.0.0

🚀 Major Release: The 3-Tier API Architecture

Version 2.0.0 represents a complete paradigm shift for torchvision-customizer. We have moved away from the monolithic CustomCNN class to a flexible, component-based 3-tier architecture that offers unprecedented control over model design.

---

✨ Key Features

1. Tier 1: Component Registry 🗂️

The new registry system serves as the single source of truth for all building blocks.

• Unified Discovery: registry.list('block') to find all available components.
• Easy Access: registry.get('residual') returns the class directly.
• Extensible: Easily register your own components with @registry.register.

2. Tier 2: Architecture Recipes 📜

A declarative way to define models using human-readable strings. Perfect for config-driven experiments.

• String Definitions: "residual(64) x 2 | downsample"
• Serialization: Recipes can be saved/loaded from YAML/JSON.
• Safety: Automated parsing ensures valid arguments.

3. Tier 3: Model Composer 🎼

A fluent, pythonic API for building models programmatically.

• Operator Overloading: Use >> for sequential connection, | for branching, and * for repetition.
• Context Awareness: Stage and Head automatically infer input channels.
• Mix & Match: Combine different patterns (e.g., 'residual+se') in a single stage.

4. Parametric Templates 🏗️

We have re-implemented standard architectures from scratch to be fully parametric and customizable. No pre-trained weights, just pure architectural flexibility.

• ResNet: 18, 34, 50, 101, 152 (Basic & Bottleneck)
• VGG: 11, 13, 16, 19
• MobileNet: V1, V2, V3 (Small/Large)
• DenseNet: 121, 169, 201, 264
• EfficientNet: B0-B7

---

💥 Breaking Changes

• Removed CustomCNN: The legacy CustomCNN class and the old torchvision_customizer.models module have been removed. Please migrate to Recipe or Compose.
• Python Version: Minimum Python version lowered to 3.9 (previously 3.13) for better compatibility.

---

🛠️ Improvements

• Model Introspection: Added model.explain() for a beautiful, ASCII-art summary of your custom architecture.
• Windows Support: Fixed character encoding issues in model visualization.
• Strict Typing: Comprehensive type hints across the entire codebase.
• Documentation: Completely rewritten documentation to reflect the new API tiers.

---

📦 Quick Example

Before (v1.x):

model = CustomCNN(layers=50, architecture='resnet') # Limited customization

After (v2.0):

# Declarative
recipe = Recipe(stem="conv(64)", stages=["residual(64) x 3"], head="linear(10)")
model = build_recipe(recipe)

# OR Fluent
model = Stem(64) >> Stage(64, blocks=3, pattern='residual') >> Head(10)

---

🔗 Contributors

• @codewithdark-git (Architecture & Implementation)

torchvision-customizer v1.0.0

Version 1.0.0 - Initial Release

A flexible CNN architecture builder for PyTorch.

Features

• Modular CNN components (blocks, layers, models)
• Multiple APIs (simple, builder pattern, configuration-based)
• 382+ tests, 113+ examples
• Comprehensive documentation
• Production-ready

Links

• Documentation
• PyPI
• GitHub