### Install Python Packages (Manual/Non-Windows)

Source: https://github.com/pythongosssss/comfyui-wd14-tagger/blob/main/README.md

Use this command to install required Python packages for manual or non-Windows installations.

```bash
pip install -r requirements.txt
```

--------------------------------

### Clone Repository for Installation

Source: https://github.com/pythongosssss/comfyui-wd14-tagger/blob/main/README.md

Clone the repository into the custom_nodes folder to install the extension. Ensure you are in the correct directory before cloning.

```bash
git clone https://github.com/pythongosssss/ComfyUI-WD14-Tagger
```

--------------------------------

### Install Python Packages (Windows Standalone)

Source: https://github.com/pythongosssss/comfyui-wd14-tagger/blob/main/README.md

Use this command to install required Python packages when using the Windows standalone installation with embedded Python.

```bash
../../../python_embeded/python.exe -s -m pip install -r requirements.txt
```

--------------------------------

### Install ComfyUI WD14 Tagger

Source: https://context7.com/pythongosssss/comfyui-wd14-tagger/llms.txt

Clone the repository into the ComfyUI custom nodes directory and install Python dependencies. For Windows standalone installations, use the embedded Python interpreter.

```bash
# Clone into ComfyUI custom nodes folder
cd ComfyUI/custom_nodes
git clone https://github.com/pythongosssss/ComfyUI-WD14-Tagger

# Install requirements (standard)
pip install -r ComfyUI-WD14-Tagger/requirements.txt

# OR for Windows standalone (embedded Python)
../../../python_embeded/python.exe -s -m pip install -r requirements.txt
```

--------------------------------

### Change Directory to Extension Folder

Source: https://github.com/pythongosssss/comfyui-wd14-tagger/blob/main/README.md

Navigate to the cloned extension directory in your terminal. This is necessary before installing Python packages.

```bash
cd C:\ComfyUI_windows_portable\ComfyUI\custom_nodes\ComfyUI-WD14-Tagger
```

--------------------------------

### HTTP REST Endpoint for Tagging

Source: https://context7.com/pythongosssss/comfyui-wd14-tagger/llms.txt

Examples of using `curl` to interact with the `/pysssss/wd14tagger/tag` HTTP endpoint. This allows tagging images located in ComfyUI's output, input, or temp directories.

```bash
# Tag an image in the ComfyUI output directory
curl "http://127.0.0.1:8188/pysssss/wd14tagger/tag?filename=ComfyUI_00001_.png&type=output"
# Response: "1girl, solo, long hair, blue eyes, smile, school uniform"

# Tag an image in the input directory, with subfolder
curl "http://127.0.0.1:8188/pysssss/wd14tagger/tag?filename=photo.jpg&type=input&subfolder=portraits"
# Response: "1girl, realistic, short hair, red lips, jacket"

# With ComfyUI client ID and node ID (used for live status updates)
curl "http://127.0.0.1:8188/pysssss/wd14tagger/tag?filename=test.png&type=output&clientId=abc123&node=7"

# Error responses:
# 404 — filename parameter missing or file not found
# 400 — invalid type value (must be output, input, or temp)
# 403 — path traversal attempt blocked (image_path outside target_dir)
```

--------------------------------

### ComfyUI Workflow Node for WD14 Tagger

Source: https://context7.com/pythongosssss/comfyui-wd14-tagger/llms.txt

Example JSON snippet for configuring the WD14 Tagger node within a ComfyUI workflow. It specifies the model, confidence thresholds, and tag formatting options.

```json
{
    "id": 7,
    "type": "WD14Tagger|pysssss",
    "inputs": [
        {"name": "image", "link": 5}          # link from LoadImage output
    ],
    "widgets_values": [
        "wd-v1-4-moat-tagger-v2",             # model
        0.35,                                   # threshold
        0.85,                                   # character_threshold
        False,                                  # replace_underscore
        False,                                  # trailing_comma
        "monochrome, greyscale"                 # exclude_tags
    ]
}
```

--------------------------------

### GET /pysssss/wd14tagger/tag

Source: https://context7.com/pythongosssss/comfyui-wd14-tagger/llms.txt

A ComfyUI server route that accepts an image file already present on disk (in the `output`, `input`, or `temp` directories) and returns its tags as a JSON string. Used by the right-click context menu in the ComfyUI frontend.

