Files
Speech/apps/api/internal/services/course_generation.go
T
Eugenius Naumenko e274eaab2b Adaptiven A1-Kurs und statistisches Aussprachetraining integrieren
Direkte DeepSeek- und Mistral-Anbindung mit versionierten Aktionsprofilen,
Budgetreservierung, Tokenabrechnung und administrativen Qualitätsprüfungen
ersetzen die Flowise-Abhängigkeit im regulären Betrieb.

840 geprüfte A1-Aufgaben mit geschützter Testauswertung und konkreten offenen
Arbeitsaufträgen ergänzen den Kurs. Inhalts- und Sprachbewertung bleiben von
Azure-Aussprachewerten getrennt; historische Aufgaben und Antworten bleiben erhalten.

Echte Wort- und Phonemmessungen werden mit Herkunft, Aktualität und Nachweisdichte
gebündelt. Go bestimmt Trainingsziele und Wiederholungen, das Modell formuliert
dazu passende Nachsprechübungen. Profilansicht und Auswahlgründe werden angezeigt.

Validierung: Go-Race-Tests mit lokaler PostgreSQL-Integration, go vet,
Web-Build, Audit aller 840 Aufgaben und drei Browser-Smokes mit lokalen
Modell-/Speech-Fixtures bestanden. Keine Produktionsänderungen oder Live-Aufrufe.
2026-11-01 23:23:20 +00:00

225 lines
8.9 KiB
Go

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
}