# Content Generation API Documentation

This guide covers the APIs for autonomous content generation including meditation scripts, daily content, conversations, and more.

## Overview

The content generation system uses multi-agent pipelines powered by OpenRouter and ElevenLabs to create:

- **Meditation Scripts**: Structured scripts with audio tags
- **Daily Content**: Quotes, reflections, and moments
- **Conversations**: Multi-speaker dialogues
- **Sleep Content**: Sleep stories and soundscapes
- **Yoga Sequences**: Pose sequences with instructions

## Content Orchestration Service

The central service for coordinating content generation pipelines.

### Basic Usage

```typescript
import { ContentOrchestrationService } from '../content-orchestration/content-orchestration-service.js';

const orchestrator = new ContentOrchestrationService({
  openRouterApiKey: process.env.OPENROUTER_API_KEY,
  elevenLabsApiKey: process.env.ELEVENLABS_API_KEY
});

const content = await orchestrator.generateContent({
  type: 'meditation',
  tradition: 'buddhist',
  duration: 600,  // 10 minutes
  theme: 'loving-kindness'
});
```

## Meditation Script Generation

### Generate a Script

```typescript
import {
  MeditationScriptService,
  type ScriptGenerationRequest
} from '../meditation-script-generation/meditation-script-service.js';

const service = new MeditationScriptService({
  llmProvider: openRouterProvider,
  defaultModel: 'anthropic/claude-sonnet-4.5'
});

const request: ScriptGenerationRequest = {
  tradition: 'buddhist',
  technique: 'breath-awareness',
  targetDuration: 600,  // 10 minutes in seconds
  voiceTone: 'calm',
  pacingSpeed: 'slow',
  difficulty: 'beginner',
  theme: 'Finding inner peace',
  includeAudioTags: true
};

const result = await service.generateScript(request);
```

### Script Structure

```typescript
interface MeditationScript {
  id: string;
  title: string;
  tradition: MeditationTradition;
  technique: MeditationTechnique;
  sections: ScriptSection[];
  metadata: ScriptMetadata;
  audioTags: AudioTag[];
  citations: Citation[];
  totalDuration: number;
  wordCount: number;
}

interface ScriptSection {
  type: ScriptSectionType;  // 'opening' | 'body' | 'deepening' | 'transition' | 'closing'
  content: string;
  duration: number;
  audioTags: AudioTag[];
  emotionalBeat?: EmotionalBeat;
}
```

### Traditions

| Tradition | Key Concepts |
|-----------|--------------|
| `buddhist` | Mindfulness, Four Noble Truths, Eightfold Path |
| `hindu` | Yoga, Chakras, Mantras, Prana |
| `taoist` | Wu Wei, Yin-Yang, Qi, Flow |
| `christian` | Contemplative prayer, Lectio Divina |
| `sufi` | Dhikr, Heart meditation, Divine love |
| `zen` | Zazen, Koans, Present moment |
| `secular` | Mindfulness without religious context |

### Techniques

| Technique | Description |
|-----------|-------------|
| `breath-awareness` | Focus on breath sensations |
| `body-scan` | Systematic body awareness |
| `loving-kindness` | Metta/compassion practice |
| `visualization` | Guided imagery |
| `mantra` | Repetitive sacred phrases |
| `open-awareness` | Choiceless awareness |
| `walking` | Mindful movement |

### Progress Tracking

```typescript
const result = await service.generateScript(request, (progress) => {
  console.log(`Stage: ${progress.stage}`);
  console.log(`Progress: ${progress.progress}%`);
  console.log(`Message: ${progress.message}`);
});
```

### Pipeline Stages

1. **Architect** - Structures the meditation flow
2. **Writer** - Creates the prose content
3. **Tradition Expert** - Ensures authenticity
4. **Quality Reviewer** - Polishes and refines

## Daily Content Service

Generate daily quotes, reflections, and moments.

### Generate Daily Quote

```typescript
import { AutonomousDailyContentService } from '../daily-content/autonomous-daily-content-service.js';

const service = new AutonomousDailyContentService(config);

const quote = await service.generateQuote({
  tradition: 'zen',
  theme: 'impermanence',
  mood: 'contemplative'
});

// Result
{
  text: "Like morning dew on a lotus leaf...",
  attribution: "Zen teaching",
  tradition: "zen",
  tags: ["impermanence", "nature", "awareness"]
}
```

### Generate Daily Reflection

```typescript
const reflection = await service.generateReflection({
  tradition: 'buddhist',
  topic: 'gratitude',
  length: 'medium'  // short | medium | long
});
```

