Anima In-Context Character LoRA v1 + ComfyUI nodes + workflow

.gitattributes

@@ -33,3 +33,6 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+samples/example_output.png filter=lfs diff=lfs merge=lfs -text
+samples/example_output2.png filter=lfs diff=lfs merge=lfs -text
+samples/example_reference.jpg filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,119 @@
+---
+license: other
+license_name: circlestone-labs-non-commercial
+license_link: https://huggingface.co/circlestone-labs/Anima
+base_model: circlestone-labs/Anima
+tags:
+- anima
+- lora
+- in-context
+- character-reference
+- ip-adapter-alternative
+- comfyui
+- anime
+pipeline_tag: text-to-image
+library_name: diffusers
+---
+
+# Anima In-Context Character
+
+**Reference-driven character generation for [Anima](https://huggingface.co/circlestone-labs/Anima)** — attach a few images of a character and generate that character in new poses, scenes and expressions. No per-character training. Works on characters the base model has never seen.
+
+This is a LoRA + a small ComfyUI node pack. Unlike CLIP-embedding IP-Adapters, the reference enters the model as its **own VAE latent inside self-attention**, so fine details (hair ornaments, clothing patterns, eye color) are preserved in principle rather than summarized into a single embedding.
+
+|  | |
+|---|---|
+| Base model | Anima 2B (Cosmos-Predict2 DiT + Qwen3-0.6B text encoder, WanVAE) |
+| Type | in-context reference LoRA (DiT, rank 64) + ComfyUI nodes |
+| Trained on | ~994k anime images / ~62k (reference≠target) character pairs |
+| Use | attach 1–3 reference images → generate in any pose/scene |
+
+---
+
+## How it works
+
+Anima's DiT is a **video** architecture: latents flow as `(B, C, T, H, W)` and self-attention runs over the flattened `(t h w)` sequence with 3D RoPE (`max_frames=128`, `patch_temporal=1`).
+
+This adapter exploits that:
+
+1. The reference image's VAE latent is **concatenated as an extra frame on the T axis** — `[generated frame, reference frame(s)]`. It gets a distinct temporal RoPE coordinate, so it never collides spatially with the generated frame.
+2. Per-frame timesteps: the reference frame is conditioned at **timestep 0 (a clean image)** while the generated frame follows the sampler. This is the OminiControl-style "clean condition token" recipe.
+3. The generated frame attends to the reference tokens via **shared self-attention** — the reference's appearance flows in directly, not through a lossy embedding.
+4. Reference frames are sliced off the output before the sampler sees it.
+
+The LoRA teaches the base T2I model to *use* those reference tokens. It was trained on **same-character / different-artist** pairs with character names removed from the captions, so identity must flow through the reference frames (not the text) — the network learns a transferable "copy this character into a new context" skill rather than memorizing specific characters.
+
+## How it was made
+
+- **Data**: ~994k tagged anime images → grouped by character → **same character, different artist** pairs (so the character stream carries identity, not style) → filtered by anime-character identity similarity (deepghs *ccip*) to drop costume/wrong-tag noise → references composited onto white via anime segmentation.
+- **Captions**: general tags only ([OppaiOracle](https://huggingface.co/Grio43/OppaiOracle)), with character/artist/copyright tags stripped — so identity can only flow through the reference.
+- **Training**: DiT LoRA (rank 64, α 32), reference frames appended at timestep 0, loss on the generated frame only, 10% reference-dropout for CFG. Multi-view pairs (2 references from distinct artists) so "attach a few images" is trained, not just inference-time.
+- Full pipeline & node source: [github.com/daraskme/anima-duet](https://github.com/daraskme) *(see project repo)*.
+
+---
+
+## ComfyUI usage
+
+### 1. Install the custom nodes
+Clone the node pack into `ComfyUI/custom_nodes/`:
+```
+comfyui-anima-incontext/   (from this repo's `comfyui-anima-incontext/` folder)
+```
+Restart ComfyUI. You should see nodes under the **anima/incontext** category.
+
+### 2. Get the models
+| File | Put in |
+|---|---|
+| `anima-incontext-character.safetensors` (this repo) | `ComfyUI/models/loras/` |
+| `anima-base-v1.0.safetensors` | `ComfyUI/models/diffusion_models/` |
+| `qwen_3_06b_base.safetensors` | `ComfyUI/models/text_encoders/` |
+| `qwen_image_vae.safetensors` | `ComfyUI/models/vae/` |
+
+(The three base files come from the [Anima](https://huggingface.co/circlestone-labs/Anima) release.)
+
+### 3. Load the workflow
+Drag `workflow_anima_incontext_character.json` onto the ComfyUI canvas. It's wired as:
+
+```
+UNETLoader ─► LoraLoaderModelOnly (this LoRA) ─┐
+LoadImage ×2 ─► AnimaRefEncode ×2 ─► AnimaRefLatentBatch ─► AnimaInContextApply ─► KSampler ─► VAEDecode ─► SaveImage
+```
+
+### 4. Nodes
+- **Anima Reference Encode** — IMAGE (+ optional MASK) → LATENT. A mask composites the subject on white (recommended). `target_width/height` resizes onto a white canvas so refs match the generation resolution.
+- **Anima Reference Latent Batch** — combine 2+ references (full-body + face works best).
+- **Anima In-Context Reference Apply** — attach references to the model.
+  - `strength` 1.0 = neutral, >1 stronger reference pull, 0 = off
+  - `cond_only` (default on) — reference masked on the CFG-uncond half; matches training
+  - `fit_mode` `pad` (aspect-preserving, default) / `stretch` / `crop`
+  - `start_percent`/`end_percent` — sampling window
+
+## Tips for best results
+
+- **Attach a full-body shot + a face close-up.** Two references (batched) noticeably improve hair-length and face fidelity over a single one.
+- **Also describe the appearance in the prompt** (hair color, outfit, ears, etc.). Reference + matching tags is the strongest combination — the prompt describes the *pose/scene*, the reference carries the *identity*.
+- Composite the subject on a **white background** (use the mask input) — reduces background bleed.
+- If identity drifts, raise `strength` to 1.2–1.5 or add a third reference.
+- Recommended base sampler: `er_sde` / `simple`, 30 steps, CFG 4, `discrete_flow_shift` 3.0.
+
+## Limitations
+
+- Fine ornament/pattern detail can drift; multi-reference + appearance tags mitigate it.
+- Strong reference pull can slightly wash out backgrounds — trade off with `strength` and the sampling window.
+- Anime domain (the training data is anime illustration).
+
+## License
+
+Base model **Anima** is under the **CircleStone Labs Non-Commercial License** (derives from Cosmos-Predict2 → NVIDIA Open Model License also applies). **This LoRA is a derivative and is released for non-commercial use.** Generated images may be usable commercially per the base license, but **verify the current Anima LICENSE before any commercial use or redistribution.** Training data is derived from public booru sources.
+
+---
+
+## 日本語
+
+**Anima 向けの参照画像キャラ生成 LoRA。** キャラ画像を数枚添付するだけで、そのキャラを別ポーズ・別シーンで生成できます（キャラ毎の学習不要、未知キャラも可）。
+
+CLIP 埋め込み型 IP-Adapter と違い、参照画像を**モデル自身の VAE latent のまま self-attention に入れる**ため、髪飾り・服の柄・瞳の色などの細部が原理的に落ちません。参照を DiT の時間軸に「クリーンフレーム（timestep=0）」として連結する OminiControl 系の方式です。
+
+**使い方**: `comfyui-anima-incontext` ノードを導入 → このLoRAを `models/loras/` へ → `workflow_anima_incontext_character.json` を読み込み → 参照は**全身1枚＋顔アップ1枚**を推奨、プロンプトにも外見タグを併記すると最も安定します。`strength` は 1.0 中立、効きが弱ければ 1.2〜1.5。
+
+**ライセンス**: ベースの Anima は CircleStone Labs 非商用ライセンス。本LoRAは派生物として**非商用**での配布です。商用利用・再配布前に最新 LICENSE を確認してください。

anima-incontext-character.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:77eeb2c4263551f4760cc7af46196c6811ff623b7706f97a8f97c31ce5f0fe56
+size 554343064

comfyui-anima-incontext/README.md

@@ -0,0 +1,123 @@
+# comfyui-anima-incontext
+
+Anima (circlestone-labs, Cosmos-Predict2 2B DiT) 向けの
+**参照画像条件付け**カスタムノード集。2 つの独立したストリームを持つ:
+
+- **キャラストリーム (in-context)** — 参照画像のVAE latentをDiTの
+  時間軸（T軸）に「クリーンフレーム」として連結し、shared
+  self-attentionでキャラの見た目を参照させる。CLIP埋め込み型
+  IP-Adapterと違い、参照はモデル自身のVAE latentのまま自己注意に
+  入るため、髪飾り・服の柄・瞳などの細部が原理的に落ちない
+  （OminiControl / IC-LoRA / UNO 系のアプローチ）。
+- **絵柄ストリーム (decoupled cross-attn)** — SigLIP パッチトークンを
+  各ブロックのテキスト cross-attn に decoupled attention で注入する
+  統計的転写（AnimeAdapter 系）。細部をコピーしないことが目的なので、
+  あえて埋め込み注入型。**要学習済みアダプタ**。
+
+2 つは別モジュール（self-attn / cross-attn）をパッチするので併用可能。
+`char` と `style` の強度は独立に制御できる。
+
+## なぜT軸連結か
+
+ComfyUI本体の実装（`comfy/ldm/cosmos/predict2.py`, `comfy/ldm/anima/model.py`）
+を読んだ結果:
+
+- AnimaのDiTはvideoアーキテクチャで、latentは `(B, C, T, H, W)`、
+  自己注意は `(t h w)` を平坦化した列に **3D RoPE** 付きで計算される。
+  Animaのconfigは `max_frames=128`, `patch_temporal=1` なので、
+  T=2（生成1 + 参照1）はRoPE的に完全に正当。参照トークンは時間座標が
+  ずれるため、生成フレームと空間位置が衝突しない。
+- `timesteps` は `(B, T)` のフレーム毎形式を受け付ける
+  （`ndim==1` のときだけ unsqueeze）。よって **参照フレームだけ
+  timestep=0（クリーン画像）としてAdaLN変調** できる。
+- `forward` は `WrappersMP.DIFFUSION_MODEL` のWrapperExecutor経由
+  なので、ModelPatcherのwrapper登録だけで非侵襲にフックできる。
+- 各Blockの `self_attn.attn_op` は属性（`torch_attention_op`）なので、
+  `add_object_patch` で差し替えて参照トークンへの
+  attention bias（log(strength)）による強度制御ができる。
+
+## ノード
+
+### Anima Reference Encode (in-context)
+IMAGE (+ 任意で MASK) + VAE → LATENT。
+マスクを与えるとキャラを白背景に合成してからエンコードする
+（背景バイアス除去。アニメ被写体では効果が確認されている定石）。
+`target_width` / `target_height` を生成解像度に合わせると、
+アスペクト保持の白パディングでリサイズしてからエンコードする
+（サンプリング時のlatent空間リサンプルを回避できるので推奨）。
+複数枚バッチ入力可 — 各画像が独立した参照フレームになる。
+
+### Anima Reference Latent Batch
+解像度の異なる参照LATENT同士を1つの複数フレーム参照に結合する
+（2つ目を1つ目のサイズにfit）。チェーン可能。
+
+### Anima In-Context Reference Apply
+MODEL + 参照LATENT → MODEL。
+
+- `strength` — 参照トークンへのattention bias。1.0=中立、0=無効
+- `start_percent` / `end_percent` — 参照を有効にするステップ範囲
+- `cond_only`（既定 ON）— CFGのuncond側では参照キーをマスクする。
+  学習契約（uncond=参照なし分布）と一致するので推奨
+- `fit_mode` — 参照latentが生成解像度と違う場合のfit方法
+  （`pad`=アスペクト保持+エッジ複製パディング（既定）/ `stretch` / `crop`）
+- `ref_timestep` — 参照フレームのtimestep（既定0=クリーン。
+  noise augmentation学習をした場合のみ変更）
+
+### Anima Style Adapter Loader / Anima Style Encode (SigLIP) / Anima Style Apply
+絵柄ストリーム。`models/anima_style_adapters/` に学習済みアダプタを置く。
+SigLIP系の CLIP_VISION モデルでエンコードし、`style_weight` で強度制御。
+`cond_only`（既定 ON）。未学習アダプタは gate=0 で完全no-op。
+
+## ワークフロー例
+
+```
+LoadImage ─┐
+           ├→ AnimaRefEncode ─┐
+VAELoader ─┘                  │
+                              ▼
+UNETLoader → LoraLoader → AnimaInContextApply → (AnimaStyleApply) → KSampler → ...
+             (in-context LoRA)      ▲
+                                    │ (絵柄も使う場合)
+CLIPVisionLoader → AnimaStyleEncode ┘ + AnimaStyleAdapterLoader
+```
+
+## 重要: 学習との契約 (training contract)
+
+Anima本体は単フレームT2Iとして学習されているため、**このノード単体
+（zero-shot）での参照効果は弱い/不安定**。専用のin-context LoRAを
+学習して初めて本来の精度が出る。学習コード
+（リポジトリの `training/anima_incontext_train_network.py`）は
+以下の推論時仕様をバイト単位��再現する:
+
+1. 参照latentは生成フレームの **後ろ** にT軸連結（生成frames→参照frames）
+2. 参照フレームのtimestepは **0**（生成フレームはサンプラーのt）
+3. 参照latentは `latent_format` 正規化済み（`process_latent_in` 相当、
+   Wan21のper-channel mean/std）
+4. 損失は生成フレームのみに適用（参照フレームの出力は破棄）
+5. テキスト条件（LLMAdapter経由）は変更なし
+6. 学習ペア: 同一キャラ・**異なる**出典の2枚（参照≠ターゲット）。
+   同一画像ペアはコピー機化するため禁止
+7. CFG dropout: 参照を確率~10%でドロップ（フレーム連結自体を外す）
+   → 推論側 `cond_only=True` のuncondがこの分布に対応
+
+## 実機検証結果（2026-07-04, RTX PRO 6000 / anima-base-v1.0）
+
+- **strength=0 ⇔ 通常生成: bit単位で完全一致**（strength≤0 は連結自体を
+  スキップする実装。連結+全マスクでも数学的には同値だが、bf16 では
+  attention kernel差がステップ毎に複利で増幅する — fp32 では1ステップ差
+  mean 0.05/255 と確認済み）
+- 全バリアント完走: strength=1.0（cond_only 両方）/ 解像度違い参照
+  (512x768→1024x1024, fit=pad) / 複数参照 (RefLatentBatch) / sigma窓
+- **zero-shot（LoRA なし, strength=1.0）の挙動**: 参照キャラを
+  ポーズ・衣装込みで**ほぼ完全にコピー**し、背景が崩壊する。
+  video プライアが参照を「隣接フレーム」として扱うため。
+  経路が機能している証拠だが、実用には in-context LoRA が必須
+  （参照≠ターゲットのペア学習がこのコピー機挙動を
+  「同一キャラ・別ポーズ/シーン」に矯正する）。
+  strength を下げても中間にはならず画質が劣化するだけ
+
+## 既知の制約
+
+- 参照フレームのK/Vは全ステップ不変だがキャッシュしていない
+  （2Bモデルなので実害は小さい。最適化はTODO）
+- `tests/` にモックComfyUIでの契約テストあり

comfyui-anima-incontext/__init__.py

@@ -0,0 +1,14 @@
+from .nodes import NODE_CLASS_MAPPINGS, NODE_DISPLAY_NAME_MAPPINGS
+
+try:
+    from .style_nodes import (
+        NODE_CLASS_MAPPINGS as STYLE_CLASS_MAPPINGS,
+        NODE_DISPLAY_NAME_MAPPINGS as STYLE_DISPLAY_NAME_MAPPINGS,
+    )
+
+    NODE_CLASS_MAPPINGS = {**NODE_CLASS_MAPPINGS, **STYLE_CLASS_MAPPINGS}
+    NODE_DISPLAY_NAME_MAPPINGS = {**NODE_DISPLAY_NAME_MAPPINGS, **STYLE_DISPLAY_NAME_MAPPINGS}
+except ImportError:  # style stream needs full ComfyUI (folder_paths)
+    pass
+
+__all__ = ["NODE_CLASS_MAPPINGS", "NODE_DISPLAY_NAME_MAPPINGS"]

comfyui-anima-incontext/incontext.py

@@ -0,0 +1,340 @@
+"""
+Anima In-Context Reference — core logic.
+
+Strategy
+--------
+Anima's DiT (Cosmos-Predict2 MiniTrainDIT) is a *video* architecture:
+latents flow through the blocks as (B, T, H, W, D) and self-attention is
+computed over the flattened (t h w) sequence with 3D RoPE
+(max_frames=128, patch_temporal=1).
+
+We exploit this: the reference image latent is concatenated as an extra
+*frame* along the T axis. This gives us, for free:
+
+  * a distinct temporal RoPE coordinate for reference tokens
+    (no spatial position collision with the generated frame),
+  * per-frame timestep conditioning — MiniTrainDIT accepts
+    timesteps of shape (B, T), so the reference frame can be
+    conditioned at t=0 (clean image) while the generated frame
+    follows the sampler's sigma. This matches the
+    OminiControl-style "clean condition token" recipe.
+
+The generated frame's self-attention can then attend to reference
+tokens (shared attention / in-context conditioning). Reference frames
+are sliced off the output before returning to the sampler.
+
+Strength control is implemented by patching each block's
+`self_attn.attn_op` (a plain attribute, cleanly replaceable via
+ModelPatcher.add_object_patch) with a version that adds a per-sample
+additive bias on reference-token key columns:
+
+  * log(strength) amplifies/attenuates reference attention,
+  * cond_only masks reference keys for the uncond half of the CFG
+    batch (equivalent to not concatenating the reference at all for
+    the uncond forward — this matches the training contract, where
+    the reference is dropped ~10% of the time to form the ref-free
+    distribution).
+
+NOTE: the base model was finetuned as a T2I model (single frame), so
+zero-shot behaviour without a trained in-context LoRA is expected to be
+weak. This module defines the exact inference-time contract that the
+LoRA training code must replicate:
+  - reference frames appended after generated frames on the T axis
+  - reference frames receive timestep 0
+  - reference latents are latent_format-normalized (process_latent_in)
+  - text conditioning unchanged
+"""
+
+import math
+
+import torch
+import torch.nn.functional as F
+
+import comfy.patcher_extension
+from comfy.patcher_extension import WrappersMP
+
+WRAPPER_KEY = "anima_incontext_ref"
+
+NEG_BIAS = -1e9  # finite mask value; softmax subtracts the row max so this is NaN-safe
+
+
+class RefState:
+    """Mutable state shared between the diffusion-model wrapper and the
+    patched attention ops. The wrapper fills in per-forward token counts
+    and the per-sample reference bias (they depend on resolution and on
+    the CFG batch layout), the attention ops read them."""
+
+    def __init__(self):
+        self.active = False
+        self.total_tokens = -1
+        self.gen_tokens = -1
+        # per-sample additive bias on reference key columns, shape (B,).
+        # None means "all zero" (neutral -> attn ops fall back).
+        self.bias_B = None
+        # lazily-built full bias tensor (B, 1, 1, S), cached across the
+        # 28 blocks of one forward pass
+        self._bias_cache = None
+
+    def bias_for(self, device, dtype):
+        if self._bias_cache is None or self._bias_cache.device != device or self._bias_cache.dtype != dtype:
+            b = torch.zeros((self.bias_B.shape[0], 1, 1, self.total_tokens), device=device, dtype=dtype)
+            b[:, 0, 0, self.gen_tokens:] = self.bias_B.to(device=device, dtype=dtype).unsqueeze(1)
+            self._bias_cache = b
+        return self._bias_cache
+
+
+def _tokens_per_frame(h, w, patch_spatial):
+    # pad_to_patch_size pads H and W up to a multiple of patch_spatial
+    hp = math.ceil(h / patch_spatial)
+    wp = math.ceil(w / patch_spatial)
+    return hp * wp
+
+
+def _fit_latent(r, H, W, mode):
+    """Fit reference latent frames (N, C, h, w) to the generation
+    latent size (H, W).
+
+    stretch: plain bilinear resize (aspect distortion)
+    pad:     aspect-preserving resize + edge-replicate center pad.
+             Replicate keeps a white-background reference white at the
+             borders instead of introducing a mean-gray frame.
+    crop:    aspect-filling resize + center crop
+    """
+    h, w = r.shape[-2:]
+    if (h, w) == (H, W):
+        return r
+    if mode == "stretch":
+        return F.interpolate(r, size=(H, W), mode="bilinear", align_corners=False)
+    if mode == "pad":
+        scale = min(H / h, W / w)
+        nh = max(1, min(H, round(h * scale)))
+        nw = max(1, min(W, round(w * scale)))
+        r = F.interpolate(r, size=(nh, nw), mode="bilinear", align_corners=False)
+        pt = (H - nh) // 2
+        pl = (W - nw) // 2
+        return F.pad(r, (pl, W - nw - pl, pt, H - nh - pt), mode="replicate")
+    if mode == "crop":
+        scale = max(H / h, W / w)
+        nh = max(H, round(h * scale))
+        nw = max(W, round(w * scale))
+        r = F.interpolate(r, size=(nh, nw), mode="bilinear", align_corners=False)
+        ot = (nh - H) // 2
+        ol = (nw - W) // 2
+        return r[:, :, ot:ot + H, ol:ol + W]
+    raise ValueError(f"unknown fit mode: {mode}")
+
+
+def make_ref_attn_op(state, fallback_op):
+    """Replacement for Attention.attn_op on self-attention modules.
+
+    Adds the per-sample reference bias to attention logits for
+    reference-token key columns. Falls back to the original op whenever
+    the reference is not active, the bias is neutral, or the sequence
+    length does not match the full (gen + ref) self-attention sequence
+    (which excludes cross-attention and the LLMAdapter, whose K length
+    differs).
+    """
+
+    def ref_attn_op(q_B_S_H_D, k_B_S_H_D, v_B_S_H_D, transformer_options={}):
+        if (
+            not state.active
+            or state.bias_B is None
+            or k_B_S_H_D.shape[1] != state.total_tokens
+            or q_B_S_H_D.shape[1] != state.total_tokens
+        ):
+            return fallback_op(q_B_S_H_D, k_B_S_H_D, v_B_S_H_D, transformer_options=transformer_options)
+
+        # (B, S, H, D) -> (B, H, S, D)
+        q = q_B_S_H_D.transpose(1, 2)
+        k = k_B_S_H_D.transpose(1, 2)
+        v = v_B_S_H_D.transpose(1, 2)
+
+        bias = state.bias_for(q.device, q.dtype)
+
+        out = F.scaled_dot_product_attention(q, k, v, attn_mask=bias)
+        # (B, H, S, D) -> (B, S, H*D)
+        out = out.transpose(1, 2).reshape(q_B_S_H_D.shape[0], q_B_S_H_D.shape[1], -1)
+        return out
+
+    return ref_attn_op
+
+
+def _per_sample_bias(B, strength, cond_only, cond_or_uncond, device):
+    """Build the per-sample reference-key bias, shape (B,).
+
+    cond samples get log(strength) (0 at strength=1); uncond samples get
+    the same unless cond_only, in which case their reference keys are
+    masked out entirely. strength <= 0 masks the reference everywhere.
+
+    Returns None when every entry is zero (neutral -> no attn patch).
+    """
+    if strength <= 0.0:
+        base = NEG_BIAS
+    else:
+        base = math.log(strength)
+
+    bias = torch.full((B,), base, device=device, dtype=torch.float32)
+
+    if cond_only and cond_or_uncond is not None and len(cond_or_uncond) > 0 and B % len(cond_or_uncond) == 0:
+        # calc_cond_batch concatenates equal-sized chunks along B, one
+        # per entry of cond_or_uncond (0 = cond, 1 = uncond).
+        chunk = B // len(cond_or_uncond)
+        for i, kind in enumerate(cond_or_uncond):
+            if kind == 1:
+                bias[i * chunk:(i + 1) * chunk] = NEG_BIAS
+
+    if torch.count_nonzero(bias) == 0:
+        return None
+    return bias
+
+
+def make_diffusion_wrapper(opts):
+    """DIFFUSION_MODEL wrapper around MiniTrainDIT._forward.
+
+    opts is a dict with:
+      ref_latent:   (N, C, 1, H, W) latent tensor, already
+                    latent_format-normalized (process_latent_in)
+      state:        RefState instance shared with the attn ops
+      strength:     attention bias multiplier for reference tokens
+      cond_only:    mask reference keys for the uncond CFG half
+      fit_mode:     stretch | pad | crop (reference latent resize)
+      sigma_start:  apply when current sigma <= sigma_start
+      sigma_end:    ... and sigma >= sigma_end
+      patch_spatial: DiT spatial patch size (2 for Anima)
+      ref_timestep: timestep value for reference frames (default 0.0)
+    """
+
+    def wrapper(executor, x, timesteps, context, fps=None, padding_mask=None, **kwargs):
+        state = opts["state"]
+        ref = opts["ref_latent"]
+        to = kwargs.get("transformer_options", {})
+
+        # strength <= 0 fully masks the reference for every sample, which
+        # is mathematically identical to not attaching it — skip the
+        # concat so the output is bit-exact with the reference-free
+        # forward (and faster). Verified on-device: with the concat, the
+        # masked-attention kernel差 compounds over sampling steps.
+        if opts["strength"] <= 0.0:
+            return executor(x, timesteps, context, fps, padding_mask, **kwargs)
+
+        # ---- sigma window gating ----
+        sigmas = to.get("sigmas", None)
+        if sigmas is not None:
+            s = float(sigmas.max())
+            if s > opts["sigma_start"] or s < opts["sigma_end"]:
+                return executor(x, timesteps, context, fps, padding_mask, **kwargs)
+
+        squeeze_t = False
+        if x.ndim == 4:  # (B, C, H, W) -> (B, C, 1, H, W)
+            x = x.unsqueeze(2)
+            squeeze_t = True
+
+        B, C, T, H, W = x.shape
+        n_ref = ref.shape[0]
+
+        # ---- prepare reference frames ----
+        r = ref.to(device=x.device, dtype=x.dtype)  # (N, C, 1, H', W')
+        r = r.squeeze(2)  # (N, C, H', W')
+        r = _fit_latent(r, H, W, opts.get("fit_mode", "pad"))
+        # (N, C, H, W) -> (1, C, N, H, W) -> (B, C, N, H, W)
+        r = r.permute(1, 0, 2, 3).unsqueeze(0).expand(B, -1, -1, -1, -1)
+
+        x_cat = torch.cat([x, r], dim=2)  # (B, C, T + N, H, W)
+
+        # ---- per-frame timesteps: generated frames keep the sampler's t,
+        #      reference frames get ref_timestep (0 = clean) ----
+        t = timesteps
+        if t.ndim == 1:
+            t = t.unsqueeze(1)  # (B, 1)
+        t = t.expand(B, T)
+        t_ref = torch.full((B, n_ref), opts.get("ref_timestep", 0.0), device=t.device, dtype=t.dtype)
+        t_cat = torch.cat([t, t_ref], dim=1)  # (B, T + N)
+
+        # ---- arm the attention-op state ----
+        tpf = _tokens_per_frame(H, W, opts["patch_spatial"])
+        state.gen_tokens = T * tpf
+        state.total_tokens = (T + n_ref) * tpf
+        state.bias_B = _per_sample_bias(
+            B, opts["strength"], opts.get("cond_only", False), to.get("cond_or_uncond", None), x.device
+        )
+        state._bias_cache = None
+        state.active = True
+        try:
+            out = executor(x_cat, t_cat, context, fps, padding_mask, **kwargs)
+        finally:
+            state.active = False
+            state.bias_B = None
+            state._bias_cache = None
+
+        out = out[:, :, :T]  # drop reference frames
+        if squeeze_t:
+            out = out.squeeze(2)
+        return out
+
+    return wrapper
+
+
+def apply_incontext_ref(
+    model_patcher,
+    ref_latent,
+    strength,
+    start_percent,
+    end_percent,
+    cond_only=True,
+    fit_mode="pad",
+    ref_timestep=0.0,
+):
+    """Clone the ModelPatcher and install the in-context reference patches.
+
+    ref_latent: raw LATENT samples tensor from a VAE encode,
+                (N, C, H, W) or (N, C, 1, H, W).
+    """
+    m = model_patcher.clone()
+
+    lat = ref_latent
+    if lat.ndim == 4:
+        lat = lat.unsqueeze(2)  # (N, C, 1, H, W)
+    # Normalize into the model's latent space (Wan21 per-channel
+    # mean/std). The sampler does this for the generated latent via
+    # process_latent_in; we must match it for reference frames.
+    lat = m.model.process_latent_in(lat.clone())
+
+    ms = m.get_model_object("model_sampling")
+    sigma_start = ms.percent_to_sigma(start_percent)
+    sigma_end = ms.percent_to_sigma(end_percent)
+
+    dm = m.get_model_object("diffusion_model")
+    patch_spatial = getattr(dm, "patch_spatial", 2)
+
+    state = RefState()
+    opts = {
+        "ref_latent": lat,
+        "state": state,
+        "strength": strength,
+        "cond_only": cond_only,
+        "fit_mode": fit_mode,
+        "sigma_start": sigma_start,
+        "sigma_end": sigma_end,
+        "patch_spatial": patch_spatial,
+        "ref_timestep": ref_timestep,
+    }
+
+    wrapper = make_diffusion_wrapper(opts)
+    if hasattr(m, "add_wrapper_with_key"):
+        m.add_wrapper_with_key(WrappersMP.DIFFUSION_MODEL, WRAPPER_KEY, wrapper)
+    else:
+        comfy.patcher_extension.add_wrapper_with_key(
+            WrappersMP.DIFFUSION_MODEL, WRAPPER_KEY, wrapper, m.model_options, is_model_options=True
+        )
+
+    # Patch every block's self-attention op for strength control.
+    # TODO: reference-side K/V is constant across steps and could be
+    # cached; skipped for now (2B model, minor win).
+    for i, block in enumerate(dm.blocks):
+        orig_op = block.self_attn.attn_op
+        m.add_object_patch(
+            "diffusion_model.blocks.{}.self_attn.attn_op".format(i),
+            make_ref_attn_op(state, orig_op),
+        )
+
+    return m

comfyui-anima-incontext/nodes.py

@@ -0,0 +1,179 @@
+"""ComfyUI nodes for Anima in-context character reference."""
+
+import torch
+import torch.nn.functional as F
+
+from .incontext import apply_incontext_ref, _fit_latent
+
+
+def _fit_pixels_white_pad(pixels, target_h, target_w):
+    """Aspect-preserving resize of (B, H, W, C) pixels to the target
+    size, centered on a white canvas. White matches the background that
+    AnimaRefEncode composites masked subjects onto."""
+    b, h, w, c = pixels.shape
+    if (h, w) == (target_h, target_w):
+        return pixels
+    scale = min(target_h / h, target_w / w)
+    nh = max(1, min(target_h, round(h * scale)))
+    nw = max(1, min(target_w, round(w * scale)))
+    resized = F.interpolate(
+        pixels.permute(0, 3, 1, 2), size=(nh, nw), mode="bilinear", align_corners=False
+    ).permute(0, 2, 3, 1)
+    canvas = torch.ones((b, target_h, target_w, c), device=pixels.device, dtype=pixels.dtype)
+    top = (target_h - nh) // 2
+    left = (target_w - nw) // 2
+    canvas[:, top:top + nh, left:left + nw] = resized
+    return canvas
+
+
+class AnimaRefEncode:
+    """Prepare a reference image for in-context conditioning.
+
+    Optionally composites the subject onto a white background using a
+    mask (recommended: character segmentation mask). Background removal
+    measurably improves appearance fidelity for anime subjects.
+
+    target_width / target_height (0 = keep): aspect-preserving resize
+    onto a white canvas before encoding. Set these to the generation
+    resolution to avoid any latent-space resampling at sampling time.
+
+    Multiple reference images can be batched; each becomes its own
+    reference frame.
+    """
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "vae": ("VAE",),
+                "image": ("IMAGE",),
+            },
+            "optional": {
+                "mask": ("MASK",),
+                "target_width": ("INT", {"default": 0, "min": 0, "max": 8192, "step": 8}),
+                "target_height": ("INT", {"default": 0, "min": 0, "max": 8192, "step": 8}),
+            },
+        }
+
+    RETURN_TYPES = ("LATENT",)
+    FUNCTION = "encode"
+    CATEGORY = "anima/incontext"
+
+    def encode(self, vae, image, mask=None, target_width=0, target_height=0):
+        pixels = image
+        if mask is not None:
+            m = mask
+            if m.ndim == 2:
+                m = m.unsqueeze(0)
+            m = m.unsqueeze(-1)  # (B, H, W, 1)
+            if m.shape[1:3] != pixels.shape[1:3]:
+                m = F.interpolate(
+                    m.permute(0, 3, 1, 2), size=pixels.shape[1:3], mode="bilinear", align_corners=False
+                ).permute(0, 2, 3, 1)
+            pixels = pixels * m + (1.0 - m)  # subject on white
+
+        if target_width > 0 and target_height > 0:
+            pixels = _fit_pixels_white_pad(pixels, target_height, target_width)
+
+        latent = vae.encode(pixels[:, :, :, :3])
+        return ({"samples": latent},)
+
+
+class AnimaRefLatentBatch:
+    """Batch two reference latents into one multi-frame reference.
+
+    Reference latents of different resolutions are combined by fitting
+    the second latent to the first one's size (aspect-preserving pad by
+    default). Chain several of these to stack many references."""
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "ref_latent_1": ("LATENT",),
+                "ref_latent_2": ("LATENT",),
+                "fit_mode": (["pad", "stretch", "crop"], {"default": "pad"}),
+            },
+        }
+
+    RETURN_TYPES = ("LATENT",)
+    FUNCTION = "batch"
+    CATEGORY = "anima/incontext"
+
+    def batch(self, ref_latent_1, ref_latent_2, fit_mode):
+        s1 = ref_latent_1["samples"]
+        s2 = ref_latent_2["samples"]
+        if s1.ndim == 5:
+            s1 = s1.squeeze(2)
+        if s2.ndim == 5:
+            s2 = s2.squeeze(2)
+        if s2.shape[-2:] != s1.shape[-2:]:
+            s2 = _fit_latent(s2, s1.shape[-2], s1.shape[-1], fit_mode)
+        return ({"samples": torch.cat([s1, s2], dim=0)},)
+
+
+class AnimaInContextApply:
+    """Attach in-context reference frames to an Anima model.
+
+    The reference latent is concatenated on the DiT's temporal axis as
+    clean (t=0) frames; the generated frame attends to it via shared
+    self-attention. Combine with an in-context reference LoRA trained
+    with the same contract for full effect.
+
+    strength: attention bias toward reference tokens.
+              1.0 = neutral, >1 stronger, 0 = off.
+    start_percent / end_percent: sampling step window where the
+              reference is attached.
+    cond_only: mask the reference for the uncond half of CFG. Matches
+              the training contract (reference dropped for the
+              unconditional distribution) — recommended on.
+    fit_mode: how a reference latent that does not match the generation
+              resolution is fitted (pad = aspect-preserving, default).
+    ref_timestep: timestep for reference frames. 0 = clean image
+              (the training contract). Small values (~0.05–0.1 of the
+              schedule) act as noise augmentation if a future LoRA is
+              trained that way.
+    """
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "model": ("MODEL",),
+                "ref_latent": ("LATENT",),
+                "strength": ("FLOAT", {"default": 1.0, "min": 0.0, "max": 10.0, "step": 0.05}),
+                "start_percent": ("FLOAT", {"default": 0.0, "min": 0.0, "max": 1.0, "step": 0.001}),
+                "end_percent": ("FLOAT", {"default": 1.0, "min": 0.0, "max": 1.0, "step": 0.001}),
+            },
+            "optional": {
+                "cond_only": ("BOOLEAN", {"default": True}),
+                "fit_mode": (["pad", "stretch", "crop"], {"default": "pad"}),
+                "ref_timestep": ("FLOAT", {"default": 0.0, "min": 0.0, "max": 1000.0, "step": 0.5}),
+            },
+        }
+
+    RETURN_TYPES = ("MODEL",)
+    FUNCTION = "apply"
+    CATEGORY = "anima/incontext"
+
+    def apply(self, model, ref_latent, strength, start_percent, end_percent,
+              cond_only=True, fit_mode="pad", ref_timestep=0.0):
+        samples = ref_latent["samples"]
+        m = apply_incontext_ref(
+            model, samples, strength, start_percent, end_percent,
+            cond_only=cond_only, fit_mode=fit_mode, ref_timestep=ref_timestep,
+        )
+        return (m,)
+
+
+NODE_CLASS_MAPPINGS = {
+    "AnimaRefEncode": AnimaRefEncode,
+    "AnimaRefLatentBatch": AnimaRefLatentBatch,
+    "AnimaInContextApply": AnimaInContextApply,
+}
+
+NODE_DISPLAY_NAME_MAPPINGS = {
+    "AnimaRefEncode": "Anima Reference Encode (in-context)",
+    "AnimaRefLatentBatch": "Anima Reference Latent Batch",
+    "AnimaInContextApply": "Anima In-Context Reference Apply",
+}

