Upload folder using huggingface_hub

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+outputs/exports/alphabet_model.ts filter=lfs diff=lfs merge=lfs -text

alphabet/dataset.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import torch
+from torch.utils.data import DataLoader, Dataset
+from torchvision import transforms
+from torchvision.datasets import EMNIST
+
+# EMNIST "letters" split: labels 1–26 map to A–Z
+ALPHABET_CLASSES = list("ABCDEFGHIJKLMNOPQRSTUVWXYZ")
+
+
+def _fix_emnist_orientation(t: torch.Tensor) -> torch.Tensor:
+    # EMNIST images are stored transposed; this corrects to normal orientation.
+    return t.permute(0, 2, 1).flip(1)
+
+
+class AlphabetDataset(Dataset):
+    """Wraps EMNIST 'letters' with orientation fix and optional augmentation."""
+
+    def __init__(
+        self,
+        root: str | Path,
+        train: bool = True,
+        img_size: int = 64,
+        augment: bool = False,
+        mean: float = 0.5,
+        std: float = 0.5,
+    ) -> None:
+        self.emnist = EMNIST(root=str(root), split="letters", train=train, download=True)
+        self.transform = self._build_transform(img_size, augment, mean, std)
+
+    def _build_transform(
+        self, img_size: int, augment: bool, mean: float, std: float
+    ) -> transforms.Compose:
+        ops: list[Any] = [transforms.Grayscale(num_output_channels=1)]
+        if augment:
+            ops.extend([
+                transforms.RandomAffine(
+                    degrees=10,
+                    translate=(0.08, 0.08),
+                    scale=(0.88, 1.12),
+                    shear=8,
+                    fill=255,
+                ),
+                transforms.RandomPerspective(distortion_scale=0.15, p=0.25, fill=255),
+                transforms.ColorJitter(brightness=0.20, contrast=0.20),
+                transforms.GaussianBlur(kernel_size=3, sigma=(0.1, 1.5)),
+            ])
+        ops.extend([
+            transforms.Resize((img_size, img_size)),
+            transforms.ToTensor(),
+            # EMNIST images are stored transposed relative to normal orientation.
+            # This corrects them so the model sees normally-oriented letters,
+            # matching the real letter crops it will receive at inference time.
+            transforms.Lambda(_fix_emnist_orientation),
+            transforms.Normalize(mean=[mean], std=[std]),
+        ])
+        if augment:
+            ops.append(transforms.RandomErasing(p=0.10, scale=(0.02, 0.10), value=1.0))
+        return transforms.Compose(ops)
+
+    def __len__(self) -> int:
+        return len(self.emnist)
+
+    def __getitem__(self, idx: int) -> dict[str, Any]:
+        image, label = self.emnist[idx]
+        tensor = self.transform(image)
+        # EMNIST letters are 1-indexed (1=A … 26=Z); convert to 0-indexed
+        label_idx = int(label) - 1
+        return {
+            "image": tensor,
+            "label": torch.tensor(label_idx, dtype=torch.long),
+        }
+
+
+def _collate(batch: list[dict[str, Any]]) -> dict[str, Any]:
+    images = torch.stack([b["image"] for b in batch], dim=0)
+    labels = torch.stack([b["label"] for b in batch], dim=0)
+    return {"image": images, "label": labels}
+
+
+def build_dataloaders(cfg: dict[str, Any], device: str = "cpu") -> tuple[DataLoader, DataLoader]:
+    data_cfg = cfg["data"]
+    model_cfg = cfg["model"]
+    train_cfg = cfg["train"]
+
+    img_size = int(model_cfg.get("img_size", 64))
+    mean = float(model_cfg.get("mean", 0.5))
+    std = float(model_cfg.get("std", 0.5))
+    root = data_cfg.get("root", "data/emnist")
+    batch_size = int(train_cfg.get("batch_size", 256))
+    num_workers = int(train_cfg.get("num_workers", 4))
+    pin_memory = device.startswith("cuda")
+
+    train_ds = AlphabetDataset(root, train=True, img_size=img_size, augment=True, mean=mean, std=std)
+    val_ds = AlphabetDataset(root, train=False, img_size=img_size, augment=False, mean=mean, std=std)
+
+    train_loader = DataLoader(
+        train_ds,
+        batch_size=batch_size,
+        shuffle=True,
+        num_workers=num_workers,
+        pin_memory=pin_memory,
+        collate_fn=_collate,
+        drop_last=False,
+    )
+    val_loader = DataLoader(
+        val_ds,
+        batch_size=batch_size,
+        shuffle=False,
+        num_workers=num_workers,
+        pin_memory=pin_memory,
+        collate_fn=_collate,
+        drop_last=False,
+    )
+    return train_loader, val_loader
+
+
+def preprocess_crop_for_inference(
+    image: Any,  # PIL Image
+    img_size: int = 64,
+    mean: float = 0.5,
+    std: float = 0.5,
+) -> torch.Tensor:
+    """Preprocess a real letter crop for inference (no EMNIST orientation fix)."""
+    transform = transforms.Compose([
+        transforms.Grayscale(num_output_channels=1),
+        transforms.Resize((img_size, img_size)),
+        transforms.ToTensor(),
+        transforms.Normalize(mean=[mean], std=[std]),
+    ])
+    return transform(image)
+
+
+__all__ = ["ALPHABET_CLASSES", "AlphabetDataset", "build_dataloaders", "preprocess_crop_for_inference"]

