microflame 0.1.0__tar.gz

microflame-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agoth Arop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

microflame-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: microflame
+Version: 0.1.0
+Summary: A minimal PyTorch training loop with checkpointing, resuming, and plotting built in.
+Project-URL: Homepage, https://github.com/agoth24/microflame
+Project-URL: Repository, https://github.com/agoth24/microflame
+Author: Agoth Arop
+License-Expression: MIT
+License-File: LICENSE
+Keywords: deep-learning,machine-learning,pytorch,trainer,training
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: matplotlib>=3.0
+Requires-Dist: torch>=2.0
+Requires-Dist: tqdm>=4.0
+Description-Content-Type: text/markdown
+
+# microflame
+
+[![PyPI](https://img.shields.io/pypi/v/microflame.svg)](https://pypi.org/project/microflame/)
+[![Python](https://img.shields.io/pypi/pyversions/microflame.svg)](https://pypi.org/project/microflame/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A minimal PyTorch training loop — checkpointing, resuming, and plotting built in.
+
+## Install
+
+```bash
+pip install microflame
+```
+
+## Quickstart
+
+```python
+from torch import nn
+from torch.optim import Adam
+from microflame import Trainer
+
+model = nn.Sequential(nn.Flatten(), nn.Linear(28 * 28, 128), nn.ReLU(), nn.Linear(128, 10))
+
+trainer = Trainer(
+    train_dataloader=train_loader,
+    val_dataloader=val_loader,
+    model=model,
+    loss_fn=nn.CrossEntropyLoss(),
+    optimizer=Adam(model.parameters(), lr=1e-3),
+)
+
+trainer.fit(num_epochs=10, save_path="checkpoint.pth", save_frequency=5)
+trainer.plot()
+```
+
+Resume from a checkpoint:
+
+```python
+trainer.resume("checkpoint.pth", num_epochs=20)
+```
+
+## Features
+
+- Automatic device selection (CUDA → MPS → CPU)
+- Training + validation loop with live `tqdm` progress and per-epoch metrics
+- Loss/accuracy history tracking
+- Checkpoint save/load (model, optimizer, scheduler, history)
+- Resume training from a checkpoint
+- One-line loss/accuracy plots via matplotlib
+
+## License
+
+MIT © Agoth Arop — see [LICENSE](LICENSE).

microflame-0.1.0/README.md

@@ -0,0 +1,53 @@
+# microflame
+
+[![PyPI](https://img.shields.io/pypi/v/microflame.svg)](https://pypi.org/project/microflame/)
+[![Python](https://img.shields.io/pypi/pyversions/microflame.svg)](https://pypi.org/project/microflame/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A minimal PyTorch training loop — checkpointing, resuming, and plotting built in.
+
+## Install
+
+```bash
+pip install microflame
+```
+
+## Quickstart
+
+```python
+from torch import nn
+from torch.optim import Adam
+from microflame import Trainer
+
+model = nn.Sequential(nn.Flatten(), nn.Linear(28 * 28, 128), nn.ReLU(), nn.Linear(128, 10))
+
+trainer = Trainer(
+    train_dataloader=train_loader,
+    val_dataloader=val_loader,
+    model=model,
+    loss_fn=nn.CrossEntropyLoss(),
+    optimizer=Adam(model.parameters(), lr=1e-3),
+)
+
+trainer.fit(num_epochs=10, save_path="checkpoint.pth", save_frequency=5)
+trainer.plot()
+```
+
+Resume from a checkpoint:
+
+```python
+trainer.resume("checkpoint.pth", num_epochs=20)
+```
+
+## Features
+
+- Automatic device selection (CUDA → MPS → CPU)
+- Training + validation loop with live `tqdm` progress and per-epoch metrics
+- Loss/accuracy history tracking
+- Checkpoint save/load (model, optimizer, scheduler, history)
+- Resume training from a checkpoint
+- One-line loss/accuracy plots via matplotlib
+
+## License
+
+MIT © Agoth Arop — see [LICENSE](LICENSE).

microflame-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "microflame"
+version = "0.1.0"
+description = "A minimal PyTorch training loop with checkpointing, resuming, and plotting built in."
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Agoth Arop" }]
+keywords = ["pytorch", "training", "deep-learning", "machine-learning", "trainer"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = ["torch>=2.0", "tqdm>=4.0", "matplotlib>=3.0"]
+readme = "README.md"
+
+[project.urls]
+Homepage = "https://github.com/agoth24/microflame"
+Repository = "https://github.com/agoth24/microflame"

microflame-0.1.0/src/microflame/__init__.py

@@ -0,0 +1,3 @@
+from .trainer import Trainer
+
+__all__ = ["Trainer"]

microflame-0.1.0/src/microflame/trainer.py

@@ -0,0 +1,209 @@
+import torch
+from torch import nn
+from torch.utils.data import DataLoader
+from torch.optim import Optimizer, lr_scheduler
+import matplotlib.pyplot as plt
+from tqdm import tqdm
+
+
+class Trainer:
+    def __init__(
+        self,
+        train_dataloader: DataLoader,
+        val_dataloader: DataLoader,
+        model: nn.Module,
+        loss_fn: nn.Module,
+        optimizer: Optimizer,
+        device: str | None = None,
+        scheduler: lr_scheduler.LRScheduler | None = None,
+        step_scheduler_per_batch: bool = False
+    ):
+        self.device = device or (
+            "cuda"
+            if torch.cuda.is_available()
+            else (
+                "mps" if (hasattr(torch, "mps") and torch.mps.is_available()) else "cpu"
+            )
+        )
+        self.train_dataloader = train_dataloader
+        self.val_dataloader = val_dataloader
+        self.model = model.to(self.device)
+        self.optimizer = optimizer
+        self.scheduler = scheduler
+        self.step_scheduler_per_batch = step_scheduler_per_batch
+        self.loss_fn = loss_fn
+
+        self.history = {
+            "train_loss": [],
+            "train_accuracy": [],
+            "val_loss": [],
+            "val_accuracy": [],
+        }
+
+    def accuracy(self, prediction, target):
+        return (prediction.argmax(1) == target).float().mean().item()
+
+    def _train_loop(self, current_epoch: int, num_epochs: int):
+        dataloader = self.train_dataloader
+        train_set_size = len(dataloader.dataset)
+        num_batches = len(dataloader)
+
+        train_loss, correct_preds = 0, 0
+        loop = tqdm(
+            dataloader, desc=f"Epoch [{current_epoch+1}/{num_epochs}]", leave=False
+        )
+        self.model.train()
+        for X, y in loop:
+            X, y = X.to(self.device), y.to(self.device)
+
+            # forward pass
+            pred = self.model(X)
+            loss = self.loss_fn(pred, y)
+
+            # backward pass
+            self.optimizer.zero_grad()
+            loss.backward()
+
+            self.optimizer.step()
+            if self.scheduler and self.step_scheduler_per_batch:
+                self.scheduler.step()
+
+            train_loss += loss.item()
+            correct_preds += self.accuracy(pred, y)
+
+            loop.set_postfix(Loss=loss.item())
+
+        train_loss /= num_batches
+        train_acc = 100 * correct_preds / train_set_size
+        return train_loss, train_acc
+
+    def _val_loop(self, current_epoch: int, num_epochs: int):
+        dataloader = self.val_dataloader
+        val_set_size = len(dataloader.dataset)
+        num_batches = len(dataloader)
+
+        val_loss, correct_preds = 0, 0
+        self.model.eval()
+        with torch.no_grad():
+            for X, y in dataloader:
+                X, y = X.to(self.device), y.to(self.device)
+
+                pred = self.model(X)
+                loss = self.loss_fn(pred, y)
+
+                val_loss += loss.item()
+                correct_preds += self.accuracy(pred, y)
+
+            val_loss /= num_batches
+            val_acc = 100 * correct_preds / val_set_size
+
+        return val_loss, val_acc
+
+    def fit(
+        self,
+        num_epochs: int,
+        save_path: str = "checkpoint.pth",
+        save_frequency: int | None = None,
+        start_epoch: int = 0,
+    ):
+
+        if start_epoch >= num_epochs:
+            raise ValueError("Can't run training loop. Training is already complete")
+
+        for epoch in range(start_epoch, num_epochs):
+            train_loss, train_acc = self._train_loop(
+                current_epoch=epoch, num_epochs=num_epochs
+            )
+            if self.scheduler and not self.step_scheduler_per_batch:
+                self.scheduler.step()
+            val_loss, val_acc = self._val_loop(
+                current_epoch=epoch, num_epochs=num_epochs
+            )
+
+            tqdm.write(
+                f"Epoch [{epoch+1}/{num_epochs}] "
+                f"loss={train_loss:.3f} acc={train_acc:.3f} | "
+                f"val_loss={val_loss:.3f} val_acc={val_acc:.3f}"
+            )
+
+            self.history["train_loss"].append(train_loss)
+            self.history["val_loss"].append(val_loss)
+            self.history["train_accuracy"].append(train_acc)
+            self.history["val_accuracy"].append(val_acc)
+
+            if save_frequency and (epoch + 1) % save_frequency == 0:
+                self.save_checkpoint(save_path, epoch)
+
+        if save_frequency:
+            self.save_checkpoint(save_path, epoch)
+
+    def save_checkpoint(self, path: str, epoch: int):
+        torch.save(
+            {
+                "epoch": epoch,
+                "model_state_dict": self.model.state_dict(),
+                "optimizer_state_dict": self.optimizer.state_dict(),
+                "scheduler_state_dict": (
+                    self.scheduler.state_dict() if self.scheduler else None
+                ),
+                "history": self.history,
+            },
+            path,
+        )
+
+    def load_checkpoint(self, path: str):
+        checkpoint = torch.load(path, map_location=self.device)
+        self.model.load_state_dict(checkpoint["model_state_dict"])
+        self.optimizer.load_state_dict(checkpoint["optimizer_state_dict"])
+
+        # automated warning messages for loading w/ schedulers at checkpoints
+        if checkpoint["scheduler_state_dict"] is not None and self.scheduler is None:
+            print(
+                "Warning: checkpoint has scheduler state but this Trainer has no scheduler — skipping."
+            )
+        elif self.scheduler is not None and checkpoint["scheduler_state_dict"] is None:
+            print(
+                "Warning: this Trainer has a scheduler but checkpoint has none — scheduler state not restored."
+            )
+        elif (
+            self.scheduler is not None
+            and checkpoint["scheduler_state_dict"] is not None
+        ):
+            self.scheduler.load_state_dict(checkpoint["scheduler_state_dict"])
+
+        self.history = checkpoint["history"]
+        return checkpoint["epoch"]
+
+    def resume(
+        self,
+        path: str,
+        num_epochs: int,
+        save_frequency: int | None = None,
+        save_path: str = "checkpoint.pth",
+    ):
+        last_epoch = self.load_checkpoint(path)
+        self.fit(
+            num_epochs=num_epochs,
+            start_epoch=last_epoch + 1,
+            save_frequency=save_frequency,
+            save_path=save_path,
+        )
+
+    def plot(self):
+        epochs = range(1, len(self.history["train_loss"]) + 1)
+        fig, axes = plt.subplots(1, 2, figsize=(12, 4))
+
+        axes[0].plot(epochs, self.history["train_loss"], label="Train loss")
+        axes[0].plot(epochs, self.history["val_loss"], label="val loss")
+        axes[0].set_xlabel("Epoch")
+        axes[0].set_ylabel("Loss")
+        axes[0].legend()
+
+        axes[1].plot(epochs, self.history["train_accuracy"], label="Train accuracy")
+        axes[1].plot(epochs, self.history["val_accuracy"], label="val accuracy")
+        axes[1].set_xlabel("Epoch")
+        axes[1].set_ylabel("Accuracy (%)")
+        axes[1].legend()
+
+        plt.tight_layout()
+        plt.show()

microflame-0.1.0/tests/test_trainer.py

@@ -0,0 +1,2 @@
+def test_import():
+    from microflame import Trainer