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

{inline_core-1.2.53 → inline_core-1.2.62}/CLAUDE.md

@@ -95,7 +95,16 @@ HTTP/WS  →  server/app.py  →  RunManager  →  Executor  →  Registry (desc
   the ComfyUI-equivalent decomposed graph and the intended long-term surface. **Descriptor-only
   today - their runners land in C2.** A graph built from them validates and type-checks but raises
   `No runner registered` at execution.
-- **Model runners** (`models/<name>/`) - high-level single generation nodes. **`alibaba/z-image-turbo`
+- **Model runners** (`models/<name>/`) - high-level single generation nodes. **`black-forest-labs/flux-2`
+  (`models/flux2/`) is the reference for a _family_:** one node covers klein 4B/9B, their base builds,
+  the KV variant and dev, because the picked checkpoint is identified from its own tensor shapes
+  (`flux2/variants.py`) and everything else follows. Adding a checkpoint is a row in that table.
+  Two rules it establishes: **identify a checkpoint by content, never by filename** (`diffusion_models/`
+  is shared across architectures, and Qwen3-4B and Qwen3-VL-4B have byte-identical embedding shapes),
+  and **derive geometry from the checkpoint** rather than bundling a config per variant, so a future
+  build loads with no code change. A **diffusers folder** is a valid checkpoint too, which is the only
+  way a 32B model reaches a 24 GB card: its NF4 shards stream through `from_pretrained`, where
+  `from_single_file` cannot quantize at all. **`alibaba/z-image-turbo`
   (`models/zimage/`) is the one runnable generation path today** (prompt + optional image → one take,
   backed by diffusers' `ZImagePipeline`/`ZImageImg2ImgPipeline`). This is the "Z-Image pipeline that
   already works" - the primitives will reach parity in C2. It loads from a **single diffusion
@@ -112,6 +121,11 @@ between nodes and are never takes.
 
 ### Storage & configuration (all env, see `config.py`)
 
+- **Never put weights on an instance's ephemeral/scratch disk.** On cloud GPU boxes (`/opt/dlami/nvme`,
+  `/mnt/resource`, and anything else labelled ephemeral or instance-store) the volume is **wiped on
+  every stop/start**, taking the models and leaving dangling symlinks in `models/`. This has cost two
+  full re-downloads of MiniMax H3 at ~130 GB each. Weights go on the persistent root volume, or on an
+  attached volume that survives a restart. Scratch is fine for logs and temporary output only.
 - **Models root** - `INLINE_MODELS_DIR`, else `./models`. **Bring your own weights; nothing is
   downloaded.** ComfyUI-style category subfolders (`diffusion_models/`, `vae/`, `text_encoders/`,
   `loras/`, `controlnet/`, `checkpoints/`, `clip_vision/`, `upscale_models/`, `embeddings/`). The
@@ -143,6 +157,18 @@ between nodes and are never takes.
   (Turing/Volta - compute capability < 8.0, e.g. a T4): same footprint, but it uses the fp16 tensor
   cores instead of bf16's slow path. The **VAE stays upcast** (bf16, or fp32 when the denoiser is
   fp16) because fp16 VAE decode can overflow to black/NaN images (`_compute_dtype` in `device/`).
