tracebloc 2.0.0__tar.gz → 3.0.0__tar.gz

{tracebloc-2.0.0 → tracebloc-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tracebloc
-Version: 2.0.0
+Version: 3.0.0
 Summary: Build AI with anyone. On data that can't move. SDK for the tracebloc collaborative AI workspace.
 Author-email: tracebloc <lukas@tracebloc.io>
 License-Expression: MIT

{tracebloc-2.0.0 → tracebloc-3.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tracebloc"
-version = "2.0.0"
+version = "3.0.0"
 description = "Build AI with anyone. On data that can't move. SDK for the tracebloc collaborative AI workspace."
 license = "MIT"
 license-files = ["license.txt"]
@@ -231,14 +231,8 @@ select = ["N"]
 ignore = ["N812"]
 
 [tool.ruff.lint.per-file-ignores]
-# Deprecation helpers: lowercase class name is intentional (decorator-like
-# descriptor), and module-level __getattr__/__dir__ are PEP 562 dunders.
-"tracebloc/compat/deprecation.py" = ["N801", "N807"]
-
-# Deprecated camelCase class/method aliases are preserved until 1.0.0.
-# SDK.2c (class) and SDK.2d (method) aliases land as class-scope mixedCase.
-"tracebloc/linking/model_dataset.py" = ["N815"]
-"tracebloc/user.py" = ["N815"]
+# Deprecation helpers: module-level __getattr__/__dir__ are PEP 562 dunders.
+"tracebloc/compat/deprecation.py" = ["N807"]
 
 # YOLO / vision math uses single-letter S, B, C, H, W variables per ML
 # convention (grid size, boxes, classes, height, width).

{tracebloc-2.0.0 → tracebloc-3.0.0}/tracebloc/_deprecation.py

@@ -5,7 +5,6 @@ imports from the new module.
 """
 
 from tracebloc.compat.deprecation import (  # noqa: F401  (re-export, RFC-0348 C.3)
-    deprecated_method_alias,
     deprecated_aliases,
     discard_removed_kwarg,
     _Sentinel,

{tracebloc-2.0.0 → tracebloc-3.0.0}/tracebloc/compat/deprecation.py

@@ -24,41 +24,6 @@ import warnings
 from typing import Callable, Dict, Tuple
 
 
-class deprecated_method_alias:
-    """Descriptor exposing an old-name method as a forwarder to a new-name method.
-
-    Class-body usage::
-
-        class User:
-            def upload_model(self, ...): ...
-
-            uploadModel = deprecated_method_alias("upload_model")
-
-    Accessing the old name emits a single ``DeprecationWarning``
-    naming both the old and new method, then returns the new bound
-    method — so calls still reach the new implementation. Old names
-    are removed in 1.0.0.
-    """
-
-    def __init__(self, new_name: str) -> None:
-        self._new_name = new_name
-        self._old_name = ""
-
-    def __set_name__(self, owner: type, name: str) -> None:
-        self._old_name = name
-
-    def __get__(self, instance, owner=None):
-        if instance is None:
-            return self
-        warnings.warn(
-            f"{self._old_name}() is deprecated; use {self._new_name}() instead. "
-            f"The old name will be removed in 1.0.0.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return getattr(instance, self._new_name)
-
-
 def deprecated_aliases(
     mapping: Dict[str, str],
 ) -> Tuple[Callable[[str], object], Callable[[], list]]:

{tracebloc-2.0.0 → tracebloc-3.0.0}/tracebloc/exceptions.py

@@ -99,10 +99,6 @@ class RawModeCheckError(DatasetLinkingError):
     preparation or output the platform cannot score."""
 
 
-class TrainingPlanError(TraceblocError):
-    """Raised when a training plan configuration is invalid."""
-
-
 class UnsupportedPairError(TraceblocError, ValueError):
     """Raised when a ``(category, framework)`` pair is not one the SDK trains."""
 

{tracebloc-2.0.0 → tracebloc-3.0.0}/tracebloc/linking/augmentation_methods.py

@@ -9,7 +9,7 @@ import os
 import json
 from termcolor import colored
 import numbers
-from tracebloc.compat.deprecation import deprecated_method_alias, discard_removed_kwarg
+from tracebloc.compat.deprecation import discard_removed_kwarg
 from tracebloc.training import subdataset
 from tracebloc.training.subdataset import class_set_error, dataset_error, request_error
 from tracebloc.training.image_channels import image_channel_check

{tracebloc-2.0.0 → tracebloc-3.0.0}/tracebloc/linking/data_methods.py

@@ -9,7 +9,7 @@ import os
 import json
 from termcolor import colored
 import numbers
-from tracebloc.compat.deprecation import deprecated_method_alias, discard_removed_kwarg
+from tracebloc.compat.deprecation import discard_removed_kwarg
 from tracebloc.training import subdataset
 from tracebloc.training.subdataset import class_set_error, dataset_error, request_error
 from tracebloc.training.image_channels import image_channel_check

{tracebloc-2.0.0 → tracebloc-3.0.0}/tracebloc/linking/model_dataset.py

@@ -4,7 +4,7 @@ import os
 import json
 from termcolor import colored
 import numbers
-from tracebloc.compat.deprecation import deprecated_method_alias, discard_removed_kwarg
+from tracebloc.compat.deprecation import discard_removed_kwarg
 from tracebloc.training import subdataset
 from tracebloc.training.subdataset import class_set_error, dataset_error, request_error
 from tracebloc.training.image_channels import image_channel_check
@@ -120,6 +120,7 @@ class LinkModelDataset(DataPlanMethods, TrainingPlanMethods, AugmentationMethods
                 "class_order",
                 "conversion",
                 "dataset_sequence_length",
+                "max_batch_size",
             },
         )
         self._framework = kwargs["framework"]
@@ -154,6 +155,12 @@ class LinkModelDataset(DataPlanMethods, TrainingPlanMethods, AugmentationMethods
         self._num_classes = kwargs["num_classes"]
         self._class_names = kwargs["class_names"]
         self._batch_size = kwargs["batch_size"]
+        # The model file's max_batch_size, and whether batch_size() or
+        # enable_lora() set a value: see tracebloc.training.memory_sizing.
+        self._max_batch_size = kwargs.get("max_batch_size")
+        self._batch_explicit = False
+        self._lora_explicit = False
+        self._memory_refusal = None
         # The model's declared num_feature_points (keypoints / tabular columns /
         # time-series features), threaded from upload so link-time validation
         # handlers build dummy data with the right dimension. ``_data_shape`` is
@@ -277,6 +284,12 @@ class LinkModelDataset(DataPlanMethods, TrainingPlanMethods, AugmentationMethods
         from tracebloc.training.submitter import ExperimentSubmitter
 
         self._submitter = ExperimentSubmitter(facade=self)
+        from tracebloc.training.memory_sizing import announce, size_plan
+
+        self._sizing = size_plan(self)
+        line = announce(self._sizing)
+        if line:
+            print(colored(line, "yellow"), "\n")
 
     def reset_training_plan(self) -> None:
         self._callbacks_cfg.reset()
@@ -285,6 +298,8 @@ class LinkModelDataset(DataPlanMethods, TrainingPlanMethods, AugmentationMethods
         self._training_dataset_size = self.default_dict["total_dataset_size"]
         self._training_classes = self.default_dict["class_names"]
         self._batch_size = self.default_dict["batch_size"]
+        self._batch_explicit = False
+        self._lora_explicit = False
         self._aug.reset()
         self._layers_non_trainable = ""
         self._metrics = str(["accuracy"])
@@ -315,6 +330,10 @@ class LinkModelDataset(DataPlanMethods, TrainingPlanMethods, AugmentationMethods
         self._error_method = []
         self._eligibility_passed = True
         self._validate_image_channels()
+        from tracebloc.training.memory_sizing import size_plan
+
+        self._memory_refusal = None
+        self._sizing = size_plan(self)
         print("Training Plan Parameters reset")
 
     def _print_error(self, method, error):
@@ -408,13 +427,15 @@ class LinkModelDataset(DataPlanMethods, TrainingPlanMethods, AugmentationMethods
 
     def plan(self) -> dict:
         """The applied plan, JSON-serialisable: ``{cycles, epochs, batch_size,
-        eligible, errors: [{method, message}]}``; prints nothing."""
+        sizing, eligible, errors: [{method, message}]}``, where ``sizing`` is
+        what memory sizing chose (``{outcome, lora, note}``) or ``None``;
+        prints nothing."""
         return self._summary().plan()
 
     def memory_check(self) -> dict | None:
-        """Peak-memory estimate vs the client's per-run limit: ``{estimate_gib,
-        terms_gib, limit_gib, warning}`` (``warning``: what ``start()`` prints,
-        else ``None``), or ``None`` if unsized. Never raises (backend#5165)."""
+        """Peak-memory estimate vs each training's memory: ``{estimate_gib,
+        terms_gib, limit_gib, warning}`` (``warning``: why ``start()`` refuses
+        the plan, else ``None``), or ``None`` if unsized. Never raises."""
         return self._submitter.memory_check()
 
     def get_function_name(self, method_object) -> str:
@@ -439,20 +460,6 @@ class LinkModelDataset(DataPlanMethods, TrainingPlanMethods, AugmentationMethods
         """Rich HTML rendering of the current training plan for Jupyter."""
         return self._summary().repr_html()
 
-    # --- Deprecated camelCase method aliases (removed in 1.0.0) -----------
-    resetTrainingPlan = deprecated_method_alias("reset_training_plan")
-    trainingClasses = deprecated_method_alias("training_classes")
-    dataType = deprecated_method_alias("data_type")
-    experimentName = deprecated_method_alias("experiment_name")
-    learningRate = deprecated_method_alias("learning_rate")
-    lossFunction = deprecated_method_alias("loss_function")
-    layersFreeze = deprecated_method_alias("layers_freeze")
-    terminateOnNaNCallback = deprecated_method_alias("terminate_on_nan_callback")
-    modelCheckpointCallback = deprecated_method_alias("model_checkpoint_callback")
-    earlystopCallback = deprecated_method_alias("early_stop_callback")
-    reducelrCallback = deprecated_method_alias("reduce_lr_callback")
-    getTrainingPlan = deprecated_method_alias("get_training_plan")
-
 
 # --- Deprecated class alias (removed in 1.0.0) ---
 from tracebloc.compat.deprecation import deprecated_aliases

{tracebloc-2.0.0 → tracebloc-3.0.0}/tracebloc/linking/training_methods.py

@@ -9,7 +9,7 @@ import os
 import json
 from termcolor import colored
 import numbers
-from tracebloc.compat.deprecation import deprecated_method_alias, discard_removed_kwarg
+from tracebloc.compat.deprecation import discard_removed_kwarg
 from tracebloc.training import subdataset
 from tracebloc.training.subdataset import class_set_error, dataset_error, request_error
 from tracebloc.training.image_channels import image_channel_check
@@ -76,6 +76,7 @@ class TrainingPlanMethods:
         """The run's batch size; the model file's ``batch_size`` is the default."""
         if self._plan.batch_size(batch_size):
             self._batch_size = batch_size
+            self._batch_explicit = True
 
     def epochs(self, epochs: int) -> None:
         """
@@ -341,6 +342,7 @@ class TrainingPlanMethods:
             )
             return
         self._lora.enable_lora(lora_enable)
+        self._lora_explicit = True
 
     def set_lora_parameters(
         self, lora_r: int, lora_alpha: int, lora_dropout: float, q_lora: bool

{tracebloc-2.0.0 → tracebloc-3.0.0}/tracebloc/linking/user_methods.py

@@ -13,7 +13,6 @@ import rich
 
 from tracebloc.compat.deprecation import (
     UNSET,
-    deprecated_method_alias,
     resolve_renamed_kwarg,
 )
 from tracebloc.linking.response import (
@@ -137,6 +136,7 @@ class UserLinkMethods:
             data_shape=self._User__data_shape,
             num_feature_points=self._User__num_feature_points,
             batch_size=self._User__batch_size,
+            max_batch_size=getattr(self, "_User__max_batch_size", None),
             model_path=self._User__model_path,
             # LinkModelDataset still spells this keyword ``environment`` — its
             # internal plumbing carries the stage *value* and is deliberately

{tracebloc-2.0.0 → tracebloc-3.0.0}/tracebloc/training/memory_estimate.py

@@ -1,11 +1,11 @@
-"""Peak-memory estimate for one training run, and the warning when it may not fit.
+"""Peak-memory estimate for one training, and why a plan does not fit.
 
 WHY (tracebloc/backend#5165). A causal-LM run (distilgpt2, batch 8, sequence
 128, no LoRA) was OOM-killed three times at a client's 3 GiB per-run limit, and
-nothing said beforehand that it would not fit. ``start()`` now puts the run's
-estimated PEAK next to what the client gives each run, and warns. It never
-blocks: the estimate is an estimate, and the limit is the data owner's
-(``tb resources set``), not ours to override.
+nothing said beforehand that it would not fit. The plan is now sized to the
+memory each training gets (``tracebloc.training.memory_sizing``), and
+``start()`` refuses one that does not fit: the limit is the data owner's
+(``tracebloc resources set``), not ours to override.
 
 WHAT IS COUNTED. Bytes resident at the worst moment of a cycle, PyTorch only
 (the other frameworks have no comparable state to count, so they get no
@@ -17,9 +17,9 @@ estimate rather than a guess):
                  model state and step transients, which leaves ~1 GiB here.
 ``weights``      every parameter, ``DTYPE_BYTES`` each (fp32 training).
 ``gradients``    one per TRAINABLE parameter.
-``optimizer``    per trainable parameter: 2 states for the Adam family, 1 for
-                 the rest (SGD's momentum buffer, RMSprop's square average);
-                 an optimizer we do not know counts as Adam.
+``optimizer``    per trainable parameter, the parameter-sized tensors the
+                 optimizer keeps (``_OPTIMIZER_STATES``); an optimizer not
+                 listed there counts as Adam.
 ``activations``  what autograd keeps for backward. Text: the transformer
                  estimate of Korthikanti et al. 2022 (arXiv:2205.05198),
                  ``17·s·h + 2.5·a·s²`` elements per layer per sample, at
@@ -30,24 +30,23 @@ estimate rather than a guess):
                  ``LOGITS_COPIES`` (4) times: the logits, the shifted copy
                  the causal loss makes, log-softmax, and its gradient.
                  Masked / causal LM and seq2seq only.
-``save``         end of each cycle the engine merges and clones the full
-                 state dict, converts it to numpy and serializes it
-                 (tracebloc-engine#1513): ``SAVE_COPIES`` (3) more copies of
-                 the weights.
+``save``         end of each cycle the engine writes the weights from views
+                 of the model's storage, or a delta built one key at a time
+                 (fp16, sparse, under one copy); ``safetensors`` before 0.8
+                 flattens that payload once more to write it. ``SAVE_COPIES``
+                 (1) copy of the weights covers both.
 
-PEAK, NOT AVERAGE. The step's transients and the save's copies are ADDED,
-not maxed: CPU RSS does not drop after a step (the allocator keeps the freed
-pages), so the save lands on top of the step's high-water mark. That is how
-the measured run 2 died at 3 GiB while its 30-second samples never passed
-1.88 GiB.
+PEAK, NOT AVERAGE. The step's transients and the save's copy are ADDED, not
+maxed: CPU RSS does not drop after a step (the allocator keeps the freed
+pages), so the save lands on top of the step's high-water mark.
 
 LoRA. Trainable parameters are the adapters the engine would add: ``r·(in +
 out)`` per ``nn.Linear`` (the engine adapts ``nn.Linear`` only). Activations
 are still counted in full, which over-counts when the adapters sit only near
 the output; conservative on purpose.
 
-WARN, AT A MARGIN. The estimate cannot see allocator fragmentation or short
-evaluation spikes, so it warns from ``WARN_FRACTION`` (90%) of the limit up.
+FIT, AT A MARGIN. The estimate cannot see allocator fragmentation or short
+evaluation spikes, so a plan fits only below ``WARN_FRACTION`` (90%) of the limit.
 """
 
 from __future__ import annotations
@@ -75,7 +74,7 @@ GB = 1000**3
 RUNTIME_BYTES = 1 * GIB
 DTYPE_BYTES = 4
 LOGITS_COPIES = 4
-SAVE_COPIES = 3
+SAVE_COPIES = 1
 IMAGE_ACTIVATION_FACTOR = 100
 WARN_FRACTION = 0.9
 
@@ -97,10 +96,21 @@ _IMAGE_CATEGORIES = frozenset(
         KEYPOINT_DETECTION,
     }
 )
-_ONE_STATE_OPTIMIZERS = frozenset(
-    {"sgd", "rmsprop", "adagrad", "adadelta", "asgd", "rprop", "lion"}
-)
-_NO_STATE_OPTIMIZERS = frozenset({"lbfgs"})
+#: Parameter-sized state tensors per parameter, for every optimizer the engine
+#: builds, as it builds them: ``torch.optim.<Name>(params, lr=...)``, so SGD has
+#: torch's default momentum 0 and keeps no momentum buffer.
+_OPTIMIZER_STATES = {
+    "sgd": 0,
+    "adam": 2,
+    "adamw": 2,
+    "adamax": 2,
+    "adadelta": 2,
+    "rprop": 2,
+    "rmsprop": 1,
+    "adagrad": 1,
+    "asgd": 1,
+}
+_UNKNOWN_OPTIMIZER_STATES = 2
 
 
 @dataclass(frozen=True)
@@ -193,11 +203,7 @@ def describe_model(model: Any) -> ModelShape | None:
 
 def _optimizer_states(optimizer: Any) -> int:
     name = str(optimizer or "").strip().lower()
-    if name in _NO_STATE_OPTIMIZERS:
-        return 0
-    if name in _ONE_STATE_OPTIMIZERS:
-        return 1
-    return 2  # the Adam family, and anything we do not recognise
+    return _OPTIMIZER_STATES.get(name, _UNKNOWN_OPTIMIZER_STATES)
 
 
 def _lora_trainable(shape: ModelShape, rank: int) -> int:
@@ -316,7 +322,8 @@ def needed_bytes(estimate: MemoryEstimate, where: str = "memory") -> int:
 def memory_fit_warning(
     estimate: MemoryEstimate, limit_bytes: int, where: str = "memory"
 ) -> str | None:
-    """The warning to print, or ``None`` when the estimate fits with margin."""
+    """Why the plan does not fit ``limit_bytes``, or ``None`` when it fits with
+    margin. ``start()`` refuses a plan with this message (``memory_sizing``)."""
     needed = needed_bytes(estimate, where)
     if needed < WARN_FRACTION * limit_bytes:
         return None
@@ -331,14 +338,14 @@ def memory_fit_warning(
     if text and not estimate.inputs.get("lora"):
         fixes.append("turn on LoRA")
     if where != "GPU memory":
-        fixes.append("raise the limit with `tb resources set --memory`")
+        fixes.append("raise the limit with `tracebloc resources set --memory`")
     advice = (
         fixes[0] if len(fixes) == 1 else ", ".join(fixes[:-1]) + ", or " + fixes[-1]
     )
     return (
-        f"Memory warning: this run may need ~{needed / GIB:.1f} GiB of {where} "
-        f"at its peak; your client gives each run {limit_bytes / GIB:.1f} GiB. "
-        f"It may be killed for running out of memory. To fit, {advice}."
+        f"This training needs about {needed / GIB:.1f} GiB of {where} at its "
+        f"peak, and the smallest secure environment it trains on gives each "
+        f"training {limit_bytes / GIB:.1f} GiB. To fit, {advice}."
     )