```APIDOC
## GET /pysssss/wd14tagger/tag

### Description
A ComfyUI server route that accepts an image file already present on disk (in the `output`, `input`, or `temp` directories) and returns its tags as a JSON string. Used by the right-click context menu in the ComfyUI frontend.

### Method
GET

### Endpoint
`/pysssss/wd14tagger/tag`

### Parameters
#### Query Parameters
- **filename** (str) - Required - The name of the image file.
- **type** (str) - Required - The directory type of the image file (e.g., `output`, `input`, `temp`).
- **subfolder** (str, optional) - The subfolder within the specified type directory.
- **clientId** (str, optional) - ComfyUI client ID for live status updates.
- **node** (str, optional) - Node ID for live status updates.

### Response
#### Success Response (200)
- **tags** (str) - A comma-separated string of tags.

### Response Example
```bash
# Tag an image in the ComfyUI output directory
curl "http://127.0.0.1:8188/pysssss/wd14tagger/tag?filename=ComfyUI_00001_.png&type=output"
# Response: "1girl, solo, long hair, blue eyes, smile, school uniform"

# Tag an image in the input directory, with subfolder
curl "http://127.0.0.1:8188/pysssss/wd14tagger/tag?filename=photo.jpg&type=input&subfolder=portraits"
# Response: "1girl, realistic, short hair, red lips, jacket"

# With ComfyUI client ID and node ID
curl "http://127.0.0.1:8188/pysssss/wd14tagger/tag?filename=test.png&type=output&clientId=abc123&node=7"
```

### Error Handling
- **404** — filename parameter missing or file not found.
- **400** — invalid type value (must be output, input, or temp).
- **403** — path traversal attempt blocked (image_path outside target_dir).
```

--------------------------------

### Manually Download Model Files

Source: https://github.com/pythongosssss/comfyui-wd14-tagger/blob/main/README.md

Instructions for manually downloading model files if automatic download is not desired. Place these files in the 'models' folder within the extension directory.

```bash
model.onnx
selected_tags.csv
```

--------------------------------

### Core Async Tagging Function (`tag()`)

Source: https://context7.com/pythongosssss/comfyui-wd14-tagger/llms.txt

Demonstrates how to use the `tag()` function asynchronously to process a PIL image and generate tags. Ensure the ComfyUI environment is initialized before importing `tag`.

```python
import asyncio
from PIL import Image
from wd14tagger import tag  # import after ComfyUI environment is initialized

async def run_tagging():
    image = Image.open("my_image.png").convert("RGB")

    result = await tag(
        image=image,
        model_name="wd-v1-4-moat-tagger-v2",   # model name (with or without .onnx)
        threshold=0.35,                          # general tag confidence cutoff
        character_threshold=0.85,               # character tag confidence cutoff
        exclude_tags="monochrome, greyscale",   # comma-separated tags to suppress
        replace_underscore=True,                 # replace _ with space in tag names
        trailing_comma=False,                    # use trailing comma format if True
        client_id=None,                          # optional: ComfyUI client ID for progress
        node=None                                # optional: node ID for status updates
    )

    print(result)
    # Output: "1girl, solo, long hair, blue eyes, smile, school uniform, outdoors"

asyncio.run(run_tagging())
```

--------------------------------

### Automatic Model Downloader (`download_model()`)

Source: https://context7.com/pythongosssss/comfyui-wd14-tagger/llms.txt

Shows how to use `download_model()` to automatically fetch ONNX models and CSV tag files from HuggingFace. You can optionally set the `HF_ENDPOINT` environment variable to use a mirror.

```python
import asyncio
import os
from wd14tagger import download_model

# Override HuggingFace endpoint with a mirror (optional)
os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"

async def ensure_model():
    # Downloads to the local models/ directory automatically
    # Sends progress updates via update_node_status if client_id/node provided
    await download_model(
        model="wd-v1-4-convnextv2-tagger-v2",
        client_id=None,   # set to ComfyUI client ID for UI progress bar
        node=None         # set to node ID for UI status badge
    )
    print("Model downloaded to models/wd-v1-4-convnextv2-tagger-v2.onnx")
    print("Tags CSV at models/wd-v1-4-convnextv2-tagger-v2.csv")

asyncio.run(ensure_model())
```

--------------------------------

### get_installed_models()

Source: https://context7.com/pythongosssss/comfyui-wd14-tagger/llms.txt

Returns the filenames of all ONNX models that have both a .onnx file and a matching .csv tag file present in the local models/ directory.

```APIDOC
## get_installed_models()

### Description
Returns the filenames of all ONNX models that have both a `.onnx` file and a matching `.csv` tag file present in the local `models/` directory.

### Method
```python
get_installed_models()
```

### Parameters
None

### Returns
- A list of strings, where each string is the filename of an installed and ready-to-use model.

### Example
```python
from wd14tagger import get_installed_models

