NeuralBooru is a ComfyUI custom node that bridges your local LLM server (LM Studio, Ollama, llama.cpp, vLLM, anything OpenAI-compatible) and your image generation pipeline. Describe a scene in plain English and it converts it into booru-style tags, validates them against the real Danbooru vocabulary so only tags your model was actually trained on survive, orders them the way booru-trained models expect, wraps them in your model's preferred template, and feeds them straight into the sampler.

Example 1

What makes it different

Most tag generators are specialized fine-tuned models (like TIPO/DanTagGen) that bake the tag vocabulary into their weights. NeuralBooru takes the opposite approach: it is a model-agnostic adapter. The LLM proposes, and a Danbooru whitelist disposes.

Bring your own LLM. It uses whatever model you run in LM Studio, Ollama, or any other OpenAI-compatible server. Swap a 1.7B for a 7B or next year's model and the output improves for free.
General world knowledge. A general LLM understands "a noir detective in 1940s LA" or franchise references and reasons about what tags they imply.
Validated output. Every tag is checked against ~140k real Danbooru tags, so "tag-shaped" natural language never leaks into your prompt.
Editable in plain English. Change behavior by editing the system prompt, not by retraining a model.

How It Works

flowchart LR
    UP["user_prompt"] --> LMB

    subgraph NB ["NeuralBooru (this repo)"]
        LMB(["NeuralBooru<br/>node"])
    end

    LMB <-->|"OpenAI-compatible API<br/>localhost:1234"| LMS[("LM Studio<br/>qwen3-1.7b")]

    subgraph LOAD ["Load Model"]
        CKPT["novaAnimeXL<br/>Checkpoint"]
    end

    LMB -->|"validated tags<br/>(template applied)"| POS["CLIP Text Encode<br/>(Positive)"]
    CKPT -->|CLIP| CLIPS["CLIP Set<br/>Last Layer"]
    CLIPS -->|CLIP| POS
    CLIPS -->|CLIP| NEG["CLIP Text Encode<br/>(Negative)"]
    CKPT -->|MODEL| KS["KSampler<br/>25 steps · cfg 5.5<br/>euler_ancestral"]
    CKPT -->|VAE| DEC["VAE Decode"]

    POS -->|positive| KS
    NEG -->|negative| KS
    LAT["Empty Latent<br/>1024 × 1024"] -->|latent| KS
    KS -->|samples| DEC
    DEC -->|IMAGE| SAVE["Save Image"]

A real run. You type:

A cute vampire girl with fangs, wearing jean shorts and a black crop top,
arms crossed and smirking, standing in a dark classroom at night

The LLM proposes messy, tag-ish phrases:

1girl, young adult, vampire, fangs, jean shorts, black crop top,
arms crossed, smirking, dark classroom, night, standing

Validation cleans them into real Danbooru tags:

1girl, vampire, fangs, denim shorts, crop top, crossed arms, smirk,
dark, classroom, night, standing

Note what happened: jean shorts was remapped to the real alias denim shorts, arms crossed to crossed arms, smirking to smirk, crop top and classroom were pulled out of multi-word phrases, and young adult (not a real tag) was dropped. Finally the tags are wrapped in your template and the non-tags are reported on the dropped_tags output.

And the result, straight from that prompt through NovaAnimeXL:

Everything runs locally. No internet connection required after setup.

Features

Real tag validation - every tag is checked against the Danbooru vocabulary, with alias remapping, word-form fixing, and multi-word recovery
Danbooru tag ordering - kept tags are reordered the way booru-trained models expect: people counts, character, copyright, artist, general, meta
Server-agnostic - works with any OpenAI-compatible endpoint: LM Studio, Ollama, llama.cpp, vLLM (with optional Bearer auth)
Reasoning-model aware - enable_thinking switch, <think> stripping, and fallback to the separate reasoning field some servers use
Template presets - one-click quality-tag wrappers for Illustrious, Pony, Animagine XL, and NovaAnimeXL, or write your own with {prompt}
Re-roll with seed - a seed widget re-executes the node on demand for a fresh tag variation
Transparency - a second dropped_tags output shows exactly what was filtered
Visible errors - a dead server fails the workflow with a clear message (or set on_error to fall back to your raw description)
Zero dependencies - pure Python stdlib, nothing to install

Tag Validation

This is the core of NeuralBooru. After the LLM responds, every candidate tag is resolved against a bundled list of ~140k real Danbooru tags in this order:

Exact match - the tag exists as-is
Alias remap - blonde becomes blonde hair, boobs becomes breasts
Word-form fix - smirking becomes smirk, posing becomes pose
Sub-phrase recovery - real tags are pulled out of multi-word junk (black crop top yields crop top)
Fuzzy match - optional, off by default, remaps near-misses like typos
Drop - if nothing matches, the candidate is filtered out (strict mode) and reported

Your template (the quality boosters like masterpiece, best quality) is never validated. Only the LLM's tags are.

Requirements

ComfyUI
LM Studio or Ollama (or any OpenAI-compatible server) running locally with a model loaded
A chat model that understands booru tagging. Qwen3-1.7B works great and is fast
Any SDXL-compatible checkpoint (built and tested with NovaAnimeXL)