alphabet/export.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import torch
+
+from alphabet.model import build_model
+from alphabet.utils import ensure_dir, load_yaml
+
+
+@torch.no_grad()
+def load_checkpoint_model(
+    checkpoint_path: str | Path, cfg: dict, device: str = "cpu"
+) -> torch.nn.Module:
+    model = build_model(cfg["model"])
+    checkpoint = torch.load(checkpoint_path, map_location=device, weights_only=False)
+    state_dict = (
+        checkpoint["model_state"]
+        if isinstance(checkpoint, dict) and "model_state" in checkpoint
+        else checkpoint
+    )
+    model.load_state_dict(state_dict)
+    model.to(device)
+    model.eval()
+    return model
+
+
+@torch.no_grad()
+def export_onnx(
+    model: torch.nn.Module,
+    output_path: str | Path,
+    input_shape: tuple[int, int, int, int] = (1, 1, 64, 64),
+    opset: int = 17,
+    device: str = "cpu",
+) -> Path:
+    ensure_dir(Path(output_path).parent)
+    example = torch.randn(*input_shape, device=device)
+    try:
+        torch.onnx.export(
+            model,
+            (example,),
+            str(output_path),
+            input_names=["input"],
+            output_names=["logits"],
+            opset_version=opset,
+            dynamo=True,
+        )
+    except Exception:
+        torch.onnx.export(
+            model,
+            (example,),
+            str(output_path),
+            input_names=["input"],
+            output_names=["logits"],
+            opset_version=opset,
+            dynamic_axes={"input": {0: "batch"}, "logits": {0: "batch"}},
+            dynamo=False,
+        )
+    return Path(output_path)
+
+
+@torch.no_grad()
+def export_torchscript(
+    model: torch.nn.Module,
+    output_path: str | Path,
+    input_shape: tuple[int, int, int, int] = (1, 1, 64, 64),
+    device: str = "cpu",
+) -> Path:
+    ensure_dir(Path(output_path).parent)
+    example = torch.randn(*input_shape, device=device)
+    traced = torch.jit.trace(model, example, strict=False)
+    traced = torch.jit.freeze(traced)
+    traced.save(str(output_path))
+    return Path(output_path)
+
+
+def export_from_config(
+    config_path: str | Path,
+    checkpoint_path: str | Path,
+    device: str = "cpu",
+) -> dict[str, str]:
+    cfg = load_yaml(config_path)
+    model = load_checkpoint_model(checkpoint_path, cfg, device=device)
+    export_cfg = cfg.get("export", {})
+    img_size = int(cfg["model"].get("img_size", 64))
+    in_channels = int(cfg["model"].get("in_channels", 1))
+    input_shape = (1, in_channels, img_size, img_size)
+
+    onnx_path = export_onnx(
+        model,
+        export_cfg.get("onnx_path", "outputs/exports/alphabet_model.onnx"),
+        input_shape=input_shape,
+        opset=int(export_cfg.get("onnx_opset", 17)),
+        device=device,
+    )
+    ts_path = export_torchscript(
+        model,
+        export_cfg.get("torchscript_path", "outputs/exports/alphabet_model.ts"),
+        input_shape=input_shape,
+        device=device,
+    )
+    print(f"ONNX exported  → {onnx_path}")
+    print(f"TorchScript    → {ts_path}")
+    return {"onnx": str(onnx_path), "torchscript": str(ts_path)}
+
+
+__all__ = ["load_checkpoint_model", "export_onnx", "export_torchscript", "export_from_config"]

alphabet/infer.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import cv2
+import numpy as np
+import torch
+from PIL import Image
+
+from alphabet.dataset import ALPHABET_CLASSES, preprocess_crop_for_inference
+
+
+class OnnxBackend:
+    """ONNX runtime backend for the 26-class alphabet model."""
+
+    def __init__(self, model_path: str | Path) -> None:
+        try:
+            import onnxruntime as ort
+        except ImportError as exc:
+            raise ImportError("Install onnxruntime to use the ONNX backend.") from exc
+        providers = ["CPUExecutionProvider"]
+        self.session = ort.InferenceSession(str(model_path), providers=providers)
+        self.input_name = self.session.get_inputs()[0].name
+        self.output_name = self.session.get_outputs()[0].name
+
+    def predict(self, batch_tensor: torch.Tensor) -> np.ndarray:
+        """Return softmax probabilities, shape (batch, 26)."""
+        arr = batch_tensor.detach().cpu().numpy().astype(np.float32)
+        logits = self.session.run([self.output_name], {self.input_name: arr})[0]
+        # numerically stable softmax
+        logits = logits - logits.max(axis=1, keepdims=True)
+        e = np.exp(logits)
+        return e / e.sum(axis=1, keepdims=True)
+
+
+def predict_crops(
+    backend: OnnxBackend,
+    crops: list[np.ndarray],
+    img_size: int = 64,
+    mean: float = 0.5,
+    std: float = 0.5,
+    min_confidence: float = 0.60,
+    batch_size: int = 256,
+) -> list[dict[str, Any]]:
+    """
+    Run inference on a list of pre-cropped BGR letter images.
+
+    Returns one dict per crop with:
+      letter          — predicted character ('A'–'Z')
+      prediction_index — 0–25
+      confidence      — softmax probability of the top class
+      probabilities   — full 26-element list
+      flag            — True when confidence < min_confidence (needs human review)
+    """
+    tensors: list[torch.Tensor] = []
+    for crop in crops:
+        pil = Image.fromarray(cv2.cvtColor(crop, cv2.COLOR_BGR2RGB))
+        tensors.append(preprocess_crop_for_inference(pil, img_size=img_size, mean=mean, std=std))
+
+    all_probs: list[np.ndarray] = []
+    for i in range(0, len(tensors), batch_size):
+        batch = torch.stack(tensors[i : i + batch_size], dim=0)
+        all_probs.append(backend.predict(batch))
+
+    probs_matrix = np.concatenate(all_probs, axis=0) if all_probs else np.zeros((0, 26))
+
+    results: list[dict[str, Any]] = []
+    for probs in probs_matrix:
+        idx = int(probs.argmax())
+        confidence = float(probs[idx])
+        results.append({
+            "letter": ALPHABET_CLASSES[idx],
+            "prediction_index": idx,
+            "confidence": confidence,
+            "probabilities": probs.tolist(),
+            "flag": confidence < min_confidence,
+        })
+    return results
+
+
+__all__ = ["OnnxBackend", "predict_crops"]

