Stability and documentation update v1.0.6

Improved stability when switching between Qwen3-VL GGUF models
Fixed mmproj reuse issues in local vision models
Refined internal GGUF model lifecycle management

Documentation updates:
- Clarified project scope as a prompt generator for QwenImageEdit and Wan2.2
- Reorganized Credits and Dependencies for clearer attribution
- Updated llama-cpp-python installation notes to reference the JamePeng fork documentation

Internal structure preparation for future backend refactoring
No breaking changes to node interfaces

Author: kantan-kanto

CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to ComfyUI-MultiModal-Prompt-Nodes will be documented in thi
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.6] - 2026-01-16
+
+### Fixed
+- Fixed an issue where incorrect **mmproj** could remain loaded when switching between Qwen3-VL GGUF models
+  - Properly unload and reload GGUF models when model or mmproj changes
+  - Prevent stale vision projectors from being reused across different Qwen3-VL models
+- Improved **mmproj auto-detection** logic to avoid accidentally picking mmproj files from other models
+
+### Changed
+- Refined internal GGUF model lifecycle management for better stability when switching models (e.g. 8B ↔ 4B)
+- Minor internal refactors to reduce state leakage in llama-cpp-python based vision models
+- Improved README documentation for clarity and accuracy:
+  - Clarified project scope as a **prompt generator for QwenImageEdit and Wan2.2**
+  - Reorganized Credits and Dependencies to clearly separate derived works and external dependencies
+  - Updated llama-cpp-python installation notes to reference the JamePeng fork documentation directly, avoiding incomplete or misleading installation instructions
+
+### Added
+- Added a `backends/` directory as a **structural placeholder**
+  - This directory does not change behavior in v1.0.6
+  - Reserved for future refactoring of Local GGUF and Cloud API backends without changing node interfaces
+
 ## [1.0.5] - 2026-01-13
 
 ### Removed

README.md

@@ -1,9 +1,10 @@
 # ComfyUI-MultiModal-Prompt-Nodes
 
-**Version:** 1.0.5  
+**Version:** 1.0.6  
 **License:** GPL-3.0
 
-Advanced multimodal prompt generation nodes for ComfyUI with local GGUF models (Qwen-VL) and cloud API support.
+Multimodal prompt generator nodes for ComfyUI, designed to generate prompts for **QwenImageEdit** and **Wan2.2**.  
+Supports **local LLM / local GGUF models** (Qwen3-VL, Qwen-VL) and **Qwen API** for image and video prompt generation and enhancement.
 
 ---
 
@@ -17,6 +18,13 @@ Based on extensive testing, **Wan2.2** and **Qwen-Image-Edit** respond **signifi
 ### Vision Input Compatibility
 Vision input support varies by model and llama-cpp-python version. See Installation section for detailed compatibility information. Results may vary based on your specific environment.
 
+### Local GGUF Model Stability
+Starting from **v1.0.6**, internal GGUF model handling has been improved to ensure stable behavior
+when switching between different Qwen3-VL models (e.g. 8B ↔ 4B), with mmproj files now being
+properly reloaded as part of the model switching process.
+
+These changes are internal and do **not** affect node interfaces or workflows.
+
 ---
 
 ## Features
@@ -85,10 +93,8 @@ pip install dashscope pillow numpy
 
 ***Note:** Vision input support may vary depending on your environment and configuration. In my setup, I have not been able to get vision input working with Qwen2.5-VL even with the JamePeng fork.
 
-**Recommended Installation (JamePeng fork for Qwen3-VL support):**
-```bash
-pip install llama-cpp-python==0.3.21 --break-system-packages
-```
+**Recommended Installation (JamePeng fork for Qwen3-VL support):**  
+Please follow the build and installation instructions provided in the JamePeng fork repository, as this fork requires a custom build and cannot be reliably installed via a simple `pip install`.
 
 **Source:** https://github.com/JamePeng/llama-cpp-python
 
@@ -98,6 +104,9 @@ pip install llama-cpp-python==0.3.21 --break-system-packages
 
 ⚠️ **Disclaimer:** Your results may differ depending on system configuration, GPU drivers, and other factors. If you encounter issues, please verify your environment setup and consider reporting compatibility details.
 
+**Note:** When using Qwen3-VL GGUF models, switching between different model sizes
+(e.g. 8B ↔ 4B) is supported and stable as of v1.0.6.
+
 ### 4. Place Models
 
 Place your GGUF models in `ComfyUI/models/LLM/`:
@@ -406,19 +415,36 @@ For full details, see the [LICENSE](LICENSE) file and [AUTHORS.md](AUTHORS.md).
 
 ---
 
+## Internal Structure Notes (for Advanced Users)
+
+This repository may introduce internal structural changes over time
+(e.g. extracting Local GGUF or Cloud API implementations into separate modules)
+to improve maintainability and stability.
+
+- Node interfaces (INPUT / RETURN types) are intended to remain stable
+- Internal refactors will be documented in the changelog
+- The `backends/` directory added in v1.0.6 is a **non-functional placeholder**
+  for future internal refactoring
+
+No user action is required.
+
+---
+
 ## Credits
 
