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.
Files changed (43) hide show
  1. useml-0.2.0/PKG-INFO +317 -0
  2. useml-0.2.0/README.md +300 -0
  3. {useml-0.0.2 → useml-0.2.0}/pyproject.toml +6 -4
  4. useml-0.2.0/tests/test_bundle.py +360 -0
  5. useml-0.2.0/tests/test_session.py +211 -0
  6. useml-0.2.0/tests/test_train_level0.py +226 -0
  7. useml-0.2.0/tests/test_usecases.py +308 -0
  8. useml-0.2.0/tests/test_vault.py +242 -0
  9. useml-0.2.0/useml/__init__.py +224 -0
  10. useml-0.2.0/useml/dataset/__init__.py +4 -0
  11. useml-0.2.0/useml/dataset/bundle.py +288 -0
  12. useml-0.2.0/useml/dataset/loaders.py +168 -0
  13. useml-0.2.0/useml/errors.py +377 -0
  14. useml-0.2.0/useml/imports.py +215 -0
  15. useml-0.2.0/useml/session/__init__.py +4 -0
  16. useml-0.2.0/useml/session/component.py +59 -0
  17. useml-0.2.0/useml/session/manager.py +482 -0
  18. useml-0.2.0/useml/template/__init__.py +6 -0
  19. useml-0.2.0/useml/template/config.py +133 -0
  20. useml-0.2.0/useml/template/loss.py +28 -0
  21. useml-0.2.0/useml/template/model.py +28 -0
  22. useml-0.2.0/useml/template/trainer.py +296 -0
  23. useml-0.2.0/useml/vault/__init__.py +5 -0
  24. useml-0.2.0/useml/vault/code_extractor.py +258 -0
  25. {useml-0.0.2 → useml-0.2.0}/useml/vault/core.py +21 -11
  26. useml-0.2.0/useml/vault/project.py +168 -0
  27. useml-0.2.0/useml/vault/snapshot.py +170 -0
  28. useml-0.2.0/useml/workdir/__init__.py +14 -0
  29. useml-0.2.0/useml/workdir/_hook.py +79 -0
  30. useml-0.2.0/useml.egg-info/PKG-INFO +317 -0
  31. useml-0.2.0/useml.egg-info/SOURCES.txt +33 -0
  32. {useml-0.0.2 → useml-0.2.0}/useml.egg-info/requires.txt +1 -2
  33. useml-0.0.2/PKG-INFO +0 -99
  34. useml-0.0.2/README.md +0 -81
  35. useml-0.0.2/tests/test_vault.py +0 -135
  36. useml-0.0.2/useml/__init__.py +0 -6
  37. useml-0.0.2/useml/vault/project.py +0 -110
  38. useml-0.0.2/useml/vault/snapshot.py +0 -130
  39. useml-0.0.2/useml.egg-info/PKG-INFO +0 -99
  40. useml-0.0.2/useml.egg-info/SOURCES.txt +0 -12
  41. {useml-0.0.2 → useml-0.2.0}/setup.cfg +0 -0
  42. {useml-0.0.2 → useml-0.2.0}/useml.egg-info/dependency_links.txt +0 -0
  43. {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.2"
16
- description = "Simplifying PyTorch workflows: Pipeline, Versioning, and Vault."
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
- "tqdm>=4.65.0",
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"