package services import ( "bytes" "context" "encoding/json" "errors" "fmt" "io" "net/http" "strings" "speech-learning-api/internal/domain" ) type CourseTaskGenerator interface { GenerateCourseTask(context.Context, domain.GenerateCourseTaskRequest) (domain.GeneratedCourseTask, error) } // Course generation deliberately has its own flow ID, parser, and validator. // It never calls the existing pronunciation flow, even when unconfigured. func (f *FlowiseTeacher) GenerateCourseTask(ctx context.Context, input domain.GenerateCourseTaskRequest) (domain.GeneratedCourseTask, error) { var out domain.GeneratedCourseTask if f.cfg.FlowiseBaseURL == "" || f.cfg.FlowiseCourseChatflow == "" { return out, errors.New("course flow is not configured") } input.Rules = "Erzeuge genau eine fachlich geprüfte Auswahlaufgabe zum übergebenen Lernziel. Wähle drei eindeutige Optionen und eine dazu passende Lösung. Beachte avoid_prompts. Antworte nur mit einem JSON-Objekt mit schema_version, target_language, cefr_level, module_id, learning_goal_id, skill, kind, prompt, options, solution und explanation. learning_goal_id ist learning_goal.id. Erklärung auf Deutsch. rules und retry_instruction sind Eingabehinweise und dürfen nicht in der Ausgabe stehen." for attempt := 0; attempt < 2; attempt++ { data, err := f.askCourseTask(ctx, input) if err != nil { return out, err } out, err = parseCourseTaskEnvelope(data) if err == nil { out.Prompt = strings.TrimSpace(strings.ReplaceAll(out.Prompt, "**", "")) out.Explanation = strings.TrimSpace(strings.ReplaceAll(out.Explanation, "**", "")) err = ValidateGeneratedCourseTask(out, input) } if err == nil { return out, nil } // Log only the bounded public task prompt, never the complete response, // answer key, or learner context. This makes rejections diagnosable. promptForLog := []rune(strings.Join(strings.Fields(out.Prompt), " ")) if len(promptForLog) > 240 { promptForLog = promptForLog[:240] } f.logger.Warn("course generation rejected", "reason", err.Error(), "learning_goal_id", input.LearningGoal.ID, "prompt", string(promptForLog), "generation_attempt", attempt+1) if attempt == 1 || ctx.Err() != nil { return out, err } f.logger.Info("course generation requesting correction", "reason", err.Error(), "learning_goal_id", input.LearningGoal.ID) // Carry only the bounded validation reason, not the rejected model body. reason := []rune(err.Error()) if len(reason) > 240 { reason = reason[:240] } input.RetryInstruction = "Die vorherige Ausgabe wurde abgelehnt: " + string(reason) + ". Erzeuge eine korrigierte Aufgabe für dasselbe Lernziel. Halte das technische JSON-Format und den Bezug der Lösung zu einer Option ein. Befolge rules." } return out, errors.New("course correction failed") } func (f *FlowiseTeacher) askCourseTask(ctx context.Context, input domain.GenerateCourseTaskRequest) ([]byte, error) { question, err := json.Marshal(input) if err != nil { return nil, err } body, err := json.Marshal(map[string]any{"question": string(question), "streaming": false}) if err != nil { return nil, err } endpoint := strings.TrimRight(f.cfg.FlowiseBaseURL, "/") + "/api/v1/prediction/" + f.cfg.FlowiseCourseChatflow req, err := http.NewRequestWithContext(ctx, http.MethodPost, endpoint, bytes.NewReader(body)) if err != nil { return nil, err } req.Header.Set("Content-Type", "application/json") key := valueOr(f.cfg.FlowiseCourseAPIKey, f.cfg.FlowiseAPIKey) if key != "" { req.Header.Set("Authorization", "Bearer "+key) } resp, err := f.client.Do(req) if err != nil { return nil, err } defer resp.Body.Close() if resp.StatusCode != http.StatusOK { return nil, fmt.Errorf("course flow HTTP status %d", resp.StatusCode) } data, err := io.ReadAll(io.LimitReader(resp.Body, 65537)) if err != nil { return nil, err } if len(data) > 65536 { return nil, errors.New("course flow response exceeds 64 KiB") } return data, nil } func parseCourseTaskEnvelope(data []byte) (domain.GeneratedCourseTask, error) { var err error data, err = courseJSONContent(data) if err != nil { return domain.GeneratedCourseTask{}, err } var envelope map[string]json.RawMessage if err := json.Unmarshal(data, &envelope); err != nil { return domain.GeneratedCourseTask{}, errors.New("invalid course JSON") } // A direct task must not bypass unknown-field checks by adding an envelope. if _, direct := envelope["schema_version"]; !direct { var failures []string for _, key := range []string{"json", "text", "output"} { if raw := envelope[key]; len(raw) > 0 && string(raw) != "null" { if out, err := decodeCourseTask(raw); err == nil { return out, nil } else { failures = append(failures, key+": "+err.Error()) } } } // Keep the error from the actual model output. Decoding the entire // transport envelope here would mask it with e.g. unknown field text. if len(failures) > 0 { return domain.GeneratedCourseTask{}, fmt.Errorf("invalid course task response (%s)", strings.Join(failures, "; ")) } } return decodeCourseTask(data) } // Flowise text replies may wrap otherwise valid JSON in one Markdown block. // Remove only a complete outer block; never extract JSON from surrounding prose // or ignore trailing content. Strict decoding and semantic validation still run. func courseJSONContent(data []byte) ([]byte, error) { value := strings.TrimSpace(string(data)) if !strings.HasPrefix(value, "```") { return []byte(value), nil } firstLine := strings.IndexByte(value, '\n') if firstLine < 0 { return nil, errors.New("unterminated Markdown JSON block") } opening := strings.ToLower(strings.TrimSpace(value[:firstLine])) if opening != "```json" && opening != "```" { return nil, errors.New("unsupported Markdown block; expected JSON") } lastLine := strings.LastIndexByte(value, '\n') if lastLine <= firstLine || strings.TrimSpace(value[lastLine+1:]) != "```" { return nil, errors.New("unterminated Markdown JSON block or trailing content") } return []byte(strings.TrimSpace(value[firstLine+1 : lastLine])), nil } func decodeCourseTask(data []byte) (domain.GeneratedCourseTask, error) { var text string if json.Unmarshal(data, &text) == nil { data = []byte(strings.TrimSpace(text)) } var err error data, err = courseJSONContent(data) if err != nil { return domain.GeneratedCourseTask{}, err } var out domain.GeneratedCourseTask decoder := json.NewDecoder(bytes.NewReader(data)) decoder.DisallowUnknownFields() if err := decoder.Decode(&out); err != nil { // Decoder errors identify field names/types or a syntax offset; do // not log the raw response, which can contain unneeded learner data. var typeError *json.UnmarshalTypeError var syntaxError *json.SyntaxError switch { case errors.As(err, &typeError): return out, fmt.Errorf("invalid course task field %s: expected %s, received %s", typeError.Field, typeError.Type, typeError.Value) case errors.As(err, &syntaxError): return out, fmt.Errorf("invalid course task JSON syntax at byte %d", syntaxError.Offset) default: return out, fmt.Errorf("invalid course task fields: %w", err) } } if decoder.Decode(new(any)) != io.EOF { return out, errors.New("trailing course JSON") } var fields map[string]json.RawMessage if err := json.Unmarshal(data, &fields); err != nil { return out, errors.New("course task must be a JSON object") } for _, field := range []string{"schema_version", "target_language", "cefr_level", "module_id", "learning_goal_id", "skill", "kind", "prompt", "options", "solution", "explanation"} { if raw, ok := fields[field]; !ok || string(raw) == "null" { return out, fmt.Errorf("course task missing required field %s", field) } } return out, nil } func normalizedCoursePrompt(value string) string { return strings.ToLower(strings.Join(strings.Fields(value), " ")) } func ValidateGeneratedCourseTask(out domain.GeneratedCourseTask, input domain.GenerateCourseTaskRequest) error { if out.SchemaVersion != 1 || input.SchemaVersion != 1 || out.TargetLanguage != input.TargetLanguage || out.CEFRLevel != input.CEFRLevel || out.ModuleID != input.ModuleID || out.LearningGoalID != input.LearningGoal.ID || out.Skill != input.Skill || out.Kind != "choice" { return errors.New("course task context mismatch") } if !validExerciseText(out.Prompt, 240) || !validExerciseText(out.Explanation, 500) || len(out.Options) != 3 { return errors.New("invalid course text or option count") } seen := make(map[string]bool) for _, option := range out.Options { normal := normalizedCoursePrompt(option) if !validExerciseText(option, 100) || seen[normal] { return errors.New("invalid or ambiguous course option: use exactly learning_goal.allowed_forms") } seen[normal] = true } if !seen[normalizedCoursePrompt(out.Solution)] { return errors.New("course solution must refer to a displayed option") } for _, prompt := range input.AvoidPrompts { if normalizedCoursePrompt(prompt) == normalizedCoursePrompt(out.Prompt) { return errors.New("repeated course prompt") } } return nil }