package services import ( "bytes" "context" "encoding/json" "fmt" "io" "log/slog" "net/http" "strings" "time" "unicode" "unicode/utf8" "speech-learning-api/internal/config" "speech-learning-api/internal/domain" ) type TeacherAgent interface { NextExercise(ctx context.Context, input domain.GeneratedExerciseRequest) (domain.GeneratedExercise, error) FeedbackForAttempt(ctx context.Context, targetText string, result domain.PronunciationResult, weakWords []domain.WordScore) (domain.TeacherResponse, error) StartConversation(ctx context.Context, targetLanguage, cefrLevel string) (domain.TeacherResponse, error) ContinueConversation(ctx context.Context, targetLanguage, cefrLevel, userText string) (domain.TeacherResponse, error) } type FlowiseTeacher struct { cfg config.Config client *http.Client logger *slog.Logger } func NewFlowiseTeacher(cfg config.Config, logger *slog.Logger) *FlowiseTeacher { return &FlowiseTeacher{ cfg: cfg, client: &http.Client{ Timeout: 30 * time.Second, }, logger: logger, } } func (f *FlowiseTeacher) NextExercise(ctx context.Context, input domain.GeneratedExerciseRequest) (domain.GeneratedExercise, error) { fallback := domain.GeneratedExercise{ ID: "", ExerciseType: "repeat_sentence", TargetLanguage: valueOr(input.TargetLanguage, "en-US"), CEFRLevel: valueOr(input.CEFRLevel, "A1"), ReferenceText: "Hello, my name is Anna.", DisplayPrompt: "Sprich den Satz klar nach.", TTSText: "Hello, my name is Anna.", FocusPoints: []string{"clear rhythm", "final sounds"}, SuccessCriteria: []string{"accuracy above 80"}, ReasonForChoice: "Fallback exercise because Flowise did not return a valid exercise.", Source: "fallback", } if input.UILanguage == "ru-RU" { fallback.DisplayPrompt = "Чётко повторите предложение вслух." fallback.FocusPoints = []string{"ритм", "конечные звуки"} fallback.SuccessCriteria = []string{"точность выше 80"} fallback.ReasonForChoice = "Резервное упражнение: новое упражнение сейчас недоступно." } progress := compactProgressForFlowise(input.Progress) payload := map[string]any{ "task": "next_exercise", "user_id": input.UserID, "target_language": input.TargetLanguage, "cefr_level": input.CEFRLevel, "ui_language": input.UILanguage, "profile": input.Profile, "progress": progress, "recent_weak_words": withoutPhonemeScores(input.RecentWeakWords), "recent_weak_phonemes": input.Progress.WeakPhonemes, "preferred_type": valueOr(input.PreferredType, "repeat_sentence"), "avoid_reference_text": input.AvoidReferenceText, "avoid_reference_texts": input.AvoidReferenceTexts, "rules": "Generate one A1 English pronunciation exercise. Return valid JSON only with fields: exercise_type, target_language, cefr_level, reference_text, display_prompt, tts_text, focus_points, success_criteria, reason_for_choice. The reference_text must differ from every sentence in avoid_reference_texts. Use recent_weak_phonemes only when measured scores are provided; do not invent pronunciation errors.", } return f.askExercise(ctx, payload, input, fallback) } func compactProgressForFlowise(progress domain.ProgressSummary) domain.ProgressSummary { progress.WeakWords = withoutPhonemeScores(progress.WeakWords) recent := make([]domain.Attempt, len(progress.RecentAttempts)) for i, attempt := range progress.RecentAttempts { recent[i] = attempt recent[i].WordScores = withoutPhonemeScores(attempt.WordScores) } progress.RecentAttempts = recent return progress } func withoutPhonemeScores(words []domain.WordScore) []domain.WordScore { clean := make([]domain.WordScore, len(words)) copy(clean, words) for i := range clean { clean[i].PhonemeScores = nil } return clean } func (f *FlowiseTeacher) FeedbackForAttempt(ctx context.Context, targetText string, result domain.PronunciationResult, weakWords []domain.WordScore) (domain.TeacherResponse, error) { _ = ctx _ = weakWords return localizedFeedback(ctx, targetText, result), nil } func (f *FlowiseTeacher) StartConversation(ctx context.Context, targetLanguage, cefrLevel string) (domain.TeacherResponse, error) { _ = ctx _ = targetLanguage _ = cefrLevel response := domain.TeacherResponse{ ExerciseType: "conversation", TargetText: "Hello. What is your name?", TeacherFeedback: "Wir starten sehr einfach. Antworte mit: My name is ...", TTSText: "Hello. What is your name?", NextRecommendation: "Antworten: My name is ...", } if nativeLanguage(ctx) == "ru-RU" { response.TeacherFeedback = "Начнём с простого. Ответьте: My name is ..." response.NextRecommendation = "Ответьте: My name is ..." } return response, nil } func (f *FlowiseTeacher) ContinueConversation(ctx context.Context, targetLanguage, cefrLevel, userText string) (domain.TeacherResponse, error) { _ = ctx _ = targetLanguage _ = cefrLevel _ = userText response := domain.TeacherResponse{ ExerciseType: "conversation", TargetText: "Nice to meet you. Where are you from?", TeacherFeedback: "Gut. Jetzt uebe einen kurzen Satz mit Herkunft.", TTSText: "Nice to meet you. Where are you from?", NextRecommendation: "Antworten: I am from ...", } if nativeLanguage(ctx) == "ru-RU" { response.TeacherFeedback = "Теперь потренируйте короткое предложение о том, откуда вы." response.NextRecommendation = "Ответьте: I am from ..." } return response, nil } func (f *FlowiseTeacher) askExercise(ctx context.Context, payload map[string]any, input domain.GeneratedExerciseRequest, fallback domain.GeneratedExercise) (domain.GeneratedExercise, error) { if f.cfg.FlowiseChatflow == "" || f.cfg.FlowiseBaseURL == "" { return fallback, nil } body, _ := json.Marshal(payload) reqBody, _ := json.Marshal(map[string]any{ "question": string(body), "overrideConfig": map[string]any{ "sessionId": input.SessionID, }, }) endpoint := strings.TrimRight(f.cfg.FlowiseBaseURL, "/") + "/api/v1/prediction/" + f.cfg.FlowiseChatflow req, err := http.NewRequestWithContext(ctx, http.MethodPost, endpoint, bytes.NewReader(reqBody)) if err != nil { return fallback, err } req.Header.Set("Content-Type", "application/json") if f.cfg.FlowiseAPIKey != "" { req.Header.Set("Authorization", "Bearer "+f.cfg.FlowiseAPIKey) } resp, err := f.client.Do(req) if err != nil { f.logger.Warn("flowise exercise generation unavailable, using fallback", "error", err) return fallback, nil } defer resp.Body.Close() respBody, err := io.ReadAll(resp.Body) if err != nil { return fallback, err } if resp.StatusCode >= 300 { f.logger.Warn("flowise exercise generation returned error, using fallback", "status", resp.StatusCode, "body", string(respBody)) return fallback, nil } if exercise, ok := parseGeneratedExerciseEnvelope(respBody); ok { if reason := generatedExerciseValidationError(exercise, input); reason != "" { if strings.HasPrefix(reason, "reference_text repeats") && payload["retry_instruction"] == nil { f.logger.Info("flowise repeated a recent exercise, requesting another sentence") retryPayload := make(map[string]any, len(payload)+1) for key, value := range payload { retryPayload[key] = value } retryPayload["retry_instruction"] = "The previous reference_text was rejected because it repeats a recent exercise. Choose a different natural A1 sentence that is not in avoid_reference_texts. Keep the required JSON format." return f.askExercise(ctx, retryPayload, input, fallback) } f.logger.Warn("flowise exercise response failed validation", "reason", reason) return fallback, nil } exercise.ID = "" // Exercise IDs are assigned by the API, never by Flowise. exercise.Source = "flowise" return exercise, nil } f.logger.Warn("flowise exercise response not parseable, using fallback", "body", string(respBody)) return fallback, nil } func validGeneratedExercise(exercise domain.GeneratedExercise, input domain.GeneratedExerciseRequest) bool { return generatedExerciseValidationError(exercise, input) == "" } func generatedExerciseValidationError(exercise domain.GeneratedExercise, input domain.GeneratedExerciseRequest) string { if input.AvoidReferenceText != "" && sameReferenceText(exercise.ReferenceText, input.AvoidReferenceText) { return "reference_text repeats the previous exercise" } for _, previous := range input.AvoidReferenceTexts { if sameReferenceText(exercise.ReferenceText, previous) { return "reference_text repeats a recent exercise" } } if exercise.ExerciseType != "repeat_sentence" { return "unsupported exercise_type" } if exercise.TargetLanguage != input.TargetLanguage { return "target_language does not match the request" } if exercise.CEFRLevel != input.CEFRLevel { return "cefr_level does not match the request" } for _, field := range []struct { name string value string limit int }{ {"reference_text", exercise.ReferenceText, 160}, {"display_prompt", exercise.DisplayPrompt, 240}, {"tts_text", exercise.TTSText, 160}, {"reason_for_choice", exercise.ReasonForChoice, 300}, } { if strings.TrimSpace(field.value) == "" { return field.name + " is required and must not be blank" } if utf8.RuneCountInString(field.value) > field.limit { return fmt.Sprintf("%s exceeds maximum length of %d characters", field.name, field.limit) } if strings.IndexFunc(field.value, unicode.IsControl) != -1 { return field.name + " must be a single line without control characters" } } if len(exercise.FocusPoints) < 1 || len(exercise.FocusPoints) > 5 || len(exercise.SuccessCriteria) < 1 || len(exercise.SuccessCriteria) > 5 { return "focus_points or success_criteria has an invalid count" } for _, point := range exercise.FocusPoints { if !validExerciseText(point, 80) { return "focus_points contains an invalid value" } } for _, criterion := range exercise.SuccessCriteria { if !validExerciseText(criterion, 120) { return "success_criteria contains an invalid value" } } return "" } func sameReferenceText(a, b string) bool { return strings.EqualFold(strings.Join(strings.Fields(a), " "), strings.Join(strings.Fields(b), " ")) } func validExerciseText(value string, limit int) bool { return strings.TrimSpace(value) != "" && utf8.RuneCountInString(value) <= limit && strings.IndexFunc(value, unicode.IsControl) == -1 } func parseGeneratedExerciseEnvelope(body []byte) (domain.GeneratedExercise, bool) { var envelope map[string]json.RawMessage if err := json.Unmarshal(body, &envelope); err == nil { for _, key := range []string{"text", "json", "output"} { if raw := envelope[key]; len(raw) > 0 && string(raw) != "null" { if parsed, ok := parseGeneratedExerciseJSON(raw); ok { return parsed, true } } } } return parseGeneratedExercise(string(body)) } func parseGeneratedExercise(value string) (domain.GeneratedExercise, bool) { value = strings.TrimSpace(value) value = strings.TrimPrefix(value, "```json") value = strings.TrimPrefix(value, "```") value = strings.TrimSuffix(value, "```") var out domain.GeneratedExercise if err := json.Unmarshal([]byte(strings.TrimSpace(value)), &out); err != nil { return domain.GeneratedExercise{}, false } return out, strings.TrimSpace(out.ReferenceText) != "" } func parseGeneratedExerciseJSON(value json.RawMessage) (domain.GeneratedExercise, bool) { if parsed, ok := parseGeneratedExercise(string(value)); ok { return parsed, true } var text string if err := json.Unmarshal(value, &text); err != nil { return domain.GeneratedExercise{}, false } return parseGeneratedExercise(text) } func mockFeedback(targetText string, result domain.PronunciationResult) domain.TeacherResponse { weakWord := "" weakPhoneme := domain.PhonemeScore{} weakPhonemeWord := "" for _, word := range result.WordScores { if word.Highlight == "weak" { if weakWord == "" { weakWord = word.Word } } if strings.EqualFold(word.ErrorType, "Omission") { continue } for _, phoneme := range word.PhonemeScores { if phoneme.Accuracy < 75 && (weakPhonemeWord == "" || phoneme.Accuracy < weakPhoneme.Accuracy) { weakPhoneme = phoneme weakPhonemeWord = word.Word } } } feedback := "Der Satz braucht noch etwas Übung. Sprich ihn noch einmal nach." nextRecommendation := "Wiederhole diese Übung." switch { case result.OverallScore >= 95 && result.AccuracyScore >= 95 && result.FluencyScore >= 95 && result.CompletenessScore >= 95: feedback = "Ausgezeichnet gesprochen! Die Aussprache dieses Satzes wurde sehr hoch bewertet." nextRecommendation = "Du kannst mit einer neuen Übung weitermachen." case weakPhonemeWord != "": feedback = fmt.Sprintf("Im Wort %q wurde der Laut /%s/ mit %.0f von 100 Punkten bewertet.", weakPhonemeWord, weakPhoneme.Phoneme, weakPhoneme.Accuracy) nextRecommendation = fmt.Sprintf("Wiederhole den Satz und achte besonders auf %q.", weakPhonemeWord) case weakWord != "": feedback = fmt.Sprintf("Das Wort %q wurde noch unsicher bewertet. Übe es im Satz noch einmal.", weakWord) nextRecommendation = fmt.Sprintf("Wiederhole den Satz und achte besonders auf %q.", weakWord) case result.OverallScore >= 85: feedback = "Gut gesprochen! Die Aussprache dieses Satzes wurde hoch bewertet." nextRecommendation = "Du kannst mit einer neuen Übung weitermachen." } return domain.TeacherResponse{ ExerciseType: "repeat_sentence", TargetText: targetText, TeacherFeedback: feedback, TTSText: targetText, NextRecommendation: nextRecommendation, } }