inline-core 1.2.62__tar.gz → 1.2.63__tar.gz

{inline_core-1.2.62 → inline_core-1.2.63}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: inline-core
-Version: 1.2.62
+Version: 1.2.63
 Summary: The generation engine behind Inline Studio.
 License-Expression: GPL-3.0-or-later
 Requires-Python: >=3.11

{inline_core-1.2.62 → inline_core-1.2.63}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 # PyPI name; the import package is `inline_core` (src/inline_core).
 name = "inline-core"
-version = "1.2.62"
+version = "1.2.63"
 description = "The generation engine behind Inline Studio."
 readme = "README.md"
 license = "GPL-3.0-or-later"

{inline_core-1.2.62 → inline_core-1.2.63}/scripts/minimax_h3_train_matrix.py

@@ -34,7 +34,9 @@ _STEPS = 12
 _RANK = 16
 
 
-def _manifest(work: Path, dataset: Path, models: Path, resolution: int) -> Path:
+def _manifest(
+    work: Path, dataset: Path, models: Path, resolution: int, steps: int = _STEPS
+) -> Path:
     """The same manifest shape `studio/training.py::_prepare` writes."""
     checkpoints = work / "checkpoints"
     checkpoints.mkdir(parents=True, exist_ok=True)
@@ -62,8 +64,8 @@ def _manifest(work: Path, dataset: Path, models: Path, resolution: int) -> Path:
             "alpha": _RANK,
             "learningRate": 1e-4,
             "batchSize": 1,
-            "steps": _STEPS,
-            "saveEvery": _STEPS,
+            "steps": steps,
+            "saveEvery": steps,
             "resolution": resolution,
         },
         "gpuIds": [],
@@ -152,6 +154,7 @@ def main() -> int:
     parser.add_argument("--python", default=str(_CORE / ".venv" / "bin" / "python"))
     parser.add_argument("--gpu", default="", help="label for the results file, e.g. 'L40S (46GB)'")
     parser.add_argument("--only", default="", help="one resolution, to redo a single row")
+    parser.add_argument("--steps", type=int, default=_STEPS, help="override for a smoke run")
     args = parser.parse_args()
 
     if not args.dataset.is_dir():
@@ -186,7 +189,7 @@ def main() -> int:
             continue
         work = args.out / cell_id
         work.mkdir(parents=True, exist_ok=True)
-        manifest = _manifest(work, args.dataset, args.models, resolution)
+        manifest = _manifest(work, args.dataset, args.models, resolution, args.steps)
         print(f"--- {cell_id}px, 4-bit base ---", flush=True)
         result = _run_cell(args.python, manifest, args.out / f"{cell_id}.log")
         result.update({"resolution": resolution, "base_quant": "nf4"})

{inline_core-1.2.62 → inline_core-1.2.63}/src/inline_core/models/minimaxh3/load.py

