MD: Apply TPG (Token Perturbation)

You know the failure mode: mid-generation, the model locks onto a repeated pattern - the same texture, the same squiggle, the same brick wall tiling forever. Token Perturbation Guidance attacks this at the attention level by shuffling the conditioning tokens as they pass through the model, forcing the attention heads to reconsider rather than autopilot. MD_ApplyTPG is the wrapper that patches that behavior into your model.

The idea traces to the TPG research line - perturb the token order in the conditioning sequence so the model can't settle into a rigid, repetitive interpretation. The node inserts a perturbation step that deterministically (from a seed) shuffles token positions within a chosen subset of the network's blocks, blending between the original and shuffled representations. It works across architectures: the tooltip claims SD1.5, SDXL, and FLUX compatibility, and the pack's own ACE-Step audio workflows use it on DiT-based models too.

The inputs that matter

• model - the diffusion model to patch. You get a patched_model back, wired into your sampler as you would any model.
• enable_tpg - master toggle for A/B testing without rewiring.
• target_layers - where to patch. Down (Encoder) is the default and the paper's recommendation (best FID); Mid affects global composition; Up (Decoder) hits fine texture; All is strongest and the tooltip flags it as "may be destructive."
• perturbation_strength - 0.0 to 1.0, blend between original and shuffled tokens. The tooltip's advice is worth trusting: keep it at 1.0 and control intensity via sigma range instead.
• start_sigma / end_sigma - the noise window where TPG is active. Default 1000→0.1, meaning "on from the very start through most of the run." TPG matters most at high noise (structural formation), and the tooltip suggests stopping before 0.1–0.5 so you don't damage fine texture.
• protect_first_tokens - how many leading tokens are never shuffled. Default 1, protecting [CLS]-type special tokens so global conditioning stays intact.
• split_mode - how the node finds the unconditional batch. ComfyUI's default puts uncond first (leave Standard); if output looks corrupted or inverted, flip to Cond First.
• seed - permutation seed, for reproducibility.

Outputs: patched_model (into your sampler) and debug_info (STRING - set debug_mode to Basic for active layer/sigma info; Visual prints an ASCII map of shuffles and is, per the tooltip, "Spammy!").

Installing it

Part of MD Nodes (MDMAchine/ComfyUI_MD_Nodes). ComfyUI Manager → search MD_Nodes → Install, restart, or:

cd path/to/ComfyUI/custom_nodes
git clone https://github.com/MDMAchine/ComfyUI_MD_Nodes.git
cd ComfyUI_MD_Nodes
pip install -r requirements.txt

Restart ComfyUI. Python 3.10+, current ComfyUI, GPL v3.

Common issues

The community's general guidance on guidance applies: this is a tool for fixing a specific artifact, not a permanent fixture - if your output was already clean, TPG mostly costs you variance and a little control. If output comes out corrupted, first check split_mode (the inverted-batch heuristic is the #1 cause of "why is this garbage"). If you're not getting the anti-repetition effect, check that your start_sigma actually covers the high-noise phase of your run - on distilled/turbo models with few steps, the whole generation may live below your start value. And remember perturbation_strength is a blend, not a volume knob: 0.5 is "half-shuffled," which is often weirder than full shuffle, not gentler.