Eve library

Content Generation API Documentation

Guide

Revision 1

On this page

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)}`);