cnn-classifier-toolkit 0.1.0__py3-none-any.whl

cnn_classifier/config/__init__.py

@@ -0,0 +1,17 @@
+"""Typed configuration package."""
+
+from cnn_classifier.config.loader import apply_overrides, load_config
+from cnn_classifier.config.resolve import resolve_config, validate_config_semantics
+from cnn_classifier.config.schema import (
+    RunConfig,
+    TransformConfig,
+)
+
+__all__ = [
+    "RunConfig",
+    "TransformConfig",
+    "apply_overrides",
+    "load_config",
+    "resolve_config",
+    "validate_config_semantics",
+]

cnn_classifier/config/loader.py

@@ -0,0 +1,102 @@
+"""YAML configuration loading, composition, and CLI overrides."""
+
+from __future__ import annotations
+
+import copy
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from cnn_classifier.config.resolve import resolve_config, validate_config_semantics
+from cnn_classifier.config.schema import RunConfig
+from cnn_classifier.core.errors import ConfigError
+
+_DEFAULT_CONFIG = Path(__file__).with_name("presets") / "default.yaml"
+
+
+def _load_yaml(path: Path) -> dict[str, Any]:
+    try:
+        payload = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except OSError as exc:
+        raise ConfigError(f"cannot read config {path}: {exc}") from exc
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"invalid YAML in {path}: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise ConfigError(f"config {path} must contain a YAML mapping")
+    return payload
+
+
+def deep_merge(base: Mapping[str, Any], override: Mapping[str, Any]) -> dict[str, Any]:
+    """Merge mappings recursively; lists and scalars replace."""
+    merged = copy.deepcopy(dict(base))
+    for key, value in override.items():
+        if isinstance(value, Mapping) and isinstance(merged.get(key), Mapping):
+            merged[key] = deep_merge(merged[key], value)
+        else:
+            merged[key] = copy.deepcopy(value)
+    return merged
+
+
+def _load_chain(path: Path, seen: set[Path]) -> dict[str, Any]:
+    resolved = path.resolve()
+    if resolved in seen:
+        raise ConfigError(f"cyclic defaults chain at {path}")
+    seen = {*seen, resolved}
+    payload = _load_yaml(resolved)
+    defaults = payload.pop("defaults", [])
+    if not isinstance(defaults, list):
+        raise ConfigError(f"defaults in {path} must be a list")
+    merged: dict[str, Any] = {}
+    for entry in defaults:
+        if not isinstance(entry, str):
+            raise ConfigError(f"defaults entries in {path} must be strings")
+        merged = deep_merge(merged, _load_chain(resolved.parent / entry, seen))
+    return deep_merge(merged, payload)
+
+
+def apply_overrides(raw: Mapping[str, Any], overrides: Sequence[str]) -> dict[str, Any]:
+    """Apply ``a.b=value`` overrides without silently growing the schema."""
+    result = copy.deepcopy(dict(raw))
+    for override in overrides:
+        if "=" not in override:
+            raise ConfigError(f"override must be key=value; got {override!r}")
+        dotted, value_text = override.split("=", 1)
+        parts = dotted.split(".")
+        cursor: Any = result
+        for part in parts[:-1]:
+            if not isinstance(cursor, dict) or part not in cursor:
+                raise ConfigError(f"unknown override path: {dotted}")
+            cursor = cursor[part]
+        leaf = parts[-1]
+        if not isinstance(cursor, dict) or leaf not in cursor:
+            raise ConfigError(f"unknown override path: {dotted}")
+        try:
+            parsed = yaml.safe_load(value_text)
+        except yaml.YAMLError as exc:
+            raise ConfigError(f"invalid override value for {dotted}: {value_text!r}") from exc
+        cursor[leaf] = parsed
+    return result
+
+
+def load_config(path: str | Path, overrides: Sequence[str] = ()) -> RunConfig:
+    """Load, compose, resolve, and validate an experiment configuration."""
+    config_path = Path(path)
+    if not config_path.is_file():
+        raise ConfigError(f"config file does not exist: {config_path}")
+    packaged = _load_yaml(_DEFAULT_CONFIG)
+    merged = deep_merge(packaged, _load_chain(config_path, seen=set()))
+    if overrides:
+        try:
+            resolved_defaults = RunConfig.model_validate(merged)
+        except Exception as exc:
+            raise ConfigError(f"invalid configuration {config_path}: {exc}") from exc
+        merged = apply_overrides(resolved_defaults.model_dump(mode="json"), overrides)
+    try:
+        config = RunConfig.model_validate(merged)
+    except Exception as exc:
+        raise ConfigError(f"invalid configuration {config_path}: {exc}") from exc
+    config = resolve_config(config, config_path.resolve().parent)
+    validate_config_semantics(config)
+    return config

