📚 Prompt Alias Swap 📚

Booru-style tagging is full of near-synonyms and character variants - "kermit," "kermit_the_frog," "kermit_(the_muppets)" all point at the same character, and different checkpoints were trained recognizing different ones of them best. PromptAliasSwap reads a group file of these equivalence sets and randomly swaps a matched tag for another member of its group - cheap lexical variety with no meaning change, or a way to normalize shorthand into whatever exact tag your checkpoint actually knows.

How it works

Alias groups live in .txt files under comfyui-adaptiveprompts/tag_alias_files/ - one group per line, tags comma-separated (the README notes it's built around pasting alias.csv-style content into a .txt file; .csv itself isn't supported directly). When the node finds a tag in your prompt that matches an entry in one of these groups, mode decides what happens: ALWAYS guarantees the tag gets swapped for a different member of its group every time; RANDOM picks any member of the group including the original tag itself, so it may re-select the same thing and leave the prompt unchanged. chance sits above both modes as an overall probability gate - even a matched tag only gets touched at all with probability chance, mode logic only kicks in after that roll succeeds.

The inputs and outputs that matter

• string - the prompt to process.
• alias_file - which .txt file in tag_alias_files/ to use. The node's schema currently only samples tags.txt, since that's the only file present until you add your own alongside it.
• mode - ALWAYS or RANDOM.
• chance - probability (0–1) that a matched tag gets swapped at all.
• seed - reproducibility.
• refresh_file - re-reads the alias file from disk instead of using a cached version.
• Output: Aliased String.

How to install it

Ships with the rest of the pack - search comfyui-adaptiveprompts in ComfyUI Manager, or install manually:

cd ComfyUI/custom_nodes
git clone https://github.com/Alectriciti/comfyui-adaptiveprompts

Restart ComfyUI. No models, no extra dependencies. You do need to populate tag_alias_files/ yourself - the pack doesn't ship pretrained alias lists out of the box.

Common issues & troubleshooting

Only tags.txt shows up as a choice. That's the only file the pack ships a slot for by default in the enum sample - add more .txt files to tag_alias_files/ and they should become selectable alongside it.

Multi-word phrases aren't matching. The README is explicit that, unlike PromptRepack, alias swap does not support whitespace of any kind - it's built for booru-style single tags, not natural-language phrases. If your alias groups contain spaces, they won't match reliably here.

You edited the alias file and nothing changed. It's cached by default for performance. Set refresh_file to true for the run where you want it to actually re-read the file from disk.

A tag never seems to change under ALWAYS mode. Check that its group in the alias file actually has more than one member - a "group" of a single tag has nothing else to swap to, so ALWAYS mode has no different option available and the tag stays as-is regardless of the guarantee.