Flowise-Übungen stabilisieren und Lernfortschritt korrigieren

Vermeide kürzlich angezeigte Sätze bei neuen Übungen und frage Flowise bei Wiederholungen einmal erneut. Validiere strukturierte Antworten, protokolliere die Übungsquelle und schütze nutzerspezifische Übungs-IDs.

Berechne schwierige Wörter anhand der neuesten Aussprache pro Wort. Passe das Lehrerfeedback an gute Bewertungen an und verbessere das Laden neuer Übungen im Web. Ergänze gezielte Go-Tests.
This commit is contained in:
Eugenius Naumenko
2026-10-07 20:52:02 +00:00
parent 74a4caa1c6
commit bac840e091
11 changed files with 572 additions and 119 deletions
+112 -36
View File
@@ -10,6 +10,8 @@ import (
"net/http"
"strings"
"time"
"unicode"
"unicode/utf8"
"speech-learning-api/internal/config"
"speech-learning-api/internal/domain"
@@ -53,18 +55,20 @@ func (f *FlowiseTeacher) NextExercise(ctx context.Context, input domain.Generate
Source: "fallback",
}
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": input.Progress,
"recent_weak_words": input.RecentWeakWords,
"preferred_type": valueOr(input.PreferredType, "repeat_sentence"),
"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.",
"task": "next_exercise",
"user_id": input.UserID,
"target_language": input.TargetLanguage,
"cefr_level": input.CEFRLevel,
"ui_language": input.UILanguage,
"profile": input.Profile,
"progress": input.Progress,
"recent_weak_words": input.RecentWeakWords,
"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. The same target word may still be used.",
}
return f.askExercise(ctx, payload, input.SessionID, fallback)
return f.askExercise(ctx, payload, input, fallback)
}
func (f *FlowiseTeacher) FeedbackForAttempt(ctx context.Context, targetText string, result domain.PronunciationResult, weakWords []domain.WordScore) (domain.TeacherResponse, error) {
@@ -100,7 +104,7 @@ func (f *FlowiseTeacher) ContinueConversation(ctx context.Context, targetLanguag
}, nil
}
func (f *FlowiseTeacher) askExercise(ctx context.Context, payload any, sessionID string, fallback domain.GeneratedExercise) (domain.GeneratedExercise, error) {
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
}
@@ -108,7 +112,7 @@ func (f *FlowiseTeacher) askExercise(ctx context.Context, payload any, sessionID
reqBody, _ := json.Marshal(map[string]any{
"question": string(body),
"overrideConfig": map[string]any{
"sessionId": sessionID,
"sessionId": input.SessionID,
},
})
endpoint := strings.TrimRight(f.cfg.FlowiseBaseURL, "/") + "/api/v1/prediction/" + f.cfg.FlowiseChatflow
@@ -137,11 +141,20 @@ func (f *FlowiseTeacher) askExercise(ctx context.Context, payload any, sessionID
return fallback, nil
}
if exercise, ok := parseGeneratedExerciseEnvelope(respBody); ok {
exercise.TargetLanguage = valueOr(exercise.TargetLanguage, fallback.TargetLanguage)
exercise.CEFRLevel = valueOr(exercise.CEFRLevel, fallback.CEFRLevel)
exercise.ExerciseType = valueOr(exercise.ExerciseType, fallback.ExerciseType)
exercise.DisplayPrompt = valueOr(exercise.DisplayPrompt, fallback.DisplayPrompt)
exercise.TTSText = valueOr(exercise.TTSText, exercise.ReferenceText)
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
}
@@ -149,20 +162,74 @@ func (f *FlowiseTeacher) askExercise(ctx context.Context, payload any, sessionID
return fallback, nil
}
func parseGeneratedExerciseEnvelope(body []byte) (domain.GeneratedExercise, bool) {
var envelope struct {
Text string `json:"text"`
JSON json.RawMessage `json:"json"`
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"
}
if err := json.Unmarshal(body, &envelope); err == nil {
if envelope.Text != "" {
if parsed, ok := parseGeneratedExercise(envelope.Text); ok {
return parsed, true
}
for _, previous := range input.AvoidReferenceTexts {
if sameReferenceText(exercise.ReferenceText, previous) {
return "reference_text repeats a recent exercise"
}
if len(envelope.JSON) > 0 && string(envelope.JSON) != "null" {
if parsed, ok := parseGeneratedExerciseJSON(envelope.JSON); ok {
return parsed, true
}
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 !validExerciseText(field.value, field.limit) {
return field.name + " is missing or invalid"
}
}
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
}
}
}
}
@@ -193,22 +260,31 @@ func parseGeneratedExerciseJSON(value json.RawMessage) (domain.GeneratedExercise
}
func mockFeedback(targetText string, result domain.PronunciationResult) domain.TeacherResponse {
weak := "den roten Woertern"
weakWord := ""
for _, word := range result.WordScores {
if word.Highlight == "weak" {
weak = fmt.Sprintf("'%s'", word.Word)
weakWord = word.Word
break
}
}
feedback := fmt.Sprintf("Guter Versuch. Uebe jetzt besonders %s. Sprich langsam und halte die Endlaute klar.", weak)
if result.OverallScore >= 85 {
feedback = "Sehr solide. Wiederhole den Satz einmal etwas natuerlicher und mit ruhigem Rhythmus."
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 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: "Noch einmal sprechen und auf die markierten Woerter achten.",
NextRecommendation: nextRecommendation,
}
}
+180 -4
View File
@@ -7,12 +7,38 @@ import (
"log/slog"
"net/http"
"net/http/httptest"
"strings"
"testing"
"speech-learning-api/internal/config"
"speech-learning-api/internal/domain"
)
func TestFeedbackForPerfectPronunciationRecommendsNextExercise(t *testing.T) {
result := domain.PronunciationResult{
OverallScore: 100, AccuracyScore: 100, FluencyScore: 100, CompletenessScore: 100,
WordScores: []domain.WordScore{{Word: "water", Accuracy: 100, Highlight: "good"}},
}
feedback := mockFeedback("I drink water.", result)
if strings.Contains(feedback.TeacherFeedback, "noch einmal") || strings.Contains(feedback.NextRecommendation, "Wiederhole") {
t.Fatalf("perfect pronunciation should not require repetition: %#v", feedback)
}
if !strings.Contains(feedback.NextRecommendation, "neuen Übung") {
t.Fatalf("expected recommendation to continue: %#v", feedback)
}
}
func TestFeedbackForWeakWordNamesObservedProblem(t *testing.T) {
result := domain.PronunciationResult{
OverallScore: 78,
WordScores: []domain.WordScore{{Word: "water", Accuracy: 61, Highlight: "weak"}},
}
feedback := mockFeedback("I drink water.", result)
if !strings.Contains(feedback.TeacherFeedback, "water") || !strings.Contains(feedback.NextRecommendation, "Wiederhole") {
t.Fatalf("expected focused repetition: %#v", feedback)
}
}
func TestFlowiseNextExerciseSendsSessionAndParsesResponse(t *testing.T) {
var requestBody map[string]json.RawMessage
@@ -25,6 +51,7 @@ func TestFlowiseNextExerciseSendsSessionAndParsesResponse(t *testing.T) {
}
response := domain.GeneratedExercise{
ID: "flowise-controlled-id",
ExerciseType: "repeat_sentence",
TargetLanguage: "en-US",
CEFRLevel: "A1",
@@ -51,10 +78,12 @@ func TestFlowiseNextExerciseSendsSessionAndParsesResponse(t *testing.T) {
}, slog.New(slog.NewTextHandler(io.Discard, nil)))
exercise, err := teacher.NextExercise(context.Background(), domain.GeneratedExerciseRequest{
UserID: "usr_1",
TargetLanguage: "en-US",
CEFRLevel: "A1",
SessionID: "usr_1:en-US:practice",
UserID: "usr_1",
TargetLanguage: "en-US",
CEFRLevel: "A1",
SessionID: "usr_1:en-US:practice",
AvoidReferenceText: "I would like some water.",
AvoidReferenceTexts: []string{"Can I have some water, please?", "I would like some water."},
})
if err != nil {
t.Fatalf("NextExercise: %v", err)
@@ -65,6 +94,9 @@ func TestFlowiseNextExerciseSendsSessionAndParsesResponse(t *testing.T) {
if exercise.Source != "flowise" {
t.Fatalf("unexpected source %q", exercise.Source)
}
if exercise.ID != "" {
t.Fatalf("Flowise must not assign exercise IDs, got %q", exercise.ID)
}
var override struct {
SessionID string `json:"sessionId"`
@@ -90,6 +122,142 @@ func TestFlowiseNextExerciseSendsSessionAndParsesResponse(t *testing.T) {
if question["task"] != "next_exercise" {
t.Fatalf("unexpected task %#v", question["task"])
}
if question["avoid_reference_text"] != "I would like some water." {
t.Fatalf("unexpected avoid_reference_text %#v", question["avoid_reference_text"])
}
if texts, ok := question["avoid_reference_texts"].([]any); !ok || len(texts) != 2 {
t.Fatalf("unexpected avoid_reference_texts %#v", question["avoid_reference_texts"])
}
}
func TestValidGeneratedExerciseRejectsEarlierRecentSentence(t *testing.T) {
exercise := domain.GeneratedExercise{
ExerciseType: "repeat_sentence", TargetLanguage: "en-US", CEFRLevel: "A1",
ReferenceText: "Can I have some water, please?", DisplayPrompt: "Sprich den Satz nach.",
TTSText: "Can I have some water, please?", FocusPoints: []string{"water"},
SuccessCriteria: []string{"Sprich den Satz verständlich nach."}, ReasonForChoice: "Übung mit water.",
}
input := domain.GeneratedExerciseRequest{
TargetLanguage: "en-US", CEFRLevel: "A1",
AvoidReferenceTexts: []string{"Can I have some water, please?", "I would like some water."},
}
if validGeneratedExercise(exercise, input) {
t.Fatal("an earlier recent sentence was accepted")
}
exercise.ReferenceText = "Please pass me the water."
exercise.TTSText = exercise.ReferenceText
if !validGeneratedExercise(exercise, input) {
t.Fatal("a new sentence was rejected")
}
}
func TestFlowiseNextExerciseRetriesRepeatedSentence(t *testing.T) {
calls := 0
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
calls++
var request struct {
Question string `json:"question"`
}
if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
t.Errorf("decode request: %v", err)
return
}
var question map[string]any
if err := json.Unmarshal([]byte(request.Question), &question); err != nil {
t.Errorf("decode question: %v", err)
return
}
if calls == 2 && question["retry_instruction"] == nil {
t.Error("second request lacks retry instruction")
}
reference := "Can I have some water, please?"
if calls == 2 {
reference = "I drink water every day."
}
response := domain.GeneratedExercise{
ExerciseType: "repeat_sentence", TargetLanguage: "en-US", CEFRLevel: "A1",
ReferenceText: reference, DisplayPrompt: "Sprich den Satz nach.", TTSText: reference,
FocusPoints: []string{"water"}, SuccessCriteria: []string{"Sprich den Satz verständlich nach."},
ReasonForChoice: "Übt das Wort water.",
}
_ = json.NewEncoder(w).Encode(response)
}))
defer server.Close()
teacher := NewFlowiseTeacher(config.Config{FlowiseBaseURL: server.URL, FlowiseChatflow: "chatflow-id"}, slog.New(slog.NewTextHandler(io.Discard, nil)))
exercise, err := teacher.NextExercise(context.Background(), domain.GeneratedExerciseRequest{
TargetLanguage: "en-US", CEFRLevel: "A1", AvoidReferenceTexts: []string{"Can I have some water, please?"},
})
if err != nil {
t.Fatalf("NextExercise: %v", err)
}
if calls != 2 || exercise.Source != "flowise" || exercise.ReferenceText != "I drink water every day." {
t.Fatalf("expected a new Flowise sentence after one retry, got calls=%d exercise=%#v", calls, exercise)
}
}
func TestFlowiseNextExerciseRejectsInvalidResponse(t *testing.T) {
valid := domain.GeneratedExercise{
ExerciseType: "repeat_sentence",
TargetLanguage: "en-US",
CEFRLevel: "A1",
ReferenceText: "Can I have water, please?",
DisplayPrompt: "Sprich den Satz nach.",
TTSText: "Can I have water, please?",
FocusPoints: []string{"water"},
SuccessCriteria: []string{"clear final sounds"},
ReasonForChoice: "Practice a weak word.",
}
tests := []struct {
name string
change func(*domain.GeneratedExercise)
}{
{"unsupported type", func(e *domain.GeneratedExercise) { e.ExerciseType = "short_dialogue" }},
{"wrong language", func(e *domain.GeneratedExercise) { e.TargetLanguage = "es-ES" }},
{"wrong level", func(e *domain.GeneratedExercise) { e.CEFRLevel = "B2" }},
{"empty reference", func(e *domain.GeneratedExercise) { e.ReferenceText = "" }},
{"empty prompt", func(e *domain.GeneratedExercise) { e.DisplayPrompt = "" }},
{"control character", func(e *domain.GeneratedExercise) { e.ReferenceText = "Hello\nWorld" }},
{"missing focus", func(e *domain.GeneratedExercise) { e.FocusPoints = nil }},
{"same previous sentence", func(e *domain.GeneratedExercise) { e.ReferenceText = " can I HAVE water, please? " }},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
response := valid
tt.change(&response)
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if err := json.NewEncoder(w).Encode(response); err != nil {
t.Errorf("encode response: %v", err)
}
}))
defer server.Close()
teacher := NewFlowiseTeacher(config.Config{FlowiseBaseURL: server.URL, FlowiseChatflow: "chatflow-id"}, slog.New(slog.NewTextHandler(io.Discard, nil)))
exercise, err := teacher.NextExercise(context.Background(), domain.GeneratedExerciseRequest{TargetLanguage: "en-US", CEFRLevel: "A1", AvoidReferenceText: "Can I have water, please?"})
if err != nil {
t.Fatalf("NextExercise: %v", err)
}
if exercise.Source != "fallback" {
t.Fatalf("invalid response was accepted: %#v", exercise)
}
})
}
}
func TestFlowiseNextExerciseUsesFallbackOnServerError(t *testing.T) {
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.WriteHeader(http.StatusServiceUnavailable)
}))
defer server.Close()
teacher := NewFlowiseTeacher(config.Config{FlowiseBaseURL: server.URL, FlowiseChatflow: "chatflow-id"}, slog.New(slog.NewTextHandler(io.Discard, nil)))
exercise, err := teacher.NextExercise(context.Background(), domain.GeneratedExerciseRequest{TargetLanguage: "en-US", CEFRLevel: "A1"})
if err != nil {
t.Fatalf("NextExercise: %v", err)
}
if exercise.Source != "fallback" {
t.Fatalf("server error did not use fallback: %#v", exercise)
}
}
func TestParseGeneratedExerciseEnvelope(t *testing.T) {
@@ -106,3 +274,11 @@ func TestParseGeneratedExerciseEnvelope(t *testing.T) {
t.Fatalf("unexpected focus points %#v", exercise.FocusPoints)
}
}
func TestParseGeneratedExerciseEnvelopeWithStructuredText(t *testing.T) {
body := []byte(`{"text":{"exercise_type":"repeat_sentence","target_language":"en-US","cefr_level":"A1","reference_text":"Please pass me the water.","display_prompt":"Sprich den Satz nach.","tts_text":"Please pass me the water.","focus_points":["water"],"success_criteria":["Sprich den Satz verständlich nach."],"reason_for_choice":"Übt ein Alltagswort."}}`)
exercise, ok := parseGeneratedExerciseEnvelope(body)
if !ok || exercise.ReferenceText != "Please pass me the water." {
t.Fatalf("structured Flowise text was not parsed: %#v, %v", exercise, ok)
}
}