Installation

Via ComfyUI Manager (recommended, stable releases): Search for NeuralBooru in the Custom Nodes section.

Manual (latest features, may be ahead of the registry):

cd ComfyUI/custom_nodes
git clone https://github.com/ChrisJohnson89/ComfyUI-NeuralBooru

New features land on main first and are batched into registry releases once proven. If you want what the README describes the moment it merges, use the manual install and git pull to update.

Restart ComfyUI. The NeuralBooru node appears under the NeuralBooru category, along with the NeuralBooru LLM and NeuralBooru Validator split nodes (see below).

Quick Start

Start LM Studio and load a model (Qwen3-1.7B recommended)
Enable the local server in LM Studio (default port 1234)
Open ComfyUI and load the included workflow: workflows/AI_Anime.json
Type your scene description in the user_prompt field
Hit Run

Tag validation is on by default. Check the ComfyUI console for a [NeuralBooru] dropped N non-tags line to see what got filtered.

Node Parameters

The included example workflow wires the tags and dropped_tags outputs to two core PreviewAny nodes, so every run shows exactly which tags survived validation and which candidates were filtered, right next to the graph.

| Parameter | Default | Description | |---|---|---| | user_prompt | - | Plain English scene description | | system_prompt | Built-in | Instructions for the LLM, controls tag style and rules | | prompt_template | NovaAnimeXL | Wrapper for generated tags. Use {prompt} as placeholder | | model | qwen/qwen3-1.7b | Model identifier as your server reports it (/v1/models) | | enable_thinking | False | Let reasoning models think before answering (slower) | | temperature | 0.4 | Lower = more consistent tags, higher = more creative | | max_tokens | 500 | Max tokens for the LLM response | | seed | 0 | Change to re-roll; also passed to the API | | lm_studio_url | http://localhost:1234 | Server address. Ollama: http://localhost:11434 | | validate_tags | True | Filter the LLM output against the Danbooru vocabulary | | strict_tags | True | Drop tags that are not real (off = keep them) | | fuzzy_cutoff | 0.0 | 0 disables. 0.85-0.95 remaps near-misses to real tags | | min_post_count | 0 | Drop tags rarer than this many Danbooru posts | | max_tags | 0 | 0 = unlimited, otherwise cap the tag count | | timeout | 120 | Seconds to wait for the LLM response | | api_key | empty | Optional Bearer token for servers that require auth | | exclude_categories | empty | Drop tag categories: artist, character, copyright, meta | | on_error | raise | Fail visibly, or use_input_text to fall back to your description | | template_preset | custom | Quality-tag wrapper: illustrious, pony, animagine_xl, nova_anime_xl, tags_only, or custom (uses prompt_template) | | sort_tags | True | Reorder kept tags into Danbooru-conventional order |

Outputs

| Output | Description | |---|---| | prompt | The validated, template-wrapped prompt for your CLIP encoder | | dropped_tags | Comma-separated list of candidates that were filtered out | | tags | The validated tags alone, without the template (display, metadata, custom wrapping) |

Split nodes: NeuralBooru LLM + NeuralBooru Validator

The all-in-one node above is the easiest way to run the pipeline, but the two halves are also available as separate nodes (contributed by @greeze):

NeuralBooru LLM talks to your LLM server and outputs raw_tags (the cleaned, think-stripped model output) plus an is_fallback flag that goes True when the call failed and on_error=use_input_text passed your description through.
NeuralBooru Validator takes comma-separated tags, validates them against the Danbooru vocabulary, and applies the template. It has the same prompt / dropped_tags / tags outputs as the combined node.

Wire raw_tags -> tags and is_fallback -> is_fallback and the pair behaves exactly like the original node (internally, the combined node runs these two). Split them when you want to:

see or edit the raw LLM output before validation
validate hand-typed or externally generated tags with no LLM involved
run one LLM call through several validator configs (different templates, strictness, or category filters)

The included workflows/AI_Anime_split.json is the example workflow rebuilt on the split nodes.

Prompt Template

The template wraps the generated tags. The {prompt} token is replaced with the validated tags:

masterpiece, best quality, ..., {prompt}, BREAK, depth of field, volumetric lighting

Swap this out for any model's preferred format.

Recommended Setup

| Setting | Value | Why | |---|---|---| | Model | Qwen3-1.7B | Fast, great tag quality, supports /no_think | | Temperature | 0.4 | Consistent, accurate booru tags | | Max tokens | 500 | Enough for detailed scenes, won't waste time | | Checkpoint | NovaAnimeXL Illustrious | What the default template is tuned for | | validate_tags | On | Keeps only real Danbooru tags |

Roadmap

See ROADMAP.md for planned work, including better fuzzy matching, a tag-DB refresh script, and a finetuned drop-in tagger model (tooling already in finetune/).

Credits

Tag data is derived from the Danbooru tag list distributed with DominikDoom/a1111-sd-webui-tagcomplete.

License

MIT - do whatever you want with it.