Extensions/ComfyUI-RandomPromptBuilder
ComfyUI Extension

ComfyUI-RandomPromptBuilder

A ComfyUI extension.

By btitkin·Created about a month ago·Updated about a month ago· 0
btitkin/ComfyUI-RandomPromptBuilder
Nodes—
On cloudLocal install
Stars0
Updatedabout a month ago
Readme

Random Prompt Builder for ComfyUI

Advanced AI-Powered Prompt Generation Custom Node for ComfyUI

Overview

Random Prompt Builder for ComfyUI is a professional-grade custom node that brings intelligent AI prompt generation directly into your ComfyUI workflows. This is an adapted version of the standalone Random Prompt Builder desktop application, redesigned to work seamlessly within ComfyUI's node-based interface.

Using local GGUF language models via llama-cpp-python, this node transforms simple descriptions into detailed, structured prompts optimized for various AI image generation models including Stable Diffusion, SDXL, Pony Diffusion, Flux, and more.

Key Advantages

  • Fully Local Operation: All AI processing happens on your machine using GGUF models
  • Model-Aware Formatting: Automatically formats prompts for your target model (tag-based or natural language)
  • Advanced Character Control: Detailed customization of physical attributes and characteristics
  • Structured Generation: Organizes prompts into semantic categories for consistent results
  • GPU Accelerated: Configurable GPU layer offloading for optimal performance
  • Style-Aware Output: Multiple style presets with automatic quality tag injection
  • Professional Controls: Fine-tune creativity, temperature, and other LLM parameters

Features

Core Functionality

  • Local LLM integration using GGUF models from your ComfyUI/models/LLM folder
  • GPU acceleration with configurable layer offloading
  • Multiple output formats:
    • Pony Diffusion (score tags)
    • SDXL / SD 1.5 (comma-separated tags)
    • Flux / SD3 (natural language)
    • Anime/Danbooru (booru tags)
    • Custom formats
  • Quality tags with automatic style-specific injection
  • BREAK separator support for SDXL/Pony workflows
  • Seed control for reproducible generation

Character Controls

Define your subject with precision:

  • Gender: male, female, non-binary, couple, or any
  • Age Range: 18s, 25s, 30s, 40s, 50s, 60s, 70+, or any
  • Body Type: slim, curvy, athletic, instagram model, fat, muscular, big muscular, or any
  • Ethnicity: caucasian, asian, african, hispanic, middle eastern, mixed, or any
  • Height: short, average, tall, or any
  • Physical Attributes: breast size, muscle definition (NSFW-aware)
  • Scene Type: solo, couple, threesome, or group
  • Character Overlays: furry, monster, sci-fi character traits
  • Detailed Attributes: hair style, hair color, eye color, facial hair, roleplay scenarios

Structured Prompt Organization

Organize your prompt into semantic components:

  1. Subject: Main character or object description
  2. Attributes: Physical characteristics, facial features, expressions
  3. Action: What the subject is doing
  4. Pose: Body position, stance, gestures
  5. Clothing: Outfits, accessories, wardrobe details
  6. Location: Scene setting, environment
  7. Background: Background elements, atmosphere, lighting

Style System

Style Presets:

  • Photographic
  • Cinematic
  • Anime
  • Digital Art
  • Comic Book
  • Fantasy
  • Cyberpunk
  • 3D Render
  • Oil Painting

Style Filters:

  • Main Style: Realistic, Anime, Semi-realistic, or any
  • Sub-Style (Realistic): Professional, Amateur, Flash, Film, or any
  • Sub-Style (Anime): Ghibli, Modern, Vintage, Shoujo, Shounen, or any

Content Controls:

  • NSFW Modes: Safe, NSFW, Hardcore
  • NSFW Levels: Fine-grained control (0-10)
  • Quality tag injection with style-specific enhancers

