# Autonomous Mode Tutorial

Learn how to use Yemaya's autonomous pipelines to create complete games and
films with minimal manual intervention.

## Table of Contents

1. [What is Autonomous Mode?](#what-is-autonomous-mode)
2. [Getting Started](#getting-started)
3. [Creating Your First Autonomous Game](#creating-your-first-autonomous-game)
4. [Creating Your First Autonomous Film](#creating-your-first-autonomous-film)
5. [Monitoring Progress](#monitoring-progress)
6. [Human-in-the-Loop Interventions](#human-in-the-loop-interventions)
7. [Quality Gates](#quality-gates)
8. [Customization Options](#customization-options)
9. [Best Practices](#best-practices)

---

## What is Autonomous Mode?

Autonomous mode allows Yemaya's AI agents to handle the complete creative
pipeline from concept to delivery with minimal human intervention. The system:

- **Plans** the entire project based on your initial prompt
- **Generates** all required assets (3D models, textures, audio, animations)
- **Assembles** content into playable games or watchable films
- **Tests** and validates quality at each stage
- **Delivers** finished products in your desired formats

### How It Works

```
Your Prompt → Concept Generation → Design Documents → Asset Production
     ↓              ↓                   ↓                ↓
  "A cozy        Game Concept        GDD/Script      3D Models
   farming       Art Direction       Level Design    Animations
   game..."      Target Audience     Mechanics       Audio/Music
                                                         ↓
← Quality Gates at Each Phase →                          ↓
                                                         ↓
            Final Product ← Polish & QA ← Level Assembly ←
```

### Autonomy Levels

| Level               | Description                 | Human Input          |
| ------------------- | --------------------------- | -------------------- |
| **Full Autonomous** | AI handles everything       | Initial prompt only  |
| **Guided**          | AI proposes, human approves | Approve each phase   |
| **Collaborative**   | AI assists, human directs   | Active participation |

---

## Getting Started

### Prerequisites

1. A Yemaya account with appropriate credits
2. API key or authenticated session
3. Understanding of your project goals

### Quick Start with SDK

```typescript
import { YemayaClient } from '@yemaya/sdk';

const client = new YemayaClient({
  apiKey: 'your-api-key',
});

// Create an autonomous game project
const project = await client.autonomous.createProject({
  type: 'game',
  prompt:
    'A cozy farming simulation game with anime-style graphics, crop growing, and village relationships',
  autonomyLevel: 'full',
  quality: 'high',
});

console.log(`Project created: ${project.id}`);
console.log(`Estimated completion: ${project.estimatedCompletion}`);
```

### Quick Start with REST API

```bash
curl -X POST https://api.yemaya.io/v1/autonomous/projects \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "game",
    "prompt": "A cozy farming simulation game with anime-style graphics",
    "autonomyLevel": "full",
    "quality": "high"
  }'
```

---

## Creating Your First Autonomous Game

### Step 1: Define Your Vision

The more detail you provide, the better the results:

```typescript
const project = await client.autonomous.createProject({
  type: 'game',
  prompt: `
    Create a 2D platformer game with the following:
    - Setting: Enchanted forest with magical creatures
    - Art style: Hand-painted watercolor aesthetic
    - Core mechanics: Running, jumping, wall-sliding, dash ability
    - Progression: 20 levels across 4 worlds
    - Story: A young fox searching for their missing family
    - Target audience: Ages 8-14
    - Platform: PC and Nintendo Switch
    - Estimated playtime: 6-8 hours
  `,
  autonomyLevel: 'full',
  quality: 'high',
  targetPlatforms: ['pc', 'switch'],
  gameEngine: 'godot',
});
```

### Step 2: Review Generated Concept

The system first generates a concept for your approval:

```typescript
// Wait for concept phase to complete
const concept = await client.autonomous.waitForPhase(project.id, 'concept');

console.log('Game Concept:', concept.gameConcept);
console.log('Art Direction:', concept.artDirection);
console.log('Target Audience:', concept.targetAudience);
console.log('Estimated Budget:', concept.budgetEstimate);

// View mood boards and reference images
for (const ref of concept.references) {
  console.log(`Reference: ${ref.title} - ${ref.url}`);
}
```

### Step 3: Approve or Modify

```typescript
// Option A: Approve and continue
await client.autonomous.approvePhase(project.id, 'concept');

// Option B: Request modifications
await client.autonomous.requestChanges(project.id, 'concept', {
  changes: [
    'Make the art style more vibrant',
    'Add a companion character (owl)',
    'Reduce to 15 levels for scope',
  ],
});

// Option C: Override specific elements
await client.autonomous.overridePhase(project.id, 'concept', {
  overrides: {
    'artDirection.colorPalette': ['warm', 'autumn', 'golden'],
    'scope.levelCount': 15,
  },
});
```

### Step 4: Monitor Production

```typescript
// Subscribe to real-time updates
const subscription = client.autonomous.subscribe(project.id);

subscription.on('phaseStarted', (phase) => {
  console.log(`Starting phase: ${phase.name}`);
});

subscription.on('assetGenerated', (asset) => {
  console.log(`Generated: ${asset.name} (${asset.type})`);
});

subscription.on('qualityGateResult', (result) => {
  console.log(`Quality Gate: ${result.gate} - ${result.status}`);
  if (result.issues.length > 0) {
    console.log('Issues:', result.issues);
  }
});

subscription.on('phaseCompleted', (phase) => {
  console.log(`Completed: ${phase.name} in ${phase.duration}ms`);
});
```

### Step 5: Download Finished Game

```typescript
// Wait for completion
const result = await client.autonomous.waitForCompletion(project.id);

// Download builds
const builds = await client.autonomous.getBuilds(project.id);

for (const build of builds) {
  console.log(`Platform: ${build.platform}`);
  console.log(`Download: ${build.downloadUrl}`);
  console.log(`Size: ${build.size}`);
}

// Download source project (for Godot)
const source = await client.autonomous.getSource(project.id);
console.log(`Godot Project: ${source.downloadUrl}`);
```

---

## Creating Your First Autonomous Film

### Step 1: Define Your Film

```typescript
const project = await client.autonomous.createProject({
  type: 'film',
  prompt: `
    Create a 10-minute animated short film:
    - Genre: Sci-fi drama
    - Setting: Space station orbiting a dying star
    - Style: Realistic 3D animation (Pixar-quality)
    - Story: An astronaut must choose between saving the mission data
            or returning to save their partner on the station
    - Mood: Tense, emotional, with hopeful ending
    - Target audience: Adults (PG-13)
    - Music: Orchestral score
    - Voice: AI-generated dialogue
  `,
  autonomyLevel: 'guided', // Human approval at key stages
  quality: 'ultra',
  deliveryFormat: 'DCP', // Digital Cinema Package
});
```

### Step 2: Development Phase

```typescript
// Wait for development deliverables
const development = await client.autonomous.waitForPhase(
  project.id,
  'development'
);

// Review treatment
console.log('Logline:', development.treatment.logline);
console.log('Synopsis:', development.treatment.synopsis);
console.log('Themes:', development.treatment.themes);

// Review pitch deck
console.log('Pitch Deck URL:', development.pitchDeck.url);

// Review character designs
for (const character of development.characters) {
  console.log(`${character.name}: ${character.description}`);
  console.log(`Design: ${character.conceptArtUrl}`);
}
```

### Step 3: Pre-Production

```typescript
// Approve development to proceed
await client.autonomous.approvePhase(project.id, 'development');

// Wait for pre-production
const preProd = await client.autonomous.waitForPhase(
  project.id,
  'pre-production'
);

// Review screenplay
console.log('Screenplay:', preProd.screenplay.url);
console.log('Page Count:', preProd.screenplay.pageCount);
console.log('Estimated Runtime:', preProd.screenplay.estimatedRuntime);

// Review storyboards
console.log('Storyboard:', preProd.storyboard.url);
console.log('Shots:', preProd.storyboard.shotCount);

// Review animatic
console.log('Animatic Video:', preProd.animatic.url);
```

### Step 4: Production

```typescript
// Approve pre-production
await client.autonomous.approvePhase(project.id, 'pre-production');

// Production happens automatically
// Subscribe to see render progress
subscription.on('renderProgress', (progress) => {
  console.log(`Rendering: ${progress.shot} - ${progress.percent}%`);
  console.log(`Frames: ${progress.framesComplete}/${progress.totalFrames}`);
});

subscription.on('shotComplete', (shot) => {
  console.log(`Shot complete: ${shot.name}`);
  console.log(`Preview: ${shot.previewUrl}`);
});
```

### Step 5: Post-Production and Delivery

```typescript
// Wait for post-production
const postProd = await client.autonomous.waitForPhase(
  project.id,
  'post-production'
);

// Review rough cut
console.log('Rough Cut:', postProd.roughCut.url);

// Request changes if needed
await client.autonomous.requestChanges(project.id, 'post-production', {
  changes: [
    'Extend the emotional beat at 4:32',
    'Add more ambient sound in space scenes',
    'Brighten the ending shots',
  ],
});

// Final delivery
const delivery = await client.autonomous.waitForCompletion(project.id);

console.log('DCP Package:', delivery.dcp.url);
console.log('Streaming Version:', delivery.streaming.url);
console.log('HDR Master:', delivery.hdr.url);
```

---

## Monitoring Progress

### Dashboard Overview

Access the web dashboard for visual progress tracking:

```
https://app.yemaya.io/projects/{projectId}/autonomous
```

### Programmatic Monitoring

```typescript
// Get current status
const status = await client.autonomous.getStatus(project.id);

console.log('Current Phase:', status.currentPhase);
console.log('Overall Progress:', status.overallProgress + '%');
console.log('Estimated Completion:', status.estimatedCompletion);
console.log('Active Agents:', status.activeAgents);
console.log('Resources Used:', status.resourceUsage);

// Get phase breakdown
for (const phase of status.phases) {
  console.log(`${phase.name}: ${phase.status} (${phase.progress}%)`);
}
```

### Timeline View

```typescript
// Get project timeline
const timeline = await client.autonomous.getTimeline(project.id);

for (const event of timeline.events) {
  console.log(`[${event.timestamp}] ${event.type}: ${event.description}`);
}
```

### Cost Tracking

```typescript
// Get cost breakdown
const costs = await client.autonomous.getCosts(project.id);

console.log('Total Cost:', costs.total);
console.log('Breakdown:');
console.log('  - AI Generation:', costs.aiGeneration);
console.log('  - 3D Processing:', costs.threeD);
console.log('  - Rendering:', costs.rendering);
console.log('  - Storage:', costs.storage);
```

---

## Human-in-the-Loop Interventions

### When to Intervene

The system will pause and request human input for:

1. **Quality Gate Failures** - Critical issues that need review
2. **Creative Decisions** - Ambiguous choices requiring direction
3. **Budget Thresholds** - Before exceeding estimated costs
4. **Explicit Checkpoints** - Phases marked for human approval

### Handling Intervention Requests

```typescript
// Subscribe to intervention requests
subscription.on('interventionRequired', async (intervention) => {
  console.log('Intervention needed:', intervention.type);
  console.log('Reason:', intervention.reason);
  console.log('Options:', intervention.options);

  // Option 1: Choose from provided options
  await client.autonomous.resolveIntervention(intervention.id, {
    selectedOption: intervention.options[0].id,
  });

  // Option 2: Provide custom direction
  await client.autonomous.resolveIntervention(intervention.id, {
    customDirection: 'Make the character more heroic looking',
  });

  // Option 3: Skip (use AI's best judgment)
  await client.autonomous.resolveIntervention(intervention.id, {
    action: 'skip',
  });

  // Option 4: Cancel and rollback
  await client.autonomous.resolveIntervention(intervention.id, {
    action: 'rollback',
  });
});
```

### Manual Overrides

```typescript
// Override any generated asset
await client.autonomous.overrideAsset(project.id, {
  assetId: 'ast_hero_character',
  replacementUrl: 'https://my-storage.com/custom-hero.fbx',
  reason: 'Using pre-existing character design',
});

// Skip a phase entirely
await client.autonomous.skipPhase(project.id, 'prototype', {
  reason: 'Already have validated prototype',
});

// Inject custom content
await client.autonomous.injectContent(project.id, {
  phase: 'asset-production',
  content: {
    type: 'character',
    file: fs.readFileSync('my-character.fbx'),
    name: 'Custom NPC',
  },
});
```

---

## Quality Gates

### Understanding Quality Gates

Each phase passes through quality gates that validate:

| Gate          | Validates                                       |
| ------------- | ----------------------------------------------- |
| **Narrative** | Script quality, dialogue, character consistency |
| **Visual**    | Art style consistency, technical specs          |
| **Audio**     | Sound levels, sync, frequency response          |
| **Technical** | Performance, stability, compatibility           |
| **Gameplay**  | Balance, difficulty, fun factor                 |

### Configuring Quality Thresholds

```typescript
const project = await client.autonomous.createProject({
  // ...
  qualityConfig: {
    gates: {
      narrative: {
        enabled: true,
        threshold: 0.85, // 85% quality score required
        strictMode: false, // Allow warnings to pass
      },
      visual: {
        enabled: true,
        threshold: 0.9,
        strictMode: true, // Fail on any warning
      },
      technical: {
        enabled: true,
        threshold: 0.95,
        fpsMinimum: 60,
        memoryMaxMB: 2048,
      },
      gameplay: {
        enabled: true,
        threshold: 0.8,
        playtestHours: 10, // Minimum AI playtest hours
      },
    },
    autoRemediationAttempts: 3, // Try to fix issues automatically
  },
});
```

### Handling Quality Gate Failures

```typescript
subscription.on('qualityGateFailed', async (failure) => {
  console.log(`Gate Failed: ${failure.gate}`);
  console.log(`Score: ${failure.score} (required: ${failure.threshold})`);

  for (const issue of failure.issues) {
    console.log(`- ${issue.severity}: ${issue.description}`);
    console.log(`  Suggestion: ${issue.suggestedFix}`);
  }

  // Option 1: Let AI attempt auto-remediation
  await client.autonomous.retryWithRemediation(failure.id);

  // Option 2: Override and continue (with reason)
  await client.autonomous.overrideQualityGate(failure.id, {
    reason: 'Acceptable for prototype stage',
    approvedBy: 'user@example.com',
  });

  // Option 3: Stop and review manually
  await client.autonomous.pauseProject(project.id);
});
```

---

## Customization Options

### Templates

Start from pre-built templates:

```typescript
// List available templates
const templates = await client.autonomous.listTemplates({
  type: 'game',
  genre: 'platformer',
});

// Create from template
const project = await client.autonomous.createFromTemplate({
  templateId: 'template_2d_platformer',
  customizations: {
    setting: 'underwater world',
    artStyle: 'pixel art',
    levelCount: 30,
  },
});
```

### Asset Libraries

Use existing assets:

```typescript
const project = await client.autonomous.createProject({
  // ...
  assetSources: {
    // Use assets from another project
    inheritFrom: ['proj_abc123'],

    // Use specific asset packs
    assetPacks: ['pack_fantasy_characters', 'pack_ambient_sounds'],

    // Custom asset URLs
    externalAssets: [{ type: 'character', url: 'https://...' }],
  },
});
```

### Agent Configuration

Customize AI agent behavior:

```typescript
const project = await client.autonomous.createProject({
  // ...
  agentConfig: {
    // Preferred AI models
    preferredModels: {
      narrative: 'claude-3-opus',
      visual: 'midjourney-v6',
      threeD: 'meshy-high',
    },

    // Agent personalities
    creativeDirector: {
      style: 'bold',
      riskTolerance: 'high',
    },

    // Collaboration settings
    conflictResolution: 'voting', // or 'consensus', 'priority'
    iterationLimit: 5,
  },
});
```

---

## Best Practices

### 1. Write Clear Prompts

```typescript
// ❌ Too vague
"Make a fun game"

// ✅ Clear and specific
"Create a 2D puzzle platformer with:
- Mechanics: gravity manipulation, portal guns
- Art: Minimalist geometric style, neon colors
- Length: 20 puzzles, 2-3 hours playtime
- Target: Casual puzzle enthusiasts
- Platforms: Steam, iOS, Android"
```

### 2. Set Realistic Quality Expectations

```typescript
// For prototypes
{ quality: 'draft', timeframe: 'fast' }

// For production
{ quality: 'high', timeframe: 'standard' }

// For showcase/demo
{ quality: 'ultra', timeframe: 'extended' }
```

### 3. Use Checkpoints Wisely

```typescript
const project = await client.autonomous.createProject({
  // ...
  checkpoints: {
    // Only require approval at key stages
    requireApproval: ['concept', 'gdd', 'final-qa'],

    // Auto-approve other phases
    autoApprove: ['asset-production', 'level-assembly'],
  },
});
```

### 4. Monitor Costs

```typescript
const project = await client.autonomous.createProject({
  // ...
  budgetConfig: {
    maxBudget: 500.0, // USD
    alertThreshold: 0.75, // Alert at 75%
    pauseOnExceed: true,
  },
});
```

### 5. Iterate in Phases

```typescript
// Phase 1: Quick prototype
const prototype = await client.autonomous.createProject({
  prompt: 'Your game idea',
  quality: 'draft',
  scope: { levels: 3, duration: '30min' },
});

// Review and refine
// ...

// Phase 2: Full production
const production = await client.autonomous.createProject({
  inheritFrom: prototype.id,
  quality: 'high',
  scope: { levels: 20, duration: '8h' },
});
```

### 6. Save and Reuse Configurations

```typescript
// Save successful config as template
await client.autonomous.saveAsTemplate({
  projectId: project.id,
  templateName: 'My Platformer Template',
  description: 'Configuration for 2D platformers',
});

// Reuse in future projects
const newProject = await client.autonomous.createFromTemplate({
  templateId: 'template_my_platformer',
});
```

---

## Troubleshooting

### Project Stuck

```typescript
// Check for pending interventions
const interventions = await client.autonomous.getPendingInterventions(
  project.id
);

// Force retry current phase
await client.autonomous.retryPhase(project.id);

// Reset to previous checkpoint
await client.autonomous.rollbackToCheckpoint(project.id, 'checkpoint_abc');
```

### Quality Issues

```typescript
// Get detailed quality report
const report = await client.autonomous.getQualityReport(project.id);

// Manually trigger quality recheck
await client.autonomous.rerunQualityGates(project.id);
```

### Budget Exceeded

```typescript
// Check what's consuming budget
const breakdown = await client.autonomous.getCostBreakdown(project.id);

// Pause and resume with different settings
await client.autonomous.pauseProject(project.id);
await client.autonomous.updateSettings(project.id, { quality: 'standard' });
await client.autonomous.resumeProject(project.id);
```

---

## Next Steps

- [Pipeline Configuration Guide](./pipeline-configuration.md)
- [Constraint Specification Tutorial](./constraint-specification.md)
- [Quality Gate Configuration](./quality-gates.md)
- [Output Customization Guide](./output-customization.md)
- [API Reference](../api/endpoints/README.md)