### Generate Moment

```typescript
const moment = await service.generateMoment({
  context: 'morning',
  duration: 60,  // 1 minute
  focus: 'breath'
});
```

### Schedule Content Generation

```typescript
// Schedule daily content generation
await service.scheduleDailyGeneration({
  quotesPerDay: 5,
  reflectionsPerDay: 2,
  momentsPerDay: 10,
  traditions: ['buddhist', 'zen', 'taoist'],
  generateAt: '04:00'  // 4 AM UTC
});
```

## Conversation Generation

Generate multi-speaker dialogues and discussions.

### Generate Conversation

```typescript
import { ConversationGenerationService } from '../conversation-generation/conversation-generation-service.js';

const service = new ConversationGenerationService(config);

const conversation = await service.generateConversation({
  topic: 'The nature of consciousness',
  speakers: [
    { name: 'Sam', tradition: 'secular', role: 'host' },
    { name: 'Thich', tradition: 'buddhist', role: 'guest' }
  ],
  duration: 1800,  // 30 minutes
  style: 'exploratory',
  includeTimestamps: true
});
```

### Conversation Output

```typescript
interface Conversation {
  id: string;
  title: string;
  topic: string;
  speakers: Speaker[];
  segments: ConversationSegment[];
  duration: number;
  wordCount: number;
}

interface ConversationSegment {
  speaker: string;
  text: string;
  startTime: number;
  endTime: number;
  emotion?: string;
  audioTags?: AudioTag[];
}
```

### Generate Podcast Episode

```typescript
const episode = await service.generatePodcastEpisode({
  series: 'Making Sense of Meditation',
  topic: 'The Science of Mindfulness',
  host: { name: 'Sam', voiceId: 'host_voice_id' },
  guest: { name: 'Dr. Davidson', voiceId: 'guest_voice_id' },
  duration: 3600,  // 1 hour
  includeIntroOutro: true
});
```

## Sleep Content Generation

Generate sleep stories and soundscapes.

### Generate Sleep Story

```typescript
const story = await service.generateSleepStory({
  theme: 'forest-journey',
  duration: 1800,  // 30 minutes
  voiceTone: 'soothing',
  includeNatureNarrative: true,
  fadeOutEnding: true
});
```

### Generate Sleep Meditation

```typescript
const meditation = await service.generateSleepMeditation({
  technique: 'body-scan',
  duration: 1200,  // 20 minutes
  progressiveRelaxation: true,
  includeBodyScan: true,
  endWithSilence: 300  // 5 minutes of silence at end
});
```

## Yoga Sequence Generation

Generate yoga sequences with instructions.

```typescript
import { YogaSequenceService } from '../yoga-sequence-generation/yoga-sequence-service.js';

const service = new YogaSequenceService(config);

const sequence = await service.generateSequence({
  style: 'vinyasa',
  duration: 1800,  // 30 minutes
  level: 'intermediate',
  focus: 'hip-openers',
  includeBreathwork: true,
  includeMeditation: true
});
```

### Sequence Output

```typescript
interface YogaSequence {
  id: string;
  name: string;
  style: YogaStyle;
  poses: YogaPose[];
  transitions: Transition[];
  breathwork: Breathwork[];
  duration: number;
}

interface YogaPose {
  name: string;
  sanskritName: string;
  duration: number;
  side?: 'left' | 'right' | 'both';
  instructions: string;
  modifications: string[];
  benefits: string[];
}
```

## Quality Assurance

### Validate Content

```typescript
const validation = await service.validateContent(content, {
  checkTraditionAccuracy: true,
  checkReadability: true,
  checkAudioTagBalance: true,
  checkPacing: true
});

console.log(`Valid: ${validation.valid}`);
console.log(`Score: ${validation.score}`);
console.log(`Issues: ${validation.issues}`);
```

### Quality Gates

| Gate | Threshold | Description |
|------|-----------|-------------|
| Tradition Accuracy | 85% | Correct terminology and concepts |
| Readability | Grade 8 | Flesch-Kincaid grade level |
| Pacing | ±10% | Duration within target |
| Audio Tag Density | 5-15% | Appropriate pause distribution |
| Sensitivity | Pass | No harmful content |

### Content Review

```typescript
const review = await service.reviewContent(content);

console.log(`Overall Score: ${review.overallScore}`);
console.log(`Tradition Score: ${review.traditionScore}`);
console.log(`Technical Score: ${review.technicalScore}`);
console.log(`Engagement Score: ${review.engagementScore}`);
console.log(`Suggestions: ${review.suggestions}`);
```

