📝 ComfyUI Prompt Formatting Nodes

This repository contains custom nodes for ComfyUI designed to help structure, filter, and generate text prompts using categorized tag definitions stored in a YAML file.

Nodes Included

1. 📝 Categorized Prompt Formatter: Filters and restructures an existing input prompt based on categories and a template. Preserves tag details like weights.
2. 📝 Categorized Random Prompt Formatter: Generates a new random prompt by sampling tags from categories defined in the YAML, using a template structure and a seed for reproducibility.

---

Key Features (Overall)

• YAML-based Categorization: Define tags belonging to specific categories (e.g., eyes, style, quality) in an easy-to-edit YAML file.
• Hierarchical Categories ($include): Define broad categories that automatically inherit tags from more specific ones without manual repetition in the YAML.
• Template-Driven Output: Control the structure of the output prompt using simple placeholders like <|category_name|>.
• Flexible Tag Handling: Options for case sensitivity and matching tags regardless of underscores vs. spaces (e.g., blue_eyes vs blue eyes).

---

The YAML Definitions File (prompt_categories.yaml)

Both nodes rely on a YAML file to define which tags belong to which categories. An example file (prompt_categories.yaml) is included in this repository.

Format:

• Basic: ...
• Hierarchical Inclusion ($category): A category list can include all tags from another category by adding $other_category_name as an item.

  list_one:
    - tag_a
  list_two:
    - $list_one # Includes tag_a
    - tag_b
  

• Inline Tag Expansion (prefix $category suffix): You can generate tags combinatorially within a string. The node finds the first $category_name reference in the string, resolves all tags for that category, and substitutes each one back into the string pattern.

  colors:
    - red
    - blue
  items:
    - ball
    - cube
  colored_items:
    - $colors $items # Expands to: red ball, blue ball, red cube, blue cube
    - shiny $colors sphere # Expands to: shiny red sphere, shiny blue sphere
  # Note: Currently supports only one $category reference per line for expansion.
  #       '$category' at the start of a line with no other text is treated as a full list include.
  

• Dictionary Includes ($include/tags:): The older dictionary format for includes is also supported for backward compatibility

  eyes:
    - blue eyes
    - red eyes
  person_details:
    $include: # Inherit from 'eyes'
      - eyes
    tags: # Add tags specific to 'person_details'
      - smiling
      - freckles
  

File Location:

The nodes will search for the specified YAML file in this order:

1. Absolute path (if provided).
2. Relative to the ComfyUI-Prompt-Formatter node directory.
3. Relative to the main ComfyUI input/ directory.

Example File: See the included prompt_categories.yaml for a comprehensive example.

---

1. 📝 Categorized Prompt Formatter

This node takes an existing prompt string, analyzes its tags against your YAML definitions, and reconstructs a new prompt based on your template, applying various filtering options.

Inputs & Widgets

• prompt (String): The input prompt string (e.g., "1girl, masterpiece, blue_eyes, smiling...").
• category_definition_file (String): Name or path to your category YAML file (e.g., "prompt_categories.yaml").
• output_template (String): Defines the output structure using placeholders.
  • <|category_name|>: Includes all matched tags for this category.
  • <|category_name:N|>:
    • If N > 0: Includes at most the first N matched tags.
    • If N < 0: Includes at most the last abs(N) matched tags.
    • If N = 0: Includes no tags for this category.
• input_delimiter (String): Character(s) separating tags in the input prompt (Default: ,).
• output_delimiter (String): Character(s) used to join tags in the output formatted_prompt (Default: , ).
• strip_whitespace (Boolean): Remove whitespace around input tags before matching (Default: True).
• case_sensitive_matching (Boolean): Match tags case-sensitively against YAML (Default: False).
• handle_weights (Boolean): Parse and preserve weights like (tag:1.2) or [tag] (Default: True).
• match_underscores_spaces (Boolean): Treat tag_one and tag one as equivalent during matching (Default: True). Output preserves original format.
• disable_duplicates (Boolean): Prevent the same tag string from appearing multiple times in the output (first occurrence wins) (Default: False).
• unmatched_tag_handling (Dropdown): What to do with input tags not used by the template:
  • discard: Ignore them (Default).
  • append_end: Add them all to the end of the formatted prompt.
  • output_separately: Output them in the rejected_prompt slot.

Outputs

• formatted_prompt (String): The restructured prompt based on the template.
• rejected_prompt (String): Tags not included in formatted_prompt (content depends on unmatched_tag_handling).

Example Usage

• Input Prompt: "masterpiece, 1girl, blue eyes, red eyes, smiling, detailed background, anime style, illustration"

• YAML: (Assumes quality, character_num, eyes, person_details, style categories exist)

• Template: <|quality:1|>, <|character_num|>, <|eyes:-1|>, <|style:1|>

• Unmatched Handling: output_separately

• Disable Duplicates: False

• Result (formatted_prompt): "masterpiece, 1girl, red eyes, anime style"

• Result (rejected_prompt): "blue eyes, smiling, detailed background, illustration" (Assuming 'smiling', 'detailed background' weren't matched or used; 'blue eyes' was dropped by the limit -1; 'illustration' dropped by limit 1)

---

2. 📝 Categorized Random Prompt Formatter

This node generates completely new, random prompts by selecting tags from your YAML categories based on a template structure and a seed.

Inputs & Widgets

• category_definition_file (String): Name or path to your category YAML file.
• output_template (String): Defines the structure and how many random tags to pick per category.
  • <|category_name|>: Picks 1 random tag from the category.
  • <|category_name:N|>: Picks N unique random tags from the category (N >= 0). If fewer than N tags exist, picks all available. N=0 picks none.
• seed (Int): Seed for the random number generator. 0 generates a new random seed each run; any other value provides reproducible results.
• output_delimiter (String): Character(s) used to join the selected random tags (Default: , ).

Outputs

• random_prompt (String): The generated random prompt string.
• used_seed (Int): The actual seed used for generation (useful if input seed was 0).

Example Usage

• YAML: (Assumes standard categories exist)

• Template: <|quality:1|>, <|character_num:1|>, <|hair_style:2|>, <|setting:1|>

• Seed: 42

• Possible Result (random_prompt): "best quality, 1girl, long hair, twintails, outdoors" (Specific tags depend on seed 42 and YAML content)

• Result (used_seed): 42

---

Notes & Troubleshooting

• YAML Not Found: If the node prints a warning about not finding the YAML file, double-check the filename/path and ensure it's accessible (in the node folder, ComfyUI/input/, or an absolute path).
• Restart Required: Always restart ComfyUI after installing or updating custom nodes.
• $include Cycles: The code has basic protection against circular $include directives in the YAML (e.g., A includes B, B includes A). If detected, a warning is printed, and the cycle is broken.
• Tag Order (Formatter): When using limits (<|cat:N|>) or duplicate prevention in the Formatter node, the order of tags in the input prompt determines which ones are selected first or last.
• Tag Format Preservation (Formatter): The Formatter node preserves the exact format (including weights, underscores/spaces) of the input tags when placing them in the output, even if matching used variants (lowercase, space/underscore swap).