efficiency-nodes-comfyui/.github/copilot-instructions.md

Copilot Instructions for Efficiency Nodes ComfyUI

Repository Overview

This repository provides custom efficiency nodes for ComfyUI, a powerful node-based UI for Stable Diffusion. The nodes streamline workflows by combining multiple operations into efficient, cached, and preview-enabled nodes.

Project Structure

• efficiency_nodes.py: Main file containing all 45+ node class definitions (4,464 lines)
• tsc_utils.py: Utility functions for caching, tensor operations, and console messaging
• __init__.py: Entry point that exports NODE_CLASS_MAPPINGS for ComfyUI
• py/: Specialized modules for upscaling, sampling, encoding, and tiling
• node_settings.json: Configuration for model caching behavior
• requirements.txt: Python dependencies (clip-interrogator, simpleeval)

Core Architecture

Node Pattern

All custom nodes follow the ComfyUI standard structure:

class TSC_NodeName:
    @classmethod
    def INPUT_TYPES(cls):
        return {
            "required": {...},  # Required inputs
            "optional": {...},  # Optional inputs
            "hidden": {...}     # Hidden inputs (UNIQUE_ID, PROMPT)
        }
    
    RETURN_TYPES = ("TYPE1", "TYPE2")
    RETURN_NAMES = ("output1", "output2")
    FUNCTION = "method_name"
    CATEGORY = "Efficiency Nodes/SubCategory"
    
    def method_name(self, **kwargs):
        # Node logic here
        return (result1, result2)

Naming Conventions