models = list(get_installed_models())
print(models)
# Example output:
# ["wd-v1-4-moat-tagger-v2.onnx", "wd-v1-4-convnextv2-tagger-v2.onnx"]

# Check if a specific model is ready to use without downloading:
model_name = "wd-v1-4-moat-tagger-v2"
is_ready = any(model_name + ".onnx" in s for s in models)
print(is_ready)  # True or False
```
```

--------------------------------

### User Configuration Overrides - pysssss.user.json

Source: https://context7.com/pythongosssss/comfyui-wd14-tagger/llms.txt

Create this file to override default settings from `pysssss.json` without modifying the original. It supports any subset of the `settings` keys.

```json
{
  "name": "WD14Tagger",
  "settings": {
    "model": "wd-eva02-large-tagger-v3",
    "threshold": 0.40,
    "character_threshold": 0.75,
    "exclude_tags": "monochrome, greyscale, simple background",
    "ortProviders": ["CUDAExecutionProvider", "CPUExecutionProvider"],
    "HF_ENDPOINT": "https://huggingface.co"
  }
}
```

--------------------------------

### List Locally Available ONNX Models

Source: https://context7.com/pythongosssss/comfyui-wd14-tagger/llms.txt

This Python function retrieves a list of all ONNX models available locally that have both a `.onnx` file and a corresponding `.csv` tag file in the `models/` directory. It's useful for checking which models are ready for use without needing to download them.

```python
from wd14tagger import get_installed_models

models = list(get_installed_models())
print(models)
# Example output:
# ["wd-v1-4-moat-tagger-v2.onnx", "wd-v1-4-convnextv2-tagger-v2.onnx"]

# Check if a specific model is ready to use without downloading:
model_name = "wd-v1-4-moat-tagger-v2"
is_ready = any(model_name + ".onnx" in s for s in models)
print(is_ready)  # True or False
```

--------------------------------

### download_model() — Automatic Model Downloader

Source: https://context7.com/pythongosssss/comfyui-wd14-tagger/llms.txt

Downloads `model.onnx` and `selected_tags.csv` for a given model name from HuggingFace (or a mirror specified via the `HF_ENDPOINT` environment variable). Called automatically by `tag()` when the model is not found locally.

```APIDOC
## download_model()

### Description
Downloads `model.onnx` and `selected_tags.csv` for a given model name from HuggingFace (or a mirror specified via the `HF_ENDPOINT` environment variable). Called automatically by `tag()` when the model is not found locally.

### Parameters
- **model** (str) - The name of the model to download.
- **client_id** (str, optional) - Set to ComfyUI client ID for UI progress bar.
- **node** (str, optional) - Set to node ID for UI status badge.

### Usage Example
```python
import asyncio
import os
from wd14tagger import download_model

os.environ["HF_ENDPOINT"] = "https://hf-mirror.com" # Optional mirror

async def ensure_model():
    await download_model(
        model="wd-v1-4-convnextv2-tagger-v2",
        client_id=None,
        node=None
    )
    print("Model downloaded to models/wd-v1-4-convnextv2-tagger-v2.onnx")
    print("Tags CSV at models/wd-v1-4-convnextv2-tagger-v2.csv")

asyncio.run(ensure_model())
```
```

--------------------------------

### Default Configuration - pysssss.json

Source: https://context7.com/pythongosssss/comfyui-wd14-tagger/llms.txt

Defines default settings for the WD14 Tagger, including model selection, inference thresholds, ONNX execution providers, and a list of available models with their HuggingFace download URLs.

