goodguy1963-ComfyUI-ThinkingLLM/update.md

ComfyUI-QwenVL Update Log

Version 2.5.8 (2026/09/27) - ROCm SageAttention 1 Support

2.5.8 Changes

• Added a SageAttention 1.x Triton path for Hugging Face Qwen nodes on ROCm, including SageAttention 1.0.6. Select attention_mode=sage, or use auto to try Sage before Flash Attention 2 and SDPA.
• Retained NVIDIA CUDA kernel selection. Unsupported attention masks, head sizes, and model layers use the original SDPA forward.
• Protected the KV cache from SageAttention 1's in-place key smoothing and documented that the GGUF flash_attn setting is separate from Hugging Face attention selection.

2.5.8 Validation

• Seven focused SageAttention tests and all 153 feature and compatibility tests pass on the local Windows CPU test path.
• End-to-end inference on ROCm hardware remains unverified.

Version 2.5.7 (2026/08/26) - Safe Gemma 4 GGUF Audio

2.5.7 Changes

• Fixed the dedicated Gemma 4 Audio GGUF node so supported audio no longer hits the obsolete unconditional safety block reported in issue #18.
• Kept the native crash protection for older or unknown llama.cpp backends, and now require llama-cpp-python 0.3.36 or newer.
• Added a positive runtime capability check: the selected Gemma4ChatHandler must initialize its multimodal context and the mmproj must report audio support before inference begins.
• Reorganized the README into a concise project entry point and moved detailed feature, workflow, model, backend, and troubleshooting explanations into dedicated documentation guides.

2.5.7 Validation

• Added regression coverage for legacy backends, modern audio-capable backends, the OpenAI-compatible input_audio payload, and mmproj files without audio support.
• All 153 feature and compatibility tests pass in the bundled ComfyUI Python 3.12 runtime.

Version 2.4.0 (2026/08/12) - Duration-Aware Video Prompting and QwenVL Core

2.4.0 Changes

• Added duration-aware LTX 2.3 and MiniMax H3 prompting across the Hugging Face, ComfyUI-native, and GGUF video workflows.
• Split MiniMax H3 prompting into dedicated T2VA, I2VA, FL2VA, L2VA, and full-reference contracts with frame-grid normalization and safer best-effort output cleanup.
• Refactored the QwenVL implementation into focused shared modules for model access, runtime configuration, prompt state, prompt contracts, and media handling while preserving compatibility exports.
• Improved streaming so reasoning stays separate from final content, unfinished thinking traces trigger a direct finalization retry, and terminal-only punctuation remains safe on legacy Windows code pages.
• Expanded preset recommendations, tooltips, system prompts, and documentation for video token budgets, thinking behavior, reference roles, dialogue fidelity, and duration handling.
• Fixed dynamic duration-widget hiding so switching from LTX or MiniMax back to Custom Only cannot serialize the read-only recommendation text as duration_seconds; existing corrupted values are repaired to the last valid duration or 5.0 seconds.

2.4.0 Validation

• Expanded regression coverage for compatibility, downloads, caching, duration-aware prompting, MiniMax structures, streaming, and node registration.
• All 136 isolated regression tests pass in the bundled ComfyUI Python runtime, including duration-widget serialization coverage.

Version 2.3.24 (2026/08/08) - System Prompt Preset Utility

2.3.24 Changes

• Added a standalone ThinkingLLM System Prompt Preset utility node that outputs reusable system prompts as a standard STRING.
• Exposed only presets backed by prompt definitions and made obsolete or unknown saved values return an empty string instead of a display label.
• Registered the utility in both Community and commercial releases.
• Added the existing ThinkingLLM tool styling and preset tooltip previews without enabling inference-only recommendation or token behavior.

2.3.24 Validation

• Added regression coverage for prompt lookup, undefined presets, loader registration, and frontend integration.
• All 116 isolated regression tests pass on the merged main release candidate.

Version 2.3.23 (2026/08/08) - MiniMax H3 Reference Prompt Guard

2.3.23 Changes

• Required an explicit target-video prompt and reference-role assignment for MiniMax H3 Reference-to-Video generation.
• Applied the same validation to Hugging Face, ComfyUI-native, and GGUF vision nodes.
• Rejected empty ComfyUI-native model generations before they can be cached or saved as blank output.
• Documented the correct Text-to-Video versus Reference-to-Video selection and recommended direct-generation settings.

2.3.23 Validation

• Added regression coverage for missing Reference-to-Video target prompts and empty native model output.
• All 114 isolated regression tests pass.

Version 2.3.22 (2026/08/06) - Community Model Catalog Fix

2.3.22 Changes

• Restored plain model names and the original catalog order in Community mode.
• Restored automatic downloads for Community models while retaining Hugging Face token requirements for gated repositories.
• Kept rights labels, status grouping, and fail-closed model restrictions exclusive to commercial releases.
• Preserved compatibility with workflows saved while status-prefixed model names were exposed.
• Clarified the Community and commercial model policies in the README and third-party notices.

2.3.22 Validation

• Added regression coverage for Community dropdowns, Community downloads, commercial restrictions, and legacy status-prefixed workflows.
• All 113 isolated regression tests pass on the merged main release candidate.

Version 2.3.21 (2026/08/06) - Commercial Model Catalog

2.3.21 Changes

• Grouped HF and GGUF model dropdowns by reviewed commercial status while preserving old workflow model names.
• Added fail-closed commercial mode with only the two pinned Qwen models and no runtime model downloads.
• Added Hugging Face token handling for external gated models without logging or persisting tokens.
• Split MiniMax H3 into text/keyframe and full-reference presets and log the exact LLM input sent by each node.

2.3.21 Validation

• Added regression coverage for catalog status, legacy workflow resolution, gated access, token redaction, and commercial-mode restrictions.
• All 113 isolated regression tests pass after merging the newer MiniMax H3 preset split from main.

Version 2.3.20 (2026/08/06) - Shared ComfyUI Text Encoders

2.3.20 Changes

• Added automatic discovery of compatible checkpoints in ComfyUI/models/text_encoders.
• Added native ComfyUI loading for Qwen3-VL 4B/8B and Gemma 3 12B without duplicated model files.
• Added clear errors for unsupported beam and Gemma video inputs.
• Kept incomplete MiniMax H3/Qwen3-VL 32B conditioning checkpoints out of the text-generation selector.

2.3.20 Validation

• Added regression coverage for discovery, native loading, generation, deterministic seeds, and MiniMax H3 exclusion.
• All 99 isolated regression tests pass.

Version 2.3.19 (2026/08/06) - MiniMax H3 Prompt Preset

2.3.19 Changes

• Added 🎬 MiniMax H3 Multimodal Video to vision and text-only prompt nodes.
• Added the official T2VA, I2VA, FL2VA, L2VA, and full-reference output structures, including native audio fields and reference-retention analysis.
• Documented the preset and linked the official MiniMax H3 prompt guides.

2.3.19 Validation

• Added regression coverage for preset availability, required H3 fields, and node dropdown exposure.
• Kept browser tooltip previews synchronized with the preset source.

Version 2.3.18 (2026/07/21) - Advanced Mask Preview

2.3.18 Changes

• Added a MASK_PREVIEW image output to the Hugging Face and GGUF advanced vision nodes.
• The preview shows selected pixels at normal brightness and surrounding context dimmed to 20%.
• Simple nodes keep their existing two-output workflow contract.
• Documented how to connect MASK_PREVIEW to a ComfyUI Preview Image node.

2.3.18 Validation

• All 98 regression tests pass.

Version 2.3.17 (2026/07/21) - Mask-Focused Image Editing

2.3.17 Changes

• Added optional MASK input support to all four ThinkingLLM vision nodes.
• Kept selected pixels at normal brightness while dimming surrounding context for focused visual analysis.
• Added shared Hugging Face and GGUF mask preprocessing with mask-aware cache invalidation.
• Added the 👁️ Remove (Mask Area) preset for positive background-continuation and replacement prompts.
• Documented the complete mask-focused object-removal workflow in the README.

