Metadata-Version: 2.4
Name: Stackformer
Version: 0.1.8
Summary: Modular transformer blocks built in PyTorch
Author-email: Gurumurthy <gurumurthy.00300@gmail.com>
License-Expression: MIT
Project-URL: Repository, https://github.com/Gurumurthy30/Stackformer
Project-URL: Releases, https://github.com/Gurumurthy30/Stackformer/releases
Project-URL: Issue-Tracker, https://github.com/Gurumurthy30/Stackformer/issues
Project-URL: Discussions, https://github.com/Gurumurthy30/Stackformer/discussions
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch<2.7,>=2.0
Requires-Dist: numpy<3.0,>=1.23
Requires-Dist: tqdm<5.0,>=4.5
Requires-Dist: tensorboard<3.0,>=2.14
Requires-Dist: wandb<1.0,>=0.17
Provides-Extra: test
Requires-Dist: pytest<9.0,>=8.0; extra == "test"
Requires-Dist: pytest-cov<6.0,>=5.0; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
Requires-Dist: pytest-cov<6.0,>=5.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="assets/logo.png" alt="Stackformer logo" width="560" />
</p>

# Stackformer

## Project Overview

**Stackformer** is a modular deep learning training framework built on PyTorch for transformer-based experimentation and production-style training loops. It combines reusable model building blocks with a trainer/engine stack designed for stability, extensibility, and CPU/GPU portability.

---

## Features

- Modular trainer architecture with separated state, engine, and trainer APIs.
- AMP mixed precision training support.
- Distributed training support via DDP.
- Flexible logging backends (CSV, TensorBoard, Weights & Biases).
- Metrics system for tracking and aggregation.
- Checkpointing and resume support.
- Modular model architecture (OpenAI/Meta/Google-style models + encoder-decoder transformer).
- Robust CI testing pipeline with split workflows.

---

## V3 Milestone

V3 introduces a stronger training infrastructure focused on practical deep learning workflows:

- AMP support.
- DDP support.
- Centralized metrics system.
- Modular training engine (state + step execution + high-level trainer orchestration).

---

## CI & Testing

Stackformer now uses a **multi-workflow CI pipeline**:

- `core-tests.yml` → `tests/modules`, `tests/utils`
- `model-tests.yml` → `tests/models`
- `trainer-tests.yml` → `tests/trainer`
- `integration-tests.yml` → `tests/integration`

Highlights:

- Python version matrix for 3.9, 3.10, and 3.11.
- CPU-safe training tests for portability.
- Integration coverage for model training, save/load, and checkpoint resume.

---

## Examples

Available training examples:

- `examples/simple_train.py`
- `examples/simple_trainer_v2.py`
- `examples/train_ddp.py`

---

## Installation

```bash
pip install .
```

For development:

```bash
pip install ".[dev]"
```

---

## License

MIT License. See [LICENSE](LICENSE).