+- **Quantization rungs** - the fit ladder is full-precision resident → int8 resident → **NF4 resident**
+  → sequential offload → wont-fit. NF4 is what makes a 32B model viable on a 24 GB card. Note int8
+  forces bf16 (torchao's weight-only int8 silently no-ops under fp16) while NF4 does not, so a Turing
+  card keeps its fp16 tensor cores under NF4.
+- **Prequantized checkpoints must not be re-quantized.** A checkpoint that ships already quantized
+  (`flux2/variants.is_prequantized`) has an on-disk size that already _is_ its resident size, so the
+  ladder's assumption that quantization halves it does not hold, and handing diffusers a second,
+  different quantization config is a hard error. Pass `Quantization.NONE` for those.
+- **Staged loading** - when the text encoder and the transformer cannot be co-resident (dev is a
+  15 GB encoder beside an 18 GB transformer), the prompt is encoded first and the encoder freed before
+  the transformer loads. The decision has to be made _before_ the load: by the time an OOM fires there
+  is nothing left to free.
 - **Multi-GPU** - `INLINE_PARALLEL` (e.g. `pipefusion=2`, `pipefusion=2,ulysses=2`); degrees multiply
   to the world size, which must equal the GPU count.
 
@@ -202,6 +228,11 @@ real codec that moves tensors lives with the model runner.
   Don't scatter it.
 - **Bring-your-own models.** Nothing is downloaded by the engine. The catalog scans; the user places
   files. A model picker is a `SELECT` param with `options_from="<category>"`.
+- **Verify image models by rendering.** The FLUX.2 work shipped five bugs past a green test suite,
+  and every one produced a _wrong image rather than an error_: a mis-keyed checkpoint, a
+  vision-language encoder loaded in place of a text one, an unnormalized latent, and a control context
+  cast to a quantized weight's `uint8` storage dtype. A unit test cannot see a plausible-but-wrong
+  image. Render something and look at it.
 - **Tests (pytest).** Cover the logic that matters: graph validate/topo/executor/cache, the catalog
   scan, the run store + server contract, the device/memory policy, the parallel group + xfuser seam,
   and each model runner (import-guarded, no GPU needed). See `tests/`.
@@ -211,14 +242,17 @@ real codec that moves tensors lives with the model runner.
 
 ```
 uv venv                                   # create ./.venv
-uv pip install -e ".[server,dev]"         # engine + server + test tooling
-uv pip install -e ".[runtime]"            # + torch, diffusers, transformers (real generation)
-uv pip install -e ".[runtime,parallel]"   # + xfuser, for multi-GPU denoise (2+ GPUs)
+# --python pins the target: without it uv installs into an activated venv/conda env, not ./.venv
+uv pip install --python .venv/bin/python -e ".[server,dev]"   # engine + server + test tooling
+uv pip install --python .venv/bin/python -e ".[runtime]"      # + torch, diffusers, transformers
+uv pip install --python .venv/bin/python -e ".[runtime,parallel]"  # + xfuser, multi-GPU denoise
 
 ./webui.sh                                # run (loopback:8848); friendly flags → INLINE_* env
 ./webui.sh --listen --port 9000           # bind all interfaces
 ./webui.sh --lowvram                      # tight-VRAM profile
 ./webui.sh --install --extra runtime      # set up ./.venv with the model runtime, then exit
+                                          # (reuses an existing ./.venv; --recreate rebuilds it, and
+                                          #  an activated foreign env is reported, never modified)
 python -m inline_core.server              # run the server directly (INLINE_HOST / INLINE_PORT)
 
 ruff check .                              # lint (zero warnings)
@@ -227,6 +261,53 @@ uv run pytest -q                          # tests (no GPU; model code is import-
 
 ## Where to add things
 
+- **New video model** → do **not** rediscover the plumbing; it exists as shared seams, and
+  `models/minimaxh3/` is the reference caller:
+  - `runtime/video_encode.py` + `TakeStore.save_video` / `save_audio` - frames plus a waveform to one
+    playable MP4. A model that generates video and its soundtrack jointly returns **both** takes;
+    only the one matching the descriptor's `output_kind` claims the node's canvas slot (see
+    `studio/generation._save_take`, and `tests/test_output_kind_contract.py` which keeps the
+    declarations honest).
+  - `models/video_params.py` - `VideoGrid` + `video_param_fields(...)`, the way
+    `sampling_param_fields(...)` already works. A duration snaps **up** onto the model's frame grid
+    and is then clamped into the model's window, which is what both reference implementations do:
+    asking H3 for 10 seconds gives 10.125, not 9.417. **fps is a model constant, never a param**,
+    or it desyncs from the grid.
+  - `models/references.py` - wired image/video/audio ports as one ordered, numbered list. Wiring
+    order is what the prompt addresses, so it is meaning, not decoration.
+  - `models/keymap.py` - load a checkpoint written for another implementation. Declare a key plan
+    (rename / split / swap halves / drop / assert-equal) and apply it while weights stream in. The
+    transforms it performs are the ones that fail **silently**, so a plan declares its expected row
+    layout and the detector measures the real one. It needs the **whole tensor**: one head's worth of
+    rows cannot tell the layouts apart, and it raises rather than guessing.
+  - `models/prepared.py` - cache a quantised model once. Everything that changes the bytes goes in
+    the hash, including model-specific flags, or switching a flag serves a stale artifact.
+  - `models/offload.py` - the device policy's plan to a concrete torchao + group-offload recipe,
+    plus **split residency**: group offload holds the whole model in host RAM, so a model bigger
+    than the RAM available has nowhere to sit and the kernel swaps it. `blocks_to_place` sizes the
+    overflow and those leading blocks go on the accelerator instead, placed as they land rather
+    than after the load. It moves the minimum, because every block left resident is VRAM the
+    render wanted for activations.
+  - **A group-offloaded model's host footprint is reclaimable at load and unreclaimable one step
+    later, so never size a split from free memory during the load.** Streaming from a safetensors
+    mmap leaves the CPU-side weights as clean file-backed pages the kernel can drop and re-read for
+    free. The first denoising step ends that: group offload returns each block with
+    `module.to("cpu")`, which allocates fresh anonymous memory and drops the file-backed storage.
+    A planner reading `available` mid-load is reading a number that is about to stop being true,
+    and the failure mode is not an exception. It is the machine resetting with the page cache
+    converted out from under it, no OOM message and no shutdown sequence. Budget the full
+    post-conversion footprint, and count what other components will claim from the same RAM
+    afterwards (a leaf-offloaded VAE lands there too).
+  - **Ordering, when a load both transforms and quantises:** structural transform first,
+    quantisation last, and a prequantized source takes no structural transform at all. The three
+    clauses and why they are not negotiable are in `models/offload.py`'s docstring.
+- **Vendoring unreleased upstream code** → `models/<name>/vendor/`, **verbatim, import rewrites
+  only**. Put a provenance header in its `__init__.py` naming the repo, PR, branch, commit sha and
+  date. `models/*/vendor/` is already excluded from ruff and pyright by a glob, because editing it to
+  satisfy our linters destroys the one property that makes a re-sync reviewable. Never patch
+  installed diffusers: construct components directly and pass them in, so nothing resolves a class by
+  name through a registry we do not own. Pin, don't floor, any dependency whose experimental surface
+  the vendored code imports from.
 - **New model runner** → a subpackage `models/<name>/` with `runner.py` (a `NodeDescriptor` + a
   `NodeRunner` + `register_<name>(registry, store, policy)`) and an `__init__.py` re-exporting it;
   add a `try/except ImportError` block in `server/bootstrap.py`; add an optional-deps extra in

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: inline-core
-Version: 1.2.53
+Version: 1.2.62
 Summary: The generation engine behind Inline Studio.
 License-Expression: GPL-3.0-or-later
 Requires-Python: >=3.11
@@ -10,7 +10,7 @@ Provides-Extra: all
 Requires-Dist: accelerate>=0.30; extra == 'all'
 Requires-Dist: bitsandbytes>=0.43; (platform_system != 'Darwin') and extra == 'all'
 Requires-Dist: controlnet-aux>=0.0.7; extra == 'all'
-Requires-Dist: diffusers>=0.39; extra == 'all'
+Requires-Dist: diffusers==0.39.0; extra == 'all'
 Requires-Dist: einops>=0.7; extra == 'all'
 Requires-Dist: fastapi>=0.110; extra == 'all'
 Requires-Dist: huggingface-hub>=0.23; extra == 'all'
@@ -37,8 +37,9 @@ Requires-Dist: nvidia-ml-py>=12; extra == 'parallel'
 Requires-Dist: xfuser>=0.4; extra == 'parallel'
 Provides-Extra: runtime
 Requires-Dist: accelerate>=0.30; extra == 'runtime'
+Requires-Dist: av>=12; extra == 'runtime'
 Requires-Dist: controlnet-aux>=0.0.7; extra == 'runtime'
-Requires-Dist: diffusers>=0.39; extra == 'runtime'
+Requires-Dist: diffusers==0.39.0; extra == 'runtime'
 Requires-Dist: huggingface-hub>=0.23; extra == 'runtime'
 Requires-Dist: onnxruntime>=1.17; extra == 'runtime'
 Requires-Dist: safetensors>=0.4; extra == 'runtime'
@@ -67,17 +68,24 @@ The generation engine behind Inline. It takes a typed node graph (JSON) and retu
 low-VRAM laptops up to multi-GPU machines that split a single image's sampling across GPUs (via
 xDiT). It is Inline Studio's built-in render backend.
 
-Models today: **Z-Image** (Alibaba Tongyi), a 6B rectified-flow diffusion transformer and the model
-xDiT already supports, so the multi-GPU split works on it from the start; and **Krea 2** (Krea AI),
-a 12.9B single-stream MMDiT released as an undistilled RAW base plus an 8-step distilled Turbo.
-
-> Status: early, and running end to end against a stub engine. In place and tested: the graph engine,
-> the typed `/v1` HTTP + websocket API (durable runs, streamed progress, coalescing), the model-dir
-> scan, the device + memory policy (profiles, dtype, offload, int8), the low-level primitive node
-> vocabulary. The Z-Image loader is written and validates on a GPU.
-> Cross-request batching, single-image multi-GPU (an xDiT worker group behind the sampler seam, with
-> the policy and IPC round-trip tested), and out-of-process custom nodes are built as seams but not
-> yet running on real hardware.
+Models today, all running locally on your own GPU: **Z-Image** (Alibaba Tongyi), a 6B rectified-flow
+diffusion transformer and the model xDiT already supports, so the multi-GPU split works on it from the
+start; **Krea 2** (Krea AI), a 12.9B single-stream MMDiT released as an undistilled RAW base plus an
+8-step distilled Turbo; **FLUX.2** (Black Forest Labs); and **MiniMax H3**, which generates video and
+its soundtrack in a single pass.
+
+Core also runs the **LoRA trainer** behind Inline Studio's Trainer canvas, so the same engine that
+generates can fine-tune Z-Image, Krea 2, FLUX.2 and MiniMax H3 on your own images without a cloud
+step. Training is cheaper than generating: Krea 2 fits a 16GB card at 512px with a 4-bit base. Its
+dependencies sit behind the `training` extra. See the
+[LoRA training guide](https://inlinestudio.art/lora-training) for the measured VRAM table.
+
+> Status: the graph engine, the typed `/v1` HTTP + websocket API (durable runs, streamed progress,
+> coalescing), the model-dir scan, the device + memory policy (profiles, dtype, offload, int8), the
+> low-level primitive node vocabulary, the model runners above, and the LoRA trainer all run on real
+> hardware. Cross-request batching, single-image multi-GPU (an xDiT worker group behind the sampler
+> seam, with the policy and IPC round-trip tested), and out-of-process custom nodes are built as
+> seams but are not yet exercised on real hardware.
 
 ## Engine design
 
@@ -101,13 +109,18 @@ a 6 GB laptop, pure CPU, or split across several GPUs, without touching the grap
 
 Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).
 
+`--python` pins each install to `./.venv`; without it uv targets whatever venv or conda env is
+activated in your shell, and installs land there instead.
+
 ```
 uv venv
-uv pip install -e ".[server]"     # engine + HTTP/websocket API
-uv pip install -e ".[runtime]"    # + torch, diffusers, transformers (for real generation)
-uv pip install -e ".[runtime,parallel]"  # + xfuser, to split one image across GPUs (2+ GPUs)
+uv pip install --python .venv/bin/python -e ".[server]"    # engine + HTTP/websocket API
+uv pip install --python .venv/bin/python -e ".[runtime]"   # + torch, diffusers, transformers
+uv pip install --python .venv/bin/python -e ".[runtime,parallel]"  # + xfuser, 2+ GPUs
 ```
 
+Or let the launcher do it: `./webui.sh --install --extra runtime` (Windows: `.\webui.bat`).
+
 ## Models
 
 Drop files into the models dir (default `./models`, override with `INLINE_MODELS_DIR`), ComfyUI-style,

{inline_core-1.2.53 → inline_core-1.2.62}/README.md

@@ -5,17 +5,24 @@ The generation engine behind Inline. It takes a typed node graph (JSON) and retu
 low-VRAM laptops up to multi-GPU machines that split a single image's sampling across GPUs (via
 xDiT). It is Inline Studio's built-in render backend.
 
-Models today: **Z-Image** (Alibaba Tongyi), a 6B rectified-flow diffusion transformer and the model
-xDiT already supports, so the multi-GPU split works on it from the start; and **Krea 2** (Krea AI),
-a 12.9B single-stream MMDiT released as an undistilled RAW base plus an 8-step distilled Turbo.
-
-> Status: early, and running end to end against a stub engine. In place and tested: the graph engine,
-> the typed `/v1` HTTP + websocket API (durable runs, streamed progress, coalescing), the model-dir
-> scan, the device + memory policy (profiles, dtype, offload, int8), the low-level primitive node
-> vocabulary. The Z-Image loader is written and validates on a GPU.
-> Cross-request batching, single-image multi-GPU (an xDiT worker group behind the sampler seam, with
-> the policy and IPC round-trip tested), and out-of-process custom nodes are built as seams but not
-> yet running on real hardware.
+Models today, all running locally on your own GPU: **Z-Image** (Alibaba Tongyi), a 6B rectified-flow
+diffusion transformer and the model xDiT already supports, so the multi-GPU split works on it from the
+start; **Krea 2** (Krea AI), a 12.9B single-stream MMDiT released as an undistilled RAW base plus an
+8-step distilled Turbo; **FLUX.2** (Black Forest Labs); and **MiniMax H3**, which generates video and
+its soundtrack in a single pass.
+
+Core also runs the **LoRA trainer** behind Inline Studio's Trainer canvas, so the same engine that
+generates can fine-tune Z-Image, Krea 2, FLUX.2 and MiniMax H3 on your own images without a cloud
+step. Training is cheaper than generating: Krea 2 fits a 16GB card at 512px with a 4-bit base. Its
+dependencies sit behind the `training` extra. See the
+[LoRA training guide](https://inlinestudio.art/lora-training) for the measured VRAM table.
+
+> Status: the graph engine, the typed `/v1` HTTP + websocket API (durable runs, streamed progress,
+> coalescing), the model-dir scan, the device + memory policy (profiles, dtype, offload, int8), the
+> low-level primitive node vocabulary, the model runners above, and the LoRA trainer all run on real
+> hardware. Cross-request batching, single-image multi-GPU (an xDiT worker group behind the sampler
+> seam, with the policy and IPC round-trip tested), and out-of-process custom nodes are built as
+> seams but are not yet exercised on real hardware.
 
 ## Engine design
 
@@ -39,13 +46,18 @@ a 6 GB laptop, pure CPU, or split across several GPUs, without touching the grap
 
 Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).
 
+`--python` pins each install to `./.venv`; without it uv targets whatever venv or conda env is
+activated in your shell, and installs land there instead.
+
 ```
 uv venv
-uv pip install -e ".[server]"     # engine + HTTP/websocket API
-uv pip install -e ".[runtime]"    # + torch, diffusers, transformers (for real generation)
-uv pip install -e ".[runtime,parallel]"  # + xfuser, to split one image across GPUs (2+ GPUs)
+uv pip install --python .venv/bin/python -e ".[server]"    # engine + HTTP/websocket API
+uv pip install --python .venv/bin/python -e ".[runtime]"   # + torch, diffusers, transformers
+uv pip install --python .venv/bin/python -e ".[runtime,parallel]"  # + xfuser, 2+ GPUs
 ```
 
+Or let the launcher do it: `./webui.sh --install --extra runtime` (Windows: `.\webui.bat`).
+
 ## Models
 
 Drop files into the models dir (default `./models`, override with `INLINE_MODELS_DIR`), ComfyUI-style,

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

@@ -1,7 +1,7 @@
 [project]
 # PyPI name; the import package is `inline_core` (src/inline_core).
 name = "inline-core"
-version = "1.2.53"
+version = "1.2.62"
 description = "The generation engine behind Inline Studio."
 readme = "README.md"
 license = "GPL-3.0-or-later"
@@ -18,7 +18,9 @@ runtime = [
   # A bare `torch` is CPU-only on Windows; see [tool.uv] below and requirements.txt.
   "torch>=2.2",
   # Krea 2 needs diffusers >= 0.39 (Krea2Pipeline); Z-Image needs >= 0.36 (ZImagePipeline).
-  "diffusers>=0.39",
+  # Pinned, not floored: MiniMax H3 is vendored from an unmerged PR and imports six symbols
+  # from the experimental Modular Diffusers surface, which a minor release may rename.
+  "diffusers==0.39.0",
   "transformers>=4.44",
   "accelerate>=0.30",
   "safetensors>=0.4",
@@ -32,6 +34,10 @@ runtime = [
   # HED, lineart, MLSD, scribble, normal. DWPose runs its detector on ONNX Runtime.
   "controlnet-aux>=0.0.7",
   "onnxruntime>=1.17",
+  # MiniMax H3's reference node decodes a wired video or audio clip when it builds the reference.
+  # The blocks raise a plain ImportError without it, so the node would advertise two ports it
+  # cannot read. Video output goes out through ffmpeg, not this.
+  "av>=12",
 ]
 server = [
   "fastapi>=0.110",
@@ -71,7 +77,7 @@ dev = [
 all = [
   # runtime
   "torch>=2.2",
-  "diffusers>=0.39",
+  "diffusers==0.39.0",
   "transformers>=4.44",
   "accelerate>=0.30",
   "safetensors>=0.4",
@@ -116,15 +122,21 @@ packages = ["src/inline_core"]
 [tool.ruff]
 line-length = 100
 target-version = "py311"
+# Vendored upstream code (see models/minimaxh3/vendor/__init__.py). Editing it to satisfy our
+# linters would destroy the one property that makes a re-sync reviewable: it is verbatim.
+extend-exclude = ["src/inline_core/models/*/vendor"]
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "UP", "B"]
 
 [tool.pyright]
 include = ["src", "tests"]