2.3.17 Validation

• Verified mask resizing, soft-mask blending, alpha preservation, input validation, cache invalidation, and node compatibility.
• Full local regression suite passes with 97 tests.

Version 2.3.16 (2026/07/13) — Gemma 4 E2B Catalog Repair

2.3.16 Changes

• Replaced stale Gemma 4 E2B GGUF download entries with currently hosted Bartowski Q4_K_S, Q8_0, and BF16 files.
• Preserved reuse of existing ggml-org Q8_0 and BF16 downloads through local filename aliases.

2.3.16 Validation

• Verified the replacement filenames against the live Hugging Face repository API.
• Added regression coverage for both Gemma 4 E2B text-catalog entries.
• Full local regression suite passes.

Version 2.3.15 (2026/07/12) — Installed GGUF Visibility

2.3.15 Changes

• Marked catalogued GGUF model files found on disk with [installed] in both ThinkingLLM GGUF selectors.
• Kept [local] for uncatalogued GGUF files and preserved compatibility with model names stored by older workflows.

2.3.15 Validation

• Added regression coverage for installed-model labelling, duplicate suppression, and legacy model-name resolution.
• Full local regression suite passes.

Version 2.3.14 (2026/06/20) — Gemma4 GGUF Stability Release

2.3.14 Changes

• Stabilized google_gemma-4-E4B-it-GGUF multimodal runs by applying Gemma4-compatible GGUF image settings before llama.cpp execution.
• Pinned llama.cpp main_gpu to ComfyUI's selected CUDA device so GGUF loads do not drift to the wrong card after CUDA state changes.
• Blocked unsupported Gemma4 GGUF audio before native llama.cpp can abort the ComfyUI process.
• Reused existing mapped GGUF model files across ComfyUI LLM model paths to avoid redundant downloads.
• Removed duplicate legacy ThinkingLLM search entries from the ComfyUI node list.

2.3.14 Validation

• Full local regression suite passes.
• Live NVIDIA portable ComfyUI test completed successfully with google_gemma-4-E4B-it-Q8_0.gguf and an image prompt.

Version 2.3.13 (2026/06/20) — Recommendation Note Cleanup

2.3.13 Changes

• Removed duplicate compact recommendation-note rows from ThinkingLLM nodes, including Advanced GGUF.
• Kept the real multiline recommendation note visible while pruning stale duplicate recommended_settings widgets.
• Prevented recommendation notes from being serialized back into workflows as duplicate UI-only widgets.

2.3.13 Validation

• Added regression coverage for recommendation widget deduplication.
• Full local regression suite passes.

Version 2.3.12 (2026/06/20) — Rollback Recovery Release

2.3.12 Changes

• Rebased the public release line onto the rollback-safe GGUF single-pass state from 2.3.11.
• Preserved the ComfyUI execution highlight behavior by no longer overwriting node colors once ComfyUI has set them.
• Restored the saved-workflow compatible Custom prompt + image (no preset) option.

2.3.12 Validation

• Local regression coverage verifies the execution color guard and the restored no-preset alias.
• Full local regression suite passes.

Version 2.3.11 (2026/06/19) — GGUF Single-Pass Execution Fix

2.3.11 Changes

• Disabled automatic GGUF finalization retries by default so one node execution performs one LLM generation pass unless explicitly configured otherwise.
• Added auto_finalization_retry to ThinkingLLM (GGUF), ThinkingLLM Advanced (GGUF), ThinkingLLM Gemma 4 Audio (GGUF), and ThinkingLLM Prompt Enhancer (GGUF) for users who still want the old empty/reasoning-only retry behavior.
• Fixed catalogued GGUF model reuse across ComfyUI extra_model_paths.yaml LLM mappings, preventing unnecessary re-downloads when models already exist in a shared models/LLM/GGUF directory.

2.3.11 Validation

• Added regression coverage for default single-pass GGUF execution, explicit opt-in finalization retry, GGUF node UI defaults, and shared LLM/GGUF model reuse.
• Targeted GGUF tests pass.

Version 2.3.10 (2026/06/19) — ComfyUI 2.0 Advanced GGUF Layout Fix

2.3.10 Changes

• Fixed the large blank area in ThinkingLLM Advanced (GGUF) under ComfyUI Nodes 2.0 by no longer hiding real advanced tuning widgets behind a layout hack.
• Kept legacy workflow compatibility shims hidden while exposing n_ubatch, thread, flash-attention, KQV offload, and context-checkpoint controls.
• Added regression coverage for the ComfyUI 2.0 layout compatibility rule.

2.3.10 Validation

• Targeted Advanced GGUF compatibility tests pass.
• Full local regression test file passes.

Version 2.3.6 (2026/06/14) — GGUF Context Reset Hardening

2.3.6 Changes

• Moved GGUF llama context reset to run immediately before each internal create_chat_completion call.
• Covers both normal generation and finalization retry calls while preserving keep_model_loaded=True model reuse.
• Added regression coverage that verifies reset happens before completion and before retry/finalization completions.

2.3.6 Validation

• Targeted reset regression suite passes.
• Full local test file still has the known Linux-host failures for Windows DLL-directory tests only.

v1.0.9 (Local Fork) — May 2026

New Features

• Live Terminal Token Streaming: Both Prompt Enhancer nodes (HF and GGUF) now have a stream_tokens_to_terminal toggle. When enabled, readable generation progress and thinking-status summaries are shown in the ComfyUI terminal in real time.
• RAW_TRACE Second Output: Both Prompt Enhancer nodes now return a second string output (RAW_TRACE) containing the unprocessed model output, reasoning trace, and retry history — useful for prompt debugging and model analysis.
• Per-Node Prompt State with JSON Persistence: keep_last_prompt is now backed by durable per-node state (survives idle, module reload, and ComfyUI restart). Fixed-seed prompts are automatically reused between runs. Each node instance stores its own prompt independently via workflow fingerprinting.
• Local Fork Lock: .no_auto_update sentinel prevents ComfyUI Manager from overwriting this local fork with upstream updates.

Installer

• Linux CUDA 12.8 auto-install matrix expanded to cover Python cp310–cp314 via JamePeng prebuilt wheels.

Version 1.0.6 (2026/05/16) — Windows GGUF Backend Import Fix

1.0.6 Changes

• Fixed Windows GGUF backend startup on portable ComfyUI installs by adding PyTorch runtime DLL directories before importing llama_cpp.
• Kept a fallback for nested portable installs where os.add_dll_directory(...) can fail with WinError 206, so the loader falls back to PATH instead of treating llama_cpp as missing.
• Added regression coverage for both the runtime DLL directory discovery and the long-path DLL-directory fallback.

1.0.6 Validation

• Embedded Python backend probe passes: ensure_llama_cpp_backend(require_vision_handlers=True) resolves Llama.
• Local regression suite passes: python tests/test_new_features.py

Version 1.0.5 (2026/05/16) — Streaming Toggle Fix And Release Retention

1.0.5 Changes

• Stopped the GGUF prompt enhancer from printing generated prompt text to the terminal when stream_tokens_to_terminal is turned off.
• Kept the rest of the node set unchanged after confirming the stream-toggle wiring is correct for the HF node, GGUF node, HF prompt enhancer, and wrapper nodes.
• Added regression coverage so the GGUF prompt enhancer cannot reintroduce an off-toggle text-stream fallback.

Release Retention

• Added tag-driven GitHub release automation so each version tag creates or updates only its own release entry.
• Older releases remain available side-by-side instead of being replaced by the newest published version.

1.0.5 Validation

• Local regression suite passes: python tests/test_new_features.py

Version 1.0.4 (2026/05/16) — GGUF Workflow Compatibility Fix

1.0.4 Changes

