# Civitai Integration Documentation

This directory contains comprehensive documentation for integrating Civitai AI
generation capabilities into the Oshun platform.

## Quick Links

| Document                                  | Description                                      |
| ----------------------------------------- | ------------------------------------------------ |
| [API Documentation](./api.md)             | Generation API, AIR URNs, image/video generation |
| [Model Management](./model-management.md) | Model discovery, downloads, versioning           |
| [Training Guide](./training.md)           | LoRA training for images and video               |
| [Best Practices](./best-practices.md)     | Optimization, cost management, production tips   |

## Overview

Civitai is a platform for sharing and using AI-generated content, models, and
training services. Oshun integrates with Civitai for:

- **Image Generation**: Text-to-image with SD1.5, SDXL, Flux, and Pony models
- **Video Generation**: 10 video models including Vidu, Veo3, Hunyuan, and Wan
- **Model Discovery**: Search and browse the Civitai model library
- **LoRA Training**: Train custom LoRAs for image and video generation
- **Model Management**: Download queue, caching, and hot-swap capabilities

### Key Features

- **AIR URN System**: Standardized model references across ecosystems
- **Multi-Model Support**: SD1.5, SDXL, Flux, Pony, video models
- **Quality Presets**: Fast, balanced, quality, highQuality configurations
- **Training Pipelines**: Character, style, object, and motion LoRAs
- **Production Ready**: Rate limiting, circuit breaker, caching, monitoring

## Architecture

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                        Oshun Civitai Integration                            │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  Application Layer                                                          │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  Lilith AI Service  │  Isis Factory    │    Yemaya Creative         │   │
│  │  - Avatar gen       │  - Batch gen     │    - Asset creation        │   │
│  │  - Character LoRAs  │  - Upscaling     │    - Style transfer        │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                      │                                      │
│  Provider Layer                      ▼                                      │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                     Civitai Provider                                 │   │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │   │
│  │  │ Generation   │  │ Training     │  │ Model        │              │   │
│  │  │ Provider     │  │ Provider     │  │ Discovery    │              │   │
│  │  └──────────────┘  └──────────────┘  └──────────────┘              │   │
│  │                                                                      │   │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │   │
│  │  │ Rate Limiter │  │ Circuit      │  │ Request      │              │   │
│  │  │              │  │ Breaker      │  │ Cache        │              │   │
│  │  └──────────────┘  └──────────────┘  └──────────────┘              │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                      │                                      │
│  API Layer                           ▼                                      │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  Civitai API                                                         │   │
│  │  - /v1/images/generate      - Image generation                       │   │
│  │  - /v1/videos/generate      - Video generation                       │   │
│  │  - /v1/models               - Model discovery                        │   │
│  │  - /v1/training             - LoRA training                          │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

## Getting Started

### Prerequisites

1. Civitai API key
2. Sufficient Buzz balance for generation/training
3. Node.js 18+ environment

### Quick Start

```typescript
import { createCivitaiProvider } from '@oshun/civitai-provider';

// Initialize provider
const provider = createCivitaiProvider(process.env.CIVITAI_API_KEY);

// Generate an image
const job = await provider.generateImage({
  model: 'urn:air:sdxl:checkpoint:civitai:133005@348913',
  params: {
    prompt: 'A majestic dragon flying over a castle at sunset',
    negativePrompt: 'blurry, low quality',
    width: 1024,
    height: 1024,
    steps: 25,
    cfgScale: 7,
  },
});

// Wait for result
const result = await provider.waitForJob(job.jobId);
console.log('Generated image:', result.result?.blobUrl);
```

### Using Quality Presets

```typescript
// Fast preview (12 steps)
const preview = await provider.generateImageWithPreset(
  'urn:air:sdxl:checkpoint:civitai:133005@348913',
  'A beautiful landscape',
  'fast'
);

// High quality (50 steps)
const final = await provider.generateImageWithPreset(
  'urn:air:sdxl:checkpoint:civitai:133005@348913',
  'A beautiful landscape',
  'highQuality'
);
```

## Supported Generation Types

| Type              | Description          | Typical Latency | Cost                 |
| ----------------- | -------------------- | --------------- | -------------------- |
| **Image (SD1.5)** | 512x512 generation   | 5-15s           | 2 Buzz               |
| **Image (SDXL)**  | 1024x1024 generation | 15-30s          | 5 Buzz               |
| **Image (Flux)**  | Highest quality      | 20-45s          | 8 Buzz               |
| **Video**         | 2-10 second clips    | 30-120s         | 8-25 Buzz/s          |
| **Training**      | LoRA fine-tuning     | 30min-2hr       | 50-350 Buzz/1k steps |

