API reference¶
The public API is generated from the installed package. The CLI is a thin orchestration layer over these modules.
Configuration¶
cnn_classifier.config
¶
Typed configuration package.
apply_overrides(raw, overrides)
¶
Apply a.b=value overrides without silently growing the schema.
load_config(path, overrides=())
¶
Load, compose, resolve, and validate an experiment configuration.
resolve_config(config, base_dir)
¶
Resolve data paths relative to the experiment file's directory.
validate_config_semantics(config)
¶
Reject cross-field combinations that would fail midway through a run.
Data¶
cnn_classifier.data
¶
Reusable data layer for dataset adapters, splits, and image contracts.
DatasetAdapter
¶
Bases: Protocol
Builds a train/val/test bundle from a data configuration.
build(config)
staticmethod
¶
Return the resolved datasets and their contracts.
Manifest
dataclass
¶
from_csv(path, image_root, columns)
classmethod
¶
Read a CSV manifest and validate every referenced image path.
fingerprint_records(records)
¶
Return a deterministic fingerprint independent of manifest row order.
assert_no_group_overlap(split, groups)
¶
Raise when a group appears in more than one split.
group_split_indices(groups, val_fraction, seed)
¶
Assign whole groups to train or validation, never splitting a group.
random_split_indices(labels, val_fraction, seed)
¶
Split indices with a seeded permutation, without stratification.
stratified_split_indices(labels, val_fraction, seed)
¶
Split each class proportionally, then combine the class splits.
Models¶
cnn_classifier.models
¶
Model builders and registry.
ModelBuilder
¶
Bases: Protocol
build(params, context)
staticmethod
¶
Construct a model from validated parameters and context.
build_model(config, *, num_classes, in_channels, image_size)
¶
Resolve, validate, and construct the configured model.
register_model(name)
¶
Register a model builder class under name.
model_summary(model, input_shape)
¶
Return parameter counts, module details, and output shape.
apply_stem_adaptation(model, mode, in_channels=3)
¶
Adapt a torchvision stem for native 32x32 inputs.
apply_transfer(model, transfer, *, stem_adaptation)
¶
Apply freezing, BatchNorm policy, and validation for a transfer run.
build_param_groups(model, transfer, *, base_lr, base_weight_decay)
¶
Build disjoint optimizer groups, validating every regex pattern.
replace_classifier(model, num_classes, dropout=0.0)
¶
Replace the final classifier with a task-specific head.
unfreeze_modules(model, names)
¶
Unfreeze every parameter under the named submodules.
Training¶
cnn_classifier.training
¶
Training components: optimization, scheduling, losses, AMP, and callbacks.
EarlyStopping
¶
Bases: _NoOpCallback
restore_from_history(history, fallback)
¶
Restore best value and patience progress after a resume.
ModelCheckpoint
¶
Bases: _NoOpCallback
restore_best(best)
¶
Restore the best monitored value after a resume.
autocast_context(policy)
¶
Enter autocast when the policy is enabled; otherwise do nothing.
resolve_amp(device, requested)
¶
Resolve the requested AMP mode against the actual device.
build_loss(config)
¶
Build the configured classification loss.
mixup_cutmix_batch(images, labels, mixup_alpha, cutmix_alpha, generator)
¶
Apply MixUp, CutMix, or neither, returning labels for both mixtures.
build_optimizer(model, config, param_groups=None)
¶
Build Adam, AdamW, or SGD with the configured hyperparameters.
build_scheduler(optimizer, config, epochs)
¶
Build the configured scheduler; warmup is explicit.
Evaluation¶
cnn_classifier.evaluation
¶
Evaluation metrics, calibration, bootstrap, comparisons, and inference.
bootstrap_ci(y_true, y_pred, metric_fn, n_resamples=1000, confidence=0.95, seed=0, stratify=False)
¶
Return a percentile bootstrap interval for one prediction set.
paired_bootstrap_difference(y_true, pred_a, pred_b, metric_fn, n_resamples=1000, confidence=0.95, seed=0, stratify=False)
¶
Return a bootstrap interval for metric(a) - metric(b).
expected_calibration_error(probabilities, y_true, n_bins=15)
¶
Compute ECE, MCE, Brier score, and reliability bins.
confusion_pairs(y_true, y_pred, class_names)
¶
Return off-diagonal confusion pairs sorted by count.
most_confident_errors(probabilities, y_true, class_names, max_examples=32)
¶
Return wrong predictions ranked by model confidence.
evaluate_model(model, loader, device, class_names, config)
¶
Evaluate on a loader without touching training or test state.
save_predictions(result, path)
¶
Save prediction arrays in a portable .npz archive.
measure_latency(model, input_shape, device, warmup=20, iterations=100)
¶
Measure single-image forward-pass latency with warmup and sync.
accuracy(y_true, y_pred)
¶
Return top-1 accuracy for equal-length arrays.
classification_metrics(y_true, y_pred, probabilities, class_names, top_k=3)
¶
Compute top-k, per-class, confusion, NLL, and calibration metrics.
predict_paths(model, paths, transform, device, class_names)
¶
Predict a sequence of images without requiring a DataLoader.
Diagnostics¶
cnn_classifier.diagnostics
¶
Diagnostics: overfit checks, shape tracing, gradients, activations, determinism.
activation_report(model, batch)
¶
Record mean, std, and zero fraction for each ReLU activation.
architecture_stages(model, input_shape)
¶
Return concise stage descriptors for a built-in CNN.
The built-in simple_cnn and residual_cnn families and torchvision
ResNet models get precise grouping. Other models fall back to their
top-level children.
determinism_check(train_fn, seed)
¶
Run a callable twice with the same seed and compare its result.
gradient_report(model)
¶
Return norm and zero fraction for every parameter with a gradient.
overfit_batch(model, batch, loss_fn, optimizer, device, max_steps=100, target_loss=0.01)
¶
Train one batch to a small loss, restoring the model mode.
trace_shapes(model, input_shape)
¶
Run one dummy input and report each module's shapes.
Visualization and reporting¶
cnn_classifier.viz
¶
Visualization and reporting helpers.
plot_cnn_pipeline(stages, *, input_shape, num_classes, path, title)
¶
Draw a concise, publication-style CNN stage pipeline.
plot_model_card(summary, path)
¶
Render a contract-style summary table as a figure.
compute_gradcam(model, image, target_class)
¶
Return a normalized Grad-CAM heatmap for one image.
build_markdown_report(run_dir)
¶
Return a Markdown report with the same numbers as the HTML report.
build_report(run_dir, output_path=None)
¶
Render a self-contained HTML report from saved run artifacts.
save_figure(fig, path)
¶
Save a figure as PNG and its SVG sibling; return the requested path.
set_style()
¶
Apply the package's colorblind-safe plotting defaults.
plot_training_history(history, path, title='Training history')
¶
Plot loss, accuracy, learning rate, and gradient norm panels.
CLI entry points¶
cnn_classifier.cli
¶
Command-line entry point for cnn-classifier.
doctor()
¶
Print package and runtime information.
init(directory=typer.Argument(Path('cnn_project'), help='Project directory to create.'), force=typer.Option(False, '--force', help='Overwrite an existing scaffold.'))
¶
Create a starter config, README, and data layout.
inspect_data(config_path=typer.Option(..., '-c', '--config', exists=True, dir_okay=False), set_values=_SET_OPTION, max_samples=typer.Option(None, '--max-samples', help='Limit inspection work per split.'))
¶
Report class balance, duplicates, corruption, leakage, and the model contract.
debug(config_path=typer.Option(..., '-c', '--config', exists=True, dir_okay=False), set_values=_SET_OPTION, overfit=typer.Option(False, '--overfit-batch', help='Overfit a single batch.'), gradients=typer.Option(False, '--gradients', help='Print per-layer gradient norms.'), determinism=typer.Option(False, '--determinism', help='Check repeated seeded training steps.'), trace=typer.Option(False, '--trace', help='Print module shape traces.'), steps=typer.Option(100, '--steps', help='Maximum overfit steps.'))
¶
Run cheap training diagnostics without plotting or writing a run.
train(config_path=typer.Option(..., '-c', '--config', exists=True, dir_okay=False), set_values=_SET_OPTION, resume=typer.Option(None, '--resume', help='Checkpoint to resume from.'), dry_run=typer.Option(False, '--dry-run', help='Validate without training.'), runs_dir=typer.Option(Path('runs'), '--runs-dir', help='Directory for new runs.'), allow_config_change=typer.Option(False, '--allow-config-change', help='Allow resuming with a changed config.'), no_evaluate=typer.Option(False, '--no-evaluate', help='Skip test evaluation.'))
¶
Train a model from a YAML configuration.
evaluate(checkpoint=typer.Option(..., '--checkpoint', exists=True, dir_okay=False), config_path=typer.Option(None, '-c', '--config', exists=True, dir_okay=False, help="Config override; defaults to the run's resolved config."), split=typer.Option('test', '--split', help='Split to evaluate: test or val.'), set_values=_SET_OPTION, run_dir=typer.Option(None, '--run', help='Run directory for artifacts.'), allow_config_change=typer.Option(False, '--allow-config-change'), no_figures=typer.Option(False, '--no-figures', help='Skip figure generation.'))
¶
Evaluate a checkpoint on a held-out split and write artifacts.
report(run=typer.Option(..., '--run', exists=True, file_okay=False), config_path=typer.Option(None, '-c', '--config', exists=True, dir_okay=False, help='Optional config to load.'))
¶
Build HTML and Markdown reports from an existing run directory.
predict(checkpoint=typer.Option(..., '--checkpoint', exists=True, dir_okay=False), input_path=typer.Option(..., '--input', exists=True, help='Image, folder, or manifest CSV.'), config_path=typer.Option(None, '-c', '--config', exists=True, dir_okay=False, help="Config override; defaults to the run's resolved config."), output=typer.Option(Path('predictions.csv'), '--output', help='CSV or JSON output.'), image_root=typer.Option(None, '--image-root', help='Base directory for relative manifest paths.'), top_k=typer.Option(3, '--top-k', help='Number of probabilities to report.'), set_values=_SET_OPTION, allow_config_change=typer.Option(False, '--allow-config-change'))
¶
Predict an image, a folder of images, or a manifest.
compare(run_dirs=typer.Argument(..., exists=True, file_okay=False), output_dir=typer.Option(Path('results/comparison'), '--out', help='Output directory.'), no_figure=typer.Option(False, '--no-figure', help='Skip the comparison figure.'))
¶
Compare runs that share the same test fingerprint.
main()
¶
Console-script entry point.