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.

Files changed (97) hide show
  1. useml-1.0.0/.gitignore +5 -0
  2. useml-1.0.0/DESIGN.md +222 -0
  3. useml-1.0.0/LICENSE +21 -0
  4. useml-1.0.0/PKG-INFO +242 -0
  5. useml-1.0.0/README.md +204 -0
  6. useml-1.0.0/pyproject.toml +52 -0
  7. useml-1.0.0/src/useml/__init__.py +42 -0
  8. useml-1.0.0/src/useml/__main__.py +5 -0
  9. useml-1.0.0/src/useml/_progress.py +90 -0
  10. useml-1.0.0/src/useml/_project.py +45 -0
  11. useml-1.0.0/src/useml/_setup.py +470 -0
  12. useml-1.0.0/src/useml/cli.py +473 -0
  13. useml-1.0.0/src/useml/config/__init__.py +127 -0
  14. useml-1.0.0/src/useml/config/_config.py +201 -0
  15. useml-1.0.0/src/useml/config/_git.py +81 -0
  16. useml-1.0.0/src/useml/config/_library.py +357 -0
  17. useml-1.0.0/src/useml/config/_types.py +111 -0
  18. useml-1.0.0/src/useml/config/_write.py +248 -0
  19. useml-1.0.0/src/useml/data/__init__.py +39 -0
  20. useml-1.0.0/src/useml/data/_catalog.py +148 -0
  21. useml-1.0.0/src/useml/data/_jobs.py +227 -0
  22. useml-1.0.0/src/useml/data/_keys.py +53 -0
  23. useml-1.0.0/src/useml/data/_processor.py +151 -0
  24. useml-1.0.0/src/useml/data/_run.py +240 -0
  25. useml-1.0.0/src/useml/data/_sources.py +218 -0
  26. useml-1.0.0/src/useml/data/_table.py +288 -0
  27. useml-1.0.0/src/useml/data/_view.py +138 -0
  28. useml-1.0.0/src/useml/exp/__init__.py +28 -0
  29. useml-1.0.0/src/useml/exp/_bundle.py +421 -0
  30. useml-1.0.0/src/useml/exp/_experience.py +472 -0
  31. useml-1.0.0/src/useml/exp/_launch.py +222 -0
  32. useml-1.0.0/src/useml/exp/_outputs.py +162 -0
  33. useml-1.0.0/src/useml/exp/_provenance.py +159 -0
  34. useml-1.0.0/src/useml/exp/_refs.py +242 -0
  35. useml-1.0.0/src/useml/exp/_runtime.py +303 -0
  36. useml-1.0.0/src/useml/exp/_supervise.py +252 -0
  37. useml-1.0.0/src/useml/hub/__init__.py +23 -0
  38. useml-1.0.0/src/useml/hub/_fetch.py +321 -0
  39. useml-1.0.0/src/useml/hub/_policy.py +377 -0
  40. useml-1.0.0/src/useml/hub/_registry.py +115 -0
  41. useml-1.0.0/src/useml/hub/_scan.py +107 -0
  42. useml-1.0.0/src/useml/hub/_watch.py +157 -0
  43. useml-1.0.0/src/useml/paths.py +331 -0
  44. useml-1.0.0/src/useml/store/__init__.py +65 -0
  45. useml-1.0.0/src/useml/store/_maintenance.py +253 -0
  46. useml-1.0.0/src/useml/store/_spaces.py +67 -0
  47. useml-1.0.0/src/useml/store/_store.py +676 -0
  48. useml-1.0.0/tests/conftest.py +47 -0
  49. useml-1.0.0/tests/data_procs.py +54 -0
  50. useml-1.0.0/tests/exp_steps.py +117 -0
  51. useml-1.0.0/tests/test_config.py +389 -0
  52. useml-1.0.0/tests/test_data.py +302 -0
  53. useml-1.0.0/tests/test_exp.py +228 -0
  54. useml-1.0.0/tests/test_exp_robust.py +276 -0
  55. useml-1.0.0/tests/test_fetch.py +179 -0
  56. useml-1.0.0/tests/test_paths.py +97 -0
  57. useml-1.0.0/tests/test_policy.py +200 -0
  58. useml-1.0.0/tests/test_setup.py +167 -0
  59. useml-1.0.0/tests/test_store.py +342 -0
  60. useml-0.3.2/PKG-INFO +0 -471
  61. useml-0.3.2/README.md +0 -454
  62. useml-0.3.2/pyproject.toml +0 -30
  63. useml-0.3.2/setup.cfg +0 -4
  64. useml-0.3.2/tests/test_bundle.py +0 -366
  65. useml-0.3.2/tests/test_level2.py +0 -244
  66. useml-0.3.2/tests/test_session.py +0 -208
  67. useml-0.3.2/tests/test_train_level0.py +0 -234
  68. useml-0.3.2/tests/test_usecases.py +0 -1249
  69. useml-0.3.2/tests/test_vault.py +0 -243
  70. useml-0.3.2/useml/__init__.py +0 -94
  71. useml-0.3.2/useml/dataset/__init__.py +0 -4
  72. useml-0.3.2/useml/dataset/bundle.py +0 -288
  73. useml-0.3.2/useml/dataset/loaders.py +0 -168
  74. useml-0.3.2/useml/errors.py +0 -377
  75. useml-0.3.2/useml/imports.py +0 -215
  76. useml-0.3.2/useml/session/__init__.py +0 -4
  77. useml-0.3.2/useml/session/component.py +0 -59
  78. useml-0.3.2/useml/session/manager.py +0 -482
  79. useml-0.3.2/useml/template/__init__.py +0 -6
  80. useml-0.3.2/useml/template/config.py +0 -140
  81. useml-0.3.2/useml/template/loss.py +0 -28
  82. useml-0.3.2/useml/template/model.py +0 -28
  83. useml-0.3.2/useml/template/trainer.py +0 -758
  84. useml-0.3.2/useml/vault/__init__.py +0 -5
  85. useml-0.3.2/useml/vault/code_extractor.py +0 -261
  86. useml-0.3.2/useml/vault/core.py +0 -63
  87. useml-0.3.2/useml/vault/model_registry.py +0 -267
  88. useml-0.3.2/useml/vault/project.py +0 -309
  89. useml-0.3.2/useml/vault/runs.py +0 -814
  90. useml-0.3.2/useml/vault/snapshot.py +0 -170
  91. useml-0.3.2/useml/workdir/__init__.py +0 -14
  92. useml-0.3.2/useml/workdir/_hook.py +0 -79
  93. useml-0.3.2/useml.egg-info/PKG-INFO +0 -471
  94. useml-0.3.2/useml.egg-info/SOURCES.txt +0 -36
  95. useml-0.3.2/useml.egg-info/dependency_links.txt +0 -1
  96. useml-0.3.2/useml.egg-info/requires.txt +0 -8
  97. useml-0.3.2/useml.egg-info/top_level.txt +0 -1
useml-1.0.0/.gitignore ADDED
@@ -0,0 +1,5 @@
1
+ .venv/
2
+ dist/
3
+ __pycache__/
4
+ *.egg-info/
5
+ .pytest_cache/
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.