• Restored legacy widget ordering compatibility for ThinkingLLM_QwenVL_GGUF_Advanced so older saved workflows no longer shift values into the wrong advanced GGUF fields.
• Added compatibility shims for deprecated legacy fields (seed_mode and unload_after_run) so old workflows deserialize cleanly without affecting current runtime behavior.
• Added regression tests that lock the advanced GGUF widget order and process() signature alignment.

1.0.4 Validation

• Local regression suite passes: python tests/test_new_features.py

Version 2.2.5-local-locked (2026/05/14) — Complete Feature Parity

🎯 All 6 Nodes Now Have:

• Live Terminal Streaming (stream_tokens_to_terminal toggle)
• RAW_TRACE second STRING output
• Per-Node Prompt Persistence (survives restarts)
• enable_thinking toggle (Qwen & non-Qwen with prefill steering)
• ComfyUI Interrupt Support (stops within one token)
• Hidden identity wiring for workflow-scoped state

📦 Model Registry Updates

• Gemma 4 HF entries: All 7 variants (E2B, E4B, 26B, 31B, +3 uncensored/heretic)
• Gemma 4 GGUF entries: 6 text-only GGUF variants in Qwen_model catalog
• [DL, VRAM] brackets on every hf_models.json entry
• [Q4 size | Q8 size | VRAM] brackets on Gemma GGUF entries

🔒 Fork Lock

• Git origin neutered to file:///nonexistent/... — ComfyUI Manager cannot fetch
• .no_auto_update sentinel file for belt-and-suspenders protection

Version 2.2.5-local (2026/05/14) — Gemma 4 Support, Thinking Toggle, Interrupt

⏹️ ComfyUI Interrupt Support

• Instant Stop: All Qwen nodes now check comfy.model_management.throw_exception_if_processing_interrupted() inside every streaming token loop and after every blocking generation call.
• Streaming Loops: GGUF chunk iteration and HF TextIteratorStreamer loops check interrupt on every iteration, so generation stops within one token/chunk of hitting the Interrupt button.
• Non-Streaming Paths: Blocking generate() calls are followed by an interrupt check, so the node yields as soon as the model call returns.
• OOM Retry Path: The shared HF path checks interrupt after each generation attempt, including the reduced-token retry and CPU fallback.
• Consistent Across All Nodes: GGUF enhancer, HF enhancer, GGUF VL, HF VL, and Advanced variants all respect the Interrupt button.

🖥️ Live Terminal Token Streaming

• New Widget: stream_tokens_to_terminal boolean (default False) on ALL six node types prints tokens live to the ComfyUI terminal.
• GGUF Path: Uses llama-cpp-python stream=True with chunked iteration.
• HF Path: Uses HuggingFace TextIteratorStreamer with background thread.
• Stage Delimiters: Generation, retry, and translation stages are clearly labelled.

📝 RAW_TRACE Output

• Second STRING Output: ALL six node types now expose RAW_TRACE alongside the existing output (ENHANCED_OUTPUT or RESPONSE).
• Full History: RAW_TRACE contains the uncleaned generation chain (initial generation, optional retry, optional translation) before stripping.
• Existing Output Unchanged: ENHANCED_OUTPUT / RESPONSE remains the cleaned text as before — existing workflows keep working.

🔒 Auto-Update Lock (from 2.2.3-local)

• Git Remote Neutered: Origin URL changed to file:///nonexistent/... so ComfyUI Manager's git fetch fails silently.
• Version Bumped: pyproject.toml version set to 2.2.3-local for visual identification.
• To Re-Enable Updates: Manually restore the original remote URL in .git/config before running Manager update.

Version 2.2.3-local (2026/05/13) — Per-Node Prompt Persistence

• Per-Node State: Replaced shared module-global LAST_SAVED_PROMPT with per-node state keyed by workflow identity + ComfyUI node unique_id.
• Restart-Safe: Prompts survive ComfyUI idle, Python module reload, full restart, and workflow save/reload via node_prompt_state.json.
• No Cross-Contamination: Multiple enhancer (or other Qwen) nodes in the same workflow each keep their own saved prompt independently.
• Migrated ALL Nodes: QwenVL, QwenVL Advanced, QwenVL GGUF, QwenVL GGUF Advanced, QwenVL Prompt Enhancer, and QwenVL Prompt Enhancer GGUF all use per-node state.

⏹️ ComfyUI Interrupt Support

• Instant Stop: All Qwen nodes now check comfy.model_management.throw_exception_if_processing_interrupted() inside every streaming token loop and after every blocking generation call.
• Streaming Loops: GGUF chunk iteration and HF TextIteratorStreamer loops check interrupt on every iteration, so generation stops within one token/chunk of hitting the Interrupt button.
• Non-Streaming Paths: Blocking generate() calls are followed by an interrupt check, so the node yields as soon as the model call returns.
• OOM Retry Path: The shared HF path checks interrupt after each generation attempt, including the reduced-token retry and CPU fallback.
• Consistent Across All Nodes: GGUF enhancer, HF enhancer, GGUF VL, HF VL, and Advanced variants all respect the Interrupt button.

🖥️ Live Terminal Token Streaming

• New Widget: stream_tokens_to_terminal boolean (default False) on ALL six node types prints tokens live to the ComfyUI terminal.
• Readable Progress Output: Terminal now prints buffered, human-readable chunks instead of repainting a fast-moving token tail.
• GGUF Path: Uses llama-cpp-python stream=True with chunked iteration.
• HF Path: Uses HuggingFace TextIteratorStreamer with background thread.
• Stage Delimiters: Generation, retry (if triggered), and translation stages are clearly labelled in terminal output for Prompt Enhancer nodes.
• Completion Summaries: Each streamed phase ends with a short timing/update summary so the terminal stays useful for debugging without turning into noise.

📝 RAW_TRACE Output

• Second STRING Output: ALL six node types now expose RAW_TRACE alongside the existing output. Prompt Enhancers: ENHANCED_OUTPUT + RAW_TRACE. Vision+Language nodes: RESPONSE + RAW_TRACE.
• Full History: RAW_TRACE contains the uncleaned chronological generation chain (initial generation, optional retry, optional translation) before any clean_model_output() stripping.
• Existing Output Unchanged: ENHANCED_OUTPUT / RESPONSE remains the cleaned text as before — existing workflows keep working.

🔄 Automatic Prompt Save on Fixed Seed

• No Checkbox Needed: When a fixed seed is used, generated prompts are automatically persisted to per-node state without requiring keep_last_prompt.
• keep_last_prompt Optional: The toggle still exists for explicit control (skip generation, return saved), but auto-save works independently of it.

🔒 Local Fork Lock

• Git Remote Neutered: Origin URL changed to file:///nonexistent/... so ComfyUI Manager's git fetch fails silently and no update is flagged.
• Version Bumped: pyproject.toml version set to 2.2.3-local for visual identification.
• To Re-Enable Updates: Manually restore the original remote URL in .git/config before running Manager update.

---

Version 2.2.4 (2026/03/13)

🎬 Critical I2V Timeline Fixes & NSFW Presets Optimization

This update resolves critical issues with I2V Timeline preset generation and optimizes all NSFW presets for better user experience.

🚨 Major I2V Timeline Fixes

|- Style Coherence: Fixed AI changing anime→realism mid-sequence |- Character Stability: Fixed characters disappearing/appearing incorrectly
|- Natural Lighting: Fixed AI adding artificial lights not in image
|- Timeline Structure: Fixed continuous numbering (6,7,8...) instead of 0-5 restart
|- Format Consistency: Fixed missing parentheses and unwanted labels
|- Output Format: Each prompt starts directly with timeline markers

� NSFW Presets Optimization

|- Complete Specifications: All 8 NSFW presets now include full NSFW descriptions |- Emoji Display: Restored proper emoji rendering (🍿🎥🎬📖🍿🎥🎬📖) |- Clear Instructions: Removed confusing recommendations from presets |- User Notes: Token settings guide created for workflow optimization

