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.
This commit is contained in:
Eugenius Naumenko
2026-11-01 23:23:20 +00:00
parent 83944f791e
commit e274eaab2b
186 changed files with 46676 additions and 257 deletions
@@ -0,0 +1,580 @@
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
}
return e.Repo.Snapshot(ctx, j.UserID, j.Language, user.UILanguage)
}
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":
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": user.UILanguage, "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.UILanguage)
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)
}