MatthewClayHarrison-ComfyUI-MetaMan/SETUP.md

MetaMan Setup and Configuration Guide

This guide helps you install, configure, and troubleshoot MetaMan for ComfyUI.

Quick Start

1. Installation

1. Clone to ComfyUI custom nodes:

   cd /path/to/ComfyUI/custom_nodes/
   git clone <repository-url> MetaMan
   

2. Install dependencies:

   cd MetaMan
   pip install -r requirements.txt
   

3. Test installation:

   python test_installation.py
   

4. Restart ComfyUI

2. First Use

1. Start ComfyUI
2. Look for "MetaMan" category in node browser
3. Add "MetaMan Universal" node to your workflow
4. Connect an image with AI metadata
5. Set operation to "extract_universal"
6. Run the workflow to see extracted metadata

Detailed Setup

Dependencies

MetaMan requires these Python packages:

• Pillow >= 9.0.0 (image processing)
• PyYAML >= 6.0.0 (template loading)
• piexif >= 1.1.3 (EXIF handling)
• requests >= 2.28.0 (API integration)
• jsonschema >= 4.17.0 (validation)

These are usually already available in ComfyUI environments:

• torch (tensor operations)
• json (metadata processing)

Directory Structure

After installation, your MetaMan directory should look like:

MetaMan/
├── __init__.py                 # Main package file
├── metamann.py                 # Universal metadata node
├── specialized_nodes.py        # Workflow saver & dependency resolver
├── metadata_parser.py          # Metadata parsing utilities
├── api_integration.py          # Model repository APIs
├── validation.py               # Testing and validation
├── test_installation.py        # Installation test script
├── requirements.txt            # Python dependencies
├── README.md                   # Main documentation
├── SETUP.md                    # This file
├── templates/
│   ├── universal_schema.yaml   # Universal metadata schema
│   └── services/               # Service-specific templates
│       ├── automatic1111.yaml
│       ├── comfyui.yaml
│       ├── civitai.yaml
│       ├── forge.yaml
│       ├── tensor.ai.yaml
│       └── leonardo.ai.yaml
└── examples/
    └── README.md               # Usage examples

Configuration

Adding New Services

To add support for a new AI image generation service:

1. Create service template:

   cp templates/services/automatic1111.yaml templates/services/newservice.yaml
   

2. Edit the template:

   • Update service_name
   • Define output_format
   • Configure field mappings
   • Set PNG chunk specifications

3. Update universal schema (if needed):

   • Add new fields to templates/universal_schema.yaml
   • Specify which services support each field

4. Test the new service:

   python validation.py
   

Customizing Templates

Templates are YAML files that define how metadata is converted between formats. Key sections:

• Field mappings: How universal fields map to service-specific formats
• Output format: Text, JSON, or mixed format specifications
• PNG chunks: How metadata is embedded in images
• Validation rules: Required fields and format constraints

API Configuration

For model dependency resolution, you can configure:

• Rate limiting: Adjust min_interval in api_integration.py
• Search sources: Enable/disable specific model repositories
• Confidence thresholds: Minimum confidence for accepting matches

Available Nodes

MetaMan Universal

• Purpose: Main metadata extraction and conversion node
• Operations:
  • extract_universal - Extract to universal format
  • convert_to_service - Convert to specific service format
  • save_workflow - Save workflow data
  • generate_dependencies - Find model dependencies
  • export_metadata - Export in various formats

MetaMan Workflow Saver

• Purpose: Specialized workflow preservation
• Formats:
  • embed_in_image - Embed workflow in PNG chunks
  • json_file - Save as standalone JSON
  • both - Both embedded and file
  • workflow_only - ComfyUI workflow graph only
  • prompt_only - ComfyUI prompt data only

MetaMan Dependency Resolver

• Purpose: Find and resolve model dependencies
• Sources:
  • all - Search all available sources
  • civitai_only - Civitai models only
  • huggingface_only - HuggingFace models only
  • civitai_then_hf - Civitai first, then HuggingFace

Troubleshooting

Common Issues

1. "MetaMan nodes not appearing in ComfyUI"

• Check ComfyUI console for import errors
• Verify all dependencies are installed: pip install -r requirements.txt
• Run installation test: python test_installation.py
• Restart ComfyUI completely

2. "Import errors on startup"

# Install missing dependencies
pip install PyYAML piexif requests jsonschema

# For conda environments
conda install -c conda-forge pyyaml piexif requests jsonschema

3. "Metadata not detected from images"

• Ensure image contains PNG text chunks with metadata
• Check supported formats in metadata_parser.py
• Some services use proprietary formats not yet supported

4. "Template loading errors"

• Verify YAML syntax in template files
• Run validation: python validation.py
• Check file permissions on templates directory

5. "API integration not working"

• Check internet connection for model repository access
• Verify rate limiting settings if getting blocked
• Some APIs require authentication (future feature)

Debug Mode

Enable verbose logging:

export METAMAN_DEBUG=1

Or in Python:

import os
os.environ['METAMAN_DEBUG'] = '1'

Log Files

ComfyUI logs MetaMan activities to the console. Look for:

• MetaMan: prefixed messages
• Import errors during startup
• Node execution errors during workflow runs

Getting Help

1. Check the documentation: README.md and examples/
2. Run diagnostics: python test_installation.py
3. Validate templates: python validation.py
4. Check ComfyUI console: Look for error messages
5. File an issue: Include error messages and system info

Advanced Configuration

Custom Universal Schema

You can extend the universal schema to support new metadata fields:

1. Edit templates/universal_schema.yaml

2. Add new field definitions with:

   • Field type (string, integer, float, boolean, array, object)
   • Supported services list
   • Validation rules (range, options, format)
   • Default values

3. Update service templates to handle new fields

4. Test with validation script

Performance Tuning

For large workflows or batch processing:

• Enable compression: Set compress_data=True for PNG chunks
• Limit API calls: Adjust rate limiting in api_integration.py
• Cache results: Enable cache_results=True for dependency resolution
• Reduce confidence threshold: Lower min_confidence for faster matching

Network Configuration

If behind a firewall or proxy:

# Add to api_integration.py
session.proxies = {
    'http': 'http://proxy.company.com:8080',
    'https': 'https://proxy.company.com:8080'
}

Development

Running Tests

# Full validation suite
python validation.py

# Installation test only
python test_installation.py

# Test specific template
python validation.py templates/services/automatic1111.yaml

Adding New Features

1. New metadata fields: Update universal schema first
2. New services: Create template file and test
3. New operations: Add to MetaManUniversalNode.INPUT_TYPES
4. New nodes: Follow pattern in specialized_nodes.py

Contributing

1. Fork the repository
2. Create feature branch
3. Add tests for new functionality
4. Update documentation
5. Submit pull request

---

For more information, see the main README.md or visit the project repository.