sakura-ml 0.1.4__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. sakura_ml-0.1.4/.env.template +3 -0
  2. sakura_ml-0.1.4/.github/workflows/auto-release.yml +106 -0
  3. sakura_ml-0.1.4/.github/workflows/publish.yml +33 -0
  4. sakura_ml-0.1.4/.github/workflows/test.yml +32 -0
  5. sakura_ml-0.1.4/.gitignore +23 -0
  6. sakura_ml-0.1.4/PKG-INFO +222 -0
  7. sakura_ml-0.1.4/README.md +182 -0
  8. sakura_ml-0.1.4/Taskfile.yml +44 -0
  9. sakura_ml-0.1.4/bert_demo/bench_bert.py +275 -0
  10. sakura_ml-0.1.4/bert_demo/bench_in_memory_handle.py +145 -0
  11. sakura_ml-0.1.4/bert_demo/bench_notebook.ipynb +411 -0
  12. sakura_ml-0.1.4/bert_demo/hf_async_features.ipynb +410 -0
  13. sakura_ml-0.1.4/compose.yaml +39 -0
  14. sakura_ml-0.1.4/docker/Dockerfile +71 -0
  15. sakura_ml-0.1.4/docker/static/redis/run +8 -0
  16. sakura_ml-0.1.4/docker/static/sakura/run +9 -0
  17. sakura_ml-0.1.4/main.py +146 -0
  18. sakura_ml-0.1.4/mnist_demo/__init__.py +0 -0
  19. sakura_ml-0.1.4/mnist_demo/__main__.py +38 -0
  20. sakura_ml-0.1.4/mnist_demo/lightning/__init__.py +0 -0
  21. sakura_ml-0.1.4/mnist_demo/lightning/main.py +78 -0
  22. sakura_ml-0.1.4/mnist_demo/model.py +31 -0
  23. sakura_ml-0.1.4/mnist_demo/trainer.py +104 -0
  24. sakura_ml-0.1.4/mnist_demo/utils.py +36 -0
  25. sakura_ml-0.1.4/pyproject.toml +73 -0
  26. sakura_ml-0.1.4/sakura/__init__.py +3 -0
  27. sakura_ml-0.1.4/sakura/__main__.py +22 -0
  28. sakura_ml-0.1.4/sakura/config.yaml +16 -0
  29. sakura_ml-0.1.4/sakura/ddp/__init__.py +348 -0
  30. sakura_ml-0.1.4/sakura/functional.py +9 -0
  31. sakura_ml-0.1.4/sakura/huggingface/__init__.py +447 -0
  32. sakura_ml-0.1.4/sakura/lightning/__init__.py +304 -0
  33. sakura_ml-0.1.4/sakura/ml/__init__.py +2 -0
  34. sakura_ml-0.1.4/sakura/ml/async_trainer.py +129 -0
  35. sakura_ml-0.1.4/sakura/ml/epoch/__init__.py +1 -0
  36. sakura_ml-0.1.4/sakura/ml/epoch/range.py +20 -0
  37. sakura_ml-0.1.4/sakura/ml/sakura_trainer.py +56 -0
  38. sakura_ml-0.1.4/sakura/tensorflow/__init__.py +182 -0
  39. sakura_ml-0.1.4/taskfiles/bench.yml +25 -0
  40. sakura_ml-0.1.4/taskfiles/build.yml +54 -0
  41. sakura_ml-0.1.4/taskfiles/docker.yml +39 -0
  42. sakura_ml-0.1.4/taskfiles/test.yml +20 -0
  43. sakura_ml-0.1.4/tests/__init__.py +0 -0
  44. sakura_ml-0.1.4/tests/conftest.py +29 -0
  45. sakura_ml-0.1.4/tests/test_async_trainer.py +63 -0
  46. sakura_ml-0.1.4/tests/test_ddp.py +102 -0
  47. sakura_ml-0.1.4/tests/test_epoch_range.py +39 -0
  48. sakura_ml-0.1.4/tests/test_functional.py +30 -0
  49. sakura_ml-0.1.4/tests/test_huggingface.py +67 -0
  50. sakura_ml-0.1.4/tests/test_pkg_info.py +12 -0
  51. sakura_ml-0.1.4/tests/test_sakura_trainer.py +82 -0
  52. sakura_ml-0.1.4/uv.lock +3997 -0