alphabet/model.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+
+
+class DSConv(nn.Module):
+    """Depthwise-separable conv block — same as omr_proj."""
+    def __init__(self, in_ch: int, out_ch: int, stride: int = 1) -> None:
+        super().__init__()
+        self.block = nn.Sequential(
+            nn.Conv2d(in_ch, in_ch, 3, stride=stride, padding=1, groups=in_ch, bias=False),
+            nn.BatchNorm2d(in_ch),
+            nn.ReLU(inplace=True),
+            nn.Conv2d(in_ch, out_ch, 1, bias=False),
+            nn.BatchNorm2d(out_ch),
+            nn.ReLU(inplace=True),
+        )
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return self.block(x)
+
+
+class TinyAlphaNet(nn.Module):
+    def __init__(self, in_channels: int = 1, num_classes: int = 26, dropout: float = 0.20) -> None:
+        super().__init__()
+        self.features = nn.Sequential(
+            nn.Conv2d(in_channels, 16, 3, padding=1, bias=False),
+            nn.BatchNorm2d(16),
+            nn.ReLU(inplace=True),
+            nn.MaxPool2d(2),
+            DSConv(16, 24),
+            nn.MaxPool2d(2),
+            DSConv(24, 32),
+            nn.MaxPool2d(2),
+            DSConv(32, 48),
+            nn.AdaptiveAvgPool2d(1),
+        )
+        self.head = nn.Sequential(
+            nn.Flatten(),
+            nn.Linear(48, 64),
+            nn.ReLU(inplace=True),
+            nn.Dropout(dropout),
+            nn.Linear(64, num_classes),
+        )
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return self.head(self.features(x))
+
+
+class SmallAlphaNet(nn.Module):
+    def __init__(self, in_channels: int = 1, num_classes: int = 26, dropout: float = 0.30) -> None:
+        super().__init__()
+        self.features = nn.Sequential(
+            nn.Conv2d(in_channels, 24, 3, stride=2, padding=1, bias=False),
+            nn.BatchNorm2d(24),
+            nn.ReLU(inplace=True),
+            DSConv(24, 32),
+            DSConv(32, 48, stride=2),
+            DSConv(48, 64),
+            DSConv(64, 96, stride=2),
+            DSConv(96, 128),
+            nn.AdaptiveAvgPool2d(1),
+        )
+        self.head = nn.Sequential(
+            nn.Flatten(),
+            nn.Linear(128, 64),
+            nn.ReLU(inplace=True),
+            nn.Dropout(dropout),
+            nn.Linear(64, num_classes),
+        )
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return self.head(self.features(x))
+
+
+def build_model(cfg: dict) -> nn.Module:
+    name = cfg.get("name", "small_cnn").lower()
+    in_channels = int(cfg.get("in_channels", 1))
+    num_classes = int(cfg.get("num_classes", 26))
+    dropout = float(cfg.get("dropout", 0.30))
+    if name == "tiny_cnn":
+        return TinyAlphaNet(in_channels=in_channels, num_classes=num_classes, dropout=dropout)
+    if name == "small_cnn":
+        return SmallAlphaNet(in_channels=in_channels, num_classes=num_classes, dropout=dropout)
+    raise ValueError(f"Unknown model name: {name!r}. Choose 'tiny_cnn' or 'small_cnn'.")
+
+
+def count_parameters(model: nn.Module) -> int:
+    return sum(p.numel() for p in model.parameters())
+
+
+__all__ = ["DSConv", "TinyAlphaNet", "SmallAlphaNet", "build_model", "count_parameters"]

alphabet/train.py