comfyui-anima-incontext/style_adapter.py

@@ -0,0 +1,186 @@
+"""Anima style stream — decoupled cross-attention adapter (stage 2).
+
+Design (spec §6): the character stream is in-context latent
+concatenation (detail copying is the point); the *style* stream must
+NOT copy details, so it uses statistical transfer via embedding
+injection instead:
+
+  encoder   SigLIP 2 patch tokens from the last K hidden layers,
+            aggregated with learnable softmax layer weights and
+            projected to style tokens (AnimeAdapter-style).
+  injection each DiT block's text cross-attention output gains a
+            decoupled attention term:
+                out = out_text + style_weight * gamma_i * Attn(Q, K_s, V_s)
+            where Q is the block's frozen query, K_s/V_s are new
+            trainable projections of the style tokens, and gamma_i is a
+            per-block learnable gate initialized to 0 — the adapter is
+            an exact no-op at init, so training starts from the base
+            model's behaviour.
+
+This module is pure torch (no ComfyUI imports) so the training code can
+import the same definition. ComfyUI integration lives in style_nodes.py.
+"""
+
+import torch
+import torch.nn.functional as F
+from torch import nn
+
+# Anima 2B DiT geometry
+ANIMA_X_DIM = 2048
+ANIMA_N_HEADS = 16
+ANIMA_N_BLOCKS = 28
+
+
+class RMSNorm(nn.Module):
+    def __init__(self, dim, eps=1e-6):
+        super().__init__()
+        self.eps = eps
+        self.weight = nn.Parameter(torch.ones(dim))
+
+    def forward(self, x):
+        norm = x.float() * torch.rsqrt(x.float().pow(2).mean(-1, keepdim=True) + self.eps)
+        return (norm * self.weight.float()).type_as(x)
+
+
+class StyleTokenAggregator(nn.Module):
+    """Aggregate SigLIP patch tokens from the last K hidden layers into
+    style tokens: softmax-weighted layer mix -> LayerNorm -> projection."""
+
+    def __init__(self, siglip_dim=1152, style_dim=1024, n_layers=6):
+        super().__init__()
+        self.n_layers = n_layers
+        self.layer_weights = nn.Parameter(torch.zeros(n_layers))
+        self.norm = nn.LayerNorm(siglip_dim)
+        self.proj = nn.Linear(siglip_dim, style_dim)
+
+    def forward(self, hidden_states_B_K_N_D):
+        """hidden_states: (B, K, N, D) — the last K hidden layers of the
+        vision tower (K == n_layers), N patch tokens of dim D."""
+        assert hidden_states_B_K_N_D.shape[1] == self.n_layers, (
+            f"expected {self.n_layers} layers, got {hidden_states_B_K_N_D.shape[1]}"
+        )
+        w = torch.softmax(self.layer_weights, dim=0)
+        mixed = (hidden_states_B_K_N_D * w[None, :, None, None].to(hidden_states_B_K_N_D)).sum(dim=1)
+        return self.proj(self.norm(mixed))  # (B, N, style_dim)
+
+
+class StyleBlockKV(nn.Module):
+    """Per-DiT-block decoupled K/V projections + gate."""
+
+    def __init__(self, x_dim=ANIMA_X_DIM, style_dim=1024, n_heads=ANIMA_N_HEADS):
+        super().__init__()
+        self.n_heads = n_heads
+        self.head_dim = x_dim // n_heads
+        self.k_proj = nn.Linear(style_dim, x_dim, bias=False)
+        self.v_proj = nn.Linear(style_dim, x_dim, bias=False)
+        # match the base attention's K normalization (RMSNorm per head)
+        self.k_norm = RMSNorm(self.head_dim)
+        # gate init 0 -> adapter is a no-op until trained
+        self.gate = nn.Parameter(torch.zeros(1))
+
+    def kv(self, style_tokens_B_N_D):
+        B, N, _ = style_tokens_B_N_D.shape
+        k = self.k_proj(style_tokens_B_N_D).view(B, N, self.n_heads, self.head_dim)
+        v = self.v_proj(style_tokens_B_N_D).view(B, N, self.n_heads, self.head_dim)
+        k = self.k_norm(k)
+        return k, v
+
+
+class AnimaStyleAdapter(nn.Module):
+    """Aggregator + one StyleBlockKV per DiT block."""
+
+    def __init__(self, siglip_dim=1152, style_dim=1024, n_layers=6,
+                 x_dim=ANIMA_X_DIM, n_heads=ANIMA_N_HEADS, n_blocks=ANIMA_N_BLOCKS):
+        super().__init__()
+        self.config = {
+            "siglip_dim": siglip_dim, "style_dim": style_dim, "n_layers": n_layers,
+            "x_dim": x_dim, "n_heads": n_heads, "n_blocks": n_blocks,
+        }
+        self.aggregator = StyleTokenAggregator(siglip_dim, style_dim, n_layers)
+        self.blocks = nn.ModuleList(
+            [StyleBlockKV(x_dim, style_dim, n_heads) for _ in range(n_blocks)]
+        )
+
+    @classmethod
+    def from_state_dict(cls, sd):
+        """Instantiate with dimensions inferred from a checkpoint."""
+        siglip_dim = sd["aggregator.proj.weight"].shape[1]
+        style_dim = sd["aggregator.proj.weight"].shape[0]
+        n_layers = sd["aggregator.layer_weights"].shape[0]
+        x_dim = sd["blocks.0.k_proj.weight"].shape[0]
+        n_blocks = 0
+        while f"blocks.{n_blocks}.k_proj.weight" in sd:
+            n_blocks += 1
+        head_dim = sd["blocks.0.k_norm.weight"].shape[0]
+        adapter = cls(siglip_dim, style_dim, n_layers, x_dim, x_dim // head_dim, n_blocks)
+        adapter.load_state_dict(sd)
+        return adapter
+
+
+class StyleState:
+    """Runtime state shared by all patched cross-attention wrappers.
+    Armed by the style diffusion wrapper before each forward."""
+
+    def __init__(self):
+        self.active = False
+        # style K/V per block, computed once per forward: list of (k, v)
+        self.kv_per_block = None
+        # per-sample multiplier (0 masks a sample, e.g. the uncond chunk)
+        self.sample_scale_B = None
+        self.weight = 1.0
+
+
+def style_attention(q_B_S_H_D, k_B_N_H_D, v_B_N_H_D):
+    """Decoupled attention with the block's frozen query. Returns
+    (B, S, H*D) to match the text branch pre-output_proj layout."""
+    q = q_B_S_H_D.transpose(1, 2)
+    k = k_B_N_H_D.transpose(1, 2)
+    v = v_B_N_H_D.transpose(1, 2)
+    out = F.scaled_dot_product_attention(q, k, v)
+    return out.transpose(1, 2).reshape(q_B_S_H_D.shape[0], q_B_S_H_D.shape[1], -1)
+
+
+class StyleCrossAttention(nn.Module):
+    """Replacement for a DiT block's cross_attn module.
+
+    Reimplements the original attention using the original (frozen)
+    projections, then adds the decoupled style term *before*
+    output_proj — the IP-Adapter formulation:
+
+        out = output_proj( Attn(Q, K_text, V_text)
+                           + weight * gamma * Attn(Q, K_style, V_style) )
+
+    When the state is inactive it computes exactly the original
+    attention (the reimplementation is numerically identical: same
+    modules, same attn_op).
+    """
+
+    def __init__(self, orig_attn, block_kv, state, block_index):
+        super().__init__()
+        self.orig = orig_attn
+        self.block_kv = block_kv
+        self.state = state
+        self.block_index = block_index
+
+    def forward(self, x, context=None, rope_emb=None, transformer_options={}):
+        state = self.state
+        if not state.active or state.kv_per_block is None:
+            return self.orig(x, context, rope_emb=rope_emb, transformer_options=transformer_options)
+
+        q, k, v = self.orig.compute_qkv(x, context, rope_emb=rope_emb)
+        text_out = self.orig.attn_op(q, k, v, transformer_options=transformer_options)
+
+        ks, vs = state.kv_per_block[self.block_index]
+        B = q.shape[0]
+        if ks.shape[0] != B:  # single style batch broadcast over CFG batch
+            ks = ks.expand(B, -1, -1, -1)
+            vs = vs.expand(B, -1, -1, -1)
+        style_out = style_attention(q, ks.to(q.dtype), vs.to(q.dtype))
+
+        gate = self.block_kv.gate.to(q.dtype)
+        scale = state.weight * gate
+        if state.sample_scale_B is not None:
+            scale = scale * state.sample_scale_B.to(q.dtype).view(B, 1, 1)
+        text_out = text_out + scale * style_out
+
+        return self.orig.output_dropout(self.orig.output_proj(text_out))

comfyui-anima-incontext/style_nodes.py

@@ -0,0 +1,194 @@
+"""ComfyUI nodes for the Anima style stream (decoupled cross-attention).
+
+Requires a trained AnimaStyleAdapter checkpoint (see style_adapter.py
+and the project docs); with an untrained adapter the gates are zero and
+the nodes are an exact no-op.
+
+The style stream composes freely with the in-context character stream:
+AnimaInContextApply patches self-attention (T-axis reference frames),
+AnimaStyleApply patches cross-attention — chain both Apply nodes and
+control char/style strength independently.
+"""
+
+import os
+
+import torch
+
+import comfy.utils
+import folder_paths
+from comfy.patcher_extension import WrappersMP
+
+from .style_adapter import AnimaStyleAdapter, StyleState
+
+STYLE_WRAPPER_KEY = "anima_style_ref"
+
+_ADAPTER_DIR = "anima_style_adapters"
+if _ADAPTER_DIR not in folder_paths.folder_names_and_paths:
+    folder_paths.add_model_folder_path(
+        _ADAPTER_DIR, os.path.join(folder_paths.models_dir, _ADAPTER_DIR)
+    )
+
+
+class AnimaStyleAdapterLoader:
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "adapter_name": (folder_paths.get_filename_list(_ADAPTER_DIR),),
+            },
+        }
+
+    RETURN_TYPES = ("ANIMA_STYLE_ADAPTER",)
+    FUNCTION = "load"
+    CATEGORY = "anima/style"
+
+    def load(self, adapter_name):
+        path = folder_paths.get_full_path_or_raise(_ADAPTER_DIR, adapter_name)
+        sd = comfy.utils.load_torch_file(path, safe_load=True)
+        adapter = AnimaStyleAdapter.from_state_dict(sd)
+        adapter.eval()
+        return (adapter,)
+
+
+class AnimaStyleEncode:
+    """Encode style reference image(s) with a SigLIP CLIP_VISION model,
+    keeping the hidden-state stack the adapter aggregates over.
+
+    Multiple images are encoded independently and their patch tokens are
+    concatenated at apply time (attention pools over all of them)."""
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "clip_vision": ("CLIP_VISION",),
+                "image": ("IMAGE",),
+            },
+        }
+
+    RETURN_TYPES = ("ANIMA_STYLE_EMBEDS",)
+    FUNCTION = "encode"
+    CATEGORY = "anima/style"
+
+    def encode(self, clip_vision, image):
+        out = clip_vision.encode_image(image)
+        hs = out["all_hidden_states"]  # (B, L, N, D)
+        if hs is None:
+            raise RuntimeError(
+                "this CLIP_VISION model does not expose all hidden states; "
+                "use a SigLIP vision model"
+            )
+        return ({"hidden_states": hs},)
+
+
+class AnimaStyleApply:
+    """Attach the style stream to an Anima model.
+
+    style_weight: global multiplier on the (learned, per-block) gates.
+    cond_only:    apply style only to the cond half of the CFG batch.
+    start/end_percent: sampling window, same semantics as the
+    in-context Apply node.
+    """
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "model": ("MODEL",),
+                "style_adapter": ("ANIMA_STYLE_ADAPTER",),
+                "style_embeds": ("ANIMA_STYLE_EMBEDS",),
+                "style_weight": ("FLOAT", {"default": 1.0, "min": -2.0, "max": 5.0, "step": 0.05}),
+                "start_percent": ("FLOAT", {"default": 0.0, "min": 0.0, "max": 1.0, "step": 0.001}),
+                "end_percent": ("FLOAT", {"default": 1.0, "min": 0.0, "max": 1.0, "step": 0.001}),
+            },
+            "optional": {
+                "cond_only": ("BOOLEAN", {"default": True}),
+            },
+        }
+
+    RETURN_TYPES = ("MODEL",)
+    FUNCTION = "apply"
+    CATEGORY = "anima/style"
+
+    def apply(self, model, style_adapter, style_embeds, style_weight,
+              start_percent, end_percent, cond_only=True):
+        m = model.clone()
+
+        ms = m.get_model_object("model_sampling")
+        sigma_start = ms.percent_to_sigma(start_percent)
+        sigma_end = ms.percent_to_sigma(end_percent)
+
+        dm = m.get_model_object("diffusion_model")
+        n_layers = style_adapter.config["n_layers"]
+        hidden_states = style_embeds["hidden_states"][:, -n_layers:]  # (B, K, N, D)
+
+        state = StyleState()
+        # per-(device, dtype) cache of the per-block K/V — the style
+        # tokens are constant across sampling steps
+        kv_cache = {}
+
+        def compute_kv(device, dtype):
+            key = (device, dtype)
+            if key not in kv_cache:
+                adapter = style_adapter.to(device)
+                hs = hidden_states.to(device=device, dtype=next(adapter.parameters()).dtype)
+                with torch.no_grad():
+                    tokens = adapter.aggregator(hs)  # (B, N, style_dim)
+                    # multiple style images -> one long token sequence
+                    tokens = tokens.reshape(1, -1, tokens.shape[-1])
+                    kv_cache[key] = [
+                        tuple(t.to(dtype) for t in blk.kv(tokens)) for blk in adapter.blocks
+                    ]
+            return kv_cache[key]
+
+        def wrapper(executor, x, timesteps, context, fps=None, padding_mask=None, **kwargs):
+            to = kwargs.get("transformer_options", {})
+            sigmas = to.get("sigmas", None)
+            if sigmas is not None:
+                s = float(sigmas.max())
+                if s > sigma_start or s < sigma_end:
+                    return executor(x, timesteps, context, fps, padding_mask, **kwargs)
+
+            state.kv_per_block = compute_kv(x.device, x.dtype)
+            state.weight = style_weight
+
+            state.sample_scale_B = None
+            cou = to.get("cond_or_uncond", None)
+            if cond_only and cou and x.shape[0] % len(cou) == 0:
+                chunk = x.shape[0] // len(cou)
+                scale = torch.ones(x.shape[0], device=x.device)
+                for i, kind in enumerate(cou):
+                    if kind == 1:
+                        scale[i * chunk:(i + 1) * chunk] = 0.0
+                state.sample_scale_B = scale
+
+            state.active = True
+            try:
+                return executor(x, timesteps, context, fps, padding_mask, **kwargs)
+            finally:
+                state.active = False
+
+        m.add_wrapper_with_key(WrappersMP.DIFFUSION_MODEL, STYLE_WRAPPER_KEY, wrapper)
+
+        from .style_adapter import StyleCrossAttention
+
+        for i, block in enumerate(dm.blocks):
+            m.add_object_patch(
+                "diffusion_model.blocks.{}.cross_attn".format(i),
+                StyleCrossAttention(block.cross_attn, style_adapter.blocks[i], state, i),
+            )
+
+        return (m,)
+
+
+NODE_CLASS_MAPPINGS = {
+    "AnimaStyleAdapterLoader": AnimaStyleAdapterLoader,
+    "AnimaStyleEncode": AnimaStyleEncode,
+    "AnimaStyleApply": AnimaStyleApply,
+}
+
+NODE_DISPLAY_NAME_MAPPINGS = {
+    "AnimaStyleAdapterLoader": "Anima Style Adapter Loader",
+    "AnimaStyleEncode": "Anima Style Encode (SigLIP)",
+    "AnimaStyleApply": "Anima Style Apply",
+}