```json
{
  "name": "WD14Tagger",
  "logging": false,
  "settings": {
    "model": "wd-v1-4-moat-tagger-v2",
    "threshold": 0.35,
    "character_threshold": 0.85,
    "exclude_tags": "",
    "ortProviders": ["CUDAExecutionProvider", "CPUExecutionProvider"],
    "HF_ENDPOINT": "https://huggingface.co"
  },
  "models": {
    "wd-eva02-large-tagger-v3": "{HF_ENDPOINT}/SmilingWolf/wd-eva02-large-tagger-v3",
    "wd-vit-tagger-v3": "{HF_ENDPOINT}/SmilingWolf/wd-vit-tagger-v3",
    "wd-swinv2-tagger-v3": "{HF_ENDPOINT}/SmilingWolf/wd-swinv2-tagger-v3",
    "wd-convnext-tagger-v3": "{HF_ENDPOINT}/SmilingWolf/wd-convnext-tagger-v3",
    "wd-v1-4-moat-tagger-v2": "{HF_ENDPOINT}/SmilingWolf/wd-v1-4-moat-tagger-v2",
    "wd-v1-4-convnextv2-tagger-v2": "{HF_ENDPOINT}/SmilingWolf/wd-v1-4-convnextv2-tagger-v2",
    "wd-v1-4-convnext-tagger-v2": "{HF_ENDPOINT}/SmilingWolf/wd-v1-4-convnext-tagger-v2",
    "wd-v1-4-convnext-tagger": "{HF_ENDPOINT}/SmilingWolf/wd-v1-4-convnext-tagger",
    "wd-v1-4-vit-tagger-v2": "{HF_ENDPOINT}/SmilingWolf/wd-v1-4-vit-tagger-v2",
    "wd-v1-4-swinv2-tagger-v2": "{HF_ENDPOINT}/SmilingWolf/wd-v1-4-swinv2-tagger-v2",
    "wd-v1-4-vit-tagger": "{HF_ENDPOINT}/SmilingWolf/wd-v1-4-vit-tagger"
  }
}
```

--------------------------------

### tag() — Core Async Tagging Function

Source: https://context7.com/pythongosssss/comfyui-wd14-tagger/llms.txt

The central async function that preprocesses a PIL image, runs ONNX inference, filters by threshold, and returns a formatted comma-separated tag string. Called internally by the ComfyUI node and the HTTP endpoint.

```APIDOC
## tag()

### Description
The central async function that preprocesses a PIL image, runs ONNX inference, filters by threshold, and returns a formatted comma-separated tag string. Called internally by the ComfyUI node and the HTTP endpoint.

### Parameters
- **image** (PIL.Image.Image) - The image to tag.
- **model_name** (str) - Model name (with or without .onnx).
- **threshold** (float) - General tag confidence cutoff.
- **character_threshold** (float) - Character tag confidence cutoff.
- **exclude_tags** (str) - Comma-separated tags to suppress.
- **replace_underscore** (bool) - Replace _ with space in tag names.
- **trailing_comma** (bool) - Use trailing comma format if True.
- **client_id** (str, optional) - ComfyUI client ID for progress.
- **node** (str, optional) - Node ID for status updates.

### Request Example
```python
import asyncio
from PIL import Image
from wd14tagger import tag

async def run_tagging():
    image = Image.open("my_image.png").convert("RGB")
    result = await tag(
        image=image,
        model_name="wd-v1-4-moat-tagger-v2",
        threshold=0.35,
        character_threshold=0.85,
        exclude_tags="monochrome, greyscale",
        replace_underscore=True,
        trailing_comma=False,
        client_id=None,
        node=None
    )
    print(result)

asyncio.run(run_tagging())
```

### Response
- **result** (str) - A comma-separated string of tags.
```

--------------------------------

### ComfyUI WD14Tagger Node API

Source: https://context7.com/pythongosssss/comfyui-wd14-tagger/llms.txt

Python code defining the ComfyUI node registration and input/output types for the WD14 Tagger. The node accepts an IMAGE tensor and outputs a STRING list of tags.

```python
# Node registration keys (used in ComfyUI workflow JSON)
NODE_CLASS_MAPPINGS = {
    "WD14Tagger|pysssss": WD14Tagger,
}
NODE_DISPLAY_NAME_MAPPINGS = {
    "WD14Tagger|pysssss": "WD14 Tagger 🐍",
}

# Input types returned by WD14Tagger.INPUT_TYPES():
# {
#   "required": {
#     "image":               ("IMAGE",),
#     "model":               (["wd-eva02-large-tagger-v3", "wd-vit-tagger-v3", ...], {"default": "wd-v1-4-moat-tagger-v2"}),
#     "threshold":           ("FLOAT", {"default": 0.35, "min": 0.0, "max": 1.0, "step": 0.05}),
#     "character_threshold": ("FLOAT", {"default": 0.85, "min": 0.0, "max": 1.0, "step": 0.05}),
#     "replace_underscore":  ("BOOLEAN", {"default": False}),
#     "trailing_comma":      ("BOOLEAN", {"default": False}),
#     "exclude_tags":        ("STRING",  {"default": ""}),
#   }
# }
# 
# RETURN_TYPES = ("STRING",)   # one tag string per image
# OUTPUT_IS_LIST = (True,)     # output is always a list (supports batches)
# FUNCTION = "tag"
# CATEGORY = "image"

```

--------------------------------

### Report Node Status and Progress

Source: https://context7.com/pythongosssss/comfyui-wd14-tagger/llms.txt

