easymodd 0.1.0__py3-none-any.whl

easymodd/__init__.py

@@ -0,0 +1,85 @@
+"""EasyMoDD: configurable, training-first numerical machine learning tools."""
+
+from .config import EasyMoDDConfig, load_config
+from .tensor import Device, array, backend_of, get_backend, matmul, ones, randn, seed, zeros
+from .nn import Dropout, GELU, Linear, Module, Parameter, ReLU, Sequential, Sigmoid, Tanh
+from .optim import Adam, AdamW, SGD
+from .schedulers import CosineScheduler, WarmupScheduler
+from .metrics import accuracy, mean_absolute_error, perplexity
+from .callbacks import EarlyStopping, MetricsLogger
+from .serialization import load_state, save_state
+from .training import Trainer, TrainingHistory
+from .data import ArrayDataset, BatchLoader, Dataset, Subset, TextDataset, collate_batch, split_dataset
+from .losses import CrossEntropyLoss, HuberLoss, L1Loss, MSELoss
+from .checkpoints import CheckpointManager
+from .experiments import Experiment
+from .registry import ModelRegistry, models
+from .secret_store import SecretStore
+from .transforms import Compose, Flatten, MapTransform, Normalize, Standardize, ToFloat32
+from .visualization import summarize_history, summarize_model
+from .models import MLP, TextTransformerConfig, VisionTransformerConfig, build_mlp
+
+__all__ = [
+    "Device",
+    "ArrayDataset",
+    "BatchLoader",
+    "Adam",
+    "AdamW",
+    "CheckpointManager",
+    "Compose",
+    "CrossEntropyLoss",
+    "CosineScheduler",
+    "Dataset",
+    "Dropout",
+    "EarlyStopping",
+    "EasyMoDDConfig",
+    "Experiment",
+    "Flatten",
+    "GELU",
+    "HuberLoss",
+    "L1Loss",
+    "Linear",
+    "MSELoss",
+    "MapTransform",
+    "ModelRegistry",
+    "Normalize",
+    "MetricsLogger",
+    "Module",
+    "Parameter",
+    "ReLU",
+    "Sequential",
+    "SGD",
+    "SecretStore",
+    "Sigmoid",
+    "Standardize",
+    "Tanh",
+    "ToFloat32",
+    "WarmupScheduler",
+    "Trainer",
+    "TrainingHistory",
+    "TextDataset",
+    "Subset",
+    "array",
+    "accuracy",
+    "backend_of",
+    "MLP",
+    "TextTransformerConfig",
+    "VisionTransformerConfig",
+    "build_mlp",
+    "get_backend",
+    "load_config",
+    "load_state",
+    "matmul",
+    "mean_absolute_error",
+    "perplexity",
+    "collate_batch",
+    "models",
+    "ones",
+    "randn",
+    "seed",
+    "save_state",
+    "zeros",
+    "split_dataset",
+    "summarize_history",
+    "summarize_model",
+]

easymodd/callbacks.py

