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 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.1"
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,6 @@
1
+ # useml/__init__.py
2
+
3
+ # Relative import to pull Vault from the sub-package
4
+ from .vault.core import Vault
5
+
6
+ __all__ = ["Vault"]
@@ -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
@@ -0,0 +1,9 @@
1
+ torch>=2.0.0
2
+ tqdm>=4.65.0
3
+ numpy>=1.24.0
4
+
5
+ [dev]
6
+ pytest>=7.0.0
7
+ build
8
+ twine
9
+ black
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
-
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
-
@@ -1,7 +0,0 @@
1
- README.md
2
- pyproject.toml
3
- useml/__init__.py
4
- useml.egg-info/PKG-INFO
5
- useml.egg-info/SOURCES.txt
6
- useml.egg-info/dependency_links.txt
7
- useml.egg-info/top_level.txt
File without changes