@@ -0,0 +1,224 @@
+from __future__ import annotations
+
+import math
+from contextlib import nullcontext
+from copy import deepcopy
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import torch
+import torch.nn as nn
+from sklearn.metrics import accuracy_score, classification_report
+
+from alphabet.dataset import ALPHABET_CLASSES, build_dataloaders
+from alphabet.export import export_from_config
+from alphabet.model import build_model, count_parameters
+from alphabet.utils import ensure_dir, load_yaml, save_json, set_seed, write_csv
+
+
+class EarlyStopper:
+    def __init__(self, patience: int = 8, mode: str = "max") -> None:
+        self.patience = patience
+        self.mode = mode
+        self.best: float | None = None
+        self.bad_epochs = 0
+
+    def step(self, value: float) -> bool:
+        if self.best is None:
+            self.best = value
+            return False
+        improved = value > self.best if self.mode == "max" else value < self.best
+        if improved:
+            self.best = value
+            self.bad_epochs = 0
+            return False
+        self.bad_epochs += 1
+        return self.bad_epochs >= self.patience
+
+
+def _forward_context(device: str, amp_enabled: bool):
+    if amp_enabled and device.startswith("cuda"):
+        return torch.cuda.amp.autocast()
+    return nullcontext()
+
+
+def train_one_epoch(
+    model: nn.Module,
+    loader: torch.utils.data.DataLoader,
+    optimizer: torch.optim.Optimizer,
+    criterion: nn.Module,
+    device: str,
+    scaler: torch.cuda.amp.GradScaler | None,
+    amp_enabled: bool,
+) -> float:
+    model.train()
+    losses: list[float] = []
+    for batch in loader:
+        x = batch["image"].to(device, non_blocking=True)
+        y = batch["label"].to(device, non_blocking=True)
+        optimizer.zero_grad(set_to_none=True)
+        with _forward_context(device, amp_enabled):
+            logits = model(x)
+            loss = criterion(logits, y)
+        if scaler is not None:
+            scaler.scale(loss).backward()
+            scaler.step(optimizer)
+            scaler.update()
+        else:
+            loss.backward()
+            optimizer.step()
+        losses.append(float(loss.detach().cpu().item()))
+    return float(np.mean(losses)) if losses else math.nan
+
+
+@torch.no_grad()
+def validate(
+    model: nn.Module,
+    loader: torch.utils.data.DataLoader,
+    criterion: nn.Module,
+    device: str,
+) -> tuple[float, dict[str, Any]]:
+    model.eval()
+    losses: list[float] = []
+    all_preds: list[np.ndarray] = []
+    all_labels: list[np.ndarray] = []
+
+    for batch in loader:
+        x = batch["image"].to(device, non_blocking=True)
+        y = batch["label"].to(device, non_blocking=True)
+        logits = model(x)
+        loss = criterion(logits, y)
+        preds = logits.argmax(dim=1).cpu().numpy()
+        all_preds.append(preds)
+        all_labels.append(y.cpu().numpy())
+        losses.append(float(loss.item()))
+
+    y_pred = np.concatenate(all_preds)
+    y_true = np.concatenate(all_labels)
+    accuracy = float(accuracy_score(y_true, y_pred))
+    report = classification_report(
+        y_true, y_pred,
+        target_names=ALPHABET_CLASSES,
+        output_dict=True,
+        zero_division=0,
+    )
+    metrics = {"accuracy": accuracy, "report": report}
+    return float(np.mean(losses)) if losses else math.nan, metrics
+
+
+def save_checkpoint(
+    path: str | Path,
+    model: nn.Module,
+    optimizer: torch.optim.Optimizer,
+    scheduler: Any,
+    epoch: int,
+    cfg: dict[str, Any],
+    metrics: dict[str, Any],
+) -> None:
+    ensure_dir(Path(path).parent)
+    torch.save(
+        {
+            "epoch": epoch,
+            "model_state": model.state_dict(),
+            "optimizer_state": optimizer.state_dict(),
+            "scheduler_state": scheduler.state_dict() if scheduler is not None else None,
+            "config": cfg,
+            "metrics": metrics,
+        },
+        path,
+    )
+
+
+def train_from_config(config_path: str | Path, device: str | None = None) -> dict[str, Any]:
+    cfg = load_yaml(config_path)
+    set_seed(int(cfg.get("seed", 42)))
+    device = device or (
+        "cuda" if torch.cuda.is_available()
+        else "mps" if torch.backends.mps.is_available()
+        else "cpu"
+    )
+    save_dir = ensure_dir(cfg["train"].get("save_dir", "outputs/checkpoints"))
+
+    train_loader, val_loader = build_dataloaders(cfg, device=device)
+    model = build_model(cfg["model"]).to(device)
+
+    print(f"Model parameters: {count_parameters(model):,}")
+    print(f"Training on {device} | "
+          f"{len(train_loader.dataset)} train / {len(val_loader.dataset)} val samples")
+
+    criterion = nn.CrossEntropyLoss()
+    optimizer = torch.optim.AdamW(
+        model.parameters(),
+        lr=float(cfg["train"].get("lr", 1e-3)),
+        weight_decay=float(cfg["train"].get("weight_decay", 1e-4)),
+    )
+    epochs = int(cfg["train"].get("epochs", 30))
+    scheduler = torch.optim.lr_scheduler.CosineAnnealingLR(optimizer, T_max=epochs)
+    amp_enabled = bool(cfg["train"].get("amp", True)) and device.startswith("cuda")
+    scaler = torch.cuda.amp.GradScaler(enabled=amp_enabled) if amp_enabled else None
+    early = EarlyStopper(patience=int(cfg["train"].get("early_patience", 8)), mode="max")
+
+    history: list[dict[str, Any]] = []
+    best_state: dict[str, Any] | None = None
+    best_score = -1.0
+
+    for epoch in range(1, epochs + 1):
+        train_loss = train_one_epoch(model, train_loader, optimizer, criterion, device, scaler, amp_enabled)
+        val_loss, val_metrics = validate(model, val_loader, criterion, device)
+        score = val_metrics["accuracy"]
+        scheduler.step()
+
+        print(
+            f"Epoch {epoch:>3}/{epochs} | "
+            f"train_loss={train_loss:.4f} | "
+            f"val_loss={val_loss:.4f} | "
+            f"val_acc={score:.4f}"
+        )
+
+        row = {
+            "epoch": epoch,
+            "lr": float(optimizer.param_groups[0]["lr"]),
+            "train_loss": float(train_loss),
+            "val_loss": float(val_loss),
+            "val_accuracy": float(score),
+        }
+        history.append(row)
+
+        save_checkpoint(save_dir / "last.pt", model, optimizer, scheduler, epoch, cfg, row)
+
+        if score > best_score:
+            best_score = score
+            best_state = deepcopy(model.state_dict())
+            save_checkpoint(save_dir / "best.pt", model, optimizer, scheduler, epoch, cfg, row)
+            save_json(val_metrics, save_dir / "best_metrics.json")
+
+        if early.step(score):
+            print(f"Early stopping at epoch {epoch}.")
+            break
+
+    write_csv(history, save_dir / "train_log.csv")
+
+    if best_state is not None:
+        model.load_state_dict(best_state)
+
+    _, final_metrics = validate(model, val_loader, criterion, device)
+    save_json(final_metrics, save_dir / "final_metrics.json")
+
+    summary = {
+        "device": device,
+        "params": count_parameters(model),
+        "train_size": len(train_loader.dataset),
+        "val_size": len(val_loader.dataset),
+        "best_val_accuracy": best_score,
+        "final_metrics": final_metrics,
+    }
+    save_json(summary, save_dir / "summary.json")
+
+    if bool(cfg.get("export", {}).get("after_train", True)):
+        export_from_config(config_path, save_dir / "best.pt", device=device)
+
+    return summary
+
+
+__all__ = ["train_from_config"]

alphabet/utils.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import csv
+import json
+import logging
+import random
+from pathlib import Path
+from typing import Any, Iterable
+
+import numpy as np
+import torch
+import yaml
+
+
+LOGGER = logging.getLogger("alphabet")
+
+
+def setup_logging(level: str = "INFO") -> None:
+    logging.basicConfig(
+        level=getattr(logging, level.upper(), logging.INFO),
+        format="%(asctime)s | %(levelname)s | %(message)s",
+    )
+
+
+def set_seed(seed: int = 42) -> None:
+    random.seed(seed)
+    np.random.seed(seed)
+    torch.manual_seed(seed)
+    torch.cuda.manual_seed_all(seed)
+    torch.backends.cudnn.deterministic = True
+    torch.backends.cudnn.benchmark = False
+
+
+def ensure_dir(path: str | Path) -> Path:
+    path = Path(path)
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def load_yaml(path: str | Path) -> dict[str, Any]:
+    with open(path, "r", encoding="utf-8") as f:
+        return yaml.safe_load(f)
+
+
+def save_json(data: Any, path: str | Path, indent: int = 2) -> None:
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(data, f, ensure_ascii=False, indent=indent)
+
+
+def write_csv(rows: list[dict[str, Any]], path: str | Path) -> None:
+    if not rows:
+        return
+    with open(path, "w", encoding="utf-8", newline="") as f:
+        writer = csv.DictWriter(f, fieldnames=list(rows[0].keys()))
+        writer.writeheader()
+        writer.writerows(rows)
+
+
+__all__ = [
+    "LOGGER",
+    "setup_logging",
+    "set_seed",
+    "ensure_dir",
+    "load_yaml",
+    "save_json",
+    "write_csv",
+]

