torchloop 0.2.0__tar.gz → 0.2.3__tar.gz

{torchloop-0.2.0 → torchloop-0.2.3}/.github/workflows/publish.yml

@@ -27,4 +27,4 @@ jobs:
         run: hatch build
 
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@release/v1

torchloop-0.2.3/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
+
+## [0.2.3] - 2026-03-27
+
+### Added
+
+- Trainer gradient accumulation via `accumulate_steps`.
+- Callback system with `Callback`, `EarlyStopping`, `ModelCheckpoint`, `CSVLogger`, and `StopTraining`.
+- Edge deployment submodule with `deploy_to_edge` and `estimate_model`.
+- Example script for edge deployment in `examples/edge_deployment.py`.
+- Expanded test suite for callbacks, exporter, and edge deployment logic.
+
+### Changed
+
+- AMP configuration now prefers `use_amp`; legacy `amp` is kept as a deprecated alias.
+- Public exports updated to include `Exporter`, callbacks, and edge APIs.
+- Project metadata updated for v0.2.3 and edge/dev optional dependencies.
+- README updated with callback usage and edge deployment documentation.
+
+### Fixed
+
+- Pytest import resolution for src-layout test runs.
+- Deterministic early-stopping test behavior in trainer test suite.
+
+## [0.2.0] - 2026-03-xx
+
+### Added
+
+- Automatic mixed precision (AMP) support in Trainer.
+- Learning-rate scheduler integration in Trainer.
+
+## [0.1.0] - 2026-03-xx
+
+### Added
+
+- Core `Trainer`, `Evaluator`, and `Exporter` APIs.

