feat: add svd_niter parameter for SVD accuracy control

Feature/lora extract and version bumped to 0.2.0

.gitignore

@@ -1,3 +1,7 @@
+# Repo specific
+AGENTS.MD
+custom_nodes.examples.md
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

README.md

@@ -1,2 +1,55 @@
 # ComfyUI-ModelUtils
-[WIP]Custom nodes for handling, inspecting, modifying and creating various model files.
+
+A collection of ComfyUI custom nodes for inspecting, modifying, merging, and creating model files. Supports Models, TextEncoders, LoRAs, Checkpoints, and Embeddings.
+
+## Features
+
+- **MetaKeys** – Inspect and display metadata and tensor keys from model files
+- **RenameKeys** – Batch rename tensor keys using pattern matching
+- **PruneKeys** – Remove unwanted layers/keys from models
+- **Mergers** – Combine 2 or 3 models with configurable blend modes and ratios
+- **LoRA Extraction** – Extract LoRA adapters from model pairs using various SVD rank selection methods (Fixed, Ratio, Quantile, Knee-detection, Frobenius-norm)
+
+## Example Workflows
+
+<p align="center">
+  <img src="assets/GetMetaAndkeys.png" width="400" alt="Get Meta and Keys">
+  <br>
+  <a href="example_workflows/GetMetaAndkeys.json">📥 GetMetaAndkeys.json</a>
+</p>
+
+---
+
+<p align="center">
+  <img src="assets/LoRA_Extract_nodes.png" width="400" alt="LoRA Extraction Nodes">
+  <br>
+  <a href="example_workflows/LoRA_Extract_nodes.json">📥 LoRA_Extract_nodes.json</a>
+</p>
+
+---
+
+<p align="center">
+  <img src="assets/Merging_Examples.png" width="400" alt="Merging Examples">
+  <br>
+  <a href="example_workflows/Merging_Examples.json">📥 Merging_Examples.json</a>
+</p>
+
+---
+
+<p align="center">
+  <img src="assets/RenameKeysInModel.png" width="400" alt="Rename Keys in Model">
+  <br>
+  <a href="example_workflows/RenameKeysInModel.json">📥 RenameKeysInModel.json</a>
+</p>
+
+## Acknowledgements
+
+The LoRA extraction functionality was inspired by and references the excellent work from:
+
+- [kohya-ss/sd-scripts](https://github.com/kohya-ss/sd-scripts) – Training scripts for Stable Diffusion
+- [KohakuBlueleaf/LyCORIS](https://github.com/KohakuBlueleaf/LyCORIS) – Advanced LoRA techniques
+- [bmaltais/kohya_ss](https://github.com/bmaltais/kohya_ss) – Windows-friendly GUI for sd-scripts
+
+## License
+
+See [LICENSE](LICENSE) for details.

__init__.py

@@ -1,15 +1,62 @@
-from .nodes import *
+from typing_extensions import override
+from comfy_api.latest import ComfyExtension, io
 
-NODE_CLASS_MAPPINGS = {
-    "UNetMetaKeys": UNetMetaKeys,
-    "CLIPMetaKeys": CLIPMetaKeys,
-    "LoRAMetaKeys": LoRAMetaKeys,
-    "CheckpointMetaKeys": CheckpointMetaKeys,
-}
+from .nodes.metakeys import (
+    ModelMetaKeys, TextEncoderMetaKeys, LoRAMetaKeys,
+    CheckpointMetaKeys, EmbeddingMetaKeys
+)
+from .nodes.renamekeys import (
+    ModelRenameKeys, TextEncoderRenameKeys, LoRARenameKeys,
+    CheckpointRenameKeys, EmbeddingRenameKeys
+)
+from .nodes.prunekeys import (
+    ModelPruneKeys, TextEncoderPruneKeys, LoRAPruneKeys,
+    CheckpointPruneKeys, EmbeddingPruneKeys
+)
+from .nodes.merger import (
+    ModelTwoMerger, TextEncoderTwoMerger, LoRATwoMerger,
+    CheckpointTwoMerger, EmbeddingTwoMerger,
+    ModelThreeMerger, TextEncoderThreeMerger, LoRAThreeMerger,
+    CheckpointThreeMerger, EmbeddingThreeMerger
+)
+from .nodes.lora_extract_svd import (
+    LoRAExtractFixed, LoRAExtractRatio, LoRAExtractQuantile,
+    LoRAExtractKnee, LoRAExtractFrobenius
+)
+from .nodes.lora_resize import (
+    LoRAResizeFixed, LoRAResizeRatio,
+    LoRAResizeFrobenius, LoRAResizeCumulative
+)
+
+
+class ModelUtilsExtension(ComfyExtension):
+    @override
+    async def get_node_list(self) -> list[type[io.ComfyNode]]:
+        return [
+            # MetaKeys
+            ModelMetaKeys, TextEncoderMetaKeys, LoRAMetaKeys,
+            CheckpointMetaKeys, EmbeddingMetaKeys,
+            # RenameKeys
+            ModelRenameKeys, TextEncoderRenameKeys, LoRARenameKeys,
+            CheckpointRenameKeys, EmbeddingRenameKeys,
+            # PruneKeys
+            ModelPruneKeys, TextEncoderPruneKeys, LoRAPruneKeys,
+            CheckpointPruneKeys, EmbeddingPruneKeys,
+            # Two-Model Mergers
+            ModelTwoMerger, TextEncoderTwoMerger, LoRATwoMerger,
+            CheckpointTwoMerger, EmbeddingTwoMerger,
+            # Three-Model Mergers
+            ModelThreeMerger, TextEncoderThreeMerger, LoRAThreeMerger,
+            CheckpointThreeMerger, EmbeddingThreeMerger,
+            # LoRA Extraction
+            LoRAExtractFixed, LoRAExtractRatio, LoRAExtractQuantile,
+            LoRAExtractKnee, LoRAExtractFrobenius,
+            # LoRA Resize
+            LoRAResizeFixed, LoRAResizeRatio,
+            LoRAResizeFrobenius, LoRAResizeCumulative,
+        ]
+
+
+async def comfy_entrypoint() -> ModelUtilsExtension:
+    return ModelUtilsExtension()
 
-NODE_DISPLAY_NAME_MAPPINGS = {
-    "UNetMetaKeys": "Get UNet Metadata and Keys",
-    "CLIPMetaKeys": "Get CLIP Metadata and Keys",
-    "LoRAMetaKeys": "Get LoRA Metadata and Keys",
-    "CheckpointMetaKeys": "Get Checkpoint Metadata and Keys",
-}

docs/DEVELOPMENT.md

@@ -0,0 +1,296 @@
+# ComfyUI-ModelUtils - Complete Project History
+
+## Version Timeline
+
+| Version | Commits | Key Features |
+|---------|---------|--------------|
+| 0.1.1 | `70d6c13`-`d67cbca` | Initial nodes (MetaKeys) |
+| 0.1.2 | `6b662a4` | Icon assets |
+| 0.1.4 | `cbe3502` | Key renaming/pruning nodes |
+| 0.1.5 | `78b3198` | Model merging nodes |
+| 0.1.6 | `31989be` | Embedding nodes, namespace fixes |
+| 0.1.7 | `b6fae8d` | Mismatch handling, layer filtering, V3 migration |
+| **0.2.0** | `3df073f` | LoRA extraction, memory optimization, pinned memory |
+
+---
+
+## Phase 1: Initial Release (v0.1.1)
+
+**Commit:** `70d6c13` - "Add first nodes, toml and publish"
+
+### Files Created
+- `nodes/metakeys.py` - Get model metadata and layer keys
+- `nodes/utils.py` - Shared utilities
+- `__init__.py` - Node registration
+- `pyproject.toml` - Package configuration
+
+### Nodes
+- `ModelMetaKeys` - Get diffusion model metadata
+- `CheckpointMetaKeys` - Get checkpoint metadata
+- `TextEncoderMetaKeys` - Get text encoder metadata
+- `LoRAMetaKeys` - Get LoRA metadata
+- `EmbeddingMetaKeys` - Get embedding metadata
+
+---
+
+## Phase 2: Key Manipulation (v0.1.4)
+
+**Commit:** `4f08fe6` - "add key renaming and key pruning nodes"
+
+### Files Created
+- `nodes/renamekeys.py` - Rename tensor keys
+- `nodes/prunekeys.py` - Remove tensor keys by pattern
+
+### Nodes (5 variants each for model types)
+- `ModelRenameKeys`, `CheckpointRenameKeys`, `TextEncoderRenameKeys`, `LoRARenameKeys`, `EmbeddingRenameKeys`
+- `ModelPruneKeys`, `CheckpointPruneKeys`, `TextEncoderPruneKeys`, `LoRAPruneKeys`, `EmbeddingPruneKeys`
+
+---
+
+## Phase 3: Model Merging (v0.1.5)
+
+**Commit:** `7959370` - "Add model merging nodes"
+
+### Files Created
+- `nodes/merger.py` - Main merging logic
+- `nodes/merger_ops.py` - Merge operation modes
+- `nodes/merger_utils.py` - `MemoryEfficientSafeOpen` class
+- `docs/merger_2_model_modes.md` - Documentation
+- `docs/merger_3_model_modes.md` - Documentation
+
+### Nodes
+- `CheckpointTwoMerger`, `DiffusionModelTwoMerger`, `TextEncoderTwoMerger`, `LoRATwoMerger`
+- `CheckpointThreeMerger`, `DiffusionModelThreeMerger`, `TextEncoderThreeMerger`, `LoRAThreeMerger`
+
+### Merge Modes (TWO_MODEL_MODES)
+- Weighted Sum, Add Difference, Smooth Add Difference
+- Train Difference, Sum Twice, Triple Sum
+- Euclidean Add Difference, Distribution Crossover, Ties
+- Slerp, Lerp, SVD Supermerger, SVD LoRA Extraction
+
+### Merge Modes (THREE_MODEL_MODES)
+- Add Difference (A + (B - C) × α)
+
+### MemoryEfficientSafeOpen (initial)
+```python
+class MemoryEfficientSafeOpen:
+    def __init__(self, filename, device='cpu', mmap_mode=True)
+    def keys() -> List[str]
+    def get_tensor(key) -> Tensor
+    # mmap for zero-copy reads
+```
+
+---
+
+## Phase 4: Embedding Nodes (v0.1.6)
+
+**Commit:** `0d035ef` - "Add embedding nodes"
+
+### Additions
+- Added embedding variants to all node types
+- Namespace conflict fixes (`68f22fa`, `5ea63ab`)
+- Refactored names for universality (`232dc76`)
+
+---
+
+## Phase 5: Mismatch Handling (v0.1.7)
+
+**Commits:** `19bc047` → `de27186`
+
+### Features Added
+- `mismatch_mode` parameter: skip/zeros/error
+- Layer filtering with regex patterns
+- `exclude_patterns` - Keep model A only (no merge)
+- `discard_patterns` - Remove from output entirely
+
+### Files Modified
+- `merger.py` - Added mismatch handling logic
+- `merger_ops.py` - Added `MissingTensorBehavior` enum, `MissingTensorError`
+
+---
+
+## Phase 6: V3 API Migration (v0.1.7)
+
+**Commit:** `a3116cb` - "migrate to v3 schema and add LoRA extraction node"
+
+### Changes
+- Migrated all nodes from legacy API to `comfy_api.latest.io`
+- `io.Schema`, `io.ComfyNode`, `io.NodeOutput`
+- Added initial LoRA extraction node (diff-based)
+
+---
+
+## Phase 7: LyCORIS Extraction (pre-0.2.0)
+
+**Commits:** `92d3c55` → `18679cc`
+
+### Files Created
+- `nodes/lycoris_extract.py` - LyCORIS-based extraction
+- `nodes/lora_extract.py` - Simple diff extraction
+
+### Initial Implementation
+- Used `lycoris-lora` external dependency
+- `lycoris.utils.extract_linear`, `extract_conv`
+- Added `requirements.txt` with `lycoris-lora`
+
+### Nodes Split (`18679cc`)
+- `LyCORISExtractFixed`, `LyCORISExtractThreshold`
+- `LyCORISExtractRatio`, `LyCORISExtractQuantile`
+
+---
+
+## Phase 8: Native SVD Port (0.2.0)
+
+**Commits:** `6d7b2d1` → `eef7377`
+
+### Removed
+- `lycoris-lora` dependency
+- `lycoris_extract.py`
+- `lora_extract.py`
+
+### NEW: [lora_extract_svd.py](file:///f:/ComfyUI/custom_nodes/ComfyUI-ModelUtils/nodes/lora_extract_svd.py)
+
+**8 Rank Selection Functions:**
+```python
+_index_sv_fixed(S, dim)           # Fixed rank
+_index_sv_threshold(S, threshold) # Absolute threshold
+_index_sv_ratio(S, ratio)         # Relative to max
+_index_sv_cumulative(S, target)   # Cumulative sum %
+_index_sv_fro(S, target)          # Frobenius norm
+_index_sv_knee(S)                 # Knee detection
+_index_sv_cumulative_knee(S)      # Cumsum knee
+_index_sv_rel_decrease(S, tau)    # Ratio drop
+```
+
+**SVD Functions:**
+```python
+_svd_extract_linear_lowrank(weight, rank, device, clamp_quantile)
+_svd_extract_linear(weight, mode, mode_param, device, max_rank, clamp_quantile)
+_svd_extract_conv(weight, mode, mode_param, device, max_rank, clamp_quantile)
+_detect_fused_layer(key, shape)  # QKV/MLP detection
+_extract_chunked_layer(...)      # Chunked extraction
+```
+
+**Nodes:**
+- `LoRAExtractFixed` - Uses `svd_lowrank` (10x faster)
+- `LoRAExtractRatio` - Relative threshold
+- `LoRAExtractQuantile` - Cumulative target
+- `LoRAExtractKnee` - Auto knee detection
+- `LoRAExtractFrobenius` - Norm preservation
+
+---
+
+## Phase 9: Memory Management (0.2.0)
+
+**Commit:** `6d7b2d1` - "refactor nodes and implement memory management"
+
+### NEW: [device_utils.py](file:///f:/ComfyUI/custom_nodes/ComfyUI-ModelUtils/nodes/device_utils.py)
+
+Integrates with `comfy.model_management`:
+
+```python
+@dataclass
+class DeviceCapabilities:
+    device_type, total_vram_gb, free_vram_gb, total_ram_gb, free_ram_gb
+    cpu_cores, recommended_workers, max_tensor_size_gb
+    supports_pinned_memory, supports_async_streams
+
+get_device_capabilities(device) -> DeviceCapabilities
+estimate_model_size(path) -> float  # GB
+can_fit_in_memory(paths, device, safety_factor) -> (bool, str)
+prepare_for_large_operation(gb, device) -> bool  # Calls free_memory()
+cleanup_after_operation()  # gc.collect() + soft_empty_cache()
+get_optimal_workers(size_gb) -> int
+```
+
+### Updates to Existing Nodes
+- `metakeys.py` - Header-only reading (no tensor loading)
+- `renamekeys.py` - `MemoryEfficientSafeOpen` + memory mgmt
+- `prunekeys.py` - `MemoryEfficientSafeOpen` + memory mgmt
+- `merger.py` - Memory prep/cleanup
+
+---
+
+## Phase 10: Pinned Memory (0.2.0)
+
+**Commit:** `b770786` - "Add pinned memory for faster merging and extraction"
+
+### [merger_utils.py](file:///f:/ComfyUI/custom_nodes/ComfyUI-ModelUtils/nodes/merger_utils.py) Enhancements
+
+```python
+# Context manager
+class PinnedTensor:
+    def __enter__(self) -> Tensor  # Pins memory
+    def __exit__(...)              # Unpins
+
+# Transfer helper (2-3x faster)
+def transfer_to_gpu_pinned(tensor, device='cuda', dtype=None) -> Tensor
+
+# MemoryEfficientSafeOpen additions
+def get_tensor_to_gpu(key, device, dtype)  # Pinned transfer
+def keys_sorted_by_offset() -> List[str]   # Sequential I/O
+def get_tensors_parallel(keys, workers, sort_by_offset) -> Dict  # Parallel
+def get_tensor_as_dict(key) -> Dict        # JSON config parsing
+```
+
+---
+
+## Phase 11: SVD Optimization (0.2.0)
+
+**Commit:** `65c1ae3` - "add svd_lowrank for fixed rank extraction"
+
+### Changes
+- Added `_svd_extract_linear_lowrank()` using `torch.svd_lowrank`
+- Routes fixed mode to lowrank for **10x speedup**
+- Changed `chunk_large_layers` default to `False`
+
+---
+
+## Phase 12: Bug Fixes (0.2.0)
+
+**Commit:** `eef7377` - "Added .contiguous() to saves"
+
+### Fix
+Non-contiguous tensor error from SVD slices:
+```python
+tensor.to(dtype).cpu().contiguous()  # Added .contiguous()
+```
+
+---
+
+## Current File Structure
+
+```
+ComfyUI-ModelUtils/
+├── __init__.py
+├── pyproject.toml
+├── requirements.txt (empty - no external deps)
+├── README.md
+├── docs/
+│   ├── merger_2_model_modes.md
+│   └── merger_3_model_modes.md
+├── nodes/
+│   ├── utils.py
+│   ├── metakeys.py
+│   ├── renamekeys.py
+│   ├── prunekeys.py
+│   ├── merger.py
+│   ├── merger_ops.py
+│   ├── merger_utils.py
+│   ├── device_utils.py
+│   └── lora_extract_svd.py
+└── assets/
+    └── icon.png
+```
+
+---
+
+## Performance Summary
+
+| Feature | Improvement |
+|---------|-------------|
+| Fixed-rank SVD | **10x** (svd_lowrank) |
+| CPU→GPU transfer | **2-3x** (pinned memory) |
+| Metadata reading | **100x+** (header only) |
+| Parallel I/O | **2-4x** (ThreadPoolExecutor) |
+| Memory management | Auto-unload models before heavy ops |

docs/merger_2_model_modes.md

@@ -0,0 +1,87 @@
+# 2-Model Merger Documentation
+
+---
+
+## Weight-Sum
+> `A * (1 - α) + B * α`. A simple linear interpolation between two models.
+
+**Models Used:** A, B
+**Parameters:**
+- **Alpha:** Interpolation weight. `0.0` is 100% Model A, `1.0` is 100% Model B.
+
+---
+
+## Comparative-Interpolation
+> Interpolates between A and B based on the relative differences in their tensor values. Creates a unique blend by deciding how much of each model to use for each individual weight.
+
+**Models Used:** A, B
+**Parameters:**
+- **Alpha:** Controls the interpolation curve's strength and shape.
+- **Beta:** Switches the interpolation style. `0.0` focuses on similarity, `1.0` focuses on difference.
+- **Gamma:** Mixes between a randomized (binomial) interpolation at `0.0` and a smooth (linear) one at `1.0`.
+
+---
+
+## Power-Up (DARE)
+> Adds the unique capabilities of Model B to Model A using the Drop and Rescale (DARE) technique, which often preserves the knowledge of the base model better than simple additions.
+
+**Models Used:** A, B
+**Parameters:**
+- **Alpha:** The dropout rate. This is the proportion of unique weights from Model B that are *dropped* before merging. A higher value means less of B is merged.
+- **Beta:** A final multiplier for the rescaled difference before it's added to Model A.
+
+---
+
+## SVD LoRA Extraction
+> Extracts the difference between Model B and Model A and saves it as a new LoRA file. **This mode outputs a LoRA, not a full model.** The output file will be saved to your `loras` directory.
+
+**Models Used:** A (Tuned Model), B (Base Model)
+**Parameters:**
+- **Alpha:** The Rank (dimension) for the LoRA's standard layers.
+- **Beta:** The Rank (dimension) specifically for 3x3 convolution layers.
+- **Gamma:** The clamp quantile for weight values. `0.99` is a typical value to prevent outlier weights from dominating.
+
+---
+
+## Layer Mismatch Handling
+
+When merging models with different layer structures (e.g., fine-tuned models with added/removed layers, or LoRAs with partial layer coverage), the `mismatch_mode` parameter controls behavior:
+
+| Mode | Behavior |
+|------|----------|
+| `skip` | Missing layers in B use A's values **(default)** |
+| `zeros` | Missing layers in B are treated as zeros |
+| `error` | Fail if any layer is missing |
+
+**Common scenarios:**
+- Merging a fine-tuned model with added/removed layers
+- Combining LoRA-extracted differences with base models
+- Cross-architecture experiments
+
+**Note:** Extra layers in Model B that don't exist in Model A are currently ignored. The output will always have the same layer structure as Model A.
+
+---
+
+## Layer Filtering (Regex Patterns)
+
+Use regex patterns to control which layers are merged:
+
+### `exclude_patterns`
+Layers matching any pattern will **keep Model A's values only** (no merge).
+
+### `discard_patterns`
+Layers matching any pattern will be **removed entirely** from the output.
+
+**Pattern format:**
+- Whitespace-separated regex patterns
+- Patterns use **substring matching** (not full match)
+- Example: `text_model lora` matches any key containing "text_model" OR "lora"
+- Example: `layer\.[0-5]\.` matches layers 0-5 using regex syntax
+
+**Pattern Examples:**
+| Pattern | Matches |
+|---------|---------|
+| `text_model` | All text encoder layers |
+| `\.norm` | All normalization layers |
+| `attn\.(q\|k\|v)` | Query, key, value attention weights |
+| `block\.[0-9]\.` | Blocks 0-9 |

docs/merger_3_model_modes.md

@@ -0,0 +1,83 @@
+# 3-Model Merger Documentation
+
+---
+
+## Add-Difference
+> `A + (B - C) * α`. This classic technique applies the "difference" between models B and C to model A. For example, it can be used to add a style (B) to a base model (A) while subtracting the style's original base (C).
+
+**Models Used:** A, B, C
+**Parameters:**
+- **Alpha:** A multiplier for the `(B - C)` difference vector before it's added to A.
+- **Beta:** A smoothing toggle. `0` for Off, `1` for On. When On, applies a median and gaussian filter to the difference, which can result in a smoother merge.
+
+---
+
+## Train-Difference
+> A variation of Add-Difference from the SuperMerger extension that uses a more complex scaling factor based on the relative distances between the tensors of A, B, and C.
+
+**Models Used:** A, B, C
+**Parameters:**
+- **Alpha:** A multiplier for the final calculated "training" difference.
+
+---
+
+## Extract-Features
+> A powerful mode that identifies features present in both `(B - A)` and `(C - A)` and adds them to A. Allows for fine-grained control over combining aspects based on their similarity.
+
+**Models Used:** A, B, C
+**Parameters:**
+- **Alpha:** Weights the merge between Model B (`0.0`) and Model C (`1.0`).
+- **Beta:** Controls the focus on similarity (`0.0`) versus dissimilarity (`1.0`).
+- **Gamma:** A bias exponent for similarity. Higher values increase the bias.
+- **Delta:** A final multiplier for the extracted features before they are added to Model A.
+
+---
+
+## Add-Dissimilarities
+> Identifies features that are dissimilar between Model B and Model C and adds them to Model A. Useful for combining unique aspects of two different models.
+
+**Models Used:** A, B, C
+**Parameters:**
+- **Alpha:** Weights the comparison between Model B (`0.0`) and Model C (`1.0`).
+- **Beta:** A multiplier for the final extracted dissimilar features.
+- **Gamma:** A bias exponent for the similarity calculation.
+
+---
+
+## Layer Mismatch Handling
+
+When merging models with different layer structures, the `mismatch_mode` parameter controls behavior:
+
+| Mode | Behavior |
+|------|----------|
+| `skip` | Missing layers in B/C use A's values **(default)** |
+| `zeros` | Missing layers in B/C are treated as zeros |
+| `error` | Fail if any layer is missing |
+
+**Special case for B - C subtraction (Add-Difference, Train-Difference):**
+- If **both** B and C have the layer: Normal subtraction is performed
+- If **either** B or C is missing the layer: The difference is treated as `None` (no contribution from this layer), and Model A's value is used
+
+**Common scenarios:**
+- Merging a fine-tuned model with added/removed layers
+- Extracting style differences between models with slightly different architectures
+- Combining partial LoRAs or adapters
+
+**Note:** Extra layers in Models B/C that don't exist in Model A are currently ignored. The output will always have the same layer structure as Model A.
+
+---
+
+## Layer Filtering (Regex Patterns)
+
+Use regex patterns to control which layers are merged:
+
+### `exclude_patterns`
+Layers matching any pattern will **keep Model A's values only** (no merge).
+
+### `discard_patterns`
+Layers matching any pattern will be **removed entirely** from the output.
+
+**Pattern format:**
+- Whitespace-separated regex patterns
+- Patterns use **substring matching** (not full match)
+- Example: `text_model lora` matches any key containing "text_model" OR "lora"

example_workflows/GetMetaAndkeys.json

@@ -0,0 +1,600 @@
+{
+  "id": "e07ecc9b-30b9-45e4-9ed6-5fbb7e510257",
+  "revision": 0,
+  "last_node_id": 31,
+  "last_link_id": 19,
+  "nodes": [
+    {
+      "id": 16,
+      "type": "PreviewAny",
+      "pos": [
+        -3608,
+        200
+      ],
+      "size": [
+        832,
+        232
+      ],
+      "flags": {},
+      "order": 7,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "source",
+          "type": "*",
+          "link": 18
+        }
+      ],
+      "outputs": [],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfy-core",
+        "ver": "0.7.0",
+        "Node name for S&R": "PreviewAny"
+      },
+      "widgets_values": [
+        null,
+        null,
+        true
+      ]
+    },
+    {
+      "id": 17,
+      "type": "ModelMetaKeys",
+      "pos": [
+        -2800,
+        504
+      ],
+      "size": [
+        346.253515625,
+        78
+      ],
+      "flags": {},
+      "order": 2,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "metadata",
+          "type": "STRING",
+          "links": [
+            13
+          ]
+        },
+        {
+          "name": "keys",
+          "type": "STRING",
+          "links": [
+            17
+          ]
+        }
+      ],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfyui_modelutils",
+        "ver": "eef737706127fe4a2c28172ab706e92318e0dc60",
+        "Node name for S&R": "ModelMetaKeys"
+      },
+      "widgets_values": [
+        "flux2-dev.safetensors"
+      ]
+    },
+    {
+      "id": 18,
+      "type": "TextEncoderMetaKeys",
+      "pos": [
+        -3176,
+        680
+      ],
+      "size": [
+        329.4234375,
+        78
+      ],
+      "flags": {},
+      "order": 3,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "metadata",
+          "type": "STRING",
+          "links": [
+            15
+          ]
+        },
+        {
+          "name": "keys",
+          "type": "STRING",
+          "links": [
+            16
+          ]
+        }
+      ],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfyui_modelutils",
+        "ver": "eef737706127fe4a2c28172ab706e92318e0dc60",
+        "Node name for S&R": "TextEncoderMetaKeys"
+      },
+      "widgets_values": [
+        "clip_l.safetensors"
+      ]
+    },
+    {
+      "id": 19,
+      "type": "CheckpointMetaKeys",
+      "pos": [
+        -3168,
+        512
+      ],
+      "size": [
+        317.6724609375,
+        78
+      ],
+      "flags": {},
+      "order": 1,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "metadata",
+          "type": "STRING",
+          "links": [
+            12
+          ]
+        },
+        {
+          "name": "keys",
+          "type": "STRING",
+          "links": [
+            18
+          ]
+        }
+      ],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfyui_modelutils",
+        "ver": "eef737706127fe4a2c28172ab706e92318e0dc60",
+        "Node name for S&R": "CheckpointMetaKeys"
+      },
+      "widgets_values": [
+        "unsorted\\v1-5-pruned-emaonly.safetensors"
+      ]
+    },
+    {
+      "id": 21,
+      "type": "LoRAMetaKeys",
+      "pos": [
+        -2800,
+        680
+      ],
+      "size": [
+        277.0943359375,
+        78
+      ],
+      "flags": {},
+      "order": 0,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "metadata",
+          "type": "STRING",
+          "links": [
+            14
+          ]
+        },
+        {
+          "name": "keys",
+          "type": "STRING",
+          "links": [
+            19
+          ]
+        }
+      ],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfyui_modelutils",
+        "ver": "eef737706127fe4a2c28172ab706e92318e0dc60",
+        "Node name for S&R": "LoRAMetaKeys"
+      },
+      "widgets_values": [
+        "Chroma\\FlatAnimeStyle_Chroma.safetensors"
+      ]
+    },
+    {
+      "id": 24,
+      "type": "PreviewAny",
+      "pos": [
+        -2728,
+        216
+      ],
+      "size": [
+        512,
+        200
+      ],
+      "flags": {},
+      "order": 9,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "source",
+          "type": "*",
+          "link": 17
+        }
+      ],
+      "outputs": [],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfy-core",
+        "ver": "0.7.0",
+        "Node name for S&R": "PreviewAny"
+      },
+      "widgets_values": [
+        null,
+        null,
+        true
+      ]
+    },
+    {
+      "id": 25,
+      "type": "PreviewAny",
+      "pos": [
+        -2816,
+        832
+      ],
+      "size": [
+        736,
+        248
+      ],
+      "flags": {},
+      "order": 5,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "source",
+          "type": "*",
+          "link": 19
+        }
+      ],
+      "outputs": [],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfy-core",
+        "ver": "0.7.0",
+        "Node name for S&R": "PreviewAny"
+      },
+      "widgets_values": [
+        null,
+        null,
+        true
+      ]
+    },
+    {
+      "id": 27,
+      "type": "PreviewAny",
+      "pos": [
+        -3496,
+        848
+      ],
+      "size": [
+        632,
+        224
+      ],
+      "flags": {},
+      "order": 11,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "source",
+          "type": "*",
+          "link": 16
+        }
+      ],
+      "outputs": [],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfy-core",
+        "ver": "0.7.0",
+        "Node name for S&R": "PreviewAny"
+      },
+      "widgets_values": [
+        null,
+        null,
+        true
+      ]
+    },
+    {
+      "id": 28,
+      "type": "PreviewAny",
+      "pos": [
+        -3600,
+        664
+      ],
+      "size": [
+        352,
+        136
+      ],
+      "flags": {},
+      "order": 10,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "source",
+          "type": "*",
+          "link": 15
+        }
+      ],
+      "outputs": [],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfy-core",
+        "ver": "0.7.0",
+        "Node name for S&R": "PreviewAny"
+      },
+      "widgets_values": [
+        null,
+        null,
+        true
+      ]
+    },
+    {
+      "id": 29,
+      "type": "PreviewAny",
+      "pos": [
+        -2408,
+        648
+      ],
+      "size": [
+        360,
+        120
+      ],
+      "flags": {},
+      "order": 4,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "source",
+          "type": "*",
+          "link": 14
+        }
+      ],
+      "outputs": [],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfy-core",
+        "ver": "0.7.0",
+        "Node name for S&R": "PreviewAny"
+      },
+      "widgets_values": [
+        null,
+        null,
+        true
+      ]
+    },
+    {
+      "id": 30,
+      "type": "PreviewAny",
+      "pos": [
+        -3576,
+        480
+      ],
+      "size": [
+        336,
+        128
+      ],
+      "flags": {},
+      "order": 6,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "source",
+          "type": "*",
+          "link": 12
+        }
+      ],
+      "outputs": [],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfy-core",
+        "ver": "0.7.0",
+        "Node name for S&R": "PreviewAny"
+      },
+      "widgets_values": [
+        null,
+        null,
+        true
+      ]
+    },
+    {
+      "id": 31,
+      "type": "PreviewAny",
+      "pos": [
+        -2368,
+        472
+      ],
+      "size": [
+        328,
+        120
+      ],
+      "flags": {},
+      "order": 8,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "source",
+          "type": "*",
+          "link": 13
+        }
+      ],
+      "outputs": [],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfy-core",
+        "ver": "0.7.0",
+        "Node name for S&R": "PreviewAny"
+      },
+      "widgets_values": [
+        null,
+        null,
+        true
+      ]
+    }
+  ],
+  "links": [
+    [
+      12,
+      19,
+      0,
+      30,
+      0,
+      "STRING"
+    ],
+    [
+      13,
+      17,
+      0,
+      31,
+      0,
+      "STRING"
+    ],
+    [
+      14,
+      21,
+      0,
+      29,
+      0,
+      "STRING"
+    ],
+    [
+      15,
+      18,
+      0,
+      28,
+      0,
+      "STRING"
+    ],
+    [
+      16,
+      18,
+      1,
+      27,
+      0,
+      "STRING"
+    ],
+    [
+      17,
+      17,
+      1,
+      24,
+      0,
+      "STRING"
+    ],
+    [
+      18,
+      19,
+      1,
+      16,
+      0,
+      "STRING"
+    ],
+    [
+      19,
+      21,
+      1,
+      25,
+      0,
+      "STRING"
+    ]
+  ],
+  "groups": [],
+  "config": {},
+  "extra": {
+    "workflowRendererVersion": "LG",
+    "ds": {
+      "scale": 0.9070294784580497,
+      "offset": [
+        3855.323424397858,
+        -56.106573378634465
+      ]
+    },
+    "frontendVersion": "1.37.2",
+    "VHS_latentpreview": false,
+    "VHS_latentpreviewrate": 0,
+    "VHS_MetadataImage": true,
+    "VHS_KeepIntermediate": true
+  },
+  "version": 0.4
+}

