package httpapi import ( "context" "encoding/base64" "errors" "io" "log/slog" "net/http" "strings" "time" "unicode" "speech-learning-api/internal/config" "speech-learning-api/internal/domain" "speech-learning-api/internal/services" ) type DataStore interface { GetUser(ctx context.Context, id string) (domain.User, error) GetPrimaryProfile(ctx context.Context, userID string) (domain.LearnerProfile, error) UpdatePreferences(ctx context.Context, userID, uiLanguage, targetLanguage, cefrLevel string, dailyGoalMinutes int) (domain.LearnerProfile, error) ListLanguages(ctx context.Context) ([]domain.LanguageProfile, error) GetLanguage(ctx context.Context, code string) (domain.LanguageProfile, error) NextLessonAndExercise(ctx context.Context, profile domain.LearnerProfile, avoidReferenceText ...string) (domain.Lesson, domain.Exercise, error) SaveGeneratedExercise(ctx context.Context, userID string, generated domain.GeneratedExercise) (domain.Lesson, domain.Exercise, error) GetExercise(ctx context.Context, id, userID string) (domain.Exercise, error) RecentPronunciationTexts(ctx context.Context, userID, language, level string) ([]string, error) SaveAttempt(ctx context.Context, attempt domain.Attempt) (domain.Attempt, error) Progress(ctx context.Context, userID string, limit int) (domain.ProgressSummary, error) AdminOverview(ctx context.Context) (domain.AdminOverview, error) AdminUsers(ctx context.Context, search string, page int) (domain.AdminUserPage, error) CreateConversationSession(ctx context.Context, userID, targetLanguage, cefrLevel string) (domain.ConversationSession, error) SaveConversationTurn(ctx context.Context, turn domain.ConversationTurn) (domain.ConversationTurn, error) DebugStatus(ctx context.Context) domain.DebugDBStatus CourseModules(ctx context.Context, userID, language, level string) ([]domain.CourseModule, error) CourseModule(ctx context.Context, userID, language, level, id string) (domain.CourseModuleDetail, error) CourseTaskKey(ctx context.Context, taskID, userID, language, level string) (domain.CourseTaskKey, error) SaveCourseAttempt(ctx context.Context, userID, taskID, answer string, correct bool) (string, error) SelectCoursePractice(ctx context.Context, userID, moduleID string) (domain.CoursePracticeSelection, error) CoursePractice(ctx context.Context, userID, moduleID string) ([]domain.CourseTask, error) CoursePracticeByRequest(ctx context.Context, userID, moduleID, requestID string) (domain.CoursePracticeResult, error) CoursePracticeFallback(ctx context.Context, userID, seedID string) (domain.CoursePracticeResult, error) SaveGeneratedCourseTask(ctx context.Context, userID, requestID string, out domain.GeneratedCourseTask) (domain.CoursePracticeResult, error) } type Server struct { ai *services.AIService course *services.CourseEngine cfg config.Config logger *slog.Logger store DataStore auth *services.AuthService speech services.SpeechService teacher services.TeacherAgent courseGenerator services.CourseTaskGenerator started time.Time } func NewServer(cfg config.Config, logger *slog.Logger, store DataStore, auth *services.AuthService, speech services.SpeechService, teacher services.TeacherAgent) *Server { generator, _ := teacher.(services.CourseTaskGenerator) return &Server{courseGenerator: generator, cfg: cfg, logger: logger, store: store, auth: auth, speech: speech, teacher: teacher, started: time.Now()} } func (s *Server) Routes() http.Handler { mux := http.NewServeMux() mux.HandleFunc("GET /health", s.health) mux.HandleFunc("POST /auth/register", s.register) mux.HandleFunc("POST /auth/login", s.login) mux.HandleFunc("POST /auth/logout", s.logout) mux.Handle("GET /me", s.requireAuth(http.HandlerFunc(s.me))) mux.Handle("PATCH /me/preferences", s.requireAuth(http.HandlerFunc(s.updatePreferences))) mux.Handle("GET /languages", s.requireAuth(http.HandlerFunc(s.languages))) mux.Handle("GET /languages/{code}/voices", s.requireAuth(http.HandlerFunc(s.languageVoices))) mux.Handle("GET /dashboard", s.requireAuth(http.HandlerFunc(s.dashboard))) mux.Handle("GET /pronunciation/profile", s.requireAuth(http.HandlerFunc(s.pronunciationProfile))) mux.Handle("GET /progress", s.requireAuth(http.HandlerFunc(s.progress))) mux.Handle("POST /lessons/next", s.requireAuth(http.HandlerFunc(s.nextLesson))) mux.Handle("GET /practice/exercises/{id}/audio", s.requireAuth(http.HandlerFunc(s.exerciseAudio))) mux.Handle("POST /practice/attempts", s.requireAuth(http.HandlerFunc(s.createAttempt))) mux.Handle("GET /course/catalog", s.requireAuth(http.HandlerFunc(s.adaptiveCatalog))) mux.Handle("POST /course/modules/{id}/tasks/next", s.requireAuth(http.HandlerFunc(s.adaptiveNext))) mux.Handle("GET /course/modules/{id}/tasks", s.requireAuth(http.HandlerFunc(s.adaptiveHistory))) mux.Handle("GET /course/jobs/{id}", s.requireAuth(http.HandlerFunc(s.adaptiveJob))) mux.Handle("POST /course/jobs/{id}/retry", s.requireAuth(http.HandlerFunc(s.adaptiveRetryJob))) mux.Handle("GET /course/tasks/{id}", s.requireAuth(http.HandlerFunc(s.adaptiveTask))) mux.Handle("POST /course/tasks/{id}/audio-attempts", s.requireAuth(http.HandlerFunc(s.adaptiveAudioAttempt))) mux.Handle("GET /course/attempts/{id}", s.requireAuth(http.HandlerFunc(s.adaptiveGetAttempt))) mux.Handle("POST /course/attempts/{id}/retry", s.requireAuth(http.HandlerFunc(s.adaptiveRetryAttempt))) mux.Handle("POST /course/exams", s.requireAuth(http.HandlerFunc(s.adaptiveNewExam))) mux.Handle("GET /course/exams/{id}", s.requireAuth(http.HandlerFunc(s.adaptiveExam))) mux.Handle("GET /course/modules", s.requireAuth(http.HandlerFunc(s.courseModules))) mux.Handle("POST /course/modules/{id}/practice/next", s.requireAuth(http.HandlerFunc(s.nextCoursePractice))) mux.Handle("GET /course/modules/{id}/practice", s.requireAuth(http.HandlerFunc(s.coursePractice))) mux.Handle("GET /course/modules/{id}", s.requireAuth(http.HandlerFunc(s.courseModule))) mux.Handle("POST /course/tasks/{id}/attempts", s.requireAuth(http.HandlerFunc(s.courseAttempt))) mux.Handle("GET /course/tasks/{id}/audio", s.requireAuth(http.HandlerFunc(s.courseAudio))) mux.Handle("POST /conversation/start", s.requireAuth(http.HandlerFunc(s.startConversation))) mux.Handle("POST /conversation/{id}/turn", s.requireAuth(http.HandlerFunc(s.conversationTurn))) mux.Handle("GET /admin/overview", s.requireAuth(s.requireAdmin(http.HandlerFunc(s.adminOverview)))) mux.Handle("GET /admin/users", s.requireAuth(s.requireAdmin(http.HandlerFunc(s.adminUsers)))) mux.Handle("GET /admin/ai/settings", s.requireAuth(s.requireAdmin(http.HandlerFunc(s.aiSettings)))) mux.Handle("PUT /admin/ai/profiles/{action}", s.requireAuth(s.requireAdmin(http.HandlerFunc(s.aiSaveProfile)))) mux.Handle("PUT /admin/ai/budget", s.requireAuth(s.requireAdmin(http.HandlerFunc(s.aiSaveBudget)))) mux.Handle("GET /admin/ai/providers/{provider}/models", s.requireAuth(s.requireAdmin(http.HandlerFunc(s.aiModels)))) mux.Handle("GET /admin/ai/usage", s.requireAuth(s.requireAdmin(http.HandlerFunc(s.aiUsage)))) mux.Handle("GET /admin/ai/calls/{id}", s.requireAuth(s.requireAdmin(http.HandlerFunc(s.aiCallDetail)))) mux.Handle("POST /admin/ai/calls/{id}/resolve", s.requireAuth(s.requireAdmin(http.HandlerFunc(s.aiResolve)))) mux.Handle("POST /admin/ai/quality", s.requireAuth(s.requireAdmin(http.HandlerFunc(s.aiQuality)))) mux.Handle("POST /admin/ai/test", s.requireAuth(s.requireAdmin(http.HandlerFunc(s.aiTest)))) if s.cfg.DebugEnabled { mux.Handle("GET /debug/status", s.requireAuth(s.requireAdmin(http.HandlerFunc(s.debugStatus)))) mux.Handle("GET /debug/db", s.requireAuth(s.requireAdmin(http.HandlerFunc(s.debugDB)))) mux.Handle("GET /debug/ai", s.requireAuth(s.requireAdmin(http.HandlerFunc(s.debugAI)))) mux.Handle("GET /debug/flowise", s.requireAuth(s.requireAdmin(http.HandlerFunc(s.debugFlowise)))) mux.Handle("GET /debug/azure", s.requireAuth(s.requireAdmin(http.HandlerFunc(s.debugAzure)))) mux.Handle("GET /debug/runtime", s.requireAuth(s.requireAdmin(http.HandlerFunc(s.debugRuntime)))) } return s.requestID(s.requestLogging(s.cors(mux))) } func (s *Server) health(w http.ResponseWriter, r *http.Request) { writeJSON(w, http.StatusOK, map[string]string{"status": "ok"}) } func (s *Server) register(w http.ResponseWriter, r *http.Request) { var req struct { Email string `json:"email"` Password string `json:"password"` UILanguage string `json:"ui_language"` TargetLanguage string `json:"target_language"` DailyGoalMinutes int `json:"daily_goal_minutes"` } if err := decodeJSON(r, &req); err != nil { writeError(w, http.StatusBadRequest, err) return } result, err := s.auth.Register(r.Context(), req.Email, req.Password, req.UILanguage, req.TargetLanguage, req.DailyGoalMinutes) if err != nil { writeError(w, http.StatusBadRequest, err) return } writeJSON(w, http.StatusCreated, result) } func (s *Server) login(w http.ResponseWriter, r *http.Request) { var req struct { Email string `json:"email"` Password string `json:"password"` } if err := decodeJSON(r, &req); err != nil { writeError(w, http.StatusBadRequest, err) return } result, err := s.auth.Login(r.Context(), req.Email, req.Password) if err != nil { status := http.StatusInternalServerError if errors.Is(err, services.ErrInvalidCredentials) { status = http.StatusUnauthorized } writeError(w, status, err) return } writeJSON(w, http.StatusOK, result) } func (s *Server) logout(w http.ResponseWriter, r *http.Request) { writeJSON(w, http.StatusOK, map[string]string{"status": "ok"}) } func (s *Server) me(w http.ResponseWriter, r *http.Request) { user, err := s.store.GetUser(r.Context(), currentUserID(r)) if err != nil { writeError(w, http.StatusNotFound, err) return } profile, err := s.store.GetPrimaryProfile(r.Context(), user.ID) if err != nil { writeError(w, http.StatusNotFound, err) return } writeJSON(w, http.StatusOK, map[string]any{"user": user, "profile": profile}) } func (s *Server) updatePreferences(w http.ResponseWriter, r *http.Request) { var req struct { UILanguage string `json:"ui_language"` TargetLanguage string `json:"target_language"` CEFRLevel string `json:"cefr_level"` DailyGoalMinutes int `json:"daily_goal_minutes"` } if err := decodeJSON(r, &req); err != nil { writeError(w, http.StatusBadRequest, err) return } profile, err := s.store.UpdatePreferences(r.Context(), currentUserID(r), req.UILanguage, req.TargetLanguage, valueOr(req.CEFRLevel, "A1"), req.DailyGoalMinutes) if err != nil { writeError(w, http.StatusBadRequest, err) return } writeJSON(w, http.StatusOK, profile) } func (s *Server) languages(w http.ResponseWriter, r *http.Request) { languages, err := s.store.ListLanguages(r.Context()) if err != nil { writeError(w, http.StatusInternalServerError, err) return } writeJSON(w, http.StatusOK, languages) } func (s *Server) languageVoices(w http.ResponseWriter, r *http.Request) { lang, err := s.store.GetLanguage(r.Context(), r.PathValue("code")) if err != nil { writeError(w, http.StatusNotFound, err) return } writeJSON(w, http.StatusOK, map[string]any{"code": lang.Code, "voices": lang.Voices, "default_voice": lang.DefaultTTSVoice}) } func (s *Server) dashboard(w http.ResponseWriter, r *http.Request) { userID := currentUserID(r) user, err := s.store.GetUser(r.Context(), userID) if err != nil { writeError(w, http.StatusNotFound, err) return } profile, err := s.store.GetPrimaryProfile(r.Context(), userID) if err != nil { writeError(w, http.StatusNotFound, err) return } progress, err := s.store.Progress(r.Context(), userID, 5) if err != nil { writeError(w, http.StatusInternalServerError, err) return } lesson, exercise, err := s.nextAgentExercise(r.Context(), user, profile, progress, nil) if err != nil { writeError(w, http.StatusNotFound, err) return } writeJSON(w, http.StatusOK, domain.Dashboard{ User: user, Profile: profile, Progress: progress, NextLesson: lesson, NextExercise: exercise, }) } func (s *Server) progress(w http.ResponseWriter, r *http.Request) { progress, err := s.store.Progress(r.Context(), currentUserID(r), 20) if err != nil { writeError(w, http.StatusInternalServerError, err) return } writeJSON(w, http.StatusOK, progress) } func (s *Server) nextLesson(w http.ResponseWriter, r *http.Request) { userID := currentUserID(r) var req struct { PreviousExerciseID string `json:"previous_exercise_id"` RecentExerciseIDs []string `json:"recent_exercise_ids"` } if err := decodeJSON(r, &req); err != nil && !errors.Is(err, io.EOF) { writeError(w, http.StatusBadRequest, err) return } recentIDs := req.RecentExerciseIDs if req.PreviousExerciseID != "" && (len(recentIDs) == 0 || recentIDs[len(recentIDs)-1] != req.PreviousExerciseID) { recentIDs = append(recentIDs, req.PreviousExerciseID) } if len(recentIDs) > 3 { writeError(w, http.StatusBadRequest, errors.New("at most three recent exercises are allowed")) return } avoidReferenceTexts := make([]string, 0, len(recentIDs)) for _, id := range recentIDs { previous, err := s.store.GetExercise(r.Context(), id, userID) if err != nil { writeError(w, http.StatusNotFound, err) return } avoidReferenceTexts = append(avoidReferenceTexts, previous.TargetText) } user, err := s.store.GetUser(r.Context(), userID) if err != nil { writeError(w, http.StatusNotFound, err) return } profile, err := s.store.GetPrimaryProfile(r.Context(), userID) if err != nil { writeError(w, http.StatusNotFound, err) return } progress, err := s.store.Progress(r.Context(), userID, 10) if err != nil { writeError(w, http.StatusInternalServerError, err) return } lesson, exercise, err := s.nextAgentExercise(r.Context(), user, profile, progress, avoidReferenceTexts) if err != nil { writeError(w, http.StatusNotFound, err) return } writeJSON(w, http.StatusOK, map[string]any{"lesson": lesson, "exercise": exercise}) } func (s *Server) nextAgentExercise(ctx context.Context, user domain.User, profile domain.LearnerProfile, progress domain.ProgressSummary, avoidReferenceTexts []string) (domain.Lesson, domain.Exercise, error) { // Keep fallback exercises available even when the learner has already used // every seed. The broader persisted history constrains generated sentences. fallbackAvoid := append([]string{}, avoidReferenceTexts...) recent, err := s.store.RecentPronunciationTexts(ctx, user.ID, profile.TargetLanguage, profile.CEFRLevel) if err != nil { return domain.Lesson{}, domain.Exercise{}, err } avoidReferenceTexts = append(append([]string{}, avoidReferenceTexts...), recent...) avoidReferenceText := "" if len(avoidReferenceTexts) > 0 { avoidReferenceText = avoidReferenceTexts[len(avoidReferenceTexts)-1] } var plan *domain.PronunciationPlan if s.cfg.PronunciationStrategy == "statistical" { repo, ok := s.store.(pronunciationStore) if !ok { return domain.Lesson{}, domain.Exercise{}, errors.New("pronunciation statistics unavailable") } selected, err := repo.PlanPronunciation(ctx, user.ID, profile.TargetLanguage, time.Now().UTC()) if err != nil { return domain.Lesson{}, domain.Exercise{}, err } plan = &selected } generated, err := s.teacher.NextExercise(ctx, domain.GeneratedExerciseRequest{ TrainingPlan: plan, UserID: user.ID, Profile: profile, Progress: progress, TargetLanguage: profile.TargetLanguage, CEFRLevel: profile.CEFRLevel, UILanguage: user.UILanguage, SessionID: flowiseSessionID(user.ID, profile.TargetLanguage, "practice"), RecentWeakWords: progress.WeakWords, PreferredType: "repeat_sentence", AvoidReferenceText: avoidReferenceText, AvoidReferenceTexts: avoidReferenceTexts, }) if err == nil && (generated.Source == "flowise" || generated.Source == "ai") && strings.TrimSpace(generated.ReferenceText) != "" { generated.TrainingPlan = plan if plan != nil && plan.Mode == "transfer" { plan.CandidateWord = generated.CandidateWord } lesson, exercise, saveErr := s.store.SaveGeneratedExercise(ctx, user.ID, generated) if saveErr == nil { s.logger.Info("next exercise selected", "request_id", ctx.Value(requestIDKey), "source", exercise.Source, "exercise_id", exercise.ID) return lesson, exercise, nil } s.logger.Warn("saving generated exercise failed, using seed fallback", "error", saveErr) } if err != nil { s.logger.Warn("AI next exercise failed, using seed fallback", "error", err) } if plan != nil { if repo, ok := s.store.(pronunciationStore); ok { if planErr := repo.FailPronunciationPlan(ctx, user.ID, plan.ID); planErr != nil { s.logger.Warn("pronunciation plan cleanup failed", "error", planErr) } } } lesson, exercise, err := s.store.NextLessonAndExercise(ctx, profile, fallbackAvoid...) if err == nil { s.logger.Info("next exercise selected", "request_id", ctx.Value(requestIDKey), "source", exercise.Source, "exercise_id", exercise.ID) } return lesson, exercise, err } func (s *Server) exerciseAudio(w http.ResponseWriter, r *http.Request) { exercise, err := s.store.GetExercise(r.Context(), r.PathValue("id"), currentUserID(r)) if err != nil { writeError(w, http.StatusNotFound, err) return } mode := r.URL.Query().Get("mode") if mode == "" { mode = "normal" } if mode != "normal" && mode != "slow" && mode != "focus" { writeError(w, http.StatusBadRequest, errors.New("unsupported audio mode")) return } focusWord := r.URL.Query().Get("word") if mode == "focus" { focusWord = exerciseFocusWord(exercise.TargetText, focusWord) if focusWord == "" { writeError(w, http.StatusBadRequest, errors.New("word must occur in the exercise sentence")) return } } else if focusWord != "" { writeError(w, http.StatusBadRequest, errors.New("word is only supported in focus mode")) return } language, err := s.store.GetLanguage(r.Context(), exercise.TargetLanguage) if err != nil { writeError(w, http.StatusInternalServerError, err) return } audio, mime, err := s.speech.SynthesizeExercise(r.Context(), language.AzureLocale, language.DefaultTTSVoice, exercise.TargetText, mode, focusWord) if err != nil { writeError(w, http.StatusBadGateway, err) return } if len(audio) == 0 { writeError(w, http.StatusServiceUnavailable, errors.New("audio is unavailable")) return } w.Header().Set("Content-Type", mime) w.Header().Set("Cache-Control", "private, no-store") w.WriteHeader(http.StatusOK) _, _ = w.Write(audio) } func exerciseFocusWord(sentence, requested string) string { requested = strings.TrimFunc(strings.TrimSpace(requested), func(r rune) bool { return !unicode.IsLetter(r) && !unicode.IsNumber(r) }) if requested == "" { return "" } for _, token := range strings.Fields(sentence) { word := strings.TrimFunc(token, func(r rune) bool { return !unicode.IsLetter(r) && !unicode.IsNumber(r) }) if strings.EqualFold(word, requested) { return word } } return "" } func (s *Server) createAttempt(w http.ResponseWriter, r *http.Request) { if err := r.ParseMultipartForm(24 << 20); err != nil { writeError(w, http.StatusBadRequest, err) return } exerciseID := r.FormValue("exercise_id") exercise, err := s.store.GetExercise(r.Context(), exerciseID, currentUserID(r)) if err != nil { writeError(w, http.StatusNotFound, err) return } file, header, err := r.FormFile("audio") if err != nil { writeError(w, http.StatusBadRequest, errors.New("audio file is required")) return } defer file.Close() audio, err := io.ReadAll(io.LimitReader(file, 20<<20)) if err != nil { writeError(w, http.StatusBadRequest, err) return } contentType := header.Header.Get("Content-Type") if contentType == "" { contentType = "audio/wav" } result, err := s.speech.AssessPronunciation(r.Context(), services.PronunciationInput{ Audio: audio, ContentType: contentType, TargetText: exercise.TargetText, Locale: exercise.TargetLanguage, }) if err != nil { writeError(w, http.StatusBadGateway, err) return } teacher, err := s.teacher.FeedbackForAttempt(r.Context(), exercise.TargetText, result, weakWords(result.WordScores)) if err != nil { writeError(w, http.StatusBadGateway, err) return } attempt, err := s.store.SaveAttempt(r.Context(), domain.Attempt{ UserID: currentUserID(r), Provider: result.Provider, Measurement: &result, ExerciseID: exercise.ID, TargetLanguage: exercise.TargetLanguage, RecognizedText: result.RecognizedText, OverallScore: result.OverallScore, AccuracyScore: result.AccuracyScore, FluencyScore: result.FluencyScore, CompletenessScore: result.CompletenessScore, ProsodyScore: result.ProsodyScore, WordScores: result.WordScores, TeacherFeedback: teacher.TeacherFeedback, }) if err != nil { writeError(w, http.StatusInternalServerError, err) return } if s.course != nil { if err := s.course.Repo.SyncLegacyForExercise(r.Context(), exercise.ID); err != nil { s.logger.Warn("legacy speech evidence sync failed", "error", err) } } writeJSON(w, http.StatusCreated, map[string]any{"attempt": attempt, "teacher": teacher, "provider": result.Provider}) } func (s *Server) startConversation(w http.ResponseWriter, r *http.Request) { profile, err := s.store.GetPrimaryProfile(r.Context(), currentUserID(r)) if err != nil { writeError(w, http.StatusNotFound, err) return } session, err := s.store.CreateConversationSession(r.Context(), currentUserID(r), profile.TargetLanguage, profile.CEFRLevel) if err != nil { writeError(w, http.StatusInternalServerError, err) return } teacher, err := s.teacher.StartConversation(r.Context(), profile.TargetLanguage, profile.CEFRLevel) if err != nil { writeError(w, http.StatusBadGateway, err) return } lang, _ := s.store.GetLanguage(r.Context(), profile.TargetLanguage) audio, mime, _ := s.speech.Synthesize(r.Context(), lang.AzureLocale, lang.DefaultTTSVoice, firstNonEmpty(teacher.TTSText, teacher.TargetText)) turn, _ := s.store.SaveConversationTurn(r.Context(), domain.ConversationTurn{SessionID: session.ID, Speaker: "teacher", Text: firstNonEmpty(teacher.TTSText, teacher.TargetText)}) writeJSON(w, http.StatusCreated, map[string]any{ "session": session, "turn": turn, "teacher": teacher, "audio": encodeAudio(audio, mime), }) } func (s *Server) conversationTurn(w http.ResponseWriter, r *http.Request) { var req struct { Text string `json:"text"` } if err := decodeJSON(r, &req); err != nil { writeError(w, http.StatusBadRequest, err) return } profile, err := s.store.GetPrimaryProfile(r.Context(), currentUserID(r)) if err != nil { writeError(w, http.StatusNotFound, err) return } sessionID := r.PathValue("id") userTurn, err := s.store.SaveConversationTurn(r.Context(), domain.ConversationTurn{SessionID: sessionID, Speaker: "learner", Text: req.Text}) if err != nil { writeError(w, http.StatusInternalServerError, err) return } teacher, err := s.teacher.ContinueConversation(r.Context(), profile.TargetLanguage, profile.CEFRLevel, req.Text) if err != nil { writeError(w, http.StatusBadGateway, err) return } lang, _ := s.store.GetLanguage(r.Context(), profile.TargetLanguage) audio, mime, _ := s.speech.Synthesize(r.Context(), lang.AzureLocale, lang.DefaultTTSVoice, firstNonEmpty(teacher.TTSText, teacher.TargetText)) teacherTurn, _ := s.store.SaveConversationTurn(r.Context(), domain.ConversationTurn{SessionID: sessionID, Speaker: "teacher", Text: firstNonEmpty(teacher.TTSText, teacher.TargetText)}) writeJSON(w, http.StatusOK, map[string]any{ "user_turn": userTurn, "teacher_turn": teacherTurn, "teacher": teacher, "audio": encodeAudio(audio, mime), }) } func weakWords(words []domain.WordScore) []domain.WordScore { out := make([]domain.WordScore, 0) for _, word := range words { if word.Accuracy < 75 { out = append(out, word) } } return out } func encodeAudio(audio []byte, mime string) map[string]string { if len(audio) == 0 { return nil } return map[string]string{ "mime_type": mime, "base64": base64.StdEncoding.EncodeToString(audio), } } func firstNonEmpty(values ...string) string { for _, value := range values { if strings.TrimSpace(value) != "" { return value } } return "" } func flowiseSessionID(userID, targetLanguage, scope string) string { parts := []string{strings.TrimSpace(userID), strings.TrimSpace(targetLanguage), strings.TrimSpace(scope)} for i, part := range parts { parts[i] = strings.ReplaceAll(part, " ", "_") } return strings.Join(parts, ":") } func valueOr(value, fallback string) string { if strings.TrimSpace(value) == "" { return fallback } return value }