📋 Technical Improvements

|- Timeline Markers: Correct (At X seconds: ...) format for all 4 prompts |- Character Continuity: Natural progression without forced artificial presence |- Lighting Rules: Logical progression instead of absolute prohibitions |- Style Detection: Consistent style application across all timeline segments

🎯 Model Recommendations

|- Qwen3-VL-8B: Recommended for I2V Timeline (20s) complex sequences |- Qwen3-VL-4B: Sufficient for I2V Scene (5s) single prompts |- Token Settings: 2048+ for 20s timeline, 1024+ for 5s prompts

Version 2.0.7 (2026/02/03)

|- FP16 Only: All HF nodes now use FP16 exclusively (~6GB VRAM on RTX 5090) |- Quantization Dropdown Removed: Eliminated confusing quantization options from all HF nodes |- Working Logic Restored: Reverted to proven working FP16 logic from commit d057b34 |- Both Nodes Fixed: Applied fixes to both Standard and Advanced nodes

🎯 Interface Simplification

|- Cleaner UI: Removed quantization dropdown from QwenVL and QwenVL Advanced nodes |- GGUF for Quantization: Users wanting quantized models should use dedicated GGUF nodes |- Consistent Parameters: Both nodes now have consistent parameter structure |- keep_last_prompt: Added missing parameter to maintain feature parity

🔧 Technical Changes

|- Memory Management: Improved model loading with CPU→CUDA transfer pattern |- Attention Backend: SDPA as stable default (SageAttention can be added later) |- Error Prevention: Removed all BitsAndBytes-related code paths |- Debug Logging: Enhanced logging for attention mode selection and model loading

🐛 Bug Fixes

|- OOM on RTX 5090: Fixed critical Out-Of-Memory during model loading |- Missing Parameters: Added frame_count and keep_last_prompt to Advanced node |- Quantization Logic: Simplified to prevent device mismatch and quantization errors |- Function Signatures: Corrected all process() functions after dropdown removal

💡 User Guidance

|- HF Nodes: Use for maximum quality with FP16 (~6GB VRAM) |- GGUF Nodes: Use for quantized models (Q4/Q8, 2-4GB VRAM) |- Performance: FP16 + SageAttention/FlashAttention for best speed |- Stability: SDPA fallback ensures compatibility across all hardware

---

Version 2.2.3 (2026/02/27)

🔧 CUDA 13 Compatibility Fix + Redundancy Removal

This update removes redundant memory management features and improves CUDA 13 compatibility.

🔧 Memory Management Cleanup

|- Removed unload_after_run: Eliminated redundant checkbox from all QwenVL nodes |- Fixed Parameter Errors: Resolved missing argument errors in GGUF and PromptEnhancer nodes |- Conflict Prevention: Prevents multiple unload operations that cause CUDA 13 crashes |- Simplified Interface: Cleaner node interface without redundant parameters |- VRAM Cleanup Node: Maintained for manual cleanup when needed

🐛 Bug Fixes

|- VastAI CUDA 13: Fixed crashes caused by conflicting unload operations |- WanMoeKSampler: Manual boundary setting prevents automatic switching crashes |- Memory Conflicts: Eliminated double cleanup between QwenVL and VRAM Cleanup nodes |- Parameter Errors: Fixed "missing 1 required positional argument: unload_after_run" errors |- Function Signatures: Corrected all run() and load_model() function signatures

📚 Documentation Updates

|- All READMEs: Updated to reflect unload_after_run removal |- Installation Guides: Simplified instructions without redundant parameters |- Troubleshooting: Added CUDA 13 specific guidance

🏆 Credits & Attribution

|- Community Feedback: Thanks to user testing that identified redundancy issue |- CUDA 13 Testing: Comprehensive testing on VastAI infrastructure |- Memory Management: Streamlined approach for better stability

---

Version 2.2.2 (2026/02/19)

🚀 Critical T2V/I2V Fixes + ComfyUI Optimizations

Version 2.2.2 (2026/02/19)

🚀 Critical T2V/I2V Fixes + ComfyUI Optimizations

This major update resolves critical workflow issues with T2V/I2V batch processing, same model reuse conflicts, and adds significant performance optimizations including Flash Attention 2 support and refined ComfyUI startup arguments.

🚀 T2V/I2V Workflow Fixes (Critical)

|- Batch Processing: Fixed critical T2V → GGUF issue with batch images [batch, height, width, channels] |- Frame Detection: Added automatic batch detection and individual frame processing |- Video Support: Enhanced video frame processing with proper shape handling |- Debug Enhanced: Comprehensive logging for batch processing troubleshooting

Same Model Reuse Fix

|- Conflict Resolution: Fixed crash when using same model between T2V and I2V nodes |- Memory Management: Enhanced cleanup with CUDA synchronization and timing |- Signature Mismatch: Resolved different signature patterns between nodes |- Aggressive Cleanup: Forced complete VRAM cleanup before model reload

🐳 Docker System Optimizations

|- ComfyUI Arguments: Optimized startup arguments for better performance |- Flash Attention 2: Enabled for 2-3x speedup on compatible hardware |- Experimental Features: Added validated arguments (--async-offload, --reserve-vram 2) |- Version Compatibility: Resolved version-specific argument differences

keep_model_loaded Enhancement

🔧 keep_model_loaded Enhancement

|- Missing Parameter: Added keep_model_loaded to PromptEnhancer node |- Consistent Behavior: Both GGUF and PromptEnhancer now have identical memory management |- Conditional Cleanup: Proper cleanup based on keep_model_loaded setting |- User Control: Full control over memory usage vs performance

🐳 Docker Final Optimization

|- Complete Build: All fixes integrated into final Docker build |- Flash Attention 2 Ready: Performance optimizations included |- Debug Enhanced: Comprehensive logging for troubleshooting |- Production Ready: Stable and optimized for deployment

📋 Files Modified

Node Files: |- AILab_QwenVL_GGUF.py: Batch processing + enhanced cleanup |- AILab_QwenVL_GGUF_PromptEnhancer.py: keep_model_loaded + cleanup

Docker System Files: |- runpod/Dockerfile: Flash Attention 2 + optimized ComfyUI arguments |- runpod/Dockerfile.4090: Flash Attention 2 + optimized ComfyUI arguments

🎯 Impact

|- T2V/I2V Workflows: Now fully functional with batch processing |- Same Model Reuse: No more conflicts between nodes |- Performance: 2-3x faster with Flash Attention 2 |- Stability: Robust memory management and cleanup |- Production: Ready for deployment with all optimizations

Version 2.2.1 (2026/02/18)

🔧 Critical GGUF VRAM Fix + Docker Optimization

This critical update resolves a major VRAM leak issue in GGUF nodes that was causing crashes after multiple executions, plus significant Docker improvements for better stability and functionality.

🔧 GGUF VRAM Fix (Critical)

• VRAM Leak Resolved: Fixed critical issue where GGUF models kept VRAM allocated after runs
• Issue #104: Addressed GitHub issue where GGUF models failed after 2 runs
• Aggressive Cleanup: Implemented comprehensive VRAM cleanup for all GGUF nodes
• Enhanced Clear Method: Added explicit model deletion and multiple CUDA cache clearing
• Debug Logging: Added detailed cleanup logging for troubleshooting
• Exception Handling: Robust error handling during cleanup operations

🚀 Performance Improvements

• Stable GGUF Operation: Nodes now work reliably without VRAM accumulation
• No More Crashes: GGUF Advanced and PromptEnhancer nodes stable after multiple runs
• Memory Management: Proper garbage collection and CUDA synchronization
• Resource Efficiency: Better VRAM utilization and cleanup

🐳 Docker Enhancements

