useml 0.0.2__tar.gz → 0.2.0__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.
- useml-0.2.0/PKG-INFO +317 -0
- useml-0.2.0/README.md +300 -0
- {useml-0.0.2 → useml-0.2.0}/pyproject.toml +6 -4
- useml-0.2.0/tests/test_bundle.py +360 -0
- useml-0.2.0/tests/test_session.py +211 -0
- useml-0.2.0/tests/test_train_level0.py +226 -0
- useml-0.2.0/tests/test_usecases.py +308 -0
- useml-0.2.0/tests/test_vault.py +242 -0
- useml-0.2.0/useml/__init__.py +224 -0
- useml-0.2.0/useml/dataset/__init__.py +4 -0
- useml-0.2.0/useml/dataset/bundle.py +288 -0
- useml-0.2.0/useml/dataset/loaders.py +168 -0
- useml-0.2.0/useml/errors.py +377 -0
- useml-0.2.0/useml/imports.py +215 -0
- useml-0.2.0/useml/session/__init__.py +4 -0
- useml-0.2.0/useml/session/component.py +59 -0
- useml-0.2.0/useml/session/manager.py +482 -0
- useml-0.2.0/useml/template/__init__.py +6 -0
- useml-0.2.0/useml/template/config.py +133 -0
- useml-0.2.0/useml/template/loss.py +28 -0
- useml-0.2.0/useml/template/model.py +28 -0
- useml-0.2.0/useml/template/trainer.py +296 -0
- useml-0.2.0/useml/vault/__init__.py +5 -0
- useml-0.2.0/useml/vault/code_extractor.py +258 -0
- {useml-0.0.2 → useml-0.2.0}/useml/vault/core.py +21 -11
- useml-0.2.0/useml/vault/project.py +168 -0
- useml-0.2.0/useml/vault/snapshot.py +170 -0
- useml-0.2.0/useml/workdir/__init__.py +14 -0
- useml-0.2.0/useml/workdir/_hook.py +79 -0
- useml-0.2.0/useml.egg-info/PKG-INFO +317 -0
- useml-0.2.0/useml.egg-info/SOURCES.txt +33 -0
- {useml-0.0.2 → useml-0.2.0}/useml.egg-info/requires.txt +1 -2
- useml-0.0.2/PKG-INFO +0 -99
- useml-0.0.2/README.md +0 -81
- useml-0.0.2/tests/test_vault.py +0 -135
- useml-0.0.2/useml/__init__.py +0 -6
- useml-0.0.2/useml/vault/project.py +0 -110
- useml-0.0.2/useml/vault/snapshot.py +0 -130
- useml-0.0.2/useml.egg-info/PKG-INFO +0 -99
- useml-0.0.2/useml.egg-info/SOURCES.txt +0 -12
- {useml-0.0.2 → useml-0.2.0}/setup.cfg +0 -0
- {useml-0.0.2 → useml-0.2.0}/useml.egg-info/dependency_links.txt +0 -0
- {useml-0.0.2 → useml-0.2.0}/useml.egg-info/top_level.txt +0 -0
useml-0.2.0/PKG-INFO
ADDED
|
@@ -0,0 +1,317 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: useml
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Minimalist ML experiment versioning for PyTorch — checkpointing, source archiving, and model isolation.
|
|
5
|
+
Author-email: Enzo-py <85191552+Enzo-py@users.noreply.github.com>
|
|
6
|
+
Project-URL: Homepage, https://github.com/Enzo-py/useml
|
|
7
|
+
Project-URL: Bug Tracker, https://github.com/Enzo-py/useml/issues
|
|
8
|
+
Requires-Python: >=3.8
|
|
9
|
+
Description-Content-Type: text/markdown
|
|
10
|
+
Requires-Dist: torch>=2.0.0
|
|
11
|
+
Requires-Dist: pyyaml>=6.0
|
|
12
|
+
Provides-Extra: dev
|
|
13
|
+
Requires-Dist: pytest>=7.0.0; extra == "dev"
|
|
14
|
+
Requires-Dist: build; extra == "dev"
|
|
15
|
+
Requires-Dist: twine; extra == "dev"
|
|
16
|
+
Requires-Dist: black; extra == "dev"
|
|
17
|
+
|
|
18
|
+
# useml
|
|
19
|
+
|
|
20
|
+
**Stop coding plumbing, start training models.**
|
|
21
|
+
|
|
22
|
+
`useml` is a minimalist ML experiment versioning framework for PyTorch. It handles checkpointing, source archiving, and model isolation so you can focus on the architecture.
|
|
23
|
+
|
|
24
|
+
## Installation
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
pip install useml
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Core concepts
|
|
31
|
+
|
|
32
|
+
```
|
|
33
|
+
vault/
|
|
34
|
+
└── my-experiment/ ← project
|
|
35
|
+
├── snap_20240501_.../ ← snapshot (one per commit)
|
|
36
|
+
│ ├── weights/ ← model .pth files
|
|
37
|
+
│ ├── configs/ ← per-component YAML configs
|
|
38
|
+
│ ├── source/ ← archived source code
|
|
39
|
+
│ ├── manifest.yaml ← component registry
|
|
40
|
+
│ └── metadata.yaml ← message + metrics
|
|
41
|
+
└── snap_20240502_.../
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Basic usage
|
|
45
|
+
|
|
46
|
+
### Session setup
|
|
47
|
+
|
|
48
|
+
```python
|
|
49
|
+
import useml
|
|
50
|
+
|
|
51
|
+
useml.init("vault") # connect to a vault directory
|
|
52
|
+
useml.new("my-experiment") # create and focus a project
|
|
53
|
+
# or: useml.focus("my-experiment") to resume an existing one
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### Track → Commit loop
|
|
57
|
+
|
|
58
|
+
```python
|
|
59
|
+
import torch.nn as nn
|
|
60
|
+
import useml
|
|
61
|
+
|
|
62
|
+
useml.init("vault")
|
|
63
|
+
useml.new("mnist-run", auto_focus=True)
|
|
64
|
+
|
|
65
|
+
model = nn.Linear(784, 10)
|
|
66
|
+
useml.track("classifier", model)
|
|
67
|
+
|
|
68
|
+
# ... train ...
|
|
69
|
+
|
|
70
|
+
snap = useml.commit("baseline", val_loss=0.42, accuracy=0.91)
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### Multiple models, per-model configs
|
|
74
|
+
|
|
75
|
+
```python
|
|
76
|
+
useml.track("encoder", encoder, config=encoder_config)
|
|
77
|
+
useml.track("decoder", decoder, config=decoder_config)
|
|
78
|
+
useml.commit("joint training", val_loss=0.18)
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### Config
|
|
82
|
+
|
|
83
|
+
```python
|
|
84
|
+
from useml import Config
|
|
85
|
+
|
|
86
|
+
config = Config(
|
|
87
|
+
epochs=30,
|
|
88
|
+
lr=1e-3,
|
|
89
|
+
optimizer="adamw", # "adam" | "adamw" | "sgd"
|
|
90
|
+
loss="cross_entropy", # str key, nn.Module class/instance, or callable
|
|
91
|
+
batch_size=128,
|
|
92
|
+
checkpoint_every=5, # commit every N epochs during useml.train()
|
|
93
|
+
device="auto", # "auto" | "cpu" | "cuda" | "mps"
|
|
94
|
+
)
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
### Dashboard
|
|
98
|
+
|
|
99
|
+
```python
|
|
100
|
+
useml.show()
|
|
101
|
+
# --- UseML Dashboard ---
|
|
102
|
+
# Vault: vault/
|
|
103
|
+
# Project: my-experiment (3 snapshots)
|
|
104
|
+
# Tracked: ['classifier']
|
|
105
|
+
# Latest: baseline [snap_20240501_...]
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
## Level-0 — train in two lines
|
|
109
|
+
|
|
110
|
+
```python
|
|
111
|
+
import useml
|
|
112
|
+
from useml import Config, Model
|
|
113
|
+
import torch.nn as nn
|
|
114
|
+
|
|
115
|
+
class Net(Model):
|
|
116
|
+
def __init__(self):
|
|
117
|
+
super().__init__()
|
|
118
|
+
self.fc = nn.Linear(784, 10)
|
|
119
|
+
def forward(self, x):
|
|
120
|
+
return self.fc(x.view(x.size(0), -1))
|
|
121
|
+
|
|
122
|
+
useml.init("vault")
|
|
123
|
+
useml.new("mnist-quick", auto_focus=True)
|
|
124
|
+
|
|
125
|
+
history = useml.train(Net, "mnist", config=Config(epochs=10))
|
|
126
|
+
# Built-in datasets: "mnist", "fashion_mnist", "cifar10", "cifar100"
|
|
127
|
+
# HuggingFace: "hf:<dataset_name>"
|
|
128
|
+
# Custom: any torch.utils.data.Dataset
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
### Custom step function
|
|
132
|
+
|
|
133
|
+
Override the default `criterion(model(x), y)` without subclassing:
|
|
134
|
+
|
|
135
|
+
```python
|
|
136
|
+
def ae_step(model, batch, device):
|
|
137
|
+
x, _ = batch
|
|
138
|
+
x = x.to(device)
|
|
139
|
+
return F.mse_loss(model(x), x) # target = input
|
|
140
|
+
|
|
141
|
+
useml.train(AutoEncoder, "mnist", config=config, step_fn=ae_step)
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
### Config custom fields
|
|
145
|
+
|
|
146
|
+
`Config` accepts any extra keyword argument as a custom field. Custom fields
|
|
147
|
+
are serialised to the snapshot YAML and forwarded to the model constructor
|
|
148
|
+
by `useml.load()`.
|
|
149
|
+
|
|
150
|
+
```python
|
|
151
|
+
config = Config(epochs=10, lr=1e-3, latent_dim=16, kl_weight=1e-3)
|
|
152
|
+
config.latent_dim # 16
|
|
153
|
+
config.to_dict() # includes latent_dim and kl_weight in snapshot YAML
|
|
154
|
+
|
|
155
|
+
# On load, useml calls VAE(latent_dim=16) automatically
|
|
156
|
+
model = useml.load("vae")
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
## Level-1 — DataBundle (versioned data contracts)
|
|
160
|
+
|
|
161
|
+
`DataBundle` pairs a raw dataset with a preprocessing transform and hashes
|
|
162
|
+
both at every snapshot. The raw data is stored once; only the transform code
|
|
163
|
+
and three hashes are embedded in the snapshot.
|
|
164
|
+
|
|
165
|
+
```python
|
|
166
|
+
from useml import DataBundle
|
|
167
|
+
|
|
168
|
+
bundle = DataBundle(
|
|
169
|
+
name="polar_clouds",
|
|
170
|
+
source=CartesianDataset(), # raw data — any torch Dataset or built-in name
|
|
171
|
+
transform=gridify, # per-sample callable: (sample) -> sample
|
|
172
|
+
version="v1", # optional label
|
|
173
|
+
)
|
|
174
|
+
|
|
175
|
+
history = useml.train(MyCNN, bundle, config=config)
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
Three hashes are recorded in `metadata.yaml` for every snapshot that uses the bundle:
|
|
179
|
+
|
|
180
|
+
| Hash | What it tracks |
|
|
181
|
+
|---|---|
|
|
182
|
+
| `source_hash` | Fingerprint of the raw dataset |
|
|
183
|
+
| `transform_hash` | sha256 of the transform function's source code + name |
|
|
184
|
+
| `cache_key` | sha256(source_hash + transform_hash) — used for disk cache |
|
|
185
|
+
|
|
186
|
+
The transform source code is also archived verbatim in `source/_bundle_<name>_<fn>.py`
|
|
187
|
+
inside the snapshot, so the exact preprocessing of any checkpoint is always recoverable.
|
|
188
|
+
|
|
189
|
+
### Factory transforms
|
|
190
|
+
|
|
191
|
+
When a transform is produced by a factory (different params, same algorithm),
|
|
192
|
+
set a descriptive `__name__` so the hashes and archived file names are distinct:
|
|
193
|
+
|
|
194
|
+
```python
|
|
195
|
+
def make_gridify(n_r_bins, n_theta_bins):
|
|
196
|
+
def gridify(sample):
|
|
197
|
+
...
|
|
198
|
+
gridify.__name__ = f"gridify_{n_r_bins}r_{n_theta_bins}t"
|
|
199
|
+
return gridify
|
|
200
|
+
|
|
201
|
+
bundle_fine = DataBundle("ds", raw_ds, transform=make_gridify(16, 32))
|
|
202
|
+
bundle_coarse = DataBundle("ds", raw_ds, transform=make_gridify(8, 16))
|
|
203
|
+
# → different transform_hash, different archived .py file
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
### Optional disk cache
|
|
207
|
+
|
|
208
|
+
For expensive transforms, set `cache=True` to materialise the processed dataset
|
|
209
|
+
on first run and reload it on subsequent runs:
|
|
210
|
+
|
|
211
|
+
```python
|
|
212
|
+
bundle = DataBundle("ds", raw_ds, transform=heavy_preprocess, cache=True)
|
|
213
|
+
# Saved to: <data_dir>/.bundle_cache/<cache_key>.pt
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
### Manual commit with bundle metadata
|
|
217
|
+
|
|
218
|
+
When calling `useml.train()`, bundle metadata flows into the snapshot automatically.
|
|
219
|
+
For manual workflows, pass it explicitly:
|
|
220
|
+
|
|
221
|
+
```python
|
|
222
|
+
useml.track("model", model, config=config)
|
|
223
|
+
useml.commit("run 1", bundle_meta=bundle.to_meta_dict())
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
## Loading models
|
|
227
|
+
|
|
228
|
+
```python
|
|
229
|
+
# Load latest weights (uses current code)
|
|
230
|
+
model = useml.load("classifier")
|
|
231
|
+
|
|
232
|
+
# Load with full code isolation (archived source + weights)
|
|
233
|
+
useml.mount("\\latest")
|
|
234
|
+
model = useml.load("classifier")
|
|
235
|
+
|
|
236
|
+
# Load from a specific snapshot
|
|
237
|
+
model = useml.load("classifier", _from="\\head~2")
|
|
238
|
+
|
|
239
|
+
# Import archived code directly
|
|
240
|
+
useml.mount("\\latest")
|
|
241
|
+
from useml.workdir.models import Net
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
## Snapshot tags
|
|
245
|
+
|
|
246
|
+
| Tag | Meaning |
|
|
247
|
+
|---|---|
|
|
248
|
+
| `\latest` | Most recent snapshot |
|
|
249
|
+
| `\head~N` | N snapshots before latest |
|
|
250
|
+
| `\current` / `\workdir` | Unmount (back to live code) |
|
|
251
|
+
| `snap_20240501_...` | Exact snapshot folder name |
|
|
252
|
+
|
|
253
|
+
## Custom loss
|
|
254
|
+
|
|
255
|
+
```python
|
|
256
|
+
# String key (built-in)
|
|
257
|
+
Config(loss="cross_entropy") # also: "mse", "bce", "l1"
|
|
258
|
+
|
|
259
|
+
# Class
|
|
260
|
+
Config(loss=nn.HuberLoss)
|
|
261
|
+
|
|
262
|
+
# Instance
|
|
263
|
+
Config(loss=nn.HuberLoss(delta=0.5))
|
|
264
|
+
|
|
265
|
+
# Plain function
|
|
266
|
+
def focal_loss(pred, target): ...
|
|
267
|
+
Config(loss=focal_loss)
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
The loss source is automatically archived in the snapshot.
|
|
271
|
+
|
|
272
|
+
## Stashing (multi-project workflows)
|
|
273
|
+
|
|
274
|
+
```python
|
|
275
|
+
useml.focus("project-a")
|
|
276
|
+
useml.track("model", model_a)
|
|
277
|
+
useml.stash() # park project-a in RAM
|
|
278
|
+
|
|
279
|
+
useml.focus("project-b")
|
|
280
|
+
useml.track("model", model_b)
|
|
281
|
+
useml.commit("run b")
|
|
282
|
+
|
|
283
|
+
useml.focus("project-a") # restore from stash
|
|
284
|
+
useml.commit("run a")
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
## Error codes
|
|
288
|
+
|
|
289
|
+
All exceptions raised by useml carry a `[UML-NNN]` code. See [ERRORS.md](ERRORS.md) for the full catalog with causes and fixes.
|
|
290
|
+
|
|
291
|
+
## API reference
|
|
292
|
+
|
|
293
|
+
| Function | Description |
|
|
294
|
+
|---|---|
|
|
295
|
+
| `useml.init(vault_path)` | Connect session to a vault directory |
|
|
296
|
+
| `useml.new(name)` | Create and focus a new project |
|
|
297
|
+
| `useml.focus(name)` | Resume an existing project |
|
|
298
|
+
| `useml.track(name, model, config?, optimizer?)` | Register a component |
|
|
299
|
+
| `useml.commit(message, **metrics)` | Save a snapshot |
|
|
300
|
+
| `useml.load(name, _from?)` | Restore a model with weights |
|
|
301
|
+
| `useml.mount(tag)` | Mount a snapshot for workdir imports |
|
|
302
|
+
| `useml.show()` | Print session dashboard |
|
|
303
|
+
| `useml.stash()` | Park current project state in RAM |
|
|
304
|
+
| `useml.projects()` | List all projects in the vault |
|
|
305
|
+
| `useml.train(model_cls, dataset, config?, step_fn?)` | Level-0 training entry point |
|
|
306
|
+
| `useml.debug_imports()` | Inspect workdir importable modules |
|
|
307
|
+
|
|
308
|
+
**Level-1**
|
|
309
|
+
|
|
310
|
+
| Class | Description |
|
|
311
|
+
|---|---|
|
|
312
|
+
| `useml.DataBundle(name, source, transform?, version?, cache?)` | Versioned data contract with hash tracking |
|
|
313
|
+
| `bundle.source_hash()` | Fingerprint of the raw dataset |
|
|
314
|
+
| `bundle.transform_hash()` | sha256 of the transform source + name |
|
|
315
|
+
| `bundle.cache_key()` | Combined hash used for disk cache |
|
|
316
|
+
| `bundle.to_meta_dict()` | Dict embedded in snapshot `metadata.yaml` under `data:` |
|
|
317
|
+
| `bundle.transform_source()` | Source code of the transform (for archival) |
|
useml-0.2.0/README.md
ADDED
|
@@ -0,0 +1,300 @@
|
|
|
1
|
+
# useml
|
|
2
|
+
|
|
3
|
+
**Stop coding plumbing, start training models.**
|
|
4
|
+
|
|
5
|
+
`useml` is a minimalist ML experiment versioning framework for PyTorch. It handles checkpointing, source archiving, and model isolation so you can focus on the architecture.
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
pip install useml
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Core concepts
|
|
14
|
+
|
|
15
|
+
```
|
|
16
|
+
vault/
|
|
17
|
+
└── my-experiment/ ← project
|
|
18
|
+
├── snap_20240501_.../ ← snapshot (one per commit)
|
|
19
|
+
│ ├── weights/ ← model .pth files
|
|
20
|
+
│ ├── configs/ ← per-component YAML configs
|
|
21
|
+
│ ├── source/ ← archived source code
|
|
22
|
+
│ ├── manifest.yaml ← component registry
|
|
23
|
+
│ └── metadata.yaml ← message + metrics
|
|
24
|
+
└── snap_20240502_.../
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## Basic usage
|
|
28
|
+
|
|
29
|
+
### Session setup
|
|
30
|
+
|
|
31
|
+
```python
|
|
32
|
+
import useml
|
|
33
|
+
|
|
34
|
+
useml.init("vault") # connect to a vault directory
|
|
35
|
+
useml.new("my-experiment") # create and focus a project
|
|
36
|
+
# or: useml.focus("my-experiment") to resume an existing one
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
### Track → Commit loop
|
|
40
|
+
|
|
41
|
+
```python
|
|
42
|
+
import torch.nn as nn
|
|
43
|
+
import useml
|
|
44
|
+
|
|
45
|
+
useml.init("vault")
|
|
46
|
+
useml.new("mnist-run", auto_focus=True)
|
|
47
|
+
|
|
48
|
+
model = nn.Linear(784, 10)
|
|
49
|
+
useml.track("classifier", model)
|
|
50
|
+
|
|
51
|
+
# ... train ...
|
|
52
|
+
|
|
53
|
+
snap = useml.commit("baseline", val_loss=0.42, accuracy=0.91)
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### Multiple models, per-model configs
|
|
57
|
+
|
|
58
|
+
```python
|
|
59
|
+
useml.track("encoder", encoder, config=encoder_config)
|
|
60
|
+
useml.track("decoder", decoder, config=decoder_config)
|
|
61
|
+
useml.commit("joint training", val_loss=0.18)
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### Config
|
|
65
|
+
|
|
66
|
+
```python
|
|
67
|
+
from useml import Config
|
|
68
|
+
|
|
69
|
+
config = Config(
|
|
70
|
+
epochs=30,
|
|
71
|
+
lr=1e-3,
|
|
72
|
+
optimizer="adamw", # "adam" | "adamw" | "sgd"
|
|
73
|
+
loss="cross_entropy", # str key, nn.Module class/instance, or callable
|
|
74
|
+
batch_size=128,
|
|
75
|
+
checkpoint_every=5, # commit every N epochs during useml.train()
|
|
76
|
+
device="auto", # "auto" | "cpu" | "cuda" | "mps"
|
|
77
|
+
)
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
### Dashboard
|
|
81
|
+
|
|
82
|
+
```python
|
|
83
|
+
useml.show()
|
|
84
|
+
# --- UseML Dashboard ---
|
|
85
|
+
# Vault: vault/
|
|
86
|
+
# Project: my-experiment (3 snapshots)
|
|
87
|
+
# Tracked: ['classifier']
|
|
88
|
+
# Latest: baseline [snap_20240501_...]
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
## Level-0 — train in two lines
|
|
92
|
+
|
|
93
|
+
```python
|
|
94
|
+
import useml
|
|
95
|
+
from useml import Config, Model
|
|
96
|
+
import torch.nn as nn
|
|
97
|
+
|
|
98
|
+
class Net(Model):
|
|
99
|
+
def __init__(self):
|
|
100
|
+
super().__init__()
|
|
101
|
+
self.fc = nn.Linear(784, 10)
|
|
102
|
+
def forward(self, x):
|
|
103
|
+
return self.fc(x.view(x.size(0), -1))
|
|
104
|
+
|
|
105
|
+
useml.init("vault")
|
|
106
|
+
useml.new("mnist-quick", auto_focus=True)
|
|
107
|
+
|
|
108
|
+
history = useml.train(Net, "mnist", config=Config(epochs=10))
|
|
109
|
+
# Built-in datasets: "mnist", "fashion_mnist", "cifar10", "cifar100"
|
|
110
|
+
# HuggingFace: "hf:<dataset_name>"
|
|
111
|
+
# Custom: any torch.utils.data.Dataset
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
### Custom step function
|
|
115
|
+
|
|
116
|
+
Override the default `criterion(model(x), y)` without subclassing:
|
|
117
|
+
|
|
118
|
+
```python
|
|
119
|
+
def ae_step(model, batch, device):
|
|
120
|
+
x, _ = batch
|
|
121
|
+
x = x.to(device)
|
|
122
|
+
return F.mse_loss(model(x), x) # target = input
|
|
123
|
+
|
|
124
|
+
useml.train(AutoEncoder, "mnist", config=config, step_fn=ae_step)
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
### Config custom fields
|
|
128
|
+
|
|
129
|
+
`Config` accepts any extra keyword argument as a custom field. Custom fields
|
|
130
|
+
are serialised to the snapshot YAML and forwarded to the model constructor
|
|
131
|
+
by `useml.load()`.
|
|
132
|
+
|
|
133
|
+
```python
|
|
134
|
+
config = Config(epochs=10, lr=1e-3, latent_dim=16, kl_weight=1e-3)
|
|
135
|
+
config.latent_dim # 16
|
|
136
|
+
config.to_dict() # includes latent_dim and kl_weight in snapshot YAML
|
|
137
|
+
|
|
138
|
+
# On load, useml calls VAE(latent_dim=16) automatically
|
|
139
|
+
model = useml.load("vae")
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
## Level-1 — DataBundle (versioned data contracts)
|
|
143
|
+
|
|
144
|
+
`DataBundle` pairs a raw dataset with a preprocessing transform and hashes
|
|
145
|
+
both at every snapshot. The raw data is stored once; only the transform code
|
|
146
|
+
and three hashes are embedded in the snapshot.
|
|
147
|
+
|
|
148
|
+
```python
|
|
149
|
+
from useml import DataBundle
|
|
150
|
+
|
|
151
|
+
bundle = DataBundle(
|
|
152
|
+
name="polar_clouds",
|
|
153
|
+
source=CartesianDataset(), # raw data — any torch Dataset or built-in name
|
|
154
|
+
transform=gridify, # per-sample callable: (sample) -> sample
|
|
155
|
+
version="v1", # optional label
|
|
156
|
+
)
|
|
157
|
+
|
|
158
|
+
history = useml.train(MyCNN, bundle, config=config)
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
Three hashes are recorded in `metadata.yaml` for every snapshot that uses the bundle:
|
|
162
|
+
|
|
163
|
+
| Hash | What it tracks |
|
|
164
|
+
|---|---|
|
|
165
|
+
| `source_hash` | Fingerprint of the raw dataset |
|
|
166
|
+
| `transform_hash` | sha256 of the transform function's source code + name |
|
|
167
|
+
| `cache_key` | sha256(source_hash + transform_hash) — used for disk cache |
|
|
168
|
+
|
|
169
|
+
The transform source code is also archived verbatim in `source/_bundle_<name>_<fn>.py`
|
|
170
|
+
inside the snapshot, so the exact preprocessing of any checkpoint is always recoverable.
|
|
171
|
+
|
|
172
|
+
### Factory transforms
|
|
173
|
+
|
|
174
|
+
When a transform is produced by a factory (different params, same algorithm),
|
|
175
|
+
set a descriptive `__name__` so the hashes and archived file names are distinct:
|
|
176
|
+
|
|
177
|
+
```python
|
|
178
|
+
def make_gridify(n_r_bins, n_theta_bins):
|
|
179
|
+
def gridify(sample):
|
|
180
|
+
...
|
|
181
|
+
gridify.__name__ = f"gridify_{n_r_bins}r_{n_theta_bins}t"
|
|
182
|
+
return gridify
|
|
183
|
+
|
|
184
|
+
bundle_fine = DataBundle("ds", raw_ds, transform=make_gridify(16, 32))
|
|
185
|
+
bundle_coarse = DataBundle("ds", raw_ds, transform=make_gridify(8, 16))
|
|
186
|
+
# → different transform_hash, different archived .py file
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
### Optional disk cache
|
|
190
|
+
|
|
191
|
+
For expensive transforms, set `cache=True` to materialise the processed dataset
|
|
192
|
+
on first run and reload it on subsequent runs:
|
|
193
|
+
|
|
194
|
+
```python
|
|
195
|
+
bundle = DataBundle("ds", raw_ds, transform=heavy_preprocess, cache=True)
|
|
196
|
+
# Saved to: <data_dir>/.bundle_cache/<cache_key>.pt
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
### Manual commit with bundle metadata
|
|
200
|
+
|
|
201
|
+
When calling `useml.train()`, bundle metadata flows into the snapshot automatically.
|
|
202
|
+
For manual workflows, pass it explicitly:
|
|
203
|
+
|
|
204
|
+
```python
|
|
205
|
+
useml.track("model", model, config=config)
|
|
206
|
+
useml.commit("run 1", bundle_meta=bundle.to_meta_dict())
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
## Loading models
|
|
210
|
+
|
|
211
|
+
```python
|
|
212
|
+
# Load latest weights (uses current code)
|
|
213
|
+
model = useml.load("classifier")
|
|
214
|
+
|
|
215
|
+
# Load with full code isolation (archived source + weights)
|
|
216
|
+
useml.mount("\\latest")
|
|
217
|
+
model = useml.load("classifier")
|
|
218
|
+
|
|
219
|
+
# Load from a specific snapshot
|
|
220
|
+
model = useml.load("classifier", _from="\\head~2")
|
|
221
|
+
|
|
222
|
+
# Import archived code directly
|
|
223
|
+
useml.mount("\\latest")
|
|
224
|
+
from useml.workdir.models import Net
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
## Snapshot tags
|
|
228
|
+
|
|
229
|
+
| Tag | Meaning |
|
|
230
|
+
|---|---|
|
|
231
|
+
| `\latest` | Most recent snapshot |
|
|
232
|
+
| `\head~N` | N snapshots before latest |
|
|
233
|
+
| `\current` / `\workdir` | Unmount (back to live code) |
|
|
234
|
+
| `snap_20240501_...` | Exact snapshot folder name |
|
|
235
|
+
|
|
236
|
+
## Custom loss
|
|
237
|
+
|
|
238
|
+
```python
|
|
239
|
+
# String key (built-in)
|
|
240
|
+
Config(loss="cross_entropy") # also: "mse", "bce", "l1"
|
|
241
|
+
|
|
242
|
+
# Class
|
|
243
|
+
Config(loss=nn.HuberLoss)
|
|
244
|
+
|
|
245
|
+
# Instance
|
|
246
|
+
Config(loss=nn.HuberLoss(delta=0.5))
|
|
247
|
+
|
|
248
|
+
# Plain function
|
|
249
|
+
def focal_loss(pred, target): ...
|
|
250
|
+
Config(loss=focal_loss)
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
The loss source is automatically archived in the snapshot.
|
|
254
|
+
|
|
255
|
+
## Stashing (multi-project workflows)
|
|
256
|
+
|
|
257
|
+
```python
|
|
258
|
+
useml.focus("project-a")
|
|
259
|
+
useml.track("model", model_a)
|
|
260
|
+
useml.stash() # park project-a in RAM
|
|
261
|
+
|
|
262
|
+
useml.focus("project-b")
|
|
263
|
+
useml.track("model", model_b)
|
|
264
|
+
useml.commit("run b")
|
|
265
|
+
|
|
266
|
+
useml.focus("project-a") # restore from stash
|
|
267
|
+
useml.commit("run a")
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
## Error codes
|
|
271
|
+
|
|
272
|
+
All exceptions raised by useml carry a `[UML-NNN]` code. See [ERRORS.md](ERRORS.md) for the full catalog with causes and fixes.
|
|
273
|
+
|
|
274
|
+
## API reference
|
|
275
|
+
|
|
276
|
+
| Function | Description |
|
|
277
|
+
|---|---|
|
|
278
|
+
| `useml.init(vault_path)` | Connect session to a vault directory |
|
|
279
|
+
| `useml.new(name)` | Create and focus a new project |
|
|
280
|
+
| `useml.focus(name)` | Resume an existing project |
|
|
281
|
+
| `useml.track(name, model, config?, optimizer?)` | Register a component |
|
|
282
|
+
| `useml.commit(message, **metrics)` | Save a snapshot |
|
|
283
|
+
| `useml.load(name, _from?)` | Restore a model with weights |
|
|
284
|
+
| `useml.mount(tag)` | Mount a snapshot for workdir imports |
|
|
285
|
+
| `useml.show()` | Print session dashboard |
|
|
286
|
+
| `useml.stash()` | Park current project state in RAM |
|
|
287
|
+
| `useml.projects()` | List all projects in the vault |
|
|
288
|
+
| `useml.train(model_cls, dataset, config?, step_fn?)` | Level-0 training entry point |
|
|
289
|
+
| `useml.debug_imports()` | Inspect workdir importable modules |
|
|
290
|
+
|
|
291
|
+
**Level-1**
|
|
292
|
+
|
|
293
|
+
| Class | Description |
|
|
294
|
+
|---|---|
|
|
295
|
+
| `useml.DataBundle(name, source, transform?, version?, cache?)` | Versioned data contract with hash tracking |
|
|
296
|
+
| `bundle.source_hash()` | Fingerprint of the raw dataset |
|
|
297
|
+
| `bundle.transform_hash()` | sha256 of the transform source + name |
|
|
298
|
+
| `bundle.cache_key()` | Combined hash used for disk cache |
|
|
299
|
+
| `bundle.to_meta_dict()` | Dict embedded in snapshot `metadata.yaml` under `data:` |
|
|
300
|
+
| `bundle.transform_source()` | Source code of the transform (for archival) |
|
|
@@ -12,17 +12,19 @@ dev = [
|
|
|
12
12
|
|
|
13
13
|
[project]
|
|
14
14
|
name = "useml"
|
|
15
|
-
version = "0.0
|
|
16
|
-
description = "
|
|
15
|
+
version = "0.2.0"
|
|
16
|
+
description = "Minimalist ML experiment versioning for PyTorch — checkpointing, source archiving, and model isolation."
|
|
17
17
|
readme = "README.md"
|
|
18
18
|
requires-python = ">=3.8"
|
|
19
19
|
authors = [{name = "Enzo-py", email = "85191552+Enzo-py@users.noreply.github.com"}]
|
|
20
20
|
dependencies = [
|
|
21
21
|
"torch>=2.0.0",
|
|
22
|
-
"
|
|
23
|
-
"numpy>=1.24.0",
|
|
22
|
+
"pyyaml>=6.0",
|
|
24
23
|
]
|
|
25
24
|
|
|
25
|
+
[tool.setuptools.packages.find]
|
|
26
|
+
include = ["useml*"]
|
|
27
|
+
|
|
26
28
|
[project.urls]
|
|
27
29
|
"Homepage" = "https://github.com/Enzo-py/useml"
|
|
28
30
|
"Bug Tracker" = "https://github.com/Enzo-py/useml/issues"
|