example_workflows/LoRA_Extract_nodes.json

@@ -0,0 +1,522 @@
+{
+  "id": "e07ecc9b-30b9-45e4-9ed6-5fbb7e510257",
+  "revision": 0,
+  "last_node_id": 10,
+  "last_link_id": 5,
+  "nodes": [
+    {
+      "id": 1,
+      "type": "LoRAExtractFixed",
+      "pos": [
+        -1848,
+        16
+      ],
+      "size": [
+        296,
+        352
+      ],
+      "flags": {},
+      "order": 2,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "output_path",
+          "type": "STRING",
+          "links": [
+            3
+          ]
+        }
+      ],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfyui_modelutils",
+        "ver": "eef737706127fe4a2c28172ab706e92318e0dc60",
+        "Node name for S&R": "LoRAExtractFixed"
+      },
+      "widgets_values": [
+        "13499-bf16.safetensors",
+        "13499-bf16.safetensors",
+        64,
+        32,
+        false,
+        0.99,
+        0,
+        "skip",
+        "extracted_lora",
+        "fp16",
+        "cuda",
+        ""
+      ]
+    },
+    {
+      "id": 2,
+      "type": "LoRAExtractFrobenius",
+      "pos": [
+        -2432,
+        24
+      ],
+      "size": [
+        296,
+        352
+      ],
+      "flags": {},
+      "order": 0,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "output_path",
+          "type": "STRING",
+          "links": [
+            1
+          ]
+        }
+      ],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfyui_modelutils",
+        "ver": "eef737706127fe4a2c28172ab706e92318e0dc60",
+        "Node name for S&R": "LoRAExtractFrobenius"
+      },
+      "widgets_values": [
+        "13499-bf16.safetensors",
+        "13499-bf16.safetensors",
+        0.9,
+        0.9,
+        false,
+        0.99,
+        0,
+        "skip",
+        "extracted_lora",
+        "fp16",
+        "cuda",
+        ""
+      ]
+    },
+    {
+      "id": 3,
+      "type": "LoRAExtractKnee",
+      "pos": [
+        -2416,
+        440
+      ],
+      "size": [
+        280,
+        328
+      ],
+      "flags": {},
+      "order": 1,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "output_path",
+          "type": "STRING",
+          "links": [
+            2
+          ]
+        }
+      ],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfyui_modelutils",
+        "ver": "eef737706127fe4a2c28172ab706e92318e0dc60",
+        "Node name for S&R": "LoRAExtractKnee"
+      },
+      "widgets_values": [
+        "13499-bf16.safetensors",
+        "13499-bf16.safetensors",
+        "sv_knee",
+        false,
+        0.99,
+        0,
+        "skip",
+        "extracted_lora",
+        "fp16",
+        "cuda",
+        ""
+      ]
+    },
+    {
+      "id": 4,
+      "type": "LoRAExtractQuantile",
+      "pos": [
+        -1248,
+        128
+      ],
+      "size": [
+        288,
+        352
+      ],
+      "flags": {},
+      "order": 4,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "output_path",
+          "type": "STRING",
+          "links": [
+            5
+          ]
+        }
+      ],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfyui_modelutils",
+        "ver": "eef737706127fe4a2c28172ab706e92318e0dc60",
+        "Node name for S&R": "LoRAExtractQuantile"
+      },
+      "widgets_values": [
+        "13499-bf16.safetensors",
+        "13499-bf16.safetensors",
+        0.9,
+        0.9,
+        false,
+        0.99,
+        0,
+        "skip",
+        "extracted_lora",
+        "fp16",
+        "cuda",
+        ""
+      ]
+    },
+    {
+      "id": 5,
+      "type": "LoRAExtractRatio",
+      "pos": [
+        -1824,
+        424
+      ],
+      "size": [
+        296,
+        352
+      ],
+      "flags": {},
+      "order": 3,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "output_path",
+          "type": "STRING",
+          "links": [
+            4
+          ]
+        }
+      ],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfyui_modelutils",
+        "ver": "eef737706127fe4a2c28172ab706e92318e0dc60",
+        "Node name for S&R": "LoRAExtractRatio"
+      },
+      "widgets_values": [
+        "13499-bf16.safetensors",
+        "13499-bf16.safetensors",
+        0.5,
+        0.5,
+        false,
+        0.99,
+        0,
+        "skip",
+        "extracted_lora",
+        "fp16",
+        "cuda",
+        ""
+      ]
+    },
+    {
+      "id": 6,
+      "type": "PreviewAny",
+      "pos": [
+        -2096,
+        136
+      ],
+      "size": [
+        210,
+        168
+      ],
+      "flags": {},
+      "order": 5,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "source",
+          "type": "*",
+          "link": 1
+        }
+      ],
+      "outputs": [],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfy-core",
+        "ver": "0.7.0",
+        "Node name for S&R": "PreviewAny"
+      },
+      "widgets_values": [
+        null,
+        null,
+        true
+      ]
+    },
+    {
+      "id": 7,
+      "type": "PreviewAny",
+      "pos": [
+        -2096,
+        448
+      ],
+      "size": [
+        210,
+        168
+      ],
+      "flags": {},
+      "order": 6,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "source",
+          "type": "*",
+          "link": 2
+        }
+      ],
+      "outputs": [],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfy-core",
+        "ver": "0.7.0",
+        "Node name for S&R": "PreviewAny"
+      },
+      "widgets_values": [
+        null,
+        null,
+        true
+      ]
+    },
+    {
+      "id": 8,
+      "type": "PreviewAny",
+      "pos": [
+        -1504,
+        96
+      ],
+      "size": [
+        210,
+        168
+      ],
+      "flags": {},
+      "order": 7,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "source",
+          "type": "*",
+          "link": 3
+        }
+      ],
+      "outputs": [],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfy-core",
+        "ver": "0.7.0",
+        "Node name for S&R": "PreviewAny"
+      },
+      "widgets_values": [
+        null,
+        null,
+        true
+      ]
+    },
+    {
+      "id": 9,
+      "type": "PreviewAny",
+      "pos": [
+        -1472,
+        432
+      ],
+      "size": [
+        210,
+        168
+      ],
+      "flags": {},
+      "order": 8,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "source",
+          "type": "*",
+          "link": 4
+        }
+      ],
+      "outputs": [],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfy-core",
+        "ver": "0.7.0",
+        "Node name for S&R": "PreviewAny"
+      },
+      "widgets_values": [
+        null,
+        null,
+        true
+      ]
+    },
+    {
+      "id": 10,
+      "type": "PreviewAny",
+      "pos": [
+        -904,
+        184
+      ],
+      "size": [
+        210,
+        168
+      ],
+      "flags": {},
+      "order": 9,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "source",
+          "type": "*",
+          "link": 5
+        }
+      ],
+      "outputs": [],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfy-core",
+        "ver": "0.7.0",
+        "Node name for S&R": "PreviewAny"
+      },
+      "widgets_values": [
+        null,
+        null,
+        true
+      ]
+    }
+  ],
+  "links": [
+    [
+      1,
+      2,
+      0,
+      6,
+      0,
+      "STRING"
+    ],
+    [
+      2,
+      3,
+      0,
+      7,
+      0,
+      "STRING"
+    ],
+    [
+      3,
+      1,
+      0,
+      8,
+      0,
+      "STRING"
+    ],
+    [
+      4,
+      5,
+      0,
+      9,
+      0,
+      "STRING"
+    ],
+    [
+      5,
+      4,
+      0,
+      10,
+      0,
+      "STRING"
+    ]
+  ],
+  "groups": [],
+  "config": {},
+  "extra": {
+    "workflowRendererVersion": "LG",
+    "ds": {
+      "scale": 1.05,
+      "offset": [
+        2532,
+        84
+      ]
+    },
+    "frontendVersion": "1.37.2",
+    "VHS_latentpreview": false,
+    "VHS_latentpreviewrate": 0,
+    "VHS_MetadataImage": true,
+    "VHS_KeepIntermediate": true
+  },
+  "version": 0.4
+}

example_workflows/Merging_Examples.json

@@ -0,0 +1,460 @@
+{
+  "id": "e07ecc9b-30b9-45e4-9ed6-5fbb7e510257",
+  "revision": 0,
+  "last_node_id": 16,
+  "last_link_id": 11,
+  "nodes": [
+    {
+      "id": 6,
+      "type": "PreviewAny",
+      "pos": [
+        -3552,
+        136
+      ],
+      "size": [
+        336,
+        160
+      ],
+      "flags": {},
+      "order": 5,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "source",
+          "type": "*",
+          "link": 6
+        }
+      ],
+      "outputs": [],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfy-core",
+        "ver": "0.7.0",
+        "Node name for S&R": "PreviewAny"
+      },
+      "widgets_values": [
+        null,
+        null,
+        true
+      ]
+    },
+    {
+      "id": 7,
+      "type": "PreviewAny",
+      "pos": [
+        -2792,
+        144
+      ],
+      "size": [
+        456,
+        464
+      ],
+      "flags": {},
+      "order": 6,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "source",
+          "type": "*",
+          "link": 9
+        }
+      ],
+      "outputs": [],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfy-core",
+        "ver": "0.7.0",
+        "Node name for S&R": "PreviewAny"
+      },
+      "widgets_values": [
+        null,
+        null,
+        false
+      ]
+    },
+    {
+      "id": 11,
+      "type": "ModelThreeMerger",
+      "pos": [
+        -3120,
+        112
+      ],
+      "size": [
+        296,
+        522
+      ],
+      "flags": {},
+      "order": 2,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "output_filename",
+          "type": "STRING",
+          "links": null
+        },
+        {
+          "name": "documentation",
+          "type": "STRING",
+          "links": [
+            9
+          ]
+        }
+      ],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfyui_modelutils",
+        "ver": "eef737706127fe4a2c28172ab706e92318e0dc60",
+        "Node name for S&R": "ModelThreeMerger"
+      },
+      "widgets_values": [
+        "DOCUMENTATION ONLY",
+        "Chroma1-HD.safetensors",
+        "Chroma-DC-2K.safetensors",
+        "None",
+        "Add-Difference",
+        "skip",
+        0.5,
+        0.5,
+        0.5,
+        0.5,
+        996811747788113,
+        "randomize",
+        "merged_3_model",
+        "fp32",
+        "cuda",
+        "",
+        ""
+      ]
+    },
+    {
+      "id": 12,
+      "type": "ModelTwoMerger",
+      "pos": [
+        -3120,
+        704
+      ],
+      "size": [
+        304,
+        474
+      ],
+      "flags": {},
+      "order": 0,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "output_filename",
+          "type": "STRING",
+          "links": [
+            11
+          ]
+        },
+        {
+          "name": "documentation",
+          "type": "STRING",
+          "links": null
+        }
+      ],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfyui_modelutils",
+        "ver": "eef737706127fe4a2c28172ab706e92318e0dc60",
+        "Node name for S&R": "ModelTwoMerger"
+      },
+      "widgets_values": [
+        "MERGE",
+        "None",
+        "None",
+        "Weight-Sum",
+        "skip",
+        0.5,
+        0.5,
+        0.99,
+        388546580517523,
+        "randomize",
+        "merged_2_model",
+        "fp32",
+        "cuda",
+        "",
+        ""
+      ]
+    },
+    {
+      "id": 13,
+      "type": "LoRAThreeMerger",
+      "pos": [
+        -3872,
+        128
+      ],
+      "size": [
+        296,
+        522
+      ],
+      "flags": {},
+      "order": 1,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "output_filename",
+          "type": "STRING",
+          "links": [
+            6
+          ]
+        },
+        {
+          "name": "documentation",
+          "type": "STRING",
+          "links": []
+        }
+      ],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfyui_modelutils",
+        "ver": "eef737706127fe4a2c28172ab706e92318e0dc60",
+        "Node name for S&R": "LoRAThreeMerger"
+      },
+      "widgets_values": [
+        "MERGE",
+        "None",
+        "None",
+        "None",
+        "Add-Difference",
+        "skip",
+        0.5,
+        0.5,
+        0.5,
+        0.5,
+        1120102695669269,
+        "randomize",
+        "merged_3_lora",
+        "fp32",
+        "cuda",
+        "",
+        ""
+      ]
+    },
+    {
+      "id": 14,
+      "type": "LoRATwoMerger",
+      "pos": [
+        -3872,
+        720
+      ],
+      "size": [
+        296,
+        474
+      ],
+      "flags": {},
+      "order": 3,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "output_filename",
+          "type": "STRING",
+          "links": []
+        },
+        {
+          "name": "documentation",
+          "type": "STRING",
+          "links": [
+            10
+          ]
+        }
+      ],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfyui_modelutils",
+        "ver": "eef737706127fe4a2c28172ab706e92318e0dc60",
+        "Node name for S&R": "LoRATwoMerger"
+      },
+      "widgets_values": [
+        "DOCUMENTATION ONLY",
+        "Hyper-FLUX.1-dev-16steps-lora-rescale_z1.safetensors",
+        "Hyper-FLUX.1-dev-16steps-lora-rescale_z2.safetensors",
+        "Weight-Sum",
+        "skip",
+        0.5,
+        0.5,
+        0.99,
+        1020143314396572,
+        "randomize",
+        "merged_2_lora",
+        "fp32",
+        "cuda",
+        "",
+        ""
+      ]
+    },
+    {
+      "id": 15,
+      "type": "PreviewAny",
+      "pos": [
+        -2768,
+        720
+      ],
+      "size": [
+        432,
+        160
+      ],
+      "flags": {},
+      "order": 4,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "source",
+          "type": "*",
+          "link": 11
+        }
+      ],
+      "outputs": [],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfy-core",
+        "ver": "0.7.0",
+        "Node name for S&R": "PreviewAny"
+      },
+      "widgets_values": [
+        null,
+        null,
+        true
+      ]
+    },
+    {
+      "id": 16,
+      "type": "PreviewAny",
+      "pos": [
+        -3544,
+        712
+      ],
+      "size": [
+        400,
+        448
+      ],
+      "flags": {},
+      "order": 7,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "source",
+          "type": "*",
+          "link": 10
+        }
+      ],
+      "outputs": [],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfy-core",
+        "ver": "0.7.0",
+        "Node name for S&R": "PreviewAny"
+      },
+      "widgets_values": [
+        null,
+        null,
+        false
+      ]
+    }
+  ],
+  "links": [
+    [
+      6,
+      13,
+      0,
+      6,
+      0,
+      "STRING"
+    ],
+    [
+      9,
+      11,
+      1,
+      7,
+      0,
+      "STRING"
+    ],
+    [
+      10,
+      14,
+      1,
+      16,
+      0,
+      "STRING"
+    ],
+    [
+      11,
+      12,
+      0,
+      15,
+      0,
+      "STRING"
+    ]
+  ],
+  "groups": [],
+  "config": {},
+  "extra": {
+    "workflowRendererVersion": "LG",
+    "ds": {
+      "scale": 0.9070294784580494,
+      "offset": [
+        3972,
+        -12
+      ]
+    },
+    "frontendVersion": "1.37.2",
+    "VHS_latentpreview": false,
+    "VHS_latentpreviewrate": 0,
+    "VHS_MetadataImage": true,
+    "VHS_KeepIntermediate": true
+  },
+  "version": 0.4
+}

example_workflows/RenameKeysInModel.json

@@ -0,0 +1,583 @@
+{
+  "id": "e07ecc9b-30b9-45e4-9ed6-5fbb7e510257",
+  "revision": 0,
+  "last_node_id": 46,
+  "last_link_id": 31,
+  "nodes": [
+    {
+      "id": 35,
+      "type": "LoRAMetaKeys",
+      "pos": [
+        -3136,
+        512
+      ],
+      "size": [
+        376,
+        78
+      ],
+      "flags": {},
+      "order": 0,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "metadata",
+          "type": "STRING",
+          "links": null
+        },
+        {
+          "name": "keys",
+          "type": "STRING",
+          "links": [
+            21,
+            22
+          ]
+        }
+      ],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfyui_modelutils",
+        "ver": "eef737706127fe4a2c28172ab706e92318e0dc60",
+        "Node name for S&R": "LoRAMetaKeys"
+      },
+      "widgets_values": [
+        "qwen\\gmqwen_k8_piid_4step.safetensors"
+      ]
+    },
+    {
+      "id": 36,
+      "type": "LoRARenameKeys",
+      "pos": [
+        -2856,
+        864
+      ],
+      "size": [
+        320,
+        190
+      ],
+      "flags": {},
+      "order": 7,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "old_keys",
+          "type": "STRING",
+          "widget": {
+            "name": "old_keys"
+          },
+          "link": 27
+        },
+        {
+          "name": "new_keys",
+          "type": "STRING",
+          "widget": {
+            "name": "new_keys"
+          },
+          "link": 28
+        }
+      ],
+      "outputs": [
+        {
+          "name": "output_path",
+          "type": "STRING",
+          "links": [
+            31
+          ]
+        }
+      ],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfyui_modelutils",
+        "ver": "eef737706127fe4a2c28172ab706e92318e0dc60",
+        "Node name for S&R": "LoRARenameKeys"
+      },
+      "widgets_values": [
+        "qwen\\gmqwen_k8_piid_4step.safetensors",
+        "",
+        "",
+        "gmqwen_k8_piid_4step"
+      ]
+    },
+    {
+      "id": 37,
+      "type": "PreviewAny",
+      "pos": [
+        -3792,
+        920
+      ],
+      "size": [
+        592,
+        384
+      ],
+      "flags": {},
+      "order": 1,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "source",
+          "type": "*",
+          "link": 21
+        }
+      ],
+      "outputs": [],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfy-core",
+        "ver": "0.7.0",
+        "Node name for S&R": "PreviewAny"
+      },
+      "widgets_values": [
+        null,
+        null,
+        true
+      ]
+    },
+    {
+      "id": 40,
+      "type": "RegexReplace",
+      "pos": [
+        -3400,
+        568
+      ],
+      "size": [
+        210,
+        292
+      ],
+      "flags": {},
+      "order": 2,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "string",
+          "type": "STRING",
+          "widget": {
+            "name": "string"
+          },
+          "link": 22
+        }
+      ],
+      "outputs": [
+        {
+          "name": "STRING",
+          "type": "STRING",
+          "links": [
+            23,
+            25
+          ]
+        }
+      ],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfy-core",
+        "ver": "0.7.0",
+        "Node name for S&R": "RegexReplace"
+      },
+      "widgets_values": [
+        "",
+        ",\\s\\[.+$",
+        "",
+        true,
+        true,
+        false,
+        0
+      ]
+    },
+    {
+      "id": 41,
+      "type": "PreviewAny",
+      "pos": [
+        -3784,
+        528
+      ],
+      "size": [
+        360,
+        328
+      ],
+      "flags": {},
+      "order": 3,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "source",
+          "type": "*",
+          "link": 23
+        }
+      ],
+      "outputs": [],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfy-core",
+        "ver": "0.7.0",
+        "Node name for S&R": "PreviewAny"
+      },
+      "widgets_values": [
+        null,
+        null,
+        true
+      ]
+    },
+    {
+      "id": 42,
+      "type": "RegexReplace",
+      "pos": [
+        -3176,
+        1016
+      ],
+      "size": [
+        288,
+        292
+      ],
+      "flags": {},
+      "order": 5,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "string",
+          "type": "STRING",
+          "widget": {
+            "name": "string"
+          },
+          "link": 26
+        }
+      ],
+      "outputs": [
+        {
+          "name": "STRING",
+          "type": "STRING",
+          "links": [
+            28,
+            30
+          ]
+        }
+      ],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfy-core",
+        "ver": "0.7.0",
+        "Node name for S&R": "RegexReplace"
+      },
+      "widgets_values": [
+        "",
+        "^(\\w+)",
+        "diffusion_model.\\1",
+        true,
+        true,
+        false,
+        0
+      ]
+    },
+    {
+      "id": 43,
+      "type": "RegexReplace",
+      "pos": [
+        -3152,
+        648
+      ],
+      "size": [
+        288,
+        292
+      ],
+      "flags": {},
+      "order": 4,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "string",
+          "type": "STRING",
+          "widget": {
+            "name": "string"
+          },
+          "link": 25
+        }
+      ],
+      "outputs": [
+        {
+          "name": "STRING",
+          "type": "STRING",
+          "links": [
+            26,
+            27,
+            29
+          ]
+        }
+      ],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfy-core",
+        "ver": "0.7.0",
+        "Node name for S&R": "RegexReplace"
+      },
+      "widgets_values": [
+        "",
+        "^(proj_out.+|norm_out.+)$\\n",
+        "",
+        true,
+        true,
+        false,
+        0
+      ]
+    },
+    {
+      "id": 44,
+      "type": "PreviewAny",
+      "pos": [
+        -2832,
+        632
+      ],
+      "size": [
+        640,
+        192
+      ],
+      "flags": {},
+      "order": 6,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "source",
+          "type": "*",
+          "link": 29
+        }
+      ],
+      "outputs": [],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfy-core",
+        "ver": "0.7.0",
+        "Node name for S&R": "PreviewAny"
+      },
+      "widgets_values": [
+        null,
+        null,
+        true
+      ]
+    },
+    {
+      "id": 45,
+      "type": "PreviewAny",
+      "pos": [
+        -2848,
+        1096
+      ],
+      "size": [
+        640,
+        192
+      ],
+      "flags": {},
+      "order": 8,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "source",
+          "type": "*",
+          "link": 30
+        }
+      ],
+      "outputs": [],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfy-core",
+        "ver": "0.7.0",
+        "Node name for S&R": "PreviewAny"
+      },
+      "widgets_values": [
+        null,
+        null,
+        true
+      ]
+    },
+    {
+      "id": 46,
+      "type": "PreviewAny",
+      "pos": [
+        -2520,
+        872
+      ],
+      "size": [
+        336,
+        168
+      ],
+      "flags": {},
+      "order": 9,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "source",
+          "type": "*",
+          "link": 31
+        }
+      ],
+      "outputs": [],
+      "properties": {
+        "enableTabs": false,
+        "tabWidth": 65,
+        "tabXOffset": 10,
+        "hasSecondTab": false,
+        "secondTabText": "Send Back",
+        "secondTabOffset": 80,
+        "secondTabWidth": 65,
+        "cnr_id": "comfy-core",
+        "ver": "0.7.0",
+        "Node name for S&R": "PreviewAny"
+      },
+      "widgets_values": [
+        null,
+        null,
+        true
+      ]
+    }
+  ],
+  "links": [
+    [
+      21,
+      35,
+      1,
+      37,
+      0,
+      "STRING"
+    ],
+    [
+      22,
+      35,
+      1,
+      40,
+      0,
+      "STRING"
+    ],
+    [
+      23,
+      40,
+      0,
+      41,
+      0,
+      "STRING"
+    ],
+    [
+      25,
+      40,
+      0,
+      43,
+      0,
+      "STRING"
+    ],
+    [
+      26,
+      43,
+      0,
+      42,
+      0,
+      "STRING"
+    ],
+    [
+      27,
+      43,
+      0,
+      36,
+      0,
+      "STRING"
+    ],
+    [
+      28,
+      42,
+      0,
+      36,
+      1,
+      "STRING"
+    ],
+    [
+      29,
+      43,
+      0,
+      44,
+      0,
+      "STRING"
+    ],
+    [
+      30,
+      42,
+      0,
+      45,
+      0,
+      "STRING"
+    ],
+    [
+      31,
+      36,
+      0,
+      46,
+      0,
+      "STRING"
+    ]
+  ],
+  "groups": [],
+  "config": {},
+  "extra": {
+    "workflowRendererVersion": "LG",
+    "ds": {
+      "scale": 1,
+      "offset": [
+        4191.258750150775,
+        -356.1917593715161
+      ]
+    },
+    "frontendVersion": "1.37.2",
+    "VHS_latentpreview": false,
+    "VHS_latentpreviewrate": 0,
+    "VHS_MetadataImage": true,
+    "VHS_KeepIntermediate": true
+  },
+  "version": 0.4
+}