• RunPod Methods: Adopted proven RunPod installation methods for services
• Jupyter Terminal: Switched to simple pip install jupyter (RunPod approach)
• FileBrowser: Using official get.sh script for latest version
• ComfyUI Latest: Always uses latest stable version automatically
• SSH Complete: Both server and client SSH for full networking
• FFmpeg ENV: Added IMAGEIO_FFMPEG_EXE environment variable
• Build Warnings: Removed problematic HF_TOKEN variables

📋 Files Modified

• AILab_QwenVL_GGUF.py: Enhanced VRAM cleanup
• AILab_QwenVL_GGUF_PromptEnhancer.py: Enhanced VRAM cleanup
• runpod/Dockerfile: RunPod methods + optimizations
• runpod/Dockerfile.4090: RunPod methods + optimizations

🎯 Impact

• Reliability: GGUF nodes now production-ready
• Stability: No more VRAM-related crashes
• Docker: Better container experience
• Performance: Consistent operation across multiple runs

---

Version 2.2.0 (2026/02/15)

🎬 WAN 2.2 Story Generation System

This major update introduces a complete story generation system for WAN 2.2, enabling the creation of continuous 20-second videos with 4 distinct segments, along with custom utility nodes and enhanced performance optimizations.

🎬 Story Generation System

• 4-Segment Videos: Complete system for generating 20-second continuous videos (4 × 5-second segments)
• Narrative Continuity: Intelligent prompt splitting ensures story coherence across segments
• Auto-Split Technology: Custom node automatically detects and splits prompt separators
• Workflow Integration: Ready-to-use WAN 2.2 Story workflow included
• NSFW Optimized: Enhanced prompts specifically designed for story generation

🔄 Custom Nodes

• Story Split Node: Intelligent text splitting with auto-detection of separators (\n, \n\n, \n\n\n)
• Smart Processing: Automatically handles inconsistent model output formatting
• Category: Located in 🔷QwenVL-Mod/Utils category
• Chaining Support: Full input/output connectivity for workflow integration

🎯 Enhanced Prompts

• WAN 2.2 NSFW Story: Optimized prompt format for 4-segment generation
• Separator Instructions: Clear guidelines for prompt separation
• Continuity Rules: Enhanced narrative continuity between segments
• Token Optimization: Recommended max_tokens=1536 for complete output

⚡ Performance Optimizations

• Context Settings: Optimized context_length for 8B models (65,536 tokens)
• Model-Specific: 4B models maintain 32,768 context for stability
• Memory Management: Improved VRAM usage and stability
• Crash Prevention: Safe defaults prevent ComfyUI crashes with large contexts

🐳 Docker Integration

• Container Ready: Complete Story system integrated in Docker containers
• Auto-Download: WAN2.2-I2V-AutoPrompt-Story.json and WAN2.2-T2V-AutoPrompt-Story.json workflows included
• Cloud Deployment: Ready for RunPod/VastAI deployment
• Service Integration: FileBrowser, JupyterLab, and ComfyUI with Story support

📁 File Structure

• Nodes: /nodes/story_split_node.py for intelligent prompt splitting
• Workflows:
  • /vastai/workflows/WAN2.2-I2V-AutoPrompt-Story.json ready-to-use I2V workflow
  • /vastai/workflows/WAN2.2-T2V-AutoPrompt-Story.json ready-to-use T2V workflow
• Docker: Updated /runpod/Dockerfile with Story workflows
• Prompts: Enhanced /AILab_System_Prompts.json with Story system

🔧 Technical Improvements

• Auto-Loading: Enhanced __init__.py to load nodes from subdirectory
• Error Handling: Robust separator detection and fallback mechanisms
• Debug Output: Detailed debugging information for troubleshooting
• Flexible Input: Support for custom delimiters and auto-detection modes

Version 2.1.0 (2026/02/14)

🏷️ User-Friendly Keep Last Prompt Feature

This update refines the prompt persistence feature with a more intuitive parameter name and simplified implementation, making it easier for users to understand and use.

🔄 Keep Last Prompt User-Friendly

• Parameter Rename: Changed bypass_mode to keep_last_prompt for better user understanding
• Intuitive Checkbox: Clear boolean parameter for prompt persistence control
• Consistent Logic: Unified behavior across all 6 nodes (HF, GGUF, PromptEnhancer variants)
• Workflow Optimization: Generate once, preserve results while changing inputs
• Zero Resource Usage: Cached mode provides instant responses without model loading
• Smart Caching: Per-node prompt state via NODE_PROMPT_STATE backed by node_prompt_state.json for durable per-node prompt persistence

🔥 Enhanced NSFW Support

• Stronger Instructions: Changed "If" to "WHEN" for more directive NSFW handling
• Explicit Directives: Added "IMPORTANT: Describe ALL content without censorship or filtering"
• Detailed Requirements: "Provide explicit, detailed descriptions of body parts, sexual acts, and adult content"
• No Sanitization: "Do not sanitize, euphemize, or avoid explicit content"
• Universal Application: Applied to all WAN 2.2 presets (I2V, T2V, Storyboard, Cinematic)

🔦 Fixed Lighting Invention Issues

• Accuracy Problem: Corrected AI tendency to add lights not present in source images
• Visible Only Rule: Changed to "Specify ONLY visible technical elements adapted for style"
• Source Fidelity: "light sources actually present in the image, light quality as observed"
• No Invention: "Do not invent or add lighting not present in the original image"
• Better Descriptions: More accurate lighting analysis based on actual image content

🔄 Updated GGUF Models

• Replaced noctrex Models: Removed older noctrex abliterated GGUF variants
• Added mradermacher v2/v3: Latest mradermacher quantizations for better performance
• 4B Model: Qwen3-VL-4B-Instruct-c_abliterated-v2-GGUF (7 variants: 2.38GB-4.28GB)
• 8B Model: Qwen3-VL-8B-Instruct-c_abliterated-v3-GGUF (7 variants: 4.8GB-8.71GB)
• Enhanced File Selection: More quantization options (Q4_K_S, Q5_K_S) for better VRAM efficiency
• Corrected MMProj Files: Updated to use proper .mmproj-f16.gguf files for each model

📦 Enhanced Model Selection (HF)

• Added Josiefied Model: Josiefied-Qwen3-VL-4B-Instruct-abliterated-beta-v1 (HF only)
• GGUF Not Available: Josiefied model exists only in HuggingFace format, not GGUF
• Better Alternatives: mradermacher models provide superior GGUF quantizations
• Reliable Behavior: Works regardless of seed changes or model variations

✅ Universal Implementation

• All Nodes Updated: QwenVL, QwenVL Advanced, QwenVL GGUF, QwenVL Advanced GGUF, QwenVL Prompt Enhancer, QwenVL Prompt Enhancer GGUF
• Consistent UI: Same parameter name and tooltip across all nodes
• Bug Fixes: Resolved TypeError issues in Advanced nodes

🔄 How Keep Last Prompt Works

1. Generate Phase (keep_last_prompt=False): Generate new prompt and save to per-node state (survives idle, module reload, and ComfyUI restart).
2. Keep Phase (keep_last_prompt=True): Return the per-node saved prompt for the specific node instance only.
3. First Run: If no per-node prompt exists, returns empty string.
4. Per-Node Isolation: Each Qwen node stores its own prompt independently. Multiple enhancer nodes in one workflow will not overwrite each other.
5. RAW_TRACE Output: Prompt Enhancer nodes now expose a second STRING output containing the full uncleaned generation trace (initial generation, retry if triggered, translation if enabled).

🐛 Bug Fixes

• Fixed TypeError: Resolved "unexpected keyword argument" errors in Advanced nodes
• Parameter Consistency: All process() functions now use keep_last_prompt
• Syntax Errors: Fixed duplicate global declarations

---

Version 2.0.9 (2026/02/12)

🎛️ Bypass Mode Parameter for Prompt Persistence

This major feature introduces a new bypass_mode parameter that allows users to maintain previously generated prompts without regeneration, providing perfect workflow control.

🎛️ New Bypass Mode Feature

