📘 UmiAI Wildcard Processor

A "Logic Engine" for ComfyUI Prompts.

UmiAI transforms static prompts into dynamic, context-aware workflows. It introduces Persistent Variables, Conditional Logic, Native LoRA Loading, and External Data Fetching directly into your prompt text box.

✨ Key Features

• 🔋 Native LoRA Loading: Type <lora:filename:1.0> directly in the text. The node patches the model internally—no external LoRA Loader nodes required.

• 🧠 Integrated Local LLM: Turn simple tag lists into rich natural language descriptions using local models (Qwen/Llama3). Runs entirely on CPU to save VRAM.

• 📊 CSV Data Injection: Load spreadsheet data (.csv) and map columns to variables (e.g., $name, $outfit) for complex character handling.

• 🛠️ Z-Image Support: Automatically detects and fixes Z-Image format LoRAs (QKV Fusion) on the fly.

• 🧠 Persistent Variables: Define a choice once ($hair={Red|Blue}) and reuse it ($hair) anywhere to ensure consistency.

• 🔀 Conditional Logic: [if keyword : True Text | False Text] logic gates. Perfect for ensuring outfits match genres.

• 🌍 Global Presets: Automatically load variables from wildcards/globals.yaml into every prompt.

• 🎨 Danbooru Integration: Type char:name to automatically fetch visual tags from Danbooru.

• 📏 Resolution Control: Set @@width=1024@@ inside your prompt to control image size contextually.

---

🛠️ Installation

Method 1: Manual Install (Recommended)

1. Navigate to your ComfyUI/custom_nodes/ folder.
2. Clone this repository:

   git clone https://github.com/Tinuva88/Comfy-UmiAI
   

3. ⚠️ IMPORTANT: Rename the folder to ComfyUI-UmiAI if it isn't already.
4. Install dependencies:

   pip install -r requirements.txt
   

5. Restart ComfyUI completely.

Method 2: ComfyUI Manager

• Install via Git URL: Copy the URL of this repository and paste it into ComfyUI Manager.

---

Updating

Node giving you a strange issue after updating? Right click the node and press "Fix Node (recreate)" and it'll repopulate with correct default values

🔌 Wiring Guide (The "Passthrough" Method)

The UmiAI node acts as the "Central Brain". You must pass your Model and CLIP through it so it can apply LoRAs automatically.

1. The Main Chain

• Connect Checkpoint Loader (Model & CLIP) ➞ UmiAI Node (Inputs).
• Connect UmiAI Node (Model & CLIP Outputs) ➞ KSampler or Text Encode.

2. Prompts & Resolution

• Text Output ➞ CLIP Text Encode (Positive)
• Negative Output ➞ CLIP Text Encode (Negative)
• Width/Height ➞ Empty Latent Image

⚠️ Setting up Resolution Control: To let the node control image size (e.g., @@width=1024@@), right-click your Empty Latent Image node and select Convert width/height to input, then connect the wires.

<img width="883" height="194" alt="wvQeZXNUmL" src="https://github.com/user-attachments/assets/f6018158-297b-45a1-9593-2ce751e8cf38" />

---

⚡ Syntax Cheat Sheet