nodes/__init__.py

@@ -1,8 +0,0 @@
-from .metakeys import *
-
-__all__ = (
-    "UNetMetaKeys",
-    "CLIPMetaKeys",
-    "LoRAMetaKeys",
-    "CheckpointMetaKeys",
-)

nodes/device_utils.py

@@ -0,0 +1,268 @@
+"""
+Device capabilities and memory management utilities.
+
+Integrates with ComfyUI's model_management for safe memory operations.
+"""
+import os
+import gc
+import psutil
+import torch
+from typing import Optional, Tuple
+from dataclasses import dataclass
+
+# Import ComfyUI's model management functions
+try:
+    from comfy.model_management import (
+        get_torch_device,
+        get_free_memory,
+        get_total_memory,
+        free_memory,
+        soft_empty_cache,
+        unload_all_models,
+        is_device_cuda,
+    )
+    COMFY_AVAILABLE = True
+except ImportError:
+    COMFY_AVAILABLE = False
+
+
+@dataclass
+class DeviceCapabilities:
+    """Device capabilities for I/O and compute optimization."""
+    device_type: str  # 'cuda', 'cpu', 'mps', 'xpu'
+    total_vram_gb: float
+    free_vram_gb: float
+    total_ram_gb: float
+    free_ram_gb: float
+    cpu_cores: int
+    recommended_workers: int
+    max_tensor_size_gb: float  # Largest tensor we can safely load
+    supports_pinned_memory: bool
+    supports_async_streams: bool
+
+
+def get_device_capabilities(device: Optional[torch.device] = None) -> DeviceCapabilities:
+    """
+    Analyze device capabilities for optimal I/O configuration.
+
+    Args:
+        device: Target device (default: ComfyUI's torch device)
+
+    Returns:
+        DeviceCapabilities dataclass with recommended settings
+    """
+    if device is None:
+        if COMFY_AVAILABLE:
+            device = get_torch_device()
+        else:
+            device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
+
+    device_type = device.type if hasattr(device, 'type') else 'cpu'
+
+    # Get RAM info
+    ram_info = psutil.virtual_memory()
+    total_ram_gb = ram_info.total / (1024**3)
+    free_ram_gb = ram_info.available / (1024**3)
+
+    # Get VRAM info
+    if device_type == 'cuda' and torch.cuda.is_available():
+        if COMFY_AVAILABLE:
+            total_vram = get_total_memory(device)
+            free_vram = get_free_memory(device)
+        else:
+            free_vram, total_vram = torch.cuda.mem_get_info(device)
+        total_vram_gb = total_vram / (1024**3)
+        free_vram_gb = free_vram / (1024**3)
+        supports_pinned = True
+        supports_async = True
+    elif device_type == 'mps':
+        total_vram_gb = total_ram_gb * 0.5  # MPS shares RAM
+        free_vram_gb = free_ram_gb * 0.5
+        supports_pinned = False
+        supports_async = False
+    else:
+        total_vram_gb = 0
+        free_vram_gb = 0
+        supports_pinned = False
+        supports_async = False
+
+    # CPU cores
+    cpu_cores = os.cpu_count() or 4
+
+    # Recommended workers based on hardware
+    if device_type == 'cuda':
+        # GPU: fewer workers since I/O is not the bottleneck
+        recommended_workers = min(4, cpu_cores // 2)
+    else:
+        # CPU: more workers for parallel I/O
+        recommended_workers = min(8, cpu_cores)
+
+    # Max tensor size: leave headroom for operations
+    if device_type == 'cuda':
+        max_tensor_gb = min(free_vram_gb * 0.8, free_ram_gb * 0.5)
+    else:
+        max_tensor_gb = free_ram_gb * 0.6
+
+    return DeviceCapabilities(
+        device_type=device_type,
+        total_vram_gb=total_vram_gb,
+        free_vram_gb=free_vram_gb,
+        total_ram_gb=total_ram_gb,
+        free_ram_gb=free_ram_gb,
+        cpu_cores=cpu_cores,
+        recommended_workers=recommended_workers,
+        max_tensor_size_gb=max_tensor_gb,
+        supports_pinned_memory=supports_pinned,
+        supports_async_streams=supports_async,
+    )
+
+
+def estimate_model_size(file_path: str) -> float:
+    """Estimate model size in GB from file size."""
+    try:
+        return os.path.getsize(file_path) / (1024**3)
+    except OSError:
+        return 0.0
+
+
+def can_fit_in_memory(
+    model_paths: list[str],
+    device: Optional[torch.device] = None,
+    safety_factor: float = 0.8
+) -> Tuple[bool, str]:
+    """
+    Check if models can fit in available memory.
+
+    Args:
+        model_paths: List of model file paths
+        device: Target device
+        safety_factor: Fraction of free memory to use (default 0.8)
+
+    Returns:
+        (can_fit, reason_message)
+    """
+    caps = get_device_capabilities(device)
+
+    total_size = sum(estimate_model_size(p) for p in model_paths)
+
+    if caps.device_type == 'cuda':
+        available = caps.free_vram_gb * safety_factor
+        mem_type = "VRAM"
+    else:
+        available = caps.free_ram_gb * safety_factor
+        mem_type = "RAM"
+
+    if total_size <= available:
+        return True, f"OK: {total_size:.2f}GB needed, {available:.2f}GB {mem_type} available"
+    else:
+        return False, f"Insufficient memory: {total_size:.2f}GB needed but only {available:.2f}GB {mem_type} available"
+
+
+def prepare_for_large_operation(
+    estimated_memory_gb: float,
+    device: Optional[torch.device] = None
+) -> bool:
+    """
+    Prepare device for a large memory operation by freeing resources.
+
+    Args:
+        estimated_memory_gb: Estimated memory needed in GB
+        device: Target device
+
+    Returns:
+        True if preparation succeeded
+    """
+    if not COMFY_AVAILABLE:
+        gc.collect()
+        if torch.cuda.is_available():
+            torch.cuda.empty_cache()
+        return True
+
+    if device is None:
+        device = get_torch_device()
+
+    memory_bytes = int(estimated_memory_gb * 1024**3)
+
+    # Use ComfyUI's free_memory which unloads models intelligently
+    try:
+        free_memory(memory_bytes, device)
+        return True
+    except Exception as e:
+        print(f"[DeviceUtils] Warning: Could not free memory: {e}")
+        return False
+
+
+def cleanup_after_operation():
+    """Clean up memory after a large operation."""
+    gc.collect()
+
+    if COMFY_AVAILABLE:
+        soft_empty_cache()
+    elif torch.cuda.is_available():
+        torch.cuda.empty_cache()
+        torch.cuda.ipc_collect()
+
+
+def get_optimal_workers(
+    model_size_gb: float,
+    caps: Optional[DeviceCapabilities] = None
+) -> int:
+    """
+    Calculate optimal number of I/O workers based on model size and device.
+
+    Args:
+        model_size_gb: Model size in GB
+        caps: Pre-calculated device capabilities (optional)
+
+    Returns:
+        Recommended number of workers
+    """
+    if caps is None:
+        caps = get_device_capabilities()
+
+    # For very large models, fewer workers to avoid memory pressure
+    if model_size_gb > caps.free_ram_gb * 0.5:
+        return max(1, caps.recommended_workers // 2)
+
+    # For small models, use more workers
+    if model_size_gb < 2.0:
+        return min(8, caps.cpu_cores)
+
+    return caps.recommended_workers
+
+
+def get_processing_device_string(prefer_cuda: bool = True) -> str:
+    """
+    Get the best available processing device as a string.
+
+    Args:
+        prefer_cuda: Prefer CUDA over CPU if available
+
+    Returns:
+        Device string ('cuda', 'mps', 'cpu')
+    """
+    if prefer_cuda:
+        if torch.cuda.is_available():
+            return "cuda"
+        if hasattr(torch.backends, 'mps') and torch.backends.mps.is_available():
+            return "mps"
+    return "cpu"
+
+
+def print_device_info():
+    """Print device capabilities for debugging."""
+    caps = get_device_capabilities()
+    print(f"\n{'='*50}")
+    print("  Device Capabilities")
+    print(f"{'='*50}")
+    print(f"  Device Type: {caps.device_type}")
+    print(f"  Total VRAM: {caps.total_vram_gb:.2f} GB")
+    print(f"  Free VRAM: {caps.free_vram_gb:.2f} GB")
+    print(f"  Total RAM: {caps.total_ram_gb:.2f} GB")
+    print(f"  Free RAM: {caps.free_ram_gb:.2f} GB")
+    print(f"  CPU Cores: {caps.cpu_cores}")
+    print(f"  Recommended Workers: {caps.recommended_workers}")
+    print(f"  Max Tensor Size: {caps.max_tensor_size_gb:.2f} GB")
+    print(f"  Pinned Memory: {caps.supports_pinned_memory}")
+    print(f"  Async Streams: {caps.supports_async_streams}")
+    print(f"{'='*50}\n")

nodes/lora_extract_svd.py

@@ -0,0 +1,840 @@
+"""
+LoRA Extraction via SVD decomposition.
+
+Native implementation of Low-Rank Adapter extraction with multiple rank selection modes.
+No external dependencies required.
+"""
+import os
+import re
+import torch
+import torch.linalg as linalg
+import folder_paths
+import comfy.utils
+from tqdm import tqdm
+from comfy_api.latest import io
+from safetensors.torch import save_file
+from .merger_utils import MemoryEfficientSafeOpen, transfer_to_gpu_pinned
+from .device_utils import (
+    estimate_model_size, prepare_for_large_operation,
+    cleanup_after_operation, get_device_capabilities
+)
+
+
+# =============================================================================
+# Rank Index Functions - Determine LoRA rank from singular values
+# =============================================================================
+
+def _index_sv_fixed(S: torch.Tensor, dim: int) -> int:
+    """Fixed rank mode - use specified dimension."""
+    return max(1, min(dim, len(S) - 1))
+
+
+def _index_sv_threshold(S: torch.Tensor, threshold: float) -> int:
+    """Threshold mode - keep singular values above absolute threshold."""
+    rank = int(torch.sum(S > threshold).item())
+    return max(1, min(rank, len(S) - 1))
+
+
+def _index_sv_ratio(S: torch.Tensor, ratio: float) -> int:
+    """Ratio mode - keep singular values > max(S) / ratio (kohya convention)."""
+    if ratio <= 0:
+        return len(S) - 1
+    min_sv = S[0] / ratio
+    rank = int(torch.sum(S > min_sv).item())
+    return max(1, min(rank, len(S) - 1))
+
+
+def _index_sv_cumulative(S: torch.Tensor, target: float) -> int:
+    """Cumulative mode - keep enough SVs to reach target % of total."""
+    total = torch.sum(S)
+    if total < 1e-8:
+        return 1
+    cumsum = torch.cumsum(S, dim=0) / total
+    rank = int(torch.searchsorted(cumsum, target).item()) + 1
+    return max(1, min(rank, len(S) - 1))
+
+
+def _index_sv_fro(S: torch.Tensor, target: float) -> int:
+    """Frobenius norm mode - preserve target fraction of Frobenius norm."""
+    S_sq = S.pow(2)
+    total_sq = torch.sum(S_sq)
+    if total_sq < 1e-8:
+        return 1
+    cumsum = torch.cumsum(S_sq, dim=0) / total_sq
+    rank = int(torch.searchsorted(cumsum, target ** 2).item()) + 1
+    return max(1, min(rank, len(S) - 1))
+
+
+def _index_sv_knee(S: torch.Tensor, min_sv: float = 1e-8) -> int:
+    """Knee detection - find elbow point on singular value curve."""
+    n = len(S)
+    if n < 3:
+        return 1
+    s_max, s_min = S[0].item(), S[-1].item()
+    if s_max - s_min < min_sv:
+        return 1
+    # Normalize to [0, 1]
+    s_norm = (S - s_min) / (s_max - s_min)
+    x_norm = torch.linspace(0, 1, n, device=S.device, dtype=S.dtype)
+    # Distance from diagonal
+    distances = (x_norm + s_norm - 1).abs()
+    rank = torch.argmax(distances).item() + 1
+    return max(1, min(rank, n - 1))
+
+
+def _index_sv_cumulative_knee(S: torch.Tensor, min_sv: float = 1e-8) -> int:
+    """Knee detection on cumulative singular value curve."""
+    n = len(S)
+    if n < 3:
+        return 1
+    total = torch.sum(S)
+    if total < min_sv:
+        return 1
+    cumsum = torch.cumsum(S, dim=0) / total
+    y_min, y_max = cumsum[0].item(), cumsum[-1].item()
+    if y_max - y_min < min_sv:
+        return 1
+    y_norm = (cumsum - y_min) / (y_max - y_min)
+    x_norm = torch.linspace(0, 1, n, device=S.device, dtype=S.dtype)
+    distances = (y_norm - x_norm).abs()
+    rank = torch.argmax(distances).item() + 1
+    return max(1, min(rank, n - 1))
+
+
+def _index_sv_rel_decrease(S: torch.Tensor, tau: float = 0.1) -> int:
+    """Relative decrease mode - stop when consecutive SV ratio drops below tau."""
+    if len(S) < 2:
+        return 1
+    ratios = S[1:] / (S[:-1] + 1e-8)
+    for k in range(len(ratios)):
+        if ratios[k] < tau:
+            return k + 1
+    return len(S)
+
+
+def _compute_rank(S: torch.Tensor, mode: str, mode_param: float,
+                  max_rank: int = None) -> int:
+    """Compute rank based on mode and parameters."""
+    if mode == "fixed":
+        rank = _index_sv_fixed(S, int(mode_param))
+    elif mode == "threshold":
+        rank = _index_sv_threshold(S, mode_param)
+    elif mode == "ratio":
+        rank = _index_sv_ratio(S, mode_param)
+    elif mode == "quantile" or mode == "sv_cumulative":
+        rank = _index_sv_cumulative(S, mode_param)
+    elif mode == "sv_fro":
+        rank = _index_sv_fro(S, mode_param)
+    elif mode == "sv_knee":
+        rank = _index_sv_knee(S)
+    elif mode == "sv_cumulative_knee":
+        rank = _index_sv_cumulative_knee(S)
+    elif mode == "sv_rel_decrease":
+        rank = _index_sv_rel_decrease(S, mode_param)
+    else:
+        rank = _index_sv_fixed(S, int(mode_param) if mode_param else 64)
+
+    if max_rank is not None:
+        rank = min(rank, max_rank)
+    return rank
+
+
+# =============================================================================
+# SVD Extraction Functions
+# =============================================================================
+
+def _svd_extract_linear_lowrank(
+    weight: torch.Tensor,
+    rank: int,
+    device: str,
+    clamp_quantile: float = 0.99,
+    niter: int = 2,
+) -> tuple:
+    """
+    Low-rank SVD decomposition using svd_lowrank for fixed rank extraction.
+    
+    Much faster than full SVD when rank << min(m, n) because it only computes
+    the top-k singular values using randomized algorithms.
+    
+    Args:
+        niter: Power iterations for SVD accuracy (higher = more accurate but slower)
+    
+    Returns:
+        (lora_down, lora_up, diff), "low rank" or (weight, "full")
+    """
+    weight = weight.to(device=device, dtype=torch.float32)
+    out_dim, in_dim = weight.shape
+    
+    # Clamp rank to valid range
+    max_possible_rank = min(out_dim, in_dim)
+    rank = max(1, min(rank, max_possible_rank - 1))
+    
+    # Check if decomposition is worthwhile
+    if rank >= max_possible_rank // 2:
+        return weight, "full"
+    
+    # Use svd_lowrank for faster low-rank approximation
+    try:
+        U, S, V = torch.svd_lowrank(weight, q=rank, niter=niter)
+        # U: [out_dim, rank], S: [rank], V: [in_dim, rank]
+        Vh = V.T  # [rank, in_dim]
+    except Exception as e:
+        raise RuntimeError(f"svd_lowrank failed: {e}")
+    
+    # Clamp outliers
+    if clamp_quantile < 1.0 and len(S) > 0:
+        try:
+            max_val = torch.quantile(S, clamp_quantile)
+            S = S.clamp(max=max_val)
+        except RuntimeError:
+            pass
+    
+    # Construct LoRA matrices
+    lora_up = U @ torch.diag(S)  # [out_dim, rank]
+    lora_down = Vh               # [rank, in_dim]
+    
+    # Compute reconstruction diff
+    diff = weight - (lora_up @ lora_down)
+    
+    return (lora_down, lora_up, diff), "low rank"
+
+
+def _svd_extract_linear(
+    weight: torch.Tensor,
+    mode: str,
+    mode_param: float,
+    device: str,
+    max_rank: int = None,
+    clamp_quantile: float = 0.99,
+    niter: int = 2,
+) -> tuple:
+    """
+    SVD decomposition for linear layers.
+
+    For fixed rank mode, uses svd_lowrank which is much faster.
+    For adaptive modes, uses full SVD to analyze all singular values.
+
+    Returns:
+        (lora_down, lora_up, rank), "low rank" or (weight, "full")
+    """
+    weight = weight.to(device=device, dtype=torch.float32)
+    out_dim, in_dim = weight.shape
+    
+    # For fixed rank, use the faster svd_lowrank
+    if mode == "fixed" and mode_param > 0:
+        target_rank = int(mode_param)
+        if max_rank is not None:
+            target_rank = min(target_rank, max_rank)
+        return _svd_extract_linear_lowrank(weight, target_rank, device, clamp_quantile, niter)
+
+    # For adaptive modes, use full SVD to analyze singular values
+    try:
+        U, S, Vh = linalg.svd(weight, full_matrices=False)
+    except Exception as e:
+        raise RuntimeError(f"SVD failed: {e}")
+
+    # Compute rank based on mode
+    rank = _compute_rank(S, mode, mode_param, max_rank)
+
+    # Check if decomposition is worthwhile
+    if rank >= min(out_dim, in_dim) // 2:
+        return weight, "full"
+
+    # Truncate to rank
+    U = U[:, :rank]
+    S = S[:rank]
+    Vh = Vh[:rank, :]
+
+    # Clamp outliers
+    if clamp_quantile < 1.0 and len(S) > 0:
+        try:
+            max_val = torch.quantile(S, clamp_quantile)
+            S = S.clamp(max=max_val)
+        except RuntimeError:
+            pass  # Skip clamping if quantile fails
+
+    # Construct LoRA matrices
+    # lora_up = U @ diag(S), lora_down = Vh
+    lora_up = U @ torch.diag(S)  # [out_dim, rank]
+    lora_down = Vh               # [rank, in_dim]
+
+    # Compute reconstruction diff for optional sparse bias
+    diff = weight - (lora_up @ lora_down)
+
+    return (lora_down, lora_up, diff), "low rank"
+
+
+def _svd_extract_conv(
+    weight: torch.Tensor,
+    mode: str,
+    mode_param: float,
+    device: str,
+    max_rank: int = None,
+    clamp_quantile: float = 0.99,
+) -> tuple:
+    """
+    SVD decomposition for conv2d layers.
+
+    Returns:
+        (lora_down, lora_up, rank), "low rank" or (weight, "full")
+    """
+    out_ch, in_ch, kh, kw = weight.shape
+    is_1x1 = (kh == 1 and kw == 1)
+
+    # Flatten for SVD
+    if is_1x1:
+        mat = weight.squeeze()  # [out_ch, in_ch]
+    else:
+        mat = weight.reshape(out_ch, -1)  # [out_ch, in_ch*k*k]
+
+    result, mode_str = _svd_extract_linear(mat, mode, mode_param, device, max_rank, clamp_quantile)
+
+    if mode_str == "full":
+        return weight, "full"
+
+    lora_down, lora_up, diff = result
+    rank = lora_down.shape[0]
+
+    # Reshape for conv
+    if is_1x1:
+        lora_down = lora_down.unsqueeze(-1).unsqueeze(-1)  # [rank, in_ch, 1, 1]
+        lora_up = lora_up.unsqueeze(-1).unsqueeze(-1)      # [out_ch, rank, 1, 1]
+    else:
+        lora_down = lora_down.reshape(rank, in_ch, kh, kw)
+        lora_up = lora_up.reshape(out_ch, rank, 1, 1)
+
+    return (lora_down, lora_up, diff), "low rank"
+
+
+# =============================================================================
+# Chunked Extraction for Large Layers
+# =============================================================================
+
+def _detect_fused_layer(key: str, shape: tuple) -> int:
+    """Detect fused QKV/MLP layers and return number of chunks."""
+    if len(shape) != 2:
+        return 1
+
+    out_dim, in_dim = shape
+    key_lower = key.lower()
+
+    # QKV layers (3 chunks)
+    if "qkv" in key_lower and out_dim % 3 == 0 and out_dim // 3 >= in_dim // 4:
+        return 3
+
+    # KV layers (2 chunks)
+    if "kv" in key_lower and "qkv" not in key_lower and out_dim % 2 == 0:
+        return 2
+
+    # Fused MLP (2 chunks)
+    if ("linear1" in key_lower or "gate_up" in key_lower) and out_dim % 2 == 0 and out_dim >= in_dim * 2:
+        return 2
+
+    return 1
+
+
+def _extract_chunked_layer(
+    weight_diff: torch.Tensor,
+    num_chunks: int,
+    mode: str,
+    mode_param: float,
+    device: str,
+    max_rank: int = None,
+) -> tuple:
+    """Extract LoRA from fused layer by chunking."""
+    out_dim, in_dim = weight_diff.shape
+    chunk_size = out_dim // num_chunks
+
+    all_lora_up = []
+    all_lora_down = []
+
+    for i in range(num_chunks):
+        chunk = weight_diff[i * chunk_size:(i + 1) * chunk_size, :]
+
+        try:
+            result, mode_str = _svd_extract_linear(chunk, mode, mode_param, device, max_rank)
+            if mode_str == "full":
+                return None, None, 0
+            lora_down, lora_up, _ = result
+            all_lora_down.append(lora_down)
+            all_lora_up.append(lora_up)
+        except Exception:
+            return None, None, 0
+
+    # Combine chunks
+    combined_lora_up = torch.cat(all_lora_up, dim=0)
+    combined_lora_down = torch.stack(all_lora_down, dim=0).mean(dim=0)
+    rank = combined_lora_down.shape[0]
+
+    return combined_lora_up, combined_lora_down, rank
+
+
+# =============================================================================
+# Pattern Matching
+# =============================================================================
+
+def _compile_patterns(pattern_string: str) -> list:
+    """Compile regex patterns from whitespace-separated string."""
+    if not pattern_string or not pattern_string.strip():
+        return []
+    patterns = []
+    for p in pattern_string.split():
+        p = p.strip()
+        if p:
+            try:
+                patterns.append(re.compile(p))
+            except re.error:
+                pass
+    return patterns
+
+
+def _matches_any_pattern(key: str, patterns: list) -> bool:
+    """Check if key matches any pattern."""
+    return any(p.search(key) for p in patterns)
+
+
+# =============================================================================
+# Main Extraction Function
+# =============================================================================
+
+def extract_lora_from_files(
+    model_a_path: str,
+    model_b_path: str,
+    mode: str,
+    linear_param: float,
+    conv_param: float,
+    prefix: str,
+    device: str,
+    save_dtype: str,
+    linear_max_rank: int = None,
+    conv_max_rank: int = None,
+    clamp_quantile: float = 0.99,
+    min_diff: float = 0.0,
+    skip_patterns_str: str = "",
+    mismatch_mode: str = "skip",
+    chunk_large_layers: bool = True,
+    svd_niter: int = 2,
+) -> dict[str, torch.Tensor]:
+    """
+    Extract LoRA from difference between two models.
+
+    Args:
+        model_a_path: Finetuned model path
+        model_b_path: Base model path
+        mode: Rank selection mode
+        linear_param: Mode parameter for linear layers
+        conv_param: Mode parameter for conv layers
+        prefix: LoRA key prefix (e.g. "lora_unet_")
+        device: Computation device
+        save_dtype: Output dtype
+        linear_max_rank: Max rank for linear layers
+        conv_max_rank: Max rank for conv layers
+        clamp_quantile: Quantile for weight clamping
+        min_diff: Minimum difference threshold
+        skip_patterns_str: Patterns for layers to skip
+        mismatch_mode: How to handle mismatches
+        chunk_large_layers: Enable chunked extraction
+    """
+    output_sd = {}
+
+    save_torch_dtype = {
+        "fp32": torch.float32,
+        "fp16": torch.float16,
+        "bf16": torch.bfloat16,
+    }.get(save_dtype, torch.float16)
+
+    skip_patterns = _compile_patterns(skip_patterns_str)
+
+    # Prepare memory before heavy operation
+    total_size_gb = estimate_model_size(model_a_path) + estimate_model_size(model_b_path)
+    print(f"[LoRA Extract] Preparing memory for {total_size_gb:.2f}GB operation...")
+    prepare_for_large_operation(total_size_gb * 1.5, torch.device(device))  # 1.5x for SVD headroom
+
+    handler_a = MemoryEfficientSafeOpen(model_a_path)
+    handler_b = MemoryEfficientSafeOpen(model_b_path)
+
+    try:
+        keys_a = set(handler_a.keys())
+        keys_b = set(handler_b.keys())
+
+        weight_keys = [k for k in keys_a if k.endswith(".weight")]
+
+        pbar = comfy.utils.ProgressBar(len(weight_keys))
+
+        stats = {"extracted": 0, "full": 0, "skipped": 0, "chunked": 0}
+
+        for key in tqdm(weight_keys, desc="Extracting LoRA", unit="layers"):
+            lora_key = key[:-7]
+            lora_name = prefix + lora_key.replace(".", "_")
+
+            if _matches_any_pattern(key, skip_patterns):
+                stats["skipped"] += 1
+                pbar.update(1)
+                continue
+
+            # Load tensors with pinned memory for CUDA
+            use_pinned = device == 'cuda'
+            
+            if key not in keys_b:
+                if mismatch_mode == "skip":
+                    stats["skipped"] += 1
+                    pbar.update(1)
+                    continue
+                cpu_a = handler_a.get_tensor(key)
+                if use_pinned:
+                    weight_diff = transfer_to_gpu_pinned(cpu_a, device, torch.float32)
+                else:
+                    weight_diff = cpu_a.to(device=device, dtype=torch.float32)
+                del cpu_a
+            else:
+                cpu_a = handler_a.get_tensor(key)
+                cpu_b = handler_b.get_tensor(key)
+                
+                if use_pinned:
+                    tensor_a = transfer_to_gpu_pinned(cpu_a, device, torch.float32)
+                    tensor_b = transfer_to_gpu_pinned(cpu_b, device, torch.float32)
+                else:
+                    tensor_a = cpu_a.to(device=device, dtype=torch.float32)
+                    tensor_b = cpu_b.to(device=device, dtype=torch.float32)
+                del cpu_a, cpu_b
+
+                if tensor_a.shape != tensor_b.shape:
+                    if mismatch_mode == "skip":
+                        stats["skipped"] += 1
+                        pbar.update(1)
+                        del tensor_a, tensor_b
+                        continue
+                    weight_diff = tensor_a
+                    del tensor_b
+                else:
+                    weight_diff = tensor_a - tensor_b
+                    del tensor_a, tensor_b
+
+            # Skip small differences
+            if min_diff > 0 and weight_diff.abs().max() < min_diff:
+                stats["skipped"] += 1
+                del weight_diff
+                pbar.update(1)
+                continue
+
+            # Skip 1D tensors
+            if weight_diff.ndim < 2:
+                stats["skipped"] += 1
+                del weight_diff
+                pbar.update(1)
+                continue
+
+            is_conv = weight_diff.ndim == 4
+
+            try:
+                if is_conv:
+                    result, mode_str = _svd_extract_conv(
+                        weight_diff, mode, conv_param, device, conv_max_rank, clamp_quantile
+                    )
+                else:
+                    result, mode_str = _svd_extract_linear(
+                        weight_diff, mode, linear_param, device, linear_max_rank, clamp_quantile, svd_niter
+                    )
+            except Exception as e:
+                # Try chunked extraction for large tensors
+                if chunk_large_layers and not is_conv:
+                    num_chunks = _detect_fused_layer(key, weight_diff.shape)
+                    if num_chunks > 1:
+                        print(f"[LoRA Extract] Chunked: {key} ({num_chunks} chunks)")
+                        lora_up, lora_down, rank = _extract_chunked_layer(
+                            weight_diff, num_chunks, mode, linear_param, device, linear_max_rank
+                        )
+                        if lora_up is not None:
+                            output_sd[f"{lora_name}.lora_up.weight"] = lora_up.to(save_torch_dtype).cpu().contiguous()
+                            output_sd[f"{lora_name}.lora_down.weight"] = lora_down.to(save_torch_dtype).cpu().contiguous()
+                            output_sd[f"{lora_name}.alpha"] = torch.tensor([rank]).to(save_torch_dtype)
+                            stats["chunked"] += 1
+                            del weight_diff
+                            pbar.update(1)
+                            continue
+
+                print(f"[LoRA Extract] Failed: {key}: {e}")
+                stats["skipped"] += 1
+                del weight_diff
+                pbar.update(1)
+                continue
+
+            # Store result
+            if mode_str == "full":
+                output_sd[f"{lora_name}.diff"] = weight_diff.to(save_torch_dtype).cpu().contiguous()
+                stats["full"] += 1
+            else:
+                lora_down, lora_up, _ = result
+                output_sd[f"{lora_name}.lora_down.weight"] = lora_down.to(save_torch_dtype).cpu().contiguous()
+                output_sd[f"{lora_name}.lora_up.weight"] = lora_up.to(save_torch_dtype).cpu().contiguous()
+                output_sd[f"{lora_name}.alpha"] = torch.tensor([lora_down.shape[0]]).to(save_torch_dtype)
+                stats["extracted"] += 1
+
+            del weight_diff
+            pbar.update(1)
+
+        print(f"[LoRA Extract] Done: {stats['extracted']} extracted, {stats['chunked']} chunked, "
+              f"{stats['full']} full, {stats['skipped']} skipped")
+
+    finally:
+        handler_a.__exit__(None, None, None)
+        handler_b.__exit__(None, None, None)
+        cleanup_after_operation()
+
+    return output_sd
+
+
+def _save_lora(output_sd: dict, output_filename: str) -> str:
+    """Save LoRA to file."""
+    if not output_sd:
+        raise ValueError("No LoRA weights extracted")
+
+    output_dir = folder_paths.get_folder_paths("loras")[0]
+    os.makedirs(output_dir, exist_ok=True)
+    output_path = os.path.join(output_dir, f"{output_filename.strip()}.safetensors")
+
+    save_file(output_sd, output_path)
+    print(f"[LoRA Extract] Saved to {output_path}")
+
+    return output_path
+
+
+# =============================================================================
+# Node Definitions
+# =============================================================================
+
+def _get_model_inputs():
+    return [
+        io.Combo.Input("model_a", options=folder_paths.get_filename_list("diffusion_models"),
+                      tooltip="Finetuned model (A - B = LoRA)"),
+        io.Combo.Input("model_b", options=folder_paths.get_filename_list("diffusion_models"),
+                      tooltip="Base model (A - B = LoRA)"),
+    ]
+
+
+def _get_common_inputs():
+    return [
+        io.Boolean.Input("chunk_large_layers", default=False,
+                        tooltip="Split large fused layers (QKV, MLP) into chunks"),
+        io.Float.Input("clamp_quantile", default=0.99, min=0.5, max=1.0, step=0.01,
+                      tooltip="Clamp outlier singular values"),
+        io.Float.Input("min_diff", default=0.0, min=0.0, max=1.0, step=0.001,
+                      tooltip="Skip layers with max difference below this"),
+        io.Combo.Input("mismatch_mode", options=["skip", "zeros", "error"], default="skip"),
+        io.String.Input("output_filename", default="extracted_lora"),
+        io.Combo.Input("save_dtype", options=["fp16", "bf16", "fp32"], default="fp16"),
+        io.Combo.Input("device", options=["cuda", "cpu"], default="cuda"),
+        io.String.Input("skip_patterns", default="", multiline=True,
+                       tooltip="Regex patterns for layers to skip"),
+    ]
+
+
+class LoRAExtractFixed(io.ComfyNode):
+    """Extract LoRA with fixed rank."""
+
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="LoRAExtractFixed",
+            display_name="LoRA Extract (Fixed Rank)",
+            category="ModelUtils/LoRA",
+            description="Extract LoRA with specified fixed rank for each layer type.",
+            inputs=[
+                *_get_model_inputs(),
+                io.Int.Input("linear_dim", default=64, min=1, max=4096,
+                            tooltip="Rank for linear/attention layers"),
+                io.Int.Input("conv_dim", default=32, min=1, max=4096,
+                            tooltip="Rank for conv layers"),
+                io.Int.Input("svd_niter", default=2, min=0, max=10,
+                            tooltip="SVD power iterations (higher = more accurate but slower)"),
+                *_get_common_inputs(),
+            ],
+            outputs=[io.String.Output(display_name="output_path")],
+            is_output_node=True,
+        )
+
+    @classmethod
+    def execute(cls, model_a, model_b, linear_dim, conv_dim, svd_niter, chunk_large_layers,
+                clamp_quantile, min_diff, mismatch_mode, output_filename,
+                save_dtype, device, skip_patterns) -> io.NodeOutput:
+
+        model_a_path = folder_paths.get_full_path_or_raise("diffusion_models", model_a)
+        model_b_path = folder_paths.get_full_path_or_raise("diffusion_models", model_b)
+
+        output_sd = extract_lora_from_files(
+            model_a_path, model_b_path, "fixed", linear_dim, conv_dim,
+            "lora_unet_", device, save_dtype, linear_dim, conv_dim,
+            clamp_quantile, min_diff, skip_patterns, mismatch_mode, chunk_large_layers, svd_niter
+        )
+
+        return io.NodeOutput(_save_lora(output_sd, output_filename))
+
+
+class LoRAExtractRatio(io.ComfyNode):
+    """Extract LoRA with singular value ratio threshold."""
+
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="LoRAExtractRatio",
+            display_name="LoRA Extract (Ratio)",
+            category="ModelUtils/LoRA",
+            description="Keep singular values > max(S) / ratio.",
+            inputs=[
+                *_get_model_inputs(),
+                io.Float.Input("linear_ratio", default=2.0, min=1.0, max=100.0, step=0.1,
+                              tooltip="Ratio threshold for linear layers (higher = more SVs kept)"),
+                io.Float.Input("conv_ratio", default=2.0, min=1.0, max=100.0, step=0.1,
+                              tooltip="Ratio threshold for conv layers (higher = more SVs kept)"),
+                io.Int.Input("linear_max_rank", default=128, min=1, max=1024,
+                            tooltip="Maximum rank for linear layers"),
+                io.Int.Input("conv_max_rank", default=128, min=1, max=1024,
+                            tooltip="Maximum rank for conv layers"),
+                *_get_common_inputs(),
+            ],
+            outputs=[io.String.Output(display_name="output_path")],
+            is_output_node=True,
+        )
+
+    @classmethod
+    def execute(cls, model_a, model_b, linear_ratio, conv_ratio, linear_max_rank, conv_max_rank,
+                chunk_large_layers, clamp_quantile, min_diff, mismatch_mode, output_filename,
+                save_dtype, device, skip_patterns) -> io.NodeOutput:
+
+        model_a_path = folder_paths.get_full_path_or_raise("diffusion_models", model_a)
+        model_b_path = folder_paths.get_full_path_or_raise("diffusion_models", model_b)
+
+        output_sd = extract_lora_from_files(
+            model_a_path, model_b_path, "ratio", linear_ratio, conv_ratio,
+            "lora_unet_", device, save_dtype, linear_max_rank, conv_max_rank,
+            clamp_quantile, min_diff, skip_patterns, mismatch_mode, chunk_large_layers
+        )
+
+        return io.NodeOutput(_save_lora(output_sd, output_filename))
+
+
+class LoRAExtractQuantile(io.ComfyNode):
+    """Extract LoRA with cumulative singular value quantile."""
+
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="LoRAExtractQuantile",
+            display_name="LoRA Extract (Quantile)",
+            category="ModelUtils/LoRA",
+            description="Keep enough singular values to reach target percentage.",
+            inputs=[
+                *_get_model_inputs(),
+                io.Float.Input("linear_quantile", default=0.9, min=0.0, max=1.0, step=0.01,
+                              tooltip="Target cumulative % for linear layers"),
+                io.Float.Input("conv_quantile", default=0.9, min=0.0, max=1.0, step=0.01,
+                              tooltip="Target cumulative % for conv layers"),
+                io.Int.Input("linear_max_rank", default=128, min=1, max=1024,
+                            tooltip="Maximum rank for linear layers"),
+                io.Int.Input("conv_max_rank", default=128, min=1, max=1024,
+                            tooltip="Maximum rank for conv layers"),
+                *_get_common_inputs(),
+            ],
+            outputs=[io.String.Output(display_name="output_path")],
+            is_output_node=True,
+        )
+
+    @classmethod
+    def execute(cls, model_a, model_b, linear_quantile, conv_quantile, linear_max_rank, conv_max_rank,
+                chunk_large_layers, clamp_quantile, min_diff, mismatch_mode, output_filename,
+                save_dtype, device, skip_patterns) -> io.NodeOutput:
+
+        model_a_path = folder_paths.get_full_path_or_raise("diffusion_models", model_a)
+        model_b_path = folder_paths.get_full_path_or_raise("diffusion_models", model_b)
+
+        output_sd = extract_lora_from_files(
+            model_a_path, model_b_path, "quantile", linear_quantile, conv_quantile,
+            "lora_unet_", device, save_dtype, linear_max_rank, conv_max_rank,
+            clamp_quantile, min_diff, skip_patterns, mismatch_mode, chunk_large_layers
+        )
+
+        return io.NodeOutput(_save_lora(output_sd, output_filename))
+
+
+class LoRAExtractKnee(io.ComfyNode):
+    """Extract LoRA with automatic knee detection."""
+
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="LoRAExtractKnee",
+            display_name="LoRA Extract (Knee Detection)",
+            category="ModelUtils/LoRA",
+            description="Automatically find optimal rank using knee detection on singular value curve.",
+            inputs=[
+                *_get_model_inputs(),
+                io.Combo.Input("knee_method", options=["sv_knee", "sv_cumulative_knee"],
+                              default="sv_knee", tooltip="Knee detection method"),
+                io.Int.Input("linear_max_rank", default=128, min=1, max=1024,
+                            tooltip="Maximum rank for linear layers"),
+                io.Int.Input("conv_max_rank", default=128, min=1, max=1024,
+                            tooltip="Maximum rank for conv layers"),
+                *_get_common_inputs(),
+            ],
+            outputs=[io.String.Output(display_name="output_path")],
+            is_output_node=True,
+        )
+
+    @classmethod
+    def execute(cls, model_a, model_b, knee_method, linear_max_rank, conv_max_rank,
+                chunk_large_layers, clamp_quantile, min_diff, mismatch_mode, output_filename,
+                save_dtype, device, skip_patterns) -> io.NodeOutput:
+
+        model_a_path = folder_paths.get_full_path_or_raise("diffusion_models", model_a)
+        model_b_path = folder_paths.get_full_path_or_raise("diffusion_models", model_b)
+
+        output_sd = extract_lora_from_files(
+            model_a_path, model_b_path, knee_method, 0, 0,
+            "lora_unet_", device, save_dtype, linear_max_rank, conv_max_rank,
+            clamp_quantile, min_diff, skip_patterns, mismatch_mode, chunk_large_layers
+        )
+
+        return io.NodeOutput(_save_lora(output_sd, output_filename))
+
+
+class LoRAExtractFrobenius(io.ComfyNode):
+    """Extract LoRA preserving target fraction of Frobenius norm."""
+
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="LoRAExtractFrobenius",
+            display_name="LoRA Extract (Frobenius)",
+            category="ModelUtils/LoRA",
+            description="Preserve target fraction of Frobenius norm.",
+            inputs=[
+                *_get_model_inputs(),
+                io.Float.Input("linear_target", default=0.9, min=0.0, max=1.0, step=0.01,
+                              tooltip="Target Frobenius norm fraction for linear"),
+                io.Float.Input("conv_target", default=0.9, min=0.0, max=1.0, step=0.01,
+                              tooltip="Target Frobenius norm fraction for conv"),
+                io.Int.Input("linear_max_rank", default=128, min=1, max=1024,
+                            tooltip="Maximum rank for linear layers"),
+                io.Int.Input("conv_max_rank", default=128, min=1, max=1024,
+                            tooltip="Maximum rank for conv layers"),
+                *_get_common_inputs(),
+            ],
+            outputs=[io.String.Output(display_name="output_path")],
+            is_output_node=True,
+        )
+
+    @classmethod
+    def execute(cls, model_a, model_b, linear_target, conv_target, linear_max_rank, conv_max_rank,
+                chunk_large_layers, clamp_quantile, min_diff, mismatch_mode, output_filename,
+                save_dtype, device, skip_patterns) -> io.NodeOutput:
+
+        model_a_path = folder_paths.get_full_path_or_raise("diffusion_models", model_a)
+        model_b_path = folder_paths.get_full_path_or_raise("diffusion_models", model_b)
+
+        output_sd = extract_lora_from_files(
+            model_a_path, model_b_path, "sv_fro", linear_target, conv_target,
+            "lora_unet_", device, save_dtype, linear_max_rank, conv_max_rank,
+            clamp_quantile, min_diff, skip_patterns, mismatch_mode, chunk_large_layers
+        )
+
+        return io.NodeOutput(_save_lora(output_sd, output_filename))