Advanced LLM Controls

  • Creativity: 0.0 (strict formatting) to 1.0 (highly creative)
  • Temperature: 0.1-2.0 (sampling randomness)
  • Top-P: Nucleus sampling threshold
  • Frequency Penalty: Reduce token repetition
  • Presence Penalty: Encourage topic diversity
  • Context Window: 512-32768 tokens
  • GPU Layers: Offload processing to GPU (0 = CPU only)

Enhancement System

  • Enhancement Rounds: 0-3 iterations of prompt refinement
  • Locked Phrases: Preserve specific text across enhancement iterations
  • Selective Enhancement: Toggle person, pose, and location enhancements
  • Mandatory Tags: Force-include specific tags in final output
  • Negative Prompts: Custom negative prompt support

Installation

Method 1: ComfyUI Manager (Recommended)

  1. Open ComfyUI Manager
  2. Search for "Random Prompt Builder" or "RandomPromptBuilder"
  3. Click Install
  4. Restart ComfyUI

Method 2: Manual Installation

Step 1: Clone the repository

Navigate to your ComfyUI custom nodes directory and clone this repository:

cd ComfyUI/custom_nodes/
git clone https://github.com/btitkin/ComfyUI-RandomPromptBuilder.git

Step 2: Install Python dependencies

cd ComfyUI-RandomPromptBuilder
pip install -r requirements.txt

Step 3: Install llama-cpp-python with GPU support

Choose the appropriate installation method for your hardware:

NVIDIA CUDA (Windows):

$env:CMAKE_ARGS="-DGGML_CUDA=on"
pip install llama-cpp-python --upgrade --force-reinstall --no-cache-dir

NVIDIA CUDA (Linux/Mac):

CMAKE_ARGS="-DGGML_CUDA=on" pip install llama-cpp-python --upgrade --force-reinstall --no-cache-dir

AMD ROCm:

CMAKE_ARGS="-DGGML_HIPBLAS=on" pip install llama-cpp-python --upgrade --force-reinstall --no-cache-dir

Apple Silicon (Metal):

CMAKE_ARGS="-DGGML_METAL=on" pip install llama-cpp-python --upgrade --force-reinstall --no-cache-dir

CPU Only:

pip install llama-cpp-python

Step 4: Download GGUF model

