Compare commits

..
2 Commits
Author SHA1 Message Date
Eugenius Naumenko bac840e091 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.
2026-10-07 20:52:02 +00:00
Eugenius Naumenko 74a4caa1c6 änderungen von vorherigen Codexnutzung: sollte den Agent lassen die Aufgaben zu erzeugen 2026-09-22 16:14:41 +00:00
18 changed files with 955 additions and 284 deletions
+1
View File
@@ -19,6 +19,7 @@ AZURE_SPEECH_REGION=
AZURE_ENABLE_MOCK=true
FLOWISE_BASE_URL=http://flowise:3000
# When set, Flowise generates the next exercise before the API falls back to seed data.
FLOWISE_CHATFLOW_ID=
FLOWISE_API_KEY=
+29
View File
@@ -45,6 +45,7 @@ type Exercise struct {
PromptText string `json:"prompt_text"`
TargetText string `json:"target_text"`
Difficulty int `json:"difficulty"`
Source string `json:"source,omitempty"`
}
type WordScore struct {
@@ -90,6 +91,34 @@ type ProgressSummary struct {
DailyGoalMinutes int `json:"daily_goal_minutes"`
}
type GeneratedExerciseRequest struct {
UserID string `json:"user_id"`
Profile LearnerProfile `json:"profile"`
Progress ProgressSummary `json:"progress"`
TargetLanguage string `json:"target_language"`
CEFRLevel string `json:"cefr_level"`
UILanguage string `json:"ui_language"`
SessionID string `json:"session_id"`
RecentWeakWords []WordScore `json:"recent_weak_words"`
PreferredType string `json:"preferred_type"`
AvoidReferenceText string `json:"avoid_reference_text,omitempty"`
AvoidReferenceTexts []string `json:"avoid_reference_texts,omitempty"`
}
type GeneratedExercise struct {
ID string `json:"exercise_id"`
ExerciseType string `json:"exercise_type"`
TargetLanguage string `json:"target_language"`
CEFRLevel string `json:"cefr_level"`
ReferenceText string `json:"reference_text"`
DisplayPrompt string `json:"display_prompt"`
TTSText string `json:"tts_text"`
FocusPoints []string `json:"focus_points"`
SuccessCriteria []string `json:"success_criteria"`
ReasonForChoice string `json:"reason_for_choice"`
Source string `json:"source"`
}
type Dashboard struct {
User User `json:"user"`
Profile LearnerProfile `json:"profile"`
+87 -6
View File
@@ -21,8 +21,9 @@ type DataStore interface {
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) (domain.Lesson, domain.Exercise, error)
GetExercise(ctx context.Context, id string) (domain.Exercise, 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)
SaveAttempt(ctx context.Context, attempt domain.Attempt) (domain.Attempt, error)
Progress(ctx context.Context, userID string, limit int) (domain.ProgressSummary, error)
CreateConversationSession(ctx context.Context, userID, targetLanguage, cefrLevel string) (domain.ConversationSession, error)
@@ -189,7 +190,7 @@ func (s *Server) dashboard(w http.ResponseWriter, r *http.Request) {
writeError(w, http.StatusInternalServerError, err)
return
}
lesson, exercise, err := s.store.NextLessonAndExercise(r.Context(), profile)
lesson, exercise, err := s.nextAgentExercise(r.Context(), user, profile, progress, nil)
if err != nil {
writeError(w, http.StatusNotFound, err)
return
@@ -209,12 +210,48 @@ func (s *Server) progress(w http.ResponseWriter, r *http.Request) {
}
func (s *Server) nextLesson(w http.ResponseWriter, r *http.Request) {
profile, err := s.store.GetPrimaryProfile(r.Context(), currentUserID(r))
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
}
lesson, exercise, err := s.store.NextLessonAndExercise(r.Context(), profile)
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
@@ -222,13 +259,49 @@ func (s *Server) nextLesson(w http.ResponseWriter, r *http.Request) {
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) {
avoidReferenceText := ""
if len(avoidReferenceTexts) > 0 {
avoidReferenceText = avoidReferenceTexts[len(avoidReferenceTexts)-1]
}
generated, err := s.teacher.NextExercise(ctx, domain.GeneratedExerciseRequest{
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" && strings.TrimSpace(generated.ReferenceText) != "" {
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("flowise next exercise failed, using seed fallback", "error", err)
}
lesson, exercise, err := s.store.NextLessonAndExercise(ctx, profile, avoidReferenceTexts...)
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) 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)
exercise, err := s.store.GetExercise(r.Context(), exerciseID, currentUserID(r))
if err != nil {
writeError(w, http.StatusNotFound, err)
return
@@ -372,6 +445,14 @@ func firstNonEmpty(values ...string) string {
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
+69
View File
@@ -0,0 +1,69 @@
package httpapi
import (
"bytes"
"context"
"mime/multipart"
"net/http"
"net/http/httptest"
"testing"
"speech-learning-api/internal/domain"
"speech-learning-api/internal/store"
)
type exerciseLookupStore struct {
DataStore
exerciseID string
userID string
}
func (s *exerciseLookupStore) GetExercise(_ context.Context, exerciseID, userID string) (domain.Exercise, error) {
s.exerciseID = exerciseID
s.userID = userID
return domain.Exercise{}, store.ErrNotFound
}
func TestCreateAttemptScopesExerciseLookupToCurrentUser(t *testing.T) {
var body bytes.Buffer
form := multipart.NewWriter(&body)
if err := form.WriteField("exercise_id", "ex_other_user"); err != nil {
t.Fatal(err)
}
if err := form.Close(); err != nil {
t.Fatal(err)
}
req := httptest.NewRequest(http.MethodPost, "/practice/attempts", &body)
req.Header.Set("Content-Type", form.FormDataContentType())
req = req.WithContext(context.WithValue(req.Context(), userIDKey, "usr_current"))
recorder := httptest.NewRecorder()
lookup := &exerciseLookupStore{}
server := &Server{store: lookup}
server.createAttempt(recorder, req)
if recorder.Code != http.StatusNotFound {
t.Fatalf("status = %d, want 404", recorder.Code)
}
if lookup.exerciseID != "ex_other_user" || lookup.userID != "usr_current" {
t.Fatalf("lookup used exercise %q and user %q", lookup.exerciseID, lookup.userID)
}
}
func TestNextLessonScopesPreviousExerciseToCurrentUser(t *testing.T) {
req := httptest.NewRequest(http.MethodPost, "/lessons/next", bytes.NewBufferString(`{"previous_exercise_id":"ex_other_user"}`))
req = req.WithContext(context.WithValue(req.Context(), userIDKey, "usr_current"))
recorder := httptest.NewRecorder()
lookup := &exerciseLookupStore{}
server := &Server{store: lookup}
server.nextLesson(recorder, req)
if recorder.Code != http.StatusNotFound {
t.Fatalf("status = %d, want 404", recorder.Code)
}
if lookup.exerciseID != "ex_other_user" || lookup.userID != "usr_current" {
t.Fatalf("lookup used exercise %q and user %q", lookup.exerciseID, lookup.userID)
}
}
+171 -68
View File
@@ -10,12 +10,15 @@ import (
"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)
@@ -37,59 +40,80 @@ func NewFlowiseTeacher(cfg config.Config, logger *slog.Logger) *FlowiseTeacher {
}
}
func (f *FlowiseTeacher) FeedbackForAttempt(ctx context.Context, targetText string, result domain.PronunciationResult, weakWords []domain.WordScore) (domain.TeacherResponse, error) {
prompt := map[string]any{
"task": "practice_feedback",
"target_text": targetText,
"recognized_text": result.RecognizedText,
"scores": result,
"weak_words": weakWords,
"rules": "Answer in German. A1 learner. Max two corrections. Return valid JSON only.",
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",
}
return f.ask(ctx, prompt, mockFeedback(targetText, result))
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"),
"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, fallback)
}
func (f *FlowiseTeacher) FeedbackForAttempt(ctx context.Context, targetText string, result domain.PronunciationResult, weakWords []domain.WordScore) (domain.TeacherResponse, error) {
_ = ctx
_ = weakWords
return mockFeedback(targetText, result), nil
}
func (f *FlowiseTeacher) StartConversation(ctx context.Context, targetLanguage, cefrLevel string) (domain.TeacherResponse, error) {
prompt := map[string]any{
"task": "start_conversation",
"target_language": targetLanguage,
"cefr_level": cefrLevel,
"rules": "Create a simple A1 roleplay. Return valid JSON only.",
}
return f.ask(ctx, prompt, domain.TeacherResponse{
_ = ctx
_ = targetLanguage
_ = cefrLevel
return 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 ...",
})
}, nil
}
func (f *FlowiseTeacher) ContinueConversation(ctx context.Context, targetLanguage, cefrLevel, userText string) (domain.TeacherResponse, error) {
prompt := map[string]any{
"task": "continue_conversation",
"target_language": targetLanguage,
"cefr_level": cefrLevel,
"user_text": userText,
"rules": "Continue a simple A1 conversation. Return valid JSON only.",
}
return f.ask(ctx, prompt, domain.TeacherResponse{
_ = ctx
_ = targetLanguage
_ = cefrLevel
_ = userText
return 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 ...",
})
}, nil
}
func (f *FlowiseTeacher) ask(ctx context.Context, payload any, fallback domain.TeacherResponse) (domain.TeacherResponse, 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
}
body, _ := json.Marshal(payload)
question := string(body)
reqBody, _ := json.Marshal(map[string]any{
"question": question,
"question": string(body),
"overrideConfig": map[string]any{
"sessionId": input.SessionID,
},
})
endpoint := strings.TrimRight(f.cfg.FlowiseBaseURL, "/") + "/api/v1/prediction/" + f.cfg.FlowiseChatflow
@@ -104,7 +128,7 @@ func (f *FlowiseTeacher) ask(ctx context.Context, payload any, fallback domain.T
resp, err := f.client.Do(req)
if err != nil {
f.logger.Warn("flowise unavailable, using fallback", "error", err)
f.logger.Warn("flowise exercise generation unavailable, using fallback", "error", err)
return fallback, nil
}
defer resp.Body.Close()
@@ -113,75 +137,154 @@ func (f *FlowiseTeacher) ask(ctx context.Context, payload any, fallback domain.T
return fallback, err
}
if resp.StatusCode >= 300 {
f.logger.Warn("flowise returned error, using fallback", "status", resp.StatusCode, "body", string(respBody))
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
}
var envelope struct {
Text string `json:"text"`
JSON json.RawMessage `json:"json"`
}
if err := json.Unmarshal(respBody, &envelope); err == nil {
if envelope.Text != "" {
if parsed, ok := parseTeacherResponse(envelope.Text); ok {
return parsed, nil
}
fallback.TeacherFeedback = envelope.Text
return fallback, nil
}
if len(envelope.JSON) > 0 && string(envelope.JSON) != "null" {
if parsed, ok := parseTeacherResponseJSON(envelope.JSON); ok {
return parsed, nil
}
}
}
if parsed, ok := parseTeacherResponse(string(respBody)); ok {
return parsed, nil
}
f.logger.Warn("flowise 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 parseTeacherResponse(value string) (domain.TeacherResponse, bool) {
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 !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
}
}
}
}
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.TeacherResponse
var out domain.GeneratedExercise
if err := json.Unmarshal([]byte(strings.TrimSpace(value)), &out); err != nil {
return domain.TeacherResponse{}, false
return domain.GeneratedExercise{}, false
}
return out, out.TeacherFeedback != "" || out.TargetText != "" || out.TTSText != ""
return out, strings.TrimSpace(out.ReferenceText) != ""
}
func parseTeacherResponseJSON(value json.RawMessage) (domain.TeacherResponse, bool) {
if parsed, ok := parseTeacherResponse(string(value)); ok {
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.TeacherResponse{}, false
return domain.GeneratedExercise{}, false
}
return parseTeacherResponse(text)
return parseGeneratedExercise(text)
}
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,
}
}
+228 -59
View File
@@ -7,79 +7,60 @@ import (
"log/slog"
"net/http"
"net/http/httptest"
"strings"
"testing"
"speech-learning-api/internal/config"
"speech-learning-api/internal/domain"
)
func TestParseTeacherResponse(t *testing.T) {
response, ok := parseTeacherResponse(`{
"exercise_type": "repeat_sentence",
"target_text": "Hello.",
"teacher_feedback": "Gut.",
"tts_text": "Hello.",
"ssml": "",
"next_recommendation": "Noch einmal."
}`)
if !ok {
t.Fatal("expected response to parse")
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"}},
}
if response.TargetText != "Hello." {
t.Fatalf("unexpected target text %q", response.TargetText)
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 TestParseTeacherResponseJSONFromObject(t *testing.T) {
response, ok := parseTeacherResponseJSON(json.RawMessage(`{
"exercise_type": "repeat_sentence",
"target_text": "Hello.",
"teacher_feedback": "Gut.",
"tts_text": "Hello.",
"ssml": "",
"next_recommendation": "Noch einmal."
}`))
if !ok {
t.Fatal("expected response to parse")
func TestFeedbackForWeakWordNamesObservedProblem(t *testing.T) {
result := domain.PronunciationResult{
OverallScore: 78,
WordScores: []domain.WordScore{{Word: "water", Accuracy: 61, Highlight: "weak"}},
}
if response.TeacherFeedback != "Gut." {
t.Fatalf("unexpected feedback %q", response.TeacherFeedback)
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 TestParseTeacherResponseJSONFromString(t *testing.T) {
response, ok := parseTeacherResponseJSON(json.RawMessage(`"{\"exercise_type\":\"repeat_sentence\",\"target_text\":\"Hello.\",\"teacher_feedback\":\"Gut.\",\"tts_text\":\"Hello.\",\"ssml\":\"\",\"next_recommendation\":\"Noch einmal.\"}"`))
if !ok {
t.Fatal("expected response to parse")
}
if response.NextRecommendation != "Noch einmal." {
t.Fatalf("unexpected recommendation %q", response.NextRecommendation)
}
}
func TestFlowiseAskSendsQuestionOnly(t *testing.T) {
func TestFlowiseNextExerciseSendsSessionAndParsesResponse(t *testing.T) {
var requestBody map[string]json.RawMessage
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.URL.Path != "/api/v1/prediction/chatflow-id" {
t.Fatalf("unexpected path %q", r.URL.Path)
}
if r.Header.Get("Authorization") != "Bearer api-key" {
t.Fatalf("unexpected authorization header %q", r.Header.Get("Authorization"))
}
if err := json.NewDecoder(r.Body).Decode(&requestBody); err != nil {
t.Fatalf("decode request body: %v", err)
}
response := domain.TeacherResponse{
ExerciseType: "conversation",
TargetText: "Hello.",
TeacherFeedback: "Gut.",
TTSText: "Hello.",
NextRecommendation: "Noch einmal.",
response := domain.GeneratedExercise{
ID: "flowise-controlled-id",
ExerciseType: "repeat_sentence",
TargetLanguage: "en-US",
CEFRLevel: "A1",
ReferenceText: "I live in Berlin.",
DisplayPrompt: "Sprich den Satz klar nach.",
TTSText: "I live in Berlin.",
FocusPoints: []string{"live"},
SuccessCriteria: []string{"accuracy above 80"},
ReasonForChoice: "Uebt einen kurzen A1-Satz.",
}
responseText, err := json.Marshal(response)
if err != nil {
@@ -94,22 +75,210 @@ func TestFlowiseAskSendsQuestionOnly(t *testing.T) {
teacher := NewFlowiseTeacher(config.Config{
FlowiseBaseURL: server.URL,
FlowiseChatflow: "chatflow-id",
FlowiseAPIKey: "api-key",
}, slog.New(slog.NewTextHandler(io.Discard, nil)))
response, err := teacher.ask(context.Background(), map[string]any{"task": "start_conversation"}, domain.TeacherResponse{
TeacherFeedback: "fallback",
exercise, err := teacher.NextExercise(context.Background(), domain.GeneratedExerciseRequest{
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("ask: %v", err)
t.Fatalf("NextExercise: %v", err)
}
if response.TeacherFeedback != "Gut." {
t.Fatalf("unexpected feedback %q", response.TeacherFeedback)
if exercise.ReferenceText != "I live in Berlin." {
t.Fatalf("unexpected reference text %q", exercise.ReferenceText)
}
if _, ok := requestBody["question"]; !ok {
t.Fatal("expected question in request body")
if exercise.Source != "flowise" {
t.Fatalf("unexpected source %q", exercise.Source)
}
if _, ok := requestBody["form"]; ok {
t.Fatal("did not expect form in request body")
if exercise.ID != "" {
t.Fatalf("Flowise must not assign exercise IDs, got %q", exercise.ID)
}
var override struct {
SessionID string `json:"sessionId"`
}
if err := json.Unmarshal(requestBody["overrideConfig"], &override); err != nil {
t.Fatalf("decode overrideConfig: %v", err)
}
if override.SessionID != "usr_1:en-US:practice" {
t.Fatalf("unexpected sessionId %q", override.SessionID)
}
var question map[string]any
if err := json.Unmarshal(requestBody["question"], &question); err == nil {
t.Fatalf("expected question to be a JSON string, got object %#v", question)
}
var questionText string
if err := json.Unmarshal(requestBody["question"], &questionText); err != nil {
t.Fatalf("decode question text: %v", err)
}
if err := json.Unmarshal([]byte(questionText), &question); err != nil {
t.Fatalf("decode question payload: %v", err)
}
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) {
body := []byte(`{"text":"{\"exercise_type\":\"repeat_sentence\",\"target_language\":\"en-US\",\"cefr_level\":\"A1\",\"reference_text\":\"I live in Berlin.\",\"display_prompt\":\"Sprich den Satz klar nach.\",\"tts_text\":\"I live in Berlin.\",\"focus_points\":[\"live\"],\"success_criteria\":[\"accuracy above 80\"],\"reason_for_choice\":\"Practise /l/.\"}"}`)
exercise, ok := parseGeneratedExerciseEnvelope(body)
if !ok {
t.Fatal("expected generated exercise to parse")
}
if exercise.ReferenceText != "I live in Berlin." {
t.Fatalf("unexpected reference text %q", exercise.ReferenceText)
}
if len(exercise.FocusPoints) != 1 || exercise.FocusPoints[0] != "live" {
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)
}
}
+131 -19
View File
@@ -43,6 +43,76 @@ func (s *PostgresStore) Init(ctx context.Context) error {
return nil
}
func (s *PostgresStore) EnsureGeneratedLesson(ctx context.Context, targetLanguage, cefrLevel string) (domain.Lesson, error) {
lesson := domain.Lesson{
ID: "les_generated_" + strings.ToLower(strings.ReplaceAll(targetLanguage, "-", "_")) + "_" + strings.ToLower(cefrLevel),
TargetLanguage: targetLanguage,
CEFRLevel: cefrLevel,
Topic: "agent_generated",
Title: "Agent generated practice",
}
row := s.db.QueryRowContext(ctx, `
INSERT INTO lessons (id, target_language, cefr_level, topic, title)
VALUES ($1, $2, $3, $4, $5)
ON CONFLICT (id) DO UPDATE SET
target_language = EXCLUDED.target_language,
cefr_level = EXCLUDED.cefr_level,
topic = EXCLUDED.topic,
title = EXCLUDED.title
RETURNING id, target_language, cefr_level, topic, title
`, lesson.ID, lesson.TargetLanguage, lesson.CEFRLevel, lesson.Topic, lesson.Title)
if err := row.Scan(&lesson.ID, &lesson.TargetLanguage, &lesson.CEFRLevel, &lesson.Topic, &lesson.Title); err != nil {
return domain.Lesson{}, err
}
return lesson, nil
}
func (s *PostgresStore) SaveGeneratedExercise(ctx context.Context, userID string, generated domain.GeneratedExercise) (domain.Lesson, domain.Exercise, error) {
targetLanguage := valueOr(generated.TargetLanguage, "en-US")
cefrLevel := valueOr(generated.CEFRLevel, "A1")
lesson, err := s.EnsureGeneratedLesson(ctx, targetLanguage, cefrLevel)
if err != nil {
return domain.Lesson{}, domain.Exercise{}, err
}
focusPoints, err := json.Marshal(generated.FocusPoints)
if err != nil {
return domain.Lesson{}, domain.Exercise{}, err
}
successCriteria, err := json.Marshal(generated.SuccessCriteria)
if err != nil {
return domain.Lesson{}, domain.Exercise{}, err
}
exercise := domain.Exercise{
ID: NewID("exg"),
LessonID: lesson.ID,
TargetLanguage: targetLanguage,
CEFRLevel: cefrLevel,
Type: valueOr(generated.ExerciseType, "repeat_sentence"),
PromptText: valueOr(generated.DisplayPrompt, "Sprich den Satz klar nach."),
TargetText: generated.ReferenceText,
Difficulty: 1,
Source: "flowise",
}
if strings.TrimSpace(exercise.TargetText) == "" {
return domain.Lesson{}, domain.Exercise{}, errors.New("generated exercise reference_text is required")
}
row := s.db.QueryRowContext(ctx, `
INSERT INTO exercises (
id, lesson_id, target_language, cefr_level, type, prompt_text, target_text,
difficulty, source, created_by_user_id, tts_text, focus_points_json,
success_criteria_json, reason_for_choice, agent_context_json
)
VALUES ($1, $2, $3, $4, $5, $6, $7, $8, 'flowise', $9, $10, $11, $12, $13, $14)
RETURNING id, lesson_id, target_language, cefr_level, type, prompt_text, target_text, difficulty, source
`, exercise.ID, exercise.LessonID, exercise.TargetLanguage, exercise.CEFRLevel, exercise.Type,
exercise.PromptText, exercise.TargetText, exercise.Difficulty, userID, generated.TTSText,
string(focusPoints), string(successCriteria), generated.ReasonForChoice, mustJSON(generated))
if err := row.Scan(&exercise.ID, &exercise.LessonID, &exercise.TargetLanguage, &exercise.CEFRLevel, &exercise.Type, &exercise.PromptText, &exercise.TargetText, &exercise.Difficulty, &exercise.Source); err != nil {
return domain.Lesson{}, domain.Exercise{}, err
}
return lesson, exercise, nil
}
func (s *PostgresStore) DebugStatus(ctx context.Context) domain.DebugDBStatus {
status := domain.DebugDBStatus{
Counts: map[string]int{},
@@ -204,27 +274,32 @@ func (s *PostgresStore) GetLanguage(ctx context.Context, code string) (domain.La
return lang, nil
}
func (s *PostgresStore) NextLessonAndExercise(ctx context.Context, profile domain.LearnerProfile) (domain.Lesson, domain.Exercise, error) {
func (s *PostgresStore) NextLessonAndExercise(ctx context.Context, profile domain.LearnerProfile, avoidReferenceText ...string) (domain.Lesson, domain.Exercise, error) {
var lesson domain.Lesson
var exercise domain.Exercise
row := s.db.QueryRowContext(ctx, `
SELECT l.id, l.target_language, l.cefr_level, l.topic, l.title,
e.id, e.lesson_id, e.target_language, e.cefr_level, e.type,
e.prompt_text, e.target_text, e.difficulty
e.prompt_text, e.target_text, e.difficulty, COALESCE(e.source, 'seed')
FROM exercises e
JOIN lessons l ON l.id = e.lesson_id
WHERE e.target_language = $1 AND e.cefr_level = $2
AND COALESCE(e.source, 'seed') = 'seed'
AND NOT EXISTS (
SELECT 1 FROM jsonb_array_elements_text($4::jsonb) AS avoided(sentence)
WHERE lower(trim(avoided.sentence)) = lower(trim(e.target_text))
)
ORDER BY (
SELECT COUNT(*)
FROM attempts a
WHERE a.exercise_id = e.id AND a.user_id = $3
), e.difficulty, e.id
LIMIT 1
`, profile.TargetLanguage, profile.CEFRLevel, profile.UserID)
`, profile.TargetLanguage, profile.CEFRLevel, profile.UserID, mustJSON(avoidReferenceText))
if err := row.Scan(
&lesson.ID, &lesson.TargetLanguage, &lesson.CEFRLevel, &lesson.Topic, &lesson.Title,
&exercise.ID, &exercise.LessonID, &exercise.TargetLanguage, &exercise.CEFRLevel, &exercise.Type,
&exercise.PromptText, &exercise.TargetText, &exercise.Difficulty,
&exercise.PromptText, &exercise.TargetText, &exercise.Difficulty, &exercise.Source,
); err != nil {
if errors.Is(err, sql.ErrNoRows) {
return domain.Lesson{}, domain.Exercise{}, ErrNotFound
@@ -234,14 +309,14 @@ func (s *PostgresStore) NextLessonAndExercise(ctx context.Context, profile domai
return lesson, exercise, nil
}
func (s *PostgresStore) GetExercise(ctx context.Context, id string) (domain.Exercise, error) {
func (s *PostgresStore) GetExercise(ctx context.Context, id, userID string) (domain.Exercise, error) {
var e domain.Exercise
row := s.db.QueryRowContext(ctx, `
SELECT id, lesson_id, target_language, cefr_level, type, prompt_text, target_text, difficulty
SELECT id, lesson_id, target_language, cefr_level, type, prompt_text, target_text, difficulty, COALESCE(source, 'seed')
FROM exercises
WHERE id = $1
`, id)
if err := row.Scan(&e.ID, &e.LessonID, &e.TargetLanguage, &e.CEFRLevel, &e.Type, &e.PromptText, &e.TargetText, &e.Difficulty); err != nil {
WHERE id = $1 AND (COALESCE(source, 'seed') = 'seed' OR created_by_user_id = $2)
`, id, userID)
if err := row.Scan(&e.ID, &e.LessonID, &e.TargetLanguage, &e.CEFRLevel, &e.Type, &e.PromptText, &e.TargetText, &e.Difficulty, &e.Source); err != nil {
if errors.Is(err, sql.ErrNoRows) {
return domain.Exercise{}, ErrNotFound
}
@@ -307,26 +382,38 @@ func (s *PostgresStore) Progress(ctx context.Context, userID string, limit int)
}
defer rows.Close()
weakByWord := map[string]domain.WordScore{}
for rows.Next() {
attempt, err := scanAttempt(rows)
if err != nil {
return domain.ProgressSummary{}, err
}
summary.RecentAttempts = append(summary.RecentAttempts, attempt)
}
if err := rows.Err(); err != nil {
return domain.ProgressSummary{}, err
}
summary.WeakWords = latestWeakWords(summary.RecentAttempts)
return summary, nil
}
// RecentAttempts are ordered newest first. A newer successful score clears an
// older weak score for the same word within the progress window.
func latestWeakWords(attempts []domain.Attempt) []domain.WordScore {
seen := make(map[string]bool)
var weak []domain.WordScore
for _, attempt := range attempts {
for _, word := range attempt.WordScores {
key := strings.ToLower(strings.TrimSpace(word.Word))
if key == "" || seen[key] {
continue
}
seen[key] = true
if word.Accuracy < 75 {
existing, ok := weakByWord[strings.ToLower(word.Word)]
if !ok || word.Accuracy < existing.Accuracy {
weakByWord[strings.ToLower(word.Word)] = word
weak = append(weak, word)
}
}
}
}
for _, word := range weakByWord {
summary.WeakWords = append(summary.WeakWords, word)
}
return summary, rows.Err()
return weak
}
func (s *PostgresStore) CreateConversationSession(ctx context.Context, userID, targetLanguage, cefrLevel string) (domain.ConversationSession, error) {
@@ -401,6 +488,14 @@ func valueOr(value, fallback string) string {
return value
}
func mustJSON(value any) string {
body, err := json.Marshal(value)
if err != nil {
return "{}"
}
return string(body)
}
const schemaSQL = `
CREATE TABLE IF NOT EXISTS users (
id TEXT PRIMARY KEY,
@@ -446,9 +541,26 @@ CREATE TABLE IF NOT EXISTS exercises (
type TEXT NOT NULL,
prompt_text TEXT NOT NULL,
target_text TEXT NOT NULL,
difficulty INT NOT NULL DEFAULT 1
difficulty INT NOT NULL DEFAULT 1,
source TEXT NOT NULL DEFAULT 'seed',
created_by_user_id TEXT REFERENCES users(id) ON DELETE SET NULL,
tts_text TEXT NOT NULL DEFAULT '',
focus_points_json JSONB NOT NULL DEFAULT '[]'::jsonb,
success_criteria_json JSONB NOT NULL DEFAULT '[]'::jsonb,
reason_for_choice TEXT NOT NULL DEFAULT '',
agent_context_json JSONB NOT NULL DEFAULT '{}'::jsonb,
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
ALTER TABLE exercises ADD COLUMN IF NOT EXISTS source TEXT NOT NULL DEFAULT 'seed';
ALTER TABLE exercises ADD COLUMN IF NOT EXISTS created_by_user_id TEXT REFERENCES users(id) ON DELETE SET NULL;
ALTER TABLE exercises ADD COLUMN IF NOT EXISTS tts_text TEXT NOT NULL DEFAULT '';
ALTER TABLE exercises ADD COLUMN IF NOT EXISTS focus_points_json JSONB NOT NULL DEFAULT '[]'::jsonb;
ALTER TABLE exercises ADD COLUMN IF NOT EXISTS success_criteria_json JSONB NOT NULL DEFAULT '[]'::jsonb;
ALTER TABLE exercises ADD COLUMN IF NOT EXISTS reason_for_choice TEXT NOT NULL DEFAULT '';
ALTER TABLE exercises ADD COLUMN IF NOT EXISTS agent_context_json JSONB NOT NULL DEFAULT '{}'::jsonb;
ALTER TABLE exercises ADD COLUMN IF NOT EXISTS created_at TIMESTAMPTZ NOT NULL DEFAULT now();
CREATE TABLE IF NOT EXISTS attempts (
id TEXT PRIMARY KEY,
user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+25
View File
@@ -0,0 +1,25 @@
package store
import (
"testing"
"speech-learning-api/internal/domain"
)
func TestLatestWeakWordsUsesNewestScorePerWord(t *testing.T) {
attempts := []domain.Attempt{
{WordScores: []domain.WordScore{
{Word: "Water", Accuracy: 100},
{Word: "coffee", Accuracy: 60},
}},
{WordScores: []domain.WordScore{
{Word: "water", Accuracy: 61},
{Word: "Coffee", Accuracy: 90},
{Word: "please", Accuracy: 68},
}},
}
weak := latestWeakWords(attempts)
if len(weak) != 2 || weak[0].Word != "coffee" || weak[1].Word != "please" {
t.Fatalf("latest scores should clear water and keep coffee/please weak, got %#v", weak)
}
}
+21 -3
View File
@@ -1,17 +1,35 @@
import { request } from './client';
import type { Dashboard, Exercise, Lesson, ProgressSummary } from './types';
let pendingDashboardRequest: Promise<Dashboard> | null = null;
export function fetchDashboard() {
return request<Dashboard>('/dashboard');
if (!pendingDashboardRequest) {
pendingDashboardRequest = request<Dashboard>('/dashboard').finally(() => {
pendingDashboardRequest = null;
});
}
return pendingDashboardRequest;
}
export function fetchProgress() {
return request<ProgressSummary>('/progress');
}
export function fetchNextLesson() {
export async function fetchNextLesson(fresh = false, recentExerciseIds: string[] = []) {
if (!fresh && pendingDashboardRequest) {
try {
const dashboard = await pendingDashboardRequest;
return { lesson: dashboard.next_lesson, exercise: dashboard.next_exercise };
} catch {
// A failed dashboard request should not prevent a direct practice request.
}
}
return request<{ lesson: Lesson; exercise: Exercise }>('/lessons/next', {
method: 'POST',
body: JSON.stringify({})
body: JSON.stringify(recentExerciseIds.length ? {
previous_exercise_id: recentExerciseIds[recentExerciseIds.length - 1],
recent_exercise_ids: recentExerciseIds
} : {})
});
}
+1
View File
@@ -30,6 +30,7 @@ export type Exercise = {
prompt_text: string;
target_text: string;
difficulty: number;
source?: 'seed' | 'flowise' | 'fallback' | string;
};
export type WordScore = {
+14 -2
View File
@@ -2,6 +2,7 @@ import { BookOpen, Bug, ChartNoAxesColumnIncreasing, LogOut, Mic, MessageCircle
import { useEffect, useState } from 'react';
import { clearToken, getToken } from '../api/client';
import { fetchDebugStatus } from '../api/debug';
import type { Exercise, Lesson } from '../api/types';
import { DashboardPage } from '../pages/DashboardPage';
import { LoginPage } from '../pages/LoginPage';
import { RegisterPage } from '../pages/RegisterPage';
@@ -14,6 +15,7 @@ import { useHashRoute } from './useHashRoute';
export function App() {
const [route, setRoute] = useHashRoute(getToken() ? 'dashboard' : 'login');
const [debugAvailable, setDebugAvailable] = useState(false);
const [practiceSelection, setPracticeSelection] = useState<{ lesson: Lesson; exercise: Exercise } | null>(null);
const authed = Boolean(getToken());
useEffect(() => {
@@ -34,15 +36,25 @@ export function App() {
};
}, [authed]);
useEffect(() => {
if (route !== 'practice') setPracticeSelection(null);
}, [route]);
function handleAuthed() {
setRoute('dashboard');
}
function logout() {
clearToken();
setPracticeSelection(null);
setRoute('login');
}
function openDashboardExercise(lesson: Lesson, exercise: Exercise) {
setPracticeSelection({ lesson, exercise });
setRoute('practice');
}
if (!authed) {
return (
<main className="auth-shell">
@@ -92,8 +104,8 @@ export function App() {
</aside>
<main className="main-view">
{route === 'dashboard' && <DashboardPage onPractice={() => setRoute('practice')} />}
{route === 'practice' && <PracticePage />}
{route === 'dashboard' && <DashboardPage onLoaded={(lesson, exercise) => setPracticeSelection({ lesson, exercise })} onPractice={openDashboardExercise} />}
{route === 'practice' && <PracticePage initialSelection={practiceSelection} />}
{route === 'conversation' && <ConversationPage />}
{route === 'progress' && <ProgressPage />}
{route === 'debug' && <DebugPage />}
+16 -5
View File
@@ -1,18 +1,29 @@
import { ArrowRight, Clock, Gauge } from 'lucide-react';
import { useEffect, useState } from 'react';
import { fetchDashboard } from '../api/lessons';
import type { Dashboard } from '../api/types';
import type { Dashboard, Exercise, Lesson } from '../api/types';
type Props = {
onPractice: () => void;
onPractice: (lesson: Lesson, exercise: Exercise) => void;
onLoaded: (lesson: Lesson, exercise: Exercise) => void;
};
export function DashboardPage({ onPractice }: Props) {
export function DashboardPage({ onPractice, onLoaded }: Props) {
const [dashboard, setDashboard] = useState<Dashboard | null>(null);
const [error, setError] = useState('');
useEffect(() => {
fetchDashboard().then(setDashboard).catch((err) => setError(err instanceof Error ? err.message : 'Dashboard konnte nicht geladen werden'));
let cancelled = false;
fetchDashboard()
.then((data) => {
if (cancelled) return;
setDashboard(data);
onLoaded(data.next_lesson, data.next_exercise);
})
.catch((err) => {
if (!cancelled) setError(err instanceof Error ? err.message : 'Dashboard konnte nicht geladen werden');
});
return () => { cancelled = true; };
}, []);
if (error) return <p className="form-error">{error}</p>;
@@ -25,7 +36,7 @@ export function DashboardPage({ onPractice }: Props) {
<p className="eyebrow">Heute</p>
<h1>A1 Aussprachetraining</h1>
</div>
<button className="primary-button" onClick={onPractice}>
<button className="primary-button" onClick={() => onPractice(dashboard.next_lesson, dashboard.next_exercise)}>
<ArrowRight size={18} /> Naechste Uebung
</button>
</header>
+40 -13
View File
@@ -1,5 +1,5 @@
import { RotateCcw, Send } from 'lucide-react';
import { useEffect, useState } from 'react';
import { useEffect, useRef, useState } from 'react';
import { fetchNextLesson } from '../api/lessons';
import { submitAttempt } from '../api/practice';
import type { AttemptResponse, Exercise, Lesson } from '../api/types';
@@ -7,28 +7,46 @@ import { AudioRecorder } from '../components/AudioRecorder';
import { PronunciationText } from '../components/PronunciationText';
import { ScoreBadge } from '../components/ScoreBadge';
export function PracticePage() {
const [lesson, setLesson] = useState<Lesson | null>(null);
const [exercise, setExercise] = useState<Exercise | null>(null);
type Props = {
initialSelection?: { lesson: Lesson; exercise: Exercise } | null;
};
export function PracticePage({ initialSelection }: Props) {
const [lesson, setLesson] = useState<Lesson | null>(initialSelection?.lesson ?? null);
const [exercise, setExercise] = useState<Exercise | null>(initialSelection?.exercise ?? null);
const [audio, setAudio] = useState<Blob | null>(null);
const [result, setResult] = useState<AttemptResponse | null>(null);
const [loading, setLoading] = useState(false);
const [loadingNext, setLoadingNext] = useState(false);
const [error, setError] = useState('');
const [notice, setNotice] = useState('');
const recentExerciseIds = useRef<string[]>(initialSelection?.exercise.id ? [initialSelection.exercise.id] : []);
useEffect(() => {
loadNext();
if (!initialSelection) void loadNext();
}, []);
async function loadNext() {
async function loadNext(fresh = false) {
if (loadingNext) return;
setLoadingNext(true);
setError('');
setNotice('');
setAudio(null);
setResult(null);
try {
const next = await fetchNextLesson();
const next = await fetchNextLesson(fresh, fresh ? recentExerciseIds.current : []);
if (fresh && exercise?.target_text.trim().toLowerCase() === next.exercise.target_text.trim().toLowerCase()) {
setNotice('Der Agent hat denselben Satz erneut erzeugt. Bitte versuche es noch einmal.');
}
setLesson(next.lesson);
setExercise(next.exercise);
if (next.exercise.id && recentExerciseIds.current[recentExerciseIds.current.length - 1] !== next.exercise.id) {
recentExerciseIds.current = [...recentExerciseIds.current, next.exercise.id].slice(-3);
}
} catch (err) {
setError(err instanceof Error ? err.message : 'Uebung konnte nicht geladen werden');
} finally {
setLoadingNext(false);
}
}
@@ -45,8 +63,14 @@ export function PracticePage() {
}
}
if (error) return <p className="form-error">{error}</p>;
if (!lesson || !exercise) return <p className="muted">Lade Uebung...</p>;
if (!lesson || !exercise) {
return (
<div className="view-stack">
<p className={error ? 'form-error' : 'muted'}>{error || 'Lade Uebung...'}</p>
{error && <button className="ghost-button" disabled={loadingNext} onClick={() => void loadNext(true)}>Erneut versuchen</button>}
</div>
);
}
return (
<div className="view-stack">
@@ -55,17 +79,20 @@ export function PracticePage() {
<p className="eyebrow">{lesson.title}</p>
<h1>Aussprache</h1>
</div>
<button className="ghost-button" onClick={loadNext}>
<RotateCcw size={18} /> Andere Uebung
<button className="ghost-button" disabled={loadingNext || loading} onClick={() => void loadNext(true)}>
<RotateCcw size={18} /> {loadingNext ? 'Lade neue Uebung...' : 'Andere Uebung'}
</button>
</header>
{error && <p className="form-error">{error}</p>}
{notice && <p className="muted">{notice}</p>}
<section className="panel practice-panel">
<p className="muted">{exercise.prompt_text}</p>
<PronunciationText targetText={exercise.target_text} words={result?.attempt.word_scores} />
<div className="action-row">
<AudioRecorder onRecorded={setAudio} disabled={loading} />
<button className="primary-button" disabled={!audio || loading} onClick={submit}>
<AudioRecorder onRecorded={setAudio} disabled={loading || loadingNext} />
<button className="primary-button" disabled={!audio || loading || loadingNext} onClick={submit}>
<Send size={18} /> Bewerten
</button>
</div>
+12 -8
View File
@@ -8,24 +8,28 @@ The Flowise agent acts as a precise A1 English teacher for German-speaking adult
- `target_language`
- `cefr_level`
- current exercise
- Azure scores
- learner profile
- progress summary
- weak words
- recent attempts
## Output
The backend expects valid JSON:
For task `next_exercise`, the backend expects valid JSON:
```json
{
"exercise_type": "repeat_sentence",
"target_text": "Hello, my name is Anna.",
"teacher_feedback": "Uebe besonders 'name'.",
"target_language": "en-US",
"cefr_level": "A1",
"reference_text": "Hello, my name is Anna.",
"display_prompt": "Sprich den Satz klar nach.",
"tts_text": "Hello, my name is Anna.",
"ssml": "",
"next_recommendation": "Sprich den Satz noch einmal langsam."
"focus_points": ["name"],
"success_criteria": ["accuracy above 80"],
"reason_for_choice": "Kurzer Satz fuer klare A1-Aussprache."
}
```
The agent must not create pronunciation scores. Azure is the scoring source.
The agent must not create pronunciation scores. Azure is the scoring source. Feedback and simple
conversation are local backend logic in this phase; Flowise is used only for exercise generation.
+9 -2
View File
@@ -13,13 +13,20 @@ FlowiseAI runs as a Docker container on the same VPS and Docker network. The fro
## Backend
The Go API is the system of record. It owns auth, learner profiles, language profiles, exercises, attempts, progress, Azure calls, and Flowise calls.
The Go API is the system of record. It owns auth, learner profiles, language profiles, generated exercises, attempts, progress, Azure calls, and Flowise calls.
Flowise owns the first version of the lesson logic: when the dashboard or `POST /lessons/next`
needs the next task, the API sends profile/progress context to Flowise with a stable
`sessionId`. Flowise returns one exercise JSON object. The API stores that exercise in PostgreSQL
for the current user and returns it to the frontend. If Flowise is unavailable or returns invalid
JSON, the API falls back to seeded A1 exercises. Feedback and the simple conversation screen stay
local backend behavior in this first Flowise-generation phase.
Important boundaries:
- `httpapi`: request/response handling.
- `services`: auth, Azure Speech, Flowise teacher logic.
- `store`: PostgreSQL schema, seed data, repositories.
- `store`: PostgreSQL schema, seed data, generated exercise persistence, repositories.
- `domain`: shared API/domain structs.
## Multilingual Design
+11 -7
View File
@@ -6,7 +6,7 @@ Flowise laeuft in Docker als Service `flowise` und ist vom Backend intern ueber
Fuer Agentflow V2 nutze zuerst die konkrete Anleitung in
[`agentflow-v2-setup.md`](./agentflow-v2-setup.md). Sie passt zur aktuellen
Go-Backend-Anbindung, die Flowise mit `question` und `form` aufruft.
Go-Backend-Anbindung, die Flowise mit `question` und `overrideConfig.sessionId` aufruft.
1. Flowise im Browser oeffnen: http://localhost:3000
2. Einen Chatflow oder Agentflow fuer `A1 English Teacher` erstellen.
@@ -17,17 +17,21 @@ Go-Backend-Anbindung, die Flowise mit `question` und `form` aufruft.
FLOWISE_CHATFLOW_ID=...
```
Das Backend erwartet JSON-Antworten mit:
Fuer die naechste Uebung erwartet das Backend JSON-Antworten mit:
```json
{
"exercise_type": "repeat_sentence",
"target_text": "Hello, my name is Anna.",
"teacher_feedback": "Uebe besonders 'name'.",
"target_language": "en-US",
"cefr_level": "A1",
"reference_text": "Hello, my name is Anna.",
"display_prompt": "Sprich den Satz klar nach.",
"tts_text": "Hello, my name is Anna.",
"ssml": "",
"next_recommendation": "Sprich den Satz noch einmal langsam."
"focus_points": ["name"],
"success_criteria": ["accuracy above 80"],
"reason_for_choice": "Kurzer A1-Satz fuer klare Betonung."
}
```
Wenn keine Chatflow-ID gesetzt ist, nutzt die API einen lokalen Fallback.
Feedback und einfache Konversation laufen vorerst lokal im Backend. Wenn keine Chatflow-ID gesetzt
ist oder Flowise kein valides JSON liefert, nutzt die API Seed-Uebungen als Fallback.
+81 -85
View File
@@ -11,32 +11,27 @@ It is designed for the current Go backend adapter.
- Internal Flowise URL for the API container: `http://flowise:3000`
- Verified Flowise version on the existing instance: `3.0.11`
- The Go backend calls Flowise with `POST /api/v1/prediction/{FLOWISE_CHATFLOW_ID}`.
- The request body includes `question` as a JSON string and `form` as the same structured object.
- The request body includes `question` as one JSON string and `overrideConfig.sessionId`.
Build the first V2 flow with Start Node input type `Chat Input`; it is the simplest path because
all current tasks arrive as one JSON context. V2 `Form Input` is also possible now, but only if the
form fields match the backend payload fields for the task you want to handle.
the backend sends one JSON context as the chat input. V2 `Form Input` can come later if you split
the flow into typed task-specific flows.
The backend parses Flowise responses from `text`, `json`, or a raw JSON response. A plain JSON text
reply is still the easiest response format to debug in Flowise and in the app.
## Current backend tasks
The current backend can call the agent for these tasks:
The current backend sends only one task to Flowise:
1. `practice_feedback`
- Sent after Azure/mock pronunciation assessment.
- Context includes `target_text`, `recognized_text`, `scores`, `weak_words`, and rules.
- The agent must never create or modify pronunciation scores.
2. `start_conversation`
- Starts a short A1 roleplay.
- Context includes `target_language` and `cefr_level`.
3. `continue_conversation`
- Continues a short A1 roleplay.
- Context includes `target_language`, `cefr_level`, and `user_text`.
1. `next_exercise`
- Sent when dashboard or `POST /lessons/next` needs the next speaking exercise.
- Context includes learner profile, recent progress, weak words, target language, CEFR level, and rules.
- The agent creates exactly one A1 exercise. The backend stores it in PostgreSQL for that user.
The backend does not currently call Flowise to choose the next DB exercise. The prompt
`prompts/exercise_generation.md` is useful for a later backend extension, but it is not used now.
Flowise owns the exercise-generation logic. PostgreSQL remains the durable system of record for
users, profiles, generated exercises, attempts, and progress. Pronunciation scoring stays in Azure
Speech/the backend. Feedback and the simple conversation screen are local fallback logic for now.
## Recommended V2 graph
@@ -65,7 +60,8 @@ Start Node:
LLM/Agent Node:
- Input Message: `{{ $flow.input }}`
- Memory: off for now. The backend does not pass a Flowise `sessionId` yet.
- Memory: on or Flowise chat memory enabled if you want per-user continuity.
- The backend sends `overrideConfig.sessionId` in the shape `user_id:target_language:practice`.
- Output: JSON text only.
Direct Reply Node:
@@ -83,55 +79,47 @@ You receive one JSON object as the user message. It contains a field named "task
Global rules:
- Return valid JSON only. No Markdown. No code fences. No commentary outside JSON.
- Use exactly this JSON shape:
- Read the input JSON field "task".
- If task is "next_exercise", use exactly this JSON shape:
{
"exercise_type": "repeat_sentence",
"target_text": "English text the learner should say next",
"teacher_feedback": "Short German feedback",
"tts_text": "Text for speech synthesis",
"ssml": "",
"next_recommendation": "One short next step in German"
"target_language": "en-US",
"cefr_level": "A1",
"reference_text": "English sentence the learner must pronounce",
"display_prompt": "Short German instruction",
"tts_text": "English text for speech synthesis",
"focus_points": ["one or two words or sounds to practise"],
"success_criteria": ["concrete success criterion"],
"reason_for_choice": "Short German reason based on learner progress"
}
- Allowed exercise_type values: "repeat_sentence", "conversation".
- If the task is missing or unknown, still return one safe A1 repeat_sentence exercise in this same shape.
- Allowed exercise_type value for now: "repeat_sentence".
- Keep the learner at CEFR A1 unless the input explicitly says otherwise.
- Explain in German. Target sentences and roleplay turns are in English.
- Use short, everyday A1 English. Prefer 3 to 9 words for target_text when possible.
- Give at most two corrections per turn.
- Use German for display_prompt and reason_for_choice.
- Use English for reference_text and tts_text.
- Use short, everyday A1 English. Prefer 3 to 9 words for reference_text when possible.
- Do not invent pronunciation scores. Scores come only from Azure Speech or the backend mock.
- Do not change score values. Use scores only to decide feedback.
- Prefer repetition, minimal pairs, shadowing, short roleplay, and one clear next step.
- Keep ssml as an empty string unless the backend later asks for SSML.
- Use recent weak_words if present.
- Prefer repetition, minimal pairs, shadowing, and one clear pronunciation focus.
Task rules:
If task is "practice_feedback":
- Use target_text, recognized_text, scores, and weak_words.
- Mention the weakest word or sound if available.
- If overall_score is high, praise briefly and recommend a more natural rhythm.
- If weak_words are present, ask the learner to repeat the original target_text slowly.
- exercise_type must be "repeat_sentence".
- target_text and tts_text should usually equal the original target_text.
If task is "start_conversation":
- Start one simple A1 roleplay.
- Use one short teacher sentence as target_text and tts_text.
- Give a German next_recommendation that tells the learner how to answer.
- exercise_type must be "conversation".
If task is "continue_conversation":
- Read user_text and continue with one short teacher sentence.
- Correct only the most important issue, if any.
- Keep the roleplay moving with a simple A1 question or prompt.
- exercise_type must be "conversation".
If the task is missing or unknown:
- Return a safe repeat_sentence response for A1 practice.
If task is "next_exercise":
- Create one short pronunciation exercise for the learner.
- exercise_type must be "repeat_sentence" for the current MVP.
- reference_text and tts_text should be English and usually identical.
- display_prompt and reason_for_choice should be German.
- Use recent weak_words if present.
- Keep the sentence short, natural, and useful for A1.
- Do not include pronunciation scores.
```
## JSON contract
Use this contract mentally or as a structured-output schema if the UI supports it.
Exercise generation response for `next_exercise`:
```json
{
"type": "object",
@@ -139,31 +127,49 @@ Use this contract mentally or as a structured-output schema if the UI supports i
"properties": {
"exercise_type": {
"type": "string",
"enum": ["repeat_sentence", "conversation"]
"enum": ["repeat_sentence"]
},
"target_text": {
"target_language": {
"type": "string"
},
"teacher_feedback": {
"cefr_level": {
"type": "string"
},
"reference_text": {
"type": "string"
},
"display_prompt": {
"type": "string"
},
"tts_text": {
"type": "string"
},
"ssml": {
"focus_points": {
"type": "array",
"items": {
"type": "string"
}
},
"next_recommendation": {
"success_criteria": {
"type": "array",
"items": {
"type": "string"
}
},
"reason_for_choice": {
"type": "string"
}
},
"required": [
"exercise_type",
"target_text",
"teacher_feedback",
"target_language",
"cefr_level",
"reference_text",
"display_prompt",
"tts_text",
"ssml",
"next_recommendation"
"focus_points",
"success_criteria",
"reason_for_choice"
]
}
```
@@ -172,34 +178,25 @@ Use this contract mentally or as a structured-output schema if the UI supports i
Paste these as chat input in Flowise.
Practice feedback:
Next exercise:
```json
{"task":"practice_feedback","target_text":"Can I have a coffee, please?","recognized_text":"Can I have coffee please","scores":{"recognized_text":"Can I have coffee please","overall_score":72,"accuracy_score":70,"fluency_score":78,"completeness_score":82,"prosody_score":69,"word_scores":[{"word":"Can","accuracy":91,"highlight":"good"},{"word":"I","accuracy":88,"highlight":"good"},{"word":"have","accuracy":74,"highlight":"ok"},{"word":"a","accuracy":55,"highlight":"weak"},{"word":"coffee","accuracy":79,"highlight":"ok"},{"word":"please","accuracy":68,"highlight":"weak"}],"provider":"mock"},"weak_words":[{"word":"a","accuracy":55,"highlight":"weak"},{"word":"please","accuracy":68,"highlight":"weak"}],"rules":"Answer in German. A1 learner. Max two corrections. Return valid JSON only."}
```
Start conversation:
```json
{"task":"start_conversation","target_language":"en-US","cefr_level":"A1","rules":"Create a simple A1 roleplay. Return valid JSON only."}
```
Continue conversation:
```json
{"task":"continue_conversation","target_language":"en-US","cefr_level":"A1","user_text":"My name Anna","rules":"Continue a simple A1 conversation. Return valid JSON only."}
{"task":"next_exercise","user_id":"usr_demo","target_language":"en-US","cefr_level":"A1","ui_language":"de-DE","profile":{"target_language":"en-US","cefr_level":"A1","daily_goal_minutes":10},"progress":{"total_attempts":2,"average_score":73,"weak_words":[{"word":"please","accuracy":61,"highlight":"weak"}],"recent_attempts":[]},"recent_weak_words":[{"word":"please","accuracy":61,"highlight":"weak"}],"preferred_type":"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."}
```
Expected output example:
```json
{
"exercise_type": "conversation",
"target_text": "Nice to meet you, Anna.",
"teacher_feedback": "Fast richtig: Sage \"My name is Anna.\"",
"tts_text": "Nice to meet you, Anna.",
"ssml": "",
"next_recommendation": "Antworte kurz: I am from ..."
"exercise_type": "repeat_sentence",
"target_language": "en-US",
"cefr_level": "A1",
"reference_text": "Can I have water, please?",
"display_prompt": "Sprich den Satz langsam und klar nach.",
"tts_text": "Can I have water, please?",
"focus_points": ["please", "water"],
"success_criteria": ["accuracy above 80", "clear final sounds"],
"reason_for_choice": "Die Uebung wiederholt ein schwaches Wort in einem kurzen Alltagssatz."
}
```
@@ -226,7 +223,7 @@ docker compose up --build -d speech-api
## Validation
1. In Flowise, run each test payload and confirm the reply is plain JSON text.
2. In the app, submit a pronunciation attempt and verify that the `teacher` response is not the local fallback.
2. In the app, open the dashboard or click the next lesson button and verify that the returned exercise has `source: "flowise"`.
3. Use the Debug page or `GET /api/debug/flowise` after the API is recreated with `DEBUG_ENABLED=true`.
If `/api/debug/*` returns `404`, the running API was started without debug routes. Recreate the
@@ -234,11 +231,10 @@ If `/api/debug/*` returns `404`, the running API was started without debug route
## Later upgrades
These backend changes would unlock a more capable V2 agent:
Useful later upgrades:
- Send `overrideConfig.sessionId` and/or recent turns for conversation continuity.
- Add typed V2 `Form Input` variants if individual task-specific flows are split out.
- Add a backend task for dynamic exercise generation using `prompts/exercise_generation.md`.
- Add Flowise tools for curriculum lookup, spaced repetition policy, or vector-memory retrieval.
- Add a safe internal admin/debug tool only if the backend passes a scoped service credential.
References:
+12 -10
View File
@@ -2,19 +2,21 @@ You are an A1 English teacher for German-speaking adult learners.
Rules:
- Keep the learner at CEFR A1 unless the backend explicitly sends another level.
- Answer explanations in German.
- Use short English target sentences.
- Give at most two corrections per turn.
- Use German for display_prompt and reason_for_choice.
- Use short English reference_text sentences.
- Do not invent pronunciation scores. Scores come only from Azure Speech.
- Prefer repetition, minimal pairs, shadowing, and short roleplay.
- Prefer repetition, minimal pairs, and shadowing.
- Return valid JSON only.
Required JSON shape:
Return this JSON shape:
{
"exercise_type": "repeat_sentence | conversation",
"target_text": "English text the learner should say next",
"teacher_feedback": "Short German feedback",
"exercise_type": "repeat_sentence",
"target_language": "en-US",
"cefr_level": "A1",
"reference_text": "English text the learner should pronounce",
"display_prompt": "Short German instruction",
"tts_text": "Text for speech synthesis",
"ssml": "",
"next_recommendation": "One short next step in German"
"focus_points": ["word or sound to practise"],
"success_criteria": ["concrete success criterion"],
"reason_for_choice": "Short German reason based on progress"
}