nodes/lora_resize.py

@@ -0,0 +1,588 @@
+"""
+LoRA Resize - Resize existing LoRAs to different ranks.
+
+Based on kohya_ss resize_lora.py. Merges LoRA weights and re-extracts via SVD.
+Supports fixed rank and dynamic methods (sv_ratio, sv_fro, sv_cumulative).
+"""
+import os
+import re
+import torch
+import torch.linalg as linalg
+import folder_paths
+import comfy.utils
+from tqdm import tqdm
+from comfy_api.latest import io
+from safetensors.torch import save_file
+from typing import Optional, Dict, Tuple, List
+from .merger_utils import MemoryEfficientSafeOpen, transfer_to_gpu_pinned
+from .device_utils import estimate_model_size, prepare_for_large_operation, cleanup_after_operation
+
+# Reuse rank functions from extraction module
+from .lora_extract_svd import (
+    _index_sv_ratio,
+    _index_sv_cumulative,
+    _index_sv_fro,
+)
+
+
+MIN_SV = 1e-6
+
+
+# =============================================================================
+# LoRA Format Detection - Support various LoRA sources
+# =============================================================================
+
+def detect_lora_format(keys: List[str]) -> Dict:
+    """
+    Detect LoRA format and key patterns from various sources.
+    
+    Supports:
+    - Kohya/A1111: lora_unet_*, lora_te_*
+    - Diffusers: *.lora_A.weight, *.lora_B.weight
+    - PEFT: base_model.model.*.lora_A/B
+    - ComfyUI native: *.lora_down.weight, *.lora_up.weight
+    - Flux/SDXL: Various transformer key patterns
+    
+    Returns:
+        Dict with format info and key patterns
+    """
+    format_info = {
+        "format": "unknown",
+        "down_suffix": ".lora_down.weight",
+        "up_suffix": ".lora_up.weight",
+        "alpha_suffix": ".alpha",
+        "has_alpha": False,
+        "key_count": 0,
+    }
+    
+    # Check for alpha keys
+    alpha_keys = [k for k in keys if '.alpha' in k or k.endswith('alpha')]
+    format_info["has_alpha"] = len(alpha_keys) > 0
+    
+    # Detect format by key patterns
+    sample_keys = keys[:20]  # Check first 20 keys
+    
+    # Kohya/A1111 format: lora_unet_down_blocks_0_*.lora_down.weight
+    if any('lora_unet_' in k or 'lora_te' in k for k in sample_keys):
+        format_info["format"] = "kohya"
+        format_info["down_suffix"] = ".lora_down.weight"
+        format_info["up_suffix"] = ".lora_up.weight"
+    
+    # Diffusers format: transformer.*.lora_A.weight
+    elif any('.lora_A.weight' in k for k in sample_keys):
+        format_info["format"] = "diffusers"
+        format_info["down_suffix"] = ".lora_A.weight"
+        format_info["up_suffix"] = ".lora_B.weight"
+        format_info["alpha_suffix"] = ".alpha"
+    
+    # PEFT format: base_model.model.*.lora_A.default.weight
+    elif any('base_model.model.' in k and 'lora_' in k for k in sample_keys):
+        format_info["format"] = "peft"
+        # Handle nested structure
+        format_info["down_suffix"] = ".lora_A.default.weight"
+        format_info["up_suffix"] = ".lora_B.default.weight"
+    
+    # ComfyUI native / standard
+    elif any('.lora_down.weight' in k for k in sample_keys):
+        format_info["format"] = "comfy"
+        format_info["down_suffix"] = ".lora_down.weight"
+        format_info["up_suffix"] = ".lora_up.weight"
+    
+    # Count LoRA layers
+    down_keys = [k for k in keys if format_info["down_suffix"] in k]
+    format_info["key_count"] = len(down_keys)
+    
+    return format_info
+
+
+def extract_lora_pairs(keys: List[str], format_info: Dict) -> Dict[str, Dict[str, str]]:
+    """
+    Group LoRA keys into down/up/alpha pairs.
+    
+    Returns:
+        Dict[block_name, {"down": key, "up": key, "alpha": key}]
+    """
+    down_suffix = format_info["down_suffix"]
+    up_suffix = format_info["up_suffix"]
+    alpha_suffix = format_info["alpha_suffix"]
+    
+    pairs = {}
+    
+    for key in keys:
+        if down_suffix in key:
+            block_name = key.replace(down_suffix, "")
+            if block_name not in pairs:
+                pairs[block_name] = {}
+            pairs[block_name]["down"] = key
+        elif up_suffix in key:
+            block_name = key.replace(up_suffix, "")
+            if block_name not in pairs:
+                pairs[block_name] = {}
+            pairs[block_name]["up"] = key
+        elif alpha_suffix in key or key.endswith('.alpha'):
+            # Handle various alpha key formats
+            block_name = key.replace(alpha_suffix, "").replace(".alpha", "")
+            if block_name not in pairs:
+                pairs[block_name] = {}
+            pairs[block_name]["alpha"] = key
+    
+    return pairs
+
+
+def detect_lora_rank(handler: MemoryEfficientSafeOpen, pairs: Dict) -> Tuple[int, float]:
+    """
+    Detect the rank and alpha of an existing LoRA.
+    
+    Returns:
+        (network_dim, network_alpha)
+    """
+    network_dim = None
+    network_alpha = None
+    
+    for block_name, block_keys in pairs.items():
+        if "down" not in block_keys:
+            continue
+        
+        # Get dim from down weight shape
+        if network_dim is None:
+            down_key = block_keys["down"]
+            shape = handler.header[down_key]["shape"]
+            # Linear: [rank, in_features] or Conv: [rank, in_ch, k, k]
+            network_dim = shape[0]
+        
+        # Get alpha if present
+        if network_alpha is None and "alpha" in block_keys:
+            alpha_tensor = handler.get_tensor(block_keys["alpha"])
+            network_alpha = float(alpha_tensor.item())
+        
+        if network_dim is not None and network_alpha is not None:
+            break
+    
+    # Default alpha to dim if not found
+    if network_alpha is None:
+        network_alpha = float(network_dim) if network_dim else 1.0
+    if network_dim is None:
+        network_dim = 1
+    
+    return network_dim, network_alpha
+
+
+# =============================================================================
+# Merge Functions
+# =============================================================================
+
+def _merge_linear(lora_down: torch.Tensor, lora_up: torch.Tensor, device: str) -> torch.Tensor:
+    """Merge linear LoRA weights: lora_up @ lora_down."""
+    lora_down = lora_down.to(device=device, dtype=torch.float32)
+    lora_up = lora_up.to(device=device, dtype=torch.float32)
+    return lora_up @ lora_down
+
+
+def _merge_conv(lora_down: torch.Tensor, lora_up: torch.Tensor, device: str) -> torch.Tensor:
+    """Merge conv LoRA weights."""
+    in_rank, in_size, kernel_size, k_ = lora_down.shape
+    out_size, out_rank, _, _ = lora_up.shape
+    assert in_rank == out_rank, f"rank mismatch: {in_rank} vs {out_rank}"
+    
+    lora_down = lora_down.to(device=device, dtype=torch.float32)
+    lora_up = lora_up.to(device=device, dtype=torch.float32)
+    
+    merged = lora_up.reshape(out_size, -1) @ lora_down.reshape(in_rank, -1)
+    return merged.reshape(out_size, in_size, kernel_size, kernel_size)
+
+
+# =============================================================================
+# Extract Functions (after merge)
+# =============================================================================
+
+def _extract_linear(
+    weight: torch.Tensor,
+    max_rank: int,
+    dynamic_method: Optional[str],
+    dynamic_param: Optional[float],
+    scale: float,
+    niter: int = 2,
+) -> Dict:
+    """Extract LoRA from merged linear weight."""
+    out_size, in_size = weight.shape
+    
+    if dynamic_method is None:
+        # Fixed rank - use svd_lowrank for 10x speedup
+        rank = min(max_rank, min(out_size, in_size) - 1)
+        U, S, Vh = torch.svd_lowrank(weight, q=rank, niter=niter)
+        Vh = Vh.T  # svd_lowrank returns V, not Vh
+        new_rank = rank
+        new_alpha = float(scale * new_rank)
+        stats = {"sum_retained": 1.0, "fro_retained": 1.0}  # Not computed for lowrank
+    else:
+        # Dynamic methods need full SVD to compute rank from all singular values
+        U, S, Vh = linalg.svd(weight, full_matrices=False)
+        new_rank, new_alpha, stats = _compute_resize(S, max_rank, dynamic_method, dynamic_param, scale)
+        U = U[:, :new_rank]
+        S = S[:new_rank]
+        Vh = Vh[:new_rank, :]
+    
+    lora_up = U @ torch.diag(S)
+    lora_down = Vh
+    
+    return {
+        "lora_down": lora_down.cpu().contiguous(),
+        "lora_up": lora_up.cpu().contiguous(),
+        "new_rank": new_rank,
+        "new_alpha": new_alpha,
+        **stats
+    }
+
+
+def _extract_conv(
+    weight: torch.Tensor,
+    max_rank: int,
+    dynamic_method: Optional[str],
+    dynamic_param: Optional[float],
+    scale: float,
+    niter: int = 2,
+) -> Dict:
+    """Extract LoRA from merged conv weight."""
+    out_ch, in_ch, kh, kw = weight.shape
+    mat = weight.reshape(out_ch, -1)
+    
+    if dynamic_method is None:
+        # Fixed rank - use svd_lowrank for 10x speedup
+        rank = min(max_rank, min(mat.shape) - 1)
+        U, S, Vh = torch.svd_lowrank(mat, q=rank, niter=niter)
+        Vh = Vh.T  # svd_lowrank returns V, not Vh
+        new_rank = rank
+        new_alpha = float(scale * new_rank)
+        stats = {"sum_retained": 1.0, "fro_retained": 1.0}  # Not computed for lowrank
+    else:
+        # Dynamic methods need full SVD to compute rank from all singular values
+        U, S, Vh = linalg.svd(mat, full_matrices=False)
+        new_rank, new_alpha, stats = _compute_resize(S, max_rank, dynamic_method, dynamic_param, scale)
+        U = U[:, :new_rank]
+        S = S[:new_rank]
+        Vh = Vh[:new_rank, :]
+    
+    lora_up = (U @ torch.diag(S)).reshape(out_ch, new_rank, 1, 1)
+    lora_down = Vh.reshape(new_rank, in_ch, kh, kw)
+    
+    return {
+        "lora_down": lora_down.cpu().contiguous(),
+        "lora_up": lora_up.cpu().contiguous(),
+        "new_rank": new_rank,
+        "new_alpha": new_alpha,
+        **stats
+    }
+
+
+def _compute_resize(
+    S: torch.Tensor,
+    max_rank: int,
+    dynamic_method: Optional[str],
+    dynamic_param: Optional[float],
+    scale: float
+) -> Tuple[int, float, Dict]:
+    """Compute new rank and alpha based on resize method."""
+    
+    if dynamic_method == "sv_ratio" and dynamic_param is not None:
+        # Note: _index_sv_ratio uses S[0]*ratio, kohya uses S[0]/ratio
+        # Use kohya convention here for consistency with their tool
+        min_sv = S[0] / dynamic_param
+        new_rank = max(1, int(torch.sum(S > min_sv).item()))
+    elif dynamic_method == "sv_cumulative" and dynamic_param is not None:
+        new_rank = _index_sv_cumulative(S, dynamic_param)
+    elif dynamic_method == "sv_fro" and dynamic_param is not None:
+        new_rank = _index_sv_fro(S, dynamic_param)
+    else:
+        new_rank = max_rank
+    
+    # Clamp rank
+    if S[0] < MIN_SV:
+        new_rank = 1
+    else:
+        new_rank = max(1, min(new_rank, max_rank, len(S) - 1))
+    
+    new_alpha = float(scale * new_rank)
+    
+    # Compute retention stats
+    s_sum = float(torch.sum(torch.abs(S)))
+    s_rank = float(torch.sum(torch.abs(S[:new_rank]))) if new_rank <= len(S) else s_sum
+    
+    S_sq = S.pow(2)
+    s_fro = float(torch.sqrt(torch.sum(S_sq)))
+    s_red_fro = float(torch.sqrt(torch.sum(S_sq[:new_rank]))) if new_rank <= len(S) else s_fro
+    
+    stats = {
+        "sum_retained": s_rank / s_sum if s_sum > 0 else 1.0,
+        "fro_retained": s_red_fro / s_fro if s_fro > 0 else 1.0,
+    }
+    
+    return new_rank, new_alpha, stats
+
+
+# =============================================================================
+# Main Resize Function
+# =============================================================================
+
+def resize_lora_file(
+    lora_path: str,
+    new_rank: int,
+    dynamic_method: Optional[str],
+    dynamic_param: Optional[float],
+    device: str,
+    save_dtype: torch.dtype,
+    output_filename: str,
+    verbose: bool = True,
+    svd_niter: int = 2,
+) -> str:
+    """
+    Resize a LoRA file to a new rank.
+    
+    Args:
+        lora_path: Path to input LoRA
+        new_rank: Target rank (max rank for dynamic methods)
+        dynamic_method: None, "sv_ratio", "sv_fro", "sv_cumulative"
+        dynamic_param: Parameter for dynamic method
+        device: Processing device
+        save_dtype: Output dtype
+        output_filename: Output filename (without extension)
+        verbose: Print progress info
+        svd_niter: Power iterations for SVD accuracy
+    
+    Returns:
+        Path to saved resized LoRA
+    """
+    # Prepare memory
+    lora_size_gb = estimate_model_size(lora_path)
+    prepare_for_large_operation(lora_size_gb * 2, torch.device(device))
+    
+    handler = MemoryEfficientSafeOpen(lora_path)
+    
+    try:
+        metadata = handler.metadata().copy()
+        all_keys = handler.keys()
+        
+        # Detect format and extract pairs
+        format_info = detect_lora_format(all_keys)
+        pairs = extract_lora_pairs(all_keys, format_info)
+        network_dim, network_alpha = detect_lora_rank(handler, pairs)
+        
+        scale = network_alpha / network_dim if network_dim > 0 else 1.0
+        
+        if verbose:
+            method_str = f"{dynamic_method}: {dynamic_param}" if dynamic_method else "fixed"
+            print(f"[LoRA Resize] Format: {format_info['format']}, layers: {format_info['key_count']}")
+            print(f"[LoRA Resize] Original dim={network_dim}, alpha={network_alpha:.1f}, scale={scale:.3f}")
+            print(f"[LoRA Resize] Resizing with method={method_str}, max_rank={new_rank}")
+        
+        output_sd = {}
+        fro_list = []
+        pbar = comfy.utils.ProgressBar(len(pairs))
+        
+        with torch.no_grad():
+            for block_name, block_keys in tqdm(pairs.items(), desc="Resizing layers", unit="layers"):
+                if "down" not in block_keys or "up" not in block_keys:
+                    pbar.update(1)
+                    continue
+                
+                lora_down = handler.get_tensor(block_keys["down"])
+                lora_up = handler.get_tensor(block_keys["up"])
+                
+                is_conv = len(lora_down.shape) == 4
+                
+                # Transfer to GPU with pinned memory if available
+                if device == 'cuda':
+                    lora_down = transfer_to_gpu_pinned(lora_down, device, torch.float32)
+                    lora_up = transfer_to_gpu_pinned(lora_up, device, torch.float32)
+                
+                # Merge and re-extract
+                if is_conv:
+                    weight = _merge_conv(lora_down, lora_up, device)
+                    result = _extract_conv(weight, new_rank, dynamic_method, dynamic_param, scale, svd_niter)
+                else:
+                    weight = _merge_linear(lora_down, lora_up, device)
+                    result = _extract_linear(weight, new_rank, dynamic_method, dynamic_param, scale, svd_niter)
+                
+                del weight, lora_down, lora_up
+                
+                fro_list.append(result['fro_retained'])
+                
+                # Store using same format suffixes as input
+                down_suffix = format_info["down_suffix"]
+                up_suffix = format_info["up_suffix"]
+                alpha_suffix = format_info["alpha_suffix"]
+                
+                output_sd[f"{block_name}{down_suffix}"] = result["lora_down"].to(save_dtype)
+                output_sd[f"{block_name}{up_suffix}"] = result["lora_up"].to(save_dtype)
+                output_sd[f"{block_name}{alpha_suffix}"] = torch.tensor([result["new_alpha"]]).to(save_dtype)
+                
+                pbar.update(1)
+        
+        if verbose and fro_list:
+            import numpy as np
+            avg_fro = np.mean(fro_list)
+            std_fro = np.std(fro_list)
+            print(f"[LoRA Resize] Average Frobenius retention: {avg_fro:.1%} ± {std_fro:.3f}")
+        
+        # Update metadata
+        if dynamic_method:
+            metadata["ss_training_comment"] = f"Dynamic resize with {dynamic_method}: {dynamic_param} from dim {network_dim}"
+            metadata["ss_network_dim"] = "Dynamic"
+            metadata["ss_network_alpha"] = "Dynamic"
+        else:
+            metadata["ss_training_comment"] = f"Resized from dim {network_dim} to {new_rank}"
+            metadata["ss_network_dim"] = str(new_rank)
+            metadata["ss_network_alpha"] = str(scale * new_rank)
+        
+        # Save
+        output_dir = folder_paths.get_folder_paths("loras")[0]
+        os.makedirs(output_dir, exist_ok=True)
+        output_path = os.path.join(output_dir, f"{output_filename.strip()}.safetensors")
+        
+        save_file(output_sd, output_path, metadata)
+        print(f"[LoRA Resize] Saved to {output_path}")
+        
+        return output_path
+        
+    finally:
+        handler.__exit__(None, None, None)
+        cleanup_after_operation()
+
+
+# =============================================================================
+# Node Definitions
+# =============================================================================
+
+class LoRAResizeFixed(io.ComfyNode):
+    """Resize LoRA to a fixed rank."""
+    
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="LoRAResizeFixed",
+            display_name="LoRA Resize (Fixed Rank)",
+            category="ModelUtils/LoRA/Resize",
+            description="Resize existing LoRA to a specific rank by merging and re-extracting via SVD.",
+            inputs=[
+                io.Combo.Input("lora_name", options=folder_paths.get_filename_list("loras"),
+                              tooltip="LoRA to resize"),
+                io.Int.Input("new_rank", default=64, min=1, max=1024,
+                            tooltip="Target rank"),
+                io.Int.Input("svd_niter", default=2, min=0, max=10,
+                            tooltip="SVD power iterations (higher = more accurate but slower)"),
+                io.String.Input("output_filename", default="resized_lora"),
+                io.Combo.Input("save_dtype", options=["fp16", "bf16", "fp32"], default="fp16"),
+                io.Combo.Input("device", options=["cuda", "cpu"], default="cuda"),
+            ],
+            outputs=[io.String.Output(display_name="output_path")],
+            is_output_node=True,
+        )
+    
+    @classmethod
+    def execute(cls, lora_name, new_rank, svd_niter, output_filename, save_dtype, device) -> io.NodeOutput:
+        lora_path = folder_paths.get_full_path_or_raise("loras", lora_name)
+        dtype = {"fp16": torch.float16, "bf16": torch.bfloat16, "fp32": torch.float32}[save_dtype]
+        
+        path = resize_lora_file(lora_path, new_rank, None, None, device, dtype, output_filename, svd_niter=svd_niter)
+        return io.NodeOutput(path)
+
+
+class LoRAResizeRatio(io.ComfyNode):
+    """Resize LoRA keeping SVs above ratio threshold."""
+    
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="LoRAResizeRatio",
+            display_name="LoRA Resize (SV Ratio)",
+            category="ModelUtils/LoRA/Resize",
+            description="Dynamically resize LoRA, keeping singular values where S[i] > S[0]/ratio.",
+            inputs=[
+                io.Combo.Input("lora_name", options=folder_paths.get_filename_list("loras"),
+                              tooltip="LoRA to resize"),
+                io.Int.Input("max_rank", default=128, min=1, max=1024,
+                            tooltip="Maximum allowed rank"),
+                io.Float.Input("ratio", default=2.0, min=1.0, max=100.0, step=0.1,
+                              tooltip="Keep SVs where S[i] > S[0]/ratio"),
+                io.String.Input("output_filename", default="resized_lora_ratio"),
+                io.Combo.Input("save_dtype", options=["fp16", "bf16", "fp32"], default="fp16"),
+                io.Combo.Input("device", options=["cuda", "cpu"], default="cuda"),
+            ],
+            outputs=[io.String.Output(display_name="output_path")],
+            is_output_node=True,
+        )
+    
+    @classmethod
+    def execute(cls, lora_name, max_rank, ratio, output_filename, save_dtype, device) -> io.NodeOutput:
+        lora_path = folder_paths.get_full_path_or_raise("loras", lora_name)
+        dtype = {"fp16": torch.float16, "bf16": torch.bfloat16, "fp32": torch.float32}[save_dtype]
+        
+        path = resize_lora_file(lora_path, max_rank, "sv_ratio", ratio, device, dtype, output_filename)
+        return io.NodeOutput(path)
+
+
+class LoRAResizeFrobenius(io.ComfyNode):
+    """Resize LoRA to preserve Frobenius norm target."""
+    
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="LoRAResizeFrobenius",
+            display_name="LoRA Resize (Frobenius)",
+            category="ModelUtils/LoRA/Resize",
+            description="Dynamically resize LoRA to preserve target fraction of Frobenius norm.",
+            inputs=[
+                io.Combo.Input("lora_name", options=folder_paths.get_filename_list("loras"),
+                              tooltip="LoRA to resize"),
+                io.Int.Input("max_rank", default=128, min=1, max=1024,
+                            tooltip="Maximum allowed rank"),
+                io.Float.Input("target", default=0.9, min=0.1, max=1.0, step=0.01,
+                              tooltip="Target Frobenius norm retention (0.9 = 90%)"),
+                io.String.Input("output_filename", default="resized_lora_fro"),
+                io.Combo.Input("save_dtype", options=["fp16", "bf16", "fp32"], default="fp16"),
+                io.Combo.Input("device", options=["cuda", "cpu"], default="cuda"),
+            ],
+            outputs=[io.String.Output(display_name="output_path")],
+            is_output_node=True,
+        )
+    
+    @classmethod
+    def execute(cls, lora_name, max_rank, target, output_filename, save_dtype, device) -> io.NodeOutput:
+        lora_path = folder_paths.get_full_path_or_raise("loras", lora_name)
+        dtype = {"fp16": torch.float16, "bf16": torch.bfloat16, "fp32": torch.float32}[save_dtype]
+        
+        path = resize_lora_file(lora_path, max_rank, "sv_fro", target, device, dtype, output_filename)
+        return io.NodeOutput(path)
+
+
+class LoRAResizeCumulative(io.ComfyNode):
+    """Resize LoRA to preserve cumulative SV target."""
+    
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="LoRAResizeCumulative",
+            display_name="LoRA Resize (Cumulative)",
+            category="ModelUtils/LoRA/Resize",
+            description="Dynamically resize LoRA to preserve target fraction of cumulative singular values.",
+            inputs=[
+                io.Combo.Input("lora_name", options=folder_paths.get_filename_list("loras"),
+                              tooltip="LoRA to resize"),
+                io.Int.Input("max_rank", default=128, min=1, max=1024,
+                            tooltip="Maximum allowed rank"),
+                io.Float.Input("target", default=0.9, min=0.1, max=1.0, step=0.01,
+                              tooltip="Target cumulative SV retention (0.9 = 90%)"),
+                io.String.Input("output_filename", default="resized_lora_cumulative"),
+                io.Combo.Input("save_dtype", options=["fp16", "bf16", "fp32"], default="fp16"),
+                io.Combo.Input("device", options=["cuda", "cpu"], default="cuda"),
+            ],
+            outputs=[io.String.Output(display_name="output_path")],
+            is_output_node=True,
+        )
+    
+    @classmethod
+    def execute(cls, lora_name, max_rank, target, output_filename, save_dtype, device) -> io.NodeOutput:
+        lora_path = folder_paths.get_full_path_or_raise("loras", lora_name)
+        dtype = {"fp16": torch.float16, "bf16": torch.bfloat16, "fp32": torch.float32}[save_dtype]
+        
+        path = resize_lora_file(lora_path, max_rank, "sv_cumulative", target, device, dtype, output_filename)
+        return io.NodeOutput(path)

nodes/merger.py

@@ -0,0 +1,746 @@
+import os
+import re
+import torch
+import folder_paths
+import comfy.utils
+from tqdm import tqdm
+from comfy_api.latest import io
+from safetensors.torch import save_file
+from .merger_ops import TWO_MODEL_MODES, THREE_MODEL_MODES, MissingTensorBehavior, MissingTensorError
+from .merger_utils import MemoryEfficientSafeOpen, transfer_to_gpu_pinned
+from .device_utils import (
+    estimate_model_size, prepare_for_large_operation, cleanup_after_operation
+)
+
+
+def load_documentation_from_file(filename):
+    """Loads documentation from a markdown file in the ../docs/ directory."""
+    current_dir = os.path.dirname(os.path.realpath(__file__))
+    docs_path = os.path.join(current_dir, '..', 'docs', filename)
+    try:
+        with open(docs_path, 'r', encoding='utf-8') as f:
+            return f.read()
+    except FileNotFoundError:
+        return f"# Documentation File Not Found\n\nPlease ensure `{filename}` exists in the `docs` directory of the custom node."
+
+
+def _compile_patterns(pattern_string):
+    """Compiles whitespace-separated regex patterns into a list of compiled patterns.
+
+    Returns empty list if pattern_string is empty or whitespace-only.
+    Raises ValueError if any pattern is invalid regex.
+    """
+    if not pattern_string or not pattern_string.strip():
+        return []
+
+    patterns = []
+    for pattern in pattern_string.split():
+        try:
+            patterns.append(re.compile(pattern))
+        except re.error as e:
+            raise ValueError(f"Invalid regex pattern '{pattern}': {e}")
+    return patterns
+
+
+def _matches_any_pattern(key, patterns):
+    """Returns True if key matches any of the compiled regex patterns (substring search)."""
+    for pattern in patterns:
+        if pattern.search(key):
+            return True
+    return False
+
+
+class MergerLogic:
+    """Shared merge execution logic for all merger nodes."""
+
+    @staticmethod
+    def execute_merge(model_names, calc_mode, all_modes, recipe_params, model_type):
+        calc_mode_class = next((m for m in all_modes if m.name == calc_mode), None)
+        if not calc_mode_class:
+            raise ValueError(f"Calc mode '{calc_mode}' not found.")
+        primary_model_name = model_names.get('model_a')
+        if not primary_model_name or primary_model_name == "None":
+            raise ValueError("Model A is required to run the merge.")
+
+        # Prepare memory before heavy operation
+        total_size_gb = 0
+        model_paths = []
+        for name in model_names.values():
+            if name and name != "None":
+                path = folder_paths.get_full_path(model_type, name)
+                if path:
+                    total_size_gb += estimate_model_size(path)
+                    model_paths.append(path)
+
+        if total_size_gb > 0:
+            process_device = recipe_params.get('device', 'cpu')
+            print(f"[Merger] Preparing memory for {total_size_gb:.2f}GB merge operation...")
+            prepare_for_large_operation(total_size_gb * 1.2, torch.device(process_device))
+
+        handlers = {}
+        for name in model_names.values():
+            if name and name != "None":
+                path = folder_paths.get_full_path(model_type, name)
+                if not path:
+                    raise FileNotFoundError(f"Model '{name}' not found.")
+                handlers[name] = MemoryEfficientSafeOpen(path)
+
+        primary_handler = handlers[primary_model_name]
+        all_keys = primary_handler.keys()
+        metadata = primary_handler.header.get("__metadata__", {})
+
+        # Convert mismatch_mode string to enum
+        mismatch_mode_str = recipe_params.get('mismatch_mode', 'skip')
+        mismatch_mode = MissingTensorBehavior(mismatch_mode_str)
+        recipe_params['mismatch_mode'] = mismatch_mode
+
+        # Compile filter patterns
+        exclude_patterns = _compile_patterns(recipe_params.get('exclude_patterns', ''))
+        discard_patterns = _compile_patterns(recipe_params.get('discard_patterns', ''))
+
+        # Pre-compute key differences for logging
+        primary_keys = set(all_keys)
+        for name, handler in handlers.items():
+            if name != primary_model_name:
+                secondary_keys = set(handler.keys())
+                missing = primary_keys - secondary_keys
+                extra = secondary_keys - primary_keys
+                if missing:
+                    print(f"[Merger] {name} is missing {len(missing)} keys present in Model A")
+                if extra:
+                    print(f"[Merger] {name} has {len(extra)} extra keys not in Model A (ignored)")
+
+        merged_state_dict = {}
+        pbar = comfy.utils.ProgressBar(len(all_keys))
+        save_dtype = recipe_params.pop('save_dtype')
+        save_torch_dtype = {"fp32": torch.float32, "fp16": torch.float16, "bf16": torch.bfloat16}.get(save_dtype)
+        recipe_params.update({"handlers": handlers})
+        process_device = recipe_params.get('device', 'cpu')
+        process_dtype = recipe_params.get('dtype', torch.float32)
+
+        skipped_keys = 0
+        excluded_keys = 0
+        discarded_keys = 0
+        error_keys = []
+
+        for key in tqdm(all_keys, desc="Merging layers", unit="layers"):
+            # Check discard patterns first - skip entirely
+            if _matches_any_pattern(key, discard_patterns):
+                discarded_keys += 1
+                pbar.update(1)
+                continue
+
+            # Pre-load Model A's tensor with pinned memory for CUDA
+            cpu_tensor = primary_handler.get_tensor(key)
+            if process_device == 'cuda':
+                tensor_a = transfer_to_gpu_pinned(cpu_tensor, process_device, process_dtype)
+            else:
+                tensor_a = cpu_tensor.to(device=process_device, dtype=process_dtype)
+            del cpu_tensor
+
+            # Check exclude patterns - use Model A only, no merge
+            if _matches_any_pattern(key, exclude_patterns):
+                merged_state_dict[key] = tensor_a.to(save_torch_dtype).cpu().clone()
+                excluded_keys += 1
+                pbar.update(1)
+                continue
+
+            # Pass tensor_a metadata to recipes for zeros mode and fallback
+            recipe_params['_tensor_a'] = tensor_a
+            recipe_params['_tensor_a_shape'] = tensor_a.shape
+            recipe_params['_tensor_a_dtype'] = tensor_a.dtype
+
+            try:
+                recipe = calc_mode_class.create_recipe(key=key, **recipe_params)
+                result = recipe.merge()
+            except MissingTensorError as e:
+                if mismatch_mode == MissingTensorBehavior.ERROR:
+                    raise ValueError(f"Layer mismatch error (mismatch_mode='error'): {e}")
+                result = None
+                error_keys.append(key)
+
+            # Handle None result (mismatch occurred with skip mode)
+            if result is None:
+                result = tensor_a
+                skipped_keys += 1
+
+            if isinstance(result, dict):
+                for r_key, r_tensor in result.items():
+                    merged_state_dict[r_key] = r_tensor.to(save_torch_dtype).cpu().clone()
+            else:
+                merged_state_dict[key] = result.to(save_torch_dtype).cpu().clone()
+
+            # Clean up tensor_a reference to allow GC
+            del recipe_params['_tensor_a']
+            pbar.update(1)
+
+        # Log summary
+        if excluded_keys > 0:
+            print(f"[Merger] Excluded {excluded_keys} keys from merge (kept Model A only)")
+        if discarded_keys > 0:
+            print(f"[Merger] Discarded {discarded_keys} keys from output")
+        if skipped_keys > 0:
+            print(f"[Merger] Used Model A's values for {skipped_keys} keys due to mismatches")
+        if error_keys:
+            print(f"[Merger] Unexpected errors on {len(error_keys)} keys: {error_keys[:5]}{'...' if len(error_keys) > 5 else ''}")
+
+        for handler in handlers.values():
+            handler.__exit__(None, None, None)
+
+        output_folder = "loras" if calc_mode == "SVD LoRA Extraction" else model_type
+        # Use [-1] for diffusion_models to get the actual diffusion_models folder, not legacy unet
+        output_dir = folder_paths.get_folder_paths(output_folder)[-1]
+        os.makedirs(output_dir, exist_ok=True)
+        output_filename = recipe_params.get("output_filename")
+        output_path = os.path.join(output_dir, f"{output_filename}.safetensors")
+        save_file(merged_state_dict, output_path, metadata=metadata)
+
+        # Cleanup after heavy operation
+        del merged_state_dict
+        cleanup_after_operation()
+
+        return f"{output_filename}.safetensors"
+
+
+# --- Two-Model Merger Nodes ---
+
+class CheckpointTwoMerger(io.ComfyNode):
+    MODEL_TYPE = "checkpoints"
+
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="CheckpointTwoMerger",
+            display_name="Merge Checkpoints (2 Models)",
+            category="ModelUtils/Merging",
+            inputs=[
+                io.Combo.Input("execution_mode", options=["MERGE", "DOCUMENTATION ONLY"]),
+                io.Combo.Input("model_a", options=["None"] + folder_paths.get_filename_list("checkpoints")),
+                io.Combo.Input("model_b", options=["None"] + folder_paths.get_filename_list("checkpoints")),
+                io.Combo.Input("calc_mode", options=[m.name for m in TWO_MODEL_MODES]),
+                io.Combo.Input("mismatch_mode", options=["skip", "zeros", "error"], default="skip"),
+                io.Float.Input("alpha", default=0.5, min=-2.0, max=3.0, step=0.01),
+                io.Float.Input("beta", default=0.5, min=-2.0, max=3.0, step=0.01),
+                io.Float.Input("gamma", default=0.99, min=0.0, max=1.0, step=0.001),
+                io.Int.Input("seed", default=0, min=0, max=0xffffffffffffffff),
+                io.String.Input("output_filename", default="merged_2_checkpoint"),
+                io.Combo.Input("save_dtype", options=["fp32", "fp16", "bf16"]),
+                io.Combo.Input("process_device", options=["cuda", "cpu"]),
+                io.String.Input("exclude_patterns", default="", multiline=True),
+                io.String.Input("discard_patterns", default="", multiline=True),
+            ],
+            outputs=[
+                io.String.Output(display_name="output_filename"),
+                io.String.Output(display_name="documentation"),
+            ],
+        )
+
+    @classmethod
+    def execute(cls, execution_mode: str, model_a: str, model_b: str,
+                calc_mode: str, mismatch_mode: str, alpha: float, beta: float,
+                gamma: float, seed: int, output_filename: str, save_dtype: str,
+                process_device: str, exclude_patterns: str, discard_patterns: str) -> io.NodeOutput:
+        doc = load_documentation_from_file('merger_2_model_modes.md')
+        if execution_mode == "DOCUMENTATION ONLY":
+            return io.NodeOutput("Documentation mode active. No merge performed.", doc)
+
+        recipe_params = {
+            "model_a": model_a, "model_b": model_b, "calc_mode": calc_mode,
+            "mismatch_mode": mismatch_mode,
+            "alpha": alpha, "beta": beta, "gamma": gamma, "seed": seed,
+            "output_filename": output_filename, "save_dtype": save_dtype,
+            "device": process_device, "dtype": torch.float32,
+            "exclude_patterns": exclude_patterns, "discard_patterns": discard_patterns,
+        }
+        model_names = {"model_a": model_a, "model_b": model_b}
+        filename = MergerLogic.execute_merge(model_names, calc_mode, TWO_MODEL_MODES, recipe_params, cls.MODEL_TYPE)
+        return io.NodeOutput(filename, doc)
+
+
+class ModelTwoMerger(io.ComfyNode):
+    MODEL_TYPE = "diffusion_models"
+
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="ModelTwoMerger",
+            display_name="Merge Models (2 Models)",
+            category="ModelUtils/Merging",
+            inputs=[
+                io.Combo.Input("execution_mode", options=["MERGE", "DOCUMENTATION ONLY"]),
+                io.Combo.Input("model_a", options=["None"] + folder_paths.get_filename_list("diffusion_models")),
+                io.Combo.Input("model_b", options=["None"] + folder_paths.get_filename_list("diffusion_models")),
+                io.Combo.Input("calc_mode", options=[m.name for m in TWO_MODEL_MODES]),
+                io.Combo.Input("mismatch_mode", options=["skip", "zeros", "error"], default="skip"),
+                io.Float.Input("alpha", default=0.5, min=-2.0, max=3.0, step=0.01),
+                io.Float.Input("beta", default=0.5, min=-2.0, max=3.0, step=0.01),
+                io.Float.Input("gamma", default=0.99, min=0.0, max=1.0, step=0.001),
+                io.Int.Input("seed", default=0, min=0, max=0xffffffffffffffff),
+                io.String.Input("output_filename", default="merged_2_model"),
+                io.Combo.Input("save_dtype", options=["fp32", "fp16", "bf16"]),
+                io.Combo.Input("process_device", options=["cuda", "cpu"]),
+                io.String.Input("exclude_patterns", default="", multiline=True),
+                io.String.Input("discard_patterns", default="", multiline=True),
+            ],
+            outputs=[
+                io.String.Output(display_name="output_filename"),
+                io.String.Output(display_name="documentation"),
+            ],
+        )
+
+    @classmethod
+    def execute(cls, execution_mode: str, model_a: str, model_b: str,
+                calc_mode: str, mismatch_mode: str, alpha: float, beta: float,
+                gamma: float, seed: int, output_filename: str, save_dtype: str,
+                process_device: str, exclude_patterns: str, discard_patterns: str) -> io.NodeOutput:
+        doc = load_documentation_from_file('merger_2_model_modes.md')
+        if execution_mode == "DOCUMENTATION ONLY":
+            return io.NodeOutput("Documentation mode active. No merge performed.", doc)
+
+        recipe_params = {
+            "model_a": model_a, "model_b": model_b, "calc_mode": calc_mode,
+            "mismatch_mode": mismatch_mode,
+            "alpha": alpha, "beta": beta, "gamma": gamma, "seed": seed,
+            "output_filename": output_filename, "save_dtype": save_dtype,
+            "device": process_device, "dtype": torch.float32,
+            "exclude_patterns": exclude_patterns, "discard_patterns": discard_patterns,
+        }
+        model_names = {"model_a": model_a, "model_b": model_b}
+        filename = MergerLogic.execute_merge(model_names, calc_mode, TWO_MODEL_MODES, recipe_params, cls.MODEL_TYPE)
+        return io.NodeOutput(filename, doc)
+
+
+class TextEncoderTwoMerger(io.ComfyNode):
+    MODEL_TYPE = "text_encoders"
+
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="TextEncoderTwoMerger",
+            display_name="Merge Text Encoders (2 Models)",
+            category="ModelUtils/Merging",
+            inputs=[
+                io.Combo.Input("execution_mode", options=["MERGE", "DOCUMENTATION ONLY"]),
+                io.Combo.Input("model_a", options=["None"] + folder_paths.get_filename_list("text_encoders")),
+                io.Combo.Input("model_b", options=["None"] + folder_paths.get_filename_list("text_encoders")),
+                io.Combo.Input("calc_mode", options=[m.name for m in TWO_MODEL_MODES]),
+                io.Combo.Input("mismatch_mode", options=["skip", "zeros", "error"], default="skip"),
+                io.Float.Input("alpha", default=0.5, min=-2.0, max=3.0, step=0.01),
+                io.Float.Input("beta", default=0.5, min=-2.0, max=3.0, step=0.01),
+                io.Float.Input("gamma", default=0.99, min=0.0, max=1.0, step=0.001),
+                io.Int.Input("seed", default=0, min=0, max=0xffffffffffffffff),
+                io.String.Input("output_filename", default="merged_2_textencoder"),
+                io.Combo.Input("save_dtype", options=["fp32", "fp16", "bf16"]),
+                io.Combo.Input("process_device", options=["cuda", "cpu"]),
+                io.String.Input("exclude_patterns", default="", multiline=True),
+                io.String.Input("discard_patterns", default="", multiline=True),
+            ],
+            outputs=[
+                io.String.Output(display_name="output_filename"),
+                io.String.Output(display_name="documentation"),
+            ],
+        )
+
+    @classmethod
+    def execute(cls, execution_mode: str, model_a: str, model_b: str,
+                calc_mode: str, mismatch_mode: str, alpha: float, beta: float,
+                gamma: float, seed: int, output_filename: str, save_dtype: str,
+                process_device: str, exclude_patterns: str, discard_patterns: str) -> io.NodeOutput:
+        doc = load_documentation_from_file('merger_2_model_modes.md')
+        if execution_mode == "DOCUMENTATION ONLY":
+            return io.NodeOutput("Documentation mode active. No merge performed.", doc)
+
+        recipe_params = {
+            "model_a": model_a, "model_b": model_b, "calc_mode": calc_mode,
+            "mismatch_mode": mismatch_mode,
+            "alpha": alpha, "beta": beta, "gamma": gamma, "seed": seed,
+            "output_filename": output_filename, "save_dtype": save_dtype,
+            "device": process_device, "dtype": torch.float32,
+            "exclude_patterns": exclude_patterns, "discard_patterns": discard_patterns,
+        }
+        model_names = {"model_a": model_a, "model_b": model_b}
+        filename = MergerLogic.execute_merge(model_names, calc_mode, TWO_MODEL_MODES, recipe_params, cls.MODEL_TYPE)
+        return io.NodeOutput(filename, doc)
+
+
+class LoRATwoMerger(io.ComfyNode):
+    MODEL_TYPE = "loras"
+
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="LoRATwoMerger",
+            display_name="Merge LoRAs (2 Models)",
+            category="ModelUtils/Merging",
+            inputs=[
+                io.Combo.Input("execution_mode", options=["MERGE", "DOCUMENTATION ONLY"]),
+                io.Combo.Input("model_a", options=["None"] + folder_paths.get_filename_list("loras")),
+                io.Combo.Input("model_b", options=["None"] + folder_paths.get_filename_list("loras")),
+                io.Combo.Input("calc_mode", options=[m.name for m in TWO_MODEL_MODES]),
+                io.Combo.Input("mismatch_mode", options=["skip", "zeros", "error"], default="skip"),
+                io.Float.Input("alpha", default=0.5, min=-2.0, max=3.0, step=0.01),
+                io.Float.Input("beta", default=0.5, min=-2.0, max=3.0, step=0.01),
+                io.Float.Input("gamma", default=0.99, min=0.0, max=1.0, step=0.001),
+                io.Int.Input("seed", default=0, min=0, max=0xffffffffffffffff),
+                io.String.Input("output_filename", default="merged_2_lora"),
+                io.Combo.Input("save_dtype", options=["fp32", "fp16", "bf16"]),
+                io.Combo.Input("process_device", options=["cuda", "cpu"]),
+                io.String.Input("exclude_patterns", default="", multiline=True),
+                io.String.Input("discard_patterns", default="", multiline=True),
+            ],
+            outputs=[
+                io.String.Output(display_name="output_filename"),
+                io.String.Output(display_name="documentation"),
+            ],
+        )
+
+    @classmethod
+    def execute(cls, execution_mode: str, model_a: str, model_b: str,
+                calc_mode: str, mismatch_mode: str, alpha: float, beta: float,
+                gamma: float, seed: int, output_filename: str, save_dtype: str,
+                process_device: str, exclude_patterns: str, discard_patterns: str) -> io.NodeOutput:
+        doc = load_documentation_from_file('merger_2_model_modes.md')
+        if execution_mode == "DOCUMENTATION ONLY":
+            return io.NodeOutput("Documentation mode active. No merge performed.", doc)
+
+        recipe_params = {
+            "model_a": model_a, "model_b": model_b, "calc_mode": calc_mode,
+            "mismatch_mode": mismatch_mode,
+            "alpha": alpha, "beta": beta, "gamma": gamma, "seed": seed,
+            "output_filename": output_filename, "save_dtype": save_dtype,
+            "device": process_device, "dtype": torch.float32,
+            "exclude_patterns": exclude_patterns, "discard_patterns": discard_patterns,
+        }
+        model_names = {"model_a": model_a, "model_b": model_b}
+        filename = MergerLogic.execute_merge(model_names, calc_mode, TWO_MODEL_MODES, recipe_params, cls.MODEL_TYPE)
+        return io.NodeOutput(filename, doc)
+
+
+class EmbeddingTwoMerger(io.ComfyNode):
+    MODEL_TYPE = "embeddings"
+
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="EmbeddingTwoMerger",
+            display_name="Merge Embeddings (2 Models)",
+            category="ModelUtils/Merging",
+            inputs=[
+                io.Combo.Input("execution_mode", options=["MERGE", "DOCUMENTATION ONLY"]),
+                io.Combo.Input("model_a", options=["None"] + folder_paths.get_filename_list("embeddings")),
+                io.Combo.Input("model_b", options=["None"] + folder_paths.get_filename_list("embeddings")),
+                io.Combo.Input("calc_mode", options=[m.name for m in TWO_MODEL_MODES]),
+                io.Combo.Input("mismatch_mode", options=["skip", "zeros", "error"], default="skip"),
+                io.Float.Input("alpha", default=0.5, min=-2.0, max=3.0, step=0.01),
+                io.Float.Input("beta", default=0.5, min=-2.0, max=3.0, step=0.01),
+                io.Float.Input("gamma", default=0.99, min=0.0, max=1.0, step=0.001),
+                io.Int.Input("seed", default=0, min=0, max=0xffffffffffffffff),
+                io.String.Input("output_filename", default="merged_2_embedding"),
+                io.Combo.Input("save_dtype", options=["fp32", "fp16", "bf16"]),
+                io.Combo.Input("process_device", options=["cuda", "cpu"]),
+                io.String.Input("exclude_patterns", default="", multiline=True),
+                io.String.Input("discard_patterns", default="", multiline=True),
+            ],
+            outputs=[
+                io.String.Output(display_name="output_filename"),
+                io.String.Output(display_name="documentation"),
+            ],
+        )
+
+    @classmethod
+    def execute(cls, execution_mode: str, model_a: str, model_b: str,
+                calc_mode: str, mismatch_mode: str, alpha: float, beta: float,
+                gamma: float, seed: int, output_filename: str, save_dtype: str,
+                process_device: str, exclude_patterns: str, discard_patterns: str) -> io.NodeOutput:
+        doc = load_documentation_from_file('merger_2_model_modes.md')
+        if execution_mode == "DOCUMENTATION ONLY":
+            return io.NodeOutput("Documentation mode active. No merge performed.", doc)
+
+        recipe_params = {
+            "model_a": model_a, "model_b": model_b, "calc_mode": calc_mode,
+            "mismatch_mode": mismatch_mode,
+            "alpha": alpha, "beta": beta, "gamma": gamma, "seed": seed,
+            "output_filename": output_filename, "save_dtype": save_dtype,
+            "device": process_device, "dtype": torch.float32,
+            "exclude_patterns": exclude_patterns, "discard_patterns": discard_patterns,
+        }
+        model_names = {"model_a": model_a, "model_b": model_b}
+        filename = MergerLogic.execute_merge(model_names, calc_mode, TWO_MODEL_MODES, recipe_params, cls.MODEL_TYPE)
+        return io.NodeOutput(filename, doc)
+
+
+# --- Three-Model Merger Nodes ---
+
+class CheckpointThreeMerger(io.ComfyNode):
+    MODEL_TYPE = "checkpoints"
+
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="CheckpointThreeMerger",
+            display_name="Merge Checkpoints (3 Models)",
+            category="ModelUtils/Merging",
+            inputs=[
+                io.Combo.Input("execution_mode", options=["MERGE", "DOCUMENTATION ONLY"]),
+                io.Combo.Input("model_a", options=["None"] + folder_paths.get_filename_list("checkpoints")),
+                io.Combo.Input("model_b", options=["None"] + folder_paths.get_filename_list("checkpoints")),
+                io.Combo.Input("model_c", options=["None"] + folder_paths.get_filename_list("checkpoints")),
+                io.Combo.Input("calc_mode", options=[m.name for m in THREE_MODEL_MODES]),
+                io.Combo.Input("mismatch_mode", options=["skip", "zeros", "error"], default="skip"),
+                io.Float.Input("alpha", default=0.5, min=-2.0, max=3.0, step=0.01),
+                io.Float.Input("beta", default=0.5, min=-2.0, max=3.0, step=0.01),
+                io.Float.Input("gamma", default=0.5, min=-2.0, max=3.0, step=0.01),
+                io.Float.Input("delta", default=0.5, min=-2.0, max=3.0, step=0.01),
+                io.Int.Input("seed", default=0, min=0, max=0xffffffffffffffff),
+                io.String.Input("output_filename", default="merged_3_checkpoint"),
+                io.Combo.Input("save_dtype", options=["fp32", "fp16", "bf16"]),
+                io.Combo.Input("process_device", options=["cuda", "cpu"]),
+                io.String.Input("exclude_patterns", default="", multiline=True),
+                io.String.Input("discard_patterns", default="", multiline=True),
+            ],
+            outputs=[
+                io.String.Output(display_name="output_filename"),
+                io.String.Output(display_name="documentation"),
+            ],
+        )
+
+    @classmethod
+    def execute(cls, execution_mode: str, model_a: str, model_b: str, model_c: str,
+                calc_mode: str, mismatch_mode: str, alpha: float, beta: float,
+                gamma: float, delta: float, seed: int, output_filename: str, save_dtype: str,
+                process_device: str, exclude_patterns: str, discard_patterns: str) -> io.NodeOutput:
+        doc = load_documentation_from_file('merger_3_model_modes.md')
+        if execution_mode == "DOCUMENTATION ONLY":
+            return io.NodeOutput("Documentation mode active. No merge performed.", doc)
+
+        recipe_params = {
+            "model_a": model_a, "model_b": model_b, "model_c": model_c, "calc_mode": calc_mode,
+            "mismatch_mode": mismatch_mode,
+            "alpha": alpha, "beta": beta, "gamma": gamma, "delta": delta, "seed": seed,
+            "output_filename": output_filename, "save_dtype": save_dtype,
+            "device": process_device, "dtype": torch.float32,
+            "exclude_patterns": exclude_patterns, "discard_patterns": discard_patterns,
+        }
+        model_names = {"model_a": model_a, "model_b": model_b, "model_c": model_c}
+        filename = MergerLogic.execute_merge(model_names, calc_mode, THREE_MODEL_MODES, recipe_params, cls.MODEL_TYPE)
+        return io.NodeOutput(filename, doc)
+
+
+class ModelThreeMerger(io.ComfyNode):
+    MODEL_TYPE = "diffusion_models"
+
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="ModelThreeMerger",
+            display_name="Merge Models (3 Models)",
+            category="ModelUtils/Merging",
+            inputs=[
+                io.Combo.Input("execution_mode", options=["MERGE", "DOCUMENTATION ONLY"]),
+                io.Combo.Input("model_a", options=["None"] + folder_paths.get_filename_list("diffusion_models")),
+                io.Combo.Input("model_b", options=["None"] + folder_paths.get_filename_list("diffusion_models")),
+                io.Combo.Input("model_c", options=["None"] + folder_paths.get_filename_list("diffusion_models")),
+                io.Combo.Input("calc_mode", options=[m.name for m in THREE_MODEL_MODES]),
+                io.Combo.Input("mismatch_mode", options=["skip", "zeros", "error"], default="skip"),
+                io.Float.Input("alpha", default=0.5, min=-2.0, max=3.0, step=0.01),
+                io.Float.Input("beta", default=0.5, min=-2.0, max=3.0, step=0.01),
+                io.Float.Input("gamma", default=0.5, min=-2.0, max=3.0, step=0.01),
+                io.Float.Input("delta", default=0.5, min=-2.0, max=3.0, step=0.01),
+                io.Int.Input("seed", default=0, min=0, max=0xffffffffffffffff),
+                io.String.Input("output_filename", default="merged_3_model"),
+                io.Combo.Input("save_dtype", options=["fp32", "fp16", "bf16"]),
+                io.Combo.Input("process_device", options=["cuda", "cpu"]),
+                io.String.Input("exclude_patterns", default="", multiline=True),
+                io.String.Input("discard_patterns", default="", multiline=True),
+            ],
+            outputs=[
+                io.String.Output(display_name="output_filename"),
+                io.String.Output(display_name="documentation"),
+            ],
+        )
+
+    @classmethod
+    def execute(cls, execution_mode: str, model_a: str, model_b: str, model_c: str,
+                calc_mode: str, mismatch_mode: str, alpha: float, beta: float,
+                gamma: float, delta: float, seed: int, output_filename: str, save_dtype: str,
+                process_device: str, exclude_patterns: str, discard_patterns: str) -> io.NodeOutput:
+        doc = load_documentation_from_file('merger_3_model_modes.md')
+        if execution_mode == "DOCUMENTATION ONLY":
+            return io.NodeOutput("Documentation mode active. No merge performed.", doc)
+
+        recipe_params = {
+            "model_a": model_a, "model_b": model_b, "model_c": model_c, "calc_mode": calc_mode,
+            "mismatch_mode": mismatch_mode,
+            "alpha": alpha, "beta": beta, "gamma": gamma, "delta": delta, "seed": seed,
+            "output_filename": output_filename, "save_dtype": save_dtype,
+            "device": process_device, "dtype": torch.float32,
+            "exclude_patterns": exclude_patterns, "discard_patterns": discard_patterns,
+        }
+        model_names = {"model_a": model_a, "model_b": model_b, "model_c": model_c}
+        filename = MergerLogic.execute_merge(model_names, calc_mode, THREE_MODEL_MODES, recipe_params, cls.MODEL_TYPE)
+        return io.NodeOutput(filename, doc)
+
+
+class TextEncoderThreeMerger(io.ComfyNode):
+    MODEL_TYPE = "text_encoders"
+
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="TextEncoderThreeMerger",
+            display_name="Merge Text Encoders (3 Models)",
+            category="ModelUtils/Merging",
+            inputs=[
+                io.Combo.Input("execution_mode", options=["MERGE", "DOCUMENTATION ONLY"]),
+                io.Combo.Input("model_a", options=["None"] + folder_paths.get_filename_list("text_encoders")),
+                io.Combo.Input("model_b", options=["None"] + folder_paths.get_filename_list("text_encoders")),
+                io.Combo.Input("model_c", options=["None"] + folder_paths.get_filename_list("text_encoders")),
+                io.Combo.Input("calc_mode", options=[m.name for m in THREE_MODEL_MODES]),
+                io.Combo.Input("mismatch_mode", options=["skip", "zeros", "error"], default="skip"),
+                io.Float.Input("alpha", default=0.5, min=-2.0, max=3.0, step=0.01),
+                io.Float.Input("beta", default=0.5, min=-2.0, max=3.0, step=0.01),
+                io.Float.Input("gamma", default=0.5, min=-2.0, max=3.0, step=0.01),
+                io.Float.Input("delta", default=0.5, min=-2.0, max=3.0, step=0.01),
+                io.Int.Input("seed", default=0, min=0, max=0xffffffffffffffff),
+                io.String.Input("output_filename", default="merged_3_textencoder"),
+                io.Combo.Input("save_dtype", options=["fp32", "fp16", "bf16"]),
+                io.Combo.Input("process_device", options=["cuda", "cpu"]),
+                io.String.Input("exclude_patterns", default="", multiline=True),
+                io.String.Input("discard_patterns", default="", multiline=True),
+            ],
+            outputs=[
+                io.String.Output(display_name="output_filename"),
+                io.String.Output(display_name="documentation"),
+            ],
+        )
+
+    @classmethod
+    def execute(cls, execution_mode: str, model_a: str, model_b: str, model_c: str,
+                calc_mode: str, mismatch_mode: str, alpha: float, beta: float,
+                gamma: float, delta: float, seed: int, output_filename: str, save_dtype: str,
+                process_device: str, exclude_patterns: str, discard_patterns: str) -> io.NodeOutput:
+        doc = load_documentation_from_file('merger_3_model_modes.md')
+        if execution_mode == "DOCUMENTATION ONLY":
+            return io.NodeOutput("Documentation mode active. No merge performed.", doc)
+
+        recipe_params = {
+            "model_a": model_a, "model_b": model_b, "model_c": model_c, "calc_mode": calc_mode,
+            "mismatch_mode": mismatch_mode,
+            "alpha": alpha, "beta": beta, "gamma": gamma, "delta": delta, "seed": seed,
+            "output_filename": output_filename, "save_dtype": save_dtype,
+            "device": process_device, "dtype": torch.float32,
+            "exclude_patterns": exclude_patterns, "discard_patterns": discard_patterns,
+        }
+        model_names = {"model_a": model_a, "model_b": model_b, "model_c": model_c}
+        filename = MergerLogic.execute_merge(model_names, calc_mode, THREE_MODEL_MODES, recipe_params, cls.MODEL_TYPE)
+        return io.NodeOutput(filename, doc)
+
+
+class LoRAThreeMerger(io.ComfyNode):
+    MODEL_TYPE = "loras"
+
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="LoRAThreeMerger",
+            display_name="Merge LoRAs (3 Models)",
+            category="ModelUtils/Merging",
+            inputs=[
+                io.Combo.Input("execution_mode", options=["MERGE", "DOCUMENTATION ONLY"]),
+                io.Combo.Input("model_a", options=["None"] + folder_paths.get_filename_list("loras")),
+                io.Combo.Input("model_b", options=["None"] + folder_paths.get_filename_list("loras")),
+                io.Combo.Input("model_c", options=["None"] + folder_paths.get_filename_list("loras")),
+                io.Combo.Input("calc_mode", options=[m.name for m in THREE_MODEL_MODES]),
+                io.Combo.Input("mismatch_mode", options=["skip", "zeros", "error"], default="skip"),
+                io.Float.Input("alpha", default=0.5, min=-2.0, max=3.0, step=0.01),
+                io.Float.Input("beta", default=0.5, min=-2.0, max=3.0, step=0.01),
+                io.Float.Input("gamma", default=0.5, min=-2.0, max=3.0, step=0.01),
+                io.Float.Input("delta", default=0.5, min=-2.0, max=3.0, step=0.01),
+                io.Int.Input("seed", default=0, min=0, max=0xffffffffffffffff),
+                io.String.Input("output_filename", default="merged_3_lora"),
+                io.Combo.Input("save_dtype", options=["fp32", "fp16", "bf16"]),
+                io.Combo.Input("process_device", options=["cuda", "cpu"]),
+                io.String.Input("exclude_patterns", default="", multiline=True),
+                io.String.Input("discard_patterns", default="", multiline=True),
+            ],
+            outputs=[
+                io.String.Output(display_name="output_filename"),
+                io.String.Output(display_name="documentation"),
+            ],
+        )
+
+    @classmethod
+    def execute(cls, execution_mode: str, model_a: str, model_b: str, model_c: str,
+                calc_mode: str, mismatch_mode: str, alpha: float, beta: float,
+                gamma: float, delta: float, seed: int, output_filename: str, save_dtype: str,
+                process_device: str, exclude_patterns: str, discard_patterns: str) -> io.NodeOutput:
+        doc = load_documentation_from_file('merger_3_model_modes.md')
+        if execution_mode == "DOCUMENTATION ONLY":
+            return io.NodeOutput("Documentation mode active. No merge performed.", doc)
+
+        recipe_params = {
+            "model_a": model_a, "model_b": model_b, "model_c": model_c, "calc_mode": calc_mode,
+            "mismatch_mode": mismatch_mode,
+            "alpha": alpha, "beta": beta, "gamma": gamma, "delta": delta, "seed": seed,
+            "output_filename": output_filename, "save_dtype": save_dtype,
+            "device": process_device, "dtype": torch.float32,
+            "exclude_patterns": exclude_patterns, "discard_patterns": discard_patterns,
+        }
+        model_names = {"model_a": model_a, "model_b": model_b, "model_c": model_c}
+        filename = MergerLogic.execute_merge(model_names, calc_mode, THREE_MODEL_MODES, recipe_params, cls.MODEL_TYPE)
+        return io.NodeOutput(filename, doc)
+
+
+class EmbeddingThreeMerger(io.ComfyNode):
+    MODEL_TYPE = "embeddings"
+
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="EmbeddingThreeMerger",
+            display_name="Merge Embeddings (3 Models)",
+            category="ModelUtils/Merging",
+            inputs=[
+                io.Combo.Input("execution_mode", options=["MERGE", "DOCUMENTATION ONLY"]),
+                io.Combo.Input("model_a", options=["None"] + folder_paths.get_filename_list("embeddings")),
+                io.Combo.Input("model_b", options=["None"] + folder_paths.get_filename_list("embeddings")),
+                io.Combo.Input("model_c", options=["None"] + folder_paths.get_filename_list("embeddings")),
+                io.Combo.Input("calc_mode", options=[m.name for m in THREE_MODEL_MODES]),
+                io.Combo.Input("mismatch_mode", options=["skip", "zeros", "error"], default="skip"),
+                io.Float.Input("alpha", default=0.5, min=-2.0, max=3.0, step=0.01),
+                io.Float.Input("beta", default=0.5, min=-2.0, max=3.0, step=0.01),
+                io.Float.Input("gamma", default=0.5, min=-2.0, max=3.0, step=0.01),
+                io.Float.Input("delta", default=0.5, min=-2.0, max=3.0, step=0.01),
+                io.Int.Input("seed", default=0, min=0, max=0xffffffffffffffff),
+                io.String.Input("output_filename", default="merged_3_embedding"),
+                io.Combo.Input("save_dtype", options=["fp32", "fp16", "bf16"]),
+                io.Combo.Input("process_device", options=["cuda", "cpu"]),
+                io.String.Input("exclude_patterns", default="", multiline=True),
+                io.String.Input("discard_patterns", default="", multiline=True),
+            ],
+            outputs=[
+                io.String.Output(display_name="output_filename"),
+                io.String.Output(display_name="documentation"),
+            ],
+        )
+
+    @classmethod
+    def execute(cls, execution_mode: str, model_a: str, model_b: str, model_c: str,
+                calc_mode: str, mismatch_mode: str, alpha: float, beta: float,
+                gamma: float, delta: float, seed: int, output_filename: str, save_dtype: str,
+                process_device: str, exclude_patterns: str, discard_patterns: str) -> io.NodeOutput:
+        doc = load_documentation_from_file('merger_3_model_modes.md')
+        if execution_mode == "DOCUMENTATION ONLY":
+            return io.NodeOutput("Documentation mode active. No merge performed.", doc)
+
+        recipe_params = {
+            "model_a": model_a, "model_b": model_b, "model_c": model_c, "calc_mode": calc_mode,
+            "mismatch_mode": mismatch_mode,
+            "alpha": alpha, "beta": beta, "gamma": gamma, "delta": delta, "seed": seed,
+            "output_filename": output_filename, "save_dtype": save_dtype,
+            "device": process_device, "dtype": torch.float32,
+            "exclude_patterns": exclude_patterns, "discard_patterns": discard_patterns,
+        }
+        model_names = {"model_a": model_a, "model_b": model_b, "model_c": model_c}
+        filename = MergerLogic.execute_merge(model_names, calc_mode, THREE_MODEL_MODES, recipe_params, cls.MODEL_TYPE)
+        return io.NodeOutput(filename, doc)