@@ -0,0 +1,40 @@
+"""Reusable training callbacks."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+class MetricsLogger:
+    """Append one JSON object per training event."""
+
+    def __init__(self, path: str | Path):
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+
+    def __call__(self, *, step: int, metrics: dict[str, float]) -> None:
+        with self.path.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps({"step": step, **metrics}) + "\n")
+
+
+class EarlyStopping:
+    def __init__(self, metric: str = "loss", patience: int = 10, minimum_delta: float = 0.0):
+        if patience < 1:
+            raise ValueError("patience must be at least 1")
+        self.metric = metric
+        self.patience = patience
+        self.minimum_delta = minimum_delta
+        self.best = float("inf")
+        self.bad_steps = 0
+
+    def __call__(self, *, step: int, metrics: dict[str, float]) -> bool:
+        value = metrics.get(self.metric)
+        if value is None:
+            return False
+        if value < self.best - self.minimum_delta:
+            self.best = value
+            self.bad_steps = 0
+        else:
+            self.bad_steps += 1
+        return self.bad_steps >= self.patience

easymodd/checkpoints.py

@@ -0,0 +1,59 @@
+"""Config-controlled checkpoint management."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import zipfile
+from .serialization import save_state
+
+
+class CheckpointManager:
+    """Checkpoint policy that creates no files when disabled."""
+
+    def __init__(self, directory: str | Path, enabled: bool = True,
+                 keep_recent: int = 2, compress_old: bool = True):
+        if keep_recent < 1:
+            raise ValueError("keep_recent must be at least 1")
+        self.directory = Path(directory)
+        self.enabled = bool(enabled)
+        self.keep_recent = keep_recent
+        self.compress_old = bool(compress_old)
+
+    def save(self, state: dict, step: int) -> Path | None:
+        if not self.enabled:
+            return None
+        self.directory.mkdir(parents=True, exist_ok=True)
+        path = self.directory / f"step_{step:07d}.json"
+        path.write_text(json.dumps(state, indent=2), encoding="utf-8")
+        self._compress_old()
+        return path
+
+    def save_training_state(self, step: int, *, model, optimizer=None,
+                            scheduler=None, config=None, metrics=None) -> Path | None:
+        if not self.enabled:
+            return None
+        self.directory.mkdir(parents=True, exist_ok=True)
+        path = self.directory / f"step_{step:07d}.pkl"
+        save_state(path, model=model, optimizer=optimizer, scheduler=scheduler,
+                   config=config, metrics=metrics)
+        self._compress_artifacts()
+        return path
+
+    def _compress_old(self) -> None:
+        files = sorted(self.directory.glob("step_*.json"), key=lambda item: item.stat().st_mtime)
+        for path in files[:-self.keep_recent]:
+            archive = path.with_suffix(".zip")
+            if self.compress_old and not archive.exists():
+                with zipfile.ZipFile(archive, "w", zipfile.ZIP_DEFLATED) as handle:
+                    handle.write(path, arcname=path.name)
+                path.unlink()
+
+    def _compress_artifacts(self) -> None:
+        files = sorted(self.directory.glob("step_*.pkl"), key=lambda item: item.stat().st_mtime)
+        for path in files[:-self.keep_recent]:
+            archive = path.with_suffix(".zip")
+            if self.compress_old and not archive.exists():
+                with zipfile.ZipFile(archive, "w", zipfile.ZIP_DEFLATED) as handle:
+                    handle.write(path, arcname=path.name)
+                path.unlink()

easymodd/cli.py

@@ -0,0 +1,36 @@
+"""Installed EasyMoDD command-line entry point."""
+
+from __future__ import annotations
+
+import argparse
+from importlib.metadata import version, PackageNotFoundError
+
+from .config import load_config
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="easymodd", description="Configurable training tools")
+    parser.add_argument("command", choices=["validate-config", "inspect-config", "version"], help="Operation to perform")
+    parser.add_argument("--config", default=None, help="Consumer-project TOML config path")
+    args = parser.parse_args()
+    if args.command == "version":
+        try:
+            print(version("easymodd"))
+        except PackageNotFoundError:
+            print("0.1.0 (source checkout)")
+        return
+    if not args.config:
+        parser.error(f"--config is required for {args.command}; EasyMoDD does not ship a project config")
+    if args.command == "validate-config":
+        config = load_config(args.config)
+        print(f"Valid EasyMoDD config: {config.source}")
+    else:
+        config = load_config(args.config)
+        for section, values in config.values.items():
+            print(f"[{section}]")
+            for key, value in values.items():
+                print(f"{key} = {value!r}")
+
+
+if __name__ == "__main__":
+    main()

easymodd/config.py