config/config.yaml

@@ -0,0 +1,33 @@
+seed: 42
+
+data:
+  root: data/emnist          # torchvision downloads EMNIST here on first run
+
+model:
+  name: small_cnn            # tiny_cnn | small_cnn
+  in_channels: 1
+  num_classes: 26
+  img_size: 64
+  mean: 0.5
+  std: 0.5
+  dropout: 0.30
+
+train:
+  batch_size: 256
+  num_workers: 4
+  epochs: 30
+  lr: 0.001
+  weight_decay: 0.0001
+  amp: true                  # mixed precision — only active on CUDA
+  early_patience: 8
+  save_dir: outputs/checkpoints
+
+infer:
+  min_confidence: 0.60       # flag for human review below this threshold
+  batch_size: 256
+
+export:
+  after_train: true
+  onnx_opset: 17
+  onnx_path: outputs/exports/alphabet_model.onnx
+  torchscript_path: outputs/exports/alphabet_model.ts

main.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from alphabet.utils import setup_logging
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Alphabet (A-Z) classifier CLI")
+    parser.add_argument("--log-level", default="INFO")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    p_train = subparsers.add_parser("train", help="Download EMNIST and train the model")
+    p_train.add_argument("--config", default="config/config.yaml")
+    p_train.add_argument("--device", default=None, help="cuda | cpu (auto-detects if omitted)")
+
+    p_export = subparsers.add_parser("export", help="Export a checkpoint to ONNX and TorchScript")
+    p_export.add_argument("--config", default="config/config.yaml")
+    p_export.add_argument("--checkpoint", required=True, help="Path to best.pt")
+    p_export.add_argument("--device", default="cpu")
+
+    p_infer = subparsers.add_parser("infer", help="Run inference on a single image (for testing)")
+    p_infer.add_argument("--model", required=True, help="Path to .onnx model")
+    p_infer.add_argument("--image", required=True, help="Path to a letter crop image")
+    p_infer.add_argument("--config", default="config/config.yaml")
+
+    args = parser.parse_args()
+    setup_logging(args.log_level)
+
+    if args.command == "train":
+        from alphabet.train import train_from_config
+        summary = train_from_config(args.config, device=args.device)
+        print(f"\nBest val accuracy: {summary['best_val_accuracy']:.4f}")
+        return
+
+    if args.command == "export":
+        from alphabet.export import export_from_config
+        exported = export_from_config(args.config, args.checkpoint, device=args.device)
+        print(exported)
+        return
+
+    if args.command == "infer":
+        import cv2
+        import numpy as np
+        from alphabet.infer import OnnxBackend, predict_crops
+        from alphabet.utils import load_yaml
+
+        cfg = load_yaml(args.config)
+        infer_cfg = cfg.get("infer", {})
+        model_cfg = cfg["model"]
+
+        crop = cv2.imread(args.image, cv2.IMREAD_COLOR)
+        if crop is None:
+            print(f"Error: could not read image at {args.image}", file=sys.stderr)
+            sys.exit(1)
+
+        backend = OnnxBackend(args.model)
+        results = predict_crops(
+            backend,
+            [crop],
+            img_size=int(model_cfg.get("img_size", 64)),
+            mean=float(model_cfg.get("mean", 0.5)),
+            std=float(model_cfg.get("std", 0.5)),
+            min_confidence=float(infer_cfg.get("min_confidence", 0.60)),
+        )
+        r = results[0]
+        flag_str = " [FLAGGED for review]" if r["flag"] else ""
+        print(f"Prediction : {r['letter']}{flag_str}")
+        print(f"Confidence : {r['confidence']:.4f}")
+        top3 = sorted(enumerate(r["probabilities"]), key=lambda x: -x[1])[:3]
+        for idx, prob in top3:
+            letter = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"[idx]
+            print(f"  {letter}: {prob:.4f}")
+        return
+
+
+if __name__ == "__main__":
+    main()

outputs/checkpoints/best.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d1465af892d48aeef51d9e5bdd90018ea69c37c998ff492055c33be4eae6ccd8
+size 505956

outputs/checkpoints/best_metrics.json

