image-gen

---

LIBRARY-FIRST PROTOCOL (MANDATORY)

Before writing ANY code, you MUST check:

Step 1: Library Catalog

• Location: .claude/library/catalog.json
• If match >70%: REUSE or ADAPT

Step 2: Patterns Guide

• Location: .claude/docs/inventories/LIBRARY-PATTERNS-GUIDE.md
• If pattern exists: FOLLOW documented approach

Step 3: Existing Projects

• Location: D:\Projects\*
• If found: EXTRACT and adapt

Decision Matrix

| Match | Action | |-------|--------| | Library >90% | REUSE directly | | Library 70-90% | ADAPT minimally | | Pattern exists | FOLLOW pattern | | In project | EXTRACT | | No match | BUILD (add to library after) |

---

Purpose

Generate images using the best available provider - local models (free, private) or cloud APIs (fast, paid). Fully modular architecture allows plugging in any image generation backend.

Providers

| Provider | Type | Cost | Requirements | Quality | |----------|------|------|--------------|---------| | SDXL Lightning | Local | Free | 8GB VRAM, ~7GB disk | Excellent | | OpenAI DALL-E 3 | API | ~$0.04/image | OPENAI_API_KEY | Excellent | | Replicate | API | ~$0.01/image | REPLICATE_API_TOKEN | Good | | Custom | Any | Varies | User-defined | Varies |

When to Use

Perfect For:

• Blog banners and social media images (LinkedIn: 1200x630)
• Documentation diagrams and illustrations
• UI mockups and wireframes
• Concept visualization
• Any image generation need

Provider Selection:

• Privacy required? -> Use local SDXL
• No GPU? -> Use OpenAI or Replicate API
• Batch generation? -> Use local (no API costs)
• Highest quality? -> DALL-E 3 or SDXL Lightning

Quick Start

1. Check Available Providers

python scripts/multi-model/image-gen/cli.py --list

2. Setup Local SDXL (Recommended)

# First-time setup (downloads ~7GB)
python scripts/multi-model/image-gen/cli.py --setup local

3. Generate Images

# Auto-selects best available provider
python scripts/multi-model/image-gen/cli.py "A sunset over mountains" output.png

# LinkedIn banner size
python scripts/multi-model/image-gen/cli.py "Tech concept" banner.png --width 1200 --height 630

# Specific provider
python scripts/multi-model/image-gen/cli.py "A cat" cat.png --provider openai

Integration with Visual Art Composition

For professional-quality images, combine with visual-art-composition:

Step 1: visual-art-composition (Structure the prompt)
    |
    +---> 13-dimension aesthetic framework
    +---> Cross-cultural synthesis
    +---> Productive tension resolution
    |
    v
Step 2: image-gen (Generate the image)
    |
    +---> Select best provider (local or API)
    +---> Generate high-quality image
    +---> Save to specified path

Example Pipeline

# 1. Get structured prompt from visual-art-composition
/visual-art-composition "tech dashboard for productivity app"

# 2. Generate with structured prompt
python scripts/multi-model/image-gen/cli.py \
  "Dashboard UI with linear perspective depth, composed blues and warm golds,
   focal hierarchy with clear primary metric, notan two-value contrast.
   Modern professional aesthetic, clean geometric forms." \
  docs/images/dashboard.png --width 1200 --height 630

Provider Setup

Local SDXL Lightning (Recommended)

Requirements:

• GPU with 8GB+ VRAM (or CPU with 16GB+ RAM, slower)
• ~7GB disk space on D: drive
• Python with diffusers, torch

Setup:

python scripts/multi-model/image-gen/cli.py --setup local

Environment Variables (optional):

export SDXL_MODEL_DIR="D:/AI-Models/sdxl-lightning"

OpenAI DALL-E 3

Requirements:

• OpenAI API key
• ~$0.04 per image

Setup:

export OPENAI_API_KEY="sk-..."
python scripts/multi-model/image-gen/cli.py --setup openai

Replicate

Requirements:

• Replicate API token
• ~$0.01 per image

Setup:

export REPLICATE_API_TOKEN="r8_..."
python scripts/multi-model/image-gen/cli.py --setup replicate

Adding Custom Providers

Create a new provider by implementing ImageGeneratorBase:

from base import ImageGeneratorBase, ImageProvider, ProviderRegistry

class MyCustomGenerator(ImageGeneratorBase):
    provider = ImageProvider.CUSTOM

    def is_available(self) -> bool:
        # Check if provider is configured
        return True

    def setup(self) -> bool:
        # Download models, verify API keys, etc.
        return True

    def generate(self, prompt, output_path, config=None):
        # Generate image
        # Return GeneratedImage
        pass

# Register
ProviderRegistry.register(ImageProvider.CUSTOM, MyCustomGenerator)

Python API

from scripts.multi_model.image_gen.base import ProviderRegistry, ImageConfig

# Get best available provider
provider = ProviderRegistry.get_best_available()

# Configure
config = ImageConfig(
    width=1200,
    height=630,
    num_inference_steps=4
)

# Generate
result = provider.generate(
    prompt="A beautiful sunset",
    output_path="output.png",
    config=config
)

print(f"Generated: {result.path} in {result.generation_time_seconds}s")

Batch Generation

prompts = [
    "Sunset over mountains",
    "City skyline at night",
    "Forest in autumn"
]

results = provider.generate_batch(
    prompts=prompts,
    output_dir="./images/",
    config=config
)

Best Practices

Prompt Engineering

1. Be specific about composition, colors, style
2. Include negative prompts for local models
3. Use visual-art-composition for professional quality
4. Specify aspect ratio in prompt when needed

Performance

1. Local models: First generation is slow (model loading), subsequent are fast
2. API models: Consistent speed, watch for rate limits
3. Batch generation: More efficient than individual calls

Quality

1. SDXL Lightning: 4 steps is optimal (more steps = minimal improvement)
2. DALL-E 3: No step control, always high quality
3. Always validate output matches intent

Related Skills

• visual-art-composition: 13-dimension aesthetic framework for structured prompts
• prompt-architect: General prompt optimization
• pptx-generation: Uses images for presentation slides

Troubleshooting

"No provider available"

• Run --list to see what's configured
• Run --setup local to download SDXL Lightning
• Or set API keys for cloud providers

Out of VRAM

• Use CPU mode (slower): Set SDXL_DEVICE=cpu
• Use API provider instead
• Reduce image size

Slow First Generation

• Normal for local models (loading ~7GB model)
• Subsequent generations are fast (~2-5 seconds)

Poor Quality

• Use more descriptive prompts
• Apply visual-art-composition framework
• Try different provider

Files

• CLI: scripts/multi-model/image-gen/cli.py
• Base classes: scripts/multi-model/image-gen/base.py
• Local SDXL: scripts/multi-model/image-gen/local_sdxl.py
• API providers: scripts/multi-model/image-gen/api_providers.py