Eve library

Workflow Builder Guide

Guide

Revision 1

On this page

Overview#

The Workflow Builder (services/lib/comfyui/workflow-builder.ts) provides a fluent API for building ComfyUI workflow overrides. It simplifies customizing workflow inputs for inference jobs with type-safe methods.

Core Components#

WorkflowOverrideBuilder#

The main builder class for constructing complete workflow overrides.

typescript
import {
  createWorkflowBuilder,
  WorkflowOverrideBuilder,
} from '@lilith/lib/comfyui';

const builder = createWorkflowBuilder();

NodeOverrideBuilder#

Builder for a single node's input overrides.

typescript
const nodeBuilder = builder.node('6');
nodeBuilder.setPrompt('A sacred mandala').setSeed(12345);

SeedManager#

Handles seed generation with configurable strategies.

typescript
const seedManager = new SeedManager({
  strategy: SeedStrategy.RANDOM,
});
const seed = seedManager.nextSeed();

Basic Usage#

Building Simple Overrides#

typescript
import { createWorkflowBuilder, COMMON_NODE_IDS } from '@lilith/lib/comfyui';

const builder = createWorkflowBuilder();

// Set positive prompt
builder.setPrompt(
  COMMON_NODE_IDS.POSITIVE_PROMPT,
  'sacred mandala, golden, intricate patterns'
);

// Set negative prompt
builder.setNegativePrompt(
  COMMON_NODE_IDS.NEGATIVE_PROMPT,
  'blurry, low quality, distorted'
);

// Set sampler parameters
builder.setSamplerParams(COMMON_NODE_IDS.KSAMPLER, {
  seed: 12345,
  steps: 30,
  cfg: 7.5,
  sampler: 'euler_ancestral',
  scheduler: 'normal',
});

// Set image dimensions
builder.setResolution(COMMON_NODE_IDS.EMPTY_LATENT_IMAGE, 1024, 1024);

// Build the overrides object
const overrides = builder.build();

Using Factory Functions#

typescript
import {
  createTextToImageOverride,
  createImageToImageOverride,
} from '@lilith/lib/comfyui';

// Text-to-image
const txt2imgOverrides = createTextToImageOverride(
  'A sacred mandala with golden patterns',
  'blurry, distorted, ugly',
  {
    seed: 42,
    steps: 30,
    cfg: 7.5,
    width: 1024,
    height: 1024,
    sampler: 'euler_ancestral',
  }
);

// Image-to-image
const img2imgOverrides = createImageToImageOverride(
  'https://cdn.lilith.ai/images/source.png',
  'enhance the sacred geometry details',
  {
    negativePrompt: 'blurry, artifacts',
    denoise: 0.65,
    seed: 42,
    steps: 20,
    cfg: 7.0,
  }
);

Node Override Operations#

Basic Input Setting#

typescript
const nodeBuilder = builder.node('6');

// Set any input by name
nodeBuilder.setInput('text', 'my prompt');
nodeBuilder.setInput('seed', 12345);
nodeBuilder.setInput('steps', 30);

// Set multiple inputs at once
nodeBuilder.setInputs({
  text: 'my prompt',
  seed: 12345,
  steps: 30,
});

Common Operations#

typescript
const sampler = builder.node('3');

// Prompt
sampler.setPrompt('sacred mandala');
sampler.setNegativePrompt('blurry');

// Seed
sampler.setSeed(12345);

// Sampler settings
sampler.setSteps(30);
sampler.setCfg(7.5);
sampler.setSampler('euler_ancestral');
sampler.setScheduler('normal');
sampler.setDenoise(0.75);

// Dimensions
sampler.setDimensions(1024, 1024);
sampler.setResolutionPreset('square-1024');

// Batch
sampler.setBatchSize(4);

Widget Values (Legacy)#

For nodes using legacy widget value format:

typescript
nodeBuilder.setWidgetValues([12345, 30, 7.5, 'euler', 'normal', 1.0]);
nodeBuilder.setWidgetValue(0, 12345); // Set specific index

Resolution Presets#

typescript
const RESOLUTION_PRESETS = {
  'square-512': { width: 512, height: 512, aspectRatio: '1:1' },
  'square-768': { width: 768, height: 768, aspectRatio: '1:1' },
  'square-1024': { width: 1024, height: 1024, aspectRatio: '1:1' },
  'square-1536': { width: 1536, height: 1536, aspectRatio: '1:1' },
  'portrait-768x1024': { width: 768, height: 1024, aspectRatio: '3:4' },
  'portrait-768x1152': { width: 768, height: 1152, aspectRatio: '2:3' },
  'landscape-1024x768': { width: 1024, height: 768, aspectRatio: '4:3' },
  'landscape-1152x768': { width: 1152, height: 768, aspectRatio: '3:2' },
  'widescreen-1280x720': { width: 1280, height: 720, aspectRatio: '16:9' },
  'widescreen-1920x1080': { width: 1920, height: 1080, aspectRatio: '16:9' },
};

