<h1 id="knx-tagger">KNX-Tagger</h1><a target="_blank" rel="ugc" href="https://discord.gg/HhBSvM9gBY"><img src="https://camo.githubusercontent.com/29b74ae259c302700bac245901fe48afcc97be4b1f9edd22e6f7b4904540151a/68747470733a2f2f696d672e736869656c64732e696f2f646973636f72642f313032343434323438333735303439303232323f6c6f676f3d646973636f7264267374796c653d666f722d7468652d626164676526636f6c6f723d353836354632" alt="Discord" /></a><span style="background-color:rgb(13, 17, 23);color:rgb(240, 246, 252);font-family:-apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, &quot;Noto Sans&quot;, Helvetica, Arial, sans-serif, &quot;Apple Color Emoji&quot;, &quot;Segoe UI Emoji&quot;;font-size:16px"> <a target="_blank" rel="ugc" href="https://ko-fi.com/duskfallcrew"><img src="https://camo.githubusercontent.com/695b32ba02a1f49376e084b594f8af9f6d14300e62d200b821a92804651d38ec/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f537570706f727425323075732532306f6e2d4b6f2d2d46692d4646354535423f7374796c653d666f722d7468652d6261646765266c6f676f3d6b6f6669" alt="Support us on Ko-fi" /></a><hr />Image tagging tool using Google's Gemini API for Stable Diffusion/Flux LoRA training.All issues/feature requests need to be handled on the Github:<a target="_blank" rel="ugc" href="https://github.com/Ktiseos-Nyx/Knx-Tagger">https://github.com/Ktiseos-Nyx/Knx-Tagger</a><h2 id="requirements">Requirements</h2><ul><li>Python 3.10+</li><li>PyQt6</li><li>Google Gemini API key (free tier available)</li><li>Supported models: <code>gemini-2.5-flash</code>, <code>gemini-2.5-pro</code>, <code>gemini-flash-latest</code></li></ul><h2 id="features">Features</h2><ul><li>Multiple Tagging Modes:<ul><li>Danbooru-style tags (comma-separated)</li><li>Natural language captions</li><li>Custom prompts with your own instructions</li></ul></li><li>Bias Modes for Focused Tagging:<ul><li>Character focus: Emphasize character details, expressions, poses</li><li>Style focus: Highlight artistic technique, composition, lighting</li><li>Realism focus: Detailed environmental and photographic elements</li><li>Environment focus: Scene context, settings, atmosphere</li></ul></li><li>Flexible Workflow:<ul><li>Test mode: Preview tags on 10 images first</li><li>Batch mode: Process entire folders</li><li>Skip already-tagged images</li><li>Tag filtering and exclusion</li><li>Activation tag prepending (for LoRA triggers)</li></ul></li><li>Kohya-Compatible Output:<ul><li><code>.txt</code> or <code>.caption</code> files alongside images</li><li>Perfect for SD/Flux training workflows</li></ul></li><li>Theme System:<ul><li>213+ pre-made themes from KNX collection</li><li>Support for qt-material, unreal-stylesheet, and custom QSS</li><li>Searchable theme selector dialog</li><li>Complete skinning documentation for creating custom themes</li><li>Guides for Krita, GIMP, Photoshop, Affinity, and Illustrator</li></ul></li><li>Cost Tracking:<ul><li>Estimates API costs before processing</li><li>Uses efficient gemini-2.5-flash model</li><li>Concurrent processing (10 workers) for speed</li></ul></li></ul><h2 id="installation">Installation</h2><h3 id="recommended:-install-as-package-(with-knx-tagger-command)">Recommended: Install as Package (with <code>knx-tagger</code> command)</h3><pre><code># Clone the repo
git clone https://github.com/Ktiseos-Nyx/Knx-Tagger.git
cd Knx-Tagger

# Install in editable mode
pip install -e .

# Now you can run from anywhere:
knx-tagger</code></pre><h3 id="alternative-1:-using-venv-(standard)">Alternative 1: Using venv (Standard)</h3><pre><code># Create virtual environment
python -m venv venv

# Activate it
# On macOS/Linux (bash/zsh):
source venv/bin/activate

# On macOS/Linux (fish shell):
source venv/bin/activate.fish

# On Windows:
venv\Scripts\activate