Download a GGUF model and place it in ComfyUI/models/LLM/ (create the directory if it doesn't exist)

Step 5: Restart ComfyUI

Recommended Models

Place GGUF model files in the ComfyUI/models/LLM/ directory.

Model Recommendations

| Model | Quantization | Size | Download Link | Notes | |-------|--------------|------|---------------|-------| | Qwen2.5-7B-Instruct | Q4_K_M | ~4.4GB | HuggingFace | Best balance of quality and speed | | Qwen2.5-7B-Instruct | Q5_K_M | ~5.4GB | HuggingFace | Higher quality | | Mistral-7B-Instruct-v0.3 | Q4_K_M | ~4.4GB | HuggingFace | Excellent creativity | | Llama-3.2-3B-Instruct | Q4_K_M | ~2.0GB | HuggingFace | Lightweight option |

Quantization Guide

  • Q4_K_M: Best speed/quality balance (recommended for most users)
  • Q5_K_M: Higher quality with moderate file size increase
  • Q6_K: Near-original quality, larger file size
  • Q8_0: Maximum quality, largest file size

Quick Start

Basic Workflow Setup

Step 1: Add the Node

Right-click in ComfyUI -> Add Node -> PromptBuilder -> Random Prompt Builder (GGUF)

Step 2: Connect Outputs

  • POSITIVE_PROMPT -> CLIPTextEncode (positive)
  • NEGATIVE_PROMPT -> CLIPTextEncode (negative)
  • Connect to your KSampler or other sampling nodes

Step 3: Configure Settings

  • Select your GGUF model from the dropdown
  • Choose target model format (SDXL, Pony, Flux, etc.)
  • Set style preset and NSFW mode

Step 4: Add Prompt Details (Optional)

  • Fill in character controls (gender, age, body type, etc.)
  • Add structured prompt categories (subject, action, clothing, etc.)
  • Add mandatory tags if needed

Step 5: Generate

Click "Queue Prompt" in ComfyUI to generate both positive and negative prompts.

Example Workflow Structure

[Random Prompt Builder (GGUF)]
    -> POSITIVE_PROMPT
[CLIP Text Encode (Prompt)]
    -> CONDITIONING
[KSampler] <- + other inputs
    -> LATENT
[VAE Decode]
    -> IMAGE
[Save Image]

Usage Examples

Example 1: Anime Character (Pony Model)

Settings:

  • Target Model: Pony (Score Tags)
  • Style Preset: Anime
  • NSFW Mode: Safe
  • Use Quality Tags: True

Character Controls:

  • Gender: female
  • Age: 18s
  • Body Type: slim

Structured Inputs:

  • Subject: magical girl
  • Attributes: long pink hair, bright eyes, cheerful expression
  • Clothing: frilly dress with ribbons
  • Location: cherry blossom garden

Generated Output:

score_9, score_8_up, score_7_up, masterpiece, best quality, highres, 18s, female, slim body type, magical girl, long pink hair, bright eyes, cheerful expression, frilly dress with ribbons, cherry blossom garden

Example 2: Photorealistic Portrait (SDXL)

Settings:

  • Target Model: SDXL / SD 1.5 (Tags)
  • Style Preset: Photographic
  • Main Style: Realistic
  • Sub Style (Realistic): Professional
  • Use BREAK: True
  • Use Quality Tags: True

Character Controls:

  • Gender: female
  • Age: 30s
  • Body Type: athletic
  • Ethnicity: asian

Structured Inputs:

  • Subject: warrior princess
  • Attributes: long flowing black hair, determined expression, battle scars
  • Action: looking at camera with confidence
  • Pose: dynamic stance, hand on sword hilt
  • Clothing: ornate silver armor with red accents, flowing cape
  • Location: ancient temple ruins
  • Background: mystical fog, moonlight filtering through pillars

Generated Output:

photorealistic, high detail, professional photography, best quality, 8k, BREAK 30s, asian, female, athletic body type, BREAK warrior princess, long flowing black hair, determined expression, battle scars, BREAK looking at camera with confidence, dynamic stance, hand on sword hilt, BREAK ornate silver armor with red accents, flowing cape, BREAK ancient temple ruins, BREAK mystical fog, moonlight filtering through pillars

Example 3: Natural Language (Flux)

Settings:

  • Target Model: Flux / SD3 (Natural)
  • Style Preset: Cinematic
  • Creativity: 0.8

Structured Inputs:

  • Subject: cyberpunk detective
  • Attributes: augmented eyes, weathered face
  • Action: investigating a holographic crime scene
  • Location: neon-lit alley in rain-soaked megacity

Generated Output:

A cinematic scene of a cyberpunk detective with augmented eyes and a weathered face, investigating a holographic crime scene in a neon-lit alley within a rain-soaked megacity. The lighting is dramatic with high contrast, creating a moody atmosphere with shallow depth of field.

Parameters Reference

Required Parameters

| Parameter | Type | Default | Range | Description | |-----------|------|---------|-------|-------------| | llm_model | Dropdown | - | - | GGUF model from models/LLM folder | | gpu_layers | INT | 20 | 0-200 | Number of layers to offload to GPU (0=CPU only) | | n_ctx | INT | 2048 | 512-32768 | Context window size | | seed | INT | 0 | 0-18446744073709551615 | Random seed for reproducibility | | control_after_generate | Dropdown | randomize | - | "fixed" or "randomize" seed after generation |

LLM Tuning Parameters

| Parameter | Type | Default | Range | Description | |-----------|------|---------|-------|-------------| | creativity | FLOAT | 0.8 | 0.0-1.0 | 0.0=strict formatting, 1.0=highly creative | | temperature | FLOAT | 0.7 | 0.1-2.0 | LLM sampling temperature | | top_p | FLOAT | 1.0 | 0.0-1.0 | Nucleus sampling threshold | | frequency_penalty | FLOAT | 0.0 | 0.0-2.0 | Penalize token repetition | | presence_penalty | FLOAT | 0.0 | 0.0-2.0 | Penalize topic repetition |

Output Format Parameters

| Parameter | Type | Default | Options | |-----------|------|---------|---------| | target_model | Dropdown | SDXL / SD 1.5 (Tags) | Pony (Score Tags), SDXL / SD 1.5 (Tags), Flux / SD3 (Natural), Wan (Natural), General (Tags), General (Natural) | | style_preset | Dropdown | Photographic | None, Photographic, Cinematic, Anime, Digital Art, Comic Book, Fantasy, Cyberpunk, 3D Render, Oil Painting | | use_quality_tags | BOOLEAN | True | - | | use_break | BOOLEAN | False | - |

Style Filter Parameters

| Parameter | Type | Default | Options | |-----------|------|---------|---------| | main_style | Dropdown | any | any, realistic, anime | | sub_style_realistic | Dropdown | ignore | ignore, any, film photography, webcam, spycam, cctv, smartphone, polaroid, analog, editorial, portrait studio, street photography, fashion editorial, professional, amateur, flash | | sub_style_anime | Dropdown | ignore | ignore, any, ghibli, naruto, bleach, 90s vhs anime, chibi, ecchi manga, dark fantasy anime, dragon ball, one piece, neon genesis evangelion, cyberpunk edgerunners, demon slayer, death note, attack on titan, pokemon |

NSFW Parameters

| Parameter | Type | Default | Range/Options | |-----------|------|---------|---------------| | nsfw_mode | Dropdown | Safe | safe, nsfw, hardcore | | nsfw_level | INT | 5 | 1-10 | | hardcore_level | INT | 5 | 1-10 |

Character Control Parameters

Most character parameters support "any" for random selection or "ignore" to exclude them from the prompt. scene_type uses a fixed scene-size selection.

| Parameter | Options | |-----------|---------| | scene_type | solo, couple, threesome, group | | gender | ignore, any, male, female, mixed, couple, futanari, trans female, trans male, femboy, nonbinary, furry, monster, sci-fi | | age | ignore, any, 18s, 25s, 30s, 40s, 50s, 60s, 70+ | | body_type | ignore, any, slim, curvy, athletic, instagram model, fat, muscular, big muscular | | ethnicity | ignore, any, caucasian, european, scandinavian, slavic, mediterranean, asian, japanese, chinese, korean, indian, african, hispanic, middle eastern, native american | | height | ignore, any, very short, short, average, tall | | breast_size | ignore, any, flat, small, medium, large, huge, gigantic | | hips_size | ignore, any, narrow, average, wide, extra wide | | butt_size | ignore, any, flat, small, average, large, bubble | | penis_size | ignore, any, small, average, large, huge, horse-hung | | muscle_definition | ignore, any, soft, toned, defined, ripped, bodybuilder | | hair_style | Free text | | hair_color | Free text | | eye_color | Free text | | facial_hair | ignore, any, clean-shaven, stubble, goatee, mustache, full beard | | character_style | Preset dropdown | | roleplay | Preset dropdown |

Character Overlay Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | overlay_furry | BOOLEAN | False | Apply furry character traits | | overlay_monster | BOOLEAN | False | Apply monster/creature traits | | overlay_scifi | BOOLEAN | False | Apply sci-fi/cybernetic traits |

Enhancement Parameters

| Parameter | Type | Default | Range | Description | |-----------|------|---------|-------|-------------| | enhance_round | INT | 0 | 0-10 | Number of enhancement iterations | | locked_phrases | STRING | "" | - | Phrases preserved across enhancement rounds | | enhance_person | BOOLEAN | True | - | Enhance character descriptions | | enhance_pose | BOOLEAN | True | - | Enhance pose descriptions | | enhance_location | BOOLEAN | True | - | Enhance location descriptions |

Structured Prompt Categories

All are multiline text inputs:

| Parameter | Description | |-----------|-------------| | subject | Main subject/character | | attributes | Physical characteristics, expressions, features | | action | What they're doing, activity | | pose | Stance, body position, gestures | | clothing | Outfit, accessories, wardrobe | | location | Environment, setting, place | | background | Background details, atmosphere, lighting |

Additional Controls

| Parameter | Type | Default | Range | Description | |-----------|------|---------|-------|-------------| | mandatory_tags | STRING | "" | - | Tags forced into output | | negative_prompt | STRING | "ugly, bad anatomy, blurry, low quality, worst quality" | - | Custom negative prompt output | | max_tokens | INT | 512 | 128-2048 | Maximum tokens for LLM generation | | aspect_ratio | Dropdown | none | - | Target image aspect ratio | | additional_params | STRING | "" | - | Additional instructions for the LLM |

Advanced Usage

GPU Layer Configuration

Adjust gpu_layers based on your GPU VRAM:

| VRAM | Recommended GPU Layers | Model Size | |------|------------------------|------------| | 24GB+ | 33 (full model) | Any Q4_K_M | | 12-16GB | 25-30 | Q4_K_M 7B | | 8-10GB | 15-20 | Q4_K_M 7B | | 6GB | 10-15 | Q4_K_M 3B | | 4GB | 0-10 (CPU recommended) | Q4_K_M 3B |

Enhancement Rounds

Use enhance_round to iteratively refine prompts:

  • 0: No enhancement (direct generation)
  • 1: Single refinement pass
  • 2: Two refinement passes (high quality)
  • 3: Three refinement passes (maximum quality, slower)

When using enhancement rounds, any text in locked_phrases will be preserved exactly across all iterations.

BREAK Formatting

When use_break is enabled, the output is structured with BREAK separators, useful for SDXL and Pony models:

quality tags, BREAK character attributes, BREAK action and pose, BREAK clothing, BREAK location, BREAK background

Batch Processing

Use ComfyUI's native batch processing:

  1. Set control_after_generate to "randomize"
  2. Use a batch size > 1 in your workflow
  3. Each batch item receives a unique seed and prompt variation

Troubleshooting

No models found in models/LLM

Solution: Place .gguf model files in the ComfyUI/models/LLM/ folder. Create the directory if it doesn't exist.

Out of Memory / CUDA Out of Memory

Solutions:

  • Reduce gpu_layers (try 15-20 for 8GB VRAM, 10-15 for 6GB)
  • Use a smaller quantization (Q4_K_M instead of Q5_K_M or Q6_K)
  • Use a smaller model size (3B instead of 7B)
  • Reduce n_ctx if you don't need long context

Slow Generation

Solutions:

  • Increase gpu_layers if you have VRAM available
  • Ensure llama-cpp-python was installed with GPU support
  • Use a more aggressive quantization (Q4_K_M)
  • Reduce n_ctx to 1024 or 512
  • Use a smaller model (3B parameters)

llama_cpp not available

Solution: Install llama-cpp-python:

pip install llama-cpp-python

For GPU support, see installation instructions above.

Prompt Output is Empty or Malformed

Solutions:

  • Increase temperature (try 0.8-1.0)
  • Increase creativity (try 0.7-0.9)
  • Ensure your model is an instruction-tuned variant (e.g., *-Instruct)
  • Try a different model
  • Increase max_tokens to 512 or 1024

Node Not Showing in ComfyUI

Solutions:

  • Ensure the folder is named correctly in custom_nodes/
  • Check ComfyUI console for Python errors
  • Verify requirements.txt dependencies are installed
  • Restart ComfyUI completely

Model Loading is Slow

This is normal on the first load. The model is loaded into memory and cached. Subsequent generations will be much faster.

Performance Optimization

First-Time Setup

Model loading takes 10-30 seconds on first use. This is normal and only happens once per session.

Recommended Settings

For Speed:

  • gpu_layers: 20
  • n_ctx: 1024
  • creativity: 0.7
  • max_tokens: 256

For Quality:

  • gpu_layers: max available
  • n_ctx: 2048
  • creativity: 0.8
  • enhance_round: 2
  • max_tokens: 512

Resource Usage

  • Context Window: Higher n_ctx allows longer prompts but uses more VRAM. 2048 is usually sufficient.
  • VRAM Usage: Approximately 4-6GB VRAM for Q4_K_M 7B model with 20-25 GPU layers
  • CPU Fallback: If gpu_layers = 0, generation uses CPU (significantly slower but works on any system)

Differences from Main Application

This ComfyUI node is adapted from the Random Prompt Builder desktop application.

| Feature | Desktop App | ComfyUI Node | |---------|-------------|--------------| | Interface | Electron GUI | ComfyUI Node Parameters | | Model Loading | node-llama-cpp | llama-cpp-python | | Batch Processing | Built-in batch UI | Uses ComfyUI batch system | | History/Favorites | Built-in management | Use ComfyUI workflow saving | | Prompt Display | Rich text preview | Separate Prompt Display node | | API Providers | Google Gemini, Custom API | GGUF models only | | Installation | Standalone executable | ComfyUI custom node |

The core prompt generation logic and LLM system prompts are shared between both versions for consistent output quality.

Changelog

v3.0 - Current

  • Feature parity with main desktop application (98%+)
  • Added style filter system (main style + realistic/anime sub-styles)
  • Added enhancement iteration system (0-3 rounds + locked phrases)
  • Added character overlays (furry, monster, sci-fi)
  • Added scene type control (solo, duo, group)
  • Extended character attributes (hair, eyes, facial hair, roleplay)
  • Added separate enhance toggles (person, pose, location)
  • Improved LLM system prompts for better output quality
  • Better error handling and user feedback

v2.0 - Enhanced

  • Critical fix: Returns single string instead of list (fixes CLIPTextEncode error)
  • Added structured prompt categories (attributes, action, background)
  • Added character controls (gender, age, body_type, ethnicity, height, physical attributes)
  • Added quality tags injection system with 9 style presets
  • Added BREAK support for SDXL/Pony workflows
  • Added model tuning parameters (top_p, frequency_penalty, presence_penalty)
  • Improved LLM system prompts for better structured output
  • Changed to control_after_generate for seed management
  • Better error handling and model caching

v1.0 - Initial

  • Initial release with basic GGUF prompt generation
  • Support for multiple target model formats
  • Basic seed and creativity controls

Additional Nodes

Prompt Display Node

A companion node for previewing generated prompts in the ComfyUI interface.

Usage:

  1. Add "Prompt Display (Preview Text)" node
  2. Connect the POSITIVE_PROMPT or NEGATIVE_PROMPT output
  3. The node displays the full prompt text in the node interface

This is helpful for reviewing prompts before they're encoded.

License

MIT License.

This project is a ComfyUI adaptation of the Random Prompt Builder desktop application. Both projects are developed by btitkin.

Contributing

Contributions are welcome. Please follow these steps:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/new-feature)
  3. Commit your changes (git commit -m 'Add new feature')
  4. Push to the branch (git push origin feature/new-feature)
  5. Open a Pull Request

Reporting Issues

When reporting issues, please include:

  • ComfyUI version
  • Python version
  • GPU type and VRAM amount
  • GGUF model being used
  • Full error message from console
  • Node parameter values used

Credits

Related Links

Support

For questions, issues, or discussions: