Character Consistency Auditor

Audit character consistency across AI-generated image batches using Claude's vision API. Detect visual drift before it reaches production.

Problem

When generating character images across sessions, tools like ComfyUI, Midjourney, and Stable Diffusion often produce subtle (or not-so-subtle) deviations — hair color shifts, outfit changes, missing accessories, background mismatches. Manually comparing dozens of outputs against a reference is tedious and error-prone.

Solution

Character Consistency Auditor compares every generated image against a canonical reference on structured dimensions (face, hair, outfit, props, background, etc.) using Claude's vision model. It produces per-image drift scores, flags off-model outputs, and renders an HTML dashboard.

Features

• Structured checklist — compare on face shape, hair, eyes, outfit, props, lighting, background (customizable)
• Per-image scoring — 0.0 (identical) to 1.0 (completely different) per dimension
• HTML dashboard — visual report with color-coded drift bars
• Streamlit web app — upload reference + batch, run audit in-browser
• ComfyUI node — drop into any workflow for inline consistency checking
• JSON export — machine-readable reports for CI/CD pipelines

Installation

git clone https://github.com/darshd9941/character-consistency-auditor.git
cd character-consistency-auditor
pip install -r requirements.txt
cp .env.example .env
# Edit .env and add your ANTHROPIC_API_KEY

Usage

Standalone CLI

from auditor import audit_batch

report = audit_batch(
    reference_path="reference.png",
    generated_folder="./outputs",
    output_path="report.json",
)

from report_generator import generate_html
generate_html(report, "dashboard.html")

Streamlit Web App

streamlit run app.py

Upload a reference image and a folder of generated images through the browser UI. Download JSON and HTML reports.

ComfyUI Integration

1. Copy this repository into your ComfyUI custom_nodes/ directory:

cp -r character-consistency-auditor /path/to/ComfyUI/custom_nodes/

2. Restart ComfyUI. The Character Consistency Auditor node appears under image/analysis.

3. Inputs:

   • reference_image — the canonical character IMAGE
   • generated_image — the IMAGE to compare against
   • checklist_items — comma-separated dimensions (optional, defaults to all)
   • threshold — drift threshold for flagging (default 0.3)

4. Outputs:

   • json_report — full JSON comparison string
   • overall_drift — float score (0–1)
   • html_dashboard — rendered HTML report

Checklist Dimensions

| Dimension | What it checks | |---------------|-----------------------------------------------------| | face_shape | Facial structure, proportions, jawline | | hair_style | Cut, length, styling | | hair_color | Hue, saturation, highlights | | eye_color | Iris color, pupil shape | | skin_tone | Complexion, undertone | | outfit | Clothing items, colors, patterns | | accessories | Jewelry, glasses, hats, weapons | | props | Held items, environmental objects | | lighting | Direction, intensity, color temperature | | background | Scene, setting, color palette |

Custom checklists are supported — pass any comma-separated list of dimensions.

License

MIT — see LICENSE.