-### Original Authors
+### Derived From / Inspirations
+This project is a restructured and extended ComfyUI custom node collection, derived from the following GPL-3.0 licensed projects:
+
 - **ComfyUI-QwenPromptRewriter**: [lihaoyun6](https://github.com/lihaoyun6/ComfyUI-QwenPromptRewriter) (GPL-3.0)
 - **ComfyUI-QwenVL**: [1038lab](https://github.com/1038lab/ComfyUI-QwenVL) (GPL-3.0)
 
-### Dependencies
-- **llama-cpp-python**: [Andrei Betlen](https://github.com/abetlen/llama-cpp-python)
-- **Qwen3-VL support**: [JamePeng's fork](https://github.com/JamePeng/llama-cpp-python)
-- **Qwen models**: [Alibaba Cloud Qwen Team](https://github.com/QwenLM/Qwen)
-- **Dashscope API**: Alibaba Cloud
+For detailed attribution, file-level mapping, and contribution notes, see **[AUTHORS.md](AUTHORS.md)**.
 
-For full attribution, see [AUTHORS.md](AUTHORS.md)
+### Key Dependencies / Providers
+- **llama-cpp-python**: Andrei Betlen  
+- **Qwen3-VL support**: JamePeng's llama-cpp-python fork  
+- **Qwen models**: Alibaba Cloud Qwen Team  
+- **Dashscope API**: Alibaba Cloud
 
 ---
 
@@ -446,10 +472,9 @@ Areas needing help:
 
 See [CHANGELOG.md](CHANGELOG.md) for detailed version history.
 
-### Current Version: 1.0.5
-- Device selection: CPU/GPU dropdown
-- Raw style for Vision LLM Node
-- Unified interface across all nodes
-- Extended token limit for Wan (2048)
-- API key management via api_key.txt only
-- mmproj auto-detect improvements
+### Current Version: 1.0.6
+- Improved stability when switching between Qwen3-VL GGUF models
+- Fixed mmproj reuse issues in local vision models
+- Internal structure preparation for future backend refactoring
+- Documentation updates clarifying project scope, installation notes, and attribution
+- No breaking changes to node interfaces

__init__.py

@@ -6,7 +6,7 @@
 # the Free Software Foundation, either version 3 of the License, or
 # (at your option) any later version.
 
-__version__ = "1.0.5"
+__version__ = "1.0.6"
 
 from .qwen_nodes import NODE_CLASS_MAPPINGS as qNODE_CLASS_MAPPINGS, NODE_DISPLAY_NAME_MAPPINGS as qNODE_DISPLAY_NAME_MAPPINGS
 from .wan_nodes import NODE_CLASS_MAPPINGS as wNODE_CLASS_MAPPINGS, NODE_DISPLAY_NAME_MAPPINGS as wNODE_DISPLAY_NAME_MAPPINGS

backends/.gitkeep

@@ -0,0 +1,11 @@
+# backends (placeholder)
+
+This directory is intentionally added as a **structural placeholder**.
+
+Future versions may move implementation details here, e.g.:
+
+- `local_gguf.py`: Local GGUF backend (llama-cpp-python, mmproj handling, caching)
+- `cloud_api.py`: Cloud/API backend (DashScope or other providers)
+- `messages.py`: Shared message/image preprocessing utilities
+
+**Important:** Node interfaces (ComfyUI INPUT/RETURN types) are intended to remain stable.

backends/README.md

@@ -0,0 +1,5 @@
+"""Backend package (placeholder)
+
+This package is reserved for future refactors that extract Local GGUF and Cloud API
+implementations out of node definition files, without changing node interfaces.
+"""

backends/__init__.py

@@ -0,0 +1,38 @@
+"""import_utils.py
+Small helpers to make local (same-folder) imports robust inside ComfyUI custom nodes.
+
+This module is intentionally tiny and dependency-free.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Optional
+
+
+def ensure_local_import(file_path: str, *, prepend: bool = True) -> str:
+    """Ensure the directory containing *file_path* is present in sys.path.
+
+    ComfyUI sometimes loads custom nodes in a way that does not guarantee the node
+    folder is on sys.path. Several nodes in this repo import sibling modules
+    (e.g. vision_llm_node.py). This helper makes that import reliable.
+
+    Args:
+        file_path: Usually pass __file__ from the caller module.
+        prepend: If True, insert at sys.path[0]; else append.
+
+    Returns:
+        The normalized directory path that was inserted/ensured.
+    """
+    node_dir = os.path.dirname(os.path.abspath(file_path))
+    # Normalize for stable comparisons across platforms
+    node_dir = os.path.normpath(node_dir)
+
+    if node_dir and node_dir not in sys.path:
+        if prepend:
+            sys.path.insert(0, node_dir)
+        else:
+            sys.path.append(node_dir)
+
+    return node_dir

import_utils.py

@@ -474,7 +474,11 @@ def rewrit(self, image, prompt, prompt_style, target_language, llm_model, mmproj
                 # vision_llm_node rewrite_prompt_with_gguf import
                 import sys
                 current_dir = os.path.dirname(os.path.abspath(__file__))
-                sys.path.insert(0, current_dir)
+                if current_dir not in sys.path:
+                    sys.path.insert(0, current_dir)
+                # Centralized import path handling
+                from import_utils import ensure_local_import
+                ensure_local_import(__file__)
                 from vision_llm_node import rewrite_prompt_with_gguf
 
                 # Model path retrieval