comfyui_sdk_dart 0.1.0

A comprehensive Dart SDK for interacting with ComfyUI's machine learning workflow API. Create, validate, and execute ML workflows with type safety and real-time event handling.

ComfyUI SDK for Dart

A powerful and type-safe Dart SDK for interacting with ComfyUI's API. This SDK provides comprehensive support for ComfyUI's REST API and WebSocket events, making it easy to create and manage AI image generation workflows.

Features

• 🚀 Full ComfyUI API support
• 🔄 Real-time WebSocket event handling
• 🛡️ Type-safe API interactions
• 🎯 Robust error handling
• ⚡ Async/await support
• 🔍 Input validation
• 📦 Workflow management
• 📊 Progress tracking
• 🔄 Queue management
• 🧪 Comprehensive testing

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  comfyui_sdk_dart: ^0.1.0

Quick Start

import 'package:comfyui_sdk_dart/comfyui_sdk_dart.dart';

void main() async {
  // Initialize client and connect
  final client = ComfyClient(baseUrl: 'http://localhost:8188');
  await client.init();

  // Create a text-to-image workflow
  final workflow = Workflow(
    nodes: {
      'loader': WorkflowNode(
        id: 'loader',
        type: 'CheckpointLoaderSimple',
        inputs: {'ckpt_name': 'v1-5-pruned.safetensors'},
      ),
      'prompt': WorkflowNode(
        id: 'prompt',
        type: 'CLIPTextEncode',
        inputs: {
          'text': 'a beautiful landscape with mountains',
          'clip': {'@from': 'loader.CLIP'},
        },
      ),
      'sampler': WorkflowNode(
        id: 'sampler',
        type: 'KSampler',
        inputs: {
          'model': {'@from': 'loader.MODEL'},
          'positive': {'@from': 'prompt.CONDITIONING'},
          'seed': 42,
          'steps': 20,
          'cfg': 7.5,
          'sampler_name': 'euler',
          'scheduler': 'normal',
          'latent_image': {'@from': 'empty.LATENT'},
        },
      ),
      'empty': WorkflowNode(
        id: 'empty',
        type: 'EmptyLatentImage',
        inputs: {
          'width': 512,
          'height': 512,
          'batch_size': 1,
        },
      ),
      'decoder': WorkflowNode(
        id: 'decoder',
        type: 'VAEDecode',
        inputs: {
          'samples': {'@from': 'sampler.LATENT'},
          'vae': {'@from': 'loader.VAE'},
        },
      ),
      'save': WorkflowNode(
        id: 'save',
        type: 'SaveImage',
        inputs: {
          'images': {'@from': 'decoder.IMAGE'},
          'filename_prefix': 'landscape',
        },
      ),
    },
    edges: {
      'loader': {
        'CLIP': {
          'prompt': 'clip',
        },
        'MODEL': {
          'sampler': 'model',
        },
        'VAE': {
          'decoder': 'vae',
        },
      },
      'prompt': {
        'CONDITIONING': {
          'sampler': 'positive',
        },
      },
      'empty': {
        'LATENT': {
          'sampler': 'latent_image',
        },
      },
      'sampler': {
        'LATENT': {
          'decoder': 'samples',
        },
      },
      'decoder': {
        'IMAGE': {
          'save': 'images',
        },
      },
    },
  );

  // Listen to events
  client.events.listen((event) {
    switch (event.type) {
      case 'execution_start':
        print('Workflow started');
        break;
      case 'executing':
        final progress = event.data['value'] / event.data['max'] * 100;
        print('Progress: ${progress.toStringAsFixed(1)}%');
        break;
      case 'execution_complete':
        print('Workflow completed');
        break;
    }
  });

  try {
    // Queue the workflow
    final response = await client.queuePrompt(workflow);
    print('Queued with ID: ${response.promptId}');

    // Wait for completion and get results
    await Future.delayed(Duration(seconds: 5));
    final history = await client.getHistory();
    print('Latest outputs: ${history.first.outputs}');
  } catch (e) {
    print('Error: $e');
  } finally {
    await client.close();
  }
}

Examples

Check out our comprehensive examples in the example directory:

• Basic Workflow - Simple workflow creation and execution
• Text to Image - Text prompt to image generation
• Image to Image - Image modification with text prompt
• WebSocket Events - Real-time event handling
• Error Handling - Comprehensive error handling examples

API Reference

ComfyClient

The main client for interacting with ComfyUI:

final client = ComfyClient(baseUrl: 'http://localhost:8188');

// Initialize and connect
await client.init();

// Core methods
await client.queuePrompt(workflow);     // Queue a workflow
await client.getHistory();              // Get execution history
await client.getSystemInfo();           // Get system stats
await client.getObjectInfo();           // Get node information
await client.getQueue();                // Get current queue
await client.deleteQueueItem(promptId); // Delete from queue
await client.interrupt();               // Stop execution
await client.close();                   // Clean up

Event Handling

Real-time updates through WebSocket events:

client.events.listen((event) {
  switch (event.type) {
    case 'execution_start':
      print('Started: ${event.data}');
      break;
    case 'executing':
      print('Progress: ${event.data}');
      break;
    case 'executed':
      print('Node done: ${event.data}');
      break;
    case 'execution_complete':
      print('Completed: ${event.data}');
      break;
  }
});

Error Handling

Comprehensive error handling with custom exceptions:

try {
  await client.queuePrompt(workflow);
} on ComfyWebSocketException catch (e) {
  print('WebSocket error: $e');
} on ComfyApiException catch (e) {
  print('API error: $e');
} on ComfyException catch (e) {
  print('General error: $e');
}

Models

Workflow

A complete workflow with nodes and edges:

final workflow = Workflow(
  nodes: {
    'node1': WorkflowNode(...),
    'node2': WorkflowNode(...),
  },
  edges: {
    'node1': {
      'OUTPUT': {
        'node2': 'input',
      },
    },
  },
);

WorkflowNode

A node in the workflow:

final node = WorkflowNode(
  id: 'unique_id',
  type: 'NodeType',
  inputs: {
    'param1': 'value1',
    'param2': {'@from': 'other_node.OUTPUT'},
  },
);

Development

Running Tests

# Run all tests
dart test

# Run with coverage
dart test --coverage=coverage
dart run coverage:format_coverage --packages=.packages --report-on=lib --lcov -o coverage/lcov.info -i coverage

Generating Code

# Generate JSON serialization code
dart run build_runner build --delete-conflicting-outputs

Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.