cnn_classifier/config/presets/default.yaml

@@ -0,0 +1,47 @@
+schema_version: "1.0"
+
+runtime:
+  device: auto
+  deterministic: true
+  num_workers: auto
+  persistent_workers: true
+  pin_memory: auto
+  channels_last: false
+  compile: false
+
+tracking:
+  console: true
+  csv: true
+  tensorboard: true
+
+report:
+  enabled: true
+  formats: [html, markdown]
+  figures:
+    - training_history
+    - confusion_matrix
+    - per_class
+    - calibration
+    - errors
+    - model_summary
+
+evaluation:
+  metrics: [accuracy, top_k, macro_f1, per_class, confusion_matrix, ece, nll]
+  top_k: 3
+  bootstrap:
+    enabled: true
+    n_resamples: 1000
+    confidence: 0.95
+    stratify: true
+  calibration:
+    bins: 15
+  latency:
+    enabled: true
+    warmup: 20
+    iterations: 100
+  error_analysis:
+    max_examples: 32
+  tta:
+    enabled: false
+    transforms: [identity, hflip]
+    reduction: mean_probabilities

cnn_classifier/config/resolve.py

@@ -0,0 +1,108 @@
+"""Path resolution and semantic validation for configuration."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from cnn_classifier.config.schema import DataConfig, RunConfig
+from cnn_classifier.core.errors import ConfigError
+
+
+def _absolute(path: Path | None, base_dir: Path) -> Path | None:
+    if path is None:
+        return None
+    return path if path.is_absolute() else (base_dir / path).resolve()
+
+
+def resolve_config(config: RunConfig, base_dir: Path) -> RunConfig:
+    """Resolve data paths relative to the experiment file's directory."""
+    data = config.data.model_copy(
+        update={
+            "root": _absolute(config.data.root, base_dir),
+            "manifest": _absolute(config.data.manifest, base_dir),
+            "image_root": _absolute(config.data.image_root, base_dir),
+        }
+    )
+    return config.model_copy(update={"data": data})
+
+
+def _check_channel_lengths(data: DataConfig) -> None:
+    norm = data.normalization
+    if norm.mode != "supplied":
+        return
+    if norm.mean is None or norm.std is None:
+        raise ConfigError("supplied normalization requires mean and std")
+    if len(norm.mean) != len(norm.std):
+        raise ConfigError("normalization mean and std must have the same length")
+    expected = {"rgb": 3, "gray": 1}.get(data.channels)
+    if expected is not None and len(norm.mean) != expected:
+        raise ConfigError(
+            f"normalization has {len(norm.mean)} channels but data.channels={data.channels!r}"
+        )
+
+
+def validate_config_semantics(config: RunConfig) -> None:
+    """Reject cross-field combinations that would fail midway through a run."""
+    training = config.training
+    data = config.data
+    scheduler = training.scheduler
+
+    if training.epochs <= 0:
+        raise ConfigError("training.epochs must be positive")
+    if training.batch_size <= 0:
+        raise ConfigError("training.batch_size must be positive")
+    if training.grad_accum_steps <= 0:
+        raise ConfigError("training.grad_accum_steps must be positive")
+    if scheduler.warmup_epochs >= training.epochs:
+        raise ConfigError("scheduler.warmup_epochs must be smaller than training.epochs")
+    if not 0.0 <= scheduler.min_lr_ratio < 1.0:
+        raise ConfigError("scheduler.min_lr_ratio must be in [0, 1)")
+    if training.optimizer.lr <= 0:
+        raise ConfigError("optimizer.lr must be positive")
+    if training.optimizer.weight_decay < 0:
+        raise ConfigError("optimizer.weight_decay must be non-negative")
+    if not 0.0 <= training.loss.label_smoothing < 1.0:
+        raise ConfigError("loss.label_smoothing must be in [0, 1)")
+    if not 0.0 <= training.mixup_alpha <= 1.0:
+        raise ConfigError("training.mixup_alpha must be in [0, 1]")
+    if not 0.0 <= training.cutmix_alpha <= 1.0:
+        raise ConfigError("training.cutmix_alpha must be in [0, 1]")
+    if training.ema.enabled and not 0.0 < training.ema.decay < 1.0:
+        raise ConfigError("training.ema.decay must be in (0, 1)")
+    if training.early_stopping.patience < 0:
+        raise ConfigError("early_stopping.patience must be non-negative")
+    if training.amp == "fp16" and config.runtime.device in {"cpu", "mps"}:
+        raise ConfigError("fp16 AMP is only supported on CUDA devices")
+
+    if data.image_size[0] <= 0 or data.image_size[1] <= 0:
+        raise ConfigError("data.image_size dimensions must be positive")
+    if data.num_classes is not None and data.num_classes <= 0:
+        raise ConfigError("data.num_classes must be positive")
+    if data.split.mode in {"random", "random_stratified", "group"} and not (
+        0.0 < data.split.val_fraction < 1.0
+    ):
+        raise ConfigError("data.split.val_fraction must be in (0, 1)")
+    if (
+        isinstance(data.class_names, tuple)
+        and data.num_classes is not None
+        and len(data.class_names) != data.num_classes
+    ):
+        raise ConfigError("data.class_names length must match data.num_classes")
+    if data.value_range.mode == "fixed":
+        if data.value_range.min is None or data.value_range.max is None:
+            raise ConfigError("fixed value_range requires min and max")
+        if data.value_range.min >= data.value_range.max:
+            raise ConfigError("value_range.min must be smaller than value_range.max")
+    _check_channel_lengths(data)
+
+    bootstrap = config.evaluation.bootstrap
+    if bootstrap.n_resamples <= 0:
+        raise ConfigError("bootstrap.n_resamples must be positive")
+    if not 0.0 < bootstrap.confidence < 1.0:
+        raise ConfigError("bootstrap.confidence must be in (0, 1)")
+    if config.evaluation.calibration.bins <= 0:
+        raise ConfigError("calibration.bins must be positive")
+    if config.evaluation.latency.warmup < 0:
+        raise ConfigError("latency.warmup must be non-negative")
+    if config.evaluation.latency.iterations <= 0:
+        raise ConfigError("latency.iterations must be positive")

