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;
}