{torchloop-0.2.0 → torchloop-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: torchloop
-Version: 0.2.0
+Version: 0.2.3
 Summary: Lightweight PyTorch utility library for training, evaluation, and TFLite export — without the framework lock-in.
 Project-URL: Homepage, https://github.com/Tharun007-TK/torchloop
 Project-URL: Repository, https://github.com/Tharun007-TK/torchloop
@@ -40,24 +40,39 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Requires-Python: >=3.9
 Requires-Dist: matplotlib>=3.7.0
-Requires-Dist: numpy>=1.24.0
-Requires-Dist: scikit-learn>=1.3.0
-Requires-Dist: torch>=2.0.0
+Requires-Dist: numpy>=1.20
+Requires-Dist: scikit-learn>=1.0
+Requires-Dist: torch<2.6,>=2.0
 Requires-Dist: torchvision>=0.15.0
 Requires-Dist: tqdm>=4.65.0
 Provides-Extra: all
+Requires-Dist: black>=23.0; extra == 'all'
+Requires-Dist: coremltools>=7.0; (platform_system == 'Darwin') and extra == 'all'
 Requires-Dist: hatch>=1.7.0; extra == 'all'
+Requires-Dist: mypy>=1.0; extra == 'all'
 Requires-Dist: onnx>=1.14.0; extra == 'all'
+Requires-Dist: onnx>=1.15; extra == 'all'
 Requires-Dist: onnxruntime>=1.15.0; extra == 'all'
-Requires-Dist: pytest-cov>=4.1.0; extra == 'all'
-Requires-Dist: pytest>=7.4.0; extra == 'all'
+Requires-Dist: onnxruntime>=1.16; extra == 'all'
+Requires-Dist: pytest-cov>=4.0; extra == 'all'
+Requires-Dist: pytest>=7.0; extra == 'all'
 Requires-Dist: ruff>=0.1.0; extra == 'all'
+Requires-Dist: tensorflow-lite-runtime>=2.15; (platform_system != 'Darwin') and extra == 'all'
 Requires-Dist: tensorflow>=2.13.0; extra == 'all'
+Requires-Dist: torchinfo>=1.8; extra == 'all'
 Provides-Extra: dev
+Requires-Dist: black>=23.0; extra == 'dev'
 Requires-Dist: hatch>=1.7.0; extra == 'dev'
-Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
-Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
 Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: torchinfo>=1.8; extra == 'dev'
+Provides-Extra: edge
+Requires-Dist: coremltools>=7.0; (platform_system == 'Darwin') and extra == 'edge'
+Requires-Dist: onnx>=1.15; extra == 'edge'
+Requires-Dist: onnxruntime>=1.16; extra == 'edge'
+Requires-Dist: tensorflow-lite-runtime>=2.15; (platform_system != 'Darwin') and extra == 'edge'
 Provides-Extra: export
 Requires-Dist: onnx>=1.14.0; extra == 'export'
 Requires-Dist: onnxruntime>=1.15.0; extra == 'export'
@@ -86,10 +101,17 @@ You write the same PyTorch training loop in every project. Same checkpoint logic
 ## Install
 
 ```bash
+# Base installation
 pip install torchloop
 
 # With TFLite export support
 pip install torchloop[export]
+
+# With edge deployment support
+pip install torchloop[edge]
+
+# Development setup
+pip install torchloop[dev]
 ```
 
 ---
@@ -99,16 +121,21 @@ pip install torchloop[export]
 ### Training
 
 ```python
-from torchloop import Trainer
+from torchloop import EarlyStopping, ModelCheckpoint, Trainer
 
 trainer = Trainer(
     model,
     optimizer=torch.optim.Adam(model.parameters()),
     criterion=torch.nn.CrossEntropyLoss(),
     device="cuda",
-    patience=5,           # early stopping
+    use_amp=True,
+    accumulate_steps=4,
+    patience=5,
 )
 
+trainer.add_callback(EarlyStopping(patience=5))
+trainer.add_callback(ModelCheckpoint(filepath="best.pt"))
+
 history = trainer.fit(train_loader, val_loader, epochs=30)
 trainer.save("best.pt")
 ```
@@ -139,6 +166,25 @@ exp.to_onnx("model.onnx")
 exp.to_tflite("model.tflite", quantize=True)
 ```
 
+### Edge Deployment
+
+```python
+from torchloop.edge import deploy_to_edge, estimate_model
+
+stats = estimate_model(model, (1, 3, 224, 224), target_device="esp32")
+print(f"RAM: {stats['estimated_ram_mb']} MB")
+print(f"Latency: {stats['estimated_latency_ms']} ms")
+
+deploy_to_edge(
+    model,
+    target="esp32",
+    input_shape=(1, 3, 224, 224),
+    output_path="model.tflite",
+    quantize=True,
+    quantize_type="int8",
+)
+```
+
 ---
 
 ## Design Principles
@@ -151,9 +197,12 @@ exp.to_tflite("model.tflite", quantize=True)
 
 ## Roadmap
 
-- [ ] `v0.1.0` — Trainer, Evaluator, Exporter
-- [ ] `v0.2.0` — LR scheduler support, mixed precision (AMP)
-- [ ] `v0.3.0` — W&B / MLflow logging hooks
+- [x] `v0.1.0` — Trainer, Evaluator, Exporter
+- [x] `v0.2.0` — LR scheduler support, mixed precision (AMP)
+- [x] `v0.2.1` — Gradient accumulation + callbacks
+- [x] `v0.2.2` — Edge submodule
+- [ ] `v0.3.0` — W&B / MLflow hooks + CoreML export
+- [ ] `v0.3.1` — Model pruning utilities
 
 ---
 

{torchloop-0.2.0 → torchloop-0.2.3}/README.md

@@ -20,10 +20,17 @@ You write the same PyTorch training loop in every project. Same checkpoint logic
 ## Install
 
 ```bash
+# Base installation
 pip install torchloop
 
 # With TFLite export support
 pip install torchloop[export]
+
+# With edge deployment support
+pip install torchloop[edge]
+
+# Development setup
+pip install torchloop[dev]
 ```
 
 ---
@@ -33,16 +40,21 @@ pip install torchloop[export]
 ### Training
 
 ```python
-from torchloop import Trainer
+from torchloop import EarlyStopping, ModelCheckpoint, Trainer
 
 trainer = Trainer(
     model,
     optimizer=torch.optim.Adam(model.parameters()),
     criterion=torch.nn.CrossEntropyLoss(),
     device="cuda",
-    patience=5,           # early stopping
+    use_amp=True,
+    accumulate_steps=4,
+    patience=5,
 )
 
+trainer.add_callback(EarlyStopping(patience=5))
+trainer.add_callback(ModelCheckpoint(filepath="best.pt"))
+
 history = trainer.fit(train_loader, val_loader, epochs=30)
 trainer.save("best.pt")
 ```
@@ -73,6 +85,25 @@ exp.to_onnx("model.onnx")
 exp.to_tflite("model.tflite", quantize=True)
 ```
 
+### Edge Deployment
+
+```python
+from torchloop.edge import deploy_to_edge, estimate_model
+
+stats = estimate_model(model, (1, 3, 224, 224), target_device="esp32")
+print(f"RAM: {stats['estimated_ram_mb']} MB")
+print(f"Latency: {stats['estimated_latency_ms']} ms")
+
+deploy_to_edge(
+    model,
+    target="esp32",
+    input_shape=(1, 3, 224, 224),
+    output_path="model.tflite",
+    quantize=True,
+    quantize_type="int8",
+)
+```
+
 ---
 
 ## Design Principles
@@ -85,9 +116,12 @@ exp.to_tflite("model.tflite", quantize=True)
 
 ## Roadmap
 
-- [ ] `v0.1.0` — Trainer, Evaluator, Exporter
-- [ ] `v0.2.0` — LR scheduler support, mixed precision (AMP)
-- [ ] `v0.3.0` — W&B / MLflow logging hooks
+- [x] `v0.1.0` — Trainer, Evaluator, Exporter
+- [x] `v0.2.0` — LR scheduler support, mixed precision (AMP)
+- [x] `v0.2.1` — Gradient accumulation + callbacks
+- [x] `v0.2.2` — Edge submodule
+- [ ] `v0.3.0` — W&B / MLflow hooks + CoreML export
+- [ ] `v0.3.1` — Model pruning utilities
 
 ---
 

torchloop-0.2.3/examples/edge_deployment.py

@@ -0,0 +1,67 @@
+"""Example: train a tiny CNN and prepare an ESP32-friendly artifact."""
+
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+from torch.utils.data import DataLoader, TensorDataset
+
+from torchloop import EarlyStopping, Trainer
+from torchloop.edge import deploy_to_edge, estimate_model
+
+
+class SimpleCNN(nn.Module):
+    """Small CNN for demonstration."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.conv = nn.Conv2d(3, 16, kernel_size=3, padding=1)
+        self.pool = nn.AdaptiveAvgPool2d(1)
+        self.fc = nn.Linear(16, 10)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        x = torch.relu(self.conv(x))
+        x = self.pool(x)
+        x = x.view(x.size(0), -1)
+        return self.fc(x)
+
+
+def main() -> None:
+    """Run training, estimation, and deployment."""
+    model = SimpleCNN()
+    x_data = torch.randn(100, 3, 32, 32)
+    y_data = torch.randint(0, 10, (100,))
+
+    dataset = TensorDataset(x_data, y_data)
+    loader = DataLoader(dataset, batch_size=10, shuffle=True)
+
+    trainer = Trainer(
+        model,
+        optimizer=torch.optim.Adam(model.parameters()),
+        criterion=nn.CrossEntropyLoss(),
+        device="cpu",
+        use_amp=False,
+        accumulate_steps=1,
+    )
+    trainer.add_callback(EarlyStopping(patience=3))
+    trainer.fit(loader, loader, epochs=10)
+
+    stats = estimate_model(model, (1, 3, 32, 32), target_device="esp32")
+    print("ESP32 estimate")
+    print(f"Params: {stats['params']:,}")
+    print(f"RAM: {stats['estimated_ram_mb']:.2f} MB")
+    print(f"Latency: {stats['estimated_latency_ms']:.2f} ms")
+
+    deploy_to_edge(
+        model,
+        target="esp32",
+        input_shape=(1, 3, 32, 32),
+        output_path="model_esp32.tflite",
+        quantize=True,
+        quantize_type="int8",
+    )
+    print("Export complete: model_esp32.tflite")
+
+
+if __name__ == "__main__":
+    main()

{torchloop-0.2.0 → torchloop-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "torchloop"
-version = "0.2.0"
+version = "0.2.3"
 description = "Lightweight PyTorch utility library for training, evaluation, and TFLite export — without the framework lock-in."
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -26,27 +26,36 @@ classifiers = [
 ]
 
 dependencies = [
-  "torch>=2.0.0",
+  "torch>=2.0,<2.6",
   "torchvision>=0.15.0",
-  "scikit-learn>=1.3.0",
-  "numpy>=1.24.0",
+  "scikit-learn>=1.0",
+  "numpy>=1.20",
   "matplotlib>=3.7.0",
   "tqdm>=4.65.0",
 ]
 
 [project.optional-dependencies]
+edge = [
+  "onnx>=1.15",
+  "onnxruntime>=1.16",
+  "tensorflow-lite-runtime>=2.15; platform_system != 'Darwin'",
+  "coremltools>=7.0; platform_system == 'Darwin'",
+]
 export = [
   "onnx>=1.14.0",
   "onnxruntime>=1.15.0",
   "tensorflow>=2.13.0",   # needed for TFLite conversion
 ]
 dev = [
-  "pytest>=7.4.0",
-  "pytest-cov>=4.1.0",
+  "pytest>=7.0",
+  "pytest-cov>=4.0",
+  "black>=23.0",
+  "mypy>=1.0",
+  "torchinfo>=1.8",
   "ruff>=0.1.0",          # linter + formatter
   "hatch>=1.7.0",
 ]
-all = ["torchloop[export,dev]"]
+all = ["torchloop[edge,export,dev]"]
 
 [project.urls]
 Homepage = "https://github.com/Tharun007-TK/torchloop"
@@ -65,4 +74,9 @@ select = ["E", "F", "I"]   # pycodestyle + pyflakes + isort
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+pythonpath = ["src"]
 addopts = "--cov=src/torchloop --cov-report=term-missing"
+filterwarnings = [
+  "ignore:AMP requested on non-CUDA.*:UserWarning",
+  "ignore::DeprecationWarning",
+]

torchloop-0.2.3/requirements.txt

@@ -0,0 +1,6 @@
+torch>=2.0.0
+torchvision>=0.15.0
+scikit-learn>=1.3.0
+numpy>=1.24.0
+matplotlib>=3.7.0
+tqdm>=4.65.0

torchloop-0.2.3/src/torchloop/__init__.py

@@ -0,0 +1,37 @@
+"""
+torchloop — Lightweight PyTorch utility library.
+
+Modules:
+    trainer   : Training loop, metric logging, checkpoint management
+    evaluator : Classification report, confusion matrix, per-class F1
+    exporter  : PyTorch → ONNX → TFLite with optional quantization
+"""
+
+__version__ = "0.2.3"
+__author__ = "Tharun Kumar"
+
+from torchloop.callbacks import (
+    CSVLogger,
+    Callback,
+    EarlyStopping,
+    ModelCheckpoint,
+    StopTraining,
+)
+from torchloop.edge import deploy_to_edge, estimate_model
+from torchloop.evaluator import Evaluator
+from torchloop.exporter import Exporter
+from torchloop.trainer import Trainer
+
+__all__ = [
+    "Trainer",
+    "Evaluator",
+    "Exporter",
+    "Callback",
+    "EarlyStopping",
+    "ModelCheckpoint",
+    "CSVLogger",
+    "StopTraining",
+    "deploy_to_edge",
+    "estimate_model",
+    "__version__",
+]

torchloop-0.2.3/src/torchloop/callbacks.py

@@ -0,0 +1,216 @@
+"""Callback utilities for training lifecycle hooks."""
+
+from __future__ import annotations
+
+import csv
+from pathlib import Path
+from typing import Any, Optional
+
+import torch
+
+
+class StopTraining(Exception):
+    """Raised by callbacks to request early stop of training."""
+
+
+class Callback:
+    """Base callback class.
+
+    Subclass this and override hook methods to customize training behavior.
+    """
+
+    def on_train_begin(self, logs: Optional[dict[str, Any]] = None) -> None:
+        """Called before the first epoch starts.
+
+        Args:
+            logs: Optional training state dictionary.
+        """
+
+    def on_train_end(self, logs: Optional[dict[str, Any]] = None) -> None:
+        """Called after training ends.
+
+        Args:
+            logs: Optional training state dictionary.
+        """
+
+    def on_epoch_begin(
+        self,
+        epoch: int,
+        logs: Optional[dict[str, Any]] = None,
+    ) -> None:
+        """Called at the start of each epoch.
+
+        Args:
+            epoch: Current epoch number.
+            logs: Optional training state dictionary.
+        """
+
+    def on_epoch_end(
+        self,
+        epoch: int,
+        logs: Optional[dict[str, Any]] = None,
+    ) -> None:
+        """Called at the end of each epoch.
+
+        Args:
+            epoch: Current epoch number.
+            logs: Optional training state dictionary.
+        """
+
+    def on_batch_end(
+        self,
+        batch: int,
+        logs: Optional[dict[str, Any]] = None,
+    ) -> None:
+        """Called after each training batch.
+
+        Args:
+            batch: Zero-based batch index.
+            logs: Optional batch-level metrics.
+        """
+
+
+class EarlyStopping(Callback):
+    """Stop training when a monitored metric stops improving.
+
+    Args:
+        patience: Number of epochs to wait for an improvement.
+        monitor: Metric name expected in logs.
+        min_delta: Minimum improvement required to reset patience.
+    """
+
+    def __init__(
+        self,
+        patience: int = 5,
+        monitor: str = "val_loss",
+        min_delta: float = 0.0,
+    ) -> None:
+        if patience < 1:
+            raise ValueError("patience must be >= 1")
+        if min_delta < 0:
+            raise ValueError("min_delta must be >= 0")
+
+        self.patience = patience
+        self.monitor = monitor
+        self.min_delta = min_delta
+        self.best = float("inf")
+        self.counter = 0
+
+    def on_epoch_end(
+        self,
+        epoch: int,
+        logs: Optional[dict[str, Any]] = None,
+    ) -> None:
+        """Check metric value and raise StopTraining when patience is exceeded.
+
+        Args:
+            epoch: Current epoch number.
+            logs: Metrics dictionary from trainer.
+        """
+        logs = logs or {}
+        current = logs.get(self.monitor)
+        if current is None:
+            return
+
+        if current <= self.best - self.min_delta:
+            self.best = float(current)
+            self.counter = 0
+            return
+
+        self.counter += 1
+        if self.counter >= self.patience:
+            raise StopTraining(f"Early stopping triggered at epoch {epoch}")
+
+
+class ModelCheckpoint(Callback):
+    """Save model checkpoints based on monitored metric.
+
+    Args:
+        monitor: Metric name expected in logs.
+        save_best_only: Save only when monitored metric improves.
+        filepath: Path to write checkpoint file.
+    """
+
+    def __init__(
+        self,
+        monitor: str = "val_loss",
+        save_best_only: bool = True,
+        filepath: str = "checkpoint.pt",
+    ) -> None:
+        self.monitor = monitor
+        self.save_best_only = save_best_only
+        self.filepath = Path(filepath)
+        self.best = float("inf")
+
+    def on_epoch_end(
+        self,
+        epoch: int,
+        logs: Optional[dict[str, Any]] = None,
+    ) -> None:
+        """Persist model checkpoint if criteria are met.
+
+        Args:
+            epoch: Current epoch number.
+            logs: Metrics dictionary from trainer.
+        """
+        logs = logs or {}
+        model = logs.get("model")
+        if model is None:
+            return
+
+        current = logs.get(self.monitor)
+        if current is None:
+            return
+
+        if not self.save_best_only:
+            torch.save(model.state_dict(), self.filepath)
+            return
+
+        if float(current) < self.best:
+            self.best = float(current)
+            torch.save(model.state_dict(), self.filepath)
+
+
+class CSVLogger(Callback):
+    """Log epoch metrics to a CSV file.
+
+    Args:
+        log_dir: Directory where CSV logs are written.
+        filename: Name of CSV file.
+    """
+
+    def __init__(self, log_dir: str = "./logs", filename: str = "metrics.csv") -> None:
+        self.log_dir = Path(log_dir)
+        self.filename = filename
+        self._initialized = False
+        self._fieldnames: list[str] = []
+
+    def on_epoch_end(
+        self,
+        epoch: int,
+        logs: Optional[dict[str, Any]] = None,
+    ) -> None:
+        """Append epoch metrics to CSV.
+
+        Args:
+            epoch: Current epoch number.
+            logs: Metrics dictionary from trainer.
+        """
+        logs = dict(logs or {})
+        logs["epoch"] = epoch
+
+        self.log_dir.mkdir(parents=True, exist_ok=True)
+        file_path = self.log_dir / self.filename
+
+        if not self._initialized:
+            self._fieldnames = sorted(logs.keys())
+            with file_path.open("w", newline="", encoding="utf-8") as f:
+                writer = csv.DictWriter(f, fieldnames=self._fieldnames)
+                writer.writeheader()
+                writer.writerow({k: logs.get(k) for k in self._fieldnames})
+            self._initialized = True
+            return
+
+        with file_path.open("a", newline="", encoding="utf-8") as f:
+            writer = csv.DictWriter(f, fieldnames=self._fieldnames)
+            writer.writerow({k: logs.get(k) for k in self._fieldnames})

torchloop-0.2.3/src/torchloop/edge/__init__.py

@@ -0,0 +1,6 @@
+"""Edge deployment utilities for torchloop."""
+
+from torchloop.edge.deploy import deploy_to_edge
+from torchloop.edge.estimate import estimate_model
+
+__all__ = ["deploy_to_edge", "estimate_model"]