Files
Eugenius Naumenko 16cceae28a Muttersprache koppeln und russischen A1-Kurs ergänzen
GUI und neue Erklärungen verwenden gemeinsam native_language. Deutsch und
Russisch sind die beiden Muttersprachen; Englisch bleibt die Lernsprache.
Kompatibilitätsfelder werden atomar gekoppelt, widersprüchliche Eingaben
abgewiesen und bestehende Profile sowie eingefrorene Inhalte erhalten.

Ergänzt vollständige russische GUI-Kataloge und 840 geprüfte Aufgabenansichten
in sieben Modulen einschließlich A1-Test, mit getrennten Sprachrollen für
Ausgangs- und Lernmaterial. Äquivalente Ansichten teilen ihre Nachweisidentität.
Stabile API-Fehlercodes, neue deterministische Hilfen und Trainingsbegründungen
berücksichtigen die Muttersprache. Dokumentiert das Sprachmodell in AGENTS.md.

Validierung: Go-Race-Suite mit eigener lokaler PostgreSQL-Testdatenbank, go vet,
Web-Build, Offline-Bank-/Variantenaudit, Diff-Prüfung sowie lokale Browser-Smokes
für Sprachen, Kurs, Administration, Aussprache und Aufnahme. Keine Live-Anbieter,
Produktionsprofile, Deployment-Schritte oder historischen Neubewertungen.
2026-11-07 17:02:17 +00:00

350 lines
14 KiB
Go

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,
}
}