nodes/merger_ops.py

@@ -0,0 +1,408 @@
+import torch
+import scipy.ndimage
+import torch.nn.functional as F
+from enum import Enum
+
+
+class MissingTensorBehavior(Enum):
+    """Controls behavior when a tensor key is missing from a model."""
+    ERROR = "error"      # Raise exception (strict mode)
+    SKIP = "skip"        # Return None, let caller handle
+    ZEROS = "zeros"      # Return zeros tensor matching shape from primary model
+
+
+class MissingTensorError(Exception):
+    """Raised when a tensor is missing and behavior is ERROR."""
+    pass
+
+# ################# #
+# MERGE OPERATORS
+# ################# #
+class Operation:
+    def __init__(self, key, *sources):
+        self.key = key
+        self.sources = tuple(sources)
+        self.merge_func = self.recurse
+        self.alpha = None
+        self.beta = None
+        self.gamma = None
+        self.delta = None
+        self.seed = None
+
+    def __eq__(self, other):
+        return (type(self), self.key, self.alpha, self.beta, self.gamma, self.delta, self.seed, self.sources) == \
+               (type(other), other.key, other.alpha, other.beta, other.gamma, other.delta, other.seed, other.sources)
+
+    def __hash__(self):
+        return hash((type(self), self.key, self.alpha, self.beta, self.gamma, self.delta, self.seed, self.sources))
+
+    def oper(self, *args) -> torch.Tensor:
+        raise NotImplementedError
+
+    def recurse(self, operation):
+        source_tensors = [source_oper.merge() for source_oper in operation.sources]
+        return operation.oper(*source_tensors)
+
+    def merge(self):
+        return self.merge_func(self)
+
+class LoadTensor(Operation):
+    def __init__(self, key, model_name, handlers, device, dtype,
+                 on_missing=MissingTensorBehavior.ERROR, fallback_shape=None, fallback_dtype=None):
+        super().__init__(key)
+        self.model_name = model_name
+        self.handlers = handlers
+        self.device = device
+        self.dtype = dtype
+        self.on_missing = on_missing
+        self.fallback_shape = fallback_shape
+        self.fallback_dtype = fallback_dtype
+
+    def merge(self) -> torch.Tensor:
+        if self.model_name not in self.handlers:
+            raise ValueError(f"Model '{self.model_name}' is required for this mode but was not provided.")
+
+        handler = self.handlers[self.model_name]
+        if self.key not in handler.keys():
+            if self.on_missing == MissingTensorBehavior.ERROR:
+                raise MissingTensorError(
+                    f"Key '{self.key}' not found in model '{self.model_name}'"
+                )
+            elif self.on_missing == MissingTensorBehavior.SKIP:
+                return None
+            elif self.on_missing == MissingTensorBehavior.ZEROS:
+                if self.fallback_shape is None:
+                    raise ValueError(
+                        f"Cannot create zeros for '{self.key}' without fallback_shape"
+                    )
+                dtype = self.fallback_dtype if self.fallback_dtype else self.dtype
+                return torch.zeros(self.fallback_shape, device=self.device, dtype=dtype)
+
+        return handler.get_tensor(self.key).to(device=self.device, dtype=self.dtype)
+
+class Multiply(Operation):
+    def __init__(self, key, alpha, *sources):
+        super().__init__(key, *sources)
+        self.alpha = alpha
+    def oper(self, a) -> torch.Tensor:
+        if a is None:
+            return None
+        return a * self.alpha
+
+
+class Add(Operation):
+    def oper(self, a, b) -> torch.Tensor:
+        if a is None:
+            return b
+        if b is None:
+            return a
+        return a + b
+
+
+class Sub(Operation):
+    def oper(self, a, b) -> torch.Tensor:
+        if a is None or b is None:
+            return None  # Cannot compute difference with missing operand
+        return a - b
+
+class SVD(Operation):
+    def __init__(self, key, alpha, beta, gamma, *sources):
+        super().__init__(key, *sources)
+        self.alpha, self.beta, self.gamma = int(alpha), int(beta), gamma
+    def oper(self, a, b) -> torch.Tensor:
+        if a is None or b is None:
+            return None
+        diff, weights, conv2d = a - b, {}, len(a.size()) == 4
+        kernel_size = None if not conv2d else a.size()[2:4]
+        conv2d_3x3 = conv2d and kernel_size != (1, 1)
+        rank = self.alpha if not conv2d_3x3 or self.beta is None else self.beta
+        rank = min(rank, a.size()[1], a.size()[0])
+        matrix = diff.flatten(start_dim=1) if conv2d_3x3 else diff.squeeze() if conv2d else diff
+        U, S, Vh = torch.linalg.svd(matrix)
+        U, S, Vh = U[:, :rank], S[:rank], Vh[:rank, :]
+        U = U @ torch.diag(S)
+        dist = torch.cat([U.flatten(), Vh.flatten()])
+        hi_val = torch.quantile(dist, self.gamma)
+        U, Vh = U.clamp(-hi_val, hi_val), Vh.clamp(-hi_val, hi_val)
+        if conv2d:
+            Vh = Vh.reshape(rank, a.size()[1], *kernel_size) if conv2d_3x3 else Vh.reshape(rank, a.size()[1], 1, 1)
+            U = U.reshape(a.size()[0], rank, 1, 1)
+        weights_sd = {f"{self.key}.lora_up.weight": U, f"{self.key}.lora_down.weight": Vh, f"{self.key}.alpha": torch.tensor(float(rank))}
+        return weights_sd
+
+class Smooth(Operation):
+    def oper(self, a) -> torch.Tensor:
+        if a is None:
+            return None
+        filtered = scipy.ndimage.median_filter(a.detach().cpu().to(torch.float32).numpy(), size=3)
+        filtered = scipy.ndimage.gaussian_filter(filtered, sigma=1)
+        return torch.tensor(filtered, dtype=a.dtype, device=a.device)
+class TrainDiff(Operation):
+    def oper(self, a, b, c) -> torch.Tensor:
+        if a is None or b is None or c is None:
+            return None
+        if torch.allclose(b.float(), c.float()): return torch.zeros_like(a)
+        diff_bc = b.float() - c.float()
+        dist_bc, dist_ab = torch.abs(diff_bc), torch.abs(b.float() - a.float())
+        scale = torch.where(dist_bc + dist_ab != 0, dist_ab / (dist_bc + dist_ab), 0.0)
+        return (torch.sign(diff_bc) * torch.abs(scale) * torch.abs(diff_bc)).to(a.dtype) * 1.8
+class ExtractOp(Operation):
+    def __init__(self, key, alpha, beta, gamma, *args):
+        super().__init__(key, *args)
+        self.alpha, self.beta, self.gamma = alpha, beta, gamma
+    def oper(self, base: torch.Tensor, a: torch.Tensor, b: torch.Tensor) -> torch.Tensor:
+        if a is None or b is None:
+            return None
+        base_f = base.float() if base is not None else 0
+        a_f, b_f = a.float() - base_f, b.float() - base_f
+        c = torch.cosine_similarity(a_f.flatten(), b_f.flatten(), 0).clamp(-1, 1)
+        d = ((c + 1) / 2)**self.gamma
+        return (torch.lerp(a_f, b_f, self.alpha) * torch.lerp(d, 1 - d, self.beta)).to(a.dtype)
+
+
+class Similarities(ExtractOp):
+    def oper(self, a: torch.Tensor, b: torch.Tensor) -> torch.Tensor:
+        if a is None or b is None:
+            return None
+        return super().oper(None, a, b)
+class PowerUpOp(Operation):
+    def __init__(self, key, alpha, seed, *sources):
+        super().__init__(key, *sources)
+        self.alpha, self.seed = alpha, seed
+    def oper(self, a, b):
+        if a is None or b is None:
+            return None
+        delta = b - a
+        rng = torch.Generator(device=delta.device).manual_seed(self.seed)
+        m = torch.bernoulli(torch.full_like(delta, 1 - self.alpha), generator=rng)
+        return (m * delta) / (1 - self.alpha) if (1 - self.alpha) > 0 else torch.zeros_like(delta)
+
+
+class InterpolateDifference(Operation):
+    def __init__(self, key, alpha, beta, gamma, seed, *sources):
+        super().__init__(key, *sources)
+        self.alpha, self.beta, self.gamma, self.seed = alpha, beta, gamma, seed
+    def oper(self, a, b):
+        if a is None or b is None:
+            return None
+        alpha, delta = max(self.alpha, 0.001), torch.abs(a - b)
+        max_delta = torch.max(delta)
+        if max_delta == 0: return a
+        diff = ((max_delta - delta) / max_delta if self.beta != 1 else delta / max_delta) ** (1 / alpha - 1)
+        diff = torch.nan_to_num(diff)
+        rng = torch.Generator(device=diff.device).manual_seed(self.seed)
+        mask = torch.lerp(torch.bernoulli(torch.clamp(diff, 0, 1), generator=rng), diff, self.gamma)
+        return a * (1 - mask) + b * mask
+
+# ################# #
+# CALCULATION MODES
+# ################# #
+class CalcMode:
+    name = 'calcmode'; description = 'description'; models_used = []; param_docs = {}
+    def create_recipe(self, key, **kwargs) -> Operation: raise NotImplementedError
+
+    @staticmethod
+    def _get_secondary_loader_args(kwargs, mismatch_mode):
+        """Helper to build loader args for secondary models (B, C) with fallback support."""
+        base_args = {
+            "handlers": kwargs['handlers'],
+            "device": kwargs['device'],
+            "dtype": kwargs['dtype'],
+            "on_missing": mismatch_mode,
+        }
+        # Add fallback info for zeros mode
+        if '_tensor_a_shape' in kwargs:
+            base_args['fallback_shape'] = kwargs['_tensor_a_shape']
+            base_args['fallback_dtype'] = kwargs.get('_tensor_a_dtype', kwargs['dtype'])
+        return base_args
+
+
+class PreloadedTensor(Operation):
+    """Returns a pre-loaded tensor instead of loading from file.
+
+    Used when Model A's tensor is pre-loaded in the merge loop.
+    """
+    def __init__(self, key, tensor):
+        super().__init__(key)
+        self.tensor = tensor
+
+    def merge(self) -> torch.Tensor:
+        return self.tensor
+
+class WeightSum(CalcMode):
+    name = 'Weight-Sum'
+    description = 'A * (1 - α) + B * α. Simple linear interpolation.'
+    models_used = ['A', 'B']
+    param_docs = {'alpha': 'Interpolation weight. 0.0 is 100% Model A, 1.0 is 100% Model B.'}
+    def create_recipe(self, key, **kwargs):
+        mismatch_mode = kwargs.get('mismatch_mode', MissingTensorBehavior.SKIP)
+
+        # Use pre-loaded tensor_a if available
+        if '_tensor_a' in kwargs:
+            a = PreloadedTensor(key, kwargs['_tensor_a'])
+        else:
+            loader_args_a = {"handlers": kwargs['handlers'], "device": kwargs['device'], "dtype": kwargs['dtype']}
+            a = LoadTensor(key, kwargs['model_a'], **loader_args_a)
+
+        loader_args_b = self._get_secondary_loader_args(kwargs, mismatch_mode)
+        b = LoadTensor(key, kwargs['model_b'], **loader_args_b)
+
+        if kwargs['alpha'] >= 1: return b
+        if kwargs['alpha'] <= 0: return a
+        c = Multiply(key, 1 - kwargs['alpha'], a)
+        d = Multiply(key, kwargs['alpha'], b)
+        return Add(key, c, d)
+
+
+class AddDifference(CalcMode):
+    name = 'Add-Difference'
+    description = 'A + (B - C) * α. Applies the difference between B and C to A.'
+    models_used = ['A', 'B', 'C']
+    param_docs = {'alpha': 'Multiplier for the (B - C) difference.', 'beta': 'Smoothing (0=Off, 1=On).'}
+    def create_recipe(self, key, **kwargs):
+        mismatch_mode = kwargs.get('mismatch_mode', MissingTensorBehavior.SKIP)
+
+        if '_tensor_a' in kwargs:
+            a = PreloadedTensor(key, kwargs['_tensor_a'])
+        else:
+            loader_args_a = {"handlers": kwargs['handlers'], "device": kwargs['device'], "dtype": kwargs['dtype']}
+            a = LoadTensor(key, kwargs['model_a'], **loader_args_a)
+
+        loader_args_bc = self._get_secondary_loader_args(kwargs, mismatch_mode)
+        b = LoadTensor(key, kwargs['model_b'], **loader_args_bc)
+        c = LoadTensor(key, kwargs['model_c'], **loader_args_bc)
+        diff = Sub(key, b, c)
+        if kwargs['beta'] == 1: diff = Smooth(key, diff)
+        diffm = Multiply(key, kwargs['alpha'], diff)
+        return Add(key, a, diffm)
+
+
+class TrainDifference(CalcMode):
+    name = 'Train-Difference'
+    description = 'A + (B - C) * α, using tensor distances.'
+    models_used = ['A', 'B', 'C']
+    param_docs = {'alpha': 'Multiplier for the calculated difference.'}
+    def create_recipe(self, key, **kwargs):
+        mismatch_mode = kwargs.get('mismatch_mode', MissingTensorBehavior.SKIP)
+
+        if '_tensor_a' in kwargs:
+            a = PreloadedTensor(key, kwargs['_tensor_a'])
+        else:
+            loader_args_a = {"handlers": kwargs['handlers'], "device": kwargs['device'], "dtype": kwargs['dtype']}
+            a = LoadTensor(key, kwargs['model_a'], **loader_args_a)
+
+        loader_args_bc = self._get_secondary_loader_args(kwargs, mismatch_mode)
+        b = LoadTensor(key, kwargs['model_b'], **loader_args_bc)
+        c = LoadTensor(key, kwargs['model_c'], **loader_args_bc)
+        diff = TrainDiff(key, a, b, c)
+        diffm = Multiply(key, kwargs['alpha'], diff)
+        return Add(key, a, diffm)
+class InterpDifference(CalcMode):
+    name = 'Comparative-Interpolation'
+    description = 'Interpolates A and B based on relative tensor value differences.'
+    models_used = ['A', 'B']
+    param_docs = {'alpha': 'Curve strength.', 'beta': 'Style (0=Similarity, 1=Difference).', 'gamma': 'Mix (0=Random, 1=Linear).'}
+    def create_recipe(self, key, **kwargs):
+        mismatch_mode = kwargs.get('mismatch_mode', MissingTensorBehavior.SKIP)
+
+        if '_tensor_a' in kwargs:
+            a = PreloadedTensor(key, kwargs['_tensor_a'])
+        else:
+            loader_args_a = {"handlers": kwargs['handlers'], "device": kwargs['device'], "dtype": kwargs['dtype']}
+            a = LoadTensor(key, kwargs['model_a'], **loader_args_a)
+
+        # Skip certain keys entirely
+        if key.startswith('cond_stage_model.transformer.text_model.embeddings'):
+            return a
+
+        loader_args_b = self._get_secondary_loader_args(kwargs, mismatch_mode)
+        b = LoadTensor(key, kwargs['model_b'], **loader_args_b)
+        return InterpolateDifference(key, kwargs['alpha'], kwargs['beta'], kwargs['gamma'], kwargs['seed'], a, b)
+
+
+class Extract(CalcMode):
+    name = 'Extract-Features'
+    description = 'Adds features from B and C to A, based on their similarity.'
+    models_used = ['A', 'B', 'C']
+    param_docs = {'alpha': 'Weighting B vs C.', 'beta': 'Similarity vs dissimilarity.', 'gamma': 'Similarity bias.', 'delta': 'Multiplier for final features.'}
+    def create_recipe(self, key, **kwargs):
+        mismatch_mode = kwargs.get('mismatch_mode', MissingTensorBehavior.SKIP)
+
+        if '_tensor_a' in kwargs:
+            a = PreloadedTensor(key, kwargs['_tensor_a'])
+        else:
+            loader_args_a = {"handlers": kwargs['handlers'], "device": kwargs['device'], "dtype": kwargs['dtype']}
+            a = LoadTensor(key, kwargs['model_a'], **loader_args_a)
+
+        loader_args_bc = self._get_secondary_loader_args(kwargs, mismatch_mode)
+        b = LoadTensor(key, kwargs['model_b'], **loader_args_bc)
+        c = LoadTensor(key, kwargs['model_c'], **loader_args_bc)
+        extracted = ExtractOp(key, kwargs['alpha'], kwargs['beta'], kwargs['gamma'] * 15, a, b, c)
+        multiplied = Multiply(key, kwargs['delta'], extracted)
+        return Add(key, a, multiplied)
+
+
+class AddDisimilarity(CalcMode):
+    name = 'Add-Dissimilarities'
+    description = 'Adds dissimilar features between B and C to model A.'
+    models_used = ['A', 'B', 'C']
+    param_docs = {'alpha': 'Weighting B vs C.', 'beta': 'Multiplier for final features.', 'gamma': 'Similarity bias.'}
+    def create_recipe(self, key, **kwargs):
+        mismatch_mode = kwargs.get('mismatch_mode', MissingTensorBehavior.SKIP)
+
+        if '_tensor_a' in kwargs:
+            a = PreloadedTensor(key, kwargs['_tensor_a'])
+        else:
+            loader_args_a = {"handlers": kwargs['handlers'], "device": kwargs['device'], "dtype": kwargs['dtype']}
+            a = LoadTensor(key, kwargs['model_a'], **loader_args_a)
+
+        loader_args_bc = self._get_secondary_loader_args(kwargs, mismatch_mode)
+        b = LoadTensor(key, kwargs['model_b'], **loader_args_bc)
+        c = LoadTensor(key, kwargs['model_c'], **loader_args_bc)
+        extracted = Similarities(key, kwargs['alpha'], 1, kwargs['gamma'] * 15, b, c)
+        multiplied = Multiply(key, kwargs['beta'], extracted)
+        return Add(key, a, multiplied)
+
+
+class PowerUp(CalcMode):
+    name = 'Power-Up (DARE)'
+    description = 'Adds capabilities of B to A using Drop and Rescale (DARE).'
+    models_used = ['A', 'B']
+    param_docs = {'alpha': 'Dropout rate (proportion of weights from B to *drop*).', 'beta': 'Multiplier for the final difference.'}
+    def create_recipe(self, key, **kwargs):
+        mismatch_mode = kwargs.get('mismatch_mode', MissingTensorBehavior.SKIP)
+
+        if '_tensor_a' in kwargs:
+            a = PreloadedTensor(key, kwargs['_tensor_a'])
+        else:
+            loader_args_a = {"handlers": kwargs['handlers'], "device": kwargs['device'], "dtype": kwargs['dtype']}
+            a = LoadTensor(key, kwargs['model_a'], **loader_args_a)
+
+        loader_args_b = self._get_secondary_loader_args(kwargs, mismatch_mode)
+        b = LoadTensor(key, kwargs['model_b'], **loader_args_b)
+        deltahat = PowerUpOp(key, kwargs['alpha'], kwargs['seed'], a, b)
+        res = Multiply(key, kwargs['beta'], deltahat)
+        return Add(key, a, res)
+
+
+class SVDMode(CalcMode):
+    name = 'SVD LoRA Extraction'
+    description = 'Extracts the difference between B and A into a LoRA file.'
+    models_used = ['A', 'B']
+    param_docs = {'alpha': 'Rank for standard layers.', 'beta': 'Rank for 3x3 conv layers.', 'gamma': 'Clamp quantile for weights.'}
+    def create_recipe(self, key, **kwargs):
+        mismatch_mode = kwargs.get('mismatch_mode', MissingTensorBehavior.SKIP)
+
+        if '_tensor_a' in kwargs:
+            a = PreloadedTensor(key, kwargs['_tensor_a'])
+        else:
+            loader_args_a = {"handlers": kwargs['handlers'], "device": kwargs['device'], "dtype": kwargs['dtype']}
+            a = LoadTensor(key, kwargs['model_a'], **loader_args_a)
+
+        loader_args_b = self._get_secondary_loader_args(kwargs, mismatch_mode)
+        b = LoadTensor(key, kwargs['model_b'], **loader_args_b)
+        return SVD(key, kwargs['alpha'], kwargs['beta'], kwargs['gamma'], a, b)
+
+
+TWO_MODEL_MODES = [WeightSum(), InterpDifference(), PowerUp(), SVDMode()]
+THREE_MODEL_MODES = [AddDifference(), TrainDifference(), Extract(), AddDisimilarity()]

