package services import ( "context" "errors" "fmt" "log/slog" "time" "speech-learning-api/internal/domain" "speech-learning-api/internal/store" ) type CourseEngine struct { Mode string Repo *store.AdaptiveStore Profiles *store.PostgresStore Agent CourseAgent Logger *slog.Logger } func NewCourseEngine(repo *store.AdaptiveStore, profiles *store.PostgresStore, agent CourseAgent, logger *slog.Logger) *CourseEngine { return &CourseEngine{Repo: repo, Profiles: profiles, Agent: agent, Logger: logger} } func (e *CourseEngine) Run(ctx context.Context) { for i := 0; i < 2; i++ { go e.worker(ctx) } timer := time.NewTicker(5 * time.Second) defer timer.Stop() for { if direct, ok := e.Agent.(*AIService); ok { if err := direct.Repo.Recover(ctx); err != nil && ctx.Err() == nil { e.Logger.Warn("AI call recovery failed", "error", err) } } if err := e.Repo.Reconcile(ctx, e.Mode == "bank"); err != nil && ctx.Err() == nil { e.Logger.Warn("course job recovery failed", "error", err) } select { case <-ctx.Done(): return case <-timer.C: } } } func (e *CourseEngine) worker(ctx context.Context) { timer := time.NewTicker(time.Second) defer timer.Stop() for { if ctx.Err() != nil { return } job, err := e.Repo.Claim(ctx) if err != nil { if !errors.Is(err, store.ErrNotFound) && ctx.Err() == nil { e.Logger.Warn("course job claim failed", "error", err) } select { case <-ctx.Done(): return case <-timer.C: } continue } timeout := 180 * time.Second if job.Kind == "exam" { timeout = 300 * time.Second } work, cancel := context.WithTimeout(ctx, timeout) task, err := e.Process(work, job) cancel() finish, stop := context.WithTimeout(context.Background(), 5*time.Second) if ctx.Err() != nil { _ = e.Repo.Release(finish, job) stop() return } failure := "" if job.Kind == "evaluate" && e.Mode == "bank" && (errors.Is(err, store.ErrAIBudget) || errors.Is(err, store.ErrAIDisabled)) { err = e.Repo.Ungrade(finish, job.UserID, job.SubjectID) } if err != nil { e.Logger.Warn("course job failed", "job_id", job.ID, "kind", job.Kind, "error", err) failure = AIErrorSafe(err) if job.Kind == "evaluate" { _ = e.Repo.FailAttempt(finish, job.UserID, job.SubjectID) } } if err := e.Repo.Finish(finish, job, task, failure); err != nil { e.Logger.Warn("course job result not saved", "job_id", job.ID, "error", err) } stop() } } func (e *CourseEngine) snapshot(ctx context.Context, j domain.CourseJob) (domain.CourseSnapshot, error) { user, err := e.Profiles.GetUser(ctx, j.UserID) if err != nil { return domain.CourseSnapshot{}, err } instructionLanguage := j.InstructionLanguage if instructionLanguage == "" { instructionLanguage = user.ExplanationLanguage() } return e.Repo.Snapshot(ctx, j.UserID, j.Language, instructionLanguage) } func (e *CourseEngine) analyze(ctx context.Context, j domain.CourseJob) (domain.CourseSnapshot, error) { snapshot, err := e.snapshot(ctx, j) if err != nil { return snapshot, err } if snapshot.PreviousAnalysis != nil && snapshot.PreviousAnalysis.FactsVersion == snapshot.FactsVersion { return snapshot, nil } if err = e.Repo.Stage(ctx, j, "analyzing"); err != nil { return snapshot, err } var analysis domain.CourseAnalysis if err = e.Agent.Teacher(ctx, "analyze_course_progress", snapshot, &analysis); err != nil { return snapshot, err } if err = ValidateCourseAnalysis(&analysis, snapshot); err != nil { return snapshot, err } if err = e.Repo.SaveAnalysis(ctx, j.UserID, analysis); err != nil { return snapshot, err } snapshot.PreviousAnalysis = &analysis return snapshot, nil } func (e *CourseEngine) Process(ctx context.Context, j domain.CourseJob) (*domain.AdaptiveTask, error) { if e.Mode == "bank" { switch j.Kind { case "next", "legacy_next": t, err := e.Repo.AssignBankTask(ctx, j) if errors.Is(err, store.ErrNotFound) { t, err = e.Repo.Reserve(ctx, j.UserID, j.Language, j.ModuleID, j.Skill) } if err == nil && j.Kind == "legacy_next" && t.Kind != "choice" { t, err = e.Repo.Reserve(ctx, j.UserID, j.Language, j.ModuleID, "vocabulary") } return &t, err case "exam": if j.InstructionLanguage != "" && j.InstructionLanguage != "de-DE" { return nil, store.ErrCourseVariantUnavailable } tasks, err := e.Repo.BankExam(ctx, j.UserID, j.Language, j.ModuleID) if errors.Is(err, store.ErrNotFound) { tasks, err = e.Repo.ReserveExam(ctx, j.UserID, j.Language, j.ModuleID) } if err != nil { return nil, err } if err = ValidateExamTasks(tasks, j.Language, j.ModuleID); err != nil { return nil, err } return nil, e.Repo.SaveExamTasks(ctx, j.UserID, j.Language, j.SubjectID, tasks) case "evaluate": attempt, err := e.Repo.Attempt(ctx, j.UserID, j.Language, j.SubjectID) if err != nil { return nil, err } task, err := e.Repo.Task(ctx, j.UserID, j.Language, attempt.TaskID) if err != nil { return nil, err } if task.Kind == "choice" { return nil, e.evaluate(ctx, j) } if !e.EvaluationAvailable(ctx) { if err = e.Repo.Ungrade(ctx, j.UserID, j.SubjectID); err != nil { return nil, err } if attempt.ExamID != "" { return nil, e.completeBankExam(ctx, j.UserID, j.Language, attempt.ExamID) } return nil, nil } case "analyze": return nil, nil case "exam_finalize": return nil, e.completeBankExam(ctx, j.UserID, j.Language, j.SubjectID) } } if agent, ok := e.Agent.(interface { BeginOperation(context.Context, string, string) (context.Context, error) }); ok { var err error ctx, err = agent.BeginOperation(ctx, j.UserID, fmt.Sprintf("%s:%d", j.ID, j.AIRevision)) if err != nil { return nil, err } } switch j.Kind { case "analyze": _, err := e.analyze(ctx, j) return nil, err case "next", "legacy_next": return e.next(ctx, j) case "evaluate": return nil, e.evaluate(ctx, j) case "exam": return nil, e.exam(ctx, j) case "exam_finalize": return nil, e.finalizeExam(ctx, j) default: return nil, errors.New("unknown course job kind") } } func (e *CourseEngine) next(ctx context.Context, j domain.CourseJob) (*domain.AdaptiveTask, error) { if j.TaskID != "" { task, err := e.Repo.Task(ctx, j.UserID, j.Language, j.TaskID) return &task, err } task, err := e.generateOne(ctx, j) if err == nil { e.Logger.Info("course practice selected", "source", task.Source, "task_id", task.ID, "job_id", j.ID) return &task, nil } e.Logger.Warn("course generation fallback", "reason", err.Error(), "job_id", j.ID, "module_id", j.ModuleID, "skill", j.Skill) // Keep a small database budget after an agent deadline; otherwise a slow // model would also cancel the reserve lookup and hide the promised fallback. if errors.Is(ctx.Err(), context.DeadlineExceeded) { var cancel context.CancelFunc ctx, cancel = context.WithTimeout(context.Background(), 5*time.Second) defer cancel() } task, err = e.Repo.Reserve(ctx, j.UserID, j.Language, j.ModuleID, j.Skill) if err != nil { return nil, err } // Legacy clients can render choice tasks only; keep their fallback compatible. if j.Kind == "legacy_next" && task.Kind != "choice" { task, err = e.Repo.Reserve(ctx, j.UserID, j.Language, j.ModuleID, "vocabulary") if err != nil { return nil, err } } e.Logger.Info("course practice selected", "source", "seed", "task_id", task.ID, "job_id", j.ID) return &task, nil } func (e *CourseEngine) generateOne(ctx context.Context, j domain.CourseJob) (domain.AdaptiveTask, error) { snapshot, err := e.analyze(ctx, j) if err != nil { return domain.AdaptiveTask{}, err } if err = e.Repo.Stage(ctx, j, "planning"); err != nil { return domain.AdaptiveTask{}, err } requiredKind := "" if j.Kind == "legacy_next" { requiredKind = "choice" } var brief domain.CourseBrief err = e.Agent.Teacher(ctx, "plan_course_task", map[string]any{"snapshot": snapshot, "analysis": snapshot.PreviousAnalysis, "module_id": j.ModuleID, "requested_skill": j.Skill, "required_kind": requiredKind}, &brief) if err != nil { return domain.AdaptiveTask{}, err } if err = ValidateCourseBrief(brief, snapshot, j.ModuleID, j.Skill); err != nil { return domain.AdaptiveTask{}, err } if requiredKind != "" && brief.Kind != requiredKind { return domain.AdaptiveTask{}, errors.New("planner returned an unsupported legacy format") } brief, err = e.Repo.SaveBrief(ctx, j.UserID, snapshot.FactsVersion, brief) if err != nil { return domain.AdaptiveTask{}, err } // Re-read the persisted brief: the generator's contract is a stored learning // instruction, not an ephemeral assertion hidden in Flowise chat memory. brief, err = e.Repo.Brief(ctx, j.UserID, brief.ID) if err != nil { return domain.AdaptiveTask{}, err } if err = e.Repo.Stage(ctx, j, "generating_and_reviewing"); err != nil { return domain.AdaptiveTask{}, err } input := map[string]any{"count": 1, "brief": brief, "analysis": snapshot.PreviousAnalysis, "curriculum": snapshot.Modules, "ui_language": snapshot.UILanguage, "avoid_prompts": snapshot.RecentPrompts} var tasks []domain.AdaptiveTask for attempt := 0; attempt < 2; attempt++ { tasks, err = e.Agent.Generate(ctx, input) if err == nil { if len(tasks) != 1 { err = errors.New("expected exactly one task") } else { err = ValidateAdaptiveTask(tasks[0], j.Language, j.ModuleID, brief.Skill) if err == nil && tasks[0].Kind != brief.Kind { err = errors.New("task renderer does not match learning brief") } } } if err == nil { break } if attempt == 1 || ctx.Err() != nil { return domain.AdaptiveTask{}, err } input["technical_error"] = "The response did not match the technical contract. Return the requested renderer and complete required fields." } task := tasks[0] task.ID = "" if task.Source != "ai" { task.Source = "flowise" } task.BriefID = brief.ID task.ExamID = "" task.Review = false return e.Repo.SaveTask(ctx, j, task) } func (e *CourseEngine) Submit(ctx context.Context, user, language, taskID, request, answer string, speech *domain.PronunciationResult) (domain.AdaptiveAttempt, *domain.CourseJob, error) { task, err := e.Repo.Task(ctx, user, language, taskID) if err != nil { return domain.AdaptiveAttempt{}, nil, err } if task.Kind == "choice" { selected := "" for _, o := range task.Options { if answer == o.ID || answer == o.Label { selected = o.ID } } if selected == "" { return domain.AdaptiveAttempt{}, nil, errors.New("choose one of the displayed options") } answer = selected } a, err := e.Repo.Submit(ctx, user, request, task, answer, speech) if err != nil { return a, nil, err } if a.Status == "graded" || a.Status == "ungraded" { return a, nil, nil } if task.Kind != "choice" && e.Mode == "bank" && !e.EvaluationAvailable(ctx) { if err = e.Repo.Ungrade(ctx, user, a.ID); err != nil { return a, nil, err } a, err = e.Repo.Attempt(ctx, user, language, a.ID) if a.ExamID != "" { _ = e.completeBankExam(ctx, user, language, a.ExamID) } return a, nil, err } if task.Kind == "choice" { evaluation := domain.CourseEvaluation{Score: 0, Verdict: "incorrect", Feedback: task.AnswerKey.Explanation, Issues: []string{}} if a.Answer == task.AnswerKey.CorrectOptionID { evaluation.Score = 100 evaluation.Verdict = "correct" } if err = e.Repo.Grade(ctx, user, language, a.ID, evaluation); err != nil { return a, nil, err } a, err = e.Repo.Attempt(ctx, user, language, a.ID) if err != nil { return a, nil, err } e.afterGrade(ctx, user, language, a) return a, nil, nil } job, err := e.Repo.Enqueue(ctx, user, language, "evaluate", a.ModuleID, a.Skill, a.ID, "evaluation:"+a.ID) return a, &job, err } func (e *CourseEngine) evaluate(ctx context.Context, j domain.CourseJob) error { a, err := e.Repo.Attempt(ctx, j.UserID, j.Language, j.SubjectID) if err != nil { return err } if a.Status != "graded" { task, err := e.Repo.Task(ctx, j.UserID, j.Language, a.TaskID) if err != nil { return err } if task.Kind == "choice" { evaluation := domain.CourseEvaluation{Score: 0, Verdict: "incorrect", Feedback: task.AnswerKey.Explanation, Issues: []string{}} if a.Answer == task.AnswerKey.CorrectOptionID { evaluation.Score = 100 evaluation.Verdict = "correct" } if err = e.Repo.Grade(ctx, j.UserID, j.Language, a.ID, evaluation); err != nil { return err } e.afterGrade(ctx, j.UserID, j.Language, a) return nil } snapshot, err := e.snapshot(ctx, j) if err != nil { return err } if err = e.Repo.Stage(ctx, j, "evaluating"); err != nil { return err } var evaluation domain.CourseEvaluation err = e.Agent.Teacher(ctx, "evaluate_course_attempt", courseEvaluationInput(task, a, j.Language, snapshot.UILanguage), &evaluation) if err != nil { return err } if err = ValidateCourseEvaluation(evaluation); err != nil { return err } if err = e.Repo.Grade(ctx, j.UserID, j.Language, a.ID, evaluation); err != nil { return err } } e.afterGrade(ctx, j.UserID, j.Language, a) return nil } func (e *CourseEngine) afterGrade(ctx context.Context, user, language string, a domain.AdaptiveAttempt) { if e.Mode == "bank" { if a.ExamID != "" { if err := e.completeBankExam(ctx, user, language, a.ExamID); err != nil { e.Logger.Warn("exam completion failed", "error", err) } } return } var err error if a.ExamID != "" { _, err = e.Repo.Enqueue(ctx, user, language, "exam_finalize", a.ModuleID, "", a.ExamID, "finalize:"+a.ExamID) // A first early finalizer must not block the final answer from scheduling it. if err == nil { _ = e.Repo.ResetFinalizer(ctx, user, a.ExamID) } } else { snapshot, snapErr := e.Repo.Snapshot(ctx, user, language, "") if snapErr != nil { err = snapErr } else { _, err = e.Repo.Enqueue(ctx, user, language, "analyze", "", "", "", fmt.Sprintf("analysis:%s:%d", language, snapshot.FactsVersion)) } } if err != nil { e.Logger.Warn("course learning update enqueue failed", "error", err) } } // A configured evaluator is optional. Missing configuration/budget must not turn // a saved open response into an invented zero or a failed learning result. func (e *CourseEngine) EvaluationAvailable(ctx context.Context) bool { if a, ok := e.Agent.(*AIService); ok { p, err := a.Repo.Profiles(ctx) if err != nil { return false } v := p["evaluate_course_attempt"] if !v.Enabled || v.Model == "" || !v.PricingSet || !a.Configured(v.Provider) { return false } b, err := a.Repo.Budget(ctx) if err != nil { return false } price := v.InputPrice if v.OutputPrice > price { price = v.OutputPrice } reserve := aiTokenCost(v.ContextTokens, price) + 3 return b.MonthlyLimit > 0 && b.MonthlyLimit-b.MonthCommitted >= reserve && (b.DailyLimit == 0 || b.DailyLimit-b.DayCommitted >= reserve) } return e.Agent != nil } func (e *CourseEngine) exam(ctx context.Context, j domain.CourseJob) error { exam, err := e.Repo.Exam(ctx, j.UserID, j.Language, j.SubjectID) if err != nil { return err } if exam.Status != "preparing" { return nil } snapshot, err := e.analyze(ctx, j) var tasks []domain.AdaptiveTask if err == nil { if stageErr := e.Repo.Stage(ctx, j, "generating_and_reviewing_exam"); stageErr != nil { return stageErr } tasks, err = e.Agent.Generate(ctx, map[string]any{"count": 12, "exam": true, "module_id": j.ModuleID, "target_language": j.Language, "course_version": domain.CourseVersion, "cefr_level": "A1", "ui_language": snapshot.UILanguage, "curriculum": snapshot.Modules, "analysis": snapshot.PreviousAnalysis, "requirements": "Exactly two tasks per skill. Cover the six learning modules. Freeze tasks and rubrics before the session starts."}) if err == nil { err = ValidateExamTasks(tasks, j.Language, j.ModuleID) } } if err != nil { e.Logger.Warn("course exam reserve selected", "reason", err.Error()) if errors.Is(ctx.Err(), context.DeadlineExceeded) { var cancel context.CancelFunc ctx, cancel = context.WithTimeout(context.Background(), 10*time.Second) defer cancel() } tasks, err = e.Repo.ReserveExam(ctx, j.UserID, j.Language, j.ModuleID) if err != nil { return err } } else { for i := range tasks { if tasks[i].Source != "ai" { tasks[i].Source = "flowise" } tasks[i].BriefID = "" tasks[i].Review = false } } return e.Repo.SaveExamTasks(ctx, j.UserID, j.Language, j.SubjectID, tasks) } func ValidateExamTasks(tasks []domain.AdaptiveTask, language, module string) error { if len(tasks) != 12 { return errors.New("exam requires twelve tasks") } skills := map[string]int{} origins := map[string]bool{} for _, t := range tasks { if err := ValidateAdaptiveTask(t, language, module, ""); err != nil { return err } skills[t.Skill]++ if !courseMember(t.OriginModuleKey, []string{"introductions", "family", "numbers_time", "daily_life", "food_shopping", "home_city"}) { return errors.New("exam origin is not a learning module") } origins[t.OriginModuleKey] = true } for _, skill := range domain.CourseSkills { if skills[skill] != 2 { return errors.New("exam requires two tasks per skill") } } if len(origins) != 6 { return errors.New("exam must cover the six learning modules") } return nil } func (e *CourseEngine) finalizeExam(ctx context.Context, j domain.CourseJob) error { _, err := e.Repo.CompleteExam(ctx, j.UserID, j.Language, j.SubjectID) if err != nil { return err } exam, err := e.Repo.Exam(ctx, j.UserID, j.Language, j.SubjectID) if err != nil { return err } if exam.Status != "completed" { return nil } user, err := e.Profiles.GetUser(ctx, j.UserID) if err != nil { return err } var summary struct { Summary string `json:"summary"` } err = e.Agent.Teacher(ctx, "summarize_course_exam", map[string]any{"target_language": j.Language, "ui_language": valueOr(j.InstructionLanguage, user.ExplanationLanguage()), "exam": exam}, &summary) if err != nil { return err } if !courseText(summary.Summary, 6000) { return errors.New("invalid exam summary") } if err = e.Repo.ExamSummary(ctx, j.UserID, j.SubjectID, summary.Summary); err != nil { return err } snapshot, err := e.Repo.Snapshot(ctx, j.UserID, j.Language, user.ExplanationLanguage()) if err != nil { return err } _, err = e.Repo.Enqueue(ctx, j.UserID, j.Language, "analyze", "", "", "", fmt.Sprintf("analysis:%s:%d", j.Language, snapshot.FactsVersion)) return err } // PublicAttempt withholds all evaluation data during an unfinished exam. func (e *CourseEngine) PublicAttempt(ctx context.Context, user, language string, a domain.AdaptiveAttempt) (domain.AdaptiveAttempt, error) { if a.ExamID != "" { exam, err := e.Repo.Exam(ctx, user, language, a.ExamID) if err != nil { return a, err } if exam.Status != "completed" { a.Evaluation = nil a.Speech = nil } } return a, nil } func (e *CourseEngine) completeBankExam(ctx context.Context, user, language, id string) error { _, err := e.Repo.CompleteExam(ctx, user, language, id) if err != nil { return err } return e.Repo.EnsureBankExamSummary(ctx, user, id) }