These Python functions, `update_node_status` and `update_node_status_async`, are used to send status messages and progress updates to a specific ComfyUI node via WebSocket. This is particularly useful for displaying live progress during model downloads directly on the node in the graph UI. The synchronous version is safe for non-async contexts, while the async variant is for use within coroutines.

```python
from pysssss import update_node_status, update_node_status_async

# Synchronous — safe to call from non-async context
update_node_status(
    client_id="abc123",   # ComfyUI websocket client ID (None = use server's current client)
    node="7",             # Node ID as a string
    text="Downloading wd-v1-4-moat-tagger-v2",  # Badge label (None clears the badge)
    progress=0.45         # Float 0.0–1.0 for progress bar fill (None = no bar)
)

# Clear the status badge when done
update_node_status(client_id="abc123", node="7", text=None)

# Async variant for use inside coroutines
async def report():
    await update_node_status_async("abc123", "7", "Processing...", progress=0.9)
    await update_node_status_async("abc123", "7", None)  # clear
```

--------------------------------

### update_node_status() / update_node_status_async()

Source: https://context7.com/pythongosssss/comfyui-wd14-tagger/llms.txt

Sends a status message and optional progress fraction to a specific ComfyUI node via WebSocket. Used during model downloads to show a live progress badge on the tagger node in the graph UI.

```APIDOC
## update_node_status() / update_node_status_async()

### Description
Sends a status message and optional progress fraction to a specific ComfyUI node via WebSocket. Used during model downloads to show a live progress badge on the tagger node in the graph UI.

### Method
```python
update_node_status(client_id: str | None, node: str, text: str | None, progress: float | None)
update_node_status_async(client_id: str | None, node: str, text: str | None, progress: float | None)
```

### Parameters
- **client_id** (string | None): ComfyUI websocket client ID. If None, the server's current client is used.
- **node** (string): The ID of the target node.
- **text** (string | None): The text to display on the badge. If None, the badge is cleared.
- **progress** (float | None): A float between 0.0 and 1.0 for the progress bar fill. If None, no progress bar is shown.

### Example
```python
from pysssss import update_node_status, update_node_status_async

# Synchronous — safe to call from non-async context
update_node_status(
    client_id="abc123",   # ComfyUI websocket client ID (None = use server's current client)
    node="7",             # Node ID as a string
    text="Downloading wd-v1-4-moat-tagger-v2",  # Badge label (None clears the badge)
    progress=0.45         # Float 0.0–1.0 for progress bar fill (None = no bar)
)

# Clear the status badge when done
update_node_status(client_id="abc123", node="7", text=None)

# Async variant for use inside coroutines
async def report():
    await update_node_status_async("abc123", "7", "Processing...", progress=0.9)
    await update_node_status_async("abc123", "7", None)  # clear
```
```

--------------------------------

### Register WD14 Tagger Extension in ComfyUI

Source: https://context7.com/pythongosssss/comfyui-wd14-tagger/llms.txt

This JavaScript code registers the WD14 Tagger extension with ComfyUI. It adds a right-click menu option to image nodes that calls the tagger's HTTP endpoint. The results are displayed in an alert. This code is automatically registered when ComfyUI loads.

```javascript
// Registered automatically when ComfyUI loads — no manual setup needed.
// Extension name: "pysssss.Wd14Tagger"

// Internally, the right-click handler rewrites the image view URL to call the tag endpoint:
// Before: /view?filename=foo.png&type=output&subfolder=
// After:  /pysssss/wd14tagger/tag?node=7&clientId=abc123&filename=foo.png&type=output&subfolder=

// The WD14Tagger node itself receives executed results and renders each tag string
// as a read-only multiline STRING widget on the node:
nodeType.prototype.onExecuted = function (message) {
    // message.tags = ["1girl, solo, long hair, ...", "1boy, solo, ..."]  (one per batch image)
    for (const list of message.tags) {
        const w = ComfyWidgets["STRING"](this, "tags", ["STRING", { multiline: true }], app).widget;
        w.inputEl.readOnly = true;
        w.inputEl.style.opacity = 0.6;
        w.value = list;
    }
    this.onResize?.(this.size);
};

// Progress/status badge drawn on node title during model download:
// Listens for "pysssss/update_status" WebSocket events:
// { node: "7", progress: 0.45, text: "Downloading wd-v1-4-moat-tagger-v2" }
api.addEventListener("pysssss/update_status", ({ detail }) => {
    let { node, progress, text } = detail;
    // Updates node state → triggers onDrawForeground to render progress bar badge
});
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.