✅ README.md — ComfyUI-prompt-utils

🧠 ComfyUI Prompt Utils

A modular toolkit for advanced prompt engineering in ComfyUI — designed for dataset creation, LoRA training, batch generation, and controlled variation.

✅ Extract & inject variables (seed=123, model=epicrealism)
✅ Manage multi-prompt batches (001_smile\n...\n---\n002_serious)
✅ Hide & swap variations with [[smile;laugh;neutral]]
✅ Fully composable — nodes work independently or chained

💡 No external dependencies — pure Python, works with any model (SDXL, Flux, Wan, LoRA, etc.).

---

📦 Installation

In your ComfyUI/custom_nodes folder:

git clone https://github.com/fmartinellidev/ComfyUI-prompt-utils.git

Or download as ZIP and extract into ComfyUI/custom_nodes/ComfyUI-prompt-utils.

Restart ComfyUI.

---

🧩 Included Nodes

Node	Purpose
Prompt Snippet Extractor	Split multi-prompt text into indexed snippets
Prompt Variable Extractor	Parse key='value' or key="value" from text
Prompt Variable Substitutor	Replace {key} placeholders with values
Prompt Hidden Processor	Swap [[option1;option2]] with a selected variation

All nodes are independent — use one or chain them all!

---

🔍 Node Details

1. Prompt Snippet Extractor

Splits a multi-prompt document (e.g. for dataset generation) into indexed snippets.

🔤 Inputs

Input	Type	Required	Default	Description
prompt_list	STRING	✅	(example)	Multi-snippet text (delimited by --- or custom)
snippet_index	INT	✅	0	Which snippet to extract (0-based)
split_char	STRING	✅	"---"	Delimiter between snippets
first_word_is_filename	BOOLEAN	✅	True	Treat first word as filename source
ignore_start_number_label	BOOLEAN	✅	True	Strip leading numbers (e.g. 001_ → "")

📤 Outputs

Output	Type	Description
prompt	STRING	Full snippet (e.g. "001_smile_front\nA gentle smile...")
prompt_text	STRING	Snippet without first word (e.g. "A gentle smile...")
filename_to_label	STRING	Cleaned label (e.g. "smile front")
filename	STRING	First word (e.g. "001_smile_front")

💡 Example

Input (prompt_list):

001_smile_front  
A gentle smile, facing camera  
---  
002_laugh_dynamic  
Laughing joyfully, head tilted

With snippet_index=0, first_word_is_filename=True, ignore_start_number_label=True:

Output	Value
prompt	"001_smile_front\nA gentle smile, facing camera"
prompt_text	"A gentle smile, facing camera"
filename_to_label	"smile front"
filename	"001_smile_front"

---

2. Prompt Variable Extractor

Extracts key='value' or key="value" pairs from text (e.g. metadata, config).

🔤 Inputs

Input	Type	Required	Default	Description
text	STRING	✅	""	Input text containing variables
prefix	STRING	✅	"#"	Prefix before keys (e.g. #seed=123)
delimiter_char	STRING	✅	"="	Char between key and value

📤 Outputs

Output	Type	Description
output_text	STRING	Text with variables removed
variables_json	STRING	JSON of extracted variables (e.g. {"seed": "123"})

💡 Example

Input (text):
#seed=1234 #model="epicrealismxl" A portrait, studio lighting

Outputs:

• output_text: "A portrait, studio lighting"
• variables_json: {"seed": "1234", "model": "epicrealismxl"}

---

3. Prompt Variable Substitutor

Replaces {key} placeholders in a template using a JSON variable map.

🔤 Inputs

Input	Type	Required	Description
prompt_template	STRING	✅	Template with {key} placeholders
variables_json	STRING	✅	JSON object (e.g. {"seed": "123"})

📤 Outputs

Output	Type	Description
prompt	STRING	Prompt with placeholders replaced

💡 Example

Inputs:

• prompt_template: "A {expression} portrait, {lighting} lighting"
• variables_json: {"expression": "smiling", "lighting": "soft"}

Output:

• prompt: "A smiling portrait, soft lighting"

---

4. Hidden Prompt Processor

Swaps hidden variation blocks like [[smile;laugh;neutral]] with a selected option.

🔤 Inputs

Input	Type	Required	Default	Description
prompt	STRING	✅	(example)	Prompt with hidden blocks
input_index_split	INT	✅	0	Which variation to use (0-based)
delimiter_pair	STRING	✅	"[[ ]]"	Block style: [[ ]] or ## ##

📤 Outputs

Output	Type	Description
input_prompt	STRING	Prompt with hidden block replaced
clean_prompt	STRING	Prompt with all hidden blocks removed

💡 Example

Input (prompt):
A portrait of [[smile;laugh;neutral]], {lighting} lighting

With input_index_split=1, delimiter_pair="[[ ]]":

Output	Value
input_prompt	"A portrait of laugh, {lighting} lighting"
clean_prompt	"A portrait of , {lighting} lighting"

🔗 Pro tip: Chain with Prompt Variable Substitutor to replace {lighting} next!

---

🧩 Recommended Workflow

graph LR
    A[Prompt Snippet Extractor] -->|prompt_text| B[Hidden Prompt Processor]
    B -->|input_prompt| C[Prompt Variable Substitutor]
    C --> D[Stable Diffusion / WaveSpeed / etc.]
    A -->|filename| E[SaveImage]

Perfect for:

• 📁 LoRA dataset generation (200+ expressions)
• 🎭 Controlled facial variation (no random sampling)
• 📊 Metadata-rich outputs (embed seed/model in filename)

---

🤝 Contributions

PRs welcome! For major changes, please open an issue first.

---

Made with ❤️ by fmartinellidev
Inspired by advanced prompt engineering needs in AI character creation.