@@ -165,9 +165,8 @@ def load_transformer(
 def _fusing_shrink(plan: Any, fused: set[str], inner: Any) -> Any:
     """Fuse a block's share of the LoRA stack the moment it lands, then hand off to ``shrink``.
 
-    Order matters both ways: after the stream the block's weights exist, and before ``shrink`` they
-    are still unquantised, which is the only window in which a full-precision delta can be added
-    in place.
+    The only window that works: after the stream the weights exist, before ``shrink`` they are
+    still unquantised, and a full-precision delta cannot be added to a quantised weight.
     """
 
     def shrink(model: Any, prefix: str) -> None:
@@ -195,11 +194,9 @@ def _fuse_subtree(module: Any, plan: Any, prefix: str) -> set[str]:
 def _finish_fuse(model: Any, plan: Any, fused: set[str]) -> None:
     """Fuse what the block callback never saw, then prove nothing was missed.
 
-    The callback only fires for ``transformer_blocks.N``, so ``context_embedder``, the token
-    refiner and the output heads would silently keep their base weights - and silently is the whole
-    problem. ``plan_loras`` only raises when a key matches *no* module in the model, and these
-    modules do exist, so a partial fuse validates clean and then degrades the output without ever
-    erroring. The residual pass covers them and the check makes any remaining gap loud.
+    The callback fires only for ``transformer_blocks.N``, so ``context_embedder`` and the token
+    refiner would keep their base weights. ``plan_loras`` raises only when a key matches *no*
+    module, and these exist, so a partial fuse validates clean and then degrades output silently.
     """
     residual = {name: deltas for name, deltas in plan.items() if name not in fused}
     if residual:

{inline_core-1.2.62 → inline_core-1.2.63}/src/inline_core/training/arch.py

@@ -76,21 +76,12 @@ _FLUX2_TARGETS = [
 ]
 
 
-#: MiniMax H3: the attention and SwiGLU feed-forward Linears of all 50 blocks, plus the text
-#: projection. Confirmed against MiniMaxH3Transformer3DModel.named_modules(): a block's Linears are
-#: exactly to_q/to_k/to_v/to_out.0, ff.net.0.proj, ff.net.2 and adaln_proj.linear.
+#: MiniMax H3: every Linear in a block except ``adaln_proj``, plus the text projection.
 #:
-#: ``adaln_proj.linear`` is deliberately absent. It is replaced at load by the rank-8 factorisation
-#: (``minimaxh3/adaln.py``) that takes the checkpoint from 66GB to 40GB, so the module a LoRA would
-#: attach to carries the whole modulation signal through eight columns - the same reason
-#: ``minimaxh3/pipeline.py`` refuses to quantize it.
-#:
-#: The fp32-pinned modules are absent for a different reason: H3 ships a mixed-precision checkpoint
-#: where the patch projections, the timestep MLP and the two output heads stay float32
-#: (``_keep_in_fp32_modules``), and adapting those fights the precision split, not the model.
-#:
-#: PEFT matches by name suffix, so this also adapts the two token-refiner blocks. That is wanted,
-#: and it is why the loader must fuse outside the block stack too - see ``minimaxh3/load.py``.
+#: ``adaln_proj`` is out because the load factorises it to rank 8, so a LoRA would attach to eight
+#: columns carrying the whole modulation signal. The fp32-pinned heads are out because adapting them
+#: fights the checkpoint's precision split. PEFT matches by suffix, so this also reaches the two
+#: token-refiner blocks, which is why the loader has to fuse outside the block stack.
 _MINIMAX_H3_TARGETS = [
     "to_q",
     "to_k",
@@ -270,13 +261,8 @@ _H3_PATCH = (1, 2, 2)
 def _h3_forward(transformer: Any, noisy: Any, timestep: Any, item: dict[str, Any]) -> Any:
     """One prediction from MiniMaxH3Transformer3DModel, mirroring the vendored denoise block.
 
-    H3 runs one packed 1-D sequence holding text, audio and video rows rather than separate streams,
-    and the caller owns that layout. The precache builds it once per image (it only depends on the
-    caption length and the latent grid) and caches the tensors, so a step just patchifies, assigns
-    every row this step's timestep, and selects the video rows back out.
-
-    A still is one latent frame with no audio rows at all, which the model accepts: the audio head
-    runs over an empty index and returns empty.
+    H3 packs text, audio and video into one 1-D sequence and the caller owns that layout, so the
+    precache builds it per image and a step only patchifies and selects the video rows back out.
     """
     from ..models.minimaxh3.vendor.packing import patchify_video_latents, unpatchify_video_tokens
 
@@ -336,14 +322,10 @@ ARCHS: dict[str, TrainingArch] = {
     MINIMAX_H3: TrainingArch(
         key=MINIMAX_H3,
         target_modules=_MINIMAX_H3_TARGETS,
-        # H3's shift is the same expression Z-Image uses, at the scheduler's video shift of 12.0
-        # (MiniMaxH3Scheduler builds its grid as shift * s / (1 + (shift - 1) * s)), so the
-        # generic sigma applies unchanged.
+        # Same shift expression as Z-Image, at the scheduler's video shift of 12.0.
         sigma=_zimage_sigma,
-        # Z-Image's convention exactly, and worth a test rather than a comment because Krea 2 and
-        # FLUX.2 use the opposite one: MiniMaxH3Scheduler.scale_noise is
-        # x_t = t * clean + (1 - t) * noise at t = 1 - sigma, and its step reconstructs
-        # x0 = x_t + sigma * v, so the velocity the model predicts is clean - noise.
+        # Z-Image's convention, opposite to Krea 2 and FLUX.2, and pinned against the vendored
+        # scheduler in test_minimaxh3_training.py rather than restated here.
         timestep=lambda sigma: 1.0 - sigma,
         target=lambda clean, noise: clean - noise,
         forward=_h3_forward,

{inline_core-1.2.62 → inline_core-1.2.63}/src/inline_core/training/h3.py

@@ -25,11 +25,8 @@ PATCH = (1, 2, 2)
 AUDIO_LATENT_CHANNELS = 32
 
 #: What an absent caption becomes. H3 tokenises with ``add_special_tokens=False`` and has no BOS,
-#: so the empty string is genuinely zero tokens and the conditioner reshapes a (1, 0) sequence into
-#: an attention head and raises. A single space is one real token and the closest thing this model
-#: has to no caption: it is guidance-distilled, so inference never encodes an unconditional prompt
-#: and there is no established unconditional embedding to match. Covers caption dropout and an
-#: image whose ``.txt`` is missing or blank.
+#: so an empty string is zero tokens and the conditioner raises on the (1, 0) sequence. Covers both
+#: caption dropout and an image whose ``.txt`` is missing.
 _EMPTY_CAPTION = " "
 
 
@@ -117,6 +114,12 @@ def _encode_captions(
     from ..models.minimaxh3.vendor.encoders import MiniMaxH3TextEncoderStep
 
     pipeline = _load_conditioner(root, device, dtype)
+    # Encode wherever it landed. It spills to host RAM on a card too small for 20.5GB, and the
+    # vendored step builds its input ids on the device it is handed, so CUDA ids against a
+    # CPU-resident encoder fail in `index_select`.
+    where = next(pipeline.text_encoder.parameters()).device
+    if where.type != torch.device(device).type:
+        logger.info("MiniMax H3: conditioner is on %s, encoding captions there", where)
     out: list[tuple[Any, Any]] = []
     try:
         for caption in captions:
@@ -126,7 +129,7 @@ def _encode_captions(
                 # is not optional here: it defaults to `components.transformer.dtype`, and this
                 # pipeline deliberately has no transformer.
                 embeds, tags = MiniMaxH3TextEncoderStep.encode_prompt(
-                    pipeline, caption, None, device=torch.device(device), dtype=dtype
+                    pipeline, caption, None, device=where, dtype=dtype
                 )
             out.append((embeds[0].cpu(), tags.cpu()))
     finally:
@@ -151,10 +154,8 @@ def _conditioning(embed: Any, tags: Any, latent: Any) -> dict[str, Any]:
         patch_size=PATCH,
         keyframe_anchors=(),
     )
-    # Training pins no conditioning rows and a still has no audio rows, so every row shares one
-    # noise level and this vector is constant across steps. Derived from the vendored planner and
-    # then checked, so a change upstream is caught here rather than silently mis-addressing the
-    # AdaLN table.
+    # Every row shares one noise level here, so this vector is constant across steps. Derived from
+    # the vendored planner and checked, or a change upstream would mis-address the AdaLN table.
     unique, indices = build_row_timesteps(layout, 1.0, 1.0, 1.0, 1.0)
     if unique.numel() != 1 or bool(indices.any()):
         raise RuntimeError(
@@ -212,7 +213,7 @@ def _load_conditioner(root: Path, device: str, dtype: Any) -> Any:
             "popup; the conditioner cannot tokenise a caption without them."
         )
 
-    quant, placement = _conditioner_plan(device)
+    quant, placement = _conditioner_plan(device, encoder_dir)
     text_encoder = Qwen3VLForConditionalGeneration.from_pretrained(
         str(encoder_dir),
         dtype=dtype,
@@ -228,7 +229,54 @@ def _load_conditioner(root: Path, device: str, dtype: Any) -> Any:
     return pipeline
 
 
-def _conditioner_plan(device: str) -> tuple[Any, dict[str, Any]]:
+#: What the 4-bit conditioner occupies wherever it lands, measured on an L40S.
+_CONDITIONER_GB = 20.5
+
+#: Left free for the process, the page cache and everything else on the box.
+_RAM_HEADROOM_GB = 4.0
+
+
+def _check_conditioner_fits(placement: Any, encoder_dir: Path) -> None:
+    """Refuse a caption pass with nowhere to put the conditioner, and warn when it will crawl.
+
+    The 4-bit figure only holds on the card: bitsandbytes quantises during the move to CUDA, so a
+    CPU placement pages the full bf16 folder instead, measured at 59GB and 42s a caption on a T4.
+    Those pages are evictable, so a short machine thrashes rather than raising.
+    """
+    from ..device.memory import MemoryPolicy
+    from ..models import pipeline_runtime as rt
+
+    free_vram = (rt.free_vram_bytes(placement.device) or 0) / 1e9
+    if free_vram >= _CONDITIONER_GB:
+        return
+    free_ram_mb = MemoryPolicy().free_ram_mb()
+    if not free_ram_mb:
+        return  # unmeasurable; better to attempt the load than to refuse on no evidence
+    free_ram = free_ram_mb / 1024
+    on_disk = _folder_bytes(encoder_dir) / 1e9
+    # Half the folder is a floor, not a fit: only 64 GB has actually been measured, and the pages
+    # are evictable, so less RAM buys thrashing rather than a clean failure.
+    floor = max(on_disk * 0.5, _CONDITIONER_GB + _RAM_HEADROOM_GB)
+    if free_ram < floor:
+        raise RuntimeError(
+            f"MiniMax H3 conditions on a 32B text encoder. It needs about {_CONDITIONER_GB:.0f} GB "
+            f"on the card, or roughly {on_disk:.0f} GB paged through system RAM when the card "
+            f"cannot hold it. This machine has {free_vram:.0f} GB free on the card and "
+            f"{free_ram:.0f} GB of free RAM, which is not enough for either. Training H3 needs a "
+            "larger GPU or more RAM."
+        )
+    logger.warning(
+        "MiniMax H3: the conditioner does not fit %0.0f GB of VRAM, so the caption pass runs "
+        "unquantised on the CPU. Expect roughly 40 seconds a caption instead of 2.",
+        free_vram,
+    )
+
+
+def _folder_bytes(path: Path) -> int:
+    return sum(f.stat().st_size for f in path.rglob("*") if f.is_file())
+
+
+def _conditioner_plan(device: str, encoder_dir: Path) -> tuple[Any, dict[str, Any]]:
     """4-bit, and on the card only if it fits, reusing the generation path's own decision."""
     from ..device.memory import MemoryPolicy
     from ..models.minimaxh3.pipeline import _encoder_config, _encoder_placement
@@ -240,6 +288,7 @@ def _conditioner_plan(device: str) -> tuple[Any, dict[str, Any]]:
     quant = _encoder_config(recipe)
     if quant is None:  # bitsandbytes absent: nothing to place, and the load will speak for itself
         return None, {}
+    _check_conditioner_fits(placement, encoder_dir)
     del device
     return quant, _encoder_placement(placement)
 
@@ -305,10 +354,8 @@ def _shrinker(basis: Any, quant: Any, device: str, dtype: Any) -> Any:
 def _keeps_precision(path: str) -> bool:
     """Whether a Linear is spared the 4-bit swap.
 
-    Only the factorised AdaLN projection. Unfactorised it is [96768, 2688] and quantising it is
-    ordinary; factorised it is [96768, 8] and those eight columns carry the entire modulation
-    signal, so the error concentrates instead of averaging. It is 1.5 MB a block, 75 MB across the
-    stack, which is not worth that.
+    Only the factorised AdaLN projection: at rank 8 its eight columns carry the whole modulation
+    signal, so quantisation error concentrates rather than averaging, for 75MB across the stack.
     """
     return "adaln_proj" in path
 
@@ -316,12 +363,8 @@ def _keeps_precision(path: str) -> bool:
 def _swap_to_4bit(module: Any, keep: Any = None, prefix: str = "") -> None:
     """Replace every ``nn.Linear`` under ``module`` with a bitsandbytes NF4 layer.
 
-    The QLoRA arrangement: the base is frozen and 4-bit, gradients still flow through it to the
-    adapter on top, and quantization itself happens when the layer moves to CUDA.
-
-    Deliberately not ``loaders._swap_to_4bit``, which takes no keep-predicate and would convert the
-    factorised AdaLN projection along with everything else. Kept local rather than widening the
-    shared loader, so the two shipping architectures that use it are untouched.
+    Deliberately not ``loaders._swap_to_4bit``: that takes no keep-predicate and would convert the
+    factorised AdaLN projection too. Local rather than widening a loader two other archs use.
     """
     import bitsandbytes as bnb
     import torch
@@ -349,9 +392,8 @@ def _swap_to_4bit(module: Any, keep: Any = None, prefix: str = "") -> None:
 def _place_unstreamed(model: Any, device: str) -> None:
     """Move what the block callback never sees.
 
-    ``load.py`` fires ``shrink`` only for ``transformer_blocks.N``, so the embedders, the token
-    refiner, the norms and the two output heads are still wherever the stream staged them. Left on
-    the CPU they meet CUDA activations in the first forward.
+    ``load.py`` fires ``shrink`` only for ``transformer_blocks.N``, so the embedders, refiner and
+    output heads are still wherever the stream staged them, and meet CUDA activations if left.
     """
     stack = model.transformer_blocks
     for child in model.children():
@@ -362,9 +404,8 @@ def _place_unstreamed(model: Any, device: str) -> None:
 
 
 def _sample(moments: Any) -> Any:
-    """Sample the posterior. Unlike the conditioning path this takes no fixed seed and no fp16
-    round trip: those exist to make a *reference* reproducible, and baking them into training
-    latents would narrow what the LoRA ever sees."""
+    """Sample the posterior, without the conditioning path's fixed seed and fp16 round trip: those
+    make a *reference* reproducible and would narrow what the LoRA sees."""
     from diffusers.models.autoencoders.vae import DiagonalGaussianDistribution
 
     return DiagonalGaussianDistribution(moments).sample()

{inline_core-1.2.62 → inline_core-1.2.63}/src/inline_core/training/models.py

@@ -178,6 +178,13 @@ _ADAPTER_SOURCE = {
 
 
 def compute_dtype() -> Any:
+    """bf16 wherever torch will take it, deliberately including Turing.
+
+    The device policy prefers fp16 below compute 8.0, where bf16 has no tensor cores. That argument
+    is about GPU matmuls and does not transfer here: this dtype also reaches the caption pass, which
+    runs on the CPU when the text encoder will not fit the card, and CPU fp16 upcasts. Switching a
+    T4 to fp16 hung the machine mid-caption. Narrow it to the GPU compute before revisiting.
+    """
     import torch
 
     if torch.cuda.is_available():

{inline_core-1.2.62 → inline_core-1.2.63}/src/inline_core/training/trainer.py

@@ -132,10 +132,9 @@ def _activation_offload(enabled: bool) -> Any:
     return torch.autograd.graph.save_on_cpu(pin_memory=True)
 
 
-#: The cached-item keys that carry activations and take the compute dtype. Everything else moves to
-#: the device unchanged: a boolean mask would become weights, integer row tags and index tensors
-#: would stop addressing anything, and H3's float64 rotary position grid would lose most of its
-#: mantissa - none of which raises, they just train against the wrong thing.
+#: The cached-item keys that carry activations and take the compute dtype. Everything else moves
+#: unchanged: a bool mask would become weights, index tensors would stop addressing anything, and
+#: H3's float64 rotary grid would lose its mantissa. None of it raises.
 _ACTIVATION_KEYS = frozenset({"latent", "embed", "audio"})
 
 

{inline_core-1.2.62 → inline_core-1.2.63}/tests/test_minimaxh3_training.py

@@ -8,6 +8,8 @@ scheduler is ever re-synced from upstream and its convention moves, these fail.
 
 from __future__ import annotations
 
+from pathlib import Path
+
 import pytest
 
 from inline_core.training import arch as archs
@@ -210,6 +212,59 @@ def test_the_swap_keeps_biases_and_frozen_base_weights() -> None:
     assert not module.proj.bias.requires_grad
 
 
+class _Placement:
+    device = "cuda:0"
+
+
+def _fit_check(
+    monkeypatch: pytest.MonkeyPatch, vram_gb: float, ram_gb: float, encoder_gb: float = 63.0
+) -> None:
+    from inline_core.device import memory
+    from inline_core.models import pipeline_runtime as rt
+    from inline_core.training import h3
+
+    monkeypatch.setattr(rt, "free_vram_bytes", lambda _d: int(vram_gb * 1e9))
+    monkeypatch.setattr(memory.MemoryPolicy, "free_ram_mb", lambda _s: int(ram_gb * 1024))
+    monkeypatch.setattr(h3, "_folder_bytes", lambda _p: int(encoder_gb * 1e9))
+
+
+def test_the_conditioner_fits_on_a_big_card(monkeypatch: pytest.MonkeyPatch) -> None:
+    from inline_core.training import h3
+
+    _fit_check(monkeypatch, vram_gb=45.0, ram_gb=8.0)
+    h3._check_conditioner_fits(_Placement(), Path("/enc"))  # card holds it, RAM is moot
+
+
+def test_the_conditioner_may_stream_from_host_ram(monkeypatch: pytest.MonkeyPatch) -> None:
+    """A 16GB card is fine given RAM for the spill. Only 64GB has been measured, so the
+    guard's floor is half the folder rather than a fit."""
+    from inline_core.training import h3
+
+    _fit_check(monkeypatch, vram_gb=15.0, ram_gb=64.0)
+    h3._check_conditioner_fits(_Placement(), Path("/enc"))
+
+
+def test_a_machine_with_room_in_neither_is_refused(monkeypatch: pytest.MonkeyPatch) -> None:
+    """The failure this prevents is a host-RAM OOM, which kills the process rather than raising."""
+    from inline_core.training import h3
+
+    _fit_check(monkeypatch, vram_gb=15.0, ram_gb=15.0)
+    with pytest.raises(RuntimeError, match="larger GPU or more RAM"):
+        h3._check_conditioner_fits(_Placement(), Path("/enc"))
+
+
+def test_an_unmeasurable_machine_is_attempted_rather_than_refused(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    from inline_core.device import memory
+    from inline_core.models import pipeline_runtime as rt
+    from inline_core.training import h3
+
+    monkeypatch.setattr(rt, "free_vram_bytes", lambda _d: 0)
+    monkeypatch.setattr(memory.MemoryPolicy, "free_ram_mb", lambda _s: None)
+    h3._check_conditioner_fits(_Placement(), Path("/enc"))  # no evidence is not evidence
+
+
 def test_the_residual_fuse_reaches_modules_outside_the_block_stack() -> None:
     """The load callback only fires for ``transformer_blocks.N``, so a per-block fuse silently
     misses ``context_embedder`` and the token refiner - both of which are LoRA targets and both of