@@ -0,0 +1,174 @@
+{
+  "accuracy": 0.9410096153846154,
+  "report": {
+    "A": {
+      "precision": 0.9084507042253521,
+      "recall": 0.9675,
+      "f1-score": 0.937046004842615,
+      "support": 800.0
+    },
+    "B": {
+      "precision": 0.9810366624525917,
+      "recall": 0.97,
+      "f1-score": 0.9754871150219987,
+      "support": 800.0
+    },
+    "C": {
+      "precision": 0.9752168525402726,
+      "recall": 0.98375,
+      "f1-score": 0.9794648413192284,
+      "support": 800.0
+    },
+    "D": {
+      "precision": 0.9523809523809523,
+      "recall": 0.95,
+      "f1-score": 0.951188986232791,
+      "support": 800.0
+    },
+    "E": {
+      "precision": 0.9774153074027604,
+      "recall": 0.97375,
+      "f1-score": 0.9755792110206637,
+      "support": 800.0
+    },
+    "F": {
+      "precision": 0.9758269720101781,
+      "recall": 0.95875,
+      "f1-score": 0.9672131147540983,
+      "support": 800.0
+    },
+    "G": {
+      "precision": 0.8993103448275862,
+      "recall": 0.815,
+      "f1-score": 0.8550819672131148,
+      "support": 800.0
+    },
+    "H": {
+      "precision": 0.957286432160804,
+      "recall": 0.9525,
+      "f1-score": 0.9548872180451128,
+      "support": 800.0
+    },
+    "I": {
+      "precision": 0.7487437185929648,
+      "recall": 0.745,
+      "f1-score": 0.7468671679197995,
+      "support": 800.0
+    },
+    "J": {
+      "precision": 0.9603072983354674,
+      "recall": 0.9375,
+      "f1-score": 0.9487666034155597,
+      "support": 800.0
+    },
+    "K": {
+      "precision": 0.9822109275730623,
+      "recall": 0.96625,
+      "f1-score": 0.9741650913673598,
+      "support": 800.0
+    },
+    "L": {
+      "precision": 0.75,
+      "recall": 0.7575,
+      "f1-score": 0.753731343283582,
+      "support": 800.0
+    },
+    "M": {
+      "precision": 0.9826732673267327,
+      "recall": 0.9925,
+      "f1-score": 0.9875621890547264,
+      "support": 800.0
+    },
+    "N": {
+      "precision": 0.9552238805970149,
+      "recall": 0.96,
+      "f1-score": 0.9576059850374065,
+      "support": 800.0
+    },
+    "O": {
+      "precision": 0.9504830917874396,
+      "recall": 0.98375,
+      "f1-score": 0.9668304668304668,
+      "support": 800.0
+    },
+    "P": {
+      "precision": 0.986284289276808,
+      "recall": 0.98875,
+      "f1-score": 0.9875156054931336,
+      "support": 800.0
+    },
+    "Q": {
+      "precision": 0.8583850931677018,
+      "recall": 0.86375,
+      "f1-score": 0.8610591900311526,
+      "support": 800.0
+    },
+    "R": {
+      "precision": 0.9613466334164589,
+      "recall": 0.96375,
+      "f1-score": 0.9625468164794008,
+      "support": 800.0
+    },
+    "S": {
+      "precision": 0.9777227722772277,
+      "recall": 0.9875,
+      "f1-score": 0.9825870646766169,
+      "support": 800.0
+    },
+    "T": {
+      "precision": 0.9489671931956257,
+      "recall": 0.97625,
+      "f1-score": 0.9624152803450401,
+      "support": 800.0
+    },
+    "U": {
+      "precision": 0.9527458492975734,
+      "recall": 0.9325,
+      "f1-score": 0.9425142135186355,
+      "support": 800.0
+    },
+    "V": {
+      "precision": 0.9334155363748459,
+      "recall": 0.94625,
+      "f1-score": 0.9397889509621353,
+      "support": 800.0
+    },
+    "W": {
+      "precision": 0.9837092731829574,
+      "recall": 0.98125,
+      "f1-score": 0.9824780976220275,
+      "support": 800.0
+    },
+    "X": {
+      "precision": 0.9785353535353535,
+      "recall": 0.96875,
+      "f1-score": 0.9736180904522613,
+      "support": 800.0
+    },
+    "Y": {
+      "precision": 0.9478908188585607,
+      "recall": 0.955,
+      "f1-score": 0.9514321295143213,
+      "support": 800.0
+    },
+    "Z": {
+      "precision": 0.9813895781637717,
+      "recall": 0.98875,
+      "f1-score": 0.9850560398505604,
+      "support": 800.0
+    },
+    "accuracy": 0.9410096153846154,
+    "macro avg": {
+      "precision": 0.9410368770369255,
+      "recall": 0.9410096153846154,
+      "f1-score": 0.9408649532424541,
+      "support": 20800.0
+    },
+    "weighted avg": {
+      "precision": 0.9410368770369254,
+      "recall": 0.9410096153846154,
+      "f1-score": 0.940864953242454,
+      "support": 20800.0
+    }
+  }
+}

outputs/checkpoints/final_metrics.json