• Classes: Use TSC_ prefix (creator's initials) + descriptive name in PascalCase
  • Examples: TSC_EfficientLoader, TSC_KSampler, TSC_XYplot
• Methods: Use snake_case for all methods
• Constants: Use UPPER_SNAKE_CASE for module-level constants

Custom Data Types

The repository defines several custom types for workflow composition:

• LORA_STACK: Tuple for stacking multiple LoRA models
• CONTROL_NET_STACK: Tuple for stacking ControlNet configurations
• SCRIPT: Type for chaining script operations (XY Plot, HighRes-Fix, etc.)
• XY: Type for XY plot data
• SDXL_TUPLE: SDXL-specific configuration tuple

Key Patterns

1. Wrapper Pattern

Efficiency nodes wrap base ComfyUI nodes to add features:

# Wraps KSampler with caching, preview, and script support
class TSC_KSampler:
    def sample(self, ...):
        # Check cache
        # Execute base KSampler
        # Store results
        # Handle script execution
        # Return enhanced output

2. Caching System

Use the caching utilities from tsc_utils.py:

from tsc_utils import load_ksampler_results, store_ksampler_results

# Load cached results
cached = load_ksampler_results(unique_id, prompt)

# Store results for future use
store_ksampler_results(unique_id, prompt, results)

Important: Cache operations use unique_id and prompt from hidden inputs to ensure per-instance caching.

3. Stack Pattern

Support stacking for composable workflows:

"optional": {
    "lora_stack": ("LORA_STACK",),
    "cnet_stack": ("CONTROL_NET_STACK",),
}

4. Script System

Nodes can execute scripts for advanced workflows:

"optional": {
    "script": ("SCRIPT",),
}

# In node execution:
if script:
    # Execute script logic (XY Plot, HighRes-Fix, etc.)

5. Dynamic UI Inputs

Use folder_paths for dynamic dropdown population:

import folder_paths

"required": {
    "ckpt_name": (folder_paths.get_filename_list("checkpoints"),),
    "vae_name": (["Baked VAE"] + folder_paths.get_filename_list("vae"),),
}

Dependencies

Required

• PyTorch: Core tensor operations
• PIL: Image processing
• NumPy: Array operations
• clip-interrogator: Image captioning
• simpleeval: Safe expression evaluation

ComfyUI Integration

The code integrates with ComfyUI via sys.path manipulation:

# Pattern used throughout codebase
comfy_dir = os.path.abspath(os.path.join(my_dir, '..', '..'))
sys.path.append(comfy_dir)
from comfy import samplers, sd, utils
# ... imports ...
sys.path.remove(comfy_dir)

Optional Dependencies

• comfyui_controlnet_aux: ControlNet preprocessing
• ComfyUI-AnimateDiff-Evolved: AnimateDiff support

Handle optional dependencies gracefully:

try:
    import optional_module
    NODE_CLASS_MAPPINGS.update({"Node Name": NodeClass})
except ImportError:
    pass

Node Registration

Nodes are registered in NODE_CLASS_MAPPINGS dictionary:

NODE_CLASS_MAPPINGS = {
    "Display Name": TSC_ClassName,
    "KSampler (Efficient)": TSC_KSampler,
    "Efficient Loader": TSC_EfficientLoader,
    # ... more nodes
}

# Optional nodes added conditionally
try:
    from simpleeval import simple_eval
    NODE_CLASS_MAPPINGS.update({
        "Simple Eval Examples": TSC_SimpleEval,
    })
except ImportError:
    print("simpleeval not installed, skipping related nodes")

Code Style Guidelines

Imports

1. Standard library imports first
2. Third-party imports (torch, PIL, numpy)
3. ComfyUI imports (with path manipulation)
4. Local imports (tsc_utils, py modules)

Error Handling

Use the colored messaging functions from tsc_utils.py:

from tsc_utils import error, warning, success

try:
    # Operation
    success("Operation completed")
except Exception as e:
    error(f"Operation failed: {e}")

Input Validation

Validate inputs in the INPUT_TYPES definition:

"seed": ("INT", {"default": 0, "min": 0, "max": 0xffffffffffffffff}),
"steps": ("INT", {"default": 20, "min": 1, "max": 10000}),
"cfg": ("FLOAT", {"default": 8.0, "min": 0.0, "max": 100.0}),
"sampler_name": (comfy.samplers.KSampler.SAMPLERS,),

Testing and Validation

This repository does not have formal unit tests. Changes should be validated by:

1. Import Test: Verify __init__.py imports successfully
2. ComfyUI Integration: Load nodes in ComfyUI UI and verify they appear
3. Workflow Test: Create test workflows and verify node functionality
4. Error Testing: Test edge cases and ensure graceful error messages

Common Patterns to Follow

Adding a New Node

1. Create class with TSC_ prefix
2. Define INPUT_TYPES, RETURN_TYPES, FUNCTION, CATEGORY
3. Implement the function method
4. Add to NODE_CLASS_MAPPINGS
5. Test in ComfyUI workflow

Adding Optional Features

1. Wrap in try/except for dependency checking
2. Use .update() to add to NODE_CLASS_MAPPINGS
3. Provide fallback or skip if dependency missing
4. Print informative message about missing dependency

Working with Models

1. Use folder_paths for model discovery
2. Implement caching via tsc_utils functions
3. Store loaded models in loaded_objects dict with unique IDs
4. Handle model loading errors gracefully

Handling UI Updates

1. Use hidden inputs for UNIQUE_ID and PROMPT tracking
2. Return UI update dictionaries when needed
3. Follow ComfyUI's output format for preview images

Performance Considerations

• Caching: Always use caching for expensive operations (model loading, sampling)
• Memory: Be mindful of GPU memory with large models
• Preview: Implement progressive preview for long operations
• Batching: Support batch processing where applicable

Documentation

• Update README.md for new nodes
• Add examples to the project Wiki
• Include workflow JSON examples for complex nodes
• Document any new configuration options in node_settings.json

Key Files to Understand

1. efficiency_nodes.py: Study existing nodes for patterns
2. tsc_utils.py: Understand caching and utility functions
3. py/bnk_adv_encode.py: Advanced CLIP encoding examples
4. py/smZ_cfg_denoiser.py: Custom denoiser implementation
5. init.py: Entry point and version management

ComfyUI-Specific Tips

• Nodes are instantiated fresh for each workflow execution
• Use UNIQUE_ID from hidden inputs for per-node-instance state
• PROMPT contains the full workflow graph
• Return types must match RETURN_TYPES exactly
• UI widgets are defined in INPUT_TYPES with tuples
• Use folder_paths for discovering models/resources

Version Information

• Current version: 2.0+ (see CC_VERSION in __init__.py)
• Published to ComfyUI registry via pyproject.toml
• Auto-publishes on main branch when pyproject.toml changes

Resources

• ComfyUI Repository
• Project Wiki
• Project README
• Original author: Luciano Cirino (TSC)
• Current maintainer: jags111