## Supported Models

### Image Generation

| Ecosystem | Example Models                | VRAM | Resolution |
| --------- | ----------------------------- | ---- | ---------- |
| SD 1.5    | Realistic Vision, DreamShaper | 4GB  | 512x512    |
| SDXL      | Juggernaut XL, RealVisXL      | 8GB  | 1024x1024  |
| Flux      | Flux.1 Dev                    | 24GB | Variable   |
| Pony      | Pony Diffusion V6             | 8GB  | 1024x1024  |

### Video Generation

| Model       | Max Duration | LoRA Support | Image-to-Video |
| ----------- | ------------ | ------------ | -------------- |
| Vidu Q1     | 8s           | No           | Yes            |
| Veo3        | 10s          | No           | Yes            |
| Hunyuan     | 8s           | Yes          | Yes            |
| Wan 2.1/2.2 | 8s           | Yes          | Yes            |
| Mochi       | 5s           | No           | No             |

## Cost Reference

### Image Generation

| Ecosystem  | Base Cost | With 2 LoRAs |
| ---------- | --------- | ------------ |
| SD 1.5     | 2 Buzz    | ~3 Buzz      |
| SDXL       | 5 Buzz    | ~6 Buzz      |
| SDXL Draft | 3 Buzz    | ~4 Buzz      |
| Flux       | 8 Buzz    | ~9 Buzz      |

### Video Generation (per second)

| Model      | Draft | Standard | Professional |
| ---------- | ----- | -------- | ------------ |
| LTXV/Mochi | 4     | 8        | 12           |
| Wan 2.1    | 5     | 10       | 15           |
| Hunyuan    | 5     | 10       | 15           |
| Veo3       | 12.5  | 25       | 37.5         |

### Training (per 1000 steps)

| Base Model | Cost         |
| ---------- | ------------ |
| SD 1.5/2.1 | 50 Buzz      |
| SDXL       | 100 Buzz     |
| Flux       | 150-200 Buzz |
| Video      | 300-350 Buzz |

## Provider Comparison

### When to Use Civitai

**Best for:**

- Access to large model library
- LoRA training capabilities
- Community models and styles
- Video generation with LoRAs

**Consider alternatives for:**

- Lowest latency requirements (use RunComfy/RunPod)
- Self-hosted requirements (use ComfyUI directly)
- Enterprise SLA requirements

## Resilience Features

### Rate Limiting

- Sliding window algorithm (60 requests/minute)
- Automatic retry with exponential backoff
- Pre-request rate limit checking

### Circuit Breaker

- Opens after 5 failures in 60 seconds
- Half-open state after 30 second timeout
- Closes after 3 consecutive successes

### Caching

- In-memory LRU cache
- 5 minute default TTL
- ETag support for conditional requests

## Monitoring

### Key Metrics

- **Success Rate**: Target >99%
- **Average Latency**: Target <30s for images
- **Cache Hit Rate**: Target >50%
- **Buzz Efficiency**: Track cost per successful generation

### Health Checks

```typescript
const health = await checkHealth();

console.log('Healthy:', health.healthy);
console.log('Rate limit remaining:', health.checks.rateLimit.remaining);
console.log('Circuit state:', health.checks.circuitBreaker.state);
console.log('Cache hit rate:', health.checks.cache.hitRate);
```

## Best Practices Summary

1. **Use quality presets** for consistent results
2. **Cache model metadata** to reduce API calls
3. **Monitor Buzz spending** with daily budgets
4. **Start with fast presets** for iteration
5. **Track seeds** for reproducibility
6. **Validate datasets** before training
7. **Use appropriate models** for the task

## Error Handling

```typescript
try {
  const result = await provider.generateImageAndWait(request);
} catch (error) {
  if (error.code === 'RATE_LIMITED') {
    // Retry after delay
  } else if (error.code === 'INSUFFICIENT_BUZZ') {
    // Top up account
  } else if (error.code === 'MODEL_NOT_FOUND') {
    // Use fallback model
  }
}
```

## Support

- Internal: #ai-generation Slack channel
- Civitai: [Discord](https://discord.gg/civitai)
- API Issues: support@civitai.com

## Related Documentation

- [ComfyUI Integration](../comfyui/) - Node-based workflow generation
- [ElevenLabs Integration](../elevenlabs/) - Voice synthesis
- [Model Registry](../../../libs/isis/ai-providers/src/providers/model-registry/) -
  Unified model management