@@ -0,0 +1,174 @@
+{
+  "accuracy": 0.9410096153846154,
+  "report": {
+    "A": {
+      "precision": 0.9084507042253521,
+      "recall": 0.9675,
+      "f1-score": 0.937046004842615,
+      "support": 800.0
+    },
+    "B": {
+      "precision": 0.9810366624525917,
+      "recall": 0.97,
+      "f1-score": 0.9754871150219987,
+      "support": 800.0
+    },
+    "C": {
+      "precision": 0.9752168525402726,
+      "recall": 0.98375,
+      "f1-score": 0.9794648413192284,
+      "support": 800.0
+    },
+    "D": {
+      "precision": 0.9523809523809523,
+      "recall": 0.95,
+      "f1-score": 0.951188986232791,
+      "support": 800.0
+    },
+    "E": {
+      "precision": 0.9774153074027604,
+      "recall": 0.97375,
+      "f1-score": 0.9755792110206637,
+      "support": 800.0
+    },
+    "F": {
+      "precision": 0.9758269720101781,
+      "recall": 0.95875,
+      "f1-score": 0.9672131147540983,
+      "support": 800.0
+    },
+    "G": {
+      "precision": 0.8993103448275862,
+      "recall": 0.815,
+      "f1-score": 0.8550819672131148,
+      "support": 800.0
+    },
+    "H": {
+      "precision": 0.957286432160804,
+      "recall": 0.9525,
+      "f1-score": 0.9548872180451128,
+      "support": 800.0
+    },
+    "I": {
+      "precision": 0.7487437185929648,
+      "recall": 0.745,
+      "f1-score": 0.7468671679197995,
+      "support": 800.0
+    },
+    "J": {
+      "precision": 0.9603072983354674,
+      "recall": 0.9375,
+      "f1-score": 0.9487666034155597,
+      "support": 800.0
+    },
+    "K": {
+      "precision": 0.9822109275730623,
+      "recall": 0.96625,
+      "f1-score": 0.9741650913673598,
+      "support": 800.0
+    },
+    "L": {
+      "precision": 0.75,
+      "recall": 0.7575,
+      "f1-score": 0.753731343283582,
+      "support": 800.0
+    },
+    "M": {
+      "precision": 0.9826732673267327,
+      "recall": 0.9925,
+      "f1-score": 0.9875621890547264,
+      "support": 800.0
+    },
+    "N": {
+      "precision": 0.9552238805970149,
+      "recall": 0.96,
+      "f1-score": 0.9576059850374065,
+      "support": 800.0
+    },
+    "O": {
+      "precision": 0.9504830917874396,
+      "recall": 0.98375,
+      "f1-score": 0.9668304668304668,
+      "support": 800.0
+    },
+    "P": {
+      "precision": 0.986284289276808,
+      "recall": 0.98875,
+      "f1-score": 0.9875156054931336,
+      "support": 800.0
+    },
+    "Q": {
+      "precision": 0.8583850931677018,
+      "recall": 0.86375,
+      "f1-score": 0.8610591900311526,
+      "support": 800.0
+    },
+    "R": {
+      "precision": 0.9613466334164589,
+      "recall": 0.96375,
+      "f1-score": 0.9625468164794008,
+      "support": 800.0
+    },
+    "S": {
+      "precision": 0.9777227722772277,
+      "recall": 0.9875,
+      "f1-score": 0.9825870646766169,
+      "support": 800.0
+    },
+    "T": {
+      "precision": 0.9489671931956257,
+      "recall": 0.97625,
+      "f1-score": 0.9624152803450401,
+      "support": 800.0
+    },
+    "U": {
+      "precision": 0.9527458492975734,
+      "recall": 0.9325,
+      "f1-score": 0.9425142135186355,
+      "support": 800.0
+    },
+    "V": {
+      "precision": 0.9334155363748459,
+      "recall": 0.94625,
+      "f1-score": 0.9397889509621353,
+      "support": 800.0
+    },
+    "W": {
+      "precision": 0.9837092731829574,
+      "recall": 0.98125,
+      "f1-score": 0.9824780976220275,
+      "support": 800.0
+    },
+    "X": {
+      "precision": 0.9785353535353535,
+      "recall": 0.96875,
+      "f1-score": 0.9736180904522613,
+      "support": 800.0
+    },
+    "Y": {
+      "precision": 0.9478908188585607,
+      "recall": 0.955,
+      "f1-score": 0.9514321295143213,
+      "support": 800.0
+    },
+    "Z": {
+      "precision": 0.9813895781637717,
+      "recall": 0.98875,
+      "f1-score": 0.9850560398505604,
+      "support": 800.0
+    },
+    "accuracy": 0.9410096153846154,
+    "macro avg": {
+      "precision": 0.9410368770369255,
+      "recall": 0.9410096153846154,
+      "f1-score": 0.9408649532424541,
+      "support": 20800.0
+    },
+    "weighted avg": {
+      "precision": 0.9410368770369254,
+      "recall": 0.9410096153846154,
+      "f1-score": 0.940864953242454,
+      "support": 20800.0
+    }
+  }
+}

outputs/checkpoints/last.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a188738c2f9a4d233e698436ddad1d04467b67564754abc18f84504ea77bb0c4
+size 505956

outputs/checkpoints/summary.json

@@ -0,0 +1,181 @@
+{
+  "device": "cuda",
+  "params": 37658,
+  "train_size": 124800,
+  "val_size": 20800,
+  "best_val_accuracy": 0.9410096153846154,
+  "final_metrics": {
+    "accuracy": 0.9410096153846154,
+    "report": {
+      "A": {
+        "precision": 0.9084507042253521,
+        "recall": 0.9675,
+        "f1-score": 0.937046004842615,
+        "support": 800.0
+      },
+      "B": {
+        "precision": 0.9810366624525917,
+        "recall": 0.97,
+        "f1-score": 0.9754871150219987,
+        "support": 800.0
+      },
+      "C": {
+        "precision": 0.9752168525402726,
+        "recall": 0.98375,
+        "f1-score": 0.9794648413192284,
+        "support": 800.0
+      },
+      "D": {
+        "precision": 0.9523809523809523,
+        "recall": 0.95,
+        "f1-score": 0.951188986232791,
+        "support": 800.0
+      },
+      "E": {
+        "precision": 0.9774153074027604,
+        "recall": 0.97375,
+        "f1-score": 0.9755792110206637,
+        "support": 800.0
+      },
+      "F": {
+        "precision": 0.9758269720101781,
+        "recall": 0.95875,
+        "f1-score": 0.9672131147540983,
+        "support": 800.0
+      },
+      "G": {
+        "precision": 0.8993103448275862,
+        "recall": 0.815,
+        "f1-score": 0.8550819672131148,
+        "support": 800.0
+      },
+      "H": {
+        "precision": 0.957286432160804,
+        "recall": 0.9525,
+        "f1-score": 0.9548872180451128,
+        "support": 800.0
+      },
+      "I": {
+        "precision": 0.7487437185929648,
+        "recall": 0.745,
+        "f1-score": 0.7468671679197995,
+        "support": 800.0
+      },
+      "J": {
+        "precision": 0.9603072983354674,
+        "recall": 0.9375,
+        "f1-score": 0.9487666034155597,
+        "support": 800.0
+      },
+      "K": {
+        "precision": 0.9822109275730623,
+        "recall": 0.96625,
+        "f1-score": 0.9741650913673598,
+        "support": 800.0
+      },
+      "L": {
+        "precision": 0.75,
+        "recall": 0.7575,
+        "f1-score": 0.753731343283582,
+        "support": 800.0
+      },
+      "M": {
+        "precision": 0.9826732673267327,
+        "recall": 0.9925,
+        "f1-score": 0.9875621890547264,
+        "support": 800.0
+      },
+      "N": {
+        "precision": 0.9552238805970149,
+        "recall": 0.96,
+        "f1-score": 0.9576059850374065,
+        "support": 800.0
+      },
+      "O": {
+        "precision": 0.9504830917874396,
+        "recall": 0.98375,
+        "f1-score": 0.9668304668304668,
+        "support": 800.0
+      },
+      "P": {
+        "precision": 0.986284289276808,
+        "recall": 0.98875,
+        "f1-score": 0.9875156054931336,
+        "support": 800.0
+      },
+      "Q": {
+        "precision": 0.8583850931677018,
+        "recall": 0.86375,
+        "f1-score": 0.8610591900311526,
+        "support": 800.0
+      },
+      "R": {
+        "precision": 0.9613466334164589,
+        "recall": 0.96375,
+        "f1-score": 0.9625468164794008,
+        "support": 800.0
+      },
+      "S": {
+        "precision": 0.9777227722772277,
+        "recall": 0.9875,
+        "f1-score": 0.9825870646766169,
+        "support": 800.0
+      },
+      "T": {
+        "precision": 0.9489671931956257,
+        "recall": 0.97625,
+        "f1-score": 0.9624152803450401,
+        "support": 800.0
+      },
+      "U": {
+        "precision": 0.9527458492975734,
+        "recall": 0.9325,
+        "f1-score": 0.9425142135186355,
+        "support": 800.0
+      },
+      "V": {
+        "precision": 0.9334155363748459,
+        "recall": 0.94625,
+        "f1-score": 0.9397889509621353,
+        "support": 800.0
+      },
+      "W": {
+        "precision": 0.9837092731829574,
+        "recall": 0.98125,
+        "f1-score": 0.9824780976220275,
+        "support": 800.0
+      },
+      "X": {
+        "precision": 0.9785353535353535,
+        "recall": 0.96875,
+        "f1-score": 0.9736180904522613,
+        "support": 800.0
+      },
+      "Y": {
+        "precision": 0.9478908188585607,
+        "recall": 0.955,
+        "f1-score": 0.9514321295143213,
+        "support": 800.0
+      },
+      "Z": {
+        "precision": 0.9813895781637717,
+        "recall": 0.98875,
+        "f1-score": 0.9850560398505604,
+        "support": 800.0
+      },
+      "accuracy": 0.9410096153846154,
+      "macro avg": {
+        "precision": 0.9410368770369255,
+        "recall": 0.9410096153846154,
+        "f1-score": 0.9408649532424541,
+        "support": 20800.0
+      },
+      "weighted avg": {
+        "precision": 0.9410368770369254,
+        "recall": 0.9410096153846154,
+        "f1-score": 0.940864953242454,
+        "support": 20800.0
+      }
+    }
+  }
+}