| Feature | Syntax | Example 1 | Example 2 | | :--- | :--- | :--- | :--- | | Load LoRA | <lora:name:str> | <lora:pixel_art:0.8> | <lora:tifa_lockhart:1> | | Random Choice | {a\|b\|c} | {Red\|Blue\|Green} | {Girl\|Boy\|Nonbinary} | | Random Weights | {#%a\|#%b\|#%c} | {25%Red\|15%Blue\|60%Green} | {75%Girl\|115%Boy\|35%Nonbinary} | | Choose X of Y | {x-y$$a\|b\|c} | {0-2$$Hat\|Scarf\|Belt} | {1-3$$Swimming\|Flying\|Jumping} | | Variables | $var={opts} | $hair={Red\|Blue\|Green} | $char1={Tifa\|Aerith\|Zelda} | | Use Variable | $var | A woman with $color1 hair. | $char1 hugging $char2 | | Danbooru | char:name | char:zelda | char:tifa_lockhart | | Sequential | {~a\|b\|c} | {~Front\|Side\|Back} | {~Seed1\|Seed2\|Seed3} | | Logic Gate | [if Key : A \| B] | [if Cyberpunk : Techwear \| Armor] | | | Set Size | @@w=X, h=Y@@ | @@width=1024, height=1536@@ | | | Comments | // or # | // This is a comment | |

---

🧠 Integrated LLM (Prompt Naturalizer)

Turn "tag soup" (e.g., 1girl, solo, beach) into lush, descriptive prose using a local Large Language Model.

Setup & Settings Select Model: In the llm_model widget, select "Download Recommended". You can choose between:

Qwen2.5-1.5B (Fast): Low RAM usage, good for quick descriptions.

Dolphin-Llama3.1-8B (Smart): Uncensored, follows complex instructions perfectly.

Enable: Set naturalize_prompt to Yes.

Hardware: The LLM runs entirely on your CPU/RAM to preserve your GPU VRAM for image generation.

Customization Widgets Temperature: Controls creativity. 0.7 is standard. Lower it for more literal descriptions, raise it for hallucinations.

Max Tokens: Limits the length of the description (600 is usually a paragraph).

Custom System Prompt: Override the default behavior.

Default: "Creative Writer" persona (Flowery, descriptive, no lists).

Example Override: "You are a horror writer. Describe the tags in a terrifying way."

Note: The LLM automatically ignores/protects lora:... tags, so they won't be hallucinated away.

---

🔋 LoRA & Z-Image System

You no longer need to chain multiple LoRA Loader nodes. UmiAI handles it internally.

Basic Usage

Type <lora: to trigger the autocomplete menu.

<lora:my_style_v1:0.8>

Z-Image Auto-Detection

If you are using Z-Image LoRAs (which normally require special loaders due to QKV mismatch), UmiAI handles this automatically.

1. Load the file using the standard syntax: <lora:z-image-anime:1.0>
2. The node detects the key format and applies the QKV Fusion Patch instantly.

Dynamic LoRAs

You can use wildcards or logic to switch LoRAs per generation:

// Randomly pick a style LoRA
{ <lora:anime_style:1.0> | <lora:realistic_v2:0.8> }

Note that LORAs may use either their internal filename or their actual filename.

---

📂 Creating Wildcards

UmiAI reads files from the wildcards/ folder.

1. Simple Text Lists (.txt)

Create wildcards/colors.txt:

Red
Blue
Green

Usage: Type __ to select __colors__.

2. Advanced Tag Lists (.yaml)

Create wildcards/styles.yaml (You can hide LoRAs here!):

2.5 Dimensional Temptation - Noa Base:
  Description:
    - Noa from the series '2.5 Dimensional Temptation' without a designated outfit
  Prompts:
    - '<lora:ILL CHAR 2.5 Dimensional Temptation GIRLPACK - Amano Lilisa, Tachibana Mikari, Noa, Kisaki Aria, 753, Makino:1> nonoa_def, Noa, blue eyes, black hair, short hair, sailor collar'
    - '<lora:ILL CHAR 2.5 Dimensional Temptation GIRLPACK - Amano Lilisa, Tachibana Mikari, Noa, Kisaki Aria, 753, Makino:1> nonoa_cos, Noa, blue eyes, blue hair, short hair, hair ornament'
  Tags:
    - 2.5 Dimensional Temptation
    - Noa
    - Human
    - White Skin
    - Lora
    - Girl Base
  Prefix:
    - 
  Suffix:
    - 
A-Rank Party - Silk Outfit:
  Description:
    - Silk from the series 'A-Rank Party' wearing her canonical outfits
  Prompts:
    - '<lora:ILL CHAR A-Rank Party - Silk:0.5> dark-skinned female, white hair, orange eyes, pointy ears, earrings, {swept bangs, french braid, long hair|high ponytail, swept bangs, long hair}, {SilkArcherOne, purple scarf, black jacket, long sleeves, black leotard, chest guard, red ribbon, leotard under clothes, underbust, highleg, white gloves, fur-trimmed shorts, white shorts, brown belt|SilkArcherTwo, beret, purple headwear, white ascot, cropped vest, white vest, sleeveless, elbow gloves, white gloves, vambraces, black leotard, leotard under clothes, highleg, fur-trimmed shorts, white shorts, red belt|SilkCasual, strapless, off-shoulder dress, frilled dress, purple dress, cleavage, long sleeves, light purple sleeves, pleated skirt, miniskirt, light pink skirt}'
  Tags:
    - A-Rank Party
    - Silk
    - Demihuman
    - Dark Skin
    - Colored Skin
    - Lora
    - Girl Outfit
  Prefix:
    - 
  Suffix:
    - 

Usage: Type < to select <[Demihuman]> and randomly choose a prompt between any of the YAML entries using <[Demihuman]> as a tag.

---

🚀 Example Workflows:

// 1. COMPOUND VARIABLES
// We pack multiple "Keys" into one choice.
// Key 1: The visible text ("Fire").
// Key 2: The Logic Trigger for the LoRA ("**L1**").
// Key 3: The Logic Trigger for the Description ("**D1**").
$theme = {Fire **L1** **D1**|Ice **L2** **D2**}

$mood = {Happy|Angry}
@@width=768, height=768@@

// 2. MAIN PROMPT
(Masterpiece), <char:hatsune miku>, 
// $theme prints "Fire **L1** **D1**". 
// The "**...**" parts will be invisible in the final output.
$theme.clean theme. 

// 3. LOGIC (Using Unique Keys)
// Check L1 (Fire Lora) - It won't see D1, so no collision.
[if L1: <lora:fire_element_v1:0.8>]
[if L2: <lora:ice_concept:1.0>]

// Check D1 (Fire Desc) - It won't see L1.
[if D1: [if Happy: warm lighting | burning flames]]
[if D2: frozen crystal textures], 

highlighted in __2$$colors__.

// 4. ESCAPING
Artist signature: __#artist__

// 5. NEGATIVE PROMPT
**worst quality, lowres**

Here's a prompt I like to use all the time:

$char1={__RandomGirls__}

$char2={__RandomGirls__}

$color1={__Colors__}

$color2={__Colors__}

$color3={__Colors__}

$color4={__Colors__}

A fullbody illustration of two girls standing together at a fashion show in the style of __ArtistNames__. $char1 is wearing __RandomOutfit__ with a primary color of $color1 and a secondary color of $color2. $char2 is wearing __RandomOutfit__ with a primary color of $color3 and a secondary color of $color4. {Both girls are __SharedPose__|The girls are holding hands and smiling while __MiscPose__}.

The background is __Background__.

---

💬 Community & Support

Join the Umi AI Discord server to share workflows and get help!

👉 Join our Discord Server