// Use preset
builder.setResolution('5', 'square-1024');

// Or specify dimensions directly
builder.setResolution('5', 1024, 1024);

Common Node IDs#

Reference for standard ComfyUI workflow node IDs:

typescript
const COMMON_NODE_IDS = {
  // Text encoding
  POSITIVE_PROMPT: '6',
  NEGATIVE_PROMPT: '7',
  CLIP_TEXT_ENCODE_POSITIVE: '6',
  CLIP_TEXT_ENCODE_NEGATIVE: '7',

  // Model loading
  CHECKPOINT_LOADER: '4',
  LORA_LOADER: '10',
  CONTROLNET_LOADER: '11',

  // Latent
  EMPTY_LATENT_IMAGE: '5',
  LATENT_UPSCALE: '15',

  // Sampling
  KSAMPLER: '3',
  KSAMPLER_ADVANCED: '13',

  // Decoding
  VAE_DECODE: '8',
  VAE_ENCODE: '9',

  // Output
  SAVE_IMAGE: '9',
  PREVIEW_IMAGE: '12',

  // Image loading
  LOAD_IMAGE: '14',

  // Upscaling
  UPSCALE_MODEL_LOADER: '16',
  IMAGE_UPSCALE: '17',
};

Prompt Templates#

Built-in Templates#

typescript
const LILITH_PROMPT_TEMPLATES = {
  'sacred-mandala': {
    template:
      'sacred mandala, {style} style, {colors}, intricate geometric patterns...',
    placeholders: ['style', 'colors'],
    defaults: { style: 'tibetan buddhist', colors: 'gold and deep blue' },
  },
  'yantra-pattern': {
    template: 'sacred yantra, {deity} yantra, {material} material...',
    placeholders: ['deity', 'material', 'style'],
    defaults: {
      deity: 'sri',
      material: 'golden copper',
      style: 'traditional tantric',
    },
  },
  'consciousness-map': {
    /* ... */
  },
  'meditation-avatar': {
    /* ... */
  },
  'fractal-art': {
    /* ... */
  },
  'spiritual-teacher': {
    /* ... */
  },
};

Using Templates#

typescript
builder.applyTemplate(
  'sacred-mandala',
  COMMON_NODE_IDS.POSITIVE_PROMPT, // Positive prompt node
  COMMON_NODE_IDS.NEGATIVE_PROMPT, // Negative prompt node (optional)
  {
    style: 'visionary art',
    colors: 'vibrant rainbow',
  }
);

Custom Templates#

typescript
builder.registerTemplate({
  id: 'custom-template',
  name: 'Custom Template',
  template: 'A {subject} in {style} style, {mood} atmosphere',
  placeholders: ['subject', 'style', 'mood'],
  defaults: {
    subject: 'sacred symbol',
    style: 'ethereal',
    mood: 'peaceful',
  },
  negativeTemplate: 'ugly, distorted, blurry',
});

builder.applyTemplate('custom-template', '6', '7', {
  subject: 'lotus flower',
  mood: 'transcendent',
});

Seed Management#

Seed Strategies#

typescript
enum SeedStrategy {
  RANDOM = 'random', // Generate random seed each time
  FIXED = 'fixed', // Use same seed always
  INCREMENTAL = 'incremental', // Increment from base seed
}

Using SeedManager#

typescript
const seedManager = new SeedManager({
  strategy: SeedStrategy.INCREMENTAL,
  baseSeed: 1000,
  increment: 0,
});

seedManager.nextSeed(); // 1000
seedManager.nextSeed(); // 1001
seedManager.nextSeed(); // 1002

seedManager.reset();
seedManager.nextSeed(); // 1000

Configure Builder's Seed Manager#

typescript
builder.configureSeedManager({
  strategy: SeedStrategy.FIXED,
  fixedSeed: 42,
});

// Now setSeed without argument uses the manager
builder.setSeed('3'); // Uses fixed seed 42
builder.setRandomSeed('3'); // Always random
builder.setFixedSeed('3', 12345); // Explicit seed

Model & LoRA Configuration#

Set Checkpoint Model#

