useml 0.3.2__tar.gz → 1.0.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.
Potentially problematic release.
This version of useml might be problematic. Click here for more details.
- useml-1.0.0/.gitignore +5 -0
- useml-1.0.0/DESIGN.md +222 -0
- useml-1.0.0/LICENSE +21 -0
- useml-1.0.0/PKG-INFO +242 -0
- useml-1.0.0/README.md +204 -0
- useml-1.0.0/pyproject.toml +52 -0
- useml-1.0.0/src/useml/__init__.py +42 -0
- useml-1.0.0/src/useml/__main__.py +5 -0
- useml-1.0.0/src/useml/_progress.py +90 -0
- useml-1.0.0/src/useml/_project.py +45 -0
- useml-1.0.0/src/useml/_setup.py +470 -0
- useml-1.0.0/src/useml/cli.py +473 -0
- useml-1.0.0/src/useml/config/__init__.py +127 -0
- useml-1.0.0/src/useml/config/_config.py +201 -0
- useml-1.0.0/src/useml/config/_git.py +81 -0
- useml-1.0.0/src/useml/config/_library.py +357 -0
- useml-1.0.0/src/useml/config/_types.py +111 -0
- useml-1.0.0/src/useml/config/_write.py +248 -0
- useml-1.0.0/src/useml/data/__init__.py +39 -0
- useml-1.0.0/src/useml/data/_catalog.py +148 -0
- useml-1.0.0/src/useml/data/_jobs.py +227 -0
- useml-1.0.0/src/useml/data/_keys.py +53 -0
- useml-1.0.0/src/useml/data/_processor.py +151 -0
- useml-1.0.0/src/useml/data/_run.py +240 -0
- useml-1.0.0/src/useml/data/_sources.py +218 -0
- useml-1.0.0/src/useml/data/_table.py +288 -0
- useml-1.0.0/src/useml/data/_view.py +138 -0
- useml-1.0.0/src/useml/exp/__init__.py +28 -0
- useml-1.0.0/src/useml/exp/_bundle.py +421 -0
- useml-1.0.0/src/useml/exp/_experience.py +472 -0
- useml-1.0.0/src/useml/exp/_launch.py +222 -0
- useml-1.0.0/src/useml/exp/_outputs.py +162 -0
- useml-1.0.0/src/useml/exp/_provenance.py +159 -0
- useml-1.0.0/src/useml/exp/_refs.py +242 -0
- useml-1.0.0/src/useml/exp/_runtime.py +303 -0
- useml-1.0.0/src/useml/exp/_supervise.py +252 -0
- useml-1.0.0/src/useml/hub/__init__.py +23 -0
- useml-1.0.0/src/useml/hub/_fetch.py +321 -0
- useml-1.0.0/src/useml/hub/_policy.py +377 -0
- useml-1.0.0/src/useml/hub/_registry.py +115 -0
- useml-1.0.0/src/useml/hub/_scan.py +107 -0
- useml-1.0.0/src/useml/hub/_watch.py +157 -0
- useml-1.0.0/src/useml/paths.py +331 -0
- useml-1.0.0/src/useml/store/__init__.py +65 -0
- useml-1.0.0/src/useml/store/_maintenance.py +253 -0
- useml-1.0.0/src/useml/store/_spaces.py +67 -0
- useml-1.0.0/src/useml/store/_store.py +676 -0
- useml-1.0.0/tests/conftest.py +47 -0
- useml-1.0.0/tests/data_procs.py +54 -0
- useml-1.0.0/tests/exp_steps.py +117 -0
- useml-1.0.0/tests/test_config.py +389 -0
- useml-1.0.0/tests/test_data.py +302 -0
- useml-1.0.0/tests/test_exp.py +228 -0
- useml-1.0.0/tests/test_exp_robust.py +276 -0
- useml-1.0.0/tests/test_fetch.py +179 -0
- useml-1.0.0/tests/test_paths.py +97 -0
- useml-1.0.0/tests/test_policy.py +200 -0
- useml-1.0.0/tests/test_setup.py +167 -0
- useml-1.0.0/tests/test_store.py +342 -0
- useml-0.3.2/PKG-INFO +0 -471
- useml-0.3.2/README.md +0 -454
- useml-0.3.2/pyproject.toml +0 -30
- useml-0.3.2/setup.cfg +0 -4
- useml-0.3.2/tests/test_bundle.py +0 -366
- useml-0.3.2/tests/test_level2.py +0 -244
- useml-0.3.2/tests/test_session.py +0 -208
- useml-0.3.2/tests/test_train_level0.py +0 -234
- useml-0.3.2/tests/test_usecases.py +0 -1249
- useml-0.3.2/tests/test_vault.py +0 -243
- useml-0.3.2/useml/__init__.py +0 -94
- useml-0.3.2/useml/dataset/__init__.py +0 -4
- useml-0.3.2/useml/dataset/bundle.py +0 -288
- useml-0.3.2/useml/dataset/loaders.py +0 -168
- useml-0.3.2/useml/errors.py +0 -377
- useml-0.3.2/useml/imports.py +0 -215
- useml-0.3.2/useml/session/__init__.py +0 -4
- useml-0.3.2/useml/session/component.py +0 -59
- useml-0.3.2/useml/session/manager.py +0 -482
- useml-0.3.2/useml/template/__init__.py +0 -6
- useml-0.3.2/useml/template/config.py +0 -140
- useml-0.3.2/useml/template/loss.py +0 -28
- useml-0.3.2/useml/template/model.py +0 -28
- useml-0.3.2/useml/template/trainer.py +0 -758
- useml-0.3.2/useml/vault/__init__.py +0 -5
- useml-0.3.2/useml/vault/code_extractor.py +0 -261
- useml-0.3.2/useml/vault/core.py +0 -63
- useml-0.3.2/useml/vault/model_registry.py +0 -267
- useml-0.3.2/useml/vault/project.py +0 -309
- useml-0.3.2/useml/vault/runs.py +0 -814
- useml-0.3.2/useml/vault/snapshot.py +0 -170
- useml-0.3.2/useml/workdir/__init__.py +0 -14
- useml-0.3.2/useml/workdir/_hook.py +0 -79
- useml-0.3.2/useml.egg-info/PKG-INFO +0 -471
- useml-0.3.2/useml.egg-info/SOURCES.txt +0 -36
- useml-0.3.2/useml.egg-info/dependency_links.txt +0 -1
- useml-0.3.2/useml.egg-info/requires.txt +0 -8
- useml-0.3.2/useml.egg-info/top_level.txt +0 -1
useml-1.0.0/.gitignore
ADDED
useml-1.0.0/DESIGN.md
ADDED
|
@@ -0,0 +1,222 @@
|
|
|
1
|
+
# useml v1 — proposition d'architecture
|
|
2
|
+
|
|
3
|
+
Rédigé le 2026-11-18, à partir du code de Pipeline-T2I et de useml 0.3.2 (PyPI).
|
|
4
|
+
|
|
5
|
+
## 1. Ce qui existe aujourd'hui
|
|
6
|
+
|
|
7
|
+
Quatre systèmes de Pipeline-T2I sont à extraire. Chacun est utile, et chacun dépend du dépôt.
|
|
8
|
+
|
|
9
|
+
| Système | Où dans Pipeline-T2I | Lignes | Dépendance au projet |
|
|
10
|
+
|---|---|---|---|
|
|
11
|
+
| Racines des caches | `cache_location.py` | 310 | lit `.cache_root` à la racine du dépôt |
|
|
12
|
+
| Store de cache | `pipeline_cache/` | ≈ 3 400 | liste d'espaces écrite en dur (`spaces.py`) |
|
|
13
|
+
| Features gelées | `model_api/gmti/edges/modeling/feature_store.py`, `training/packed.py` | ≈ 1 300 | clés propres aux arêtes |
|
|
14
|
+
| Téléchargements | `data_api/downloads.py`, `data_api/config.py` | ≈ 530 | journal écrit dans `logs/` du dépôt |
|
|
15
|
+
| Configs | `src/project/config/` | ≈ 1 100 | cherche `configs/` en remontant |
|
|
16
|
+
| Expériences | `src/project/experience/` (v1 et v2) | ≈ 4 900 | handlers `evaluate`, `train`, `edge` du projet |
|
|
17
|
+
|
|
18
|
+
useml 0.3.2 contient autre chose : un « vault » (dossier de projets), des runs, des snapshots
|
|
19
|
+
du code, un registre de modèles, un template de trainer. Deux idées valent d'être gardées :
|
|
20
|
+
le snapshot du code au lancement d'un run, et le registre des modèles entraînés.
|
|
21
|
+
|
|
22
|
+
## 2. Le problème central : les données traitées
|
|
23
|
+
|
|
24
|
+
Définitions, avec un exemple.
|
|
25
|
+
|
|
26
|
+
- Dataset brut : les fichiers d'origine. Exemple : les 108 000 images de Visual Genome (VG)
|
|
27
|
+
et leurs annotations.
|
|
28
|
+
- Processeur : une fonction qui transforme un dataset brut. Exemple : « encoder chaque image
|
|
29
|
+
avec SigLIP-B/16 à 224 pixels ».
|
|
30
|
+
- Dataset traité : le résultat d'un processeur sur un dataset. Exemple : un vecteur de 768
|
|
31
|
+
nombres par image de VG.
|
|
32
|
+
- Empreinte : un hash court qui identifie de façon unique (dataset, processeur, réglages).
|
|
33
|
+
Deux calculs avec la même empreinte donnent le même résultat.
|
|
34
|
+
|
|
35
|
+
Aujourd'hui, le traitement a lieu dans l'expérience. Conséquence : chaque expérience qui
|
|
36
|
+
change un détail relance le traitement. VG et SVG ont été encodés des dizaines de fois avec
|
|
37
|
+
SigLIP et CLIP.
|
|
38
|
+
|
|
39
|
+
Trois sources de gaspillage, visibles dans le code.
|
|
40
|
+
|
|
41
|
+
1. Le même calcul est stocké plusieurs fois. `FrozenFeatureStore` le dit lui-même : deux
|
|
42
|
+
runs en parallèle écrivent chacun leurs shards, « a key computed twice is simply stored
|
|
43
|
+
twice ». Un namespace existe par réglage, donc changer un réglage recalcule tout.
|
|
44
|
+
2. On stocke un dérivé au lieu de la source. Avec `object_pooling="map_grid"`, chaque objet
|
|
45
|
+
garde une grille de G×G cellules de D+1 nombres. Pour SigLIP-B (D = 768) et G = 4 :
|
|
46
|
+
16 × 769 = 12 304 nombres par objet. VG a 2,8 millions d'objets, donc
|
|
47
|
+
2,8 M × 12 304 × 2 octets (float16) ≈ 69 Go, ou 138 Go en float32 (le chiffre que donne
|
|
48
|
+
`packed.py`). Or ces grilles sont lues dans la carte de patchs de l'image entière.
|
|
49
|
+
Stocker la carte une fois par image coûte 196 patchs × 768 × 2 octets ≈ 0,3 Mo par
|
|
50
|
+
image, soit ≈ 33 Go pour VG. Et la carte sert pour tout G, tout masque, tout pooling.
|
|
51
|
+
3. Les images partagées entre datasets sont encodées deux fois. SVG réutilise des images
|
|
52
|
+
de VG et de COCO (`sources/svg.py`). Une clé par contenu d'image (hash des pixels ou du
|
|
53
|
+
fichier) éviterait ce double calcul.
|
|
54
|
+
|
|
55
|
+
Attention : la carte de patchs n'est pas toujours petite. SigLIP so400m à 384 pixels donne
|
|
56
|
+
27 × 27 = 729 patchs de 1 152 nombres, soit ≈ 1,7 Mo par image en float16 et ≈ 181 Go pour
|
|
57
|
+
VG. C'est l'ordre de grandeur des 100 à 200 Go observés. D'où les leviers de la section 4.
|
|
58
|
+
|
|
59
|
+
## 3. Architecture proposée
|
|
60
|
+
|
|
61
|
+
Un paquet, cinq modules indépendants. Chaque module s'importe seul.
|
|
62
|
+
|
|
63
|
+
```
|
|
64
|
+
useml/
|
|
65
|
+
paths une racine par machine ; où va chaque cache
|
|
66
|
+
hub tous les téléchargements, et la politique réseau
|
|
67
|
+
store le cache clé → valeur (index SQLite + fichiers)
|
|
68
|
+
data datasets bruts, processeurs, datasets traités
|
|
69
|
+
config YAML → arbre d'objets, avec empreinte
|
|
70
|
+
exp expériences déclarées, lancées détachées, relues après
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Les dépendances vont dans un seul sens : `paths` ← `hub` ← `store` ← `data` ← `exp`.
|
|
74
|
+
`config` ne dépend que de `paths`. Ainsi, un projet peut n'utiliser que `hub`.
|
|
75
|
+
|
|
76
|
+
### 3.1 `useml.paths` — une racine par machine
|
|
77
|
+
|
|
78
|
+
Repris de `cache_location.py`. Un seul changement de fond : la racine ne se lit plus dans
|
|
79
|
+
le dépôt, mais dans un fichier de la machine.
|
|
80
|
+
|
|
81
|
+
```
|
|
82
|
+
~/.config/useml/config.toml # ou $USEML_HOME
|
|
83
|
+
root = "/datadisk4/enzo/useml"
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Sous cette racine :
|
|
87
|
+
|
|
88
|
+
```
|
|
89
|
+
<root>/hub/ poids et datasets téléchargés (HF_HOME, TORCH_HOME…)
|
|
90
|
+
<root>/data/ datasets traités
|
|
91
|
+
<root>/store/ le cache clé → valeur
|
|
92
|
+
<root>/tmp/ TMPDIR
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Toute la logique actuelle est gardée : ne jamais déplacer un cache déjà rempli, réaligner
|
|
96
|
+
`huggingface_hub` importé trop tôt, garder le jeton de connexion.
|
|
97
|
+
|
|
98
|
+
### 3.2 `useml.hub` — une seule porte pour télécharger
|
|
99
|
+
|
|
100
|
+
Repris de `data_api/downloads.py`, avec trois ajouts.
|
|
101
|
+
|
|
102
|
+
1. Une fonction unique : `useml.hub.get("hf://openai/clip-vit-large-patch14")`,
|
|
103
|
+
`get("gdrive://<id>")`, `get("https://…")`. Elle rend un chemin local. Les drivers ne
|
|
104
|
+
parlent plus à `snapshot_download`, `gdown` ou `urllib` directement.
|
|
105
|
+
2. Un registre : chaque téléchargement est noté (source, taille, date, dernier usage).
|
|
106
|
+
`useml hub ls` dit ce qui occupe le disque.
|
|
107
|
+
3. `useml hub scan` cherche les caches égarés (`~/.cache/huggingface`, `~/.cache/torch`…)
|
|
108
|
+
et propose de les déplacer sous la racine. Sur ce Mac, `~/.cache/huggingface` pèse 57 Go.
|
|
109
|
+
|
|
110
|
+
La politique « un seul fil réseau » est active par défaut, avec ses deux couches internes
|
|
111
|
+
(patch des pools de `huggingface_hub` et `datasets`, puis garde sur `socket.connect`).
|
|
112
|
+
On la lève explicitement : `useml.hub.allow_parallel()`. La troisième couche (le moniteur
|
|
113
|
+
externe, `scripts/network_monitor.py`) devient la commande `useml hub watch`.
|
|
114
|
+
|
|
115
|
+
### 3.3 `useml.store` — le cache clé → valeur
|
|
116
|
+
|
|
117
|
+
Repris de `pipeline_cache/store.py` presque tel quel : index SQLite en WAL, écriture
|
|
118
|
+
atomique, une écriture par clé, compteurs d'usage, classes de coût pour l'éviction.
|
|
119
|
+
|
|
120
|
+
Changement : les espaces ne sont plus une liste en dur. Un projet les déclare.
|
|
121
|
+
|
|
122
|
+
```python
|
|
123
|
+
store = useml.store.open() # <root>/store
|
|
124
|
+
scores = store.space("results/scores", cost="precious")
|
|
125
|
+
scores.put({"scorer": "clip", "dataset": "winoground"}, {"acc": 0.41})
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
### 3.4 `useml.data` — séparer le traitement des expériences
|
|
129
|
+
|
|
130
|
+
C'est le cœur de la v1. Une expérience ne traite plus rien. Elle charge soit un dataset
|
|
131
|
+
brut, soit un dataset traité, désigné par son nom.
|
|
132
|
+
|
|
133
|
+
```python
|
|
134
|
+
@useml.data.processor(version=1)
|
|
135
|
+
def siglip_patches(image, *, model="siglip-b16-224"):
|
|
136
|
+
... # rend un tableau (196, 768)
|
|
137
|
+
|
|
138
|
+
vg = useml.data.load("vg")
|
|
139
|
+
feats = useml.data.process(vg, siglip_patches, model="siglip-b16-224")
|
|
140
|
+
# calcule une seule fois ; les appels suivants relisent le disque
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
Règles.
|
|
144
|
+
|
|
145
|
+
- Clé par contenu. Une ligne est identifiée par le hash de son entrée (l'image), pas par
|
|
146
|
+
sa position dans le dataset. VG et SVG partagent donc les lignes de leurs images communes.
|
|
147
|
+
- Un dataset traité est immuable une fois fini. Il porte un manifeste : empreinte du
|
|
148
|
+
processeur, version, réglages, nombre de lignes, taille, date.
|
|
149
|
+
- Reprise après arrêt. Le calcul écrit des shards ; un arrêt laisse les shards finis.
|
|
150
|
+
Relancer ne calcule que les lignes manquantes.
|
|
151
|
+
- Un seul écrivain par dataset traité (un verrou fichier). Fini les doublons de deux runs
|
|
152
|
+
en parallèle.
|
|
153
|
+
- Estimation avant calcul : `process(..., dry_run=True)` rend lignes × dimension × octets,
|
|
154
|
+
et refuse si le budget disque est dépassé.
|
|
155
|
+
|
|
156
|
+
### 3.5 `useml.config` — repris de `src/project/config`
|
|
157
|
+
|
|
158
|
+
YAML → arbre de constructeurs (`type:`), références (`{ref: siglip2}`), surcharges, empreinte,
|
|
159
|
+
erreurs à la lecture. Changements : un registre de types (`useml.config.register(GMTI)`)
|
|
160
|
+
au lieu de l'import implicite, et des dossiers de configs déclarés par le projet au lieu
|
|
161
|
+
de `configs/` trouvé en remontant.
|
|
162
|
+
|
|
163
|
+
### 3.6 `useml.exp` — repris de `src/project/experience` v2
|
|
164
|
+
|
|
165
|
+
Gardé : le bloc qui enregistre des étapes au lieu de les exécuter, les références d'étapes,
|
|
166
|
+
les empreintes chaînées (changer une ligne ne refait que ce qui en dépend), le lancement
|
|
167
|
+
détaché sous tmux, `state.json`, le refus de relancer une expérience finie.
|
|
168
|
+
|
|
169
|
+
Changé : les handlers (`evaluate`, `train`, `edge_evaluate`…) sortent de la bibliothèque.
|
|
170
|
+
useml fournit la classe `Handler` ; Pipeline-T2I garde ses handlers et les enregistre.
|
|
171
|
+
Repris de useml 0.3 : le snapshot du code au lancement, pour savoir ce qui a tourné.
|
|
172
|
+
|
|
173
|
+
## 4. Leviers mémoire, du plus rentable au moins rentable
|
|
174
|
+
|
|
175
|
+
Les gains sont des estimations sur VG. Chacun reste à mesurer sur la machine du labo.
|
|
176
|
+
|
|
177
|
+
1. Calculer une fois. Une empreinte par (dataset, processeur, réglages) et une clé par
|
|
178
|
+
contenu. Gain : tous les recalculs et doublons actuels. C'est le levier principal.
|
|
179
|
+
2. Stocker la source, dériver le reste au chargement. Garder la carte de patchs par image ;
|
|
180
|
+
calculer les grilles d'objets, les poolings et les masques sur GPU au chargement. Ces
|
|
181
|
+
opérations coûtent peu devant un passage dans le ViT. Gain sur l'exemple de la
|
|
182
|
+
section 2 : 69 Go → 33 Go, et un seul stockage pour tous les réglages de pooling.
|
|
183
|
+
3. Quantifier en int8. Un entier de 8 bits par nombre, plus une échelle par ligne. C'est
|
|
184
|
+
deux fois moins que float16. L'erreur relative attendue est de l'ordre de 0,5 %. Pour des
|
|
185
|
+
features gelées, l'effet sur l'entraînement est à vérifier, mais il est souvent nul.
|
|
186
|
+
Option par processeur : `dtype="int8"`.
|
|
187
|
+
4. Réduire la carte de patchs. Moyenner 2 × 2 patchs voisins divise la taille par 4. Utile
|
|
188
|
+
quand la grille finale est petite (G = 4). Option du processeur.
|
|
189
|
+
5. Ne pas compresser les embeddings avec zstd : des flottants presque aléatoires se
|
|
190
|
+
compressent mal (gain de quelques %). Garder la compression pour les masques (RLE) et le
|
|
191
|
+
texte.
|
|
192
|
+
6. Index compact. Aujourd'hui, `FrozenFeatureStore` charge toutes les clés dans un dict
|
|
193
|
+
Python. Pour 3,7 millions de paires, cela coûte de l'ordre de quelques centaines de Mo de
|
|
194
|
+
RAM et un long temps d'ouverture. Un tableau trié de hashes + `searchsorted` coûte
|
|
195
|
+
16 octets par ligne, soit ≈ 60 Mo, et s'ouvre en mémoire mappée.
|
|
196
|
+
7. Budget et éviction. Un plafond par racine (`max_size = "450GB"`). Au-delà, éviction par
|
|
197
|
+
classe de coût puis par dernier accès, comme `gc` le fait déjà.
|
|
198
|
+
|
|
199
|
+
Exemple combiné, SigLIP so400m à 384 pixels sur VG : 181 Go en float16 (section 2), 90 Go
|
|
200
|
+
en int8, ≈ 24 Go en int8 avec un pooling 2 × 2 (27 × 27 patchs → 14 × 14). Et ce stockage est fait une fois, pas une
|
|
201
|
+
fois par expérience.
|
|
202
|
+
|
|
203
|
+
## 5. Ordre de travail proposé
|
|
204
|
+
|
|
205
|
+
1. `paths` + `hub` : petits, autonomes, gain immédiat (les caches éparpillés).
|
|
206
|
+
2. `store` : extraction presque directe de `pipeline_cache`.
|
|
207
|
+
3. `data` : le module neuf, le plus gros gain disque.
|
|
208
|
+
4. `config` puis `exp`.
|
|
209
|
+
5. Migrer Pipeline-T2I sur useml, module par module, sans casser ses tests.
|
|
210
|
+
|
|
211
|
+
Chaque étape finit par une publication sur PyPI (1.0.0a1, a2…), pour que Pipeline-T2I
|
|
212
|
+
puisse en dépendre au fur et à mesure.
|
|
213
|
+
|
|
214
|
+
## 6. Décisions ouvertes
|
|
215
|
+
|
|
216
|
+
- API : repartir de zéro (v1 incompatible avec 0.3), ou garder `useml.init` / `new` /
|
|
217
|
+
`focus` ? Proposition : repartir de zéro ; 0.3 n'a pas d'utilisateurs connus.
|
|
218
|
+
- Langue du code et de la doc : anglais (public PyPI) ou français (comme Pipeline-T2I) ?
|
|
219
|
+
Proposition : anglais pour l'API et la doc publique.
|
|
220
|
+
- Version minimale de Python : 3.10, comme Pipeline-T2I.
|
|
221
|
+
- Dépendances obligatoires : numpy seul. torch, huggingface_hub, datasets, gdown en
|
|
222
|
+
options (`pip install useml[hf,torch]`).
|
useml-1.0.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Enzo-py
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
useml-1.0.0/PKG-INFO
ADDED
|
@@ -0,0 +1,242 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: useml
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: One root for every ML cache, one gate for every download, data processed once.
|
|
5
|
+
Project-URL: Homepage, https://github.com/Enzo-py/useml
|
|
6
|
+
Project-URL: Bug Tracker, https://github.com/Enzo-py/useml/issues
|
|
7
|
+
Author-email: Enzo-py <85191552+Enzo-py@users.noreply.github.com>
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Keywords: cache,datasets,deep learning,experiments,huggingface,machine learning,reproducibility
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Science/Research
|
|
13
|
+
Classifier: Operating System :: MacOS
|
|
14
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
20
|
+
Requires-Python: >=3.10
|
|
21
|
+
Requires-Dist: numpy>=1.22
|
|
22
|
+
Requires-Dist: pyyaml>=6
|
|
23
|
+
Requires-Dist: tomli>=1.1; python_version < '3.11'
|
|
24
|
+
Requires-Dist: tqdm>=4.60
|
|
25
|
+
Provides-Extra: all
|
|
26
|
+
Requires-Dist: gdown>=4.6; extra == 'all'
|
|
27
|
+
Requires-Dist: huggingface-hub>=0.20; extra == 'all'
|
|
28
|
+
Requires-Dist: psutil>=5.9; extra == 'all'
|
|
29
|
+
Provides-Extra: gdrive
|
|
30
|
+
Requires-Dist: gdown>=4.6; extra == 'gdrive'
|
|
31
|
+
Provides-Extra: hf
|
|
32
|
+
Requires-Dist: huggingface-hub>=0.20; extra == 'hf'
|
|
33
|
+
Provides-Extra: test
|
|
34
|
+
Requires-Dist: pytest>=7; extra == 'test'
|
|
35
|
+
Provides-Extra: watch
|
|
36
|
+
Requires-Dist: psutil>=5.9; extra == 'watch'
|
|
37
|
+
Description-Content-Type: text/markdown
|
|
38
|
+
|
|
39
|
+
# useml
|
|
40
|
+
|
|
41
|
+
One root for every ML cache, one gate for every download.
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
pip install "useml[all]"
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Quick start
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
pip install "useml[all]"
|
|
51
|
+
cd my-project
|
|
52
|
+
useml init # shows what it would set up (adds, never overwrites); confirm to write
|
|
53
|
+
useml check # checks that everything resolves
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## One root per machine
|
|
57
|
+
|
|
58
|
+
```toml
|
|
59
|
+
# ~/.config/useml/config.toml
|
|
60
|
+
root = "/datadisk4/me/useml"
|
|
61
|
+
|
|
62
|
+
[hub]
|
|
63
|
+
parallel = false # default: one download thread at a time
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
`import useml` (first, before torch / transformers) points `HF_HOME`, `TORCH_HOME`,
|
|
67
|
+
`TMPDIR`, pip, triton… under the root. A cache already placed outside the home is never
|
|
68
|
+
moved. `useml paths` shows where everything goes.
|
|
69
|
+
|
|
70
|
+
## One gate for downloads
|
|
71
|
+
|
|
72
|
+
```python
|
|
73
|
+
import useml
|
|
74
|
+
|
|
75
|
+
useml.hub.get("hf://openai/clip-vit-large-patch14")
|
|
76
|
+
useml.hub.get("hf://datasets/org/name@main/file.json")
|
|
77
|
+
useml.hub.get("https://example.org/annotations.zip", extract_archive=True)
|
|
78
|
+
useml.hub.get("gdrive://<file id>")
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Already downloaded → answered from disk, no network. Every download is recorded:
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
useml hub ls # what is on disk, how big, last used
|
|
85
|
+
useml hub scan # caches left in the home (~/.cache/huggingface…)
|
|
86
|
+
useml hub scan --move --apply
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## The network policy
|
|
90
|
+
|
|
91
|
+
By default, only one thread may download at a time, in every library:
|
|
92
|
+
|
|
93
|
+
- Hugging Face `xet` (Rust, its own parallel connections) is disabled;
|
|
94
|
+
- the thread pools of `huggingface_hub` and `datasets` become sequential;
|
|
95
|
+
- `socket.connect` refuses an outbound connection from a second thread
|
|
96
|
+
(`ParallelDownloadError`), and logs it;
|
|
97
|
+
- `useml hub watch -- python train.py` watches the whole process tree from outside
|
|
98
|
+
and kills it on a sustained violation.
|
|
99
|
+
|
|
100
|
+
`useml.hub.allow_parallel()` lifts it, explicitly.
|
|
101
|
+
|
|
102
|
+
## One cache store
|
|
103
|
+
|
|
104
|
+
```python
|
|
105
|
+
store = useml.store.open() # <root>/store
|
|
106
|
+
masks = store.declare("processing/masks", cost="expensive")
|
|
107
|
+
masks.put({"image": digest, "model": "sam-h"}, {"masks": array})
|
|
108
|
+
masks.get({"image": digest, "model": "sam-h"})
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
One SQLite index (WAL, safe across processes), large values in files written atomically,
|
|
112
|
+
one write per key. Spaces are declared with a cost (`cheap`, `expensive`, `precious`)
|
|
113
|
+
kept in the index, so cleaning needs no project code:
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
useml store spaces
|
|
117
|
+
useml store gc --max-size 450GB # dry run: cheapest to recompute first
|
|
118
|
+
useml store gc --max-size 450GB --apply
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
`[store] max_size = "450GB"` in the config sets the default budget. Nothing is ever
|
|
122
|
+
evicted automatically, pinned entries and `precious` spaces are kept.
|
|
123
|
+
|
|
124
|
+
## Data processed once
|
|
125
|
+
|
|
126
|
+
```python
|
|
127
|
+
from useml import data
|
|
128
|
+
|
|
129
|
+
@data.processor("siglip-image", version=1, batch_size=64, dtype="float16")
|
|
130
|
+
class SiglipImage:
|
|
131
|
+
def __init__(self, model="google/siglip-base-patch16-224", device="cuda"): ...
|
|
132
|
+
def load(self, path): ... # per item, in worker threads
|
|
133
|
+
def __call__(self, images): ... # a batch → (B, D) array, or a dict of arrays
|
|
134
|
+
|
|
135
|
+
data.process(data.images("/data/vg/images"), SiglipImage, name="vg-siglip")
|
|
136
|
+
feats = data.load("vg-siglip") # one line; nothing is read until used
|
|
137
|
+
feats[0], feats[100:200], feats.numpy()
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
- One table per (processor, version, parameters, dtype), shared by every dataset: rows
|
|
141
|
+
are found by a hash of their CONTENT, so an image two datasets share is computed once.
|
|
142
|
+
- Only missing rows are computed; when nothing is missing, the model is never loaded.
|
|
143
|
+
- Storage `float16` (default), `float32` or `int8` (one byte per number + a scale per row).
|
|
144
|
+
- Memory-mapped, append-only shards; one writer per table (a file lock); an interrupted
|
|
145
|
+
run keeps its rows and resumes.
|
|
146
|
+
- The size to write is checked against the free disk and `[data] max_size` before writing.
|
|
147
|
+
- `process(..., detach=True)` runs in its own process: `job.follow()`, `useml data jobs`.
|
|
148
|
+
- Anything longer than ~2 s shows a tqdm bar or a "⏳ … / ✓ … (12.3s)" line.
|
|
149
|
+
|
|
150
|
+
```bash
|
|
151
|
+
useml data ls # named datasets
|
|
152
|
+
useml data tables # tables, size, who uses them
|
|
153
|
+
useml data rm vg-siglip --table
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
## Configs in YAML, objects in one line
|
|
157
|
+
|
|
158
|
+
```toml
|
|
159
|
+
# pyproject.toml of your project
|
|
160
|
+
[tool.useml.config]
|
|
161
|
+
root = "configs" # configs/models/*.yaml, configs/scorers/*.yaml
|
|
162
|
+
packages = ["mypkg.models"] # where `type:` names are looked up (no imports by string)
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
```yaml
|
|
166
|
+
# configs/models/gmti_h.yaml
|
|
167
|
+
meta: {display_name: GMTI-H}
|
|
168
|
+
type: GMTI
|
|
169
|
+
clip: {ref: siglip2} # another config, built once and shared
|
|
170
|
+
graph_matching: {type: GraphMatching, solver: frank-wolfe}
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
```python
|
|
174
|
+
from useml import config
|
|
175
|
+
gmti = config.load("gmti_h") # memoised by name
|
|
176
|
+
gmti = config.load("gmti_h", graph_matching={"solver": "bcd"}) # one setting, merged
|
|
177
|
+
gmti.config.hash, gmti.config.provenance() # cite what ran
|
|
178
|
+
config.create("variant", gmti); config.diff("gmti_h", gmti) # and back to a file
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
Misspelled keys and types raise with the closest name and the place in the file.
|
|
182
|
+
|
|
183
|
+
## Experiences, and their outputs in one line
|
|
184
|
+
|
|
185
|
+
```python
|
|
186
|
+
from useml import exp, config, data
|
|
187
|
+
|
|
188
|
+
with exp.experience("edges/siglip-vs-clip") as e: # nothing runs in the block
|
|
189
|
+
trained = e.step(train_edges, data.load("vg-siglip"), config.load("edge_model"),
|
|
190
|
+
epochs=10, name="edges")
|
|
191
|
+
e.step(report, trained, name="report")
|
|
192
|
+
# block end: declaration written, run detached, followed with a progress bar
|
|
193
|
+
|
|
194
|
+
model = exp.get("edges/siglip-vs-clip/edges") # later, anywhere: the trained model
|
|
195
|
+
exp.open("edges/siglip-vs-clip").results() # every step's numbers
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
- A step is an importable function. Arguments are recipes: outputs of earlier steps,
|
|
199
|
+
`config.load(...)` objects, `data.load(name)` datasets, outputs of other experiences.
|
|
200
|
+
- Fingerprints chain: running the block again skips what is done; changing a line reruns
|
|
201
|
+
only what depends on it. An interrupted run resumes.
|
|
202
|
+
- Outputs are saved by type: a model built from a config is kept as config + weights and
|
|
203
|
+
comes back rebuilt; arrays as `.npz`; figures as `.png`; numbers as JSON.
|
|
204
|
+
- A step with a `ctx` parameter gets its folder, `ctx.progress(i, n)`, `ctx.checkpoints`
|
|
205
|
+
and `ctx.should_stop()`.
|
|
206
|
+
|
|
207
|
+
```bash
|
|
208
|
+
useml exp ls
|
|
209
|
+
useml exp show edges/siglip-vs-clip
|
|
210
|
+
useml exp follow edges/siglip-vs-clip
|
|
211
|
+
useml exp stop edges/siglip-vs-clip
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
### Runs that survive, crashes that explain themselves
|
|
215
|
+
|
|
216
|
+
A detached run lives in a tmux session (`useml exp attach <name>`), or in its own session
|
|
217
|
+
without tmux: closing the laptop, the SSH connection or the notebook does not stop it.
|
|
218
|
+
A small supervisor process is its parent and records how it ended — exit code, signal
|
|
219
|
+
(SIGKILL ≈ out of RAM, SIGSEGV = native crash), peak RAM, kernel OOM lines, traceback,
|
|
220
|
+
last log lines:
|
|
221
|
+
|
|
222
|
+
```bash
|
|
223
|
+
useml exp why edges/siglip-vs-clip # where it is, or why it died
|
|
224
|
+
useml exp stack edges/siglip-vs-clip # the Python stack of a run that seems stuck
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
```toml
|
|
228
|
+
# ~/.config/useml/config.toml — optional: be told when a run ends or crashes
|
|
229
|
+
[exp]
|
|
230
|
+
notify = "your-command $USEML_EXP_NAME $USEML_EXP_STATUS"
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
### Bundles: archive the version that worked
|
|
234
|
+
|
|
235
|
+
```bash
|
|
236
|
+
useml exp bundle edges/siglip-vs-clip -o archive/edges-final [--archive]
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
A standalone folder: the code exactly as it ran (commit + uncommitted diff + untracked
|
|
240
|
+
sources, recorded at every launch), a copy of useml, the configs, every step's output,
|
|
241
|
+
the rows of the datasets it read, `packages.txt`, and sha256 checksums. `python load.py`
|
|
242
|
+
/ `from load import get` reads an output; `python run.py --from-scratch` recomputes it.
|