nodes/merger_utils.py

@@ -0,0 +1,374 @@
+"""
+Memory-efficient safetensors utilities with parallel I/O and pinned memory support.
+
+Based on benchmarking, parallel reading with ThreadPoolExecutor provides 2-4x speedup
+for large models compared to sequential reads.
+
+Worker count is automatically optimized based on device capabilities when workers=None.
+Pinned memory enables faster CPU→GPU transfers (2-3x improvement).
+"""
+import os
+import mmap
+import json
+import struct
+import torch
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import Dict, List, Optional, Any, Tuple
+
+# Import ComfyUI's memory pinning functions if available
+try:
+    from comfy.model_management import pin_memory, unpin_memory, is_device_cuda
+    PINNING_AVAILABLE = True
+except ImportError:
+    PINNING_AVAILABLE = False
+    def pin_memory(tensor): return False
+    def unpin_memory(tensor): return False
+    def is_device_cuda(device): return str(device).startswith('cuda')
+
+
+class PinnedTensor:
+    """Context manager for automatic pinned memory management.
+    
+    Usage:
+        with PinnedTensor(cpu_tensor) as pinned:
+            gpu_tensor = pinned.to('cuda')
+        # Memory automatically unpinned after transfer
+    """
+    
+    def __init__(self, tensor: torch.Tensor, auto_pin: bool = True):
+        self.tensor = tensor
+        self.is_pinned = False
+        self.auto_pin = auto_pin and PINNING_AVAILABLE
+        
+    def __enter__(self) -> torch.Tensor:
+        if self.auto_pin and self.tensor.device.type == 'cpu':
+            self.is_pinned = pin_memory(self.tensor)
+        return self.tensor
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if self.is_pinned:
+            unpin_memory(self.tensor)
+            self.is_pinned = False
+
+
+def transfer_to_gpu_pinned(
+    tensor: torch.Tensor,
+    device: str = 'cuda',
+    dtype: Optional[torch.dtype] = None
+) -> torch.Tensor:
+    """Transfer tensor to GPU using pinned memory for faster transfer.
+    
+    Args:
+        tensor: CPU tensor to transfer
+        device: Target GPU device
+        dtype: Optional dtype conversion
+        
+    Returns:
+        Tensor on GPU device
+    """
+    if not PINNING_AVAILABLE or not is_device_cuda(torch.device(device)):
+        # Fall back to regular transfer
+        if dtype:
+            return tensor.to(device=device, dtype=dtype)
+        return tensor.to(device=device)
+    
+    # Pin memory for faster transfer
+    was_pinned = pin_memory(tensor)
+    try:
+        if dtype:
+            result = tensor.to(device=device, dtype=dtype, non_blocking=True)
+        else:
+            result = tensor.to(device=device, non_blocking=True)
+        # Sync to ensure transfer is complete before unpinning
+        if was_pinned:
+            torch.cuda.current_stream().synchronize()
+        return result
+    finally:
+        if was_pinned:
+            unpin_memory(tensor)
+
+
+class MemoryEfficientSafeOpen:
+    """Memory-efficient safetensors file reader with mmap, parallel I/O, and pinned memory support.
+
+    Features:
+    - mmap mode: Zero-copy tensor access via memory-mapped file
+    - Parallel loading: Multi-threaded tensor reads for 2-4x speedup
+    - Sorted batch reads: Keys sorted by file offset for sequential I/O
+    - Auto-optimized workers: Adjusts parallelism based on device capabilities
+    - Pinned memory: Faster CPU→GPU transfers when transferring to CUDA
+
+    Args:
+        filename: Path to safetensors file
+        device: Target device (default 'cpu')
+        mmap_mode: Use memory-mapped file for zero-copy (default True)
+    """
+
+    def __init__(self, filename: str, device: str = 'cpu', mmap_mode: bool = True):
+        self.filename = filename
+        self.device = device
+        self.mmap_mode = mmap_mode
+        self.header, self.header_size = self._read_header()
+        self.file = open(filename, "rb")
+        self.mmap_obj = None
+
+        if self.mmap_mode:
+            self.mmap_obj = mmap.mmap(self.file.fileno(), 0, access=mmap.ACCESS_READ)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if self.mmap_obj:
+            self.mmap_obj.close()
+        self.file.close()
+
+    def keys(self) -> List[str]:
+        """Return all tensor keys (excluding metadata)."""
+        return [k for k in self.header.keys() if k != "__metadata__"]
+
+    def metadata(self) -> Dict[str, str]:
+        """Return file metadata."""
+        return self.header.get("__metadata__", {})
+
+    def keys_sorted_by_offset(self) -> List[str]:
+        """Return keys sorted by file offset for optimal sequential I/O."""
+        keys_with_offsets = []
+        for key in self.keys():
+            offset = self.header[key]["data_offsets"][0]
+            keys_with_offsets.append((key, offset))
+        keys_with_offsets.sort(key=lambda x: x[1])
+        return [k for k, _ in keys_with_offsets]
+
+    def get_tensor(self, key: str) -> torch.Tensor:
+        """Load a single tensor by key."""
+        if key not in self.header:
+            raise KeyError(f"Tensor '{key}' not found in the file")
+
+        metadata = self.header[key]
+        offset_start, offset_end = metadata["data_offsets"]
+
+        if self.mmap_mode and self.mmap_obj:
+            if offset_start != offset_end:
+                start = self.header_size + 8 + offset_start
+                end = self.header_size + 8 + offset_end
+                tensor_bytes = memoryview(self.mmap_obj)[start:end]
+            else:
+                tensor_bytes = None
+        else:
+            tensor_bytes = None
+            if offset_start != offset_end:
+                self.file.seek(self.header_size + 8 + offset_start)
+                tensor_bytes = self.file.read(offset_end - offset_start)
+
+        return self._deserialize_tensor(tensor_bytes, metadata)
+    
+    def get_tensor_to_gpu(
+        self,
+        key: str,
+        device: str = 'cuda',
+        dtype: Optional[torch.dtype] = None
+    ) -> torch.Tensor:
+        """Load a tensor and transfer to GPU using pinned memory for faster transfer.
+        
+        Args:
+            key: Tensor key to load
+            device: Target GPU device (default 'cuda')
+            dtype: Optional dtype conversion
+            
+        Returns:
+            Tensor on GPU device
+        """
+        cpu_tensor = self.get_tensor(key)
+        return transfer_to_gpu_pinned(cpu_tensor, device, dtype)
+
+    def get_tensors_parallel(
+        self,
+        keys: Optional[List[str]] = None,
+        workers: Optional[int] = None,
+        sort_by_offset: bool = True
+    ) -> Dict[str, torch.Tensor]:
+        """Load multiple tensors in parallel using ThreadPoolExecutor.
+
+        Args:
+            keys: List of keys to load (default: all keys)
+            workers: Number of worker threads (default: auto-calculated based on device)
+            sort_by_offset: Sort keys by file offset before loading (default: True)
+
+        Returns:
+            Dict mapping key -> tensor
+        """
+        if keys is None:
+            keys = self.keys()
+
+        # Auto-calculate workers based on device capabilities
+        if workers is None:
+            try:
+                from .device_utils import get_optimal_workers, estimate_model_size
+                model_size = estimate_model_size(self.filename)
+                workers = get_optimal_workers(model_size)
+            except ImportError:
+                workers = min(4, os.cpu_count() or 4)
+
+        if sort_by_offset:
+            # Sort by offset for better I/O patterns
+            keys_with_offsets = [(k, self.header[k]["data_offsets"][0]) for k in keys]
+            keys_with_offsets.sort(key=lambda x: x[1])
+            keys = [k for k, _ in keys_with_offsets]
+
+        result = {}
+
+        with ThreadPoolExecutor(max_workers=workers) as executor:
+            futures = {
+                executor.submit(
+                    _read_tensor_from_file,
+                    self.filename,
+                    key,
+                    self.header[key],
+                    self.header_size
+                ): key
+                for key in keys
+            }
+
+            for future in as_completed(futures):
+                key = futures[future]
+                try:
+                    tensor = future.result()
+                    if tensor is not None:
+                        result[key] = tensor
+                except Exception as e:
+                    print(f"[MemoryEfficientSafeOpen] Failed to load {key}: {e}")
+
+        return result
+
+    def get_tensor_as_dict(self, key: str) -> Dict[str, Any]:
+        """Load a tensor and decode as JSON dict (for config tensors)."""
+        if key not in self.header:
+            raise KeyError(f"Tensor '{key}' not found")
+
+        metadata = self.header[key]
+        offset_start, offset_end = metadata["data_offsets"]
+
+        if offset_start == offset_end:
+            return {}
+
+        if self.mmap_mode and self.mmap_obj:
+            start = self.header_size + 8 + offset_start
+            end = self.header_size + 8 + offset_end
+            tensor_bytes = bytes(self.mmap_obj[start:end])
+        else:
+            self.file.seek(self.header_size + 8 + offset_start)
+            tensor_bytes = self.file.read(offset_end - offset_start)
+
+        return json.loads(tensor_bytes.decode("utf-8"))
+
+    def _read_header(self):
+        with open(self.filename, "rb") as f:
+            header_size = struct.unpack("<Q", f.read(8))[0]
+            header_json = f.read(header_size).decode("utf-8")
+        return json.loads(header_json), header_size
+
+    def _deserialize_tensor(self, tensor_bytes, metadata):
+        dtype_str = metadata["dtype"]
+        shape = metadata["shape"]
+        dtype = self._get_torch_dtype(dtype_str)
+
+        if tensor_bytes is None:
+            byte_tensor = torch.empty(0, dtype=torch.uint8)
+        else:
+            byte_tensor = torch.frombuffer(bytearray(tensor_bytes), dtype=torch.uint8)
+
+        if dtype_str in ["F8_E5M2", "F8_E4M3"]:
+            return self._convert_float8(byte_tensor, dtype_str, shape)
+
+        return byte_tensor.view(dtype).reshape(shape)
+
+    @staticmethod
+    def _get_torch_dtype(dtype_str):
+        dtype_map = {
+            "F64": torch.float64, "F32": torch.float32, "F16": torch.float16, "BF16": torch.bfloat16,
+            "I64": torch.int64, "I32": torch.int32, "I16": torch.int16, "I8": torch.int8,
+            "U8": torch.uint8, "BOOL": torch.bool,
+        }
+        if hasattr(torch, "float8_e5m2"):
+            dtype_map["F8_E5M2"] = torch.float8_e5m2
+        if hasattr(torch, "float8_e4m3fn"):
+            dtype_map["F8_E4M3"] = torch.float8_e4m3fn
+
+        dtype = dtype_map.get(dtype_str)
+        if dtype is None:
+            raise ValueError(f"Unsupported dtype: {dtype_str}")
+        return dtype
+
+    @staticmethod
+    def _convert_float8(byte_tensor, dtype_str, shape):
+        if dtype_str == "F8_E5M2" and hasattr(torch, "float8_e5m2"):
+            return byte_tensor.view(torch.float8_e5m2).reshape(shape)
+        elif dtype_str == "F8_E4M3" and hasattr(torch, "float8_e4m3fn"):
+            return byte_tensor.view(torch.float8_e4m3fn).reshape(shape)
+        else:
+            raise ValueError(f"Unsupported float8 type: {dtype_str}. Your PyTorch version may be too old.")
+
+
+def _read_tensor_from_file(
+    filepath: str,
+    key: str,
+    metadata: Dict,
+    header_size: int
+) -> Optional[torch.Tensor]:
+    """Helper function to read a single tensor from file (for parallel execution).
+
+    Each worker opens its own file handle for thread safety.
+    """
+    offset_start, offset_end = metadata["data_offsets"]
+    dtype_str = metadata["dtype"]
+    shape = metadata["shape"]
+
+    if offset_start == offset_end:
+        return None
+
+    dtype_map = {
+        "F64": torch.float64, "F32": torch.float32, "F16": torch.float16, "BF16": torch.bfloat16,
+        "I64": torch.int64, "I32": torch.int32, "I16": torch.int16, "I8": torch.int8,
+        "U8": torch.uint8, "BOOL": torch.bool,
+    }
+    if hasattr(torch, "float8_e5m2"):
+        dtype_map["F8_E5M2"] = torch.float8_e5m2
+    if hasattr(torch, "float8_e4m3fn"):
+        dtype_map["F8_E4M3"] = torch.float8_e4m3fn
+
+    dtype = dtype_map.get(dtype_str, torch.float32)
+
+    with open(filepath, "rb") as f:
+        f.seek(header_size + 8 + offset_start)
+        tensor_bytes = f.read(offset_end - offset_start)
+
+    byte_tensor = torch.frombuffer(bytearray(tensor_bytes), dtype=torch.uint8)
+
+    if dtype_str in ["F8_E5M2", "F8_E4M3"]:
+        if dtype_str == "F8_E5M2" and hasattr(torch, "float8_e5m2"):
+            return byte_tensor.view(torch.float8_e5m2).reshape(shape)
+        elif dtype_str == "F8_E4M3" and hasattr(torch, "float8_e4m3fn"):
+            return byte_tensor.view(torch.float8_e4m3fn).reshape(shape)
+
+    return byte_tensor.view(dtype).reshape(shape)
+
+
+def get_union_keys(*handlers) -> List[str]:
+    """Returns the union of all tensor keys across multiple model handlers."""
+    all_keys = set()
+    for handler in handlers:
+        if handler is not None:
+            all_keys.update(handler.keys())
+    return sorted(all_keys)
+
+
+def get_intersection_keys(*handlers) -> List[str]:
+    """Returns only keys present in ALL model handlers."""
+    handlers = [h for h in handlers if h is not None]
+    if not handlers:
+        return []
+    all_keys = set(handlers[0].keys())
+    for handler in handlers[1:]:
+        all_keys &= set(handler.keys())
+    return sorted(all_keys)