workflow_anima_incontext_character.json

@@ -0,0 +1,809 @@
+{
+  "last_node_id": 25,
+  "last_link_id": 18,
+  "nodes": [
+    {
+      "id": 1,
+      "type": "UNETLoader",
+      "pos": [
+        40,
+        40
+      ],
+      "size": [
+        320,
+        100
+      ],
+      "flags": {},
+      "order": 1,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "MODEL",
+          "type": "MODEL",
+          "links": [
+            1
+          ],
+          "slot_index": 0
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "UNETLoader"
+      },
+      "widgets_values": [
+        "anima-base-v1.0.safetensors",
+        "default"
+      ]
+    },
+    {
+      "id": 2,
+      "type": "CLIPLoader",
+      "pos": [
+        40,
+        190
+      ],
+      "size": [
+        320,
+        110
+      ],
+      "flags": {},
+      "order": 2,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "CLIP",
+          "type": "CLIP",
+          "links": [
+            11,
+            12
+          ],
+          "slot_index": 0
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "CLIPLoader"
+      },
+      "widgets_values": [
+        "qwen_3_06b_base.safetensors",
+        "stable_diffusion",
+        "default"
+      ]
+    },
+    {
+      "id": 3,
+      "type": "VAELoader",
+      "pos": [
+        40,
+        340
+      ],
+      "size": [
+        320,
+        80
+      ],
+      "flags": {},
+      "order": 3,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "VAE",
+          "type": "VAE",
+          "links": [
+            3,
+            4,
+            5
+          ],
+          "slot_index": 0
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "VAELoader"
+      },
+      "widgets_values": [
+        "qwen_image_vae.safetensors"
+      ]
+    },
+    {
+      "id": 4,
+      "type": "LoraLoaderModelOnly",
+      "pos": [
+        400,
+        40
+      ],
+      "size": [
+        330,
+        110
+      ],
+      "flags": {},
+      "order": 4,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "model",
+          "type": "MODEL",
+          "link": 1
+        }
+      ],
+      "outputs": [
+        {
+          "name": "MODEL",
+          "type": "MODEL",
+          "links": [
+            2
+          ],
+          "slot_index": 0
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "LoraLoaderModelOnly"
+      },
+      "widgets_values": [
+        "anima-incontext-character.safetensors",
+        1.0
+      ],
+      "title": "Character LoRA"
+    },
+    {
+      "id": 10,
+      "type": "LoadImage",
+      "pos": [
+        40,
+        470
+      ],
+      "size": [
+        320,
+        300
+      ],
+      "flags": {},
+      "order": 10,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "IMAGE",
+          "type": "IMAGE",
+          "links": [
+            6
+          ],
+          "slot_index": 0
+        },
+        {
+          "name": "MASK",
+          "type": "MASK",
+          "links": [],
+          "slot_index": 0
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "LoadImage"
+      },
+      "widgets_values": [
+        "ref_fullbody.png",
+        "image"
+      ],
+      "title": "Reference 1 (full body)"
+    },
+    {
+      "id": 11,
+      "type": "LoadImage",
+      "pos": [
+        40,
+        800
+      ],
+      "size": [
+        320,
+        300
+      ],
+      "flags": {},
+      "order": 11,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "IMAGE",
+          "type": "IMAGE",
+          "links": [
+            7
+          ],
+          "slot_index": 0
+        },
+        {
+          "name": "MASK",
+          "type": "MASK",
+          "links": [],
+          "slot_index": 0
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "LoadImage"
+      },
+      "widgets_values": [
+        "ref_face.png",
+        "image"
+      ],
+      "title": "Reference 2 (face, optional)"
+    },
+    {
+      "id": 12,
+      "type": "AnimaRefEncode",
+      "pos": [
+        400,
+        470
+      ],
+      "size": [
+        300,
+        130
+      ],
+      "flags": {},
+      "order": 12,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "vae",
+          "type": "VAE",
+          "link": 3
+        },
+        {
+          "name": "image",
+          "type": "IMAGE",
+          "link": 6
+        },
+        {
+          "name": "mask",
+          "type": "MASK",
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "name": "LATENT",
+          "type": "LATENT",
+          "links": [
+            8
+          ],
+          "slot_index": 0
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "AnimaRefEncode"
+      },
+      "widgets_values": [
+        1024,
+        1024
+      ]
+    },
+    {
+      "id": 13,
+      "type": "AnimaRefEncode",
+      "pos": [
+        400,
+        800
+      ],
+      "size": [
+        300,
+        130
+      ],
+      "flags": {},
+      "order": 13,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "vae",
+          "type": "VAE",
+          "link": 4
+        },
+        {
+          "name": "image",
+          "type": "IMAGE",
+          "link": 7
+        },
+        {
+          "name": "mask",
+          "type": "MASK",
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "name": "LATENT",
+          "type": "LATENT",
+          "links": [
+            9
+          ],
+          "slot_index": 0
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "AnimaRefEncode"
+      },
+      "widgets_values": [
+        1024,
+        1024
+      ]
+    },
+    {
+      "id": 14,
+      "type": "AnimaRefLatentBatch",
+      "pos": [
+        740,
+        470
+      ],
+      "size": [
+        300,
+        110
+      ],
+      "flags": {},
+      "order": 14,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "ref_latent_1",
+          "type": "LATENT",
+          "link": 8
+        },
+        {
+          "name": "ref_latent_2",
+          "type": "LATENT",
+          "link": 9
+        }
+      ],
+      "outputs": [
+        {
+          "name": "LATENT",
+          "type": "LATENT",
+          "links": [
+            10
+          ],
+          "slot_index": 0
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "AnimaRefLatentBatch"
+      },
+      "widgets_values": [
+        "pad"
+      ]
+    },
+    {
+      "id": 15,
+      "type": "AnimaInContextApply",
+      "pos": [
+        760,
+        40
+      ],
+      "size": [
+        330,
+        220
+      ],
+      "flags": {},
+      "order": 15,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "model",
+          "type": "MODEL",
+          "link": 2
+        },
+        {
+          "name": "ref_latent",
+          "type": "LATENT",
+          "link": 10
+        }
+      ],
+      "outputs": [
+        {
+          "name": "MODEL",
+          "type": "MODEL",
+          "links": [
+            13
+          ],
+          "slot_index": 0
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "AnimaInContextApply"
+      },
+      "widgets_values": [
+        1.0,
+        0.0,
+        1.0,
+        true,
+        "pad",
+        0.0
+      ],
+      "title": "Anima In-Context Apply"
+    },
+    {
+      "id": 20,
+      "type": "CLIPTextEncode",
+      "pos": [
+        400,
+        640
+      ],
+      "size": [
+        330,
+        140
+      ],
+      "flags": {},
+      "order": 20,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "clip",
+          "type": "CLIP",
+          "link": 11
+        }
+      ],
+      "outputs": [
+        {
+          "name": "CONDITIONING",
+          "type": "CONDITIONING",
+          "links": [
+            14
+          ],
+          "slot_index": 0
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "CLIPTextEncode"
+      },
+      "widgets_values": [
+        "1girl, silver hair, twin tails, blue eyes, black sailor uniform with red ribbon, standing in a park, cherry blossoms, detailed illustration"
+      ],
+      "title": "Positive (describe pose/scene + appearance)"
+    },
+    {
+      "id": 21,
+      "type": "CLIPTextEncode",
+      "pos": [
+        400,
+        300
+      ],
+      "size": [
+        330,
+        100
+      ],
+      "flags": {},
+      "order": 21,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "clip",
+          "type": "CLIP",
+          "link": 12
+        }
+      ],
+      "outputs": [
+        {
+          "name": "CONDITIONING",
+          "type": "CONDITIONING",
+          "links": [
+            15
+          ],
+          "slot_index": 0
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "CLIPTextEncode"
+      },
+      "widgets_values": [
+        "worst quality, low quality, blurry, jpeg artifacts"
+      ],
+      "title": "Negative"
+    },
+    {
+      "id": 22,
+      "type": "EmptyLatentImage",
+      "pos": [
+        760,
+        300
+      ],
+      "size": [
+        300,
+        110
+      ],
+      "flags": {},
+      "order": 22,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "LATENT",
+          "type": "LATENT",
+          "links": [
+            16
+          ],
+          "slot_index": 0
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "EmptyLatentImage"
+      },
+      "widgets_values": [
+        1024,
+        1024,
+        1
+      ]
+    },
+    {
+      "id": 23,
+      "type": "KSampler",
+      "pos": [
+        1140,
+        40
+      ],
+      "size": [
+        300,
+        270
+      ],
+      "flags": {},
+      "order": 23,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "model",
+          "type": "MODEL",
+          "link": 13
+        },
+        {
+          "name": "positive",
+          "type": "CONDITIONING",
+          "link": 14
+        },
+        {
+          "name": "negative",
+          "type": "CONDITIONING",
+          "link": 15
+        },
+        {
+          "name": "latent_image",
+          "type": "LATENT",
+          "link": 16
+        }
+      ],
+      "outputs": [
+        {
+          "name": "LATENT",
+          "type": "LATENT",
+          "links": [
+            17
+          ],
+          "slot_index": 0
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "KSampler"
+      },
+      "widgets_values": [
+        42,
+        "fixed",
+        30,
+        4.0,
+        "er_sde",
+        "simple",
+        1.0
+      ]
+    },
+    {
+      "id": 24,
+      "type": "VAEDecode",
+      "pos": [
+        1480,
+        40
+      ],
+      "size": [
+        260,
+        80
+      ],
+      "flags": {},
+      "order": 24,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "samples",
+          "type": "LATENT",
+          "link": 17
+        },
+        {
+          "name": "vae",
+          "type": "VAE",
+          "link": 5
+        }
+      ],
+      "outputs": [
+        {
+          "name": "IMAGE",
+          "type": "IMAGE",
+          "links": [
+            18
+          ],
+          "slot_index": 0
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "VAEDecode"
+      },
+      "widgets_values": []
+    },
+    {
+      "id": 25,
+      "type": "SaveImage",
+      "pos": [
+        1760,
+        40
+      ],
+      "size": [
+        320,
+        300
+      ],
+      "flags": {},
+      "order": 25,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "images",
+          "type": "IMAGE",
+          "link": 18
+        }
+      ],
+      "outputs": [],
+      "properties": {
+        "Node name for S&R": "SaveImage"
+      },
+      "widgets_values": [
+        "Anima_InContext"
+      ]
+    }
+  ],
+  "links": [
+    [
+      1,
+      1,
+      0,
+      4,
+      0,
+      "MODEL"
+    ],
+    [
+      2,
+      4,
+      0,
+      15,
+      0,
+      "MODEL"
+    ],
+    [
+      3,
+      3,
+      0,
+      12,
+      0,
+      "VAE"
+    ],
+    [
+      4,
+      3,
+      0,
+      13,
+      0,
+      "VAE"
+    ],
+    [
+      5,
+      3,
+      0,
+      24,
+      1,
+      "VAE"
+    ],
+    [
+      6,
+      10,
+      0,
+      12,
+      1,
+      "IMAGE"
+    ],
+    [
+      7,
+      11,
+      0,
+      13,
+      1,
+      "IMAGE"
+    ],
+    [
+      8,
+      12,
+      0,
+      14,
+      0,
+      "LATENT"
+    ],
+    [
+      9,
+      13,
+      0,
+      14,
+      1,
+      "LATENT"
+    ],
+    [
+      10,
+      14,
+      0,
+      15,
+      1,
+      "LATENT"
+    ],
+    [
+      11,
+      2,
+      0,
+      20,
+      0,
+      "CLIP"
+    ],
+    [
+      12,
+      2,
+      0,
+      21,
+      0,
+      "CLIP"
+    ],
+    [
+      13,
+      15,
+      0,
+      23,
+      0,
+      "MODEL"
+    ],
+    [
+      14,
+      20,
+      0,
+      23,
+      1,
+      "CONDITIONING"
+    ],
+    [
+      15,
+      21,
+      0,
+      23,
+      2,
+      "CONDITIONING"
+    ],
+    [
+      16,
+      22,
+      0,
+      23,
+      3,
+      "LATENT"
+    ],
+    [
+      17,
+      23,
+      0,
+      24,
+      0,
+      "LATENT"
+    ],
+    [
+      18,
+      24,
+      0,
+      25,
+      0,
+      "IMAGE"
+    ]
+  ],
+  "groups": [],
+  "config": {},
+  "extra": {},
+  "version": 0.4
+}