Speak Core Workflow A: Conversation Practice

Overview

Primary workflow for Speak: AI-powered conversation practice with real-time pronunciation feedback and adaptive tutoring.

Prerequisites

• Completed speak-install-auth setup
• Understanding of Speak core concepts
• Valid API credentials configured
• Audio handling capabilities (for speech input)

Instructions

Step 1: Initialize Conversation Session

// src/workflows/conversation-practice.ts
import {
  SpeakClient,
  AITutor,
  ConversationSession,
  ConversationConfig,
} from '@speak/language-sdk';

interface ConversationPracticeConfig {
  targetLanguage: string;
  nativeLanguage: string;
  topic: string;
  difficulty: 'beginner' | 'intermediate' | 'advanced';
  duration: number; // minutes
  focusAreas?: ('pronunciation' | 'grammar' | 'vocabulary' | 'fluency')[];
}

async function initializeConversation(
  client: SpeakClient,
  config: ConversationPracticeConfig
): Promise<ConversationSession> {
  const tutor = new AITutor(client, {
    targetLanguage: config.targetLanguage,
    nativeLanguage: config.nativeLanguage,
    proficiencyLevel: config.difficulty,
    personality: 'encouraging', // or 'strict', 'casual'
  });

  const session = await tutor.startConversation({
    topic: config.topic,
    maxDuration: config.duration * 60 * 1000, // Convert to ms
    focusAreas: config.focusAreas || ['pronunciation', 'grammar'],
    adaptiveDifficulty: true,
  });

  return session;
}

Step 2: Implement Conversation Loop

interface ConversationExchange {
  tutorPrompt: {
    text: string;
    audioUrl: string;
    translation?: string;
  };
  userResponse: {
    text: string;
    audioData?: ArrayBuffer;
  };
  feedback: {
    pronunciationScore: number;
    grammarCorrections: GrammarCorrection[];
    suggestions: string[];
    encouragement: string;
  };
}

async function runConversationLoop(
  session: ConversationSession,
  onExchange: (exchange: ConversationExchange) => void
): Promise<ConversationSummary> {
  const exchanges: ConversationExchange[] = [];

  while (!session.isComplete) {
    // Get AI tutor's prompt
    const tutorPrompt = await session.getNextPrompt();

    // Display prompt to user (with audio playback)
    console.log(`\nTutor: ${tutorPrompt.text}`);
    if (tutorPrompt.translation) {
      console.log(`(${tutorPrompt.translation})`);
    }

    // Get user's response (from speech recognition or text input)
    const userResponse = await getUserResponse();

    // Submit response and get feedback
    const feedback = await session.submitResponse({
      text: userResponse.text,
      audioData: userResponse.audioData,
    });

    const exchange: ConversationExchange = {
      tutorPrompt,
      userResponse,
      feedback,
    };

    exchanges.push(exchange);
    onExchange(exchange);

    // Display feedback
    displayFeedback(feedback);

    // Check if session should continue
    if (feedback.shouldEndSession) {
      break;
    }
  }

  return session.getSummary();
}

Step 3: Handle Real-time Pronunciation Feedback

interface PronunciationFeedback {
  overall: number;
  words: WordScore[];
  phonemes?: PhonemeScore[];
  suggestions: string[];
}

interface WordScore {
  word: string;
  score: number;
  issue?: 'stress' | 'tone' | 'length' | 'pronunciation';
  suggestion?: string;
}

function displayFeedback(feedback: ConversationExchange['feedback']) {
  console.log(`\n--- Feedback ---`);
  console.log(`Pronunciation: ${feedback.pronunciationScore}/100`);

  if (feedback.grammarCorrections.length > 0) {
    console.log('\nGrammar corrections:');
    for (const correction of feedback.grammarCorrections) {
      console.log(`  "${correction.original}" → "${correction.corrected}"`);
      console.log(`  Explanation: ${correction.explanation}`);
    }
  }

  if (feedback.suggestions.length > 0) {
    console.log('\nSuggestions:');
    feedback.suggestions.forEach(s => console.log(`  • ${s}`));
  }

  console.log(`\n${feedback.encouragement}`);
}

Step 4: Generate Session Summary

interface ConversationSummary {
  sessionId: string;
  duration: number;
  topic: string;
  totalExchanges: number;
  averagePronunciationScore: number;
  vocabularyUsed: VocabularyItem[];
  grammarPatternsPracticed: string[];
  areasForImprovement: string[];
  achievements: Achievement[];
  nextLessonSuggestion: string;
}

async function generateSessionSummary(
  session: ConversationSession
): Promise<ConversationSummary> {
  const summary = await session.getSummary();

  return {
    ...summary,
    // Calculate metrics
    averagePronunciationScore: calculateAveragePronunciation(summary.exchanges),
    vocabularyUsed: extractVocabulary(summary.exchanges),
    grammarPatternsPracticed: extractGrammarPatterns(summary.exchanges),
    areasForImprovement: analyzeWeakAreas(summary.exchanges),
    achievements: checkAchievements(summary),
    nextLessonSuggestion: suggestNextLesson(summary),
  };
}

Complete Workflow Example

// Full conversation practice workflow
async function conversationPracticeWorkflow() {
  const client = getSpeakClient();

  // Configure session
  const config: ConversationPracticeConfig = {
    targetLanguage: 'es',
    nativeLanguage: 'en',
    topic: 'ordering_food_restaurant',
    difficulty: 'intermediate',
    duration: 10, // 10 minutes
    focusAreas: ['pronunciation', 'vocabulary'],
  };

  console.log('Starting conversation practice...');
  console.log(`Topic: ${config.topic}`);
  console.log(`Language: ${config.targetLanguage}`);

  // Initialize session
  const session = await initializeConversation(client, config);

  // Run conversation loop
  const summary = await runConversationLoop(session, (exchange) => {
    // Real-time callback for each exchange
    trackProgress(exchange);
  });

  // Display summary
  console.log('\n========== Session Complete ==========');
  console.log(`Duration: ${Math.round(summary.duration / 60000)} minutes`);
  console.log(`Exchanges: ${summary.totalExchanges}`);
  console.log(`Average Pronunciation: ${summary.averagePronunciationScore}/100`);

  if (summary.achievements.length > 0) {
    console.log('\nAchievements earned:');
    summary.achievements.forEach(a => console.log(`  🏆 ${a.name}`));
  }

  console.log(`\nSuggested next lesson: ${summary.nextLessonSuggestion}`);

  return summary;
}

Output

• Completed conversation practice session
• Real-time pronunciation feedback
• Grammar corrections and suggestions
• Session summary with progress metrics
• Next lesson recommendations

Error Handling

| Error | Cause | Solution | |-------|-------|----------| | Session Timeout | Exceeded duration | Auto-end with summary | | Audio Processing Failed | Invalid audio format | Validate audio before submit | | Tutor Not Responding | API latency | Implement timeout and retry | | Recognition Failed | Poor audio quality | Prompt user to re-record |

Topic Categories

| Category | Example Topics | |----------|----------------| | Daily Life | greetings, shopping, directions | | Travel | hotel_booking, restaurant, transportation | | Work | meetings, presentations, negotiations | | Social | making_friends, parties, small_talk | | Culture | holidays, traditions, food |

Resources

• Speak Conversation API
• Topic Reference
• Audio Requirements

Next Steps

For pronunciation-focused training, see speak-core-workflow-b.