genml-kit 0.1.0__tar.gz → 0.2.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (252) hide show
  1. genml_kit-0.2.1/PKG-INFO +2024 -0
  2. genml_kit-0.2.1/README.md +1982 -0
  3. genml_kit-0.2.1/genml_kit/__init__.py +0 -0
  4. genml_kit-0.2.1/genml_kit/augmentations/__init__.py +7 -0
  5. {genml_kit-0.1.0/genml_kit/pretrain → genml_kit-0.2.1/genml_kit}/augmentations/dual_view.py +5 -2
  6. {genml_kit-0.1.0/genml_kit/pretrain → genml_kit-0.2.1/genml_kit}/augmentations/multicrop.py +42 -34
  7. genml_kit-0.2.1/genml_kit/datasets/__init__.py +23 -0
  8. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/datasets/balanced_sampler.py +40 -11
  9. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/datasets/ensemble.py +4 -0
  10. genml_kit-0.2.1/genml_kit/datasets/factory.py +58 -0
  11. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/datasets/image_folder.py +8 -3
  12. genml_kit-0.2.1/genml_kit/datasets/replay_buffer.py +394 -0
  13. genml_kit-0.2.1/genml_kit/datasets/rollout_buffer.py +346 -0
  14. genml_kit-0.2.1/genml_kit/datasets/transforms.py +60 -0
  15. genml_kit-0.2.1/genml_kit/datasets/vo_pairs.py +352 -0
  16. genml_kit-0.2.1/genml_kit/geometry/__init__.py +28 -0
  17. genml_kit-0.2.1/genml_kit/geometry/similarity.py +190 -0
  18. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/io/checkpointing.py +58 -10
  19. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/io/storage_utils.py +5 -10
  20. genml_kit-0.2.1/genml_kit/losses/__init__.py +52 -0
  21. genml_kit-0.2.1/genml_kit/losses/builtin.py +106 -0
  22. {genml_kit-0.1.0/genml_kit/pretrain → genml_kit-0.2.1/genml_kit}/losses/dino.py +5 -0
  23. {genml_kit-0.1.0/genml_kit/pretrain → genml_kit-0.2.1/genml_kit}/losses/focal.py +8 -6
  24. genml_kit-0.2.1/genml_kit/losses/registry.py +97 -0
  25. genml_kit-0.2.1/genml_kit/losses/rl.py +294 -0
  26. genml_kit-0.2.1/genml_kit/methods/__init__.py +26 -0
  27. genml_kit-0.2.1/genml_kit/methods/base.py +295 -0
  28. genml_kit-0.2.1/genml_kit/methods/byol.py +167 -0
  29. genml_kit-0.2.1/genml_kit/methods/classification.py +239 -0
  30. genml_kit-0.2.1/genml_kit/methods/dino.py +256 -0
  31. {genml_kit-0.1.0/genml_kit/pretrain → genml_kit-0.2.1/genml_kit}/methods/ijepa.py +86 -43
  32. genml_kit-0.2.1/genml_kit/methods/registry.py +22 -0
  33. genml_kit-0.2.1/genml_kit/methods/rl_dqn.py +292 -0
  34. genml_kit-0.2.1/genml_kit/methods/rl_ppo.py +375 -0
  35. genml_kit-0.2.1/genml_kit/methods/rl_sac.py +510 -0
  36. genml_kit-0.2.1/genml_kit/methods/rl_utils.py +69 -0
  37. {genml_kit-0.1.0/genml_kit/pretrain → genml_kit-0.2.1/genml_kit}/methods/simmim.py +74 -30
  38. genml_kit-0.2.1/genml_kit/methods/supcon.py +91 -0
  39. genml_kit-0.2.1/genml_kit/methods/vo_pair.py +172 -0
  40. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/models/__init__.py +12 -10
  41. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/models/attention_pooling.py +15 -8
  42. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/models/byol.py +3 -1
  43. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/models/cls_model_wrapper/loader.py +16 -8
  44. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/models/cls_model_wrapper/model.py +7 -2
  45. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/models/contrastive.py +1 -0
  46. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/models/convvit/loader.py +5 -4
  47. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/models/convvit/model.py +47 -16
  48. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/models/dino.py +31 -11
  49. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/models/encoder_utils.py +10 -4
  50. genml_kit-0.2.1/genml_kit/models/init.py +45 -0
  51. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/models/registry.py +67 -64
  52. genml_kit-0.2.1/genml_kit/models/rl/__init__.py +20 -0
  53. genml_kit-0.2.1/genml_kit/models/rl/actor_critic.py +456 -0
  54. genml_kit-0.2.1/genml_kit/models/rl/qnetwork.py +204 -0
  55. genml_kit-0.2.1/genml_kit/models/rl/sac_critic.py +93 -0
  56. genml_kit-0.2.1/genml_kit/models/rl/sac_model.py +27 -0
  57. genml_kit-0.2.1/genml_kit/models/rl/spaces.py +104 -0
  58. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/models/simmim.py +14 -1
  59. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/models/timm/loader.py +9 -12
  60. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/models/timm/model.py +1 -0
  61. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/models/transformer_utils.py +11 -0
  62. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/models/uvito/loader.py +4 -3
  63. genml_kit-0.2.1/genml_kit/models/uvito/model.py +238 -0
  64. genml_kit-0.2.1/genml_kit/models/vo/__init__.py +27 -0
  65. genml_kit-0.2.1/genml_kit/models/vo/loader.py +57 -0
  66. genml_kit-0.2.1/genml_kit/models/vo/processor.py +13 -0
  67. genml_kit-0.2.1/genml_kit/models/vo/vo_similar.py +236 -0
  68. genml_kit-0.2.1/genml_kit/pipelines/__init__.py +25 -0
  69. genml_kit-0.2.1/genml_kit/pipelines/base.py +62 -0
  70. genml_kit-0.2.1/genml_kit/pipelines/contracts.py +21 -0
  71. genml_kit-0.2.1/genml_kit/pipelines/images.py +441 -0
  72. genml_kit-0.2.1/genml_kit/pipelines/registry.py +18 -0
  73. genml_kit-0.2.1/genml_kit/pipelines/rl.py +631 -0
  74. genml_kit-0.2.1/genml_kit/pipelines/rl_normalize.py +208 -0
  75. genml_kit-0.2.1/genml_kit/pipelines/vo_pair.py +143 -0
  76. genml_kit-0.2.1/genml_kit/training/classifiers/__init__.py +113 -0
  77. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/training/classifiers/cls_attention.py +8 -3
  78. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/training/classifiers/mlp.py +6 -4
  79. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/training/eval.py +26 -8
  80. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/training/infer.py +11 -7
  81. genml_kit-0.2.1/genml_kit/training/labels.py +110 -0
  82. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/training/model_utils.py +10 -5
  83. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/training/optim_factory.py +58 -9
  84. genml_kit-0.2.1/genml_kit/training/rl_trainer.py +496 -0
  85. genml_kit-0.2.1/genml_kit/training/train.py +499 -0
  86. genml_kit-0.2.1/genml_kit/training/train_compat.py +161 -0
  87. genml_kit-0.2.1/genml_kit/training/train_reporting.py +517 -0
  88. genml_kit-0.2.1/genml_kit/training/trainer.py +337 -0
  89. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/training/tta.py +2 -1
  90. genml_kit-0.2.1/genml_kit/training/video_utils.py +98 -0
  91. genml_kit-0.2.1/genml_kit/training/vo/__init__.py +22 -0
  92. genml_kit-0.2.1/genml_kit/training/vo/eval_vo.py +128 -0
  93. genml_kit-0.2.1/genml_kit/training/vo/train_vo.py +231 -0
  94. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/utils/args.py +62 -14
  95. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/utils/cli.py +12 -10
  96. genml_kit-0.2.1/genml_kit/utils/env.py +47 -0
  97. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/utils/gpu.py +15 -3
  98. genml_kit-0.2.1/genml_kit/utils/registry.py +107 -0
  99. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/utils/script.py +10 -0
  100. genml_kit-0.2.1/genml_kit/utils/seed.py +119 -0
  101. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/utils/signal.py +21 -0
  102. genml_kit-0.2.1/genml_kit.egg-info/PKG-INFO +2024 -0
  103. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit.egg-info/SOURCES.txt +94 -19
  104. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit.egg-info/entry_points.txt +0 -1
  105. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit.egg-info/requires.txt +6 -1
  106. {genml_kit-0.1.0 → genml_kit-0.2.1}/pyproject.toml +18 -6
  107. genml_kit-0.2.1/tests/test_actor_critic.py +217 -0
  108. genml_kit-0.2.1/tests/test_args_frozen.py +77 -0
  109. genml_kit-0.2.1/tests/test_attention_pooling.py +37 -0
  110. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_attr_utils.py +2 -1
  111. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_balanced_sampler.py +36 -4
  112. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_byol.py +40 -30
  113. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_checkpointing.py +101 -3
  114. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_classifiers.py +15 -16
  115. genml_kit-0.2.1/tests/test_cli_help.py +49 -0
  116. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_contrastive_models.py +2 -1
  117. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_custom_models.py +152 -13
  118. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_datasets_ensemble.py +32 -2
  119. genml_kit-0.2.1/tests/test_dino.py +307 -0
  120. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_encoder_utils.py +54 -0
  121. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_ensemble_collate.py +36 -19
  122. genml_kit-0.2.1/tests/test_env.py +49 -0
  123. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_evaluation_metrics.py +8 -10
  124. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_extract_features.py +6 -3
  125. genml_kit-0.2.1/tests/test_geometry_similarity.py +301 -0
  126. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_grad_monitor.py +8 -4
  127. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_headless_models.py +11 -6
  128. genml_kit-0.2.1/tests/test_init_orthogonal.py +101 -0
  129. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_log_format.py +9 -9
  130. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_logging_utils.py +2 -1
  131. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_lora.py +20 -1
  132. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_loss_and_multipliers.py +2 -1
  133. genml_kit-0.2.1/tests/test_loss_registry.py +127 -0
  134. genml_kit-0.2.1/tests/test_method_lifecycle.py +334 -0
  135. genml_kit-0.2.1/tests/test_model_script_loading.py +94 -0
  136. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_optim_factory.py +26 -3
  137. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_param_align.py +8 -4
  138. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_pipeline.py +37 -12
  139. genml_kit-0.2.1/tests/test_pipeline_method_registry.py +413 -0
  140. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_pretrain_methods.py +15 -9
  141. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_pretrain_smoke.py +67 -114
  142. genml_kit-0.2.1/tests/test_pretrain_vis.py +127 -0
  143. genml_kit-0.2.1/tests/test_replay_buffer.py +217 -0
  144. genml_kit-0.2.1/tests/test_rl_cli.py +149 -0
  145. genml_kit-0.2.1/tests/test_rl_learning.py +238 -0
  146. genml_kit-0.2.1/tests/test_rl_losses.py +154 -0
  147. genml_kit-0.2.1/tests/test_rl_losses_phase2.py +226 -0
  148. genml_kit-0.2.1/tests/test_rl_method.py +177 -0
  149. genml_kit-0.2.1/tests/test_rl_model_selector.py +231 -0
  150. genml_kit-0.2.1/tests/test_rl_models.py +148 -0
  151. genml_kit-0.2.1/tests/test_rl_normalize.py +105 -0
  152. genml_kit-0.2.1/tests/test_rl_pipeline.py +297 -0
  153. genml_kit-0.2.1/tests/test_rl_ppo.py +341 -0
  154. genml_kit-0.2.1/tests/test_rl_sac.py +241 -0
  155. genml_kit-0.2.1/tests/test_rl_spaces.py +79 -0
  156. genml_kit-0.2.1/tests/test_rl_trainer.py +1312 -0
  157. genml_kit-0.2.1/tests/test_rl_video.py +337 -0
  158. genml_kit-0.2.1/tests/test_rollout_buffer.py +143 -0
  159. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_seed_utils.py +66 -21
  160. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_set_train_mode.py +2 -1
  161. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_signal_utils.py +38 -6
  162. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_supcon_loss.py +19 -10
  163. genml_kit-0.2.1/tests/test_supcon_method.py +114 -0
  164. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_table_utils.py +6 -3
  165. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_timm_models.py +2 -1
  166. genml_kit-0.2.1/tests/test_train_reporting.py +576 -0
  167. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_train_smoke.py +19 -7
  168. genml_kit-0.2.1/tests/test_trainer.py +320 -0
  169. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_transformer_encoder_init.py +1 -1
  170. genml_kit-0.2.1/tests/test_utils_registry.py +151 -0
  171. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_uvito.py +64 -1
  172. genml_kit-0.2.1/tests/test_vo_e2e.py +163 -0
  173. genml_kit-0.2.1/tests/test_vo_pairs.py +153 -0
  174. genml_kit-0.2.1/tests/test_vo_similar.py +222 -0
  175. genml_kit-0.2.1/tests/test_vo_training.py +247 -0
  176. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_xgb_pipeline.py +2 -1
  177. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_xgb_utils.py +6 -3
  178. genml_kit-0.1.0/PKG-INFO +0 -1209
  179. genml_kit-0.1.0/README.md +0 -1174
  180. genml_kit-0.1.0/genml_kit/__init__.py +0 -11
  181. genml_kit-0.1.0/genml_kit/datasets/__init__.py +0 -11
  182. genml_kit-0.1.0/genml_kit/models/uvito/model.py +0 -150
  183. genml_kit-0.1.0/genml_kit/pretrain/__init__.py +0 -1
  184. genml_kit-0.1.0/genml_kit/pretrain/augmentations/__init__.py +0 -1
  185. genml_kit-0.1.0/genml_kit/pretrain/cli.py +0 -884
  186. genml_kit-0.1.0/genml_kit/pretrain/losses/__init__.py +0 -8
  187. genml_kit-0.1.0/genml_kit/pretrain/methods/__init__.py +0 -11
  188. genml_kit-0.1.0/genml_kit/pretrain/methods/base.py +0 -100
  189. genml_kit-0.1.0/genml_kit/pretrain/methods/byol.py +0 -105
  190. genml_kit-0.1.0/genml_kit/pretrain/methods/dino.py +0 -179
  191. genml_kit-0.1.0/genml_kit/pretrain/methods/registry.py +0 -33
  192. genml_kit-0.1.0/genml_kit/pretrain/methods/supcon.py +0 -72
  193. genml_kit-0.1.0/genml_kit/training/classifiers/__init__.py +0 -80
  194. genml_kit-0.1.0/genml_kit/training/train.py +0 -1381
  195. genml_kit-0.1.0/genml_kit/training/train_reporting.py +0 -197
  196. genml_kit-0.1.0/genml_kit/utils/seed.py +0 -86
  197. genml_kit-0.1.0/genml_kit.egg-info/PKG-INFO +0 -1209
  198. genml_kit-0.1.0/tests/test_dino.py +0 -194
  199. genml_kit-0.1.0/tests/test_pretrain_vis.py +0 -188
  200. genml_kit-0.1.0/tests/test_restructure.py +0 -87
  201. genml_kit-0.1.0/tests/test_supcon_method.py +0 -100
  202. genml_kit-0.1.0/tests/test_train_reporting.py +0 -289
  203. {genml_kit-0.1.0 → genml_kit-0.2.1}/LICENSE +0 -0
  204. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/datasets/field_dataset.py +0 -0
  205. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/datasets/hf_proxy.py +0 -0
  206. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/datasets/retry.py +0 -0
  207. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/datasets/weighted_sampler.py +0 -0
  208. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/io/__init__.py +0 -0
  209. {genml_kit-0.1.0/genml_kit/pretrain → genml_kit-0.2.1/genml_kit}/losses/byol.py +0 -0
  210. {genml_kit-0.1.0/genml_kit/pretrain → genml_kit-0.2.1/genml_kit}/losses/contrastive.py +0 -0
  211. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/models/cls_model_wrapper/__init__.py +0 -0
  212. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/models/convvit/__init__.py +0 -0
  213. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/models/convvit/masked_encoder.py +0 -0
  214. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/models/convvit/processor.py +0 -0
  215. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/models/masked_encoder.py +0 -0
  216. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/models/processors/__init__.py +0 -0
  217. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/models/processors/base.py +0 -0
  218. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/models/timm/__init__.py +0 -0
  219. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/models/timm/processor.py +0 -0
  220. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/models/uvito/__init__.py +0 -0
  221. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/models/uvito/processor.py +0 -0
  222. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/training/__init__.py +0 -0
  223. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/training/classifiers/base.py +0 -0
  224. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/training/grad_monitor.py +0 -0
  225. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/training/metrics.py +0 -0
  226. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/training/param_align.py +0 -0
  227. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/training/xgb_pipeline.py +0 -0
  228. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/training/xgb_utils.py +0 -0
  229. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/utils/__init__.py +0 -0
  230. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/utils/attr.py +0 -0
  231. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/utils/image_dump.py +0 -0
  232. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/utils/label.py +0 -0
  233. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/utils/logging.py +0 -0
  234. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/utils/table.py +0 -0
  235. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit/utils/transformer.py +0 -0
  236. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit.egg-info/dependency_links.txt +0 -0
  237. {genml_kit-0.1.0 → genml_kit-0.2.1}/genml_kit.egg-info/top_level.txt +0 -0
  238. {genml_kit-0.1.0 → genml_kit-0.2.1}/setup.cfg +0 -0
  239. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_cli_utils.py +0 -0
  240. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_ensemble_ensure_label_space.py +0 -0
  241. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_ensemble_labels.py +0 -0
  242. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_ensemble_mixed_labels.py +0 -0
  243. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_image_dump.py +0 -0
  244. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_infer_topk.py +0 -0
  245. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_metrics.py +0 -0
  246. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_retry.py +0 -0
  247. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_s3r2util.py +0 -0
  248. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_script_utils.py +0 -0
  249. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_simmim.py +0 -0
  250. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_storage_utils.py +0 -0
  251. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_tta.py +0 -0
  252. {genml_kit-0.1.0 → genml_kit-0.2.1}/tests/test_weighted_sampler.py +0 -0