@@ -0,0 +1,3 @@
1
+ ORG=zakuroai
2
+ ZAKURO_LOGS=
3
+ SAKURA_HOME=
@@ -0,0 +1,106 @@
1
+ name: Auto-release
2
+
3
+ # On master push: bump patch, tag, create release, and publish the wheel
4
+ # to PyPI. Publishing is inlined (rather than a release-triggered sibling
5
+ # workflow) because releases created by GITHUB_TOKEN don't cascade into
6
+ # other workflows — so the chained approach never fires.
7
+
8
+ on:
9
+ push:
10
+ branches: [master, main]
11
+ paths-ignore:
12
+ - "**.md"
13
+ - "bert_demo/**.ipynb"
14
+ - "mnist_demo/**"
15
+ - ".github/workflows/*.yml"
16
+ workflow_dispatch:
17
+
18
+ permissions:
19
+ contents: write
20
+
21
+ concurrency:
22
+ group: auto-release
23
+ cancel-in-progress: false
24
+
25
+ jobs:
26
+ bump-and-release:
27
+ if: "!contains(github.event.head_commit.message, '[skip release]')"
28
+ runs-on: ubuntu-latest
29
+ outputs:
30
+ tag: ${{ steps.bump.outputs.tag }}
31
+ new_version: ${{ steps.bump.outputs.new_version }}
32
+ steps:
33
+ - uses: actions/checkout@v4
34
+ with:
35
+ fetch-depth: 0
36
+ token: ${{ secrets.GITHUB_TOKEN }}
37
+
38
+ - name: Configure git
39
+ run: |
40
+ git config user.name "github-actions[bot]"
41
+ git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
42
+
43
+ - name: Bump patch version
44
+ id: bump
45
+ run: |
46
+ set -euo pipefail
47
+ CURRENT=$(grep -E '^__version__ = ' sakura/__init__.py | sed -E 's/.*"([^"]+)".*/\1/')
48
+ IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT"
49
+ NEW="${MAJOR}.${MINOR}.$((PATCH + 1))"
50
+ echo " current: $CURRENT"
51
+ echo " new : $NEW"
52
+ sed -i.bak -E "s/^__version__ = \".*\"/__version__ = \"$NEW\"/" sakura/__init__.py
53
+ sed -i.bak -E "s/^version = \".*\"/version = \"$NEW\"/" pyproject.toml
54
+ rm sakura/__init__.py.bak pyproject.toml.bak
55
+ echo "new_version=$NEW" >> "$GITHUB_OUTPUT"
56
+ echo "tag=v$NEW" >> "$GITHUB_OUTPUT"
57
+
58
+ - name: Commit + tag
59
+ run: |
60
+ set -euo pipefail
61
+ git add sakura/__init__.py pyproject.toml
62
+ git commit -m "chore(release): v${{ steps.bump.outputs.new_version }} [skip release]"
63
+ git tag "${{ steps.bump.outputs.tag }}"
64
+ git push origin HEAD:${{ github.ref_name }}
65
+ git push origin "${{ steps.bump.outputs.tag }}"
66
+
67
+ - name: Create GitHub release
68
+ env:
69
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
70
+ run: |
71
+ gh release create "${{ steps.bump.outputs.tag }}" \
72
+ --title "${{ steps.bump.outputs.tag }}" \
73
+ --generate-notes
74
+
75
+ publish-pypi:
76
+ needs: bump-and-release
77
+ runs-on: ubuntu-latest
78
+ environment: release
79
+ steps:
80
+ - uses: actions/checkout@v4
81
+ with:
82
+ ref: ${{ needs.bump-and-release.outputs.tag }}
83
+
84
+ - uses: actions/setup-python@v5
85
+ with:
86
+ python-version: "3.12"
87
+
88
+ - uses: astral-sh/setup-uv@v4
89
+
90
+ - name: Build wheel + sdist
91
+ run: |
92
+ uv venv .venv
93
+ uv pip install --python .venv/bin/python hatchling build twine
94
+ .venv/bin/python -m build --outdir dist
95
+
96
+ - name: Publish to PyPI (API token)
97
+ env:
98
+ TWINE_USERNAME: __token__
99
+ TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
100
+ run: |
101
+ set -euo pipefail
102
+ if [ -z "${TWINE_PASSWORD:-}" ]; then
103
+ echo "::error::PYPI_API_TOKEN secret is not set on the 'release' environment."
104
+ exit 1
105
+ fi
106
+ .venv/bin/python -m twine upload dist/* --non-interactive
@@ -0,0 +1,33 @@
1
+ name: Publish
2
+
3
+ on:
4
+ release:
5
+ types: [published]
6
+
7
+ jobs:
8
+ publish-pypi:
9
+ runs-on: ubuntu-latest
10
+ environment: release
11
+ permissions:
12
+ id-token: write
13
+ steps:
14
+ - uses: actions/checkout@v4
15
+
16
+ - name: Set up Python
17
+ uses: actions/setup-python@v5
18
+ with:
19
+ python-version: "3.12"
20
+
21
+ - name: Install uv
22
+ uses: astral-sh/setup-uv@v4
23
+
24
+ - name: Build wheel
25
+ run: |
26
+ uv venv .venv
27
+ uv pip install --python .venv/bin/python hatchling build
28
+ .venv/bin/python -m build --wheel --outdir dist
29
+
30
+ - name: Publish to PyPI (trusted publishing)
31
+ uses: pypa/gh-action-pypi-publish@release/v1
32
+ with:
33
+ packages-dir: dist/
@@ -0,0 +1,32 @@
1
+ name: Test
2
+
3
+ on:
4
+ push:
5
+ branches: [master, main]
6
+ pull_request:
7
+ branches: [master, main]
8
+
9
+ jobs:
10
+ pytest:
11
+ runs-on: ubuntu-latest
12
+ strategy:
13
+ matrix:
14
+ python-version: ["3.10", "3.11", "3.12"]
15
+ steps:
16
+ - uses: actions/checkout@v4
17
+
18
+ - name: Set up Python ${{ matrix.python-version }}
19
+ uses: actions/setup-python@v5
20
+ with:
21
+ python-version: ${{ matrix.python-version }}
22
+
23
+ - name: Install uv
24
+ uses: astral-sh/setup-uv@v4
25
+
26
+ - name: Install package + test deps
27
+ run: |
28
+ uv venv .venv
29
+ uv pip install --python .venv/bin/python -e '.[huggingface]' pytest
30
+
31
+ - name: Run tests
32
+ run: .venv/bin/pytest tests/ -v
@@ -0,0 +1,23 @@
1
+ etc
2
+ dist/legacy
3
+ asr
4
+ pth
5
+ build
6
+ *.egg-info
7
+ data/*
8
+ *.pt
9
+ .idea
10
+ __pycache__
11
+ .vscode
12
+ data
13
+ tmp
14
+ etc/
15
+ MNIST
16
+ lightning_logs/
17
+
18
+ dump.rdb
19
+
20
+ *.rdb
21
+ .env
22
+ models/
23
+ .coverage
@@ -0,0 +1,222 @@
1
+ Metadata-Version: 2.4
2
+ Name: sakura-ml
3
+ Version: 0.1.4
4
+ Summary: Sakura provides asynchronous training for DNN.
5
+ Author-email: ZakuroAI <git@zakuro.ai>
6
+ License-Expression: BSD-3-Clause
7
+ Classifier: Intended Audience :: Developers
8
+ Classifier: Intended Audience :: Education
9
+ Classifier: Intended Audience :: Science/Research
10
+ Classifier: License :: OSI Approved :: BSD License
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Topic :: Scientific/Engineering
13
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
14
+ Classifier: Topic :: Scientific/Engineering :: Mathematics
15
+ Classifier: Topic :: Software Development
16
+ Classifier: Topic :: Software Development :: Libraries
17
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
18
+ Requires-Python: >=3.10
19
+ Requires-Dist: chardet
20
+ Requires-Dist: charset-normalizer==3.1.0
21
+ Requires-Dist: gnutools-python
22
+ Requires-Dist: ipython
23
+ Requires-Dist: lightning
24
+ Requires-Dist: numpy
25
+ Requires-Dist: six
26
+ Requires-Dist: torch
27
+ Requires-Dist: torchvision
28
+ Requires-Dist: tqdm>=4.64.0
29
+ Requires-Dist: zakuro-ai>=0.2.3
30
+ Provides-Extra: bench
31
+ Requires-Dist: accelerate>=0.25.0; extra == 'bench'
32
+ Requires-Dist: datasets>=2.14.0; extra == 'bench'
33
+ Requires-Dist: transformers>=4.40.0; extra == 'bench'
34
+ Provides-Extra: huggingface
35
+ Requires-Dist: datasets>=2.14.0; extra == 'huggingface'
36
+ Requires-Dist: transformers>=4.40.0; extra == 'huggingface'
37
+ Provides-Extra: tensorflow
38
+ Requires-Dist: tensorflow>=2.15.0; extra == 'tensorflow'
39
+ Description-Content-Type: text/markdown
40
+
41
+ <h1 align="center">Sakura</h1>
42
+
43
+ <p align="center">
44
+ ML-framework integrations for <a href="https://github.com/zakuro-ai/zakuro">Zakuro</a> —
45
+ hide evaluation, logging, and checkpointing behind training so the main loop never waits.
46
+ </p>
47
+
48
+ <p align="center">
49
+ <a href="#quick-start">Quick Start</a> •
50
+ <a href="#installation">Installation</a> •
51
+ <a href="#pytorch-lightning">Lightning</a> •
52
+ <a href="#huggingface-trainer">HuggingFace</a> •
53
+ <a href="#tensorflow--keras">TensorFlow</a> •
54
+ <a href="#benchmarks--notebooks">Benchmarks</a>
55
+ </p>
56
+
57
+ --------------------------------------------------------------------------------
58
+
59
+ ## What is Sakura?
60
+
61
+ Sakura wraps the framework you're already using (PyTorch Lightning, HuggingFace `Trainer`, TensorFlow `Model.fit`) with a callback that **dispatches evaluation to a [Zakuro](https://github.com/zakuro-ai/zakuro) worker** instead of running it inline. Training keeps stepping while eval runs on a side pool; metrics come back through a non-blocking queue.
62
+
63
+ The old Sakura used MPI + Redis for this plumbing. The current Sakura uses Zakuro — one `@zk.fn` dispatch per epoch, shared connection, context-aware allocation across a pool of workers. No MPI, no Redis, no `SAKURA_ROLE` fork.
64
+
65
+ ## Quick start
66
+
67
+ ### Laptop-only (no worker setup)
68
+
69
+ ```python
70
+ import lightning as L
71
+ from sakura.lightning import SakuraTrainer
72
+
73
+ trainer = SakuraTrainer(
74
+ max_epochs=10,
75
+ accelerator="auto",
76
+ model_factory=MyLightningModule, # rebuilds on the eval worker
77
+ val_loader_factory=lambda: val_loader,
78
+ )
79
+ trainer.run(model, train_loader) # val_compute=None → Zakuro standalone fallback
80
+ ```
81
+
82
+ No `zakuro-worker` needed — the eval runs in-process via Zakuro's standalone fallback, but the async dispatch pattern still works.
83
+
84
+ ### HuggingFace `Trainer` with a real worker
85
+
86
+ ```python
87
+ from transformers import Trainer, TrainingArguments
88
+ from sakura.huggingface import SakuraHFCallback
89
+ import zakuro as zk
90
+
91
+ trainer = Trainer(
92
+ model=model,
93
+ args=TrainingArguments(..., eval_strategy="no"), # we handle eval
94
+ train_dataset=train_ds,
95
+ callbacks=[
96
+ SakuraHFCallback(
97
+ model_factory=lambda: AutoModelForSequenceClassification.from_config(config),
98
+ eval_fn=my_eval_fn,
99
+ eval_payload=(val_inputs, 32),
100
+ val_compute=zk.Compute(uri="quic://worker:4433"),
101
+ fp16_state_dict=True,
102
+ on_backpressure="skip",
103
+ )
104
+ ],
105
+ )
106
+ trainer.train()
107
+ ```
108
+
109
+ `on_backpressure="skip"` makes the callback consult `AdaptiveCompute.is_backpressured()` before every dispatch — if the allocator reports saturation (the slow eval worker can't keep up), that epoch's eval is dropped rather than blocking training.
110
+
111
+ ## Installation
112
+
113
+ ```bash
114
+ # Core + HuggingFace integration
115
+ pip install 'sakura-ml[huggingface]'
116
+
117
+ # Everything
118
+ pip install 'sakura-ml[huggingface,tensorflow,bench]'
119
+
120
+ # From source
121
+ git clone https://github.com/zakuro-ai/sakura && cd sakura
122
+ uv pip install -e '.[huggingface]'
123
+ ```
124
+
125
+ Zakuro is pulled transitively. For a worker (HTTP or QUIC) install the `[worker]` extra on the zakuro package.
126
+
127
+ ## PyTorch Lightning
128
+
129
+ `sakura.lightning.SakuraTrainer` — a drop-in replacement for the async-eval case:
130
+
131
+ ```python
132
+ from sakura.lightning import SakuraTrainer
133
+
134
+ trainer = SakuraTrainer(
135
+ max_epochs=10,
136
+ accelerator="auto",
137
+ # how the eval worker rebuilds the model:
138
+ model_factory=lambda: MyLightningModule(),
139
+ # how the eval worker rebuilds the dataloader:
140
+ val_loader_factory=lambda: DataLoader(val_ds, batch_size=256),
141
+ # optional: where to run eval
142
+ val_compute=zk.Compute(uri="quic://eval-worker:4433"),
143
+ # optional: where to save the best-loss checkpoint
144
+ model_path="checkpoints/best.pth",
145
+ )
146
+ trainer.run(model, train_loader)
147
+
148
+ print(trainer.history) # [{epoch, val_loss, worker_name, elapsed_secs}, ...]
149
+ print(trainer.best_val_loss)
150
+ ```
151
+
152
+ ## HuggingFace Trainer
153
+
154
+ `sakura.huggingface.SakuraHFCallback` is a `transformers.TrainerCallback` that cloudpickles `state_dict` on `on_epoch_end`, dispatches a remote eval, and lazily reaps futures as they finish. Knobs:
155
+
156
+ | parameter | what it does |
157
+ |---|---|
158
+ | `model_factory` | how the eval worker rebuilds the architecture (weights stream in from the callback) |
159
+ | `eval_fn(model, payload)` | the eval routine itself — runs on the worker, returns a `dict` of metrics |
160
+ | `eval_payload` | anything cloudpickle can serialise — dataset, tokenizer, batch size |
161
+ | `val_compute` | `zk.Compute` or `zk.AdaptiveCompute`; `None` → standalone |
162
+ | `drain="lazy"` *(default)* / `"strict"` | whether `on_epoch_end` blocks to reap the previous future |
163
+ | `cache_key=...` | keep the validator model architecture warm on the worker |
164
+ | `fp16_state_dict=True` | halve the wire bytes |
165
+ | `async_copy=True` *(default, CUDA-only)* | GPU→CPU snapshot on a dedicated stream, ~170 → 75 ms per epoch on x399 4090 |
166
+ | `on_backpressure={"skip","queue","block"}` | policy when `AdaptiveCompute` reports saturation |
167
+ | `max_pending` | cap on in-flight evaluations |
168
+
169
+ In-memory fast path is **automatic**: when `val_compute` resolves to standalone, `torch.save`/`torch.load` are skipped entirely — measured +23.6 % wall on a 3-epoch distilbert fine-tune vs forced serialisation.
170
+
171
+ ## TensorFlow / Keras
172
+
173
+ `sakura.tensorflow.SakuraKerasCallback` — a `tf.keras.callbacks.Callback` with the same pattern:
174
+
175
+ ```python
176
+ from sakura.tensorflow import SakuraKerasCallback
177
+
178
+ model.fit(
179
+ x_train, y_train,
180
+ epochs=10,
181
+ callbacks=[SakuraKerasCallback(
182
+ model_factory=lambda: tf.keras.Sequential([...]),
183
+ val_fn=lambda m, p: m.evaluate(*p, verbose=0, return_dict=True),
184
+ val_payload=(x_val, y_val),
185
+ val_compute=zk.Compute(uri="quic://eval-worker:4433"),
186
+ )],
187
+ )
188
+ ```
189
+
190
+ Weights are transferred as numpy arrays via `get_weights()` / `set_weights()` — clean cloudpickle, no TF graph-state serialisation.
191
+
192
+ ## Generic async trainer (framework-agnostic)
193
+
194
+ `sakura.ml.async_trainer.AsyncTrainer` — for training loops that aren't Lightning / HF / Keras. Takes any object implementing `train(loader)`, `serialized_state_dict()`, `_epochs`, `_metrics`, plus a `model_factory` and `test_fn(model) -> dict`. Same dispatch mechanics.
195
+
196
+ ## Benchmarks & notebooks
197
+
198
+ - **[`bert_demo/hf_async_features.ipynb`](bert_demo/hf_async_features.ipynb)** — every `SakuraHFCallback` knob exercised on distilbert / SST-2. Runs in ~1 min on a laptop. Verified via `jupyter nbconvert --execute`.
199
+ - **[`bert_demo/bench_bert.py`](bert_demo/bench_bert.py)** — serial `Trainer` vs Sakura async, configurable.
200
+ - **[`bert_demo/bench_in_memory_handle.py`](bert_demo/bench_in_memory_handle.py)** — A/B the in-memory-handle fast path against `torch.save`. +23.6 % end-to-end measured.
201
+
202
+ ## Measured performance wins (distilbert-base-uncased, 268 MB state_dict)
203
+
204
+ | slice | before | after | measured on |
205
+ |---|---|---|---|
206
+ | blocking `.cpu()` → async CUDA-stream copy | 176 ms / epoch main-thread | **75 ms** / epoch | x399 4090 |
207
+ | cloudpickle → `torch.save` for state_dict | 482 ms / epoch pool | **282 ms** / epoch | x399 CPU |
208
+ | in-memory handle for standalone | 9.12 s wall (3 epochs) | **7.59 s** | Mac MPS |
209
+
210
+ See [`zakuro/PLAN.md`](https://github.com/zakuro-ai/zakuro/blob/master/PLAN.md#measured-results-so-far) for the consolidated numbers across both repos.
211
+
212
+ ## Development
213
+
214
+ ```bash
215
+ git clone https://github.com/zakuro-ai/sakura && cd sakura
216
+ uv pip install -e '.[bench]'
217
+ uv run pytest tests/
218
+ ```
219
+
220
+ ## License
221
+
222
+ BSD-3-Clause.
@@ -0,0 +1,182 @@
1
+ <h1 align="center">Sakura</h1>
2
+
3
+ <p align="center">
4
+ ML-framework integrations for <a href="https://github.com/zakuro-ai/zakuro">Zakuro</a> —
5
+ hide evaluation, logging, and checkpointing behind training so the main loop never waits.
6
+ </p>
7
+
8
+ <p align="center">
9
+ <a href="#quick-start">Quick Start</a> •
10
+ <a href="#installation">Installation</a> •
11
+ <a href="#pytorch-lightning">Lightning</a> •
12
+ <a href="#huggingface-trainer">HuggingFace</a> •
13
+ <a href="#tensorflow--keras">TensorFlow</a> •
14
+ <a href="#benchmarks--notebooks">Benchmarks</a>
15
+ </p>
16
+
17
+ --------------------------------------------------------------------------------
18
+
19
+ ## What is Sakura?
20
+
21
+ Sakura wraps the framework you're already using (PyTorch Lightning, HuggingFace `Trainer`, TensorFlow `Model.fit`) with a callback that **dispatches evaluation to a [Zakuro](https://github.com/zakuro-ai/zakuro) worker** instead of running it inline. Training keeps stepping while eval runs on a side pool; metrics come back through a non-blocking queue.
22
+
23
+ The old Sakura used MPI + Redis for this plumbing. The current Sakura uses Zakuro — one `@zk.fn` dispatch per epoch, shared connection, context-aware allocation across a pool of workers. No MPI, no Redis, no `SAKURA_ROLE` fork.
24
+
25
+ ## Quick start
26
+
27
+ ### Laptop-only (no worker setup)
28
+
29
+ ```python
30
+ import lightning as L
31
+ from sakura.lightning import SakuraTrainer
32
+
33
+ trainer = SakuraTrainer(
34
+ max_epochs=10,
35
+ accelerator="auto",
36
+ model_factory=MyLightningModule, # rebuilds on the eval worker
37
+ val_loader_factory=lambda: val_loader,
38
+ )
39
+ trainer.run(model, train_loader) # val_compute=None → Zakuro standalone fallback
40
+ ```
41
+
42
+ No `zakuro-worker` needed — the eval runs in-process via Zakuro's standalone fallback, but the async dispatch pattern still works.
43
+
44
+ ### HuggingFace `Trainer` with a real worker
45
+
46
+ ```python
47
+ from transformers import Trainer, TrainingArguments
48
+ from sakura.huggingface import SakuraHFCallback
49
+ import zakuro as zk
50
+
51
+ trainer = Trainer(
52
+ model=model,
53
+ args=TrainingArguments(..., eval_strategy="no"), # we handle eval
54
+ train_dataset=train_ds,
55
+ callbacks=[
56
+ SakuraHFCallback(
57
+ model_factory=lambda: AutoModelForSequenceClassification.from_config(config),
58
+ eval_fn=my_eval_fn,
59
+ eval_payload=(val_inputs, 32),
60
+ val_compute=zk.Compute(uri="quic://worker:4433"),
61
+ fp16_state_dict=True,
62
+ on_backpressure="skip",
63
+ )
64
+ ],
65
+ )
66
+ trainer.train()
67
+ ```
68
+
69
+ `on_backpressure="skip"` makes the callback consult `AdaptiveCompute.is_backpressured()` before every dispatch — if the allocator reports saturation (the slow eval worker can't keep up), that epoch's eval is dropped rather than blocking training.
70
+
71
+ ## Installation
72
+
73
+ ```bash
74
+ # Core + HuggingFace integration
75
+ pip install 'sakura-ml[huggingface]'
76
+
77
+ # Everything
78
+ pip install 'sakura-ml[huggingface,tensorflow,bench]'
79
+
80
+ # From source
81
+ git clone https://github.com/zakuro-ai/sakura && cd sakura
82
+ uv pip install -e '.[huggingface]'
83
+ ```
84
+
85
+ Zakuro is pulled transitively. For a worker (HTTP or QUIC) install the `[worker]` extra on the zakuro package.
86
+
87
+ ## PyTorch Lightning
88
+
89
+ `sakura.lightning.SakuraTrainer` — a drop-in replacement for the async-eval case:
90
+
91
+ ```python
92
+ from sakura.lightning import SakuraTrainer
93
+
94
+ trainer = SakuraTrainer(
95
+ max_epochs=10,
96
+ accelerator="auto",
97
+ # how the eval worker rebuilds the model:
98
+ model_factory=lambda: MyLightningModule(),
99
+ # how the eval worker rebuilds the dataloader:
100
+ val_loader_factory=lambda: DataLoader(val_ds, batch_size=256),
101
+ # optional: where to run eval
102
+ val_compute=zk.Compute(uri="quic://eval-worker:4433"),
103
+ # optional: where to save the best-loss checkpoint
104
+ model_path="checkpoints/best.pth",
105
+ )
106
+ trainer.run(model, train_loader)
107
+
108
+ print(trainer.history) # [{epoch, val_loss, worker_name, elapsed_secs}, ...]
109
+ print(trainer.best_val_loss)
110
+ ```
111
+
112
+ ## HuggingFace Trainer
113
+
114
+ `sakura.huggingface.SakuraHFCallback` is a `transformers.TrainerCallback` that cloudpickles `state_dict` on `on_epoch_end`, dispatches a remote eval, and lazily reaps futures as they finish. Knobs:
115
+
116
+ | parameter | what it does |
117
+ |---|---|
118
+ | `model_factory` | how the eval worker rebuilds the architecture (weights stream in from the callback) |
119
+ | `eval_fn(model, payload)` | the eval routine itself — runs on the worker, returns a `dict` of metrics |
120
+ | `eval_payload` | anything cloudpickle can serialise — dataset, tokenizer, batch size |
121
+ | `val_compute` | `zk.Compute` or `zk.AdaptiveCompute`; `None` → standalone |
122
+ | `drain="lazy"` *(default)* / `"strict"` | whether `on_epoch_end` blocks to reap the previous future |
123
+ | `cache_key=...` | keep the validator model architecture warm on the worker |
124
+ | `fp16_state_dict=True` | halve the wire bytes |
125
+ | `async_copy=True` *(default, CUDA-only)* | GPU→CPU snapshot on a dedicated stream, ~170 → 75 ms per epoch on x399 4090 |
126
+ | `on_backpressure={"skip","queue","block"}` | policy when `AdaptiveCompute` reports saturation |
127
+ | `max_pending` | cap on in-flight evaluations |
128
+
129
+ In-memory fast path is **automatic**: when `val_compute` resolves to standalone, `torch.save`/`torch.load` are skipped entirely — measured +23.6 % wall on a 3-epoch distilbert fine-tune vs forced serialisation.
130
+
131
+ ## TensorFlow / Keras
132
+
133
+ `sakura.tensorflow.SakuraKerasCallback` — a `tf.keras.callbacks.Callback` with the same pattern:
134
+
135
+ ```python
136
+ from sakura.tensorflow import SakuraKerasCallback
137
+
138
+ model.fit(
139
+ x_train, y_train,
140
+ epochs=10,
141
+ callbacks=[SakuraKerasCallback(
142
+ model_factory=lambda: tf.keras.Sequential([...]),
143
+ val_fn=lambda m, p: m.evaluate(*p, verbose=0, return_dict=True),
144
+ val_payload=(x_val, y_val),
145
+ val_compute=zk.Compute(uri="quic://eval-worker:4433"),
146
+ )],
147
+ )
148
+ ```
149
+
150
+ Weights are transferred as numpy arrays via `get_weights()` / `set_weights()` — clean cloudpickle, no TF graph-state serialisation.
151
+
152
+ ## Generic async trainer (framework-agnostic)
153
+
154
+ `sakura.ml.async_trainer.AsyncTrainer` — for training loops that aren't Lightning / HF / Keras. Takes any object implementing `train(loader)`, `serialized_state_dict()`, `_epochs`, `_metrics`, plus a `model_factory` and `test_fn(model) -> dict`. Same dispatch mechanics.
155
+
156
+ ## Benchmarks & notebooks
157
+
158
+ - **[`bert_demo/hf_async_features.ipynb`](bert_demo/hf_async_features.ipynb)** — every `SakuraHFCallback` knob exercised on distilbert / SST-2. Runs in ~1 min on a laptop. Verified via `jupyter nbconvert --execute`.
159
+ - **[`bert_demo/bench_bert.py`](bert_demo/bench_bert.py)** — serial `Trainer` vs Sakura async, configurable.
160
+ - **[`bert_demo/bench_in_memory_handle.py`](bert_demo/bench_in_memory_handle.py)** — A/B the in-memory-handle fast path against `torch.save`. +23.6 % end-to-end measured.
161
+
162
+ ## Measured performance wins (distilbert-base-uncased, 268 MB state_dict)
163
+
164
+ | slice | before | after | measured on |
165
+ |---|---|---|---|
166
+ | blocking `.cpu()` → async CUDA-stream copy | 176 ms / epoch main-thread | **75 ms** / epoch | x399 4090 |
167
+ | cloudpickle → `torch.save` for state_dict | 482 ms / epoch pool | **282 ms** / epoch | x399 CPU |
168
+ | in-memory handle for standalone | 9.12 s wall (3 epochs) | **7.59 s** | Mac MPS |
169
+
170
+ See [`zakuro/PLAN.md`](https://github.com/zakuro-ai/zakuro/blob/master/PLAN.md#measured-results-so-far) for the consolidated numbers across both repos.
171
+
172
+ ## Development
173
+
174
+ ```bash
175
+ git clone https://github.com/zakuro-ai/sakura && cd sakura
176
+ uv pip install -e '.[bench]'
177
+ uv run pytest tests/
178
+ ```
179
+
180
+ ## License
181
+
182
+ BSD-3-Clause.
@@ -0,0 +1,44 @@
1
+ version: '3'
2
+
3
+ dotenv:
4
+ - .env
5
+
6
+ vars:
7
+ PKG_NAME: sakura
8
+ VERSION:
9
+ sh: python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])"
10
+
11
+ includes:
12
+ build:
13
+ taskfile: taskfiles/build.yml
14
+ optional: true
15
+ docker:
16
+ taskfile: taskfiles/docker.yml
17
+ optional: true
18
+ test:
19
+ taskfile: taskfiles/test.yml
20
+ optional: true
21
+ bench:
22
+ taskfile: taskfiles/bench.yml
23
+ optional: true
24
+
25
+ tasks:
26
+ default:
27
+ desc: Show available tasks
28
+ cmds:
29
+ - task --list
30
+
31
+ help:
32
+ desc: Display project version and usage info
33
+ cmds:
34
+ - echo "{{.PKG_NAME}} v{{.VERSION}}"
35
+ - echo "Usage{{":"}} task {build:wheel, docker:run, ...}"
36
+ - echo "Please check README.md for instructions"
37
+
38
+ setup:
39
+ desc: Install prerequisites and verify environment
40
+ cmds:
41
+ - echo "Checking prerequisites..."
42
+ - cmd: command -v docker >/dev/null && echo "docker OK" || echo "docker NOT FOUND"
43
+ - cmd: command -v uv >/dev/null && echo "uv OK" || echo "uv NOT FOUND"
44
+ - cmd: command -v task >/dev/null && echo "task OK" || echo "task NOT FOUND"