+exclude = ["**/models/*/vendor"]
 pythonVersion = "3.11"
 typeCheckingMode = "strict"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-pythonpath = ["src"]
+# "." so `tests` imports as a package: several suites share fixtures via `from tests.x import y`,
+# and without it those modules fail to collect and silently stop running.
+pythonpath = ["src", "."]

inline_core-1.2.62/scripts/flux2_train_matrix.py

@@ -0,0 +1,204 @@
+"""VRAM + step-time sweep for FLUX.2 LoRA training: the cells behind the README benchmark table.
+
+    cd core && PYTHONPATH=src .venv/bin/python scripts/flux2_train_matrix.py --dataset <dir>
+
+One cell = one real run of `python -m inline_core.training`, the same entry point the Trainer tab
+spawns, so a number here is a number a user would see. Anything else (importing `train` in-process,
+or a hand-rolled loop) would measure a different program.
+
+Held fixed at the settings the existing Z-Image and Krea 2 rows used: 12 steps, rank 16, batch 1,
+gradient checkpointing on. What varies is resolution and base precision. Peak VRAM is the trainer's
+own `torch.cuda.max_memory_allocated` reading off the last progress line; an OOM is recorded as a
+cell rather than aborting the sweep, because "does not fit" is a result the table needs.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+_REPO = Path(__file__).resolve().parent.parent.parent
+_CORE = _REPO / "core"
+_DEFAULT_OUT = _REPO / "outputs" / "flux2-train-matrix"
+
+# (resolution, baseQuant). `none` is the bf16 base; `nf4` is the 4-bit (QLoRA) base.
+CELLS: tuple[tuple[int, str], ...] = (
+    (512, "none"),
+    (512, "nf4"),
+    (1024, "none"),
+    (1024, "nf4"),
+)
+
+_STEPS = 12
+_RANK = 16
+
+
+def _manifest(work: Path, dataset: Path, models: Path, resolution: int, quant: str) -> Path:
+    """The same manifest shape `studio/training.py::_prepare` writes."""
+    checkpoints = work / "checkpoints"
+    checkpoints.mkdir(parents=True, exist_ok=True)
+    manifest = {
+        "runId": work.name,
+        "workingDir": str(work),
+        "datasetDir": str(dataset),
+        "checkpointDir": str(checkpoints),
+        "outputPath": str(work / "lora.safetensors"),
+        "resumeFrom": None,
+        "modelsDir": str(models),
+        "arch": "flux2",
+        # FLUX.2 offers one base mode: the undistilled klein base. `raw` is that mode's key.
+        "baseMode": "raw",
+        "triggerWord": "",
+        "hyperparams": {
+            "arch": "flux2",
+            "baseMode": "raw",
+            "baseQuant": quant,
+            # Explicit, not `auto`: the sweep is measuring what each precision costs, and auto would
+            # silently swap a bf16 cell for NF4 the moment it predicted a bad fit.
+            "offload": "off",
+            "loraScope": "full",
+            "captionDropout": 0.0,
+            "flipAugment": False,
+            "rank": _RANK,
+            "alpha": _RANK,
+            "learningRate": 1e-4,
+            "batchSize": 1,
+            "steps": _STEPS,
+            "saveEvery": _STEPS,
+            "resolution": resolution,
+        },
+        "gpuIds": [],
+    }
+    path = work / "manifest.json"
+    path.write_text(json.dumps(manifest, indent=2), encoding="utf-8")
+    return path
+
+
+def _run_cell(python: str, manifest: Path, log: Path) -> dict[str, object]:
+    """Drain the JSON-line protocol, keeping the last VRAM reading and the wall time from the first
+    training step onward - loading and latent precache are not what the table reports."""
+    env = {**os.environ, "PYTHONPATH": str(_CORE / "src")}
+    proc = subprocess.Popen(
+        [python, "-m", "inline_core.training", str(manifest)],
+        cwd=str(_CORE),
+        env=env,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        bufsize=1,
+    )
+    vram: float | None = None
+    error: str | None = None
+    first_step_at: float | None = None
+    last_step_at: float | None = None
+    steps_seen = 0
+    started = time.perf_counter()
+    lines: list[str] = []
+    assert proc.stdout is not None
+    for line in proc.stdout:
+        lines.append(line)
+        line = line.strip()
+        if not line.startswith("{"):
+            continue
+        try:
+            message = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        kind = message.get("type")
+        if kind == "progress":
+            if message.get("vram") is not None:
+                vram = float(message["vram"])
+            if message.get("step"):
+                steps_seen = int(message["step"])
+                now = time.perf_counter()
+                if first_step_at is None:
+                    first_step_at = now
+                last_step_at = now
+        elif kind == "error":
+            error = str(message.get("message") or "")
+    proc.wait()
+    log.write_text("".join(lines), encoding="utf-8")
+
+    oom = bool(error) and ("out of gpu memory" in error.lower() or "out of memory" in error.lower())
+    # Step 1 pays for the first graph build, so time the interval after it and scale by the gap.
+    per_step: float | None = None
+    if first_step_at is not None and last_step_at is not None and steps_seen > 1:
+        per_step = (last_step_at - first_step_at) / (steps_seen - 1)
+    return {
+        "peak_vram_gb": vram,
+        "seconds_per_step": round(per_step, 2) if per_step else None,
+        "seconds_12_steps": round(per_step * _STEPS, 1) if per_step else None,
+        "total_seconds": round(time.perf_counter() - started, 1),
+        "steps_completed": steps_seen,
+        "status": "oom" if oom else ("ok" if proc.returncode == 0 else "failed"),
+        "error": error,
+        "log": log.name,
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--dataset", type=Path, required=True, help="dir of NNNN.jpg + NNNN.txt")
+    parser.add_argument("--out", type=Path, default=_DEFAULT_OUT)
+    parser.add_argument("--models", type=Path, default=_CORE / "models")
+    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="substring of a cell id, to redo one row")
+    args = parser.parse_args()
+
+    if not args.dataset.is_dir():
+        raise SystemExit(f"dataset not found: {args.dataset}")
+
+    args.out.mkdir(parents=True, exist_ok=True)
+    results_path = args.out / "results.json"
+    results: dict[str, dict[str, object]] = {}
+    if results_path.exists():
+        results = json.loads(results_path.read_text()).get("cells", {})
+
+    label = args.gpu
+    if not label:
+        try:
+            name = subprocess.run(
+                ["nvidia-smi", "--query-gpu=name,memory.total", "--format=csv,noheader"],
+                capture_output=True,
+                text=True,
+                check=True,
+            ).stdout.strip()
+            label = name.splitlines()[0]
+        except Exception:  # noqa: BLE001 - the label is cosmetic
+            label = "unknown GPU"
+
+    def write() -> None:
+        results_path.write_text(
+            json.dumps(
+                {"gpu": label, "steps": _STEPS, "rank": _RANK, "cells": results},
+                indent=2,
+            )
+        )
+
+    for resolution, quant in CELLS:
+        cell_id = f"{resolution}-{quant}"
+        if args.only and args.only not in cell_id:
+            continue
+        work = args.out / cell_id
+        work.mkdir(parents=True, exist_ok=True)
+        manifest = _manifest(work, args.dataset, args.models, resolution, quant)
+        print(f"--- {cell_id}: {resolution}px, base {quant} ---", flush=True)
+        result = _run_cell(args.python, manifest, args.out / f"{cell_id}.log")
+        result.update({"resolution": resolution, "base_quant": quant})
+        results[cell_id] = result
+        print(json.dumps(result, indent=2), flush=True)
+        write()
+
+    write()
+    print(f"\n{results_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())