cnn_classifier/config/schema.py

@@ -0,0 +1,251 @@
+"""Typed configuration models for cnn-classifier.
+
+Known keys are validated strictly; adapter and model parameters remain flexible
+and are validated by their registered builders. Cross-field physical checks live
+in :mod:`cnn_classifier.config.resolve` so they raise :class:`ConfigError`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+SCHEMA_VERSION = "1.0"
+
+
+class ConfigModel(BaseModel):
+    """Base for strict configuration models."""
+
+    model_config = ConfigDict(extra="forbid", allow_inf_nan=False)
+
+
+class ExperimentConfig(ConfigModel):
+    name: str
+    tags: tuple[str, ...] = ()
+    notes: str = ""
+    seed: int = 42
+
+
+class SplitConfig(ConfigModel):
+    mode: Literal["random", "random_stratified", "group", "explicit", "train_only"] = (
+        "random_stratified"
+    )
+    val_fraction: float = 0.1
+    seed: int = 42
+    group_column: str | None = None
+
+
+class NormalizationConfig(ConfigModel):
+    mode: Literal["compute", "supplied", "none"] = "compute"
+    mean: tuple[float, ...] | None = None
+    std: tuple[float, ...] | None = None
+    cache: bool = True
+
+
+class ValueRangeConfig(ConfigModel):
+    mode: Literal["auto", "fixed"] = "auto"
+    min: float | None = None
+    max: float | None = None
+
+
+class TransformConfig(ConfigModel):
+    model_config = ConfigDict(extra="allow", allow_inf_nan=False)
+
+    name: str
+
+    def params(self) -> dict[str, Any]:
+        """Return the transform-specific parameters."""
+        return dict(self.model_extra or {})
+
+
+def _empty_transforms() -> dict[Literal["train", "eval"], list[TransformConfig]]:
+    return {"train": [], "eval": []}
+
+
+class DataConfig(ConfigModel):
+    adapter: str
+    root: Path | None = None
+    manifest: Path | None = None
+    image_root: Path | None = None
+    class_names: tuple[str, ...] | Literal["auto"] = "auto"
+    num_classes: int | None = None
+    channels: Literal["rgb", "gray", "as_is"] = "rgb"
+    image_size: tuple[int, int] = (32, 32)
+    split: SplitConfig = Field(default_factory=SplitConfig)
+    normalization: NormalizationConfig = Field(default_factory=NormalizationConfig)
+    transforms: dict[Literal["train", "eval"], list[TransformConfig]] = Field(
+        default_factory=_empty_transforms
+    )
+    value_range: ValueRangeConfig = Field(default_factory=ValueRangeConfig)
+    adapter_params: dict[str, Any] = Field(default_factory=dict)
+
+
+class ParamGroupConfig(ConfigModel):
+    pattern: str
+    lr_multiplier: float = 1.0
+    weight_decay_multiplier: float = 1.0
+
+
+class UnfreezeEvent(ConfigModel):
+    epoch: int
+    modules: tuple[str, ...]
+
+
+class TransferConfig(ConfigModel):
+    weights: str | None = None
+    freeze: Literal["none", "backbone", "all_but_head"] = "none"
+    train_bn: bool = False
+    unfreeze_schedule: tuple[UnfreezeEvent, ...] = ()
+    param_groups: tuple[ParamGroupConfig, ...] = ()
+
+
+class ModelConfig(ConfigModel):
+    name: str
+    params: dict[str, Any] = Field(default_factory=dict)
+    transfer: TransferConfig = Field(default_factory=TransferConfig)
+
+
+class OptimizerConfig(ConfigModel):
+    name: Literal["adam", "adamw", "sgd"] = "adamw"
+    lr: float = 1e-3
+    weight_decay: float = 0.0
+    momentum: float = 0.9
+
+
+class SchedulerConfig(ConfigModel):
+    name: Literal["constant", "cosine", "cosine_warmup", "step", "plateau"] = "cosine"
+    warmup_epochs: int = 0
+    min_lr_ratio: float = 0.0
+    step_size: int = 10
+    gamma: float = 0.1
+    step_unit: Literal["epoch", "batch"] = "epoch"
+
+
+class LossConfig(ConfigModel):
+    name: Literal["cross_entropy"] = "cross_entropy"
+    label_smoothing: float = 0.0
+
+
+class EMAConfig(ConfigModel):
+    enabled: bool = False
+    decay: float = 0.999
+
+
+class EarlyStoppingConfig(ConfigModel):
+    enabled: bool = True
+    monitor: str = "val_accuracy"
+    mode: Literal["min", "max"] = "max"
+    patience: int = 10
+    min_delta: float = 0.0
+
+
+class CheckpointConfig(ConfigModel):
+    monitor: str = "val_accuracy"
+    mode: Literal["min", "max"] = "max"
+    save_last: bool = True
+
+
+class TrainingConfig(ConfigModel):
+    epochs: int = 50
+    batch_size: int = 128
+    grad_accum_steps: int = 1
+    selection_metric: str = "val_accuracy"
+    optimizer: OptimizerConfig = Field(default_factory=OptimizerConfig)
+    scheduler: SchedulerConfig = Field(default_factory=SchedulerConfig)
+    loss: LossConfig = Field(default_factory=LossConfig)
+    grad_clip_norm: float | None = None
+    amp: Literal["auto", "off", "fp16", "bf16"] = "auto"
+    mixup_alpha: float = 0.0
+    cutmix_alpha: float = 0.0
+    ema: EMAConfig = Field(default_factory=EMAConfig)
+    early_stopping: EarlyStoppingConfig = Field(default_factory=EarlyStoppingConfig)
+    checkpoint: CheckpointConfig = Field(default_factory=CheckpointConfig)
+
+
+class BootstrapConfig(ConfigModel):
+    enabled: bool = True
+    n_resamples: int = 1000
+    confidence: float = 0.95
+    stratify: bool = True
+
+
+class CalibrationConfig(ConfigModel):
+    bins: int = 15
+
+
+class LatencyConfig(ConfigModel):
+    enabled: bool = True
+    warmup: int = 20
+    iterations: int = 100
+
+
+class ErrorAnalysisConfig(ConfigModel):
+    max_examples: int = 32
+
+
+class TTAConfig(ConfigModel):
+    enabled: bool = False
+    transforms: tuple[Literal["identity", "hflip"], ...] = ("identity", "hflip")
+    reduction: Literal["mean_probabilities"] = "mean_probabilities"
+
+
+class EvaluationConfig(ConfigModel):
+    metrics: tuple[str, ...] = (
+        "accuracy",
+        "top_k",
+        "macro_f1",
+        "per_class",
+        "confusion_matrix",
+        "ece",
+        "nll",
+    )
+    top_k: int = 3
+    bootstrap: BootstrapConfig = Field(default_factory=BootstrapConfig)
+    calibration: CalibrationConfig = Field(default_factory=CalibrationConfig)
+    latency: LatencyConfig = Field(default_factory=LatencyConfig)
+    error_analysis: ErrorAnalysisConfig = Field(default_factory=ErrorAnalysisConfig)
+    tta: TTAConfig = Field(default_factory=TTAConfig)
+
+
+class TrackingConfig(ConfigModel):
+    console: bool = True
+    csv: bool = True
+    tensorboard: bool = True
+
+
+class ReportConfig(ConfigModel):
+    enabled: bool = True
+    formats: tuple[Literal["html", "markdown"], ...] = ("html", "markdown")
+    figures: tuple[str, ...] = (
+        "training_history",
+        "confusion_matrix",
+        "per_class",
+        "calibration",
+        "errors",
+        "model_summary",
+    )
+
+
+class RuntimeConfig(ConfigModel):
+    device: str = "auto"
+    deterministic: bool = True
+    num_workers: int | Literal["auto"] = "auto"
+    persistent_workers: bool = True
+    pin_memory: bool | Literal["auto"] = "auto"
+    channels_last: bool = False
+    compile: bool = False
+
+
+class RunConfig(ConfigModel):
+    schema_version: Literal["1.0"] = "1.0"
+    defaults: tuple[str, ...] = ()
+    experiment: ExperimentConfig
+    data: DataConfig
+    model: ModelConfig
+    training: TrainingConfig = Field(default_factory=TrainingConfig)
+    evaluation: EvaluationConfig = Field(default_factory=EvaluationConfig)
+    tracking: TrackingConfig = Field(default_factory=TrackingConfig)
+    report: ReportConfig = Field(default_factory=ReportConfig)
+    runtime: RuntimeConfig = Field(default_factory=RuntimeConfig)

cnn_classifier/core/__init__.py

@@ -0,0 +1,19 @@
+"""Core package: errors, registries, device policy, seeding, and hashing."""
+
+from cnn_classifier.core.errors import (
+    CnnClassifierError,
+    ConfigError,
+    DataError,
+    RegistryError,
+    RunError,
+)
+from cnn_classifier.core.registry import Registry
+
+__all__ = [
+    "CnnClassifierError",
+    "ConfigError",
+    "DataError",
+    "Registry",
+    "RegistryError",
+    "RunError",
+]

cnn_classifier/core/device.py

@@ -0,0 +1,50 @@
+"""Device resolution for CUDA, Apple MPS, and CPU."""
+
+from __future__ import annotations
+
+import platform
+
+import torch
+
+from cnn_classifier.core.errors import ConfigError
+
+
+def resolve_device(spec: str = "auto") -> torch.device:
+    """Resolve ``auto`` or an explicit device string into a ``torch.device``.
+
+    ``auto`` prefers CUDA, then MPS, then CPU. Explicit CUDA or MPS requests are
+    rejected when the backend is unavailable, so a run never silently changes
+    hardware.
+    """
+    value = spec.strip().lower()
+    if value == "auto":
+        if torch.cuda.is_available():
+            return torch.device("cuda")
+        if torch.backends.mps.is_available():
+            return torch.device("mps")
+        return torch.device("cpu")
+
+    try:
+        device = torch.device(value)
+    except (RuntimeError, ValueError) as exc:
+        raise ConfigError(f"invalid device {spec!r}") from exc
+
+    if device.type == "cuda" and not torch.cuda.is_available():
+        raise ConfigError(f"CUDA device {spec!r} requested but CUDA is unavailable")
+    if device.type == "mps" and not torch.backends.mps.is_available():
+        raise ConfigError(f"MPS device {spec!r} requested but MPS is unavailable")
+    if device.type not in {"cpu", "cuda", "mps"}:
+        raise ConfigError(f"unsupported device type {device.type!r}")
+    return device
+
+
+def device_report() -> dict[str, object]:
+    """Return runtime and device availability information."""
+    return {
+        "device": str(resolve_device("auto")),
+        "cuda_available": torch.cuda.is_available(),
+        "mps_available": torch.backends.mps.is_available(),
+        "torch_version": torch.__version__,
+        "python_version": platform.python_version(),
+        "platform": platform.platform(),
+    }

cnn_classifier/core/errors.py

@@ -0,0 +1,21 @@
+"""Exception hierarchy for cnn-classifier."""
+
+
+class CnnClassifierError(Exception):
+    """Base class for all package-specific errors."""
+
+
+class ConfigError(CnnClassifierError):
+    """A configuration is malformed or incompatible with the selected device."""
+
+
+class DataError(CnnClassifierError):
+    """A dataset, image, manifest, or split is invalid."""
+
+
+class RegistryError(CnnClassifierError):
+    """A registry lookup or registration failed."""
+
+
+class RunError(CnnClassifierError):
+    """A run, checkpoint, or artifact is invalid."""

cnn_classifier/core/hashing.py

@@ -0,0 +1,18 @@
+"""Stable hashing for configs, manifests, and run fingerprints."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+
+
+def stable_hash(payload: object) -> str:
+    """Return a short canonical SHA-256 hash of a JSON-compatible payload."""
+    text = json.dumps(
+        payload,
+        sort_keys=True,
+        separators=(",", ":"),
+        default=str,
+        allow_nan=False,
+    )
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()[:16]