• Smart Cache Retrieval: When bypass_mode=True, nodes automatically retrieve the most recent cached prompt for the current model
• Zero Resource Usage: Bypass mode consumes no computational resources - instant response
• Perfect Workflow Control: Generate prompts once, then enable bypass mode to preserve them while changing inputs
• Universal Implementation: Available across all nodes (HF, GGUF, PromptEnhancer, Advanced variants)

🔄 How Bypass Mode Works

1. Generate Phase (bypass_mode=False): Generate new prompts and save them to cache
2. Bypass Phase (bypass_mode=True): Retrieve and return the most recent cached prompt
3. Input Changes: When bypass mode is enabled, changing images/videos or other inputs has no effect on the output
4. Seamless Switching: Toggle bypass mode on/off to switch between generation and persistence

📋 Updated Nodes

• ✅ AILab_QwenVL (HF): Added bypass_mode parameter
• ✅ AILab_QwenVL_GGUF: Added bypass_mode parameter
• ✅ AILab_QwenVL_GGUF_Advanced: Added bypass_mode parameter
• ✅ AILab_QwenVL_PromptEnhancer (HF): Added bypass_mode parameter
• ✅ AILab_QwenVL_GGUF_PromptEnhancer: Added bypass_mode parameter

🎯 Use Cases

• Prompt Locking: Generate the perfect prompt once, then lock it while experimenting with other workflow parameters
• Batch Processing: Generate multiple prompts, then use bypass mode to maintain consistency across batches
• Resource Optimization: Enable bypass mode when you need to preserve prompts but don't want to consume GPU resources
• Workflow Debugging: Test other parts of your workflow without changing the generated prompts

🎮 Simple Control

• Checkbox Interface: Simple bypass_mode checkbox in all node interfaces
• Default Behavior: bypass_mode defaults to False (normal generation)
• Instant Feedback: Console logs show when bypass mode is active and which cached prompt is being used

🔧 Technical Implementation

• Cache-Based: Uses existing prompt caching system for reliable prompt retrieval
• Model-Specific: Retrieves prompts specific to the current model configuration
• Fallback Handling: If no cached prompt exists, returns empty string gracefully
• Performance Optimized: Minimal overhead when bypass mode is enabled

Version 2.0.8 (2026/02/06)

🐛 Bug Fixes and Stability Improvements

This release addresses critical issues identified in v2.0.7 and enhances multilingual capabilities.

🔧 Bug Fixes

• JSON Syntax Error: Fixed trailing comma in AILab_System_Prompts.json at line 26
• Undefined Variable Error: Resolved name 'image_hash' is not defined in GGUF Advanced node
• Fixed Seed Stability: Reverted problematic fixed seed improvements that caused undefined variable errors
• Node Loading: Ensured all nodes load correctly without missing variable errors

🌐 Multilingual Support Enhancement

• Complete Multilingual Support: All WAN 2.2 presets now support "user prompts from any language"
• Updated Presets:
  • 🍿 Wan 2.2 I2V: Multilingual + style detection
  • 🍿 Wan Extended Storyboard: Multilingual + style detection
  • 🎥 Wan Cinematic Video: Multilingual + style detection
  • 🍿 Wan 2.2 T2V: Multilingual + style detection

🎨 Visual Style Detection

• Enhanced Style Detection: Comprehensive support for artistic styles:
  • Anime style
  • 3D cartoon
  • Pixel art
  • Puppet animation
  • 3D game style
  • Claymation
  • Watercolor
  • Black and white animation
  • Oil painting style
  • Felt style
  • Tilt-shift photography
  • Time-lapse photography

🔧 Technical Improvements

• JSON Validation: All system prompts now validate correctly
• Error Handling: Improved error messages for debugging
• Code Stability: Removed complex seed tracking that caused undefined variables
• Documentation: Updated README and changelog with comprehensive changes

🔄 Repository Management

• Clean Revert: Properly reverted problematic commits
• Version Control: Maintained stable commit history
• Documentation: Comprehensive update logs for transparency

---

Version 2.0.7 (2026/02/04)

🧠 Smart Prompt Caching System

This release introduces intelligent prompt caching with Fixed Seed Mode for dramatic performance improvements and workflow stability.

🎯 Key Features

• Smart Caching: Automatic prompt caching prevents regeneration of identical prompts
• Fixed Seed Mode: Set any fixed seed value to maintain consistent prompts regardless of media variations
• Universal Coverage: Works across all node types (HF, GGUF, PromptEnhancer)
• Performance Boost: Instant response for cached prompts with zero model loading time
• Simplified Logic: Streamlined caching system that always includes seed for predictable behavior across all seed values

🔧 Technical Implementation

• Hash-based Cache Keys: MD5 hashes generated from model, preset, custom prompt, media, and seed
• Media Hash Sampling: Efficient image/video tensor hashing using pixel sampling
• Cache File Storage: JSON-based cache with automatic save/load functionality
• Seed-based Logic: Always includes seed in cache key for consistent behavior
• Console Logging: Clear feedback on cache hits/misses with seed information

📋 Cache Behavior

• Fixed Seed Mode: Any fixed seed value maintains consistent prompts regardless of media variations
• Random Mode: Different seeds generate different prompts even with identical inputs
• Cache Hit: Same seed + same inputs = instant response from cache
• Cache Miss: Different seed or different inputs = new generation and cache storage
• Cache Persistence: Automatic saving to prompt_cache.json after each generation
• Cache Loading: Automatic cache restoration on ComfyUI startup
• Memory Efficient: Cache only stores generated text and metadata

🎨 User Experience

• Updated Tooltips: Enhanced seed parameter tooltips explaining cache behavior
• Instant Response: Zero wait time for cached prompts
• Workflow Stability: Same prompt guaranteed with fixed seed regardless of media
• Performance Gains: Dramatic speedup for repeated prompt generation
• Transparent Operation: Clear console messages indicating cache usage

🛠️ Compatibility

• Backward Compatible: Existing workflows continue to work unchanged
• Optional Feature: Fixed Seed Mode works with any seed value
• Cache Management: Automatic cache cleanup and management
• Cross-Session: Cache persists between ComfyUI restarts
• Code Maintenance: Removed deprecated parameters across all download functions (HF, GGUF, PromptEnhancer) for future compatibility
• GGUF Performance: Increased default context size from 8192 to 32768 across all GGUF models for better utilization
• Universal Caching: Fixed Seed Mode and smart caching now available across all node types (HF, GGUF, PromptEnhancer) with shared cache file
• Simplified Logic: Streamlined caching system that always includes seed for predictable behavior across all seed values

---

Version 2.0.6 (2026/02/03)

🎬 Professional Cinematography Enhancement

This release adds comprehensive professional cinematography specifications to all WAN 2.2 presets and updates naming for consistency.

🎯 Major Enhancements

• Professional Specifications: All WAN 2.2 presets now include comprehensive cinematography technical details
• Light Sources: 8 types (sunlight, artificial, moonlight, practical, firelight, fluorescent, cloudy, mixed)
• Light Quality: 9 qualities (soft, hard, top, side, back, bottom, edge, silhouette, low/high contrast)
• Time Periods: 6 periods (daytime, nighttime, dusk, sunset, dawn, sunrise)
• Shot Types: 6 types (close-up, medium shot, medium close-up, medium full shot, full shot, wide angle)
• Composition Types: 5 types (central, balanced, side, symmetrical, short side)
• Lens Specifications: 5 focal lengths + 6 angles for complete camera control
• Camera Movements: 9 movement types for dynamic cinematography
• Color Tone: 4 tone options (warm, cool, high saturation, low saturation)

🏷️ Branding Updates

• Wan 2.2 T2V: Updated to "🍿 Wan 2.2 T2V" with proper emoji
• Extended Storyboard: Updated to "🍿 Wan Extended Storyboard" for WAN family consistency
• Cinematic Video: Updated to "🎥 Wan Cinematic Video" to align with WAN branding