# Install as package
pip install -e .</code></pre><h3 id="alternative-2:-using-uv-(faster-optional)">Alternative 2: Using uv (Faster, Optional)</h3><a target="_blank" rel="ugc" href="https://github.com/astral-sh/uv">uv</a> is a blazing-fast Python package installer - totally optional but recommended if you want speed!<pre><code># Install uv (if you don't have it)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create venv and install in one go
uv venv
source .venv/bin/activate # or .venv/bin/activate.fish for fish shell
uv pip install -e .</code></pre><h3 id="get-your-api-key">Get Your API Key</h3><ol><li>Get a Gemini API key:<ul><li>Visit: <a target="_blank" rel="ugc" href="https://aistudio.google.com/app/apikey">https://aistudio.google.com/app/apikey</a></li><li>Create a free API key</li></ul></li><li>Configure API key (optional):<pre><code>cp .env.example .env
# Edit .env and add your key</code></pre>Or just enter it when prompted on first run - the app will offer to save it for you!</li></ol><h2 id="usage">Usage</h2><h3 id="if-installed-as-package:">If Installed as Package:</h3><pre><code>knx-tagger</code></pre><h3 id="or-run-directly:">Or Run Directly:</h3><pre><code>python main.py
# or
python -m knx_tagger</code></pre>Note: You may see a harmless warning like <code>ALTS creds ignored. Not running on GCP...</code> in the console - this is just Google's library noting you're not on Google Cloud Platform. It's safe to ignore; the app uses API key authentication which is working correctly.<h3 id="workflow:">Workflow:</h3><ol><li>Select folder containing images (JPEG, PNG, WebP)</li><li>Choose tagging mode:<ul><li>Danbooru: Creative, descriptive tags</li><li>Natural: Full sentence captions</li><li>Custom: Write your own prompt</li></ul></li><li>Test first: Run on 10 images, review quality</li><li>Batch process: Tag entire folder after you're satisfied</li><li>Output: <code>.txt</code> or <code>.caption</code> files alongside each image</li></ol><h2 id="themes">Themes</h2>KNX-Tagger includes 213+ pre-made themes! Access them via 🎨 Themes in the top menu.<h3 id="browsing-themes">Browsing Themes</h3><ul><li>Click 🎨 Themes to open the theme selector</li><li>Browse by category or search by name</li><li>Double-click to apply a theme instantly</li><li>Current theme is highlighted</li></ul><h3 id="creating-custom-themes">Creating Custom Themes</h3>Want to make your own Winamp-style skins? Check out the documentation:<ul><li><code>knx_tagger/themes/SKINNING_GUIDE.md</code> - Complete QSS styling reference</li><li><code>knx_tagger/themes/WIDGET_LAYOUT_REFERENCE.md</code> - Widget positions for template creation</li><li><code>knx_tagger/themes/SOFTWARE_SPECIFIC_GUIDES.md</code> - Tutorials for Krita, GIMP, Photoshop, etc.</li></ul><h3 id="theme-categories">Theme Categories</h3><ul><li>AI themes (ChatGPT, Claude, Gemini, Llama)</li><li>Retro UI (MS-DOS, Windows XP, Mac OS 9, Linux distros)</li><li>Games (Genshin Impact, Pokemon, Final Fantasy, Playstation)</li><li>Aesthetic (Vaporwave, Kawaii, Neon, Sunset gradients)</li><li>Food &amp; Brands (Taco Bell, Domino's, Coca-Cola)</li><li>Pop Culture (MLP, Deadpool, X-Men, VTubers)</li><li>And many more cursed options!</li></ul><h2 id="tips">Tips</h2><ul><li>Danbooru mode is great for inventing new tags beyond standard booru sets</li><li>Test before batch to ensure prompt quality</li><li>Skip existing prevents re-tagging already processed images</li><li>Cost estimates are approximate - actual costs may vary</li><li>Bias modes help focus on specific aspects (character, style, environment, realism)</li><li>Exclude tags can filter out unwanted terms from AI-generated tags</li><li>Some themes may look janky - they were designed for Dataset-Tools originally!</li></ul><h2 id="extending">Extending</h2>KNX-Tagger is designed to be modular:<ul><li><code>knx_tagger/core/gemini_tagger.py</code> - API integration</li><li><code>knx_tagger/utils/file_handler.py</code> - File operations</li><li><code>knx_tagger/ui/main_window.py</code> - PyQt6 interface</li></ul>Easy to integrate into larger applications or use as a library.<h2></h2><h2 id="license">License</h2>MIT

Files with SHA256: 83f5972907ba54750803f20b90e1921dc1f52174662e83c0eb4b9f72af511e51