## Audio Tag Integration

### Available Tags

| Tag | Usage | Example |
|-----|-------|---------|
| `<break>` | Pause | `<break time="2s" />` |
| `<emphasis>` | Stress | `<emphasis level="strong">deep</emphasis>` |
| `<phoneme>` | Pronunciation | `<phoneme ph="naːmɑːsteɪ">namaste</phoneme>` |
| `<prosody>` | Rate/pitch | `<prosody rate="slow">slowly</prosody>` |
| `<say-as>` | Interpretation | `<say-as interpret-as="cardinal">3</say-as>` |

### Automatic Tag Insertion

```typescript
const script = await service.generateScript({
  ...request,
  includeAudioTags: true,
  audioTagDensity: 'moderate',  // sparse | moderate | dense
  breathPauseSeconds: 3,
  transitionPauseSeconds: 2
});
```

## Batch Generation

### Generate Multiple Scripts

```typescript
const requests: ScriptGenerationRequest[] = [
  { tradition: 'buddhist', technique: 'breath-awareness', targetDuration: 600 },
  { tradition: 'zen', technique: 'open-awareness', targetDuration: 900 },
  { tradition: 'hindu', technique: 'mantra', targetDuration: 1200 }
];

const results = await service.generateBatch(requests, {
  concurrency: 3,
  onProgress: (completed, total) => {
    console.log(`Progress: ${completed}/${total}`);
  }
});
```

### Scheduled Generation

```typescript
await service.scheduleGeneration({
  cron: '0 4 * * *',  // Daily at 4 AM
  requests: [
    { type: 'meditation', count: 10 },
    { type: 'quote', count: 50 },
    { type: 'moment', count: 20 }
  ],
  qualityThreshold: 0.8,
  autoPublish: false
});
```

## Event Handling

```typescript
service.on('generation-started', (event) => {
  console.log(`Starting: ${event.type} - ${event.id}`);
});

service.on('generation-progress', (event) => {
  console.log(`${event.stage}: ${event.progress}%`);
});

service.on('generation-completed', (event) => {
  console.log(`Completed: ${event.id}`);
  console.log(`Duration: ${event.duration}ms`);
  console.log(`Quality Score: ${event.qualityScore}`);
});

service.on('generation-failed', (event) => {
  console.error(`Failed: ${event.error}`);
});

service.on('quality-gate-failed', (event) => {
  console.warn(`Quality gate failed: ${event.gate}`);
  console.warn(`Score: ${event.score}, Required: ${event.threshold}`);
});
```

## Error Handling

```typescript
try {
  const script = await service.generateScript(request);
} catch (error) {
  if (error.code === 'TRADITION_VALIDATION_FAILED') {
    console.log('Content failed tradition accuracy check');
  } else if (error.code === 'QUALITY_GATE_FAILED') {
    console.log('Content failed quality review');
  } else if (error.code === 'LLM_ERROR') {
    console.log('Language model error, retry with fallback');
  } else if (error.code === 'RATE_LIMITED') {
    console.log('API rate limited, backoff and retry');
  }
}
```

## Best Practices

### 1. Use Appropriate Models

```typescript
// Complex meditation: Use powerful model
const meditation = await service.generateScript({
  ...request,
  model: 'anthropic/claude-sonnet-4.5'
});

// Simple quotes: Use fast model
const quote = await service.generateQuote({
  ...request,
  model: 'openai/gpt-4o-mini'
});
```

### 2. Set Quality Thresholds

```typescript
const service = new MeditationScriptService({
  ...config,
  minQualityScore: 0.8,
  autoRegenerate: true,
  maxRegenerationAttempts: 3
});
```

### 3. Use Caching

```typescript
const service = new ContentOrchestrationService({
  ...config,
  cacheEnabled: true,
  cacheTTL: 3600,
  cacheByTradition: true
});
```

### 4. Monitor Costs

```typescript
const stats = service.getStats();
console.log(`Total requests: ${stats.totalRequests}`);
console.log(`Tokens used: ${stats.tokensUsed}`);
console.log(`Estimated cost: $${stats.estimatedCost.toFixed(4)}`);
```

## Related Resources

- [OpenRouter Integration Guide](./openrouter-integration.md)
- [ElevenLabs Integration Guide](./elevenlabs-integration.md)
- [Model Selection Guide](./model-selection.md)
- [Cost Optimization Guide](./cost-optimization.md)