@@ -0,0 +1,2024 @@
1
+ Metadata-Version: 2.4
2
+ Name: genml_kit
3
+ Version: 0.2.1
4
+ Summary: General-purpose ML toolkit: image-classification, visual-odometry and self-supervised pre-training through one unified harness.
5
+ License: Apache-2.0
6
+ Project-URL: Homepage, https://github.com/davidel/genml_kit
7
+ Project-URL: Repository, https://github.com/davidel/genml_kit
8
+ Project-URL: Issues, https://github.com/davidel/genml_kit/issues
9
+ Requires-Python: >=3.9
10
+ Description-Content-Type: text/markdown
11
+ License-File: LICENSE
12
+ Requires-Dist: numpy
13
+ Requires-Dist: torch
14
+ Requires-Dist: torchvision
15
+ Requires-Dist: transformers
16
+ Requires-Dist: datasets
17
+ Requires-Dist: xgboost>=2.0
18
+ Requires-Dist: scikit-learn
19
+ Requires-Dist: pillow
20
+ Requires-Dist: tensorboard
21
+ Provides-Extra: gcs
22
+ Requires-Dist: google-cloud-storage; extra == "gcs"
23
+ Provides-Extra: s3
24
+ Requires-Dist: boto3>=1.28; extra == "s3"
25
+ Provides-Extra: lora
26
+ Requires-Dist: peft>=0.7.0; extra == "lora"
27
+ Provides-Extra: timm
28
+ Requires-Dist: timm>=1.0; extra == "timm"
29
+ Provides-Extra: uvito
30
+ Requires-Dist: segmentation_models_pytorch>=0.3.0; extra == "uvito"
31
+ Provides-Extra: rl
32
+ Requires-Dist: gymnasium>=0.29; extra == "rl"
33
+ Requires-Dist: pygame>=2.1; extra == "rl"
34
+ Requires-Dist: imageio[ffmpeg]>=2.31; extra == "rl"
35
+ Provides-Extra: all
36
+ Requires-Dist: genml_kit[gcs,lora,rl,s3,timm,uvito]; extra == "all"
37
+ Provides-Extra: dev
38
+ Requires-Dist: pytest; extra == "dev"
39
+ Requires-Dist: ruff; extra == "dev"
40
+ Requires-Dist: yapf; extra == "dev"
41
+ Dynamic: license-file
42
+
43
+ # genml_kit
44
+
45
+ [![CI](https://github.com/davidel/genml_kit/actions/workflows/ci.yml/badge.svg)](https://github.com/davidel/genml_kit/actions/workflows/ci.yml)
46
+
47
+ A general-purpose toolkit for image classification. Supports self-supervised
48
+ pre-training, supervised fine-tuning, and XGBoost ensemble inference — all
49
+ from the command line.
50
+
51
+ `genml_kit` is domain-agnostic: point it at any HuggingFace dataset, local
52
+ `ImageFolder` tree, or timm/HuggingFace backbone. It grew out of a
53
+ skin-lesion classification project; the dermoscopy-specific workflow (dataset
54
+ preparation, tuned recipes) is documented separately in
55
+ [`scdiag/README.md`](scdiag/README.md). The drone visual-odometry front-end
56
+ (similarity estimation between oblique aerial frames) is documented separately
57
+ in [`vo/README.md`](vo/README.md).
58
+
59
+ ## Contents
60
+
61
+ - [Why genml_kit?](#why-genml_kit)
62
+ - [How It Works](#how-it-works)
63
+ - [The Method Lifecycle](#the-method-lifecycle)
64
+ - [Installation](#installation)
65
+ - [Quick Start](#quick-start)
66
+ - [Pre-Training Guide](#pre-training-guide)
67
+ - [Fine-Tuning Guide](#fine-tuning-guide)
68
+ - [Inference Guide](#inference-guide)
69
+ - [Tips & Pitfalls](#tips--pitfalls)
70
+ - [Gradient Monitor](#gradient-monitor)
71
+ - [Custom Losses](#custom-losses)
72
+ - [Custom Models](#custom-models)
73
+ - [References And Further Reading](#references-and-further-reading)
74
+ - [Development](#development)
75
+ - [License](#license)
76
+
77
+ ## Why genml_kit?
78
+
79
+ Practitioners face two recurring problems: **labeled data is scarce** and
80
+ **off-the-shelf models are not domain-specific**. A ViT pre-trained on
81
+ ImageNet can classify cats and dogs, but specialized imagery — medical,
82
+ satellite, industrial, scientific — looks nothing like natural photos, and
83
+ the feature distributions are fundamentally different.
84
+
85
+ genml_kit solves this with a two-stage pipeline:
86
+
87
+ 1. **Pre-train** on large, often unlabeled image collections (or a labeled
88
+ superset) to learn domain-appropriate visual features.
89
+ 2. **Fine-tune** on your smaller labeled dataset, starting from those
90
+ pre-trained features instead of random initialization.
91
+
92
+ This consistently outperforms training from scratch, especially when your
93
+ labeled dataset has fewer than ~5 000 images. The tool also supports ensemble
94
+ inference with XGBoost on top of the learned features, which can squeeze out
95
+ additional performance for deployment.
96
+
97
+ > **Concrete example:** the dermoscopy workflow this toolkit was extracted
98
+ > from — preparing HAM10000 / ISIC / Derm1M corpora, per-method
99
+ > hyperparameters, and a worked pre-train → fine-tune run — is documented in
100
+ > [`scdiag/README.md`](scdiag/README.md).
101
+
102
+ ## How It Works
103
+
104
+ ```
105
+ ┌─────────────────────────────────────────────────────────────────┐
106
+ │ Pre-Training │
107
+ │ Unlabeled/labeled images │
108
+ │ ──────────────────────────────────► Encoder with learned │
109
+ │ SimMIM / I-JEPA / SupCon visual features │
110
+ └────────────────────────────┬────────────────────────────────────┘
111
+ │ encoder weights
112
+ ▼
113
+ ┌─────────────────────────────────────────────────────────────────┐
114
+ │ Fine-Tuning │
115
+ │ Small labeled dataset ──────────► Trained classifier │
116
+ │ + pre-trained encoder for your task │
117
+ └────────────────────────────┬────────────────────────────────────┘
118
+ │ backbone features
119
+ ▼
120
+ ┌─────────────────────────────────────────────────────────────────┐
121
+ │ (Optional) Ensemble │
122
+ │ Backbone features ──────────► XGBoost on top of the │
123
+ │ learned representations │
124
+ └─────────────────────────────────────────────────────────────────┘
125
+ ```
126
+
127
+ **Pre-training** teaches the model to understand the target imagery — textures,
128
+ boundaries, colour patterns, and spatial relationships. **Fine-tuning** adapts
129
+ that understanding to your specific classification task (e.g. disease vs.
130
+ healthy, defective vs. passing). **Ensemble inference** (optional) trains a
131
+ tree-based model on the same features, which sometimes generalises better
132
+ than a linear head for small datasets.
133
+
134
+ ### A Useful Mental Model
135
+
136
+ The encoder turns an image into a vector of features. During pre-training, we
137
+ choose an artificial task whose answer can be obtained from the images (or,
138
+ for SupCon, from their labels). The encoder learns parameters $`\theta`$ that
139
+ make this task easy. During fine-tuning, a classifier is attached to the
140
+ encoder and the whole model, or a selected part of it, is adapted to the real
141
+ labels:
142
+
143
+ ```text
144
+ image x ──► encoder f_theta(x) ──► classifier g_phi ──► class probabilities
145
+ │ │
146
+ reusable features task-specific boundary
147
+ ```
148
+
149
+ Here $`x`$ is the input image, $`f_\theta(x)`$ the feature vector computed by
150
+ the encoder with parameters $`\theta`$, and $`g_\phi`$ the classifier head with
151
+ parameters $`\phi`$.
152
+
153
+ Pre-training and fine-tuning are not two names for the same job. Pre-training
154
+ shapes a useful representation; fine-tuning decides how that representation
155
+ should be used for the target labels. If the pre-training data is visually
156
+ related to the target data, this gives the classifier a much better starting
157
+ point than random initialization. If the domains are very different, use a
158
+ smaller learning rate for the backbone and validate carefully.
159
+
160
+ The pre-training methods are introduced above with links to their papers (see
161
+ the [Pre-Training Guide](#pre-training-guide)). The
162
+ [timm documentation](https://huggingface.co/docs/timm/index) and the
163
+ [Hugging Face image classification guide](https://huggingface.co/docs/transformers/tasks/image_classification)
164
+ are useful references when selecting a backbone or processor.
165
+
166
+ ### The Method Lifecycle
167
+
168
+ `genml-kit-train` is a *branchless* driver: it never inspects which
169
+ `--method` or `--pipeline` it is running. Instead, every objective registers
170
+ itself through the `Method` registry and declares the same four lifecycle
171
+ hooks, which the driver calls in one fixed order:
172
+
173
+ | # | Hook | Purpose |
174
+ |---|---|---|
175
+ | 1 | `prepare_transforms(args, device)` | Resolve any transforms the method needs (e.g. the HF processor's normalization) **before** the loaders are built. |
176
+ | 2 | `wire_data(args, pipeline)` | Consume pipeline-built data attributes: label space, class weights, criterion. Runs **before** the model so the HF head can be sized from the label space. |
177
+ | 3 | `build_model(args, device)` | Construct the model. Every method applies LoRA (`--lora`), source-checkpoint weights (`--source_checkpoint`), freeze patterns (`--freeze`) and gradient checkpointing (`--grad_checkpoint`) through the same `_apply_model_extras` step — so all four flags work for **every** objective, not just classification. |
178
+ | 4 | `post_train(args, pipeline, device, result)` | Optional post-training stage, called after `BaseTrainer.run()` returns (skipped when the run was interrupted). |
179
+
180
+ Two ordering invariants are enforced by the hook order itself, not by
181
+ convention: transforms resolve before loaders consume them, and the label
182
+ space exists before the classification head is constructed.
183
+
184
+ Adding a new objective means implementing the hooks you need (only
185
+ `build_model` and `train_step` are abstract); the driver never changes.
186
+ `ClassificationMethod` additionally implements `post_train` to run the
187
+ optional XGBoost shallow-head stage; any future classifier-style method can
188
+ reuse the same hook.
189
+
190
+ ## Package Layout
191
+
192
+ | Module | Contents |
193
+ |---|---|
194
+ | `genml_kit.training` | `train.py` and `infer.py` CLI harnesses, `optim_factory.py` (optimizers, LLRD, schedulers), `model_utils.py` (loading, freezing, feature extraction), `param_align.py`, `eval.py` + `metrics.py`, `grad_monitor.py`, `train_reporting.py`, `tta.py`, `xgb_utils.py` + `xgb_pipeline.py`, `classifiers/` (pluggable heads) |
195
+ | `genml_kit.methods` | objective-side registry (classification, vo_pair, SimMIM, I-JEPA, DINO, BYOL, SupCon) |
196
+ | `genml_kit.losses` | shared loss library (focal, NT-Xent contrastive, DINO self-distillation, BYOL) |
197
+ | `genml_kit.augmentations` | objective-level transforms (dual-view, multi-crop) |
198
+ | `genml_kit.models` | model/processor registry; `timm/`, `convvit/`, `uvito/`, `cls_model_wrapper/` backends; `processors/base.py` |
199
+ | `genml_kit.datasets` | `hf_proxy.py` (HuggingFace → PyTorch bridge), `image_folder.py`, `ensemble.py`, `field_dataset.py`, `balanced_sampler.py`, `weighted_sampler.py`, `retry.py`, `vo_pairs.py` (synthetic VO pairs) |
200
+ | `genml_kit.geometry` | `similarity.py` (2-D similarity algebra, batched differentiable Umeyama, backward-map warp) — the math behind the visual-odometry front-end lives in [`vo/README.md`](vo/README.md) |
201
+ | `genml_kit.io` | `checkpointing.py` (atomic saves, LoRA state, remote fetch), `storage_utils.py` (S3 / GCS / R2) |
202
+ | `genml_kit.utils` | glog-style logging, CLI arg groups, seeding, signal handling, GPU info, tables, external `.py` script loading, `image_dump`, transformer init helpers |
203
+
204
+ ## Installation
205
+
206
+ ```bash
207
+ pip install genml_kit
208
+
209
+ # With timm model support:
210
+ pip install "genml_kit[timm]"
211
+
212
+ # With GCS checkpoint sync:
213
+ pip install "genml_kit[gcs]"
214
+
215
+ # With AWS S3 / Cloudflare R2 checkpoint sync (both use boto3):
216
+ pip install "genml_kit[s3]"
217
+
218
+ # With LoRA fine-tuning:
219
+ pip install "genml_kit[lora]"
220
+
221
+ # With UVito model support:
222
+ pip install "genml_kit[uvito]"
223
+
224
+ # Everything above in one shot (gcs, s3, lora, timm, uvito):
225
+ pip install "genml_kit[all]"
226
+ ```
227
+
228
+ **Requirements:** Python ≥ 3.9, PyTorch, torchvision, transformers, datasets,
229
+ NumPy, scikit-learn ≥ 1.3, XGBoost ≥ 2.0, Pillow, tensorboard.
230
+
231
+ ## Quick Start
232
+
233
+ The fastest way to get started:
234
+
235
+ ```bash
236
+ # Fine-tune a ViT on an image-classification dataset (5 epochs, ~2 minutes on GPU)
237
+ genml-kit-train --model google/vit-base-patch16-224 \
238
+ --dataset cifar10 \
239
+ --label_column label \
240
+ --epochs 5 \
241
+ --batch_size 32 \
242
+ --lr 3e-5 \
243
+ --image_size 224
244
+ ```
245
+
246
+ HuggingFace ViT backbones use fixed 224x224 position embeddings and do not
247
+ interpolate them, so they require `--image_size 224`. The toolkit default of
248
+ 448 targets size-flexible backbones such as ConvNeXt, timm EVA, or ConvViT,
249
+ which pool or interpolate the token sequence to the input size.
250
+
251
+ This downloads the model and dataset from HuggingFace, trains for 5 epochs,
252
+ and saves `genml_kit_latest.pt` and `genml_kit_best.pt`. See
253
+ [Pre-Training Guide](#pre-training-guide) below for the full pipeline
254
+ (starting with pre-training before fine-tuning).
255
+
256
+ ---
257
+
258
+ ## Pre-Training Guide
259
+
260
+ Pre-training learns general visual features from large datasets *before* you
261
+ fine-tune on your specific task. This is especially valuable wherever labeled
262
+ data is expensive to obtain but raw images are available in bulk — medical
263
+ imaging, remote sensing, industrial inspection, scientific imaging.
264
+
265
+ genml_kit supports five pre-training methods, each with different strengths:
266
+
267
+ ### Choosing Your Method
268
+
269
+ | Method | Needs labels? | Best when… | Key idea |
270
+ |---|---|---|---|
271
+ | **SimMIM** | No | You have large unlabeled datasets; want a simple, proven approach | Mask 60% of image patches, train the model to reconstruct the raw pixels |
272
+ | **I-JEPA** | No | You want faster training and better downstream transfer than SimMIM | Predict *representations* of masked regions, not raw pixels — avoids learning noise |
273
+ | **SupCon** | Yes | You have labels and want representations that cluster by class | Pull same-class images together, push different classes apart in feature space |
274
+ | **DINO** | No | You want strong features from a modest amount of data; proven, robust default | Self-distillation: a student matches the output distribution of its own EMA copy (the teacher) |
275
+ | **BYOL** | No | Similar goals to DINO with a simpler pipeline (two views, no multi-crop) | Online network predicts the output of its own EMA target network |
276
+
277
+ ### How Each Method Works
278
+
279
+ The methods differ mainly in what they call a correct answer. SimMIM asks for
280
+ pixels, I-JEPA asks for features, DINO and BYOL ask a network to predict the
281
+ output of its own slowly-moving copy, and SupCon asks for relative positions in
282
+ feature space. That distinction matters: pixel reconstruction can spend effort
283
+ reproducing colour and high-frequency detail, while the other methods spend
284
+ effort building invariant, separable representations.
285
+
286
+ **SimMIM** (Masked Image Modelling): Randomly masks ~60% of image patches and
287
+ trains a lightweight decoder to reconstruct the original pixels. The encoder
288
+ must learn to understand textures, boundaries, and spatial context from just
289
+ 40% of the image. Think of it as a "fill in the blanks" exercise for vision
290
+ models. Good default choice when you have lots of unlabeled images.
291
+ Reference: Xie et al., [SimMIM: A Simple Framework for Masked Image Modeling](https://arxiv.org/abs/2111.09886), CVPR 2022.
292
+
293
+ For an image split into patches $`x_1, \dots, x_N`$, let $`\mathcal{M}`$ be
294
+ the set of masked patch indices and $`\hat{x}_i`$ the decoder prediction.
295
+ SimMIM minimizes the mean squared reconstruction error over masked patches:
296
+
297
+ $$
298
+ \large
299
+ \mathcal{L}_{\text{MIM}} = \frac{1}{|\mathcal{M}|} \sum_{i \in \mathcal{M}} \left\| \hat{x}_i - x_i \right\|_2^2
300
+ $$
301
+
302
+ where:
303
+
304
+ - $`x_i`$ — the pixels of the $`i`$-th original patch;
305
+ - $`\hat{x}_i`$ — the decoder's reconstruction of that patch;
306
+ - $`\mathcal{M}`$ — the set of masked patch indices, and $`|\mathcal{M}|`$ its
307
+ size (how many patches are masked);
308
+ - $`\lVert \cdot \rVert_2^2`$ — the squared Euclidean ($`L_2`$) norm, i.e. the
309
+ sum of squared pixel differences over the patch.
310
+
311
+ Only masked patches contribute to the loss; otherwise copying visible pixels
312
+ would make the task too easy. A higher
313
+ `--mask_ratio` supplies less context and creates a harder task, but an
314
+ excessively high ratio can make reconstruction ambiguous.
315
+
316
+ **I-JEPA** (Joint-Embedding Predictive Architecture): Also masks patches, but
317
+ instead of reconstructing pixels, it predicts the *latent representation* of
318
+ the masked region from the visible context. This avoids wasting capacity on
319
+ pixel-level noise (e.g. exact JPEG compression artifacts) and learns more
320
+ transferable features. Uses a teacher–student setup with EMA momentum ramping.
321
+ Reference: Assran et al., [Self-Supervised Learning from Images with a Joint-Embedding Predictive Architecture](https://arxiv.org/abs/2301.08243), CVPR 2023.
322
+
323
+ Let $`f_\theta`$ be the student encoder and $`f_\xi`$ the teacher encoder;
324
+ $`\theta`$ and $`\xi`$ are their respective parameter vectors (the subscripts
325
+ name the network a symbol belongs to). The predictor $`q_\theta`$ receives the
326
+ visible context and predicts a target representation $`z_j = f_\xi(x_j)`$ for a
327
+ masked region. The objective is regression in representation space:
328
+
329
+ $$
330
+ \large
331
+ \mathcal{L}_{\text{IJEPA}} = \frac{1}{|\mathcal{M}|} \sum_{i \in \mathcal{M}} \left\| q_\theta(f_\theta(\text{context}))_i - \mathop{\mathrm{stopgrad}}\left(f_\xi(x_i)\right) \right\|_2^2
332
+ $$
333
+
334
+ where:
335
+
336
+ - $`x_i`$ — the $`i`$-th masked patch (the prediction target);
337
+ - $`f_\theta(\text{context})`$ — the student's encoding of the *visible* patches;
338
+ - $`q_\theta(\cdot)_i`$ — the predictor's output for the $`i`$-th masked location;
339
+ - $`f_\xi(x_i)`$ — the teacher's representation of the masked patch;
340
+ - $`\mathrm{stopgrad}(\cdot)`$ — treat the argument as a constant: gradients do
341
+ not flow through it during the student update;
342
+ - $`\lVert \cdot \rVert_2^2`$ — squared Euclidean distance in representation space;
343
+ - $`\mathcal{M}`$ — the set of masked patch indices.
344
+
345
+ The teacher is not optimized by backpropagation; it follows the student with
346
+ an exponential moving average:
347
+
348
+ $$
349
+ \large
350
+ \xi \leftarrow m \\, \xi + (1 - m) \\, \theta
351
+ $$
352
+
353
+ where $`m`$ is the momentum (`--teacher_momentum`) and the arrow denotes
354
+ assignment: the new teacher parameters are a convex blend of the old teacher
355
+ and the current student. A high $`m`$ changes the teacher slowly and gives
356
+ more stable targets. The asymmetric teacher update and masking are important:
357
+ two networks simply trained to copy each other could collapse to a constant
358
+ vector (the teacher-follows-student trick and $`\mathrm{stopgrad}`$ come from
359
+ Grill et al., [BYOL](https://arxiv.org/abs/2006.07733), NeurIPS 2020).
360
+
361
+ Three mechanism details complete the picture:
362
+
363
+ - **Block masking.** Target regions are not scattered single patches: the mask
364
+ is composed of a few contiguous rectangular blocks (4 blocks of 6×6 patches
365
+ in the current implementation). Contiguous holes are much harder to fill in
366
+ from context than isolated ones, so the task rewards spatial understanding
367
+ rather than high-frequency texture interpolation.
368
+ - **Two crop scales.** The *context* (source) view is a small random crop (50%
369
+ of the image side) and the *target* view is a larger one (85%). The predictor
370
+ must infer representations of a region it sees only through a narrow window,
371
+ which encourages semantic rather than layout-memorized features.
372
+ - **Momentum ramp.** $`m`$ moves from `--teacher_momentum` (0.996) toward
373
+ `--teacher_final_momentum` (1.0) as training progresses: as the encoder
374
+ matures, the teacher freezes progressively, stabilizing the targets late in
375
+ training.
376
+
377
+ **SupCon** (Supervised Contrastive Learning): Uses labels to define "positive"
378
+ pairs (same class) and "negative" pairs (different classes). The loss pulls
379
+ features of same-class images together and pushes different-class features
380
+ apart. Produces a feature space where similar images naturally cluster.
381
+ Requires a `ContrastiveEncoder` (backbone + projection head) and balanced
382
+ batch sampling to ensure each batch has enough same-class pairs.
383
+ Reference: Khosla et al., [Supervised Contrastive Learning](https://arxiv.org/abs/2004.11362), NeurIPS 2020.
384
+
385
+ An image $`x_i`$ is mapped by the encoder-and-projection-head
386
+ $`f_\theta`$ to a vector $`f_\theta(x_i)`$, which is rescaled to unit length
387
+ (normalized) so that comparisons are scale-invariant:
388
+
389
+ $$
390
+ \large
391
+ z_i = \frac{f_\theta(x_i)}{\lVert f_\theta(x_i) \rVert_2}
392
+ $$
393
+
394
+ where $`\lVert v \rVert_2 = \sqrt{\sum_d v_d^2}`$ is the Euclidean ($`L_2`$)
395
+ length of a vector $`v`$, so every $`z_i`$ lies on the unit hypersphere.
396
+ The similarity of two examples $`i`$ and $`j`$ is then the dot product of
397
+ their normalized projections, divided by the temperature $`\tau`$
398
+ (`--temperature`):
399
+
400
+ $$
401
+ \large
402
+ s_{ij} = \frac{z_i^\top z_j}{\tau}
403
+ $$
404
+
405
+ where $`z_i^\top z_j`$ is the dot product (cosine of the angle between the two
406
+ unit vectors) and $`\tau`$ rescales the similarities before the softmax.
407
+
408
+ Fix one example $`i`$, called the *anchor*. Its *positive set* is
409
+
410
+ $$
411
+ \large
412
+ \mathcal{P}(i) = \{\\, j : j \neq i \text{ and } y_j = y_i \\,\}
413
+ $$
414
+
415
+ i.e. all other examples in the batch that share the anchor's class label
416
+ $`y_i`$; every remaining example is a *negative*. SupCon averages the
417
+ log-softmax probability that the anchor assigns to each of its positives:
418
+
419
+ $$
420
+ \large
421
+ \mathcal{L}_i = -\frac{1}{|\mathcal{P}(i)|} \sum_{p \in \mathcal{P}(i)} \log \left( \frac{\exp(s_{ip})}{\sum_{a \neq i} \exp(s_{ia})} \right)
422
+ $$
423
+
424
+ $$
425
+ \large
426
+ \mathcal{L} = \frac{1}{B} \sum_{i=1}^{B} \mathcal{L}_i
427
+ $$
428
+
429
+ where:
430
+
431
+ - $`s_{ip}`$ — similarity between the anchor and positive $`p`$ (above);
432
+ - $`\sum_{a \neq i}`$ — sum over all other examples in the batch, positives
433
+ *and* negatives (the softmax denominator);
434
+ - $`|\mathcal{P}(i)|`$ — the number of positives for the anchor;
435
+ - $`B`$ — the batch size; the total loss averages the per-anchor terms.
436
+
437
+ Minimizing $`\mathcal{L}`$ pushes $`s_{ip}`$ up for same-class pairs and down
438
+ for different-class pairs. A lower temperature makes the distribution sharper:
439
+ this
440
+ can help separate hard negatives but can also make optimization less stable.
441
+ `--samples_per_class` matters because an anchor needs another example of its
442
+ class to have a positive. A class represented once contributes no useful
443
+ SupCon term for that anchor.
444
+
445
+ #### Temperature
446
+
447
+ The division by $`\tau`$ (`--temperature`, default 0.07) above, and the two
448
+ temperatures used by DINO below, all do the same job. Softmax over logits
449
+ $`s`$ becomes
450
+
451
+ $$
452
+ \large
453
+ \mathrm{softmax}(s)_j = \frac{\exp(s_j / \tau)}{\sum_k \exp(s_k / \tau)}
454
+ $$
455
+
456
+ A small $`\tau`$ divides every logit by a tiny number, so exponentials grow
457
+ very fast and the distribution concentrates on the maximum (sharp); a large
458
+ $`\tau`$ flattens it toward uniform. Sharpening amplifies small differences in
459
+ similarity, which speeds learning, but too-small $`\tau`$ makes gradients
460
+ vanish for non-maximum classes and destabilizes training. SupCon uses one
461
+ moderate value; DINO uses a small teacher temperature (sharper *targets*,
462
+ they are meant to be confident) and a larger student temperature (softer
463
+ *predictions*, easier to move).
464
+
465
+ **DINO** (self-**di**stillation with **no** labels): Caron et al.,
466
+ [Emerging Properties in Self-Supervised Vision Transformers](https://arxiv.org/abs/2104.14294), ICCV 2021.
467
+ One backbone is instantiated twice. The **student** $`f_\theta`$ is trained by
468
+ gradient descent; the **teacher** $`f_\xi`$ is the EMA copy of the student
469
+ ($`\xi \leftarrow m\\,\xi + (1-m)\\,\theta`$, as in I-JEPA above, ramped from
470
+ `--dino_momentum` 0.996 to `--dino_final_momentum` 1.0). Each image is cut
471
+ into 2 **global** crops plus `--dino_local_num` (8) small **local** crops:
472
+ the teacher sees only global views, the student sees all of them, so the
473
+ student must produce globally consistent features from partial views.
474
+
475
+ Both towers end in an MLP projection head whose output is turned into a
476
+ probability vector over the projection dimension. The teacher's distribution
477
+ is *sharpened* by its small temperature and *centered* by a running mean
478
+ $`c \in \mathbb{R}^{D}`$ updated once per step,
479
+
480
+ $$
481
+ \large
482
+ c \leftarrow m_c \\, c + (1 - m_c) \cdot \frac{1}{B}\sum_{i=1}^{B} f_\xi(x_i)
483
+ $$
484
+
485
+ (`--dino_center_momentum` 0.9), and the loss is the cross-entropy between the
486
+ teacher's processed distribution $`p_\xi`$ and the student's $`p_\theta`$,
487
+ averaged over all (teacher global, student crop) pairings:
488
+
489
+ $$
490
+ \large
491
+ \mathcal{L} = - \sum_{j} p_{\xi,j} \\, \log p_{\theta,j}
492
+ $$
493
+
494
+ Centering and sharpening are the two anti-collapse mechanisms: centering
495
+ cancels any component the teacher produces for *every* input (a constant
496
+ output carries no information and would otherwise still lower the loss), and
497
+ sharpening makes the teacher confident, forcing the student to truly reproduce
498
+ its argmax rather than drifting toward a flat, uninformative distribution.
499
+ Because the targets come from the teacher and the teacher follows the student,
500
+ this is self-distillation — there are no external labels anywhere.
501
+
502
+ **BYOL** (**B**ootstrap **Y**our **O**wn **L**atent): Grill et al.,
503
+ [Bootstrap Your Own Latent](https://arxiv.org/abs/2006.07733), NeurIPS 2020.
504
+ The same two-tower idea as DINO but with two augmented views and no
505
+ multi-crop. The **online** network (encoder + projector + predictor MLP) and
506
+ the **target** network (encoder + projector, EMA copy) process the two views;
507
+ only the online tower receives gradients. With $`z_1, z_2`$ the target
508
+ projections of the two views and $`p_1, p_2`$ the online *predictions* of
509
+ those projections, the loss is the symmetric cosine regression
510
+
511
+ $$
512
+ \large
513
+ \mathcal{L} = 2 - \cos(p_1, z_2) - \cos(p_2, z_1)
514
+ $$
515
+
516
+ which is 0 when predictions perfectly match target projections and reaches 4
517
+ when they point in opposite directions; $`\cos(u,v) = u^\top v / (\lVert u
518
+ \rVert_2 \lVert v \rVert_2)`$ is the cosine of the angle between the two
519
+ vectors. Two asymmetries keep this from collapsing to a constant: the
520
+ predictor exists only on the online side (predicting a target is easier than
521
+ being one), and the targets move slowly under the EMA — exactly the
522
+ teacher-follows-student trick noted under I-JEPA.
523
+
524
+ ### Typical Hyperparameters
525
+
526
+ These are reasonable starting points. Tune from here based on your dataset
527
+ size and GPU memory:
528
+
529
+ | Parameter | SimMIM | I-JEPA | DINO | BYOL | SupCon |
530
+ |---|---|---|---|---|---|
531
+ | `--image_size` | 448 | 448 | 224 | 224 | 448 |
532
+ | `--batch_size` | 32 | 32 | 64 | 64 | 64 |
533
+ | `--lr` | 1e-4 | 1e-4 | 5e-4 | 5e-4 | 1e-4 |
534
+ | `--epochs` | 200 | 200 | 100 | 100 | 100 |
535
+ | `--scheduler` | CosineAnnealingLR | CosineAnnealingLR | CosineAnnealingLR | CosineAnnealingLR | CosineAnnealingLR |
536
+ | `--amp_dtype` | bfloat16 | bfloat16 | bfloat16 | bfloat16 | bfloat16 |
537
+ | `--mask_ratio` | 0.6 | — | — | — | — |
538
+ | `--teacher_momentum` | — | 0.996→1.0 | — | — | — |
539
+ | `--dino_momentum` | — | — | 0.996→1.0 | — | — |
540
+ | `--byol_momentum` | — | — | — | 0.996→1.0 | — |
541
+ | `--temperature` | — | — | — | — | 0.07 |
542
+ | `--samples_per_class` | — | — | — | — | 16 |
543
+
544
+ **Tips:**
545
+ - Start with 200 epochs for SimMIM/I-JEPA. DINO, BYOL, and SupCon converge
546
+ faster (~100).
547
+ - `--temperature 0.07` is the standard from the original SupCon paper.
548
+ Lower = sharper contrastive distribution; try 0.05–0.1.
549
+ - DINO and BYOL train on smaller crops (224) with a larger LR because their
550
+ loss acts on a small projection space rather than every pixel; the defaults
551
+ above match the method-specific `--dino_*` / `--byol_*` flags.
552
+ - `--samples_per_class 16` with `--batch_size 64` gives 4 classes per batch
553
+ on a 7-class dataset. batch_size need not be divisible by
554
+ samples_per_class; the remainder is spread evenly across the per-class
555
+ groups so each batch still contains exactly batch_size samples.
556
+ - Use `--amp_dtype bfloat16` if your GPU supports it (Ampere+). Otherwise
557
+ `float16` with GradScaler works too.
558
+
559
+ ### Example: Full Pre-Training Pipeline
560
+
561
+ ```bash
562
+ # Step 1: Pre-train with SimMIM on two large image collections.
563
+ # v4.2: pre-training is a *configuration* of the unified genml-kit-train
564
+ # CLI (--pipeline images + --method simmim), not a separate binary.
565
+ genml-kit-train --pipeline images --method simmim \
566
+ --model convvit \
567
+ --datasets "imagefolder/raw-photos" "imagefolder/more-photos" \
568
+ --image_size 448 \
569
+ --batch_size 32 \
570
+ --epochs 200 \
571
+ --lr 1e-4 \
572
+ --scheduler CosineAnnealingLR \
573
+ --sched_arg T_max=200 --sched_arg eta_min=1e-6 \
574
+ --amp_dtype bfloat16 \
575
+ --checkpoint ./checkpoints/convvit_simmim
576
+
577
+ # Step 2: Fine-tune on your labeled dataset
578
+ genml-kit-train --model convvit \
579
+ --dataset my-org/labeled-photos \
580
+ --label_column category \
581
+ --source_checkpoint ./checkpoints/convvit_simmim_latest.pt \
582
+ --epochs 100 \
583
+ --lr 3e-5 \
584
+ --batch_size 32 \
585
+ --amp_dtype bfloat16
586
+ ```
587
+
588
+ ### Example: Supervised Contrastive Pre-Training
589
+
590
+ ```bash
591
+ genml-kit-train --pipeline images --method supcon \
592
+ --model convvit \
593
+ --datasets my-org/labeled-photos \
594
+ --label_column category \
595
+ --image_size 448 \
596
+ --batch_size 64 \
597
+ --samples_per_class 16 \
598
+ --proj_dim 128 \
599
+ --temperature 0.07 \
600
+ --epochs 100 \
601
+ --lr 1e-4 \
602
+ --amp_dtype bfloat16 \
603
+ --checkpoint ./checkpoints/convvit_supcon
604
+
605
+ # Then fine-tune as above with --source_checkpoint ./checkpoints/convvit_supcon_latest.pt
606
+ ```
607
+
608
+ ### Pre-Training CLI Reference
609
+
610
+ | Argument | Default | Description |
611
+ |---|---|---|
612
+ | `--method` | `classification` | Objective. The pre-training examples below pass `--method simmim` explicitly. Choices: `classification`, `simmim`, `ijepa`, `dino`, `byol`, `supcon`, `vo_pair`. |
613
+ | `--model` | `convvit` | Model name registered in genml_kit or HuggingFace model ID. |
614
+ | `--datasets` | (required) | Space-separated dataset names or local paths. |
615
+ | `--cache_dir` | `None` | HuggingFace cache directory for downloads. |
616
+ | `--remote_checkpoint` | `None` | Remote URI for checkpoint sync (`gs://BUCKET/PREFIX`, `r2://BUCKET/PREFIX`, or `s3://BUCKET/PREFIX`). |
617
+ | `--hf_token` | `None` | HuggingFace token for gated datasets (or set `HF_TOKEN` env var). |
618
+ | `--image_column` | auto-detected | Explicit HF image column name. |
619
+ | `--label_column` | `None` | Explicit HF label column name. Required by `--method supcon` if non-standard. |
620
+ | `STRICT_DATASETS` (env) | `False` | Abort on first dataset-loading failure instead of skipping. |
621
+ | `--image_size` | `448` | Input image size (square). |
622
+ | `--batch_size` | `32` | Per-GPU batch size. |
623
+ | `--seed` | `None` | Explicit RNG seed: pins the shuffling and enables full determinism (cuDNN deterministic kernels, benchmark off). Omit (default) to keep runs fast — RNG streams are still seeded from `$GENML_KIT_SEED` (default 42). See [Reproducibility](#reproducibility). |
624
+ | `--epochs` | `5` | Number of epochs. The recipes below override this for pre-training. |
625
+ | `--lr` | `3e-5` | Peak learning rate (base). The recipes below override this. |
626
+ | `--amp_dtype` | `None` | Mixed precision: `float16` or `bfloat16`. Omit to disable. |
627
+ | `--num_workers` | `4` | DataLoader worker processes. |
628
+ | `--device` | auto-detect | Device: `cpu`, `cuda`, or `cuda:INDEX`. |
629
+ | `--resume` | `True` | Auto-resume from latest checkpoint. Use `--no-resume` to disable. |
630
+ | `--state_save` | `opt,sched,amp` | States to save: `opt`, `sched`, `amp`, `none`. |
631
+ | `--state_load` | `opt,sched,amp` | States to restore on resume: `opt`, `sched`, `amp`, `none`. |
632
+ | `--checkpoint` | (required) | Checkpoint path prefix (saves `_latest.pt` and `_best.pt`). |
633
+ | `--log_level` | `INFO` | Minimum logging level. |
634
+ | `--log_targets` | `STDERR` | Comma-separated log destinations. `STDERR` logs to standard error; any other entry is a log file path (appended). Example: `STDERR,/tmp/train.log` logs to both. |
635
+ | `--grad_monitor` | `-1` | Log gradient statistics every N steps; `-1` disables. See [Gradient Monitor](#gradient-monitor). |
636
+ | `--norm_history` | `0` | Keep last N norm snapshots per parameter for trend analysis. |
637
+ | `--trend_top_n` | `10` | Show top N params in trend table by abs change %. `0` = show all. |
638
+ | `--grad_clip` | `1.0` | Maximum gradient norm for clipping. `0` disables. |
639
+ | `--lr_group` | `None` | Per-parameter-group learning rates (repeatable). Format: `"REGEX=LR"`. |
640
+ | `--llrd_decay` | `None` | Layer-wise learning rate decay factor. |
641
+ | `--vis_every` | `0` | Log reconstruction visualisation every N steps (SimMIM only). |
642
+ | `--save_every` | `500` | Save checkpoint every N optimizer steps. 0 disables. |
643
+ | `--model_arg` | `{}` | Override model configuration (repeatable). For `--model cls_model_wrapper:<hf_name>` the classifier head travels here too: `--model_arg classifier=mlp:hidden=512,dropout=0.3`. |
644
+ | `--proc_arg` | `{}` | Override processor configuration (repeatable). |
645
+ | `--optimizer` | `AdamW` | `torch.optim` optimizer class name or `.py` script path. |
646
+ | `--opt_arg` | `{}` | Extra optimizer kwargs (repeatable). |
647
+ | `--scheduler` | `None` | `torch.optim.lr_scheduler` class name or `.py` script path. |
648
+ | `--sched_arg` | `{}` | Extra scheduler kwargs (repeatable). |
649
+ | `--source_checkpoint` | `None` | Path to source checkpoint to absorb parameters from. |
650
+ | `--param_rename` | `None` | Regex-based key rename patterns (`SEARCH;REPLACE`). |
651
+ | `--grad_checkpoint` | `False` | Enable gradient checkpointing. Reduces activation memory by ~40-50% at the cost of ~25-35% more compute per step. Enables larger batch sizes. See [Gradient Checkpointing](#gradient-checkpointing). |
652
+
653
+ **Defaults shown are the generic `genml-kit-train` defaults; the
654
+ pre-training recipes below override `--method`, `--epochs`, `--lr` for their
655
+ specific objective.** The pre-training examples invoke
656
+ `genml-kit-train --pipeline images --method simmim ...` explicitly.
657
+
658
+ **SupCon-specific arguments:**
659
+
660
+ | Argument | Default | Description |
661
+ |---|---|---|
662
+ | `--proj_dim` | `128` | Output dimensionality of the projection head. |
663
+ | `--proj_hidden` | `None` | Hidden layer size of the projection MLP. `None` = single linear layer. |
664
+ | `--temperature` | `0.07` | NT-Xent temperature. Lower = sharper contrastive distribution. |
665
+ | `--samples_per_class` | `16` | Samples per class in each batch. Batch size need not be divisible by this; the remainder is spread evenly across the per-class groups. |
666
+
667
+ ### Dataset Ensemble
668
+
669
+ With `--pipeline images`, `genml-kit-train` stitches multiple datasets into
670
+ a single pre-training corpus (via `--datasets`). This is useful because no
671
+ single dataset is large enough for effective pre-training on its own.
672
+
673
+ Supported dataset types:
674
+ - **HuggingFace datasets** — any HF dataset ID that returns decoded image
675
+ data (e.g. `cifar10`, `food101`). Gated datasets require `--hf_token` or
676
+ `HF_TOKEN`.
677
+ - **Local image directories** — pass a path to a folder of images
678
+ (ImageFolder format).
679
+
680
+ Datasets are loaded lazily (only when first accessed). By default, datasets
681
+ that fail to load are logged and skipped (best-effort mode). Set the
682
+ `STRICT_DATASETS` environment variable to a truthy value (`1`, `true`,
683
+ `yes`, `on`) to abort on the first failure instead.
684
+
685
+ Images that cannot be decoded are skipped with a warning — this prevents a
686
+ single corrupted file from blocking an entire pre-training run.
687
+
688
+ #### Label Validation
689
+
690
+ When using a label-aware method (`--method supcon`), the ensemble validates
691
+ that every dataset supports labels. Datasets without a label column cause a
692
+ clear error *before* training begins, not a cryptic runtime failure mid-epoch.
693
+
694
+ Labels are automatically remapped to a shared global label space across all
695
+ datasets, so mixing datasets with overlapping but differently-named classes
696
+ works transparently.
697
+
698
+ ### Preparing Datasets
699
+
700
+ Some datasets store images inside zip archives or need custom preprocessing
701
+ before they can be used for pre-training. The toolkit consumes any local
702
+ ImageFolder directory, so a small preparation script is all it takes:
703
+
704
+ ```bash
705
+ python my_prepare_script.py --output_dir ./prepared_images
706
+ ```
707
+
708
+ Then use the extracted directory as a local dataset:
709
+
710
+ ```bash
711
+ genml-kit-train --pipeline images --method simmim \
712
+ --datasets ./prepared_images ./other-images \
713
+ --image_size 448 --batch_size 32 ...
714
+ ```
715
+
716
+ For a concrete worked example of such a preparation script, see
717
+ `scdiag/scripts/prepare_derm1m.py` and `scdiag/scripts/prepare_ham10000.py`
718
+ in the repository (dermoscopy corpora).
719
+
720
+ ---
721
+
722
+ ## Fine-Tuning Guide
723
+
724
+ After pre-training (or directly, if you skip pre-training), fine-tune a
725
+ classifier on your labeled dataset.
726
+
727
+ ### What Fine-Tuning Is Changing
728
+
729
+ Suppose the encoder produces the feature vector $`h = f_\theta(x)`$. A linear
730
+ classification head computes logits $`a = W h + b`$, and softmax turns them
731
+ into probabilities:
732
+
733
+ $$
734
+ \large
735
+ p(y=c \mid x) = \frac{\exp(a_c)}{\sum_k \exp(a_k)}
736
+ $$
737
+
738
+ where:
739
+
740
+ - $`h \in \mathbb{R}^{D}`$ — the encoder's feature vector for image $`x`$;
741
+ - $`W \in \mathbb{R}^{C \times D}`$, $`b \in \mathbb{R}^{C}`$ — the head's weight
742
+ matrix and bias ($`C`$ = number of classes, $`D`$ = feature dimension);
743
+ - $`a_c`$ — the logit (raw score) for class $`c`$;
744
+ - $`p(y=c \mid x)`$ — the model's probability that the class of $`x`$ is
745
+ $`c`$; the softmax exponentials make the scores positive and summing to one.
746
+
747
+ Training minimizes cross-entropy between the model's predicted distribution
748
+ $`p`$ and the target distribution $`q`$ over the $`C`$ classes,
749
+
750
+ $$
751
+ \large
752
+ \mathcal{L}_{\text{CE}}(p, q) = -\sum_{c=1}^{C} q_c \log p_c
753
+ $$
754
+
755
+ For a hard label the target $`q`$ is a one-hot vector, so only the term of the
756
+ true class survives and the loss reduces to the familiar $`-\log p(y \mid x)`$.
757
+ genml_kit generalizes this in three directions via `CombinedFocalLoss`:
758
+
759
+ - **Soft targets.** With Mixup (below) $`q`$ is the blend
760
+ $`\lambda\\, y_i + (1-\lambda)\\, y_j`$, and the sum keeps both classes'
761
+ terms weighted by $`\lambda`$ and $`1-\lambda`$.
762
+ - **Label smoothing** (via `--loss_args '{"label_smoothing": ...}'`):
763
+ the one-hot target is replaced by
764
+ $`q_c = 1 - \varepsilon + \varepsilon/C`$ for the true class and
765
+ $`\varepsilon/C`$ for the others. The model is no longer asked to drive
766
+ $`p_c \to 1`$ exactly, which reduces overconfidence and improves
767
+ calibration on validation data.
768
+ - **Class weights** (`--class_multipliers`): each term of the sum is scaled by
769
+ a per-class factor $`w_c`$, so rare classes contribute larger gradients.
770
+
771
+ The new classifier head is normally initialized from scratch because
772
+ its output
773
+ size depends on the target classes. When loading a pre-training checkpoint,
774
+ the useful part to transfer is the encoder; an unused SupCon projection head
775
+ should not be copied into the classifier.
776
+
777
+ The practical choice is how much of $`\theta`$ to update:
778
+
779
+ - **Full fine-tuning** updates encoder and head. It gives the model the most
780
+ freedom, but needs enough data and a conservative learning rate.
781
+ - **Frozen-backbone training** updates only the head. It is a useful baseline
782
+ for small datasets and shows how much information the representation holds.
783
+ - **LLRD** updates all layers but gives early layers smaller learning rates.
784
+ This is often a good compromise when the pre-training domain differs from
785
+ the fine-tuning domain (e.g. ImageNet to specialized imagery).
786
+ - **LoRA** freezes the original matrices and learns small low-rank updates.
787
+ It is useful when GPU memory or labeled data is limited.
788
+
789
+ Compare these strategies on the same validation split. The lowest training
790
+ loss is not necessarily the best model: monitor macro-F1, balanced accuracy,
791
+ weighted F1, and per-class precision and recall, especially for minority
792
+ classes.
793
+
794
+ ### Evaluation Metrics
795
+
796
+ Validation reports include:
797
+
798
+ - **Top-1 accuracy:** the percentage of validation images assigned the correct
799
+ class by the highest-probability prediction.
800
+ - **Precision:** for a class, the fraction of images predicted as that class
801
+ that truly belong to it:
802
+ $`\text{precision} = TP / (TP + FP)`$.
803
+ - **Recall:** for a class, the fraction of images belonging to that class that
804
+ are predicted correctly: $`\text{recall} = TP / (TP + FN)`$.
805
+ Here $`TP`$ (true positives) counts images of the class that were correctly
806
+ predicted as that class, $`FP`$ (false positives) counts images of *other*
807
+ classes wrongly predicted as this class, and $`FN`$ (false negatives) counts
808
+ images of this class wrongly predicted as something else.
809
+ - **F1:** the harmonic mean of precision and recall:
810
+ $`F_1 = \frac{2 \cdot \text{precision} \cdot \text{recall}}{\text{precision} + \text{recall}}`$.
811
+ When the denominator is zero, scikit-learn's `zero_division=0` behavior
812
+ reports zero.
813
+ - **Macro F1:** the arithmetic mean of the per-class F1 scores:
814
+ $`F_{1}^{\text{macro}} = \frac{1}{C} \sum_{c=1}^{C} F_{1,c}`$.
815
+ Every class contributes equally, regardless of its validation-set size
816
+ ($`C`$ is the number of classes, $`F_{1,c}`$ the F1 of class $`c`$).
817
+ This is the metric used for best-checkpoint selection.
818
+ - **Weighted F1:** the mean of per-class F1 scores weighted by each class's
819
+ validation support. It is therefore more influenced by common classes.
820
+ - **Balanced accuracy:** the arithmetic mean of per-class recall:
821
+ $`\text{balanced accuracy} = \frac{1}{C} \sum_{c=1}^{C} \text{recall}_c`$.
822
+ It gives each class equal weight and is useful for imbalanced datasets.
823
+ - **Support:** the number of true validation examples for a class.
824
+
825
+ The confusion matrix uses rows for true classes and columns for predicted
826
+ classes. Diagonal entries are correct predictions. The compact confusion
827
+ summary reports each class's recall and its largest confusion destinations.
828
+
829
+
830
+ When TTA is enabled, validation loss is computed from the original image only,
831
+ while Top-1 accuracy, balanced accuracy, macro F1, weighted F1, and per-class
832
+ metrics use probabilities averaged over the original image and augmented
833
+ views. The log also reports original-view metrics and the change produced by
834
+ TTA.
835
+
836
+ Training metrics may be measured on an augmented or weighted-sampler stream.
837
+ They should not be compared directly with validation metrics unless they use
838
+ the same sampling and preprocessing scheme.
839
+
840
+ ### Basic Fine-Tuning
841
+
842
+ ```bash
843
+ genml-kit-train --model google/vit-base-patch16-224 \
844
+ --dataset my-org/my-labeled-images \
845
+ --label_column category \
846
+ --epochs 5 \
847
+ --batch_size 32 \
848
+ --lr 3e-5 \
849
+ --image_size 224
850
+ ```
851
+
852
+ ### With A Custom Classifier Head
853
+
854
+ Replace the default linear head with a custom MLP or attention-based
855
+ classifier:
856
+
857
+ ```bash
858
+ # Freeze backbone, train only the custom head
859
+ genml-kit-train --model cls_model_wrapper:google/vit-base-patch16-224 \
860
+ --dataset my-org/my-labeled-images \
861
+ --label_column category \
862
+ --model_arg classifier=mlp:hidden=512,dropout=0.3 \
863
+ --freeze ".*\.(head|pool)"
864
+ ```
865
+
866
+ ### With LoRA (Parameter-Efficient Fine-Tuning)
867
+
868
+ Freeze the entire backbone and train only small low-rank adapter matrices.
869
+ Reduces trainable parameters by ~97% while often matching full fine-tuning:
870
+
871
+ ```bash
872
+ genml-kit-train \
873
+ --model cls_model_wrapper:facebook/dinov2-with-registers-large \
874
+ --lora --lora_r 16 --lora_alpha 32 \
875
+ --lora_target_modules "query,key,value" \
876
+ --freeze "classifier\.(head|pool|encoder)" \
877
+ --lr 3e-5 \
878
+ --dataset my-org/my-labeled-images \
879
+ --label_column category \
880
+ --epochs 20
881
+ ```
882
+
883
+ ### From A Pre-Trained Checkpoint
884
+
885
+ Load encoder weights from a pre-training run (SimMIM, I-JEPA, or SupCon):
886
+
887
+ ```bash
888
+ genml-kit-train --model convvit \
889
+ --dataset my-org/my-labeled-images \
890
+ --label_column category \
891
+ --source_checkpoint ./checkpoints/convvit_simmim_latest.pt \
892
+ --epochs 100
893
+ ```
894
+
895
+ The backbone weights are loaded automatically; the classifier head is
896
+ reinitialised (different `num_classes`). Use `--state_load none` to avoid
897
+ carrying over old optimizer/scheduler states.
898
+
899
+ ### Layer-Wise Learning Rate Decay (LLRD)
900
+
901
+ LLRD is a compromise between freezing the backbone and updating every layer at
902
+ the same speed. If layers are indexed from shallow 0 to deep $`L`$, a common
903
+ schedule is (introduced by Howard & Ruder, [Universal Language Model Fine-tuning](https://arxiv.org/abs/1801.06146), ACL 2018):
904
+
905
+ $$
906
+ \large
907
+ \text{lr}(\text{layer}) = \text{lr}_{\text{base}} \cdot d^{\\,L - \text{layer}}
908
+ $$
909
+
910
+ where:
911
+
912
+ - $`\text{lr}_{\text{base}}`$ — the `--lr` you pass on the command line;
913
+ - $`d`$ — the decay factor (`--llrd_decay`), usually between 0.8 and 1.0;
914
+ - $`L`$ — the index of the deepest layer, $`\text{layer}`$ the current layer's
915
+ index, both counted from 0 at the input side.
916
+
917
+ The deepest layer
918
+ receives the base rate while earlier layers receive smaller updates. Early
919
+ layers tend to represent general edges and textures; later layers are more
920
+ task-specific. This is a useful heuristic, not a law, so validate it on your
921
+ dataset. A very small decay factor can effectively freeze the shallow network.
922
+
923
+ ### Cosine Annealing
924
+
925
+ `--scheduler CosineAnnealingLR` (the default in every example above) decays
926
+ the learning rate from its initial value $`\eta_{\max}`$ toward $`\eta_{\min}`$
927
+ (0 by default) following a half cosine wave over `--epochs` epochs $`T`$:
928
+
929
+ $$
930
+ \large
931
+ \eta(t) = \eta_{\min} + \frac{1}{2}\left(\eta_{\max} - \eta_{\min}\right)
932
+ \left(1 + \cos\left(\frac{t \pi}{T}\right)\right)
933
+ $$
934
+
935
+ where $`t`$ is the current epoch. The cosine shape spends more time at high
936
+ learning rates than a linear decay — useful early, when large steps explore
937
+ the loss surface — and slows down smoothly as it approaches zero, which lets
938
+ the model settle into a minimum instead of bouncing around it. Late-training
939
+ low learning rates are also what make the EMA teacher of DINO/BYOL
940
+ effective: the teacher tracks a student that changes gently.
941
+
942
+ ### Mixup, Label Smoothing, And Imbalance
943
+
944
+ Mixup forms a virtual example from two training examples.
945
+ Reference: Zhang et al., [mixup: Beyond Empirical Risk Minimization](https://arxiv.org/abs/1710.09412), ICLR 2018.
946
+
947
+ $$
948
+ \large
949
+ \tilde{x} = \lambda x_i + (1 - \lambda) x_j
950
+ $$
951
+
952
+ $$
953
+ \large
954
+ \tilde{y} = \lambda y_i + (1 - \lambda) y_j
955
+ $$
956
+
957
+ where $`(x_i, y_i)`$ and $`(x_j, y_j)`$ are two randomly paired training
958
+ examples and the mixing coefficient $`\lambda`$ is drawn from the Beta
959
+ distribution, $`\lambda \sim \mathrm{Beta}(\alpha, \alpha)`$, with $`\alpha`$
960
+ set by `--mixup_alpha` (typical values 0.2–0.4). The parameter $`\alpha`$
961
+ shapes the distribution: small $`\alpha`$ puts most weight near 0 or 1,
962
+ large $`\alpha`$ near 1/2. The labels are probability vectors, not
963
+ class indices. Mixup smooths the decision boundary and can help on small
964
+ datasets, but strong Mixup can obscure fine-grained image details. Label
965
+ smoothing similarly replaces a one-hot label with a mostly-correct
966
+ distribution.
967
+
968
+ #### Focal Loss
969
+
970
+ Focal loss instead changes the emphasis of cross-entropy. Reference: Lin et
971
+ al., [Focal Loss for Dense Object Detection](https://arxiv.org/abs/1708.02002), ICCV 2017.
972
+ With a hard label and $`p_t`$ the predicted probability of the correct class,
973
+ its basic form is
974
+
975
+ $$
976
+ \large
977
+ \mathcal{L}_{\text{focal}} = -(1 - p_t)^{\gamma} \log(p_t)
978
+ $$
979
+
980
+ where $`\gamma`$ (via `--loss_args '{"gamma": ...}'`) down-weights easy examples: when
981
+ $`p_t \to 1`$ the factor $`(1-p_t)^{\gamma} \to 0`$, so already-confident,
982
+ easy examples receive almost no weight and training focuses on hard ones.
983
+ With $`\gamma = 0`$ the factor is 1 for every example and the loss is plain
984
+ cross-entropy; typical values are 1–3, and 2.0 is the usual default.
985
+
986
+ genml_kit implements the general form (`CombinedFocalLoss` in
987
+ `genml_kit/losses/focal.py`), which composes cleanly with the other
988
+ tools in this section. Let $`q`$ be the target distribution from the previous
989
+ step (one-hot, Mixup-blended, or label-smoothed), $`w_c`$ the per-class
990
+ multipliers (`--class_multipliers`), and $`p`$ the model's softmax output.
991
+ The loss for one example is
992
+
993
+ $$
994
+ \large
995
+ \mathcal{L} = \left(1 - p_t\right)^{\gamma} \sum_{c=1}^{C} w_c\\, q_c
996
+ \left(-\log p_c\right), \qquad p_t = \sum_{c=1}^{C} q_c\\, p_c
997
+ $$
998
+
999
+ Two details matter for the reader combining these flags:
1000
+
1001
+ - **Unified $`p_t`.** The modulating factor uses the *expected* probability
1002
+ under the target distribution, $`p_t = \sum_c q_c p_c`$, rather than the
1003
+ probability of a single class. For a one-hot target $`q`$ this reduces
1004
+ exactly to the basic form above ($`p_t`$ becomes the correct-class
1005
+ probability); with Mixup soft targets it blends the two classes'
1006
+ probabilities, giving one smooth modulation per example instead of an
1007
+ arbitrary single-class choice.
1008
+ - **One modulation per example.** The factor $`(1-p_t)^{\gamma}`$ scales the
1009
+ whole weighted cross-entropy sum — weights and soft labels act *inside* the
1010
+ sum, focal acts *outside* it. Each term is therefore attenuated
1011
+ proportionally to how confident the model already is about that example, no
1012
+ matter which class the probability mass sits on.
1013
+
1014
+ Use these tools deliberately; combining every regularizer is not
1015
+ automatically better.
1016
+
1017
+ ### Hyperparameter Guidance
1018
+
1019
+ | Scenario | `--lr` | `--epochs` | `--batch_size` | Notes |
1020
+ |---|---|---|---|---|
1021
+ | Large dataset (>10k images) | 3e-5 | 20–50 | 32–64 | Standard fine-tuning |
1022
+ | Small dataset (<1k images) | 1e-5 | 50–100 | 16–32 | Consider LoRA, stronger augmentation |
1023
+ | From pre-trained checkpoint | 3e-5 | 50–100 | 32 | Lower LR than from scratch |
1024
+ | Custom classifier head only | 1e-3 | 50–200 | 32 | Higher LR since only head trains |
1025
+
1026
+ **Tips:**
1027
+ - Start with `--lr 3e-5` for full fine-tuning, `1e-3` for head-only training.
1028
+ - Use `--mixup_alpha 0.2` for small datasets — it helps prevent overfitting.
1029
+ - `--loss_args '{"gamma": 2.0}'` down-weights easy examples, useful when
1030
+ classes are imbalanced.
1031
+ - `--class_multipliers "rare_class=3.0"` increases the loss weight for
1032
+ safety-critical or otherwise priority classes.
1033
+
1034
+ ### Reproducibility
1035
+
1036
+ RNG streams are always seeded. By default the seed comes from the
1037
+ `GENML_KIT_SEED` environment variable (default `42`), and it drives
1038
+ DataLoader shuffling, per-worker augmentation randomness, mixup, and
1039
+ dropout — the user not caring about determinism does not mean the
1040
+ toolkit runs on entropy. To compare hyperparameters under a different
1041
+ random draw, change `GENML_KIT_SEED` or pass an explicit seed.
1042
+
1043
+ Two levels of determinism:
1044
+
1045
+ | Invocation | Seeding | CUDA kernels | Reproducible? |
1046
+ |---|---|---|---|
1047
+ | default (no `--seed`) | `GENML_KIT_SEED` or 42 | `cudnn.benchmark=True` (fastest algorithms) | RNG streams identical; arithmetic not bit-exact |
1048
+ | `--seed 42` | 42 everywhere | cuDNN deterministic mode, benchmark off, deterministic algorithms | bit-exact |
1049
+
1050
+ Passing an explicit `--seed` therefore buys full determinism at a
1051
+ throughput cost (typically 10–20%); omit it for maximum speed:
1052
+
1053
+ ```bash
1054
+ genml-kit-train --model convvit --seed 42 ...
1055
+ ```
1056
+
1057
+ The train/val split and the XGBoost stage follow the user's seed: with
1058
+ `--seed` given they are pinned; without it they draw fresh entropy each
1059
+ run (HF `train_test_split(seed=None)`, XGBoost `random_state=None`).
1060
+
1061
+ Two caveats:
1062
+
1063
+ - Some CUDA ops have no deterministic kernel. Instead of aborting a
1064
+ long-running job, genml_kit logs a warning and proceeds (the op falls
1065
+ back to a non-deterministic kernel).
1066
+ - `float16` AMP with `GradScaler` involves non-associative reductions
1067
+ that can still differ run-to-run; use `bfloat16` (default on
1068
+ Ampere+) or disable AMP for strictly repeatable arithmetic.
1069
+
1070
+ Checkpointing is atomic: `_latest.pt` is written to a temporary file
1071
+ and renamed into place, so an interrupted run never leaves a truncated
1072
+ resume point.
1073
+
1074
+ ### Fine-Tuning CLI Reference
1075
+
1076
+ | Argument | Default | Description |
1077
+ |---|---|---|
1078
+ | `--model` | `google/vit-base-patch16-224` | HuggingFace model name, local path, or custom model (e.g. `convvit`, `timm:<name>`). |
1079
+ | `--dataset` | required | HuggingFace dataset name or `imagefolder/PATH` for local data. |
1080
+ | `--image_column` | auto-detected | Explicit HF image column name. |
1081
+ | `--label_column` | auto-detected | Explicit HF label column name. |
1082
+ | `--image_size` | `448` | Augmentation crop size (processor handles final resize). |
1083
+ | `--epochs` | `5` | Number of training epochs. |
1084
+ | `--batch_size` | `32` | Batch size. |
1085
+ | `--lr` | `3e-5` | Peak learning rate. |
1086
+ | `--weight_decay` | `0.01` | Weight decay. |
1087
+ | `--loss` | `None` | Loss spec: registered name (`focal`, `supcon`, or the RL bundles `ppo`/`sac`/`dqn`) or a path/URL to a `.py` script defining `build_loss(**kwargs)`. `None` (default) selects the method's built-in loss. |
1088
+ | `--loss_args` | `{}` | JSON kwargs forwarded to the loss builder. Example: `'{"gamma": 1.0, "label_smoothing": 0.1}'`. |
1089
+ | `--class_multipliers` | `""` | Per-class priority multipliers. Example: `"cat=3.0,dog=1.0"`. |
1090
+ | `--sampler` | `none` | Training sampler: `none` (shuffle), `weighted` (WeightedRandomSampler for class imbalance), or `balanced` (equal samples per class per batch; batch_size need not divide evenly). |
1091
+ | `--sampler_weights` | `frequency` | Weight mode for `--sampler weighted`: `frequency` (inverse-freq), `multipliers` (--class_multipliers), or `combined` (freq × multipliers). |
1092
+ | `--mixup_alpha` | `0.0` | Mixup alpha (`0` = disabled; recommended: `0.2`). |
1093
+ | `--seed` | `None` | Explicit RNG seed: pins the train/val split and the XGBoost stage and enables full determinism (cuDNN deterministic kernels, benchmark off). Omit (default) to keep runs fast — shuffling/mixup/dropout are still seeded from `$GENML_KIT_SEED` (default 42). See [Reproducibility](#reproducibility). |
1094
+ | `--grad_accum_steps` | `1` | Gradient accumulation steps (effective batch = batch_size × steps). |
1095
+ | `--amp_dtype` | `None` | Mixed precision: `float16` or `bfloat16`. |
1096
+ | `--device` | auto-detect | Device: `cpu`, `cuda`, or `cuda:INDEX`. |
1097
+ | `--lr_group` | `None` | Per-parameter-group learning rates (repeatable). Format: `"REGEX=LR"`. |
1098
+ | `--llrd_decay` | `None` | Layer-wise LR decay factor per depth level. Example: `--llrd_decay 0.85`. |
1099
+ | `--checkpoint` | `genml_kit` | Checkpoint base path (`_latest.pt` / `_best.pt` appended). |
1100
+ | `--log_every` | `20` | Log every N steps. |
1101
+ | `--grad_monitor` | `-1` | Log gradient statistics every N steps. See [Gradient Monitor](#gradient-monitor). |
1102
+ | `--norm_history` | `0` | Keep last N norm snapshots for trend analysis. |
1103
+ | `--trend_top_n` | `10` | Show top N params in trend table. `0` = show all. |
1104
+ | `--grad_clip` | `1.0` | Max gradient norm for clipping. `0` disables. |
1105
+ | `--save_every` | `500` | Save checkpoint every N optimizer steps. 0 disables. |
1106
+ | `--num_workers` | `2` | DataLoader worker processes. |
1107
+ | `--log_level` | `INFO` | Logging level. |
1108
+ | `--log_targets` | `STDERR` | Comma-separated log destinations. `STDERR` logs to standard error; any other entry is a log file path (appended). Example: `STDERR,/tmp/train.log` logs to both. |
1109
+ | `--log_dir` | `None` | TensorBoard log directory (default: `<checkpoint_dir>/logs`). Requires the `tensorboard` package (installed by the `dev` extra). |
1110
+ | `--cache_dir` | `None` | HuggingFace cache directory. |
1111
+ | `--remote_checkpoint` | `None` | Remote URI for checkpoint sync (`gs://BUCKET/PREFIX`, `r2://BUCKET/PREFIX`, or `s3://BUCKET/PREFIX`). |
1112
+ | `--source_checkpoint` | `None` | Path to source checkpoint to absorb parameters from. |
1113
+ | `--param_rename` | `None` | Regex-based key rename patterns (`SEARCH;REPLACE`). |
1114
+ | `--freeze` | `None` | Regex patterns for parameters to keep trainable. All others frozen. |
1115
+ | `--lora` | `False` | Enable LoRA via PEFT. Requires `pip install "genml_kit[lora]"`. |
1116
+ | `--lora_r` | `8` | LoRA rank. |
1117
+ | `--lora_alpha` | `16` | LoRA alpha (scaling = `alpha / r`). |
1118
+ | `--lora_dropout` | `0.0` | Dropout on LoRA layers. |
1119
+ | `--lora_target_modules` | `None` | Comma-separated module names for LoRA (e.g. `"query,key,value"`). |
1120
+ | `--optimizer` | `AdamW` | `torch.optim` optimizer class name or `.py` script path. |
1121
+ | `--opt_arg` | `{}` | Extra optimizer kwargs (repeatable). |
1122
+ | `--scheduler` | `None` | `torch.optim.lr_scheduler` class name or `.py` script path. |
1123
+ | `--sched_arg` | `{}` | Extra scheduler kwargs (repeatable). |
1124
+ | `--state_save` | `opt,sched,amp` | States to save: `opt`, `sched`, `amp`, `none`. |
1125
+ | `--state_load` | `opt,sched,amp` | States to restore on resume. |
1126
+ | `--xgboost_model` | `None` | Output path for XGBoost model (trains after PyTorch). |
1127
+ | `--xgb_*` | various | XGBoost hyperparameters (see `--help` for full list). |
1128
+ | `--model_arg` | `{}` | Override model configuration (repeatable). |
1129
+ | `--proc_arg` | `{}` | Override processor configuration (repeatable). |
1130
+ | `--train_augmentation_script` | `None` | Custom augmentation script. Must define `create_train_transform()`. |
1131
+ | `--grad_checkpoint` | `False` | Enable gradient checkpointing. Reduces activation memory by ~40-50% at the cost of ~25-35% more compute per step. Enables larger batch sizes. See [Gradient Checkpointing](#gradient-checkpointing). |
1132
+ | `--tta` | `None` | Test-Time Augmentation. `default` uses built-in 4-view transform (identity + flips). A path/URL loads an external script defining `create_tta_transform()`. Omit to disable. |
1133
+
1134
+ Training automatically resumes from an existing `_latest.pt` or `_best.pt`
1135
+ checkpoint if one exists at the `--checkpoint` path.
1136
+
1137
+ ### Remote Checkpoint Sync (GCS / R2 / S3)
1138
+
1139
+ `--remote_checkpoint` uploads each saved checkpoint to cloud storage.
1140
+ Requires `pip install "genml_kit[s3]"` for `s3://` and `r2://` URIs (both
1141
+ use boto3), or `genml_kit[gcs]` for `gs://`. The unified `genml-kit-train`
1142
+ CLI accepts the flag for every pipeline/method configuration.
1143
+
1144
+ The sync also works in reverse at startup: before auto-resume, any missing
1145
+ `_latest.pt` / `_best.pt` is downloaded from the remote prefix (latest is
1146
+ tried first, matching resume precedence). A locally present checkpoint is
1147
+ never overwritten — the local copy always wins — and connection or
1148
+ credential failures degrade to a warning instead of aborting startup.
1149
+
1150
+ **AWS S3** — credentials come from the standard environment variables:
1151
+
1152
+ ```bash
1153
+ %env AWS_ACCESS_KEY_ID=AKIA...
1154
+ %env AWS_SECRET_ACCESS_KEY=...
1155
+ %env AWS_SESSION_TOKEN=... # only for temporary (STS/SSO) credentials
1156
+ %env AWS_DEFAULT_REGION=us-east-1
1157
+
1158
+ --remote_checkpoint s3://my-bucket/genml_kit/convvit_ijepa
1159
+ ```
1160
+
1161
+ Permanent IAM-user keys need only the access/secret pair; the session
1162
+ token is picked up automatically when present. When the key variables
1163
+ are unset, boto3's default credential chain applies (IAM instance role,
1164
+ `~/.aws/credentials`, SSO cache).
1165
+
1166
+ **Cloudflare R2** — the S3-compatible API with R2 credentials:
1167
+
1168
+ ```bash
1169
+ %env R2_ENDPOINT_URL=https://<account_id>.r2.cloudflarestorage.com
1170
+ %env R2_ACCESS_KEY_ID=...
1171
+ %env R2_SECRET_ACCESS_KEY=...
1172
+
1173
+ --remote_checkpoint r2://my-bucket/genml_kit/convvit_ijepa
1174
+ ```
1175
+
1176
+ ### LoRA Details
1177
+
1178
+ Low-Rank Adaptation freezes the pre-trained backbone and injects small
1179
+ trainable low-rank matrices into attention layers.
1180
+ Reference: Hu et al., [LoRA: Low-Rank Adaptation of Large Language Models](https://arxiv.org/abs/2106.09685), ICLR 2022.
1181
+
1182
+ Instead of updating a weight matrix $`W`$ directly, LoRA keeps it frozen and
1183
+ adds a low-rank product to its output:
1184
+
1185
+ $$
1186
+ \large
1187
+ W' = W + \Delta W, \qquad \Delta W = \frac{\alpha}{r} \cdot B A
1188
+ $$
1189
+
1190
+ where:
1191
+
1192
+ - $`W \in \mathbb{R}^{d \times k}`$ — the frozen pre-trained weight matrix;
1193
+ - $`A \in \mathbb{R}^{r \times k}`$, $`B \in \mathbb{R}^{d \times r}`$ — the two
1194
+ small trainable matrices ($`BA`$ is a matrix product);
1195
+ - $`r`$ — the rank (`--lora_r`), much smaller than $`d`$ or $`k`$, which is
1196
+ what makes $`\Delta W`$ cheap: instead of $`d \times k`$ weights it trains
1197
+ only $`r(d + k)`$;
1198
+ - $`\alpha`$ — the scale factor (`--lora_alpha`); the effective step size of
1199
+ the update is $`\alpha / r`$.
1200
+
1201
+ Only $`A`$, $`B`$ (and the classifier head) receive gradients.
1202
+
1203
+ | r | alpha | alpha/r | Use case |
1204
+ |---|---|---|---|
1205
+ | 8 | 16 | 2.0 | Conservative, very few params |
1206
+ | 16 | 32 | 2.0 | Good default for medium datasets |
1207
+ | 16 | 64 | 4.0 | Larger updates (helpful under bfloat16) |
1208
+ | 32 | 64 | 2.0 | More capacity, same scaling |
1209
+
1210
+ LoRA can be combined with a custom classifier:
1211
+
1212
+ ```bash
1213
+ genml-kit-train \
1214
+ --model cls_model_wrapper:facebook/dinov2-with-registers-large \
1215
+ --model_arg classifier=cls_attention:num_encoder_layers=2 \
1216
+ --lora --lora_r 16 --lora_alpha 32 \
1217
+ --freeze 'classifier\.(head|pool|encoder)' \
1218
+ --lr_group 'backbone.*=1e-5' 'classifier.*=3e-4' \
1219
+ ...
1220
+ ```
1221
+
1222
+ ### Cross-Dataset Resume
1223
+
1224
+ Switch from one dataset to another while keeping backbone weights:
1225
+
1226
+ ```bash
1227
+ genml-kit-train --model facebook/convnextv2-base-22k-224 \
1228
+ --dataset my-org/other-labeled-images \
1229
+ --label_column category \
1230
+ --checkpoint genml_kit \
1231
+ --state_load none \
1232
+ --epochs 10 \
1233
+ --batch_size 16 \
1234
+ --lr 3e-5 \
1235
+ --mixup_alpha 0.2 \
1236
+ --amp_dtype bfloat16
1237
+ ```
1238
+
1239
+ Backbone weights load via `strict=False`; the classifier head (different
1240
+ `num_classes`) is reinitialised. `--state_load none` prevents carrying over
1241
+ old optimizer/scheduler states.
1242
+
1243
+ ### Gradient Checkpointing
1244
+
1245
+ Training deep vision transformers is memory-intensive: the attention maps for
1246
+ EVA02-base at 448×448 resolution consume ~4.6 GB across 12 layers, which
1247
+ limits the maximum batch size even on a 24 GB GPU. Gradient checkpointing
1248
+ trades compute for memory by discarding intermediate activations during the
1249
+ forward pass and recomputing them during the backward pass.
1250
+
1251
+ ```bash
1252
+ genml-kit-train \
1253
+ --model timm:eva02_base_patch14_448.mim_in22k_ft_in22k_in1k \
1254
+ --batch_size 32 \
1255
+ --grad_accum_steps 2 \
1256
+ --grad_checkpoint \
1257
+ --amp_dtype bfloat16 \
1258
+ ...
1259
+ ```
1260
+
1261
+ **What it does:** Each transformer block stores only its input and output.
1262
+ The intra-block activations (attention maps, FFN intermediates) are
1263
+ recomputed on-demand during the backward pass. This reduces peak activation
1264
+ memory by ~40-50%.
1265
+
1266
+ **What it costs:** The recomputation adds ~25-35% more compute per training
1267
+ step. Whether this translates to a net throughput gain or loss depends on
1268
+ your GPU:
1269
+ - **Memory-bound GPU** (VRAM-limited, compute underutilized): larger batches
1270
+ fill the GPU's compute capacity → net throughput **increase** of ~50-60%.
1271
+ - **Compute-saturated GPU** (TFLOPS at 100%): every extra FLOP adds to step
1272
+ time → net throughput **decrease** of ~20-25%, though the larger batch can
1273
+ still improve training stability and final accuracy.
1274
+
1275
+ **Backend support:** Enabled automatically for all model backends — timm,
1276
+ HuggingFace, ConvViT, and UVito — via native APIs or per-block
1277
+ `torch.utils.checkpoint` in the transformer loops.
1278
+
1279
+ ---
1280
+
1281
+ ## Inference Guide
1282
+
1283
+ Run inference on individual images:
1284
+
1285
+ ```bash
1286
+ genml-kit-infer --model facebook/convnextv2-base-22k-224 \
1287
+ --checkpoint genml_kit_best.pt \
1288
+ path/to/image.jpg path/to/other_image.png
1289
+ ```
1290
+
1291
+ Output is JSON with per-class probabilities:
1292
+
1293
+ ```json
1294
+ {
1295
+ "source": "image.jpg",
1296
+ "predictions": [
1297
+ {"label": "golden_retriever", "probability": 0.435},
1298
+ {"label": "labrador", "probability": 0.281}
1299
+ ]
1300
+ }
1301
+ ```
1302
+
1303
+ ### XGBoost And Test-Time Augmentation
1304
+
1305
+ The neural classifier makes decisions through its head. The XGBoost option
1306
+ takes the encoder representation $`h = f_\theta(x)`$ instead and fits an
1307
+ ensemble of decision trees to those vectors.
1308
+ Reference: Chen & Guestrin, [XGBoost: A Scalable Tree Boosting System](https://arxiv.org/abs/1603.02754), KDD 2016.
1309
+ A tree partitions feature space with rules such as $`h_{37} < t`$ (comparing
1310
+ the 37th feature of $`h`$ against a learned threshold $`t`$); boosting adds
1311
+ trees sequentially so each new tree focuses on errors left by previous trees.
1312
+ This can work well when the dataset is small
1313
+ and the representation is already useful, but it is not guaranteed to beat the
1314
+ neural head. Use validation data to choose tree depth, number of rounds, and
1315
+ ensemble weight.
1316
+
1317
+ Test-time augmentation (TTA) runs the same image through several plausible
1318
+ views and averages the probability vectors:
1319
+
1320
+ $$
1321
+ \large
1322
+ \bar{p}(y \mid x) = \frac{1}{K} \sum_{k=1}^{K} p(y \mid T_k(x))
1323
+ $$
1324
+
1325
+ where $`T_1, \dots, T_K`$ are the $`K`$ test-time transformations (e.g. the
1326
+ original image plus flipped copies) and $`\bar{p}`$ is their averaged
1327
+ probability vector: each transformed copy is classified independently, and the
1328
+ final prediction averages the per-view class probabilities. The
1329
+ transformations should preserve the label semantics. Horizontal flips
1330
+ are usually safer than orientation-specific crops; verify that an augmentation
1331
+ does not erase the cue that distinguishes the classes.
1332
+
1333
+ ### Inference CLI Reference
1334
+
1335
+ | Flag | Default | Description |
1336
+ |---|---|---|
1337
+ | `--model` | (required) | HuggingFace model name or custom model. |
1338
+ | `--checkpoint` | (required) | Path to state dict or wrapped checkpoint. |
1339
+ | `--top_k` | `None` | Show top-K predictions; omit for all classes. |
1340
+ | `--output` | `None` | Write JSON results to file. |
1341
+ | `--device` | `None` | Force PyTorch device (`cuda`, `cpu`). Auto-detected if omitted. |
1342
+ | `--cache_dir` | `None` | HuggingFace cache directory. |
1343
+ | `--xgboost_model` | `None` | XGBoost model path. If provided, runs XGBoost alongside PyTorch. |
1344
+
1345
+ Wrapped checkpoints (containing `model_state_dict` and metadata) are preferred
1346
+ over raw state dictionaries, which produce a metadata warning.
1347
+
1348
+ ### XGBoost Inference
1349
+
1350
+ When `--xgboost_model` is provided, the output includes both predictions:
1351
+
1352
+ ```json
1353
+ {
1354
+ "source": "image.jpg",
1355
+ "predictions": [
1356
+ {"label": "golden_retriever", "probability": 0.435}
1357
+ ],
1358
+ "xgboost_predictions": [
1359
+ {"label": "golden_retriever", "probability": 0.612}
1360
+ ]
1361
+ }
1362
+ ```
1363
+
1364
+ ---
1365
+
1366
+ ## Tips & Pitfalls
1367
+
1368
+ ### `--checkpoint` And `--source_checkpoint` Are Different
1369
+
1370
+ `--checkpoint` names the output prefix used for saving and resuming the current
1371
+ training run. `--source_checkpoint` imports weights from another run before
1372
+ the new optimizer is created. When moving a SupCon encoder into classification,
1373
+ use:
1374
+
1375
+ ```bash
1376
+ genml-kit-train \
1377
+ --checkpoint /content/eva02_finetune \
1378
+ --source_checkpoint /content/eva02_supcon_latest.pt \
1379
+ --param_rename 'encoder\\.model\\.(.*);model.$1' \
1380
+ ...
1381
+ ```
1382
+
1383
+ The rename is needed because the pre-training wrapper stores backbone keys
1384
+ under `encoder.model.*`, whereas the fine-tuning model stores them under
1385
+ `model.*`. The SupCon `projection.*` keys are expected to remain unused, and
1386
+ new classifier-head keys are expected to be missing from the source checkpoint.
1387
+ Those messages indicate a successful partial transfer if the backbone keys
1388
+ are matched.
1389
+
1390
+ ### Interpreting A SupCon Plateau
1391
+
1392
+ SupCon loss is not expected to approach zero. If an anchor has k-1 positives and
1393
+ positives become much more similar than negatives, a useful reference value is
1394
+ approximately `-log(k-1)`. This is only a diagnostic approximation: class
1395
+ counts may vary, the sampler may repeat examples, and temperature affects
1396
+ optimization. Judge the loss together with embedding quality and downstream
1397
+ validation metrics. A plateau near this reference can mean convergence; a
1398
+ plateau well above it can mean too few positives, a learning-rate problem, or
1399
+ labels that are not being passed correctly.
1400
+
1401
+ ### A Practical Debugging Order
1402
+
1403
+ 1. Confirm that images and labels are valid and that each SupCon batch has
1404
+ repeated classes.
1405
+ 2. Confirm that the loss changes when the learning rate changes and inspect
1406
+ `--grad_monitor` for zero or exploding gradients.
1407
+ 3. Check whether pre-trained weights loaded by reading the alignment report,
1408
+ not just the final epoch number.
1409
+ 4. Compare against a simple head-only or full-fine-tuning baseline before
1410
+ adding LLRD, LoRA, Mixup, focal loss, and class multipliers together.
1411
+ 5. Select the checkpoint using a validation metric appropriate to the
1412
+ objective, rather than training loss alone.
1413
+
1414
+ ### Low GPU Utilization (`util=0` In The Training Log)
1415
+
1416
+ The periodic `GPU:` line reports memory in MiB and SM utilization as a
1417
+ percentage sampled at log time (`mem=allocated/totalMiB (pct) res=…MiB
1418
+ util=…%`). `mem` counts live tensors, `res` is the caching allocator's
1419
+ pool, and `util` is one instant — not an average — so an isolated 0 is
1420
+ normal. A *persistent* pattern of `util=0` at every log line, with
1421
+ `mem`/`res` byte-identical between samples, means the GPU finished the
1422
+ last batch and is idle waiting for the next one: the run is **input
1423
+ bound**, not compute bound. The throughput line (`img/s=`) is the ground
1424
+ truth for step time.
1425
+
1426
+ Common causes and fixes, in order of likelihood:
1427
+
1428
+ - **Too few DataLoader workers.** JPEG decode + augmentation is CPU work;
1429
+ with `--num_workers 4` a 4090 can easily outrun the pipeline at
1430
+ 448². Check `nproc` on the machine and raise `--num_workers` toward
1431
+ the core count — `img/s` should scale until the GPU saturates
1432
+ (a `util` that now sits consistently above ~90% means you are done).
1433
+ - **Expensive decode.** Full-resolution JPEGs dominate decode cost.
1434
+ Pre-resizing the dataset offline (e.g. ~512px long side) cuts decode
1435
+ work several-fold and often doubles throughput on small VRAM budgets.
1436
+ - **Slow storage.** A network volume (S3/R2 mount, NFS) adds latency per
1437
+ image; prefer local NVMe for the dataset.
1438
+ - **`--seed`.** It enables cuDNN deterministic mode and disables
1439
+ benchmarking; expect slower steps by design. Omit it when you do not
1440
+ need bit-exact runs.
1441
+
1442
+ Fine-tuning runs on frozen-backbone models need very little GPU memory
1443
+ (`mem` is typically a few hundred MiB), so a low `mem` number is normal
1444
+ there and not a sign of a problem. Loader prefetch (`prefetch_factor=4`
1445
+ per worker) and `cudnn.benchmark=True` (default; disabled by an explicit
1446
+ `--seed`) already help absorb jitter and speed up the GPU side.
1447
+
1448
+ ---
1449
+
1450
+ ## Gradient Monitor
1451
+
1452
+ `--grad_monitor N` logs a per-parameter gradient report every *N* training
1453
+ steps. This helps diagnose training instability (exploding / vanishing
1454
+ gradients, imbalanced parameter updates) before it shows up in the loss.
1455
+
1456
+ ### Summary Line
1457
+
1458
+ ```
1459
+ [Step 29400] Gradient Report: 202 params | grad_rms: mean=5.68e-01 max=3.41e+00 min=1.66e-05 | grad/param: mean=2.94e-01
1460
+ ```
1461
+
1462
+ All norms are **RMS** (root mean square): the $`L_2`$ norm of the tensor
1463
+ divided by $`\sqrt{N}`$, where $`N`$ is the number of elements (`numel`):
1464
+
1465
+ $$
1466
+ \large
1467
+ \mathrm{RMS}(v) = \frac{\lVert v \rVert_2}{\sqrt{N}} = \sqrt{\frac{1}{N} \sum_{n=1}^{N} v_n^2}
1468
+ $$
1469
+
1470
+ Here $`v`$ is the tensor (a parameter or its gradient) flattened to $`N`$
1471
+ values $`v_1, \dots, v_N`$, and $`\lVert v \rVert_2 = \sqrt{\sum_n v_n^2}`$ is
1472
+ its Euclidean norm. Dividing by $`\sqrt{N}`$ makes the measure independent of
1473
+ tensor shape and directly comparable across parameters of different sizes.
1474
+
1475
+ | Field | Meaning |
1476
+ |---|---|
1477
+ | `params` | Total number of trainable parameters. |
1478
+ | `grad_rms: mean/max/min` | RMS of the gradient tensor for each parameter, then aggregated. `max` is the single most aggressive gradient — the one most likely to cause instability. |
1479
+ | `grad/param: mean` | Average gradient-to-parameter ratio. Healthy: < 0.1. Concerning: > 1.0. |
1480
+
1481
+ ### Per-Parameter Columns
1482
+
1483
+ | Column | Symbol | What to look for |
1484
+ |---|---|---|
1485
+ | **g_rms** | $`\mathrm{RMS}(\nabla_W \mathcal{L})`$ | Compare across params. One param with g_rms 100× higher is a problem. |
1486
+ | **p_rms** | $`\mathrm{RMS}(W)`$ | Per-element scale context. With `std=0.02` init, expect ~0.02. |
1487
+ | **g/p** | $`\lVert \nabla_W \mathcal{L} \rVert_2 / (\lVert W \rVert_2 + \varepsilon)`$ | **Most useful column.** Healthy: < 0.1. Concerning: > 1.0 (update overshoots). Dangerous: > 5.0. |
1488
+ | **g_max** | $`\max_n \lvert \partial \mathcal{L} / \partial W_n \rvert`$ | Highlights individual neurons with extreme gradients. |
1489
+ | **sparse** | `% zero` | High sparsity (> 50%) = most neurons not receiving signal. |
1490
+ | **status** | | `OK` = healthy. `STL` = stalled. `OVF` = exploding. `IMB` = imbalanced. `GPR` = high g/p ratio. |
1491
+
1492
+ In this table $`W`$ denotes one parameter tensor, $`\nabla_W \mathcal{L}`$ its
1493
+ gradient (the vector of partial derivatives of the loss with respect to each
1494
+ element of $`W`$), and $`\varepsilon`$ a tiny constant that only prevents
1495
+ division by zero for parameters that are exactly zero.
1496
+
1497
+ ### Reading The Report
1498
+
1499
+ **Healthy training:** g/p < 0.1, `grad/param: mean` in 0.01–0.1 range, g_rms within ~10× across layers.
1500
+
1501
+ **Exploding gradients:** One or more params with `OVF`, g/p > 5.0, `grad_rms: max` >> `mean`. Fix: lower LR, add `--grad_clip 1.0`, or use warmup.
1502
+
1503
+ **Vanishing gradients:** Many params with `STL`, g_rms near 1e-7, high sparsity. Fix: increase LR, check for dead neurons.
1504
+
1505
+ **Imbalanced updates:** Some params `IMB`, large g/p disparity between layers. Fix: use `--lr_group` for different rates, or freeze the dominant component.
1506
+
1507
+ ### Norm Trend History
1508
+
1509
+ `--norm_history N` (requires `--grad_monitor`) keeps the last N snapshots
1510
+ per parameter. A trend summary table is appended to each report showing
1511
+ direction (`UP`/`DOWN`/`---`), percentage change, and min/max values.
1512
+
1513
+ ---
1514
+
1515
+ ## Custom Losses
1516
+
1517
+ Losses are resolved through the `LOSSES` registry
1518
+ (`genml_kit.losses.registry.load_loss`). A loss spec is either a
1519
+ registered name (`focal`, `supcon`, or the RL bundles `ppo`, `sac`,
1520
+ `dqn`) or a path/URL to a `.py` script defining `build_loss(**kwargs)`:
1521
+
1522
+ ```python
1523
+ # my_loss.py
1524
+ import torch.nn as nn
1525
+
1526
+ class MyLoss(nn.Module):
1527
+ def __init__(self, alpha=1.0):
1528
+ super().__init__()
1529
+ self.alpha = alpha
1530
+
1531
+ def forward(self, logits, targets):
1532
+ return self.alpha * nn.functional.cross_entropy(logits, targets)
1533
+
1534
+ def build_loss(alpha=1.0, **kwargs):
1535
+ """Protocol: return a callable (logits, targets) -> tensor."""
1536
+ return MyLoss(alpha=alpha)
1537
+ ```
1538
+
1539
+ ```bash
1540
+ genml-kit-train --model google/vit-base-patch16-224 \
1541
+ --loss ./my_loss.py --loss_args '{"alpha": 2.0}' ...
1542
+ ```
1543
+
1544
+ **RL losses** work the same way but return a *bundle* (dict of
1545
+ callables); the script's entries are merged over the method's built-in
1546
+ bundle (the method passes its own name as the merge base: `ppo`, `sac`,
1547
+ or `dqn`), so a script may override just one loss and inherit the rest:
1548
+
1549
+ ```python
1550
+ # my_ppo_entropy.py
1551
+ def build_loss(**kwargs):
1552
+ return {"entropy": lambda ent: ent.mean() * 2.0} # override only entropy
1553
+ ```
1554
+
1555
+ ```bash
1556
+ genml-kit-train --method ppo --loss ./my_ppo_entropy.py ...
1557
+ ```
1558
+
1559
+ The built-in bundles are merged over (`ppo`: `policy`/`value`/`entropy`;
1560
+ `sac`: `q`/`policy`/`alpha`; `dqn`: `td`). The `--loss_args` JSON
1561
+ kwargs are forwarded to `build_loss(**kwargs)`.
1562
+
1563
+ ## Custom Models
1564
+
1565
+ genml_kit supports any HuggingFace `AutoModelForImageClassification` model,
1566
+ any timm model via `timm:<name>`, and custom architectures registered in
1567
+ `genml_kit.models`.
1568
+
1569
+ ### Built-In Custom Models
1570
+
1571
+ | Name | Description | `--model` value |
1572
+ |---|---|---|
1573
+ | timm | Any model from [timm](https://github.com/huggingface/pytorch-image-models) | `timm:<model_name>` |
1574
+ | ConvViT | Multi-block conv stem + ViT encoder with CLS-guided attention pooling | `convvit` |
1575
+ | UVito | Frozen SMP encoder + learnable patch projection + Transformer encoder | `uvito` |
1576
+ | ClsModelWrapper | HuggingFace backbone + custom classifier head | `cls_model_wrapper:<hf_name>` |
1577
+ | ContrastiveEncoder | Backbone + projection head for contrastive pre-training | `contrastive_encoder:<hf_name>` |
1578
+
1579
+ ### Adding A Custom Model
1580
+
1581
+ 1. Create `genml_kit/models/{name}/` with `model.py`, `processor.py`,
1582
+ `loader.py`, and `__init__.py`.
1583
+ 2. Add the import to `genml_kit/models/__init__.py`.
1584
+ 3. The model must expose `.forward(pixel_values=images)` → object with `.logits`,
1585
+ and `config.id2label` / `config.label2id`.
1586
+ 4. CLI overrides via `--model_arg KEY=VALUE` are forwarded to the loader.
1587
+
1588
+ ### External Model Scripts
1589
+
1590
+ Instead of registering a model inside the source tree, you can point
1591
+ `--model` at a `.py` file (or HTTP/HTTPS URL). The script must define
1592
+ `create_model`:
1593
+
1594
+ ```python
1595
+ # my_model.py
1596
+ import torch.nn as nn
1597
+
1598
+ class Tiny(nn.Module):
1599
+ def __init__(self, num_labels, hidden=128):
1600
+ super().__init__()
1601
+ self.net = nn.Sequential(nn.Linear(784, hidden), nn.ReLU(),
1602
+ nn.Linear(hidden, num_labels))
1603
+
1604
+ def forward(self, pixel_values):
1605
+ return pixel_values
1606
+
1607
+ def create_model(num_labels, image_size=224, id2label=None, label2id=None,
1608
+ checkpoint_path=None, device="cpu", **kwargs):
1609
+ """Protocol: return a torch.nn.Module."""
1610
+ return Tiny(num_labels=num_labels, hidden=kwargs.get("hidden", 128))
1611
+ ```
1612
+
1613
+ ```bash
1614
+ genml-kit-train --model ./my_model.py --loss focal ...
1615
+ ```
1616
+
1617
+ The script is **fully responsible for weight loading**: when
1618
+ `checkpoint_path` is provided (inference), call
1619
+ `genml_kit.io.checkpointing.load_checkpoint_weights(checkpoint_path, model, ...)`
1620
+ inside `create_model`, mirroring the ConvViT/UViTO loaders. In training
1621
+ `checkpoint_path` is `None` (random init) and the global `--source_checkpoint`
1622
+ / `--resume` paths apply uniformly after `create_model` returns.
1623
+
1624
+ An optional `create_processor(image_size=224, **kwargs)` may be defined
1625
+ for the processor; it must return an object exposing `image_mean` /
1626
+ `image_std`.
1627
+
1628
+ ### Custom Classifiers
1629
+
1630
+ `ClsModelWrapper` lets you replace the default HF classification head:
1631
+
1632
+ ```python
1633
+ class Classifier(nn.Module):
1634
+ def __init__(self, num_labels, hidden_size, **kwargs):
1635
+ super().__init__()
1636
+ self.head = nn.Linear(hidden_size, num_labels)
1637
+
1638
+ def forward(self, hidden_states): # (B, N, D) tensor
1639
+ features = hidden_states[:, 0] # CLS token
1640
+ return self.head(features)
1641
+
1642
+ def extract_features(self, hidden_states): # (B, N, D) → (B, D)
1643
+ return hidden_states[:, 0]
1644
+ ```
1645
+
1646
+ The `extract_features` method is used by `--xgboost_model` for XGBoost
1647
+ training on backbone features.
1648
+
1649
+ The head is selected through `--model_arg`, not a dedicated flag:
1650
+
1651
+ ```bash
1652
+ --model cls_model_wrapper:<hf_name> --model_arg classifier=mlp:hidden=512,dropout=0.3
1653
+ ```
1654
+
1655
+ The `classifier` value is an inline spec: the head name (a registered
1656
+ built-in \u2014 `mlp`, `cls_attention` \u2014 or a path to a `.py` file defining a
1657
+ `create_classifier(num_labels, hidden_size, **kwargs)` function), optionally followed by `:key=value,...` kwargs. Values
1658
+ are parsed as int/float/bool, and bracketed lists such as
1659
+ `cls_slice=(0, 1)` work. A head is required: `cls_model_wrapper` fails fast
1660
+ with a clear message when `classifier` is missing. Models that embed their
1661
+ own head (`convvit`, `uvito`, `timm:<name>`) do not accept this kwarg — for
1662
+ a custom head on a HuggingFace backbone use `cls_model_wrapper` instead.
1663
+ `genml-kit-infer` needs the same `--model_arg classifier=...` to rebuild the
1664
+ head before loading the checkpoint weights.
1665
+
1666
+ ---
1667
+
1668
+ ## Reinforcement Learning
1669
+
1670
+ genml_kit ships a self-contained reinforcement-learning (RL) toolkit built on
1671
+ Gymnasium. The companion document
1672
+ [`rl/README.md`](rl/README.md) is a from-the-ground-up *mathematics* tutorial
1673
+ (Bellman equations, TD, Q-learning, GAE, PPO, SAC); this section is the
1674
+ practical *usage* guide.
1675
+
1676
+ ### Installation
1677
+
1678
+ RL support is an optional extra:
1679
+
1680
+ ```
1681
+ pip install 'genml_kit[rl]'
1682
+ ```
1683
+
1684
+ ### Supported algorithms
1685
+
1686
+ | `--method` | Algorithm | Action space | Key files |
1687
+ |---|---|---|---|
1688
+ | `dqn` | Double-DQN with epsilon-greedy, optional dueling + n-step + PER | Discrete | `genml_kit/methods/rl_dqn.py` |
1689
+ | `ppo` | On-policy PPO with GAE, clipped surrogate, entropy bonus | Discrete or continuous | `genml_kit/methods/rl_ppo.py` |
1690
+ | `sac` | Soft Actor-Critic, twin critics, reparameterized policy, auto-alpha | Continuous only | `genml_kit/methods/rl_sac.py` |
1691
+
1692
+ ### Quick start
1693
+
1694
+ ```
1695
+ # DQN on CartPole (discrete)
1696
+ genml-kit-train --pipeline rl --method dqn --env_id CartPole-v1 \
1697
+ --epochs 20 --batch_size 64
1698
+
1699
+ # PPO on CartPole (discrete)
1700
+ genml-kit-train --pipeline rl --method ppo --env_id CartPole-v1 \
1701
+ --epochs 20 --ppo_rollout_len 2048
1702
+
1703
+ # SAC on a continuous env (e.g. LunarLanderContinuous-v3)
1704
+ genml-kit-train --pipeline rl --method sac --env_id LunarLanderContinuous-v3 \
1705
+ --epochs 20
1706
+ ```
1707
+
1708
+ All RL methods use `eval_return` (mean undiscounted return over
1709
+ `--eval_episodes` episodes, default 5) as the checkpoint-selection metric.
1710
+ The trainer bypasses the DataLoader: it steps the environment directly and
1711
+ samples from a replay buffer (DQN/SAC) or re-uses a rollout buffer (PPO).
1712
+
1713
+ ### Custom RL models
1714
+
1715
+ Every RL method resolves its network through the same model registry as the
1716
+ rest of the framework: `--model` selects a registered factory and
1717
+ `--model_arg key=value` forwards constructor kwargs.
1718
+
1719
+ ```
1720
+ # DQN: dueling Q-head (also the default for --dqn_dueling)
1721
+ genml-kit-train --pipeline rl --method dqn --model rl/qnet_dueling
1722
+
1723
+ # DQN: configure the MLP width via --model_arg
1724
+ genml-kit-train --pipeline rl --method dqn \
1725
+ --model rl/qnet --model_arg hidden_dims=[512,256]
1726
+
1727
+ # PPO: wider actor-critic trunk
1728
+ genml-kit-train --pipeline rl --method ppo \
1729
+ --model rl/actor_critic --model_arg hidden_dims=[64,64]
1730
+
1731
+ # SAC: critic head width (the actor defaults to rl/actor_critic)
1732
+ genml-kit-train --pipeline rl --method sac --env_id Pendulum-v1 \
1733
+ --model rl/sac_critic --model_arg hidden_dims=[256,256]
1734
+ ```
1735
+
1736
+ Registered RL factories (auto-discovered; see `MODELS.list_names()`):
1737
+
1738
+ | Name | Returns | Notes |
1739
+ |---|---|---|
1740
+ | `rl/qnet` | `QNetwork` (flat Q-head) | DQN default |
1741
+ | `rl/qnet_dueling` | `QNetwork` (dueling Q-head) | `--dqn_dueling` shortcut |
1742
+ | `rl/actor_critic` | `ActorCritic` (shared backbone) | PPO default |
1743
+ | `rl/sac_critic` | `SACCritic` (single critic head) | SAC default |
1744
+
1745
+ The methods pass a `SpaceSpec` (obs/action sizes derived from the env) to
1746
+ the factory, so a custom registered factory can accept the standard scalar
1747
+ kwargs (`obs_dim`, `n_actions`, `action_dim`, `hidden_dims`, ...) or the
1748
+ `space=` spec directly. SAC additionally supports a *factory-return
1749
+ contract*: a factory may return a plain dict `{"actor": ..., "critic": ...}`
1750
+ to supply both networks (the method composes the twin critic via a deep
1751
+ copy). As elsewhere in the framework there is **no** model-validation
1752
+ layer: an incompatible network fails loudly at first use (`act()` /
1753
+ `forward()`), and an unknown `--model` name falls through `load_model` to
1754
+ Hugging Face and fails at load time.
1755
+
1756
+ ### Evaluation videos
1757
+
1758
+ Pass `--record_eval_video` to record **one video per evaluation episode**
1759
+ during validation (all RL methods: DQN / PPO / SAC).
1760
+ `<checkpoint_dir>/videos/` as `eval_episode_000.mp4` etc., or as
1761
+ `eval_episode_000.gif` when the MP4 writer is unavailable (e.g. no
1762
+ `imageio[ffmpeg]`). Recording is **only** attempted when the environment can
1763
+ produce `rgb_array` frames: scripted/custom environments without a renderer
1764
+ are detected at validation time and skipped without crashing.
1765
+
1766
+ ### How a PPO training epoch works
1767
+
1768
+ PPO is *on-policy*: every update must be computed from transitions
1769
+ collected by the **current** policy. To keep that guarantee, the rollout
1770
+ buffer is **refilled from scratch each epoch** — nothing survives from the
1771
+ previous epoch.
1772
+
1773
+ **One training epoch** (the `=== Epoch N/500 ===` line in the logs) is
1774
+ exactly:
1775
+
1776
+ ```
1777
+ 1. rollout.reset() # clear the on-policy buffer
1778
+ 2. collect rollout_len env steps # --ppo_rollout_len (default 2048)
1779
+ 3. GAE (gamma, lam) over the rollout # advantages + returns
1780
+ 4. normalize advantages once # over the whole rollout
1781
+ 5. ppo_epochs SGD passes over it # --ppo_epochs (default 4)
1782
+ each pass: rollout_len / mini_batch_size minibatches
1783
+ 6. next epoch -> back to 1
1784
+ ```
1785
+
1786
+ So the arithmetic of a run is:
1787
+
1788
+ | Quantity | Formula | Default (Pendulum) |
1789
+ |---|---|---|
1790
+ | env steps per epoch | `rollout_len` | 2048 |
1791
+ | gradient steps per epoch | `ppo_epochs * (rollout_len / mini_batch_size)` | `4 * 2048/64 = 128` |
1792
+ | episodes per epoch | `rollout_len / episode_len` | `2048/200 ≈ 10` |
1793
+ | total env steps | `epochs * rollout_len` | 500 × 2048 = 1.02M |
1794
+
1795
+ The **two "epochs"** that can be confused:
1796
+
1797
+ - **Training epoch** (`--epochs`) — one rollout + its updates. This is
1798
+ what the log lines and checkpoints count.
1799
+ - **PPO SGD epoch** (`--ppo_epochs`) — the number of *passes over the
1800
+ same* rollout during the update phase. Raising it increases data
1801
+ reuse of a single rollout; lowering it (or raising `rollout_len`)
1802
+ increases data freshness.
1803
+
1804
+ The buffer itself is wiped cheaply: `rollout.reset()` just rewrites the
1805
+ pointer, so the tensor storage is reused and the per-epoch cost is one
1806
+ `rollout_len` collection, not an allocation. On resume, the rollout
1807
+ buffer state is saved/restored with the checkpoint and the previous
1808
+ epoch's last observation carries over, so an interrupted run continues
1809
+ mid-environment rather than restarting the episode.
1810
+
1811
+ Changing `--ppo_rollout_len` therefore changes the *epoch length in
1812
+ steps*, not the memory footprint (memory is `O(rollout_len)` but tiny —
1813
+ ~115 KB for Pendulum at 2048) and not the total step budget
1814
+ (`epochs × rollout_len`). A larger rollout gives the GAE a longer
1815
+ horizon before bootstrap and more data per update, but also means more
1816
+ gradient steps per rollout: at 50000 you'd run `4 × 50000/64 = 3125`
1817
+ updates on one batch, which pushes PPO toward overfitting a single
1818
+ rollout.
1819
+
1820
+ ### PPO flag reference
1821
+
1822
+ | Flag | Default | Meaning |
1823
+ |---|---|---|
1824
+ | `--ppo_gamma` | 0.99 | Discount factor for GAE / returns |
1825
+ | `--ppo_lam` | 0.95 | GAE trace-decay (bias-variance tradeoff) |
1826
+ | `--ppo_clip_eps` | 0.2 | Clipping epsilon of the clipped surrogate |
1827
+ | `--ppo_epochs` | 4 | SGD passes over each rollout |
1828
+ | `--ppo_mini_batch_size` | 64 | Mini-batch size for PPO updates |
1829
+ | `--ppo_entropy_coef` | 0.01 | Entropy bonus coefficient (see SB3-tricks section) |
1830
+ | `--ppo_value_coef` | 0.5 | Value-loss coefficient |
1831
+ | `--ppo_vf_clip_eps` | None | Value-function clipping (None = unclipped) |
1832
+ | `--ppo_target_kl` | None | Early-stop a PPO epoch when approx-KL exceeds this (see SB3-tricks section) |
1833
+ | `--ppo_rollout_len` | 2048 | Env steps collected per training epoch |
1834
+ | `--ppo_discrete` / `--ppo_continuous` | discrete | Action-space selection |
1835
+ | `--ppo_log_std_init` | log(0.5) ≈ −0.693 | Initial log_std of the continuous Gaussian policy (σ₀ = 0.5) |
1836
+ | `--ppo_log_std_min` | −10.0 | Lower safety clamp of log_std (σ floor ≈ 4.5e-5). Kept far below a converged policy's operating range so the entropy gradient never dies at the boundary (the old −2.0 default froze exploration at σ = 0.135) |
1837
+ | `--ppo_log_std_max` | 2.0 | Upper safety clamp of log_std (σ ceiling ≈ 7.4; bounds entropy) |
1838
+
1839
+ The `log_std_*` knobs control the **continuous** Gaussian policy's
1840
+ standard deviation. `log_std_init` sets where exploration starts;
1841
+ `log_std_min`/`log_std_max` are wide safety rails (SOTA pattern: SB3
1842
+ unbounded, rsl_rl `std_range=(1e-6, 1e6)`, jaxrl `LOG_STD_MIN=-10`) that
1843
+ prevent σ collapse/explosion while leaving entropy freely trainable.
1844
+
1845
+ ### Stable-Baselines3-style tricks
1846
+
1847
+ The PPO implementation supports three opt-in techniques that
1848
+ Stable-Baselines3 bakes into its default algorithms. All three are
1849
+ **off by default** — every existing flag combination behaves exactly as
1850
+ before — and each is documented with *when it helps* and *when it
1851
+ doesn't*.
1852
+
1853
+ #### Reward normalization (`--reward_normalize`)
1854
+
1855
+ Normalizes rewards by the running standard deviation of discounted
1856
+ returns, matching SB3 `VecNormalize(norm_reward=True)`. For each step,
1857
+ `running_return = gamma * running_return + reward` is fed to a Welford
1858
+ `RunningMeanStd`; the reward is then divided by `sqrt(var + eps)` and
1859
+ clamped to `[-reward_norm_clip, reward_norm_clip]` (default 10.0).
1860
+
1861
+ - **When it helps:** environments with large or unnormalized reward
1862
+ scales (Pendulum-v1, MuJoCo) where an O(1000) value loss otherwise
1863
+ dominates the total loss and swamps the entropy/policy signal.
1864
+ - **When it doesn't:** rewards already O(1) (CartPole, most toy envs) —
1865
+ normalization is harmless but unnecessary.
1866
+ - **Eval always uses raw rewards** (SB3 `VecNormalize.train(False)`):
1867
+ the running-return stats are not updated during evaluation, so
1868
+ `eval_return` stays comparable across runs. The running stats travel
1869
+ with the checkpoint and are restored on resume.
1870
+
1871
+ #### Orthogonal initialization (`--param_init ortho`)
1872
+
1873
+ Applies SB3-style orthogonal initialization to the model after
1874
+ construction: gain `sqrt(2)` for policy/hidden layers, `1.0` for
1875
+ value/head layers, zero biases — matching the original PPO
1876
+ implementation. `log_std` is left untouched. Works for any method
1877
+ (PPO, SAC, and non-RL MLPs alike).
1878
+
1879
+ - **When it helps:** continuous RL policies, where the default PyTorch
1880
+ init can leave the policy near-degenerate at start and slow the
1881
+ critical early phase.
1882
+ - **When it doesn't:** fine-tuned / checkpoint-loaded models (init is
1883
+ skipped when weights are loaded from a checkpoint) or discrete
1884
+ policies that already train fine with defaults.
1885
+
1886
+ #### `target_kl` early stopping (`--ppo_target_kl <float>`)
1887
+
1888
+ SB3 stops a PPO epoch early when the approximate KL divergence (the
1889
+ Schulman **k1** estimator, `0.5 * mean(log_ratio^2)`, always >= 0)
1890
+ exceeds `target_kl`. This guards against destructive updates on
1891
+ high-variance minibatches.
1892
+
1893
+ - **Suggested starting point:** `--ppo_target_kl 0.03`.
1894
+ - **Too low** (e.g. < 0.005) stalls learning; **too high** (e.g. > 0.1)
1895
+ disables the safety. `None` (default) disables early stopping.
1896
+ - Only affects PPO epochs after the first rollout, so it is a pure
1897
+ safety valve for the on-policy update phase.
1898
+
1899
+ #### Entropy coefficient (`--ppo_entropy_coef <float>`)
1900
+
1901
+ Coefficient of the entropy bonus (default 0.01). SB3 uses **0.0** for
1902
+ continuous PPO, relying on init + normalization instead; genml_kit keeps
1903
+ a small positive default as light regularization.
1904
+
1905
+ - **Higher** (0.05–0.1) encourages broader exploration — may help hard
1906
+ exploration tasks.
1907
+ - **Lower** (toward 0.0) sharpens the policy — may help fine-tuning late
1908
+ in training.
1909
+ - No single value is best for all tasks: sweep 0.0–0.1 on your task.
1910
+
1911
+ A typical "serious" continuous-PPO setup (Pendulum-style) looks like:
1912
+
1913
+ ```
1914
+ genml-kit-train --pipeline rl --method ppo --env_id Pendulum-v1 \
1915
+ --ppo_continuous --obs_normalize --reward_normalize --param_init ortho \
1916
+ --ppo_target_kl 0.03 --epochs 500
1917
+ ```
1918
+
1919
+ ### Custom environments
1920
+
1921
+ Pass `--env_script /path/to/env.py` to load a custom environment. The
1922
+ script must expose a `make_env()` factory returning a Gymnasium-style env
1923
+ (`reset()`, `step(action)`, `close()`; `observation_space` and
1924
+ `action_space` attributes, which the pipeline introspects to size the
1925
+ networks). `make_env()` may take a single `seed` keyword argument if your
1926
+ environment wants reproducible initialization.
1927
+
1928
+ ### Environment & replay options
1929
+
1930
+ Relevant flags:
1931
+ - `--env_id`, `--obs_dim`, `--env_script` -- environment selection.
1932
+ - `--replay_capacity`, `--batch_size`, `--n_step`, `--prioritized`,
1933
+ `--per_alpha`, `--per_beta_start`, `--per_beta_frames` -- replay tuning.
1934
+ - `--obs_normalize`, `--obs_norm_clip` -- running observation
1935
+ normalization (Welford). Both train and eval observations are
1936
+ normalized with the same RMS statistics.
1937
+ - `--reward_normalize`, `--reward_norm_clip` -- running-return reward
1938
+ normalization (SB3 `VecNormalize(norm_reward=True)`). See
1939
+ "Stable-Baselines3-style tricks" below.
1940
+ - `--param_init ortho` -- SB3-style orthogonal parameter initialization.
1941
+ See "Stable-Baselines3-style tricks" below.
1942
+ - `--ppo_gamma`, `--ppo_lam`, `--ppo_clip_eps`, `--ppo_epochs`,
1943
+ `--ppo_mini_batch_size`, `--ppo_value_coef`, `--ppo_vf_clip_eps`,
1944
+ `--ppo_rollout_len`, `--ppo_discrete`/`--ppo_continuous`,
1945
+ `--ppo_log_std_init/min/max` -- PPO update and policy knobs. See the
1946
+ "PPO flag reference" table above.
1947
+ - `--ppo_target_kl` -- early-stop a PPO epoch when the k1 approximate-KL
1948
+ exceeds this threshold (SB3 `target_kl`). See below.
1949
+ - `--ppo_entropy_coef` -- entropy bonus coefficient (default 0.01).
1950
+ See below.
1951
+ - `--eval_episodes`, `--env_seed` -- evaluation.
1952
+ - `--record_eval_video` -- record one MP4 (or GIF fallback) per evaluation
1953
+ episode under `<checkpoint_dir>/videos/`; only when the environment
1954
+ supports rendering (see "Evaluation videos" below).
1955
+
1956
+ ### Episode-end semantics (terminated vs truncated)
1957
+
1958
+ Gymnasium distinguishes *terminated* (the MDP truly ended, e.g. the pole
1959
+ fell) from *truncated* (the episode was cut short, e.g. by a time limit).
1960
+ genml_kit threads the true `terminated` flag through the replay buffer,
1961
+ rollout buffer, GAE, and the TD targets: a truncated final step still
1962
+ bootstraps `γ V(s′)`, while a terminated one does not. Environments using
1963
+ the legacy 4-tuple gym API (no `terminated`/`truncated` split) fall back to
1964
+ treating `done` as `terminated`.
1965
+
1966
+ ## References And Further Reading
1967
+
1968
+ - Xie et al., [SimMIM: A Simple Framework for Masked Image Modeling](https://arxiv.org/abs/2111.09886), CVPR 2022.
1969
+ - Assran et al., [Self-Supervised Learning from Images with a Joint-Embedding Predictive Architecture](https://arxiv.org/abs/2301.08243), CVPR 2023.
1970
+ - Grill et al., [Bootstrap Your Own Latent: A New Approach to Self-Supervised Learning](https://arxiv.org/abs/2006.07733), NeurIPS 2020.
1971
+ The EMA teacher and stop-gradient design used by I-JEPA-style methods.
1972
+ - Caron et al., [Emerging Properties in Self-Supervised Vision Transformers](https://arxiv.org/abs/2104.14294), ICCV 2021.
1973
+ The DINO paper — self-distillation with an EMA teacher and multi-crop.
1974
+ The centering + sharpening trick to avoid representation collapse.
1975
+ - Khosla et al., [Supervised Contrastive Learning](https://arxiv.org/abs/2004.11362), NeurIPS 2020.
1976
+ - He et al., [Masked Autoencoders Are Scalable Vision Learners](https://arxiv.org/abs/2111.06377), CVPR 2022.
1977
+ A useful comparison for masked-image pre-training.
1978
+ - Hu et al., [LoRA: Low-Rank Adaptation of Large Language Models](https://arxiv.org/abs/2106.09685), ICLR 2022.
1979
+ - Howard & Ruder, [Universal Language Model Fine-tuning for Text Classification](https://arxiv.org/abs/1801.06146), ACL 2018.
1980
+ Introduced layer-wise learning rate decay.
1981
+ - Zhang et al., [mixup: Beyond Empirical Risk Minimization](https://arxiv.org/abs/1710.09412), ICLR 2018.
1982
+ - Lin et al., [Focal Loss for Dense Object Detection](https://arxiv.org/abs/1708.02002), ICCV 2017.
1983
+ Introduced focal loss and the $`(1-p_t)^\gamma`$ easy-example down-weighting.
1984
+ - Chen & Guestrin, [XGBoost: A Scalable Tree Boosting System](https://arxiv.org/abs/1603.02754), KDD 2016.
1985
+ - The [PyTorch optimization documentation](https://pytorch.org/docs/stable/optim.html)
1986
+ explains AdamW, schedulers, and gradient clipping.
1987
+ - The [scikit-learn metrics documentation](https://scikit-learn.org/stable/modules/model_evaluation.html)
1988
+ is useful when choosing metrics for imbalanced classification.
1989
+
1990
+ ## Development
1991
+
1992
+ ```bash
1993
+ git clone https://github.com/davidel/genml_kit
1994
+ cd genml_kit
1995
+ pip install -e ".[dev,all]"
1996
+ pytest
1997
+ ```
1998
+
1999
+ Tests run with warnings-as-errors (`filterwarnings = ["error"]` in
2000
+ `pyproject.toml`), so a new dependency deprecation warning fails the suite
2001
+ instead of scrolling past. Code is formatted with
2002
+ [yapf](https://github.com/google/yapf) using the project's `.style.yapf`
2003
+ (Google style, 2-space indent) and linted with
2004
+ [Ruff](https://docs.astral.sh/ruff/) (`ruff check .`).
2005
+
2006
+ ### Naming Conventions For Class Members
2007
+
2008
+ - Anything that PyTorch registers — child `nn.Module`, `nn.Parameter`,
2009
+ registered buffer — is **never** underscore-prefixed, regardless of
2010
+ intended visibility. A leading underscore would change `state_dict()`
2011
+ keys, optimizer param groups, and DDP behavior.
2012
+ - Everything else that is not part of a class's public contract
2013
+ (internal state, helper hooks invoked only by the class itself) gets a
2014
+ leading underscore. A member called from other classes, overridden as
2015
+ an extension point, or documented as API stays public.
2016
+ - Extension-point methods that *callers* invoke (e.g.
2017
+ `PretrainMethod.build_transform`) are public; same-named hooks the
2018
+ base class *itself* dispatches (e.g. `BaseImageProcessor._build_transform`)
2019
+ are private.
2020
+
2021
+ ## License
2022
+
2023
+ Apache-2.0
2024
+