ComfyUI Booru Tag Pipeline

Standalone ComfyUI custom nodes for cleaning and canonicalizing booru-style tags against a local Danbooru snapshot.

Public dataset:

• baton4ik/danbooru-tag-metadata-snapshot

This package is meant to sit after a prompt-rewriting step:

1. an LLM or prompt tool produces booru-ish tags
2. Booru Tag Pipeline normalizes those tags
3. the cleaned tags continue into the image or video workflow

The package is deterministic on purpose. It is strong at canonicalization, aliases, and implications. It does not try to semantically guess every unknown phrase.

Nodes

Booru Tag Pipeline

Main runtime node.

Inputs:

• tags_text
• include_implications
• implication_depth
• include_retired_aliases
• include_deleted_aliases
• drop_quality_boilerplate
• prefer_underscores
• sort_mode

Outputs:

• final_tags
• unknown_tags
• replacements_made
• implications_added
• debug_log

What it does:

• splits raw comma-separated booru-ish tags
• strips simple weighting like (tag:1.2)
• resolves canonical tags from a local snapshot
• redirects aliases to canonical tags
• optionally expands active implications
• drops common quality boilerplate like masterpiece
• reports unresolved leftovers explicitly

Examples:

• hatsune miku -> hatsune_miku
• looking at viewer -> looking_at_viewer
• twin tails -> twintails
• thigh highs -> thighhighs

Booru Tag Lookup

Small debug node for inspecting one tag candidate.

Outputs:

• resolved canonical tag
• incoming aliases
• outgoing implications
• debug log

Installation

Clone into ComfyUI's custom_nodes directory:

cd /path/to/ComfyUI/custom_nodes
git clone https://github.com/hlibr/ComfyUI-Booru-Tag-Pipeline.git comfyui_booru_tag_pipeline

Install dependencies into the same Python environment ComfyUI uses:

/path/to/ComfyUI/.venv/bin/python -m pip install -r /path/to/ComfyUI/custom_nodes/comfyui_booru_tag_pipeline/requirements.txt

Restart ComfyUI after installation.

Download A Prebuilt Snapshot

If the local snapshot is missing, the node will try to download the current public SQLite snapshot automatically on first use.

You can also download it manually:

/path/to/ComfyUI/.venv/bin/python /path/to/ComfyUI/custom_nodes/comfyui_booru_tag_pipeline/scripts/download_public_snapshot.py

By default that pulls:

baton4ik/danbooru-tag-metadata-snapshot / booru_snapshot.sqlite

and places it at:

comfyui_booru_tag_pipeline/data/booru_snapshot.sqlite

Automatic download is only for the missing-snapshot case. The package does not silently auto-update an existing local snapshot.

Build The Snapshot

The runtime nodes expect a local SQLite snapshot at:

comfyui_booru_tag_pipeline/data/booru_snapshot.sqlite

Build it with:

/path/to/ComfyUI/.venv/bin/python /path/to/ComfyUI/custom_nodes/comfyui_booru_tag_pipeline/scripts/build_data_snapshot.py

You can still override the output path if you want:

/path/to/ComfyUI/.venv/bin/python /path/to/ComfyUI/custom_nodes/comfyui_booru_tag_pipeline/scripts/build_data_snapshot.py --output /custom/path/booru_snapshot.sqlite

Optional authentication for Danbooru rate limits:

export DANBOORU_LOGIN=your_username
export DANBOORU_API_KEY=your_api_key

Current snapshot sources:

• live Danbooru tags.json
• Danbooru tag_aliases
• Danbooru tag_implications

Maintainer: Publish Public Data

This section is only needed if you are maintaining the public data artifact. Normal users do not need it.

The code repo is kept separate from the public dataset because the snapshot is large, refreshable, and published in both SQLite and Parquet formats.

The public dataset publishes both:

• booru_snapshot.sqlite for local runtime use
• tags.parquet, tag_aliases.parquet, tag_implications.parquet for viewer-friendly and analytics-friendly access

The public dataset is published in two complementary formats. The SQLite snapshot is suited to local indexed lookup workflows, while the Parquet tables are better for browser-based exploration and analytical tooling such as DuckDB, Polars, Pandas, and Spark.

Use the staging script to build a publishable dataset folder:

/path/to/ComfyUI/.venv/bin/python /path/to/ComfyUI/custom_nodes/comfyui_booru_tag_pipeline/scripts/prepare_hf_dataset.py

The staging script requires publishing dependencies:

/path/to/ComfyUI/.venv/bin/python -m pip install -r /path/to/ComfyUI/custom_nodes/comfyui_booru_tag_pipeline/requirements-publish.txt

Detailed publish/download instructions live here:

• docs/HUGGINGFACE.md

Example Stack

One practical stack is:

1. GGUF Prompt Rewriter or another local LLM node
2. Booru Tag Pipeline
3. your normal image/video generation workflow

This package works best on already tag-like LLM output, not raw natural-language prose.

Snapshot Coverage

The snapshot is built from live Danbooru tag, alias, and implication data and is intended to be strong enough for serious deterministic normalization. Exact row counts and timestamps are published with the public dataset artifact so the README does not go stale every time the snapshot is refreshed.

License

MIT