# Pipeline Configuration Guide

Learn how to configure and customize Yemaya pipelines for your specific needs.

## Table of Contents

1. [Pipeline Overview](#pipeline-overview)
2. [Configuration Options](#configuration-options)
3. [Game Pipeline Configuration](#game-pipeline-configuration)
4. [Film Pipeline Configuration](#film-pipeline-configuration)
5. [Custom Pipelines](#custom-pipelines)
6. [Phase Configuration](#phase-configuration)
7. [Resource Allocation](#resource-allocation)
8. [Retry Policies](#retry-policies)
9. [Checkpoint Configuration](#checkpoint-configuration)
10. [Examples](#examples)

---

## Pipeline Overview

Yemaya supports two main pipeline types:

| Pipeline          | Phases   | Use Case                |
| ----------------- | -------- | ----------------------- |
| **Game Pipeline** | 8 phases | Creating playable games |
| **Film Pipeline** | 5 phases | Creating animated films |

Each pipeline can be configured at multiple levels:

- **Global**: Affects entire pipeline
- **Phase**: Affects specific phases
- **Task**: Affects individual tasks within phases

---

## Configuration Options

### Basic Configuration

```typescript
const config: PipelineConfig = {
  // Pipeline identity
  name: 'My Game Project',
  type: 'game',

  // Quality settings
  quality: 'high', // 'draft' | 'standard' | 'high' | 'ultra'

  // Timeline
  priority: 'normal', // 'low' | 'normal' | 'high' | 'urgent'
  deadline: '2024-12-31',

  // Autonomy
  autonomyLevel: 'guided', // 'full' | 'guided' | 'collaborative'

  // Resource limits
  budget: {
    maxUSD: 1000,
    alertThreshold: 0.8,
  },

  // Output
  outputs: {
    platforms: ['pc', 'web'],
    formats: ['godot', 'unity'],
  },
};
```

### Advanced Configuration

```typescript
const advancedConfig: PipelineConfig = {
  // ...basic config

  // Phase overrides
  phases: {
    concept: {
      enabled: true,
      timeout: 3600000, // 1 hour max
      retries: 3,
    },
    prototype: {
      enabled: false, // Skip prototype phase
      skipReason: 'Using existing prototype',
    },
    assetProduction: {
      parallelism: 10, // Parallel asset generation
      qualityThreshold: 0.9,
    },
  },

  // Agent configuration
  agents: {
    model: 'claude-3-opus',
    temperature: 0.7,
    maxIterations: 5,
  },

  // Quality gates
  qualityGates: {
    enabled: true,
    strictMode: false,
    autoRemediation: true,
  },

  // Checkpoints
  checkpoints: {
    enabled: true,
    frequency: 'phase', // 'phase' | 'hourly' | 'task'
    retention: 7, // days
  },

  // Notifications
  notifications: {
    email: ['team@example.com'],
    slack: 'https://hooks.slack.com/...',
    onEvents: ['phaseComplete', 'qualityGateFailed', 'completed'],
  },
};
```

---

## Game Pipeline Configuration

### Phase Structure

```
Phase 1: Concept Generation
    ↓
Phase 2: GDD Generation
    ↓
Phase 3: Prototype
    ↓
Phase 4: Asset Production
    ↓
Phase 5: Level Assembly
    ↓
Phase 6: Polish & Optimization
    ↓
Phase 7: QA & Testing
    ↓
Phase 8: Release
```

### Full Game Configuration

```typescript
const gameConfig: GamePipelineConfig = {
  type: 'game',

  // Target game settings
  game: {
    genre: 'platformer',
    perspective: '2d-side',
    artStyle: 'pixel-art',
    targetPlaytime: '8-10 hours',
    targetAudience: 'casual',
    ageRating: 'E',
  },

  // Platform targets
  platforms: {
    primary: 'pc',
    secondary: ['switch', 'mobile'],
    engine: 'godot',
  },

  // Scope limits
  scope: {
    levels: 20,
    uniqueCharacters: 10,
    uniqueEnemies: 15,
    uniqueItems: 50,
    cutsceneMinutes: 30,
  },

  // Phase-specific settings
  phases: {
    concept: {
      moodBoardCount: 5,
      referenceGamesCount: 3,
      generatePitchDeck: true,
    },

    gdd: {
      detailLevel: 'comprehensive',
      includeBalanceSpreadsheets: true,
      includeEconomyModel: true,
    },

    prototype: {
      coreMechanicsOnly: true,
      levelCount: 3,
      generatePlaytestReport: true,
    },

    assetProduction: {
      lodLevels: 3,
      textureResolution: 2048,
      animationQuality: 'high',
      musicTracks: 10,
      sfxCount: 200,
    },

    levelAssembly: {
      lightingQuality: 'baked',
      collisionDetail: 'precise',
      interactiveObjects: true,
    },

    polish: {
      juiciness: 'high',
      particleEffects: true,
      screenShake: true,
      accessibility: ['subtitles', 'colorblind', 'remapping'],
    },

    qa: {
      automatedTestHours: 100,
      aiPlaytestProfiles: 5,
      performanceTargetFps: 60,
      coverageThreshold: 0.85,
    },

    release: {
      stores: ['steam', 'itch', 'epic'],
      marketingAssets: true,
      pressKit: true,
      trailerLength: 90, // seconds
    },
  },
};
```

---

## Film Pipeline Configuration

### Phase Structure

```
Phase 1: Development
    ↓
Phase 2: Pre-Production
    ↓
Phase 3: Animation Production
    ↓
Phase 4: Post-Production
    ↓
Phase 5: Delivery
```

### Full Film Configuration

```typescript
const filmConfig: FilmPipelineConfig = {
  type: 'film',

  // Film specifications
  film: {
    format: 'short', // 'short' | 'feature'
    genre: 'drama',
    targetRuntime: 15, // minutes
    aspectRatio: '2.39:1',
    resolution: '4K',
    frameRate: 24,
  },

  // Style settings
  style: {
    animation: '3d-realistic',
    rendering: 'path-traced',
    colorSpace: 'ACES',
    hdr: true,
  },

  // Audio settings
  audio: {
    dialogue: 'ai-generated',
    music: 'orchestral',
    mixFormat: '5.1',
  },

  // Delivery targets
  delivery: {
    formats: ['DCP', 'ProRes', 'H265'],
    localization: ['en', 'es', 'fr', 'de', 'ja'],
    subtitles: true,
    dubbing: false,
  },

  // Phase-specific settings
  phases: {
    development: {
      treatmentLength: 'detailed',
      generateLookbook: true,
      characterDesigns: true,
      locationConcepts: true,
    },

    preProduction: {
      storyboardStyle: 'detailed',
      animaticWithScratch: true,
      shotListDetail: 'full',
      previsQuality: 'high',
    },

    production: {
      renderEngine: 'blender-cycles',
      samplesPerPixel: 4096,
      denoising: 'optix',
      motionBlur: true,
      dofSimulation: true,
      subsurfaceScattering: true,
    },

    postProduction: {
      colorGrade: 'cinematic',
      vfxComplexity: 'moderate',
      soundDesign: 'detailed',
      musicScoring: 'custom',
    },

    delivery: {
      dcpEncryption: true,
      streamingVariants: ['4k', '1080p', '720p'],
      accessibilityFeatures: ['SDH', 'AD'],
    },
  },
};
```

---

## Custom Pipelines

### Creating a Custom Pipeline

```typescript
const customPipeline: CustomPipelineConfig = {
  name: 'Music Video Pipeline',

  // Define custom phases
  phases: [
    {
      name: 'concept',
      type: 'standard',
      tasks: ['mood-board', 'style-reference', 'narrative-outline'],
    },
    {
      name: 'storyboard',
      type: 'standard',
      tasks: ['shot-planning', 'timing-sync', 'transition-design'],
    },
    {
      name: 'asset-creation',
      type: 'parallel',
      tasks: ['environment', 'characters', 'props', 'vfx-elements'],
      maxParallelism: 8,
    },
    {
      name: 'animation',
      type: 'sequential',
      tasks: ['layout', 'blocking', 'final-animation', 'lighting'],
    },
    {
      name: 'compositing',
      type: 'standard',
      tasks: ['render', 'composite', 'color-grade', 'effects'],
    },
    {
      name: 'audio-sync',
      type: 'standard',
      tasks: ['music-sync', 'sound-design', 'final-mix'],
    },
    {
      name: 'delivery',
      type: 'standard',
      tasks: ['master', 'encode', 'distribute'],
    },
  ],

  // Phase dependencies
  dependencies: {
    storyboard: ['concept'],
    'asset-creation': ['storyboard'],
    animation: ['asset-creation'],
    compositing: ['animation'],
    'audio-sync': ['compositing'],
    delivery: ['audio-sync'],
  },

  // Quality gates between phases
  qualityGates: {
    afterConcept: ['visual-quality', 'narrative-quality'],
    afterAnimation: ['technical-quality', 'visual-quality'],
    afterCompositing: ['visual-quality', 'audio-quality'],
  },
};
```

### Extending Existing Pipelines

```typescript
const extendedPipeline = await client.pipelines.extend('game', {
  // Add custom phases
  insertPhase: {
    after: 'gdd',
    phase: {
      name: 'market-research',
      tasks: ['competitor-analysis', 'audience-survey', 'pricing-strategy'],
    },
  },

  // Modify existing phases
  modifyPhase: {
    name: 'assetProduction',
    addTasks: ['custom-shader-creation', 'mocap-processing'],
  },

  // Remove phases
  removePhases: ['prototype'], // Skip prototype
});
```

---

## Phase Configuration

### Standard Phase Options

```typescript
const phaseConfig: PhaseConfig = {
  name: 'asset-production',

  // Execution settings
  enabled: true,
  timeout: 86400000, // 24 hours
  priority: 'high',

  // Retry configuration
  retries: {
    maxAttempts: 3,
    backoffStrategy: 'exponential',
    initialDelayMs: 5000,
  },

  // Resource allocation
  resources: {
    cpu: 4,
    memoryGB: 16,
    gpuCount: 2,
    storageGB: 100,
  },

  // Quality requirements
  qualityGate: {
    enabled: true,
    threshold: 0.85,
    requiredChecks: ['visual', 'technical'],
  },

  // Checkpoint behavior
  checkpoint: {
    createOnStart: true,
    createOnComplete: true,
    preserveArtifacts: true,
  },

  // Notifications
  notifications: {
    onStart: true,
    onComplete: true,
    onFailure: true,
  },
};
```

### Parallel Phase Configuration

```typescript
const parallelPhaseConfig: ParallelPhaseConfig = {
  name: 'asset-production',
  type: 'parallel',

  // Parallelism settings
  maxParallelism: 20,
  batchSize: 5,

  // Task prioritization
  taskPriority: {
    'character-models': 1,
    environment: 2,
    props: 3,
    vfx: 4,
  },

  // Failure handling
  failureMode: 'continue', // 'stop' | 'continue' | 'retry'
  failureThreshold: 0.1, // Max 10% failures allowed
};
```

---

## Resource Allocation

### Static Allocation

```typescript
const resourceConfig: ResourceConfig = {
  // Fixed resource pool
  static: {
    api: {
      instances: 2,
      cpuPerInstance: 2,
      memoryPerInstance: 4,
    },
    workers: {
      instances: 5,
      cpuPerInstance: 4,
      memoryPerInstance: 8,
      gpuPerInstance: 1,
    },
    rendering: {
      instances: 3,
      cpuPerInstance: 8,
      memoryPerInstance: 32,
      gpuPerInstance: 2,
    },
  },
};
```

### Dynamic Allocation

```typescript
const dynamicResourceConfig: ResourceConfig = {
  // Auto-scaling rules
  dynamic: {
    enabled: true,

    scaleUp: {
      queueDepthThreshold: 100,
      cpuThreshold: 0.8,
      scaleIncrement: 2,
      maxInstances: 20,
    },

    scaleDown: {
      idleMinutes: 10,
      minInstances: 2,
    },

    // Cost controls
    budget: {
      maxHourlyCost: 50,
      preferSpotInstances: true,
      spotBidPercent: 0.6,
    },
  },
};
```

### Priority-Based Allocation

```typescript
const priorityConfig: PriorityResourceConfig = {
  // Priority queues
  queues: {
    urgent: {
      weight: 10,
      maxWaitTime: 60, // seconds
    },
    high: {
      weight: 5,
      maxWaitTime: 300,
    },
    normal: {
      weight: 2,
      maxWaitTime: 1800,
    },
    low: {
      weight: 1,
      maxWaitTime: null, // no limit
    },
  },
};
```

---

## Retry Policies

### Linear Backoff

```typescript
const linearRetry: RetryPolicy = {
  strategy: 'linear',
  maxAttempts: 5,
  initialDelayMs: 1000,
  delayIncrementMs: 1000,
  // Delays: 1s, 2s, 3s, 4s, 5s
};
```

### Exponential Backoff

```typescript
const exponentialRetry: RetryPolicy = {
  strategy: 'exponential',
  maxAttempts: 5,
  initialDelayMs: 1000,
  multiplier: 2,
  maxDelayMs: 60000,
  // Delays: 1s, 2s, 4s, 8s, 16s
};
```

### Custom Retry Logic

```typescript
const customRetry: RetryPolicy = {
  strategy: 'custom',
  maxAttempts: 5,

  // Custom delay function
  delayFn: (attempt, error) => {
    if (error.code === 'RATE_LIMITED') {
      return error.retryAfter * 1000;
    }
    return Math.min(1000 * Math.pow(2, attempt), 60000);
  },

  // Retry condition
  shouldRetry: (error, attempt) => {
    // Don't retry validation errors
    if (error.code === 'VALIDATION_ERROR') return false;
    // Don't retry after 5 attempts
    if (attempt >= 5) return false;
    // Retry everything else
    return true;
  },
};
```

---

## Checkpoint Configuration

### Checkpoint Settings

```typescript
const checkpointConfig: CheckpointConfig = {
  enabled: true,

  // When to create checkpoints
  triggers: {
    onPhaseStart: true,
    onPhaseComplete: true,
    onQualityGatePass: true,
    interval: 3600000, // Every hour
  },

  // What to save
  contents: {
    pipelineState: true,
    generatedAssets: true,
    intermediateResults: true,
    agentContext: true,
  },

  // Storage settings
  storage: {
    location: 's3', // 's3' | 'local' | 'database'
    bucket: 'yemaya-checkpoints',
    compression: 'gzip',
    encryption: 'AES-256',
  },

  // Retention
  retention: {
    keepLatest: 5,
    keepDays: 30,
    keepMilestones: true,
  },

  // Recovery behavior
  recovery: {
    autoRecoveryEnabled: true,
    maxRecoveryAttempts: 3,
    notifyOnRecovery: true,
  },
};
```

### Manual Checkpoint Operations

```typescript
// Create manual checkpoint
await client.pipelines.createCheckpoint(projectId, {
  name: 'pre-risky-operation',
  description: 'Before attempting experimental feature',
});

// List checkpoints
const checkpoints = await client.pipelines.listCheckpoints(projectId);

// Restore from checkpoint
await client.pipelines.restoreCheckpoint(projectId, {
  checkpointId: 'cp_abc123',
  preserveChanges: false,
});

// Compare checkpoints
const diff = await client.pipelines.compareCheckpoints(projectId, {
  from: 'cp_abc123',
  to: 'cp_def456',
});
```

---

## Examples

### Example 1: Quick Prototype Pipeline

```typescript
const prototypeConfig: PipelineConfig = {
  name: 'Quick Prototype',
  type: 'game',
  quality: 'draft',
  priority: 'urgent',

  phases: {
    concept: { timeout: 1800000 }, // 30 min
    gdd: { enabled: true },
    prototype: {
      enabled: true,
      scope: { levels: 1, coreMechanicsOnly: true },
    },
    assetProduction: { enabled: false },
    levelAssembly: { enabled: false },
    polish: { enabled: false },
    qa: { enabled: false },
    release: { enabled: false },
  },

  outputs: {
    formats: ['web-playable'],
  },
};
```

### Example 2: High-Quality Release Pipeline

```typescript
const releaseConfig: PipelineConfig = {
  name: 'Release Build',
  type: 'game',
  quality: 'ultra',
  priority: 'normal',

  qualityGates: {
    enabled: true,
    strictMode: true,
    allMustPass: true,
  },

  phases: {
    qa: {
      automatedTestHours: 500,
      performanceTargetFps: 60,
      coverageThreshold: 0.95,
      accessibilityCompliance: 'WCAG-AA',
    },
    release: {
      stores: ['steam', 'epic', 'gog'],
      marketingAssets: true,
      pressKit: true,
      localizations: ['en', 'es', 'fr', 'de', 'ja', 'zh'],
    },
  },

  notifications: {
    onComplete: ['team@example.com', 'marketing@example.com'],
    onFailure: ['dev-leads@example.com'],
  },
};
```

### Example 3: Incremental Build Pipeline

```typescript
const incrementalConfig: PipelineConfig = {
  name: 'Incremental Update',
  type: 'game',

  // Start from existing project
  baseProject: 'proj_existing_abc123',

  // Only run specific phases
  phases: {
    concept: { enabled: false },
    gdd: { enabled: false },
    prototype: { enabled: false },
    assetProduction: {
      enabled: true,
      incrementalOnly: true,
      changedAssets: ['character_hero', 'level_5', 'ui_menu'],
    },
    levelAssembly: {
      enabled: true,
      affectedLevelsOnly: true,
    },
    polish: { enabled: true },
    qa: {
      enabled: true,
      regressionTestsOnly: true,
    },
    release: {
      enabled: true,
      patchBuild: true,
    },
  },
};
```

---

## Next Steps

- [Constraint Specification Tutorial](./constraint-specification.md)
- [Quality Gate Configuration](./quality-gates.md)
- [Output Customization Guide](./output-customization.md)
- [Autonomous Mode Tutorial](./autonomous-mode.md)