cnn_classifier/core/registry.py

@@ -0,0 +1,46 @@
+"""Small typed registries for datasets, models, transforms, and components."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Generic, TypeVar
+
+from cnn_classifier.core.errors import RegistryError
+
+T = TypeVar("T")
+
+
+class Registry(Generic[T]):
+    """A name-to-factory registry with explicit duplicate and lookup errors."""
+
+    def __init__(self, name: str) -> None:
+        self._name = name
+        self._items: dict[str, T] = {}
+
+    def register(self, name: str) -> Callable[[T], T]:
+        """Return a decorator that registers an item under ``name``."""
+        cleaned = name.strip()
+        if not cleaned:
+            raise RegistryError(f"{self._name} registry cannot register an empty name")
+        if cleaned in self._items:
+            raise RegistryError(f"{cleaned!r} is already registered in {self._name}")
+
+        def decorator(item: T) -> T:
+            self._items[cleaned] = item
+            return item
+
+        return decorator
+
+    def get(self, name: str) -> T:
+        """Return the item registered under ``name``."""
+        try:
+            return self._items[name]
+        except KeyError as exc:
+            available = ", ".join(self._items) or "<none>"
+            raise RegistryError(
+                f"{name!r} is not registered in {self._name}; available: {available}"
+            ) from exc
+
+    def names(self) -> tuple[str, ...]:
+        """Return registered names in insertion order."""
+        return tuple(self._items)