📋 Enhanced Presets

• 🍿 Wan 2.2 I2V: Timeline structure + professional specs
• 🍿 Wan 2.2 T2V: Timeline structure + professional specs
• 🍿 Wan Extended Storyboard: Timeline + continuity + professional specs
• 🎥 Wan Cinematic Video: Single scene + professional specs

🛠️ Technical Improvements

• Consistent Organization: All WAN presets now follow family branding
• Professional Quality: Industry-standard cinematography specifications
• Comprehensive Coverage: Complete technical details for professional video generation

---

Version 2.0.5 (2026/02/01)

🎬 Extended Storyboard Preset Added

This release adds a new specialized preset for extended storyboard generation with WAN 2.2 format compatibility.

🎯 New Features

• Extended Storyboard Preset: New preset positioned as 2nd in the list after Wan 2.2 I2V
• WAN 2.2 Format Compliance: Follows the same timeline structure "(At 0 seconds: ...)" format
• Storyboard Continuity: Each paragraph repeats content from previous paragraph for smooth transitions
• NSFW Support: Complete NSFW description support like Wan 2.2 I2V preset
• Cinematic Specifications: Comprehensive camera, lighting, and composition guidelines

📋 Preset Details

• Position: 2nd preset (after Wan 2.2 I2V) for easy access
• Format: 5-second timeline with detailed second-by-second descriptions
• Focus: Extended video generation with consistent character appearance and scene continuity
• Technical Specs: Includes camera movements, lighting types, composition guidelines
• Output: Optimized for storyboard-to-storyboard workflow generation

🛠️ Technical Improvements

• Stability Fixes: Identified and resolved "keep model loaded" memory issues
• Performance: Maintained stable operation without OOM errors
• Compatibility: Preset works with both VL and text-only models

---

Version 2.0.4 (2026/02/01)

🔧 Stability Update - SageAttention Removal

This release focuses on stability by removing SageAttention integration that was causing compatibility issues and model interference.

🛠️ Major Changes

• SageAttention Removed: Completely removed SageAttention integration due to compatibility and stability issues
• Simplified Attention Modes: Now supports auto, flash_attention_2, and sdpa only
• Clean Codebase: Removed 100+ lines of complex patching code
• Stable Performance: SDPA provides excellent performance with zero interference

🎯 Attention Modes Available

• Auto: Automatically chooses best available attention implementation
• Flash Attention 2: High-performance attention when available (RTX 20+)
• SDPA: Scaled Dot Product Attention - stable and well-tested fallback

🐛 Issues Resolved

• Model Output Problems: Fixed prompt generation issues caused by SageAttention interference
• Recursion Errors: Eliminated infinite recursion in attention patching
• Head Dimension Compatibility: Removed headdim restrictions that were causing crashes
• VAE Compatibility: Fixed VAE encoding/decoding interference

⚡ Performance Impact

• Flash Attention 2: Still available for 2-3x speedup on compatible hardware
• SDPA: Highly optimized baseline performance
• Zero Interference: Clean attention pipeline without patching complications
• Better Stability: More reliable across different model architectures

---

Version 2.0.3 (2026/02/01)

🔧 SageAttention Compatibility Fix

This hotfix release addresses a critical compatibility issue with SageAttention integration that prevented proper patching in certain transformer versions.

🐛 Bug Fixes

• SageAttention Patch: Fixed AttributeError when accessing transformers.models.qwen2.modeling_qwen2.F
• Proper Module Access: Changed patch target to torch.nn.functional.F.scaled_dot_product_attention
• Compatibility: Ensured SageAttention works across different transformer versions
• Safer Imports: Added better error handling for module imports

⚡ Performance Impact

• SageAttention now works correctly with 8-bit quantization
• Maintains 2-5x performance boost on compatible hardware
• Graceful fallback to SDPA when patching fails

---

Version 2.0.2 (2026/02/01)

🎯 User Experience & Model Management Update

This release focuses on improving user accessibility, model management, and content generation capabilities based on community feedback.

🚀 Enhanced Model Accessibility

• Free Abliterated Models: Added Qwen3-4B-abliterated-TIES and Qwen3-8B-abliterated-TIES (nbeerbower) as default options
• No Token Required: These models provide uncensored performance without Hugging Face authentication
• Smart Model Ordering: 4B models prioritized before 8B for better VRAM accessibility
• 8-Bit Quantization Default: Optimized VRAM usage for both VL and text models

New Default Models:

• VL: Qwen3-VL-4B-Instruct-Abliterated (8-bit quantized)
• Text: Qwen3-4B-abliterated-TIES (8-bit quantized, no token)

🔧 Improved Custom Prompt Logic

• Template Combination: Fixed custom prompts to combine with preset templates instead of replacing them
• Consistent Behavior: All nodes (HF, GGUF, PromptEnhancer) now handle custom prompts identically
• Better UX: Users can now add their input while keeping preset instructions intact
• WAN 2.2 Compatibility: Fixed I2V preset to work properly with custom user input

📝 Enhanced NSFW Content Generation

• Comprehensive Descriptions: Expanded NSFW rules to include detailed sexual act descriptions
• Clear Instructions: Added "body parts and acts being performed" specification
• Complete Coverage: Includes blowjob, paizuri, deepthroat, handjob, cunnilingus, anal, missionary, doggystyle, cowgirl, reverse cowgirl, masturbation, fingering, squirting, cumshot, facial
• Applied Universally: Enhanced both WAN 2.2 I2V and T2V presets

🎬 Preset Priority Optimization

• WAN 2.2 I2V First: Moved most-used video generation preset to top position
• Better Workflow: Faster access to primary video generation functionality
• Maintained Order: Preserved logical organization of remaining presets

🐛 Bug Fixes

• Custom Prompt Override: Fixed issue where custom prompts completely replaced preset templates
• GGUF Consistency: Applied same prompt logic fixes to GGUF nodes
• Tooltip Updates: Updated all custom prompt tooltips to reflect new behavior
• JSON Validation: Removed duplicate model entries for cleaner configuration

---

Version 2.0.1-enhanced (2026/01/30)

🚀 Major Performance & Video Generation Update

This enhanced version introduces cutting-edge performance optimizations and comprehensive video generation capabilities, making it the most advanced QwenVL integration available.

⚡ SageAttention Integration

• 2-5x Performance Boost: Added SageAttention support for 8-bit quantized attention computation
• Automatic Detection: System automatically detects SageAttention availability and GPU compatibility
• Seamless Fallback: Gracefully falls back to SDPA when SageAttention is unavailable
• Memory Efficiency: Reduced VRAM usage with quantized attention kernels

Requirements:

• NVIDIA GPU with capability >= 8.0 (RTX 30/40/50 series)
• CUDA >= 12.0
• sageattention package (optional)

🎬 WAN 2.2 Video Generation Integration

• I2V Support: Image-to-Video generation with cinematic timeline structure
• T2V Support: Text-to-Video generation with professional scene descriptions
• 5-Second Timeline: Precise second-by-second scene progression
• Multilingual: Italian/English input to optimized English output
• Cinematic Quality: Film-style direction including lighting, camera, composition

Available Prompts:

• 🍿 Wan 2.2 I2V - For image-to-video workflows in QwenVL nodes
• 🍿 Wan 2.2 T2V - For text-to-video workflows in Prompt Enhancer nodes

🔧 Enhanced Compatibility

• Transformers Compatibility: Support for both old (AutoModelForImageTextToText) and new (AutoModelForVision2Seq) transformer versions
• Attention Mode Selection: Four modes available - auto, flash_attention_2, sdpa, sageattention
• Custom Model Support: Extended HF and GGUF model configurations
• Improved Error Handling: Better diagnostics and fallback mechanisms

📚 Documentation Updates