@@ -0,0 +1,56 @@
+"""Configuration loading and validation for EasyMoDD projects."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import tomllib
+from typing import Any
+
+
+@dataclass(frozen=True)
+class EasyMoDDConfig:
+    """Validated TOML configuration with paths resolved from its location."""
+
+    values: dict[str, Any]
+    source: Path
+
+    def get(self, section: str, key: str, default: Any = None) -> Any:
+        return self.values.get(section, {}).get(key, default)
+
+    def path(self, section: str, key: str, default: str | None = None) -> Path | None:
+        value = self.get(section, key, default)
+        if value is None:
+            return None
+        path = Path(str(value))
+        return path if path.is_absolute() else (self.source.parent / path).resolve()
+
+
+def load_config(path: str | Path = "config.txt") -> EasyMoDDConfig:
+    """Load TOML from a `.txt` config file and report actionable errors."""
+    source = Path(path).resolve()
+    try:
+        raw = tomllib.loads(source.read_text(encoding="utf-8"))
+    except FileNotFoundError as error:
+        raise FileNotFoundError(
+            f"EasyMoDD config was not found: {source}. Create config.txt first."
+        ) from error
+    except tomllib.TOMLDecodeError as error:
+        raise ValueError(f"Invalid TOML in {source}: {error}") from error
+
+    if not isinstance(raw, dict):
+        raise ValueError("EasyMoDD config must contain TOML sections")
+    allowed_sections = {
+        "project", "paths", "data", "model", "training", "validation",
+        "checkpoints", "device", "logging",
+    }
+    unknown = sorted(set(raw) - allowed_sections)
+    if unknown:
+        raise ValueError(f"Unknown config section(s): {', '.join(unknown)}")
+    checkpoints = raw.get("checkpoints", {})
+    if not isinstance(checkpoints, dict):
+        raise ValueError("[checkpoints] must be a TOML table")
+    retention = checkpoints.get("keep_recent", 2)
+    if not isinstance(retention, int) or retention < 1:
+        raise ValueError("[checkpoints] keep_recent must be an integer >= 1")
+    return EasyMoDDConfig(values=raw, source=source)

easymodd/data.py

@@ -0,0 +1,127 @@
+"""Small dataset primitives shared by EasyMoDD trainers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import numpy as np
+
+
+class Dataset:
+    """Minimal indexable dataset contract."""
+
+    def __len__(self):
+        raise NotImplementedError
+
+    def __getitem__(self, index):
+        raise NotImplementedError
+
+
+class BatchLoader:
+    """Deterministic mini-batch iterator for any indexable Dataset."""
+
+    def __init__(self, dataset: Dataset, batch_size: int = 32, shuffle: bool = True,
+                 drop_last: bool = False, seed: int = 42):
+        if batch_size < 1:
+            raise ValueError("batch_size must be at least 1")
+        self.dataset = dataset
+        self.batch_size = batch_size
+        self.shuffle = shuffle
+        self.drop_last = drop_last
+        self.seed = seed
+
+    def __iter__(self):
+        rng = np.random.default_rng(self.seed)
+        indices = np.arange(len(self.dataset))
+        if self.shuffle:
+            rng.shuffle(indices)
+        for start in range(0, len(indices), self.batch_size):
+            batch_indices = indices[start:start + self.batch_size]
+            if self.drop_last and len(batch_indices) < self.batch_size:
+                continue
+            yield [self.dataset[int(index)] for index in batch_indices]
+
+    def __len__(self):
+        size = len(self.dataset) // self.batch_size
+        return size if self.drop_last else (size + bool(len(self.dataset) % self.batch_size))
+
+
+def split_dataset(dataset: Dataset, validation_fraction: float = 0.1, seed: int = 42):
+    """Return disjoint train and validation Subset objects."""
+    if not 0 < validation_fraction < 1:
+        raise ValueError("validation_fraction must be between 0 and 1")
+    indices = np.arange(len(dataset))
+    np.random.default_rng(seed).shuffle(indices)
+    cutoff = max(1, int(len(indices) * (1 - validation_fraction)))
+    return Subset(dataset, indices[:cutoff]), Subset(dataset, indices[cutoff:])
+
+
+class Subset(Dataset):
+    def __init__(self, dataset: Dataset, indices):
+        if len(indices) == 0:
+            raise ValueError("subset cannot be empty")
+        self.dataset = dataset
+        self.indices = np.asarray(indices)
+
+    def __len__(self):
+        return len(self.indices)
+
+    def __getitem__(self, index):
+        return self.dataset[int(self.indices[index])]
+
+
+class ArrayDataset(Dataset):
+    """Dataset for aligned NumPy/CuPy-compatible input and target arrays."""
+
+    def __init__(self, inputs, targets, transform=None, target_transform=None):
+        if len(inputs) != len(targets):
+            raise ValueError("inputs and targets must contain the same number of rows")
+        if len(inputs) == 0:
+            raise ValueError("dataset cannot be empty")
+        self.inputs = inputs
+        self.targets = targets
+        self.transform = transform
+        self.target_transform = target_transform
+
+    def __len__(self):
+        return len(self.inputs)
+
+    def __getitem__(self, index):
+        inputs, targets = self.inputs[index], self.targets[index]
+        return (self.transform(inputs) if self.transform else inputs,
+                self.target_transform(targets) if self.target_transform else targets)
+
+
+def collate_batch(items):
+    if not items:
+        raise ValueError("Cannot collate an empty batch")
+    inputs, targets = zip(*items)
+    return np.stack(inputs), np.stack(targets)
+
+
+class TextDataset(Dataset):
+    """Packed next-token windows from a UTF-8 text file."""
+
+    def __init__(self, source: str | Path, tokenizer, sequence_length: int):
+        if sequence_length < 2:
+            raise ValueError("sequence_length must be at least 2")
+        path = Path(source)
+        if not path.is_file():
+            raise FileNotFoundError(f"Text dataset was not found: {path}")
+        tokens = tokenizer.encode(path.read_text(encoding="utf-8"))
+        self.windows = []
+        for start in range(0, len(tokens) - sequence_length, sequence_length):
+            window = tokens[start : start + sequence_length + 1]
+            if len(window) == sequence_length + 1:
+                self.windows.append(np.asarray(window, dtype=np.int32))
+        if len(self.windows) < 2:
+            raise ValueError(
+                f"Text dataset {path} is too small for sequence_length={sequence_length}; "
+                "provide more text or reduce the sequence length."
+            )
+
+    def __len__(self):
+        return len(self.windows)
+
+    def __getitem__(self, index):
+        window = self.windows[index]
+        return window[:-1], window[1:]

