inline-core 1.3.1__tar.gz → 1.3.12__tar.gz

{inline_core-1.3.1 → inline_core-1.3.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: inline-core
-Version: 1.3.1
+Version: 1.3.12
 Summary: The generation engine behind Inline Studio.
 License-Expression: GPL-3.0-or-later
 Requires-Python: >=3.11
@@ -78,8 +78,9 @@ xDiT). It is Inline Studio's built-in render backend.
 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.
+8-step distilled Turbo; **FLUX.2** (Black Forest Labs), natively multi-reference; **MiniMax H3**
+(MiniMax), which generates video and its soundtrack in a single pass; and **LTX-2.5** (Lightricks), a
+22B video model, also with sound.
 
 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, MiniMax H3 and LTX-2.5 on your own images without a cloud
@@ -89,10 +90,10 @@ dependencies sit behind the `training` extra. See the
 
 > 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.
+> low-level primitive node vocabulary, the model runners above, single-image multi-GPU (an xDiT
+> worker group behind the sampler seam), and the LoRA trainer all run on real hardware. Cross-request
+> batching and out-of-process custom nodes are built as seams but are not yet exercised on real
+> hardware.
 
 ## Engine design
 
@@ -131,18 +132,17 @@ Or let the launcher do it: `./webui.sh --install --extra runtime` (Windows: `.\w
 ## Models
 
 Drop files into the models dir (default `./models`, override with `INLINE_MODELS_DIR`), ComfyUI-style,
-by category:
+by category. One example per category below; the per-model file list for all five architectures is in
+the [Inline Studio README](../README.md#generate).
 
 ```
 models/
-  diffusion_models/   z_image_turbo_bf16.safetensors        <- Z-Image
-                      krea2_turbo_bf16.safetensors          <- Krea 2 Turbo (generate)
-                      krea2_raw_bf16.safetensors            <- Krea 2 RAW (fine-tune)
-  vae/                ae.safetensors                        <- Z-Image
-                      qwen_image_vae_diffusers.safetensors  <- Krea 2
-  text_encoders/      qwen_3_4b.safetensors                 <- Z-Image
-                      qwen3vl_4b_bf16.safetensors           <- Krea 2
-  loras/  controlnet/  checkpoints/  ...
+  diffusion_models/   z_image_turbo_bf16.safetensors        <- transformers, one file per model
+  vae/                qwen_image_vae_diffusers.safetensors  <- Krea 2, diffusers format
+  text_encoders/      qwen_3_4b.safetensors                 <- Z-Image and FLUX.2 klein 4B
+                      MiniMax-H3-text-encoder/              <- a folder, not a single file
+  loras/              trained adapters and control LoRAs
+  controlnet/  checkpoints/  ...
 ```
 
 **Z-Image loads from a single diffusion `.safetensors`.** Drop that one ComfyUI-style file in
@@ -151,8 +151,8 @@ a VAE + text-encoder + tokenizer, resolved from **local files** - `vae/*.safeten
 HF-format `text_encoders/` dir.
 
 **Nothing is ever downloaded as a side effect of a render.** Every load runs `local_files_only=True`,
-so a missing model is a clear, fast error, not a silent multi-GB fetch. Models arrive by exactly two
-paths:
+so a missing model fails immediately with a clear error and never triggers a silent multi-GB fetch.
+Models arrive by exactly two paths:
 
 1. **You place files** under `models/` (bring-your-own / fully offline); or
 2. **You download them explicitly** from the Z-Image node's model popup in the UI - it lists the
@@ -178,9 +178,9 @@ streamed tensor by tensor onto the GPU.
 renders any node generically - adding a node type needs no UI release.
 
 **High-level model nodes are what the user sees.** Generation is one-click: you drop a single
-**Z-Image Turbo**, **Krea 2 Turbo** or **Krea 2 RAW** node, wire a Prompt into it, and hit Run. The
-node hooks up the diffusion model, VAE, and text-encoder behind the scenes - no loader/sampler
-wiring.
+**Z-Image Turbo**, **Krea 2**, **FLUX.2**, **MiniMax H3** or **LTX-2.5** node, wire a Prompt into
+it, and hit Run. The node hooks up the diffusion model, VAE, and text-encoder behind the scenes - no
+loader/sampler wiring.
 
 Underneath, a **low-level primitive vocabulary** exists (`load/diffusion-model`, `load/vae`,
 `load/text-encoder`, `encode/text`, `latent/empty`, `sample`, `vae/decode`, `vae/encode`) - the
@@ -192,8 +192,7 @@ and never appear in the add-node menu. Engine handles (`model`, `vae`, `text-enc
 
 Cut a single image's latency by running its denoise across several GPUs. The denoise loop (the
 iterative sampling step) is the expensive part of a render; with two or more GPUs, Inline Core runs
-each step's transformer forward collectively across them so one image finishes faster. This is not
-"one image per GPU" (independent renders); it is one image whose sampling is shared by all the GPUs.
+each step's transformer forward collectively across them so one image finishes faster.
 
 It is done with xDiT (`xfuser`), which parallelizes diffusion-transformer inference. xfuser runs in
 an isolated worker group the engine spawns (one process per GPU via `torchrun`) and talks to over
@@ -226,14 +225,11 @@ Enabling it:
    ```
    The degrees multiply to the world size, which must equal the number of GPUs.
 
-The device policy and the worker-group IPC are in place and tested with a stub worker; the real
-xfuser denoise lands with the GPU-side Z-Image runner.
-
 ## Memory: fit a big model onto a small GPU
 
 When a model is too large to hold full-precision on your GPU - or larger than your system RAM - Inline
 Core fits it to the machine automatically, **with no flags**. This is the low-VRAM path, and it aims to
-"just run" instead of making you tune profiles.
+just run, with no profiles to tune.
 
 - **Weights stream straight to the GPU.** Each component loads directly onto the GPU from its
   memory-mapped `.safetensors` - the engine never materializes a full copy in system RAM first. So you
@@ -242,7 +238,7 @@ Core fits it to the machine automatically, **with no flags**. This is the low-VR
 - **Auto-fit picks the lightest plan that fits.** The policy sizes the model against your VRAM and
   chooses, in order: full-precision **resident** → **int8 resident** (weight-only quantization halves the
   big weights so they fit on the GPU) → **CPU-offload streaming** (submodules move on/off the GPU). A card
-  that can't hold the model full-precision quantizes to int8 on its own - no need to know a flag.
+  that cannot hold the model at full precision quantizes to int8 on its own, with no flag to set.
 - **Load-time fit check.** A model too large for VRAM + RAM fails fast with a clear message on the node,
   instead of crashing mid-load. The model popup also shows the estimate up front (fits / will run int8 /
   won't fit).

{inline_core-1.3.1 → inline_core-1.3.12}/README.md

@@ -8,8 +8,9 @@ xDiT). It is Inline Studio's built-in render backend.
 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.
+8-step distilled Turbo; **FLUX.2** (Black Forest Labs), natively multi-reference; **MiniMax H3**
+(MiniMax), which generates video and its soundtrack in a single pass; and **LTX-2.5** (Lightricks), a
+22B video model, also with sound.
 
 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, MiniMax H3 and LTX-2.5 on your own images without a cloud
@@ -19,10 +20,10 @@ dependencies sit behind the `training` extra. See the
 
 > 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.
+> low-level primitive node vocabulary, the model runners above, single-image multi-GPU (an xDiT
+> worker group behind the sampler seam), and the LoRA trainer all run on real hardware. Cross-request
+> batching and out-of-process custom nodes are built as seams but are not yet exercised on real
+> hardware.
 
 ## Engine design
 
@@ -61,18 +62,17 @@ Or let the launcher do it: `./webui.sh --install --extra runtime` (Windows: `.\w
 ## Models
 
 Drop files into the models dir (default `./models`, override with `INLINE_MODELS_DIR`), ComfyUI-style,
-by category:
+by category. One example per category below; the per-model file list for all five architectures is in
+the [Inline Studio README](../README.md#generate).
 
 ```
 models/
-  diffusion_models/   z_image_turbo_bf16.safetensors        <- Z-Image
-                      krea2_turbo_bf16.safetensors          <- Krea 2 Turbo (generate)
-                      krea2_raw_bf16.safetensors            <- Krea 2 RAW (fine-tune)
-  vae/                ae.safetensors                        <- Z-Image
-                      qwen_image_vae_diffusers.safetensors  <- Krea 2
-  text_encoders/      qwen_3_4b.safetensors                 <- Z-Image
-                      qwen3vl_4b_bf16.safetensors           <- Krea 2
-  loras/  controlnet/  checkpoints/  ...
+  diffusion_models/   z_image_turbo_bf16.safetensors        <- transformers, one file per model
+  vae/                qwen_image_vae_diffusers.safetensors  <- Krea 2, diffusers format
+  text_encoders/      qwen_3_4b.safetensors                 <- Z-Image and FLUX.2 klein 4B
+                      MiniMax-H3-text-encoder/              <- a folder, not a single file
+  loras/              trained adapters and control LoRAs
+  controlnet/  checkpoints/  ...
 ```
 
 **Z-Image loads from a single diffusion `.safetensors`.** Drop that one ComfyUI-style file in
@@ -81,8 +81,8 @@ a VAE + text-encoder + tokenizer, resolved from **local files** - `vae/*.safeten
 HF-format `text_encoders/` dir.
 
 **Nothing is ever downloaded as a side effect of a render.** Every load runs `local_files_only=True`,
-so a missing model is a clear, fast error, not a silent multi-GB fetch. Models arrive by exactly two
-paths:
+so a missing model fails immediately with a clear error and never triggers a silent multi-GB fetch.
+Models arrive by exactly two paths:
 
 1. **You place files** under `models/` (bring-your-own / fully offline); or
 2. **You download them explicitly** from the Z-Image node's model popup in the UI - it lists the
@@ -108,9 +108,9 @@ streamed tensor by tensor onto the GPU.
 renders any node generically - adding a node type needs no UI release.
 
 **High-level model nodes are what the user sees.** Generation is one-click: you drop a single
-**Z-Image Turbo**, **Krea 2 Turbo** or **Krea 2 RAW** node, wire a Prompt into it, and hit Run. The
-node hooks up the diffusion model, VAE, and text-encoder behind the scenes - no loader/sampler
-wiring.
+**Z-Image Turbo**, **Krea 2**, **FLUX.2**, **MiniMax H3** or **LTX-2.5** node, wire a Prompt into
+it, and hit Run. The node hooks up the diffusion model, VAE, and text-encoder behind the scenes - no
+loader/sampler wiring.
 
 Underneath, a **low-level primitive vocabulary** exists (`load/diffusion-model`, `load/vae`,
 `load/text-encoder`, `encode/text`, `latent/empty`, `sample`, `vae/decode`, `vae/encode`) - the
@@ -122,8 +122,7 @@ and never appear in the add-node menu. Engine handles (`model`, `vae`, `text-enc
 
 Cut a single image's latency by running its denoise across several GPUs. The denoise loop (the
 iterative sampling step) is the expensive part of a render; with two or more GPUs, Inline Core runs
-each step's transformer forward collectively across them so one image finishes faster. This is not
-"one image per GPU" (independent renders); it is one image whose sampling is shared by all the GPUs.
+each step's transformer forward collectively across them so one image finishes faster.
 
 It is done with xDiT (`xfuser`), which parallelizes diffusion-transformer inference. xfuser runs in
 an isolated worker group the engine spawns (one process per GPU via `torchrun`) and talks to over
@@ -156,14 +155,11 @@ Enabling it:
    ```
    The degrees multiply to the world size, which must equal the number of GPUs.
 
-The device policy and the worker-group IPC are in place and tested with a stub worker; the real
-xfuser denoise lands with the GPU-side Z-Image runner.
-
 ## Memory: fit a big model onto a small GPU
 
 When a model is too large to hold full-precision on your GPU - or larger than your system RAM - Inline
 Core fits it to the machine automatically, **with no flags**. This is the low-VRAM path, and it aims to
-"just run" instead of making you tune profiles.
+just run, with no profiles to tune.
 
 - **Weights stream straight to the GPU.** Each component loads directly onto the GPU from its
   memory-mapped `.safetensors` - the engine never materializes a full copy in system RAM first. So you
@@ -172,7 +168,7 @@ Core fits it to the machine automatically, **with no flags**. This is the low-VR
 - **Auto-fit picks the lightest plan that fits.** The policy sizes the model against your VRAM and
   chooses, in order: full-precision **resident** → **int8 resident** (weight-only quantization halves the
   big weights so they fit on the GPU) → **CPU-offload streaming** (submodules move on/off the GPU). A card
-  that can't hold the model full-precision quantizes to int8 on its own - no need to know a flag.
+  that cannot hold the model at full precision quantizes to int8 on its own, with no flag to set.
 - **Load-time fit check.** A model too large for VRAM + RAM fails fast with a clear message on the node,
   instead of crashing mid-load. The model popup also shows the estimate up front (fits / will run int8 /
   won't fit).

{inline_core-1.3.1 → inline_core-1.3.12}/pyproject.toml

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

{inline_core-1.3.1 → inline_core-1.3.12}/src/inline_core/characters/apply.py

@@ -42,17 +42,27 @@ class AppliedCharacter:
         #: turned down and the character wire carries no controls of its own.
         self.lora_strength = lora_strength
 
-    def prompt_prefix(self, first_position: int) -> str:
-        """Text naming the positions the character lands on, so ordinal prompting resolves."""
+    def prompt_prefix(self, first_position: int, style: str = "ordinal") -> str:
+        """Text naming the positions the character lands on, so positional prompting resolves.
+
+        ``style`` because a model only resolves the form it was trained on: FLUX.2 reads the ordinal
+        prose below, MiniMax H3 reads ``<Picture N>`` tokens (``models/references.py``), and handing
+        either the other one names positions it cannot see.
+        """
         if not self.refs:
             # A LoRA carries the likeness, so the description is all the prompt needs.
             detail = " ".join(self.description.split())
             return f"{detail} " if detail else ""
-        positions = [str(first_position + i) for i in range(len(self.refs))]
-        if len(positions) == 1:
+        positions = [first_position + i for i in range(len(self.refs))]
+        if style == "token":
+            tokens = " ".join(f"<Picture {n}>" for n in positions)
+            plural = "" if len(positions) == 1 else "each"
+            which = f"{tokens} {'shows' if not plural else 'show'}"
+        elif len(positions) == 1:
             which = f"Image {positions[0]} shows"
         else:
-            which = f"Images {', '.join(positions[:-1])} and {positions[-1]} show"
+            ordinals = [str(n) for n in positions]
+            which = f"Images {', '.join(ordinals[:-1])} and {ordinals[-1]} show"
         line = f"{which} {self.name}, the same character in every image."
         detail = " ".join(self.description.split())
         if not detail:
@@ -67,7 +77,9 @@ def _cache_root() -> Path:
     return data_dir() / "characters"
 
 
-def char_apply(chosen: str, arch: str = encode.FLUX2_KLEIN_ARCH) -> AppliedCharacter | None:
+def char_apply(
+    chosen: str, arch: str = encode.FLUX2_KLEIN_ARCH, prefer: str | None = None
+) -> AppliedCharacter | None:
     """How a character applies on ``arch``, or None when none is picked. An unreadable pick raises
     rather than silently generating the wrong person.
 
@@ -84,18 +96,20 @@ def char_apply(chosen: str, arch: str = encode.FLUX2_KLEIN_ARCH) -> AppliedChara
 
     doc = cf.read(path)
     digest = library.content_hash(path)
-    references = arch == encode.FLUX2_KLEIN_ARCH
+    # Whether this arch reads references at all, which is exactly the archs with a policy for them.
+    references = arch in encode.REFERENCE_POLICIES
 
     if references and not cf.payload_valid(doc.manifest, arch, encode.PAYLOAD_ENCODER_VERSION):
-        doc = _recompile(doc, path)
+        doc = _recompile(doc, path, arch)
         digest = library.content_hash(path)
 
     description = _description(doc)
     lora = _extract_lora(doc, digest, arch)
     strength = encode.lora_strength(doc.manifest, arch)
     # A trained adapter wins unless the character says otherwise: the user asked for it explicitly,
-    # and loading both would apply the identity twice.
-    mode = doc.manifest.apply.get(arch) or ("lora" if lora else "reference")
+    # and loading both would apply the identity twice. `prefer` overrides both, for a node that can
+    # only run one way: H3's reference partition needs a reference and cannot use an adapter alone.
+    mode = prefer or doc.manifest.apply.get(arch) or ("lora" if lora else "reference")
     # No reference channel on this arch, so the adapter is the only way it can apply at all.
     if not references:
         mode = "lora"
@@ -137,9 +151,9 @@ def _description(doc: cf.CharDoc) -> str:
     return raw.decode("utf-8", errors="replace") if raw else ""
 
 
-def _recompile(doc: cf.CharDoc, path: Path) -> cf.CharDoc:
+def _recompile(doc: cf.CharDoc, path: Path, arch: str = encode.FLUX2_KLEIN_ARCH) -> cf.CharDoc:
     """Rebuild a stale payload from ``refs/``. Payloads are cache, so this always works."""
-    logger.info("Recompiling the %s payload for %s", encode.FLUX2_KLEIN_ARCH, path.name)
+    logger.info("Recompiling the %s payload for %s", arch, path.name)
     import io
 
     from PIL import Image
@@ -153,7 +167,7 @@ def _recompile(doc: cf.CharDoc, path: Path) -> cf.CharDoc:
             )
         images.append(Image.open(io.BytesIO(raw)).convert("RGB"))
 
-    encode.build_payload(doc.manifest, doc.members, images)
+    encode.build_payload(doc.manifest, doc.members, images, arch)
     cf.write(path, doc)
     return doc
 

{inline_core-1.3.1 → inline_core-1.3.12}/src/inline_core/characters/charfile.py

@@ -41,6 +41,18 @@ _KEY_ORDER = (
 )
 
 
+#: Where a reference came from. Nested inside `refs` rather than a new top-level key on purpose:
+#: `from_json` models only the keys it knows, so a top-level addition is destroyed by any older
+#: build that rewrites the file, and three code paths rewrite one routinely.
+ORIGIN_ORIGINAL = "original"
+ORIGIN_HARVESTED = "harvested"
+
+
+def origin_of(ref: dict[str, Any]) -> str:
+    """Absent means original: every reference written before harvesting existed is one."""
+    return str(ref.get("origin") or ORIGIN_ORIGINAL)
+
+
 class CharFileError(Exception):
     """A ``.char`` that cannot be trusted. The message is shown to the user."""
 
@@ -190,12 +202,29 @@ def write(path: Path | str, doc: CharDoc) -> Path:
 
 
 def refs_fingerprint(manifest: Manifest, policy: dict[str, Any]) -> str:
-    """Ordered ref hashes plus policy, so a reorder or a resize-budget change both invalidate."""
-    parts = [str(ref.get("sha256", "")) for ref in manifest.refs]
+    """Ordered ref hashes plus policy, so a reorder or a resize-budget change both invalidate.
+
+    Originals only. A harvested reference in here would mark the trained adapter stale the moment
+    one was taken, and `_extract_lora` drops a stale adapter with an INFO log - so the loop whose
+    whole point is a better adapter would silently switch off the adapter the user already has.
+    """
+    kept = [ref for ref in manifest.refs if origin_of(ref) == ORIGIN_ORIGINAL]
+    parts = [str(ref.get("sha256", "")) for ref in kept]
     parts.append(json.dumps(policy, sort_keys=True, separators=(",", ":")))
     return hashlib.sha256("\x1f".join(parts).encode()).hexdigest()
 
 
+def refs_identity(manifest: Manifest) -> str:
+    """Which reference set this is, order included and policy excluded.
+
+    Separate from `refs_fingerprint`, which answers "is this payload still valid" and so covers
+    only the originals and the policy. This answers "were two nodes handed the same character",
+    which a payload node needs because it compiles from a doc it is not the one holding.
+    """
+    parts = [f"{ref.get('sha256', '')}:{origin_of(ref)}" for ref in manifest.refs]
+    return hashlib.sha256("\x1f".join(parts).encode()).hexdigest()
+
+
 def payload_valid(manifest: Manifest, arch: str, encoder_version: str) -> bool:
     """Whether ``payloads/<arch>/`` can be used as-is, or must be recompiled from ``refs/``."""
     payload = manifest.payloads.get(arch)