outputs/checkpoints/train_log.csv

@@ -0,0 +1,31 @@
+epoch,lr,train_loss,val_loss,val_accuracy
+1,0.0009972609476841367,1.915840568234686,0.7317645602473398,0.7759615384615385
+2,0.0009890738003669028,0.7861337430897306,0.42019438016705396,0.8676442307692308
+3,0.0009755282581475768,0.5793002123226885,0.3414752165809637,0.8886057692307693
+4,0.0009567727288213003,0.5050285570934171,0.2945807816051855,0.9050961538461538
+5,0.0009330127018922195,0.4556999812971373,0.2711868357004189,0.9123076923076923
+6,0.0009045084971874739,0.4235607778928319,0.2438873816735861,0.9197596153846154
+7,0.0008715724127386972,0.3999694408696206,0.24509387436073002,0.9171634615384615
+8,0.0008345653031794292,0.38357853461973,0.22920766054857067,0.9245192307692308
+9,0.0007938926261462366,0.3661592132793587,0.2268367960095042,0.925625
+10,0.00075,0.3540909972163986,0.22004170343279839,0.9271634615384615
+11,0.0007033683215379003,0.3418872819327917,0.20877559076449492,0.931826923076923
+12,0.0006545084971874739,0.3346020869727506,0.20745138592291168,0.9311538461538461
+13,0.0006039558454088797,0.32655729393123606,0.20885206949783536,0.9297596153846154
+14,0.0005522642316338269,0.31873070222676775,0.19801199699683888,0.9356730769230769
+15,0.0005000000000000002,0.31525022774690487,0.19914993425694907,0.9354807692307693
+16,0.0004477357683661734,0.30843753614997277,0.20442812638811586,0.9340865384615384
+17,0.00039604415459112036,0.30016807023985465,0.19302551118975006,0.9358173076923076
+18,0.0003454915028125264,0.29682947185318,0.19384775055208947,0.9359615384615385
+19,0.00029663167846210003,0.2924738503748276,0.19320982912691628,0.9363461538461538
+20,0.00025000000000000017,0.29010163604846745,0.1872810366472638,0.9373076923076923
+21,0.00020610737385376354,0.28513376365919585,0.18672967462505147,0.9389423076923077
+22,0.00016543469682057108,0.28206356538490196,0.18462900476666486,0.9389903846153846
+23,0.00012842758726130303,0.27867109957532804,0.18512763553185435,0.9387019230769231
+24,9.549150281252637e-05,0.2803964728458983,0.1824342363355,0.9398557692307692
+25,6.698729810778068e-05,0.2762351586315476,0.18212999898667742,0.9410096153846154
+26,4.322727117869953e-05,0.27648968744229097,0.18111976517773257,0.9395673076923077
+27,2.447174185242324e-05,0.27589607660154825,0.1811773017071551,0.9402403846153846
+28,1.092619963309716e-05,0.2695515979020322,0.1805415609170024,0.9400961538461539
+29,2.7390523158633003e-06,0.2720878096450059,0.18061398978276952,0.9404807692307692
+30,0.0,0.27351888143991837,0.18064619034028997,0.9403846153846154

outputs/exports/alphabet_model.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:861f97c69f6af53f2a87c477d49bbb1ae0669c37ea6c920e8ee6419eb875172c
+size 154087

outputs/exports/alphabet_model.ts

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9c43cff1ffafc9cf3b2d36629f3ae76785a978d02d6ee7a16e3663ba698ab41e
+size 158416

requirements.txt

@@ -0,0 +1,9 @@
+numpy>=1.24
+PyYAML>=6.0
+scikit-learn>=1.4
+torch>=2.2
+torchvision>=0.17
+onnx>=1.16
+onnxruntime>=1.18
+pillow>=10.0
+opencv-python>=4.8