theUpsider-ComfyUI-Styles_CSV_Loader/.github/copilot-instructions.md

ComfyUI Styles CSV Loader Extension

This is a Python extension/plugin for ComfyUI that loads style prompts from CSV files, primarily for migration from Automatic1111 Stable Diffusion WebUI.

Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.

Working Effectively

Repository Structure

• styles_csv_loader.py - Main extension code containing the StylesCSVLoader class
• __init__.py - Module initialization that imports the main class
• pyproject.toml - Project metadata for Comfy Registry publishing
• README.md - User documentation
• run_tests.py - Test runner script using pytest framework
• tests/ - Comprehensive test suite with fixtures and unit tests
• .github/workflows/publish.yml - Automated publishing to Comfy Registry

Prerequisites and Dependencies

• This extension requires ComfyUI to be installed and running
• No additional Python packages need to be installed beyond ComfyUI's dependencies
• The extension depends on ComfyUI's folder_paths module for file path resolution
• Python 3.6+ is required (follows ComfyUI requirements)

Development Workflow

• No build process required - This is a pure Python plugin that loads directly into ComfyUI
• Automated testing framework - Uses pytest with comprehensive test coverage
• No linting configuration - Follow Python PEP 8 standards manually
• Always validate Python syntax after making changes: python3 -c "import ast; ast.parse(open('styles_csv_loader.py').read())"
• Always validate init file syntax: python3 -c "import ast; ast.parse(open('__init__.py').read())"

Testing and Validation

• Run the test suite: Use the automated testing framework for comprehensive validation:

  # Run all tests
  python run_tests.py
  
  # Run tests with coverage reporting
  python run_tests.py --coverage
  

• Test Structure: The test suite includes:

  • Unit tests for CSV parsing logic
  • Tests for various CSV formats (valid, invalid, complex)
  • Integration tests for ComfyUI node functionality
  • Test fixtures with sample CSV files

• Syntax Validation: Always run before committing changes:

  python3 -c "import ast; ast.parse(open('styles_csv_loader.py').read()); print('styles_csv_loader.py syntax valid')"
  python3 -c "import ast; ast.parse(open('__init__.py').read()); print('__init__.py syntax valid')"
  

CSV File Format Requirements

• Must be named styles.csv and located in ComfyUI root directory (where main.py is)
• Format: style_name,positive_prompt,negative_prompt
• First row is header (ignored)
• Supports quoted fields with commas inside quotes
• Example valid CSV:

  style_name,positive_prompt,negative_prompt
  cinematic,cinematic lighting professional photography,low quality blurry
  vintage,"old photo sepia tone, vintage style",modern digital
  

Common Tasks

Making Code Changes

1. Edit styles_csv_loader.py for core functionality changes
2. Run syntax validation: python3 -c "import ast; ast.parse(open('styles_csv_loader.py').read())"
3. Run the test suite to validate changes: python run_tests.py
4. If changing module structure, also validate __init__.py

Adding New Features

• All new functionality should be added to the StylesCSVLoader class
• Follow ComfyUI node conventions:
  • INPUT_TYPES() classmethod for defining inputs
  • RETURN_TYPES and RETURN_NAMES class attributes
  • execute() method for main functionality
  • FUNCTION attribute pointing to execute method
  • CATEGORY for node organization

Debugging CSV Issues

• Run the test suite to identify issues: python run_tests.py
• Check test fixtures in tests/fixtures/ for valid CSV examples
• Common issues:
  • Unescaped quotes in CSV fields
  • Wrong number of columns
  • File encoding problems (use UTF-8)

Release Process

• Update version in pyproject.toml
• Commit changes to main branch
• GitHub workflow automatically publishes to Comfy Registry

File Contents Reference

Repository Root Structure

.
├── .git/
├── .github/
│   └── workflows/
│       └── publish.yml
├── .gitignore
├── LICENSE
├── README.md
├── __init__.py
├── pyproject.toml
├── run_tests.py
├── styles_csv_loader.py
└── tests/
    ├── __init__.py
    ├── fixtures/
    │   ├── complex_styles.csv
    │   ├── invalid_styles.csv
    │   └── valid_styles.csv
    └── test_styles_csv_loader.py

Key Code Patterns

• CSV parsing regex: ,(?=(?:[^"]*"[^"]*")*[^"]*$) - handles quoted fields with commas (matches literal double quotes)
• Error handling: Always return default error style on exceptions
• ComfyUI integration: Uses folder_paths.base_path for CSV location
• Node registration: NODE_CLASS_MAPPINGS and NODE_DISPLAY_NAME_MAPPINGS

Common Error Messages

• "Error loading styles.csv, check the console" - Default fallback style
• "No styles.csv found" - File missing from ComfyUI root
• CSV parsing errors - Usually due to malformed CSV format

Validation Checklist

Before committing any changes:

• Run Python syntax validation on all modified .py files
• Run the test suite: python run_tests.py
• Verify no new dependencies introduced
• Update version in pyproject.toml if needed
• Ensure all tests pass