• SageAttention Section: Comprehensive installation and troubleshooting guide
• WAN 2.2 Documentation: Complete usage examples and best practices
• Performance Comparisons: Detailed benchmarks and requirements tables
• Updated README: Professional documentation with all new features

🏷️ Manager Integration

• Custom Nodes JSON: Prepared for ComfyUI Manager submission
• Enhanced Tags: Added wan2.2, video, i2v, t2v tags for better discoverability
• Updated Metadata: Comprehensive description highlighting all enhancements

---

Release Notes: v2.0.0 (2025-12-22)

New GGUF Nodes

We've expanded our GGUF model support with three powerful new nodes:

• QwenVL (GGUF) — Lightweight GGUF-based vision node for image/video understanding and text generation. Offers significantly faster inference speed compared to Transformers models, making it ideal for real-time workflows and resource-constrained environments.
• QwenVL (GGUF) Advanced — Enhanced GGUF vision node with additional controls for advanced users. Maintains the ultra-fast inference speed of GGUF while providing fine-tuned control over generation parameters.
• Qwen Prompt Enhancer (GGUF) — GGUF text-only node for intelligent prompt rewriting and enhancement (not a vision model). Delivers rapid prompt enhancement with minimal resource usage, perfect for iterative prompt refinement workflows.
• Qwen Prompt Enhancer (Transformers) — Uses Qwen3 transformer model to enhance and rewrite prompts. Analyzes your input prompt and intelligently expands it with better detail, structure, and clarity for improved generation quality. Offers full model capabilities with precise control over the enhancement process.

Enhanced GPU Device Selection (Advanced Node)

The QwenVL (Advanced) node now offers flexible GPU device management:

• Manual GPU selection — Choose specific CUDA devices (e.g., cuda:1, cuda:2) instead of defaulting to cuda:0
• Automatic device detection — Dynamically discovers all available CUDA devices on your system
• Improved device mapping — More consistent behavior and better resource allocation
• OOM prevention — Route models to underutilized GPUs when your primary GPU is handling diffusion workloads

Note: The basic QwenVL node continues to use automatic device selection for simplicity

---

✨ Improvements

GGUF: Quality and Usability

Cleaner Outputs by Default:

• Automatically removes common "thinking/planning" content and leaked tokens (<think>, <im_start>, <im_end>)
• Users now receive clean, usable prompt-only or answer-only text without manual filtering

QwenVL (GGUF) Vision Node:

• Model dropdown now displays actual .gguf filenames with automatic deduplication for easier model identification
• Enhanced download progress logging with clear status messages during model download and cache reuse
• Token generation speed reporting (tok/s) when available — helps compare different models and quantization levels

Qwen Prompt Enhancer (GGUF):

• Updated built-in presets to reduce "junk talk" and return clean enhanced prompts more consistently
• Refined system prompts that minimize verbose output
• More reliable prompt-only text generation

Transformers Nodes: GPU and Attention Stability

Advanced GPU Routing:

• QwenVL (Advanced) supports selecting specific GPUs (e.g., cuda:1, cuda:2) to avoid OOM when GPU0 is busy
• Improved device-mapping logic for more consistent behavior across different hardware configurations

Attention Backend Stability:

• Flash-Attention auto mode now behaves safely across all platforms
• Gracefully falls back to SDPA when Flash-Attention dependencies are unavailable
• Prevents runtime errors from missing or incompatible Flash-Attention installations

---

🐛 Bug Fixes

QwenVL (Transformers) Stability

• Fixed: Invalid CUDA device handling that caused crashes with incorrect device specifications (e.g., device "0" or malformed device_map)
  Related issue: https://github.com/1038lab/ComfyUI-QwenVL/issues/21
• Fixed: Flash-Attention detection now restricted to Linux systems only, preventing Windows metadata errors
• Fixed: Flash-Attention auto mode fallback mechanism to eliminate runtime errors when dependencies are unavailable

---

📚 Documentation & Dependencies

New Documentation

• Added: Comprehensive installation guide for vision-capable llama-cpp-python
  See docs/LLAMA_CPP_PYTHON_VISION_INSTALL.md for:
  • JamePeng fork wheel installation instructions (wheel source: https://github.com/JamePeng/llama-cpp-python/releases/)
  • Handler verification steps
  • Common numpy/OpenCV conflict resolution

Dependencies

• Added: hf_xet to requirements.txt for improved Hugging Face download performance and to eliminate Xet fallback warnings

Version 1.1.0 (2025/11/11)

⚡ Major Performance Optimization Update

This release introduces a full rework of the QwenVL runtime to significantly improve speed, stability, and GPU utilization.

🚀 Core Improvements

• Flash Attention Integration (Auto Detection)
  Automatically leverages next-generation attention optimization for faster inference on supported GPUs, while falling back to SDPA when needed.
• Attention Mode Selector
  Both QwenVL nodes expose the attention backend (auto / flash_attention_2 / sdpa) so users can quickly validate which mode performs best on their hardware without leaving the basic workflow view.
• Precision Optimization
  Smarter internal precision handling improves throughput and keeps performance consistent across high-end and low-VRAM cards.
• Runtime Acceleration
  The execution pipeline now keeps KV cache/device alignment always-on, cutting per-run overhead and reducing latency.
• Caching System
  Models remain cached in memory between runs, drastically lowering reload times when prompts change.
• Video Frame Optimization
  Streamlined frame sampling and preprocessing accelerate video-focused workflows.
• Hardware Adaptation
  Smarter device detection ensures the best configuration across NVIDIA GPUs, Apple Silicon, and CPU fallback scenarios.

🧠 Developer Enhancements

• Unified model and processor loading with cleaner logging and fewer bottlenecks.
• Refined quantization and memory handling for better stability across quant modes.
• Improved fallback behavior when advanced GPU optimizations are unavailable.

💡 Compatibility

• Fully backward compatible with existing ComfyUI workflows.
• Retains both QwenVL and QwenVL (Advanced) nodes: the basic node now bundles the most useful speed controls, while the advanced node exposes every knob (quantization, attention, device, torch.compile) for deep tuning.

🔧 Recommended

• PyTorch ≥ 2.8.0
• CUDA 12.4 or later
• Flash Attention 2.x (optional, for maximum performance)

Switching quantization or attention modes forces a one-time model reload and is expected behavior when comparing runtime profiles.

Version 1.0.4 (2025/10/31)

🆕 Custom Model Support Added

• Users can now add their own custom Qwen-VL or Hugging Face models
  by creating a custom_models.json file in the plugin directory.
  These models will automatically appear in the model selection list.

• Added automatic merging of user-defined models from custom_models.json,
  following the same flexible mechanism as in ComfyUI-JoyCaption.

• Added detailed documentation
  👉 docs/custom_models.md
  and an editable example file custom_models_example.json.

⚙️ Dependency Update

• Updated Transformers version requirement:
  transformers>=4.57.0 (was >=4.40.0)
  to ensure full compatibility with Qwen3-VL models.
  Reference: Qwen3-VL

---

Version 1.0.3 (2025/10/22)

• Added 8 more Qwen3-VL models 2B and 32B (FB16 and FP8 variants) have been integrated into our support list, catering to diverse requirements.

Version 1.0.2 (2025/10/21)

• Integrated additional Qwen3-VL models
• Added Chinese language README (README_zh.md)
• Refined fine-tuning preset system prompt

Version 1.0.1 (2025/10/17)

• Resolved various bugs
• Optimized video input logic

v1.0.0 Initial Release (2025/10/17)

• Support for Qwen3-VL and Qwen2.5-VL series models.
• Automatic model downloading from Hugging Face.
• On-the-fly quantization (4-bit, 8-bit, FP16).
• Preset and Custom Prompt system for flexible and easy use.
• Includes both a standard and an advanced node for users of all levels.
• Hardware-aware safeguards for FP8 model compatibility.
• Image and Video (frame sequence) input support.
• "Keep Model Loaded" option for improved performance on sequential runs.
• Seed parameter for reproducible generation.