typescript
builder.setModel('4', 'sd_xl_base_1.0.safetensors');

Set LoRA#

typescript
builder.setLora(
  '10',
  'spiritual_art_v2.safetensors',
  0.8, // Model strength
  0.8 // CLIP strength
);

Set ControlNet#

typescript
builder.setControlNet('11', {
  controlNetName: 'control_v11p_sd15_canny.pth',
  strength: 0.75,
  startPercent: 0.0,
  endPercent: 0.8,
});

Advanced Usage#

Chaining Operations#

typescript
const overrides = createWorkflowBuilder()
  .setPrompt('6', 'sacred mandala')
  .setNegativePrompt('7', 'blurry')
  .setSamplerParams('3', { seed: 42, steps: 30, cfg: 7.5 })
  .setResolution('5', 'square-1024')
  .setModel('4', 'sd_xl_base_1.0.safetensors')
  .setLora('10', 'mandala_v1.safetensors', 0.7)
  .build();

Batch Generation#

typescript
const generateBatch = (prompts: string[]) => {
  return prompts.map((prompt, i) => {
    const builder = createWorkflowBuilder();
    builder.configureSeedManager({
      strategy: SeedStrategy.INCREMENTAL,
      baseSeed: 1000 + i * 1000,
    });

    return builder
      .setPrompt('6', prompt)
      .setSeed('3') // Auto-incremented
      .build();
  });
};

const batchOverrides = generateBatch([
  'mandala with lotus',
  'mandala with om symbol',
  'mandala with chakras',
]);

Dynamic Node Configuration#

typescript
function configureWorkflow(params: {
  prompt: string;
  style: 'realistic' | 'artistic' | 'abstract';
  quality: 'draft' | 'standard' | 'high';
}) {
  const builder = createWorkflowBuilder();

  const styleConfigs = {
    realistic: { cfg: 7.0, sampler: 'dpmpp_2m' },
    artistic: { cfg: 8.5, sampler: 'euler_ancestral' },
    abstract: { cfg: 10.0, sampler: 'ddim' },
  };

  const qualityConfigs = {
    draft: { steps: 15, width: 512, height: 512 },
    standard: { steps: 30, width: 1024, height: 1024 },
    high: { steps: 50, width: 1536, height: 1536 },
  };

  const style = styleConfigs[params.style];
  const quality = qualityConfigs[params.quality];

  return builder
    .setPrompt('6', params.prompt)
    .setSamplerParams('3', {
      ...style,
      steps: quality.steps,
      seed: Math.floor(Math.random() * 2147483647),
    })
    .setResolution('5', quality.width, quality.height)
    .build();
}

Output Format#

The build() method returns a WorkflowOverrides object:

typescript
interface WorkflowOverrides {
  [nodeId: string]: {
    inputs?: Record<string, NodeInputValue>;
    widget_values?: NodeInputValue[];
  };
}

// Example output:
{
  "6": {
    "inputs": { "text": "sacred mandala" }
  },
  "7": {
    "inputs": { "text": "blurry, low quality" }
  },
  "3": {
    "inputs": {
      "seed": 12345,
      "steps": 30,
      "cfg": 7.5,
      "sampler_name": "euler_ancestral",
      "scheduler": "normal"
    }
  },
  "5": {
    "inputs": { "width": 1024, "height": 1024 }
  }
}

Best Practices#

1. Use Constants for Node IDs#

typescript
// Define workflow-specific node IDs
const MY_WORKFLOW_NODES = {
  PROMPT: '6',
  NEGATIVE: '7',
  SAMPLER: '3',
  LATENT: '5',
} as const;

2. Validate Before Building#

typescript
function validateOverrides(
  builder: WorkflowOverrideBuilder,
  requiredNodes: string[]
) {
  const overrides = builder.build();
  for (const nodeId of requiredNodes) {
    if (!overrides[nodeId]) {
      throw new Error(`Missing required override for node ${nodeId}`);
    }
  }
  return overrides;
}

3. Create Workflow-Specific Builders#

typescript
function createMandalaBuilder(prompt: string, options?: MandalaOptions) {
  const builder = createWorkflowBuilder();

  builder
    .applyTemplate('sacred-mandala', '6', '7', {
      style: options?.style || 'tibetan buddhist',
      colors: options?.colors || 'gold and blue',
    })
    .setSamplerParams('3', {
      steps: options?.quality === 'high' ? 50 : 30,
      cfg: 7.5,
      seed: options?.seed,
    })
    .setResolution('5', options?.resolution || 'square-1024');

  return builder;
}