Turn plain English into real Danbooru tags using a local LLM. No cloud, no API keys, no nonsense.

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.

---

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:

1. Exact match - the tag exists as-is
2. Alias remap - blonde becomes blonde hair, boobs becomes breasts
3. Word-form fix - smirking becomes smirk, posing becomes pose
4. Sub-phrase recovery - real tags are pulled out of multi-word junk (black crop top yields crop top)
5. Fuzzy match - optional, off by default, remaps near-misses like typos
6. 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

1. Start LM Studio and load a model (Qwen3-1.7B recommended)
2. Enable the local server in LM Studio (default port 1234)
3. Open ComfyUI and load the included workflow: workflows/AI_Anime.json
4. Type your scene description in the user_prompt field
5. 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.