useml 0.0.1__tar.gz → 0.0.2__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.0.2/PKG-INFO +99 -0
- useml-0.0.2/README.md +81 -0
- {useml-0.0.1 → useml-0.0.2}/pyproject.toml +14 -1
- useml-0.0.2/tests/test_vault.py +135 -0
- useml-0.0.2/useml/__init__.py +6 -0
- useml-0.0.2/useml/vault/core.py +53 -0
- useml-0.0.2/useml/vault/project.py +110 -0
- useml-0.0.2/useml/vault/snapshot.py +130 -0
- useml-0.0.2/useml.egg-info/PKG-INFO +99 -0
- useml-0.0.2/useml.egg-info/SOURCES.txt +12 -0
- useml-0.0.2/useml.egg-info/requires.txt +9 -0
- useml-0.0.1/PKG-INFO +0 -41
- useml-0.0.1/README.md +0 -31
- useml-0.0.1/useml/__init__.py +0 -0
- useml-0.0.1/useml.egg-info/PKG-INFO +0 -41
- useml-0.0.1/useml.egg-info/SOURCES.txt +0 -7
- {useml-0.0.1 → useml-0.0.2}/setup.cfg +0 -0
- {useml-0.0.1 → useml-0.0.2}/useml.egg-info/dependency_links.txt +0 -0
- {useml-0.0.1 → useml-0.0.2}/useml.egg-info/top_level.txt +0 -0
useml-0.0.2/PKG-INFO
ADDED
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: useml
|
|
3
|
+
Version: 0.0.2
|
|
4
|
+
Summary: Simplifying PyTorch workflows: Pipeline, Versioning, and Vault.
|
|
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: tqdm>=4.65.0
|
|
12
|
+
Requires-Dist: numpy>=1.24.0
|
|
13
|
+
Provides-Extra: dev
|
|
14
|
+
Requires-Dist: pytest>=7.0.0; extra == "dev"
|
|
15
|
+
Requires-Dist: build; extra == "dev"
|
|
16
|
+
Requires-Dist: twine; extra == "dev"
|
|
17
|
+
Requires-Dist: black; extra == "dev"
|
|
18
|
+
|
|
19
|
+
# useml
|
|
20
|
+
|
|
21
|
+
**Stop coding plumbing, start training models.**
|
|
22
|
+
|
|
23
|
+
`useml` is a minimalist framework for PyTorch designed to eliminate the 90% of software engineering overhead in Machine Learning projects. It handles pipelines, versioning, and environment sealing so you can focus on the architecture.
|
|
24
|
+
|
|
25
|
+
## Key Features
|
|
26
|
+
|
|
27
|
+
* **AtomicData**: Type-safe data structures for PyTorch.
|
|
28
|
+
* **Auto-Versioning**: Every run is automatically linked to a Git commit and config snapshot.
|
|
29
|
+
* **The Vault**: Seal your model, schema, and weights into a single, portable artifact.
|
|
30
|
+
* **Zero Friction**: If it doesn't simplify your code, it doesn't belong in `useml`.
|
|
31
|
+
|
|
32
|
+
### Basic Usage
|
|
33
|
+
|
|
34
|
+
```python
|
|
35
|
+
import torch
|
|
36
|
+
from useml import Vault
|
|
37
|
+
|
|
38
|
+
# 1. Initialize your vault (the root storage)
|
|
39
|
+
vault = Vault(path="my_vault")
|
|
40
|
+
|
|
41
|
+
# 2. Get or create a specific Project
|
|
42
|
+
project = vault.get_project("mnist_classifier")
|
|
43
|
+
|
|
44
|
+
# 3. Define your model
|
|
45
|
+
model = torch.nn.Linear(10, 2)
|
|
46
|
+
|
|
47
|
+
# 4. Commit your progress
|
|
48
|
+
# This saves: weights.pth + manifest.yaml + metadata.yaml
|
|
49
|
+
project.commit(model, message="Initial baseline", lr=1e-3, accuracy=0.92)
|
|
50
|
+
|
|
51
|
+
# 5. List project history (newest first)
|
|
52
|
+
for snap in project.log():
|
|
53
|
+
print(f"[{snap['timestamp']}] {snap['message']} | Acc: {snap['accuracy']}")
|
|
54
|
+
|
|
55
|
+
# 6. Restore weights from the latest snapshot
|
|
56
|
+
latest = project[0]
|
|
57
|
+
latest.load_weights(model)
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## Installation
|
|
61
|
+
```bash
|
|
62
|
+
pip install useml
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Why useml?
|
|
66
|
+
Most ML projects fail because of "hidden technical debt" in the pipeline. useml enforces a clean structure from the first line of code, ensuring that every experiment you run is 100% reproducible and deployable.
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
## Development & Testing
|
|
70
|
+
|
|
71
|
+
If you want to contribute or test the framework, follow these steps.
|
|
72
|
+
|
|
73
|
+
### 1. Install for development
|
|
74
|
+
Clone the repo and install it in editable mode with dev dependencies:
|
|
75
|
+
```bash
|
|
76
|
+
pip install -e ".[dev]"
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
### 2. Running Tests
|
|
80
|
+
We use pytest for unit testing. The tests are located in the tests/ directory.
|
|
81
|
+
To run the full suite:
|
|
82
|
+
```bash
|
|
83
|
+
pytest -vv
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
### 3. Build & Publish
|
|
87
|
+
**Update Version**: Increment version in `pyproject.toml`.
|
|
88
|
+
|
|
89
|
+
Build the package:
|
|
90
|
+
```bash
|
|
91
|
+
rm -rf dist/ build/ *.egg-info
|
|
92
|
+
python3 -m build
|
|
93
|
+
twine check dist/*
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Upload the new package version:
|
|
97
|
+
```bash
|
|
98
|
+
twine upload dist/*
|
|
99
|
+
```
|
useml-0.0.2/README.md
ADDED
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# useml
|
|
2
|
+
|
|
3
|
+
**Stop coding plumbing, start training models.**
|
|
4
|
+
|
|
5
|
+
`useml` is a minimalist framework for PyTorch designed to eliminate the 90% of software engineering overhead in Machine Learning projects. It handles pipelines, versioning, and environment sealing so you can focus on the architecture.
|
|
6
|
+
|
|
7
|
+
## Key Features
|
|
8
|
+
|
|
9
|
+
* **AtomicData**: Type-safe data structures for PyTorch.
|
|
10
|
+
* **Auto-Versioning**: Every run is automatically linked to a Git commit and config snapshot.
|
|
11
|
+
* **The Vault**: Seal your model, schema, and weights into a single, portable artifact.
|
|
12
|
+
* **Zero Friction**: If it doesn't simplify your code, it doesn't belong in `useml`.
|
|
13
|
+
|
|
14
|
+
### Basic Usage
|
|
15
|
+
|
|
16
|
+
```python
|
|
17
|
+
import torch
|
|
18
|
+
from useml import Vault
|
|
19
|
+
|
|
20
|
+
# 1. Initialize your vault (the root storage)
|
|
21
|
+
vault = Vault(path="my_vault")
|
|
22
|
+
|
|
23
|
+
# 2. Get or create a specific Project
|
|
24
|
+
project = vault.get_project("mnist_classifier")
|
|
25
|
+
|
|
26
|
+
# 3. Define your model
|
|
27
|
+
model = torch.nn.Linear(10, 2)
|
|
28
|
+
|
|
29
|
+
# 4. Commit your progress
|
|
30
|
+
# This saves: weights.pth + manifest.yaml + metadata.yaml
|
|
31
|
+
project.commit(model, message="Initial baseline", lr=1e-3, accuracy=0.92)
|
|
32
|
+
|
|
33
|
+
# 5. List project history (newest first)
|
|
34
|
+
for snap in project.log():
|
|
35
|
+
print(f"[{snap['timestamp']}] {snap['message']} | Acc: {snap['accuracy']}")
|
|
36
|
+
|
|
37
|
+
# 6. Restore weights from the latest snapshot
|
|
38
|
+
latest = project[0]
|
|
39
|
+
latest.load_weights(model)
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Installation
|
|
43
|
+
```bash
|
|
44
|
+
pip install useml
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Why useml?
|
|
48
|
+
Most ML projects fail because of "hidden technical debt" in the pipeline. useml enforces a clean structure from the first line of code, ensuring that every experiment you run is 100% reproducible and deployable.
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
## Development & Testing
|
|
52
|
+
|
|
53
|
+
If you want to contribute or test the framework, follow these steps.
|
|
54
|
+
|
|
55
|
+
### 1. Install for development
|
|
56
|
+
Clone the repo and install it in editable mode with dev dependencies:
|
|
57
|
+
```bash
|
|
58
|
+
pip install -e ".[dev]"
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
### 2. Running Tests
|
|
62
|
+
We use pytest for unit testing. The tests are located in the tests/ directory.
|
|
63
|
+
To run the full suite:
|
|
64
|
+
```bash
|
|
65
|
+
pytest -vv
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
### 3. Build & Publish
|
|
69
|
+
**Update Version**: Increment version in `pyproject.toml`.
|
|
70
|
+
|
|
71
|
+
Build the package:
|
|
72
|
+
```bash
|
|
73
|
+
rm -rf dist/ build/ *.egg-info
|
|
74
|
+
python3 -m build
|
|
75
|
+
twine check dist/*
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Upload the new package version:
|
|
79
|
+
```bash
|
|
80
|
+
twine upload dist/*
|
|
81
|
+
```
|
|
@@ -2,13 +2,26 @@
|
|
|
2
2
|
requires = ["setuptools", "wheel"]
|
|
3
3
|
build-backend = "setuptools.build_meta"
|
|
4
4
|
|
|
5
|
+
[project.optional-dependencies]
|
|
6
|
+
dev = [
|
|
7
|
+
"pytest>=7.0.0",
|
|
8
|
+
"build",
|
|
9
|
+
"twine",
|
|
10
|
+
"black",
|
|
11
|
+
]
|
|
12
|
+
|
|
5
13
|
[project]
|
|
6
14
|
name = "useml"
|
|
7
|
-
version = "0.0.
|
|
15
|
+
version = "0.0.2"
|
|
8
16
|
description = "Simplifying PyTorch workflows: Pipeline, Versioning, and Vault."
|
|
9
17
|
readme = "README.md"
|
|
10
18
|
requires-python = ">=3.8"
|
|
11
19
|
authors = [{name = "Enzo-py", email = "85191552+Enzo-py@users.noreply.github.com"}]
|
|
20
|
+
dependencies = [
|
|
21
|
+
"torch>=2.0.0",
|
|
22
|
+
"tqdm>=4.65.0",
|
|
23
|
+
"numpy>=1.24.0",
|
|
24
|
+
]
|
|
12
25
|
|
|
13
26
|
[project.urls]
|
|
14
27
|
"Homepage" = "https://github.com/Enzo-py/useml"
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
import pytest
|
|
2
|
+
import torch
|
|
3
|
+
import shutil
|
|
4
|
+
from pathlib import Path
|
|
5
|
+
from useml import Vault
|
|
6
|
+
|
|
7
|
+
# --- FIXTURES ---
|
|
8
|
+
|
|
9
|
+
@pytest.fixture
|
|
10
|
+
def clean_vault_path():
|
|
11
|
+
"""
|
|
12
|
+
Ensures a clean testing environment by creating a temporary
|
|
13
|
+
directory before each test and removing it afterward.
|
|
14
|
+
"""
|
|
15
|
+
path = Path("test_vault_storage")
|
|
16
|
+
if path.exists():
|
|
17
|
+
shutil.rmtree(path)
|
|
18
|
+
yield path
|
|
19
|
+
if path.exists():
|
|
20
|
+
shutil.rmtree(path)
|
|
21
|
+
|
|
22
|
+
# --- TEST CLASSES ---
|
|
23
|
+
|
|
24
|
+
class TestVaultHierarchy:
|
|
25
|
+
"""Tests the navigation and relationship between Vault and Project levels."""
|
|
26
|
+
|
|
27
|
+
def test_project_initialization(self, clean_vault_path):
|
|
28
|
+
"""Verifies that projects are correctly instantiated and tracked by the Vault."""
|
|
29
|
+
vault = Vault(path=clean_vault_path)
|
|
30
|
+
project = vault.get_project("mnist_v1")
|
|
31
|
+
|
|
32
|
+
assert project.path.name == "mnist_v1"
|
|
33
|
+
assert project.path.exists()
|
|
34
|
+
assert "mnist_v1" in vault.list_projects()
|
|
35
|
+
|
|
36
|
+
def test_multi_project_isolation(self, clean_vault_path):
|
|
37
|
+
"""Ensures that multiple projects can coexist independently within the same Vault."""
|
|
38
|
+
vault = Vault(path=clean_vault_path)
|
|
39
|
+
vault.get_project("computer_vision")
|
|
40
|
+
vault.get_project("nlp_task")
|
|
41
|
+
|
|
42
|
+
projects = vault.list_projects()
|
|
43
|
+
assert len(projects) == 2
|
|
44
|
+
assert "computer_vision" in projects
|
|
45
|
+
assert "nlp_task" in projects
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
class TestProjectOperations:
|
|
49
|
+
"""Tests the lifecycle of snapshots within a project, including persistence and ordering."""
|
|
50
|
+
|
|
51
|
+
def test_commit_persistence_lifecycle(self, clean_vault_path):
|
|
52
|
+
"""
|
|
53
|
+
Validates that data remains persistent after the Vault object is destroyed
|
|
54
|
+
and re-initialized.
|
|
55
|
+
"""
|
|
56
|
+
# Session 1: Commit data
|
|
57
|
+
v1 = Vault(path=clean_vault_path)
|
|
58
|
+
proj1 = v1.get_project("persistence_study")
|
|
59
|
+
model = torch.nn.Linear(10, 1)
|
|
60
|
+
|
|
61
|
+
proj1.commit(model, "Stable baseline", accuracy=0.98, stage="production")
|
|
62
|
+
del v1, proj1 # Simulate program exit
|
|
63
|
+
|
|
64
|
+
# Session 2: Re-load and Verify
|
|
65
|
+
v2 = Vault(path=clean_vault_path)
|
|
66
|
+
proj2 = v2.get_project("persistence_study")
|
|
67
|
+
|
|
68
|
+
assert len(proj2) == 1
|
|
69
|
+
snapshot = proj2[0]
|
|
70
|
+
assert snapshot["message"] == "Stable baseline"
|
|
71
|
+
assert snapshot["accuracy"] == 0.98
|
|
72
|
+
assert snapshot["stage"] == "production"
|
|
73
|
+
|
|
74
|
+
def test_chronological_ordering(self, clean_vault_path):
|
|
75
|
+
"""Ensures that .log() returns snapshots in descending chronological order (newest first)."""
|
|
76
|
+
vault = Vault(path=clean_vault_path)
|
|
77
|
+
proj = vault.get_project("chronology_test")
|
|
78
|
+
model = torch.nn.Linear(2, 2)
|
|
79
|
+
|
|
80
|
+
# Commit sequence
|
|
81
|
+
proj.commit(model, "First Commit", version=1)
|
|
82
|
+
proj.commit(model, "Second Commit", version=2)
|
|
83
|
+
proj.commit(model, "Third Commit", version=3)
|
|
84
|
+
|
|
85
|
+
history = proj.log()
|
|
86
|
+
assert len(history) == 3
|
|
87
|
+
assert history[0]["version"] == 3 # Latest
|
|
88
|
+
assert history[-1]["version"] == 1 # Oldest
|
|
89
|
+
|
|
90
|
+
def test_empty_project_constraints(self, clean_vault_path):
|
|
91
|
+
"""Checks expected failure modes when interacting with an empty project."""
|
|
92
|
+
vault = Vault(path=clean_vault_path)
|
|
93
|
+
proj = vault.get_project("empty_repo")
|
|
94
|
+
|
|
95
|
+
assert len(proj) == 0
|
|
96
|
+
with pytest.raises(IndexError):
|
|
97
|
+
_ = proj[0]
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
class TestSnapshotIntegrity:
|
|
101
|
+
"""Tests the technical validity of stored artifacts (PyTorch weights and JSON metadata)."""
|
|
102
|
+
|
|
103
|
+
def test_weight_restoration_fidelity(self, clean_vault_path):
|
|
104
|
+
"""Verifies that loaded weights are numerically identical to saved weights."""
|
|
105
|
+
vault = Vault(path=clean_vault_path)
|
|
106
|
+
proj = vault.get_project("integrity_check")
|
|
107
|
+
model = torch.nn.Linear(5, 5)
|
|
108
|
+
|
|
109
|
+
# Inject known values
|
|
110
|
+
with torch.no_grad():
|
|
111
|
+
model.weight.fill_(42.0)
|
|
112
|
+
model.bias.fill_(0.0)
|
|
113
|
+
|
|
114
|
+
proj.commit(model, "Checkpoint 42")
|
|
115
|
+
|
|
116
|
+
# Load into a fresh model instance
|
|
117
|
+
new_model = torch.nn.Linear(5, 5)
|
|
118
|
+
proj[0].load_weights(new_model)
|
|
119
|
+
|
|
120
|
+
assert torch.all(new_model.weight == 42.0)
|
|
121
|
+
assert torch.all(new_model.bias == 0.0)
|
|
122
|
+
|
|
123
|
+
def test_manifest_integrity(self, clean_vault_path):
|
|
124
|
+
"""Validates that commit messages are stored in the manifest, not the folder name."""
|
|
125
|
+
vault = Vault(path=clean_vault_path)
|
|
126
|
+
proj = vault.get_project("formatting")
|
|
127
|
+
model = torch.nn.Linear(2, 2)
|
|
128
|
+
|
|
129
|
+
msg = "Initial Research Prototype"
|
|
130
|
+
snap = proj.commit(model, msg)
|
|
131
|
+
|
|
132
|
+
# 1. The folder name should be a clean timestamped ID
|
|
133
|
+
assert "snap_" in snap.path.name
|
|
134
|
+
# 2. The REAL message must be retrieved via __getitem__ (from manifest.yaml)
|
|
135
|
+
assert snap["message"] == msg
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
from pathlib import Path
|
|
2
|
+
from typing import List, Union
|
|
3
|
+
from .project import Project
|
|
4
|
+
|
|
5
|
+
class Vault:
|
|
6
|
+
"""
|
|
7
|
+
The central management system for machine learning storage.
|
|
8
|
+
|
|
9
|
+
The Vault acts as the root directory for all experiments, organizing data into
|
|
10
|
+
individual Projects. It handles the high-level filesystem structure and
|
|
11
|
+
provides access to project-specific tracking.
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
def __init__(self, path: Union[str, Path] = "vault"):
|
|
15
|
+
"""
|
|
16
|
+
Initializes the Vault at the specified filesystem location.
|
|
17
|
+
|
|
18
|
+
Args:
|
|
19
|
+
path (Union[str, Path]): The root directory for the vault.
|
|
20
|
+
Defaults to "vault".
|
|
21
|
+
"""
|
|
22
|
+
self.path = Path(path)
|
|
23
|
+
self.path.mkdir(parents=True, exist_ok=True)
|
|
24
|
+
|
|
25
|
+
def get_project(self, name: str) -> Project:
|
|
26
|
+
"""
|
|
27
|
+
Retrieves an existing project or initializes a new one.
|
|
28
|
+
|
|
29
|
+
Args:
|
|
30
|
+
name (str): The unique name of the project. This will correspond
|
|
31
|
+
to a subdirectory within the vault.
|
|
32
|
+
|
|
33
|
+
Returns:
|
|
34
|
+
Project: An initialized Project instance tied to the specified name.
|
|
35
|
+
"""
|
|
36
|
+
project_path = self.path / name
|
|
37
|
+
return Project(project_path)
|
|
38
|
+
|
|
39
|
+
def list_projects(self) -> List[str]:
|
|
40
|
+
"""
|
|
41
|
+
Scans the vault directory and lists all identified projects.
|
|
42
|
+
|
|
43
|
+
A directory is considered a project if it exists directly within
|
|
44
|
+
the vault's root path.
|
|
45
|
+
|
|
46
|
+
Returns:
|
|
47
|
+
List[str]: A list of project names (directory names).
|
|
48
|
+
"""
|
|
49
|
+
return [d.name for d in self.path.iterdir() if d.is_dir()]
|
|
50
|
+
|
|
51
|
+
def __repr__(self) -> str:
|
|
52
|
+
"""Returns a string representation of the Vault instance."""
|
|
53
|
+
return f"<useml.Vault path='{self.path.absolute()}' projects={len(self.list_projects())}>"
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
import datetime
|
|
2
|
+
import importlib.metadata
|
|
3
|
+
|
|
4
|
+
from typing import Any, List, Optional
|
|
5
|
+
from pathlib import Path
|
|
6
|
+
|
|
7
|
+
from .snapshot import Snapshot
|
|
8
|
+
|
|
9
|
+
class Project:
|
|
10
|
+
"""
|
|
11
|
+
Manages a collection of snapshots within a specific experiment or model category.
|
|
12
|
+
|
|
13
|
+
A Project acts as a subdirectory within the Vault, responsible for versioning
|
|
14
|
+
model weights and maintaining a chronological log of commits.
|
|
15
|
+
"""
|
|
16
|
+
|
|
17
|
+
def __init__(self, path: Path):
|
|
18
|
+
"""
|
|
19
|
+
Initializes the Project instance.
|
|
20
|
+
|
|
21
|
+
Args:
|
|
22
|
+
path (Path): The filesystem path where project snapshots are stored.
|
|
23
|
+
"""
|
|
24
|
+
self.path = path
|
|
25
|
+
self.path.mkdir(parents=True, exist_ok=True)
|
|
26
|
+
|
|
27
|
+
def commit(
|
|
28
|
+
self,
|
|
29
|
+
model: Any,
|
|
30
|
+
message: str,
|
|
31
|
+
optimizer: Optional[Any] = None,
|
|
32
|
+
**user_metadata: Any
|
|
33
|
+
) -> Snapshot:
|
|
34
|
+
"""
|
|
35
|
+
Records the current state of a model as a new snapshot.
|
|
36
|
+
|
|
37
|
+
This method generates a unique snapshot ID based on the current timestamp,
|
|
38
|
+
collects system manifest data (versioning, timing), and delegates the
|
|
39
|
+
saving process to the Snapshot class.
|
|
40
|
+
|
|
41
|
+
Args:
|
|
42
|
+
model: The PyTorch model (state_dict) to save.
|
|
43
|
+
message (str): A descriptive message for this commit.
|
|
44
|
+
optimizer (Optional[Any]): Optional optimizer state to preserve.
|
|
45
|
+
**user_metadata: Arbitrary keyword arguments to store as experiment metrics.
|
|
46
|
+
|
|
47
|
+
Returns:
|
|
48
|
+
Snapshot: The newly created snapshot instance.
|
|
49
|
+
"""
|
|
50
|
+
# Microseconds (%f) are included to prevent ID collisions during rapid commits
|
|
51
|
+
timestamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S_%f")
|
|
52
|
+
snap_id = f"snap_{timestamp}"
|
|
53
|
+
snap_path = self.path / snap_id
|
|
54
|
+
|
|
55
|
+
# Dynamically fetch the framework version
|
|
56
|
+
try:
|
|
57
|
+
version = importlib.metadata.version("useml")
|
|
58
|
+
except importlib.metadata.PackageNotFoundError:
|
|
59
|
+
version = "unknown"
|
|
60
|
+
|
|
61
|
+
# System-level information
|
|
62
|
+
manifest = {
|
|
63
|
+
"message": message,
|
|
64
|
+
"timestamp": timestamp,
|
|
65
|
+
"framework_version": version,
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
snapshot = Snapshot.create_new(snap_path)
|
|
69
|
+
snapshot.save(model, optimizer, manifest, user_metadata)
|
|
70
|
+
return snapshot
|
|
71
|
+
|
|
72
|
+
def log(self) -> List[Snapshot]:
|
|
73
|
+
"""
|
|
74
|
+
Retrieves the history of snapshots in the project.
|
|
75
|
+
|
|
76
|
+
The list is sorted chronologically, with the most recent snapshot at index 0.
|
|
77
|
+
|
|
78
|
+
Returns:
|
|
79
|
+
List[Snapshot]: A list of Snapshot instances found in the project directory.
|
|
80
|
+
"""
|
|
81
|
+
snapshots = [
|
|
82
|
+
Snapshot(d) for d in self.path.iterdir()
|
|
83
|
+
if d.is_dir() and (d / "weights.pth").exists()
|
|
84
|
+
]
|
|
85
|
+
|
|
86
|
+
# Sort by creation time, descending
|
|
87
|
+
snapshots.sort(key=lambda x: x.path.stat().st_ctime, reverse=True)
|
|
88
|
+
return snapshots
|
|
89
|
+
|
|
90
|
+
def __getitem__(self, index: int) -> Snapshot:
|
|
91
|
+
"""
|
|
92
|
+
Provides direct access to snapshots using list-like indexing.
|
|
93
|
+
|
|
94
|
+
Args:
|
|
95
|
+
index (int): The index of the snapshot (0 for the latest).
|
|
96
|
+
|
|
97
|
+
Returns:
|
|
98
|
+
Snapshot: The requested snapshot.
|
|
99
|
+
|
|
100
|
+
Raises:
|
|
101
|
+
IndexError: If the index is out of range.
|
|
102
|
+
"""
|
|
103
|
+
return self.log()[index]
|
|
104
|
+
|
|
105
|
+
def __len__(self) -> int:
|
|
106
|
+
"""Returns the total number of valid snapshots in the project."""
|
|
107
|
+
return len(self.log())
|
|
108
|
+
|
|
109
|
+
def __repr__(self) -> str:
|
|
110
|
+
return f"<useml.Project name='{self.path.name}' snapshots={len(self)}>"
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
import torch
|
|
2
|
+
import yaml
|
|
3
|
+
|
|
4
|
+
from pathlib import Path
|
|
5
|
+
from typing import Any, Dict, Optional, Union
|
|
6
|
+
|
|
7
|
+
class Snapshot:
|
|
8
|
+
"""
|
|
9
|
+
Represents a point-in-time record of a model's state and associated metadata.
|
|
10
|
+
|
|
11
|
+
A Snapshot is a directory containing the serialized model weights (pth) and
|
|
12
|
+
configuration files (yaml). It supports lazy loading of metadata to optimize
|
|
13
|
+
memory usage when browsing project history.
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
def __init__(self, path: Union[str, Path]):
|
|
17
|
+
"""
|
|
18
|
+
Initializes a Snapshot instance from an existing directory.
|
|
19
|
+
|
|
20
|
+
Args:
|
|
21
|
+
path (Union[str, Path]): The directory containing snapshot files.
|
|
22
|
+
"""
|
|
23
|
+
self.path = Path(path)
|
|
24
|
+
self._manifest: Optional[Dict[str, Any]] = None
|
|
25
|
+
self._metadata: Optional[Dict[str, Any]] = None
|
|
26
|
+
|
|
27
|
+
@classmethod
|
|
28
|
+
def create_new(cls, path: Path) -> "Snapshot":
|
|
29
|
+
"""
|
|
30
|
+
Creates a new snapshot directory on disk and returns the instance.
|
|
31
|
+
|
|
32
|
+
Args:
|
|
33
|
+
path (Path): The destination directory for the new snapshot.
|
|
34
|
+
|
|
35
|
+
Returns:
|
|
36
|
+
Snapshot: An initialized Snapshot instance.
|
|
37
|
+
"""
|
|
38
|
+
path.mkdir(parents=True, exist_ok=True)
|
|
39
|
+
return cls(path)
|
|
40
|
+
|
|
41
|
+
def save(
|
|
42
|
+
self,
|
|
43
|
+
model: Any,
|
|
44
|
+
optimizer: Optional[Any],
|
|
45
|
+
manifest: Dict[str, Any],
|
|
46
|
+
metadata: Dict[str, Any]
|
|
47
|
+
) -> None:
|
|
48
|
+
"""
|
|
49
|
+
Serializes model weights and configuration to the snapshot directory.
|
|
50
|
+
|
|
51
|
+
Args:
|
|
52
|
+
model: The PyTorch model to save.
|
|
53
|
+
optimizer: Optional PyTorch optimizer to save.
|
|
54
|
+
manifest (Dict): System-level data (e.g., version, git hash).
|
|
55
|
+
metadata (Dict): User-defined metrics and hyperparameters.
|
|
56
|
+
"""
|
|
57
|
+
# 1. Save binary weights
|
|
58
|
+
torch.save(model.state_dict(), self.path / "weights.pth")
|
|
59
|
+
|
|
60
|
+
# 2. Save optimizer state if provided
|
|
61
|
+
if optimizer is not None:
|
|
62
|
+
torch.save(optimizer.state_dict(), self.path / "optimizer.pth")
|
|
63
|
+
|
|
64
|
+
# 3. Save configuration files using YAML for human readability
|
|
65
|
+
save_params = {"default_flow_style": False, "sort_keys": False}
|
|
66
|
+
|
|
67
|
+
with open(self.path / "manifest.yaml", "w") as f:
|
|
68
|
+
yaml.safe_dump(manifest, f, **save_params)
|
|
69
|
+
|
|
70
|
+
with open(self.path / "metadata.yaml", "w") as f:
|
|
71
|
+
yaml.safe_dump(metadata, f, **save_params)
|
|
72
|
+
|
|
73
|
+
def _load_data(self) -> None:
|
|
74
|
+
"""
|
|
75
|
+
Internal method to lazy-load YAML files into memory.
|
|
76
|
+
|
|
77
|
+
This prevents unnecessary I/O when snapshots are listed but their
|
|
78
|
+
metadata is not yet accessed.
|
|
79
|
+
"""
|
|
80
|
+
if self._manifest is None:
|
|
81
|
+
# Load manifest
|
|
82
|
+
manifest_path = self.path / "manifest.yaml"
|
|
83
|
+
if manifest_path.exists():
|
|
84
|
+
with open(manifest_path, "r") as f:
|
|
85
|
+
self._manifest = yaml.safe_load(f) or {}
|
|
86
|
+
else:
|
|
87
|
+
self._manifest = {}
|
|
88
|
+
|
|
89
|
+
# Load user metadata
|
|
90
|
+
metadata_path = self.path / "metadata.yaml"
|
|
91
|
+
if metadata_path.exists():
|
|
92
|
+
with open(metadata_path, "r") as f:
|
|
93
|
+
self._metadata = yaml.safe_load(f) or {}
|
|
94
|
+
else:
|
|
95
|
+
self._metadata = {}
|
|
96
|
+
|
|
97
|
+
def __getitem__(self, key: str) -> Any:
|
|
98
|
+
"""
|
|
99
|
+
Accesses manifest or metadata values using key indexing.
|
|
100
|
+
|
|
101
|
+
Priority is given to the system manifest, then user metadata.
|
|
102
|
+
|
|
103
|
+
Args:
|
|
104
|
+
key (str): The metadata or manifest key to retrieve.
|
|
105
|
+
|
|
106
|
+
Returns:
|
|
107
|
+
Any: The value associated with the key, or None if not found.
|
|
108
|
+
"""
|
|
109
|
+
self._load_data()
|
|
110
|
+
if self._manifest and key in self._manifest:
|
|
111
|
+
return self._manifest[key]
|
|
112
|
+
return self._metadata.get(key) if self._metadata else None
|
|
113
|
+
|
|
114
|
+
def load_weights(self, model: Any) -> None:
|
|
115
|
+
"""
|
|
116
|
+
Loads the saved weights into the provided model instance.
|
|
117
|
+
|
|
118
|
+
Args:
|
|
119
|
+
model: The PyTorch model to update with saved weights.
|
|
120
|
+
"""
|
|
121
|
+
weights_path = self.path / "weights.pth"
|
|
122
|
+
if not weights_path.exists():
|
|
123
|
+
raise FileNotFoundError(f"No weights.pth found in {self.path}")
|
|
124
|
+
|
|
125
|
+
model.load_state_dict(
|
|
126
|
+
torch.load(weights_path, map_location="cpu", weights_only=True)
|
|
127
|
+
)
|
|
128
|
+
|
|
129
|
+
def __repr__(self) -> str:
|
|
130
|
+
return f"<useml.Snapshot id='{self.path.name}'>"
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: useml
|
|
3
|
+
Version: 0.0.2
|
|
4
|
+
Summary: Simplifying PyTorch workflows: Pipeline, Versioning, and Vault.
|
|
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: tqdm>=4.65.0
|
|
12
|
+
Requires-Dist: numpy>=1.24.0
|
|
13
|
+
Provides-Extra: dev
|
|
14
|
+
Requires-Dist: pytest>=7.0.0; extra == "dev"
|
|
15
|
+
Requires-Dist: build; extra == "dev"
|
|
16
|
+
Requires-Dist: twine; extra == "dev"
|
|
17
|
+
Requires-Dist: black; extra == "dev"
|
|
18
|
+
|
|
19
|
+
# useml
|
|
20
|
+
|
|
21
|
+
**Stop coding plumbing, start training models.**
|
|
22
|
+
|
|
23
|
+
`useml` is a minimalist framework for PyTorch designed to eliminate the 90% of software engineering overhead in Machine Learning projects. It handles pipelines, versioning, and environment sealing so you can focus on the architecture.
|
|
24
|
+
|
|
25
|
+
## Key Features
|
|
26
|
+
|
|
27
|
+
* **AtomicData**: Type-safe data structures for PyTorch.
|
|
28
|
+
* **Auto-Versioning**: Every run is automatically linked to a Git commit and config snapshot.
|
|
29
|
+
* **The Vault**: Seal your model, schema, and weights into a single, portable artifact.
|
|
30
|
+
* **Zero Friction**: If it doesn't simplify your code, it doesn't belong in `useml`.
|
|
31
|
+
|
|
32
|
+
### Basic Usage
|
|
33
|
+
|
|
34
|
+
```python
|
|
35
|
+
import torch
|
|
36
|
+
from useml import Vault
|
|
37
|
+
|
|
38
|
+
# 1. Initialize your vault (the root storage)
|
|
39
|
+
vault = Vault(path="my_vault")
|
|
40
|
+
|
|
41
|
+
# 2. Get or create a specific Project
|
|
42
|
+
project = vault.get_project("mnist_classifier")
|
|
43
|
+
|
|
44
|
+
# 3. Define your model
|
|
45
|
+
model = torch.nn.Linear(10, 2)
|
|
46
|
+
|
|
47
|
+
# 4. Commit your progress
|
|
48
|
+
# This saves: weights.pth + manifest.yaml + metadata.yaml
|
|
49
|
+
project.commit(model, message="Initial baseline", lr=1e-3, accuracy=0.92)
|
|
50
|
+
|
|
51
|
+
# 5. List project history (newest first)
|
|
52
|
+
for snap in project.log():
|
|
53
|
+
print(f"[{snap['timestamp']}] {snap['message']} | Acc: {snap['accuracy']}")
|
|
54
|
+
|
|
55
|
+
# 6. Restore weights from the latest snapshot
|
|
56
|
+
latest = project[0]
|
|
57
|
+
latest.load_weights(model)
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## Installation
|
|
61
|
+
```bash
|
|
62
|
+
pip install useml
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Why useml?
|
|
66
|
+
Most ML projects fail because of "hidden technical debt" in the pipeline. useml enforces a clean structure from the first line of code, ensuring that every experiment you run is 100% reproducible and deployable.
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
## Development & Testing
|
|
70
|
+
|
|
71
|
+
If you want to contribute or test the framework, follow these steps.
|
|
72
|
+
|
|
73
|
+
### 1. Install for development
|
|
74
|
+
Clone the repo and install it in editable mode with dev dependencies:
|
|
75
|
+
```bash
|
|
76
|
+
pip install -e ".[dev]"
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
### 2. Running Tests
|
|
80
|
+
We use pytest for unit testing. The tests are located in the tests/ directory.
|
|
81
|
+
To run the full suite:
|
|
82
|
+
```bash
|
|
83
|
+
pytest -vv
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
### 3. Build & Publish
|
|
87
|
+
**Update Version**: Increment version in `pyproject.toml`.
|
|
88
|
+
|
|
89
|
+
Build the package:
|
|
90
|
+
```bash
|
|
91
|
+
rm -rf dist/ build/ *.egg-info
|
|
92
|
+
python3 -m build
|
|
93
|
+
twine check dist/*
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Upload the new package version:
|
|
97
|
+
```bash
|
|
98
|
+
twine upload dist/*
|
|
99
|
+
```
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
README.md
|
|
2
|
+
pyproject.toml
|
|
3
|
+
tests/test_vault.py
|
|
4
|
+
useml/__init__.py
|
|
5
|
+
useml.egg-info/PKG-INFO
|
|
6
|
+
useml.egg-info/SOURCES.txt
|
|
7
|
+
useml.egg-info/dependency_links.txt
|
|
8
|
+
useml.egg-info/requires.txt
|
|
9
|
+
useml.egg-info/top_level.txt
|
|
10
|
+
useml/vault/core.py
|
|
11
|
+
useml/vault/project.py
|
|
12
|
+
useml/vault/snapshot.py
|
useml-0.0.1/PKG-INFO
DELETED
|
@@ -1,41 +0,0 @@
|
|
|
1
|
-
Metadata-Version: 2.4
|
|
2
|
-
Name: useml
|
|
3
|
-
Version: 0.0.1
|
|
4
|
-
Summary: Simplifying PyTorch workflows: Pipeline, Versioning, and Vault.
|
|
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
|
-
|
|
11
|
-
# useml
|
|
12
|
-
|
|
13
|
-
**Stop coding plumbing, start training models.**
|
|
14
|
-
|
|
15
|
-
`useml` is a minimalist framework for PyTorch designed to eliminate the 90% of software engineering overhead in Machine Learning projects. It handles pipelines, versioning, and environment sealing so you can focus on the architecture.
|
|
16
|
-
|
|
17
|
-
## Key Features
|
|
18
|
-
|
|
19
|
-
* **AtomicData**: Type-safe data structures for PyTorch.
|
|
20
|
-
* **Auto-Versioning**: Every run is automatically linked to a Git commit and config snapshot.
|
|
21
|
-
* **The Vault**: Seal your model, schema, and weights into a single, portable artifact.
|
|
22
|
-
* **Zero Friction**: If it doesn't simplify your code, it doesn't belong in `useml`.
|
|
23
|
-
|
|
24
|
-
## Quick Start
|
|
25
|
-
|
|
26
|
-
```python
|
|
27
|
-
import useml
|
|
28
|
-
|
|
29
|
-
# Your logic here
|
|
30
|
-
# trainer = useml.Trainer(model, schema)
|
|
31
|
-
# trainer.train(loader)
|
|
32
|
-
```
|
|
33
|
-
|
|
34
|
-
## Installation
|
|
35
|
-
```bash
|
|
36
|
-
pip install useml
|
|
37
|
-
```
|
|
38
|
-
|
|
39
|
-
## Why useml?
|
|
40
|
-
Most ML projects fail because of "hidden technical debt" in the pipeline. useml enforces a clean structure from the first line of code, ensuring that every experiment you run is 100% reproducible and deployable.
|
|
41
|
-
|
useml-0.0.1/README.md
DELETED
|
@@ -1,31 +0,0 @@
|
|
|
1
|
-
# useml
|
|
2
|
-
|
|
3
|
-
**Stop coding plumbing, start training models.**
|
|
4
|
-
|
|
5
|
-
`useml` is a minimalist framework for PyTorch designed to eliminate the 90% of software engineering overhead in Machine Learning projects. It handles pipelines, versioning, and environment sealing so you can focus on the architecture.
|
|
6
|
-
|
|
7
|
-
## Key Features
|
|
8
|
-
|
|
9
|
-
* **AtomicData**: Type-safe data structures for PyTorch.
|
|
10
|
-
* **Auto-Versioning**: Every run is automatically linked to a Git commit and config snapshot.
|
|
11
|
-
* **The Vault**: Seal your model, schema, and weights into a single, portable artifact.
|
|
12
|
-
* **Zero Friction**: If it doesn't simplify your code, it doesn't belong in `useml`.
|
|
13
|
-
|
|
14
|
-
## Quick Start
|
|
15
|
-
|
|
16
|
-
```python
|
|
17
|
-
import useml
|
|
18
|
-
|
|
19
|
-
# Your logic here
|
|
20
|
-
# trainer = useml.Trainer(model, schema)
|
|
21
|
-
# trainer.train(loader)
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
## Installation
|
|
25
|
-
```bash
|
|
26
|
-
pip install useml
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
## Why useml?
|
|
30
|
-
Most ML projects fail because of "hidden technical debt" in the pipeline. useml enforces a clean structure from the first line of code, ensuring that every experiment you run is 100% reproducible and deployable.
|
|
31
|
-
|
useml-0.0.1/useml/__init__.py
DELETED
|
File without changes
|
|
@@ -1,41 +0,0 @@
|
|
|
1
|
-
Metadata-Version: 2.4
|
|
2
|
-
Name: useml
|
|
3
|
-
Version: 0.0.1
|
|
4
|
-
Summary: Simplifying PyTorch workflows: Pipeline, Versioning, and Vault.
|
|
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
|
-
|
|
11
|
-
# useml
|
|
12
|
-
|
|
13
|
-
**Stop coding plumbing, start training models.**
|
|
14
|
-
|
|
15
|
-
`useml` is a minimalist framework for PyTorch designed to eliminate the 90% of software engineering overhead in Machine Learning projects. It handles pipelines, versioning, and environment sealing so you can focus on the architecture.
|
|
16
|
-
|
|
17
|
-
## Key Features
|
|
18
|
-
|
|
19
|
-
* **AtomicData**: Type-safe data structures for PyTorch.
|
|
20
|
-
* **Auto-Versioning**: Every run is automatically linked to a Git commit and config snapshot.
|
|
21
|
-
* **The Vault**: Seal your model, schema, and weights into a single, portable artifact.
|
|
22
|
-
* **Zero Friction**: If it doesn't simplify your code, it doesn't belong in `useml`.
|
|
23
|
-
|
|
24
|
-
## Quick Start
|
|
25
|
-
|
|
26
|
-
```python
|
|
27
|
-
import useml
|
|
28
|
-
|
|
29
|
-
# Your logic here
|
|
30
|
-
# trainer = useml.Trainer(model, schema)
|
|
31
|
-
# trainer.train(loader)
|
|
32
|
-
```
|
|
33
|
-
|
|
34
|
-
## Installation
|
|
35
|
-
```bash
|
|
36
|
-
pip install useml
|
|
37
|
-
```
|
|
38
|
-
|
|
39
|
-
## Why useml?
|
|
40
|
-
Most ML projects fail because of "hidden technical debt" in the pipeline. useml enforces a clean structure from the first line of code, ensuring that every experiment you run is 100% reproducible and deployable.
|
|
41
|
-
|
|
File without changes
|
|
File without changes
|
|
File without changes
|