nodes/metakeys.py

@@ -1,118 +1,174 @@
-import torch
-from safetensors import safe_open
-from safetensors.torch import save_file
 import os
+import json
+import struct
 import folder_paths
-from comfy.model_management import get_torch_device
+import comfy.utils
+from tqdm import tqdm
+from comfy_api.latest import io
+from safetensors import safe_open
+from .utils import convert_pt_to_safetensors
 
 
-def convert_pt_to_safetensors(pt_path, safe_path):
-    try:
-        model = torch.load(pt_path, map_location="cpu")
-        if "state_dict" in model:
-            state_dict = model["state_dict"]
-        elif "model" in model:
-            state_dict = model["model"]
-        else:
-            state_dict = model
-        state_dict = {k.replace("state_dict.", ""): v for k, v in state_dict.items()}
-        metadata = {"format": "pt"}
-        save_file(state_dict, safe_path, metadata)
-        return True, ""
-    except Exception as e:
-        return False, str(e)
+def _get_metakeys(model_name: str, model_type: str) -> tuple[str, str]:
+    """Shared logic for all MetaKeys nodes."""
+    model_path = folder_paths.get_full_path_or_raise(model_type, model_name)
 
-def load_metadata_from_safetensors(safetensors_file: str) -> dict:
-    try:
-        with safe_open(safetensors_file, framework="pt", device="cpu") as f:
-            model_weights = {}
-            for key in f.keys():
-                model_weights[key] = f.get_tensor(key)
-            metadata = f.metadata()
-        if metadata is None:
-            metadata = {}
-        return model_weights, metadata
-    except Exception as e:
-        print(f"Error loading safetensors file: {e}")
-        return {}, {}
+    if model_path.endswith(('.pt', '.pth', '.bin', '.ckpt')):
+        temp_safe_path = model_path + ".safetensors"
+        if not os.path.exists(temp_safe_path):
+            conversion_successful, error_message = convert_pt_to_safetensors(model_path, temp_safe_path)
+            if not conversion_successful:
+                return f"Conversion failed: {error_message}", ""
+        model_path = temp_safe_path
 
-class BaseMetaKeys:
-    RETURN_TYPES = ("STRING", "STRING")
-    RETURN_NAMES = ("metadata", "keys")
-    FUNCTION = "get_metakeys"
-    CATEGORY = "utils"
-    DESCRIPTION = "Loads a model and returns its metadata and layer names."
+    # Read header only - no tensor loading needed
+    with open(model_path, "rb") as f:
+        header_size = struct.unpack("<Q", f.read(8))[0]
+        header_json = f.read(header_size).decode("utf-8")
+    header = json.loads(header_json)
 
-    def _get_metakeys(self, model_name, model_type):
-        model_path = folder_paths.get_full_path_or_raise(model_type, model_name)
-        model_weights = {}
-        metadata = {}
-        layer_shapes = ""
+    # Extract metadata and layer shapes from header
+    metadata = header.pop("__metadata__", {})
+    metadata_str = str(metadata)
 
-        if model_path.endswith(('.pt', '.pth', '.bin', '.ckpt')):
-            temp_safe_path = model_path + ".safetensors"
-            if not os.path.exists(temp_safe_path):
-                conversion_successful, error_message = convert_pt_to_safetensors(model_path, temp_safe_path)
-                if not conversion_successful:
-                    return f"Conversion failed: {error_message}", ""
-            model_path = temp_safe_path
+    layer_shapes = ""
+    keys = [k for k in header.keys()]
+    pbar = comfy.utils.ProgressBar(len(keys))
+    for layer_name in tqdm(keys, desc="Reading layer shapes", unit="layers"):
+        info = header[layer_name]
+        shape = str(info.get("shape", []))
+        name_shape = f"{layer_name}, {shape}\n"
+        layer_shapes += name_shape
+        pbar.update(1)
 
-        model_weights, metadata = load_metadata_from_safetensors(model_path)
-        metadata_str = str(metadata)
-        for layer_name, tensor in model_weights.items():
-            shape = str(tensor.shape)
-            shape = shape.replace("torch.Size(", "").replace(")", "")
-            name_shape = f"{layer_name}, {shape}\n"
-            layer_shapes += name_shape
-        return metadata_str, layer_shapes
+    return metadata_str, layer_shapes
 
 
-
-class UNetMetaKeys(BaseMetaKeys):
+class ModelMetaKeys(io.ComfyNode):
     @classmethod
-    def INPUT_TYPES(s):
-        return {
-            "required": {
-                "unet_name": (folder_paths.get_filename_list("diffusion_models"), ),
-            }
-        }
+    def define_schema(cls):
+        return io.Schema(
+            node_id="ModelMetaKeys",
+            display_name="Get Diffusion Model Metadata & Keys",
+            category="ModelUtils/Keys",
+            description="Loads a diffusion model and returns its metadata and layer names.",
+            inputs=[
+                io.Combo.Input(
+                    "diffusionmodel_name",
+                    options=folder_paths.get_filename_list("diffusion_models"),
+                ),
+            ],
+            outputs=[
+                io.String.Output(display_name="metadata"),
+                io.String.Output(display_name="keys"),
+            ],
+        )
 
-    def get_metakeys(self, unet_name):
-        return self._get_metakeys(unet_name, "diffusion_models")
-
-class CLIPMetaKeys(BaseMetaKeys):
     @classmethod
-    def INPUT_TYPES(s):
-        return {
-            "required": {
-                "clip_name": (folder_paths.get_filename_list("text_encoders"), ),
-            }
-        }
+    def execute(cls, diffusionmodel_name: str) -> io.NodeOutput:
+        metadata, keys = _get_metakeys(diffusionmodel_name, "diffusion_models")
+        return io.NodeOutput(metadata, keys)
 
-    def get_metakeys(self, clip_name):
-        return self._get_metakeys(clip_name, "text_encoders")
 
-class LoRAMetaKeys(BaseMetaKeys):
+class TextEncoderMetaKeys(io.ComfyNode):
     @classmethod
-    def INPUT_TYPES(s):
-        return {
-            "required": {
-                "lora_name": (folder_paths.get_filename_list("loras"), ),
-            }
-        }
-    def get_metakeys(self, lora_name):
-        return self._get_metakeys(lora_name, "loras")
+    def define_schema(cls):
+        return io.Schema(
+            node_id="TextEncoderMetaKeys",
+            display_name="Get Text Encoder Metadata & Keys",
+            category="ModelUtils/Keys",
+            description="Loads a text encoder and returns its metadata and layer names.",
+            inputs=[
+                io.Combo.Input(
+                    "textencoder_name",
+                    options=folder_paths.get_filename_list("text_encoders"),
+                ),
+            ],
+            outputs=[
+                io.String.Output(display_name="metadata"),
+                io.String.Output(display_name="keys"),
+            ],
+        )
 
-class CheckpointMetaKeys(BaseMetaKeys):
     @classmethod
-    def INPUT_TYPES(s):
-        return {
-            "required": {
-                "ckpt_name": (folder_paths.get_filename_list("checkpoints"), ),
-            }
-        }
+    def execute(cls, textencoder_name: str) -> io.NodeOutput:
+        metadata, keys = _get_metakeys(textencoder_name, "text_encoders")
+        return io.NodeOutput(metadata, keys)
 
-    def get_metakeys(self, ckpt_name):
-        return self._get_metakeys(ckpt_name, "checkpoints")
 
-__all__ = ("UNetMetaKeys", "CLIPMetaKeys", "LoRAMetaKeys", "CheckpointMetaKeys")
+class LoRAMetaKeys(io.ComfyNode):
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="LoRAMetaKeys",
+            display_name="Get LoRA Metadata & Keys",
+            category="ModelUtils/Keys",
+            description="Loads a LoRA and returns its metadata and layer names.",
+            inputs=[
+                io.Combo.Input(
+                    "lora_name",
+                    options=folder_paths.get_filename_list("loras"),
+                ),
+            ],
+            outputs=[
+                io.String.Output(display_name="metadata"),
+                io.String.Output(display_name="keys"),
+            ],
+        )
+
+    @classmethod
+    def execute(cls, lora_name: str) -> io.NodeOutput:
+        metadata, keys = _get_metakeys(lora_name, "loras")
+        return io.NodeOutput(metadata, keys)
+
+
+class CheckpointMetaKeys(io.ComfyNode):
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="CheckpointMetaKeys",
+            display_name="Get Checkpoint Metadata & Keys",
+            category="ModelUtils/Keys",
+            description="Loads a checkpoint and returns its metadata and layer names.",
+            inputs=[
+                io.Combo.Input(
+                    "ckpt_name",
+                    options=folder_paths.get_filename_list("checkpoints"),
+                ),
+            ],
+            outputs=[
+                io.String.Output(display_name="metadata"),
+                io.String.Output(display_name="keys"),
+            ],
+        )
+
+    @classmethod
+    def execute(cls, ckpt_name: str) -> io.NodeOutput:
+        metadata, keys = _get_metakeys(ckpt_name, "checkpoints")
+        return io.NodeOutput(metadata, keys)
+
+
+class EmbeddingMetaKeys(io.ComfyNode):
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="EmbeddingMetaKeys",
+            display_name="Get Embedding Metadata & Keys",
+            category="ModelUtils/Keys",
+            description="Loads an embedding and returns its metadata and layer names.",
+            inputs=[
+                io.Combo.Input(
+                    "embedding",
+                    options=folder_paths.get_filename_list("embeddings"),
+                ),
+            ],
+            outputs=[
+                io.String.Output(display_name="metadata"),
+                io.String.Output(display_name="keys"),
+            ],
+        )
+
+    @classmethod
+    def execute(cls, embedding: str) -> io.NodeOutput:
+        metadata, keys = _get_metakeys(embedding, "embeddings")
+        return io.NodeOutput(metadata, keys)

nodes/prunekeys.py

@@ -0,0 +1,220 @@
+import os
+import re
+import folder_paths
+import comfy.utils
+from tqdm import tqdm
+from comfy_api.latest import io
+from safetensors.torch import save_file
+from safetensors import safe_open
+from .utils import convert_pt_to_safetensors
+from .merger_utils import MemoryEfficientSafeOpen
+from .device_utils import estimate_model_size, prepare_for_large_operation, cleanup_after_operation
+
+
+def _prune_keys(model_name: str, model_type: str, keys_to_prune_str: str,
+                use_regex: bool, output_filename: str) -> str:
+    """Shared logic for all PruneKeys nodes."""
+    model_path = folder_paths.get_full_path_or_raise(model_type, model_name)
+
+    if model_path.endswith(('.pt', '.pth', '.bin', '.ckpt')):
+        temp_safe_path = model_path + ".safetensors"
+        if not os.path.exists(temp_safe_path):
+            conversion_successful, error_message = convert_pt_to_safetensors(model_path, temp_safe_path)
+            if not conversion_successful:
+                raise Exception(f"Conversion failed: {error_message}")
+        model_path_to_load = temp_safe_path
+    else:
+        model_path_to_load = model_path
+
+    # Prepare memory before operation
+    model_size_gb = estimate_model_size(model_path_to_load)
+    prepare_for_large_operation(model_size_gb * 1.2)
+
+    # Get metadata from safe_open (header only, no tensor loading)
+    with safe_open(model_path_to_load, framework="pt", device="cpu") as f:
+        metadata = f.metadata() or {}
+
+    patterns = [p.strip() for p in keys_to_prune_str.strip().split('\n') if p.strip()]
+
+    if not patterns:
+        raise ValueError("No keys/patterns provided to prune.")
+
+    # Stream tensors and filter on the fly
+    pruned_tensors = {}
+    with MemoryEfficientSafeOpen(model_path_to_load) as handler:
+        all_keys = handler.keys()
+        pbar = comfy.utils.ProgressBar(len(all_keys))
+        for key in tqdm(all_keys, desc="Pruning keys", unit="keys"):
+            is_match = False
+            if use_regex:
+                if any(re.search(pattern, key) for pattern in patterns):
+                    is_match = True
+            else:
+                if any(pattern in key for pattern in patterns):
+                    is_match = True
+
+            if not is_match:
+                pruned_tensors[key] = handler.get_tensor(key)
+            pbar.update(1)
+
+    # Use [-1] for diffusion_models to get the actual diffusion_models folder, not legacy unet
+    model_dir = folder_paths.get_folder_paths(model_type)[-1]
+    output_path = os.path.join(model_dir, f"{output_filename.strip()}.safetensors")
+
+    save_file(pruned_tensors, output_path, metadata)
+
+    # Cleanup after operation
+    del pruned_tensors
+    cleanup_after_operation()
+
+    return output_path
+
+
+class ModelPruneKeys(io.ComfyNode):
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="ModelPruneKeys",
+            display_name="Prune Diffusion Model Keys",
+            category="ModelUtils/Keys",
+            description="Loads a diffusion model, removes specified keys, and saves it as a new safetensors file.",
+            inputs=[
+                io.Combo.Input(
+                    "diffusionmodel_name",
+                    options=folder_paths.get_filename_list("diffusion_models"),
+                ),
+                io.String.Input("keys_to_prune", multiline=True, default=""),
+                io.Boolean.Input("use_regex", default=False),
+                io.String.Input("output_filename", default="pruned_model"),
+            ],
+            outputs=[
+                io.String.Output(display_name="output_path"),
+            ],
+        )
+
+    @classmethod
+    def execute(cls, diffusionmodel_name: str, keys_to_prune: str,
+                use_regex: bool, output_filename: str) -> io.NodeOutput:
+        path = _prune_keys(diffusionmodel_name, "diffusion_models",
+                          keys_to_prune, use_regex, output_filename)
+        return io.NodeOutput(path)
+
+
+class TextEncoderPruneKeys(io.ComfyNode):
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="TextEncoderPruneKeys",
+            display_name="Prune Text Encoder Keys",
+            category="ModelUtils/Keys",
+            description="Loads a text encoder, removes specified keys, and saves it as a new safetensors file.",
+            inputs=[
+                io.Combo.Input(
+                    "textencoder_name",
+                    options=folder_paths.get_filename_list("text_encoders"),
+                ),
+                io.String.Input("keys_to_prune", multiline=True, default=""),
+                io.Boolean.Input("use_regex", default=False),
+                io.String.Input("output_filename", default="pruned_textencoder"),
+            ],
+            outputs=[
+                io.String.Output(display_name="output_path"),
+            ],
+        )
+
+    @classmethod
+    def execute(cls, textencoder_name: str, keys_to_prune: str,
+                use_regex: bool, output_filename: str) -> io.NodeOutput:
+        path = _prune_keys(textencoder_name, "text_encoders",
+                          keys_to_prune, use_regex, output_filename)
+        return io.NodeOutput(path)
+
+
+class LoRAPruneKeys(io.ComfyNode):
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="LoRAPruneKeys",
+            display_name="Prune LoRA Keys",
+            category="ModelUtils/Keys",
+            description="Loads a LoRA, removes specified keys, and saves it as a new safetensors file.",
+            inputs=[
+                io.Combo.Input(
+                    "lora_name",
+                    options=folder_paths.get_filename_list("loras"),
+                ),
+                io.String.Input("keys_to_prune", multiline=True, default=""),
+                io.Boolean.Input("use_regex", default=False),
+                io.String.Input("output_filename", default="pruned_lora"),
+            ],
+            outputs=[
+                io.String.Output(display_name="output_path"),
+            ],
+        )
+
+    @classmethod
+    def execute(cls, lora_name: str, keys_to_prune: str,
+                use_regex: bool, output_filename: str) -> io.NodeOutput:
+        path = _prune_keys(lora_name, "loras",
+                          keys_to_prune, use_regex, output_filename)
+        return io.NodeOutput(path)
+
+
+class CheckpointPruneKeys(io.ComfyNode):
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="CheckpointPruneKeys",
+            display_name="Prune Checkpoint Keys",
+            category="ModelUtils/Keys",
+            description="Loads a checkpoint, removes specified keys, and saves it as a new safetensors file.",
+            inputs=[
+                io.Combo.Input(
+                    "ckpt_name",
+                    options=folder_paths.get_filename_list("checkpoints"),
+                ),
+                io.String.Input("keys_to_prune", multiline=True, default=""),
+                io.Boolean.Input("use_regex", default=False),
+                io.String.Input("output_filename", default="pruned_checkpoint"),
+            ],
+            outputs=[
+                io.String.Output(display_name="output_path"),
+            ],
+        )
+
+    @classmethod
+    def execute(cls, ckpt_name: str, keys_to_prune: str,
+                use_regex: bool, output_filename: str) -> io.NodeOutput:
+        path = _prune_keys(ckpt_name, "checkpoints",
+                          keys_to_prune, use_regex, output_filename)
+        return io.NodeOutput(path)
+
+
+class EmbeddingPruneKeys(io.ComfyNode):
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="EmbeddingPruneKeys",
+            display_name="Prune Embedding Keys",
+            category="ModelUtils/Keys",
+            description="Loads an embedding, removes specified keys, and saves it as a new safetensors file.",
+            inputs=[
+                io.Combo.Input(
+                    "embedding",
+                    options=folder_paths.get_filename_list("embeddings"),
+                ),
+                io.String.Input("keys_to_prune", multiline=True, default=""),
+                io.Boolean.Input("use_regex", default=False),
+                io.String.Input("output_filename", default="pruned_embedding"),
+            ],
+            outputs=[
+                io.String.Output(display_name="output_path"),
+            ],
+        )
+
+    @classmethod
+    def execute(cls, embedding: str, keys_to_prune: str,
+                use_regex: bool, output_filename: str) -> io.NodeOutput:
+        path = _prune_keys(embedding, "embeddings",
+                          keys_to_prune, use_regex, output_filename)
+        return io.NodeOutput(path)

nodes/renamekeys.py

@@ -0,0 +1,214 @@
+import os
+import folder_paths
+import comfy.utils
+from tqdm import tqdm
+from comfy_api.latest import io
+from safetensors.torch import save_file
+from safetensors import safe_open
+from .utils import convert_pt_to_safetensors
+from .merger_utils import MemoryEfficientSafeOpen
+from .device_utils import estimate_model_size, prepare_for_large_operation, cleanup_after_operation
+
+
+def _rename_keys(model_name: str, model_type: str, old_keys_str: str,
+                 new_keys_str: str, output_filename: str) -> str:
+    """Shared logic for all RenameKeys nodes."""
+    model_path = folder_paths.get_full_path_or_raise(model_type, model_name)
+
+    if model_path.endswith(('.pt', '.pth', '.bin', '.ckpt')):
+        temp_safe_path = model_path + ".safetensors"
+        if not os.path.exists(temp_safe_path):
+            conversion_successful, error_message = convert_pt_to_safetensors(model_path, temp_safe_path)
+            if not conversion_successful:
+                raise Exception(f"Conversion failed: {error_message}")
+        model_path_to_load = temp_safe_path
+    else:
+        model_path_to_load = model_path
+
+    # Prepare memory before operation
+    model_size_gb = estimate_model_size(model_path_to_load)
+    prepare_for_large_operation(model_size_gb * 1.2)
+
+    # Get metadata from safe_open (header only, no tensor loading)
+    with safe_open(model_path_to_load, framework="pt", device="cpu") as f:
+        metadata = f.metadata() or {}
+
+    old_keys = [key.strip() for key in old_keys_str.strip().split('\n') if key.strip()]
+    new_keys = [key.strip() for key in new_keys_str.strip().split('\n') if key.strip()]
+
+    if len(old_keys) != len(new_keys):
+        raise ValueError("The number of old keys must match the number of new keys.")
+
+    key_map = dict(zip(old_keys, new_keys))
+
+    # Stream tensors and rename on the fly
+    renamed_tensors = {}
+    with MemoryEfficientSafeOpen(model_path_to_load) as handler:
+        original_keys = handler.keys()
+        pbar = comfy.utils.ProgressBar(len(original_keys))
+        for key in tqdm(original_keys, desc="Renaming keys", unit="keys"):
+            new_key = key_map.get(key, key)
+            renamed_tensors[new_key] = handler.get_tensor(key)
+            pbar.update(1)
+
+    # Use [-1] for diffusion_models to get the actual diffusion_models folder, not legacy unet
+    model_dir = folder_paths.get_folder_paths(model_type)[-1]
+    output_path = os.path.join(model_dir, f"{output_filename.strip()}.safetensors")
+
+    save_file(renamed_tensors, output_path, metadata)
+
+    # Cleanup after operation
+    del renamed_tensors
+    cleanup_after_operation()
+
+    return output_path
+
+
+class ModelRenameKeys(io.ComfyNode):
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="ModelRenameKeys",
+            display_name="Rename Diffusion Model Keys",
+            category="ModelUtils/Keys",
+            description="Loads a diffusion model, renames specified keys, and saves it as a new safetensors file.",
+            inputs=[
+                io.Combo.Input(
+                    "diffusionmodel_name",
+                    options=folder_paths.get_filename_list("diffusion_models"),
+                ),
+                io.String.Input("old_keys", multiline=True, default=""),
+                io.String.Input("new_keys", multiline=True, default=""),
+                io.String.Input("output_filename", default="renamed_model"),
+            ],
+            outputs=[
+                io.String.Output(display_name="output_path"),
+            ],
+        )
+
+    @classmethod
+    def execute(cls, diffusionmodel_name: str, old_keys: str,
+                new_keys: str, output_filename: str) -> io.NodeOutput:
+        path = _rename_keys(diffusionmodel_name, "diffusion_models",
+                           old_keys, new_keys, output_filename)
+        return io.NodeOutput(path)
+
+
+class TextEncoderRenameKeys(io.ComfyNode):
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="TextEncoderRenameKeys",
+            display_name="Rename Text Encoder Keys",
+            category="ModelUtils/Keys",
+            description="Loads a text encoder, renames specified keys, and saves it as a new safetensors file.",
+            inputs=[
+                io.Combo.Input(
+                    "textencoder_name",
+                    options=folder_paths.get_filename_list("text_encoders"),
+                ),
+                io.String.Input("old_keys", multiline=True, default=""),
+                io.String.Input("new_keys", multiline=True, default=""),
+                io.String.Input("output_filename", default="renamed_textencoder"),
+            ],
+            outputs=[
+                io.String.Output(display_name="output_path"),
+            ],
+        )
+
+    @classmethod
+    def execute(cls, textencoder_name: str, old_keys: str,
+                new_keys: str, output_filename: str) -> io.NodeOutput:
+        path = _rename_keys(textencoder_name, "text_encoders",
+                           old_keys, new_keys, output_filename)
+        return io.NodeOutput(path)
+
+
+class LoRARenameKeys(io.ComfyNode):
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="LoRARenameKeys",
+            display_name="Rename LoRA Keys",
+            category="ModelUtils/Keys",
+            description="Loads a LoRA, renames specified keys, and saves it as a new safetensors file.",
+            inputs=[
+                io.Combo.Input(
+                    "lora_name",
+                    options=folder_paths.get_filename_list("loras"),
+                ),
+                io.String.Input("old_keys", multiline=True, default=""),
+                io.String.Input("new_keys", multiline=True, default=""),
+                io.String.Input("output_filename", default="renamed_lora"),
+            ],
+            outputs=[
+                io.String.Output(display_name="output_path"),
+            ],
+        )
+
+    @classmethod
+    def execute(cls, lora_name: str, old_keys: str,
+                new_keys: str, output_filename: str) -> io.NodeOutput:
+        path = _rename_keys(lora_name, "loras",
+                           old_keys, new_keys, output_filename)
+        return io.NodeOutput(path)
+
+
+class CheckpointRenameKeys(io.ComfyNode):
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="CheckpointRenameKeys",
+            display_name="Rename Checkpoint Keys",
+            category="ModelUtils/Keys",
+            description="Loads a checkpoint, renames specified keys, and saves it as a new safetensors file.",
+            inputs=[
+                io.Combo.Input(
+                    "ckpt_name",
+                    options=folder_paths.get_filename_list("checkpoints"),
+                ),
+                io.String.Input("old_keys", multiline=True, default=""),
+                io.String.Input("new_keys", multiline=True, default=""),
+                io.String.Input("output_filename", default="renamed_checkpoint"),
+            ],
+            outputs=[
+                io.String.Output(display_name="output_path"),
+            ],
+        )
+
+    @classmethod
+    def execute(cls, ckpt_name: str, old_keys: str,
+                new_keys: str, output_filename: str) -> io.NodeOutput:
+        path = _rename_keys(ckpt_name, "checkpoints",
+                           old_keys, new_keys, output_filename)
+        return io.NodeOutput(path)
+
+
+class EmbeddingRenameKeys(io.ComfyNode):
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="EmbeddingRenameKeys",
+            display_name="Rename Embedding Keys",
+            category="ModelUtils/Keys",
+            description="Loads an embedding, renames specified keys, and saves it as a new safetensors file.",
+            inputs=[
+                io.Combo.Input(
+                    "embedding",
+                    options=folder_paths.get_filename_list("embeddings"),
+                ),
+                io.String.Input("old_keys", multiline=True, default=""),
+                io.String.Input("new_keys", multiline=True, default=""),
+                io.String.Input("output_filename", default="renamed_embedding"),
+            ],
+            outputs=[
+                io.String.Output(display_name="output_path"),
+            ],
+        )
+
+    @classmethod
+    def execute(cls, embedding: str, old_keys: str,
+                new_keys: str, output_filename: str) -> io.NodeOutput:
+        path = _rename_keys(embedding, "embeddings",
+                           old_keys, new_keys, output_filename)
+        return io.NodeOutput(path)

nodes/utils.py

@@ -0,0 +1,34 @@
+import torch
+from safetensors import safe_open
+from safetensors.torch import save_file
+from comfy.model_management import get_torch_device
+
+def convert_pt_to_safetensors(pt_path, safe_path):
+    try:
+        model = torch.load(pt_path, map_location="cpu")
+        if "state_dict" in model:
+            state_dict = model["state_dict"]
+        elif "model" in model:
+            state_dict = model["model"]
+        else:
+            state_dict = model
+        state_dict = {k.replace("state_dict.", ""): v for k, v in state_dict.items()}
+        metadata = {"format": "pt"}
+        save_file(state_dict, safe_path, metadata)
+        return True, ""
+    except Exception as e:
+        return False, str(e)
+
+def load_metadata_from_safetensors(safetensors_file: str) -> dict:
+    try:
+        with safe_open(safetensors_file, framework="pt", device="cpu") as f:
+            model_weights = {}
+            for key in f.keys():
+                model_weights[key] = f.get_tensor(key)
+            metadata = f.metadata()
+        if metadata is None:
+            metadata = {}
+        return model_weights, metadata
+    except Exception as e:
+        print(f"Error loading safetensors file: {e}")
+        return {}, {}

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "ComfyUI-ModelUtils"
 description = "[WIP]Custom nodes for handling, inspecting, modifying and creating various model files."
-version = "0.1.3"
+version = "0.2.0"
 license = { file = "LICENSE" }
 
 [project.urls]

requirements.txt

@@ -0,0 +1 @@
+# No external dependencies required