easymodd/experiments.py

@@ -0,0 +1,37 @@
+"""Lightweight local experiment tracking with no external service required."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+class Experiment:
+    """Record configuration and metrics locally, optionally integrating later."""
+
+    def __init__(self, name: str, directory: str | Path = "runs", config: dict | None = None):
+        if not name.strip():
+            raise ValueError("Experiment name cannot be empty")
+        self.name = name
+        self.directory = Path(directory) / name
+        self.directory.mkdir(parents=True, exist_ok=True)
+        self.config = config or {}
+        self._write_json("config.json", self.config)
+
+    def log(self, metrics: dict[str, float], step: int | None = None) -> None:
+        event = {"time": datetime.now(timezone.utc).isoformat(), "step": step, **metrics}
+        with (self.directory / "metrics.jsonl").open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(event) + "\n")
+
+    def artifact(self, name: str, content: str | bytes) -> Path:
+        path = self.directory / name
+        path.parent.mkdir(parents=True, exist_ok=True)
+        if isinstance(content, bytes):
+            path.write_bytes(content)
+        else:
+            path.write_text(content, encoding="utf-8")
+        return path
+
+    def _write_json(self, name: str, value) -> None:
+        (self.directory / name).write_text(json.dumps(value, indent=2), encoding="utf-8")

easymodd/losses.py

@@ -0,0 +1,57 @@
+"""Loss functions with explicit gradient helpers."""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+class MSELoss:
+    """Mean squared error for regression and educational custom loops."""
+
+    def __call__(self, predictions, targets) -> float:
+        return float(np.mean((predictions - targets) ** 2))
+
+    def gradient(self, predictions, targets):
+        return 2.0 * (predictions - targets) / predictions.size
+
+
+class CrossEntropyLoss:
+    """Stable softmax cross-entropy for class-index targets."""
+
+    def __call__(self, logits, targets) -> float:
+        shifted = logits - np.max(logits, axis=-1, keepdims=True)
+        logsumexp = np.log(np.sum(np.exp(shifted), axis=-1, keepdims=True))
+        rows = np.arange(len(targets))
+        return float(np.mean(-shifted[rows, targets] + logsumexp[:, 0]))
+
+    def gradient(self, logits, targets):
+        shifted = logits - np.max(logits, axis=-1, keepdims=True)
+        probabilities = np.exp(shifted)
+        probabilities /= np.sum(probabilities, axis=-1, keepdims=True)
+        probabilities[np.arange(len(targets)), targets] -= 1
+        return probabilities / len(targets)
+
+
+class L1Loss:
+    def __call__(self, predictions, targets) -> float:
+        return float(np.mean(np.abs(predictions - targets)))
+
+    def gradient(self, predictions, targets):
+        return np.sign(predictions - targets) / predictions.size
+
+
+class HuberLoss:
+    def __init__(self, delta: float = 1.0):
+        if delta <= 0:
+            raise ValueError("delta must be greater than zero")
+        self.delta = delta
+
+    def __call__(self, predictions, targets) -> float:
+        error = np.abs(predictions - targets)
+        quadratic = np.minimum(error, self.delta)
+        linear = error - quadratic
+        return float(np.mean(0.5 * quadratic ** 2 + self.delta * linear))
+
+    def gradient(self, predictions, targets):
+        error = predictions - targets
+        return np.where(np.abs(error) <= self.delta, error, self.delta * np.sign(error)) / predictions.size

easymodd/metrics.py

@@ -0,0 +1,18 @@
+"""Training metrics that work with ordinary array-like predictions."""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def accuracy(predictions, targets) -> float:
+    predicted = np.argmax(predictions, axis=-1) if getattr(predictions, "ndim", 0) > 1 else np.rint(predictions)
+    return float(np.mean(predicted == targets))
+
+
+def mean_absolute_error(predictions, targets) -> float:
+    return float(np.mean(np.abs(predictions - targets)))
+
+
+def perplexity(cross_entropy: float) -> float:
+    return float(np.exp(np.clip(cross_entropy, -50, 50)))

easymodd/models/__init__.py

@@ -0,0 +1,7 @@
+"""Built-in model families."""
+
+from .mlp import MLP, build_mlp
+from .text_transformer import TextTransformerConfig
+from .vision_transformer import VisionTransformerConfig
+
+__all__ = ["MLP", "TextTransformerConfig", "VisionTransformerConfig", "build_mlp"]

easymodd/models/mlp.py

@@ -0,0 +1,24 @@
+"""General-purpose multilayer perceptron."""
+
+from __future__ import annotations
+
+from ..nn import Linear, ReLU, Sequential
+
+
+class MLP(Sequential):
+    """Composable feed-forward model for regression and classification."""
+
+    def __init__(self, input_size: int, hidden_sizes: list[int], output_size: int,
+                 device: str = "cpu"):
+        modules = []
+        current = input_size
+        for hidden_size in hidden_sizes:
+            modules.extend([Linear(current, hidden_size, device=device), ReLU()])
+            current = hidden_size
+        modules.append(Linear(current, output_size, device=device))
+        super().__init__(*modules)
+
+
+def build_mlp(input_size: int, hidden_sizes: list[int], output_size: int,
+              device: str = "cpu") -> MLP:
+    return MLP(input_size, hidden_sizes, output_size, device=device)

easymodd/models/text_transformer.py

@@ -0,0 +1,29 @@
+"""Configuration contract for decoder-only text Transformers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class TextTransformerConfig:
+    """Validated architecture settings for a causal text model."""
+
+    vocab_size: int
+    embed_dim: int = 512
+    heads: int = 8
+    layers: int = 4
+    ff_dim: int = 2048
+    sequence_length: int = 512
+
+    def __post_init__(self) -> None:
+        if min(self.vocab_size, self.embed_dim, self.heads, self.layers, self.ff_dim) < 1:
+            raise ValueError("Text Transformer dimensions must be positive")
+        if self.embed_dim % self.heads:
+            raise ValueError("embed_dim must be divisible by heads")
+        if self.sequence_length < 2:
+            raise ValueError("sequence_length must be at least 2")
+
+    @property
+    def head_dim(self) -> int:
+        return self.embed_dim // self.heads

easymodd/models/vision_transformer.py

@@ -0,0 +1,30 @@
+"""Configuration contract for Vision Transformer models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class VisionTransformerConfig:
+    image_size: int = 224
+    patch_size: int = 16
+    channels: int = 3
+    classes: int = 10
+    embed_dim: int = 384
+    heads: int = 6
+    layers: int = 6
+    ff_dim: int = 1536
+
+    def __post_init__(self) -> None:
+        if self.image_size % self.patch_size:
+            raise ValueError("image_size must be divisible by patch_size")
+        if min(self.patch_size, self.channels, self.classes, self.embed_dim, self.heads, self.layers, self.ff_dim) < 1:
+            raise ValueError("Vision Transformer dimensions must be positive")
+        if self.embed_dim % self.heads:
+            raise ValueError("embed_dim must be divisible by heads")
+
+    @property
+    def patch_count(self) -> int:
+        patches_per_side = self.image_size // self.patch_size
+        return patches_per_side * patches_per_side