speak-core-workflow-a

name	speak-core-workflow-a
description	Execute Speak primary workflow: AI Conversation Practice with real-time feedback. Use when implementing conversation practice features, building AI tutor interactions, or core language learning dialogue systems. Trigger with phrases like "speak conversation practice", "speak AI tutor", "speak dialogue", "primary speak workflow".
allowed-tools	Read, Write, Edit, Bash(npm:*), Grep
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>

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

   session =  tutor.({
    : config.,
    : config. *  * , 
    : config. || [, ],
    : ,
  });

   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) {
      .();
    }

    
     userResponse =  ();

    
     feedback =  session.({
      : userResponse.,
      : userResponse.,
    });

     :  = {
      tutorPrompt,
      userResponse,
      feedback,
    };

    exchanges.(exchange);
    (exchange);

    
    (feedback);

    
     (feedback.) {
      ;
    }
  }

   session.();
}

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}" → ""`);
      .();
    }
  }

   (feedback.. > ) {
    .();
    feedback..( .());
  }

  .();
}

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: (summary),
    : (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);
  });

  
  .();
  .();
  .();
  .();

   (summary.. > ) {
    .();
    summary..( .());
  }

  .();

   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.