Metadata-Version: 2.4
Name: sakura-ml
Version: 0.1.8
Summary: Sakura provides asynchronous training for DNN.
Author-email: ZakuroAI <git@zakuro.ai>
License-Expression: BSD-3-Clause
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: chardet
Requires-Dist: charset-normalizer>=3.1.0
Requires-Dist: gnutools-python
Requires-Dist: ipython
Requires-Dist: lightning
Requires-Dist: numpy
Requires-Dist: six
Requires-Dist: torch
Requires-Dist: torchvision
Requires-Dist: tqdm>=4.64.0
Requires-Dist: zakuro-ai>=0.2.3
Provides-Extra: bench
Requires-Dist: accelerate>=1.1.0; extra == 'bench'
Requires-Dist: datasets>=2.14.0; extra == 'bench'
Requires-Dist: transformers>=4.40.0; extra == 'bench'
Provides-Extra: huggingface
Requires-Dist: accelerate>=1.1.0; extra == 'huggingface'
Requires-Dist: datasets>=2.14.0; extra == 'huggingface'
Requires-Dist: transformers>=4.40.0; extra == 'huggingface'
Provides-Extra: tensorflow
Requires-Dist: tensorflow>=2.15.0; extra == 'tensorflow'
Description-Content-Type: text/markdown

<h1 align="center">
  <br>
  <img src="https://drive.google.com/uc?id=1Mz2WqXHrwEOjwtWfJVHV7NiRwC_64Shh">
</h1>
<p align="center">
  <a href="#modules">Modules</a> •
  <a href="#code-structure">Code structure</a> •
  <a href="#code-design">Code design</a> •
  <a href="#installing-the-application">Installing the application</a> •
  <a href="#taskfile-commands">Taskfile commands</a> •
  <a href="#environments">Environments</a> •
  <a href="#running-the-application">Running the application</a> •
  <a href="#changelog">Changelog</a>
</p>


--------------------------------------------------------------------------------

Sakura is a simple but powerful tool to reduce training time by running the train/test asynchronously. It provides two features:
- A simple ML framework for asynchronous training.
- An integration with PyTorch Lightning.

You can reuse your favorite Python framework such as PyTorch, TensorFlow or PaddlePaddle.


# Modules

At a granular level, Sakura is a library that consists of the following components:

| Component | Description |
| ---- | --- |
| **sakura/** | Core package — version metadata, config, and functional utilities |
| **sakura/ml/** | Machine-learning primitives: async trainer, Sakura trainer, epoch range |
| **sakura/lightning/** | PyTorch Lightning integration (`SakuraTrainer`) |
| **docker/** | Multi-stage Dockerfile and s6-overlay service scripts |
| **taskfiles/** | Modular Taskfile includes for build, test, bench, and docker workflows |
| **tests/** | Pytest test suite for trainers, epoch range, functional utils, and packaging |
| **mnist_demo/** | Standalone MNIST demo with Lightning trainer |


# Code structure

```
.
├── main.py                          # Benchmark CLI: baseline vs Sakura trainer
├── pyproject.toml                   # PEP 621 project metadata (hatchling)
├── Taskfile.yml                     # Task runner entry point
├── compose.yaml                     # Docker Compose (production + dev services)
├── .env.template                    # Environment variable template
├── docker/
│   ├── Dockerfile                   # Multi-stage: base → test → production
│   └── static/
│       ├── redis/run                # s6 service script for Redis
│       └── sakura/run               # s6 service script for Sakura
├── sakura/
│   ├── __init__.py                  # Package version and build metadata
│   ├── __main__.py                  # CLI entry point (python -m sakura)
│   ├── config.yaml                  # Default configuration
│   ├── functional.py                # Metric namespaces and defaults
│   ├── ml/
│   │   ├── async_trainer.py         # Asynchronous training loop
│   │   ├── sakura_trainer.py        # Core Sakura trainer
│   │   └── epoch/
│   │       └── range.py             # Epoch range utilities
│   └── lightning/
│       └── __init__.py              # SakuraTrainer (Lightning integration)
├── taskfiles/
│   ├── bench.yml                    # Benchmark tasks
│   ├── build.yml                    # Wheel/sdist build tasks
│   ├── docker.yml                   # Docker build/run/shell tasks
│   └── test.yml                     # Pytest tasks (local + Docker)
├── tests/
│   ├── conftest.py                  # Shared pytest fixtures
│   ├── test_async_trainer.py
│   ├── test_epoch_range.py
│   ├── test_functional.py
│   ├── test_pkg_info.py
│   └── test_sakura_trainer.py
└── mnist_demo/
    └── lightning/
        └── main.py                  # Standalone MNIST Lightning example
```

# Code design

Sakura wraps your existing PyTorch Lightning workflow. Simply swap `L.Trainer` for `SakuraTrainer` and call `trainer.run(...)` instead of `trainer.fit(...)`. The framework handles asynchronous test evaluation behind the scenes via Redis so that validation does not block training.

```python
from sakura.lightning import SakuraTrainer

model = MNISTModel()
trainer = SakuraTrainer(accelerator="auto", max_epochs=10)
trainer.run(model, train_loader, val_loader, model_path="models/best_model.pth")
```

# Installing the application

To clone and run this application, you'll need the following installed on your computer:
- [Git](https://git-scm.com)
- [Python >= 3.10](https://www.python.org/downloads/)
- [uv](https://docs.astral.sh/uv/) (recommended package manager)
- [Task](https://taskfile.dev/) (optional, for task runner commands)
- Docker Desktop (optional, for containerised builds)
   - [Install Docker Desktop on Mac](https://docs.docker.com/docker-for-mac/install/)
   - [Install Docker Desktop on Windows](https://docs.docker.com/desktop/install/windows-install/)
   - [Install Docker Desktop on Linux](https://docs.docker.com/desktop/install/linux-install/)

### Clone and install

```bash
# Clone this repository
git clone https://github.com/zakuro-ai/sakura
cd sakura

# Copy environment template
cp .env.template .env

# Create a virtual environment with a supported Python version.
# PyTorch wheels are not yet published for Python 3.13+, so pin to 3.12.
uv venv --python 3.12
source .venv/bin/activate

# Install in editable mode
uv pip install -e .
```

### Verify installation

```bash
python3 -c "import sakura; print(sakura.__version__)"
```

# Taskfile commands

This project uses [Task](https://taskfile.dev/) as its task runner. Available commands:

| Command | Description |
| --- | --- |
| `task` | Show available tasks |
| `task help` | Display project version and usage info |
| `task setup` | Install prerequisites and verify environment |
| `task build:wheel` | Build wheel distribution with uv |
| `task build:sdist` | Build source distribution with uv |
| `task build:all` | Build wheel and source distribution |
| `task build:clean` | Remove dist directory |
| `task test:run` | Run pytest test suite |
| `task test:docker` | Run pytest test suite inside a Docker container |
| `task docker:build-image` | Build the Docker image via docker compose |
| `task docker:build` | Full build (wheel + Docker image) |
| `task docker:run` | Run services via docker compose |
| `task docker:shell` | Launch docker compose and open a bash shell |
| `task bench:baseline` | Benchmark baseline Lightning trainer |
| `task bench:sakura` | Benchmark Sakura trainer |
| `task bench:both` | Benchmark both trainers and compare |
| `task bench:docker` | Run benchmark inside the sakura-dev container |

# Environments

Environment variables are defined in `.env` (copied from `.env.template`):

| Variable | Description |
| --- | --- |
| `ORG` | Organisation name (default: `zakuroai`) |
| `ZAKURO_LOGS` | Path to log directory |
| `SAKURA_HOME` | Project root directory |

Additional variables used at runtime:

| Variable | Description |
| --- | --- |
| `PATH_DATASETS` | Dataset download directory (default: `/tmp/datasets`) |
| `PYTHONPATH` | Python module search path (set in `compose.yaml`) |
| `MASTER_HOST` | Master node address for distributed training (default: `127.0.0.1`) |

# Running the application

### Benchmark CLI

```bash
# Run both baseline and Sakura trainers (default)
python3 main.py --mode both --epochs 10

# Run only the Sakura trainer
python3 main.py --mode sakura --epochs 5

# Run only the baseline Lightning trainer
python3 main.py --mode baseline
```

### Using the Sakura CLI

The `sakura` command is an informational entry point — it prints help and exits.
To run the bundled benchmark from the CLI, use `sakura-benchmark`:

```bash
# Run the benchmark via the bundled entry point (equivalent to `python3 main.py`)
sakura-benchmark --mode sakura --epochs 10
```

You should be able to see this output with no delay between epochs (asynchronous testing).
```
   _____           _                               __  __   _
  / ____|         | |                             |  \/  | | |
 | (___     __ _  | | __  _   _   _ __    __ _    | \  / | | |
  \___ \   / _` | | |/ / | | | | | '__|  / _` |   | |\/| | | |
  ____) | | (_| | |   <  | |_| | | |    | (_| |   | |  | | | |____
 |_____/   \__,_| |_|\_\  \__,_| |_|     \__,_|   |_|  |_| |______|

(0) MNIST | Epoch: 1/10 | Acc: 0.0000 / (0.0000) | Loss:0.0000 / (0.0000): 100%|██████████| 18/18 [00:06<00:00,  2.69it/s]
(1) MNIST | Epoch: 2/10 | Acc: 0.0000 / (0.0000) | Loss:0.0000 / (0.0000): 100%|██████████| 18/18 [00:05<00:00,  3.36it/s]
...
(8) MNIST | Epoch: 9/10 | Acc: 98.2402 / (98.2402) | Loss:0.0886 / (0.0886): 100%|██████████| 18/18 [00:05<00:00,  3.41it/s]
```

FYI the meaning of the above notation is:
```
([best_epoch]) [name_exp] | Epoch: [current]/[total] | Acc: [current_test_acc] / ([best_test_acc]) | Loss:[current_test_loss] / ([best_test_loss]): 100%|███| [batch_k]/[batch_n] [[time_train]<[time_left], [it/s]]
```

### Using Docker

```bash
# Build and run via Task
task docker:build
task docker:run

# Or directly with docker compose
docker compose up sakura -d
docker exec -it sakura bash
```

# Changelog

See the [GitHub releases page](https://github.com/zakuro-ai/sakura/releases) for a detailed list of changes.
