// Package pronunciation computes versioned, reproducible learning heuristics. // Scores remain provider measurements, never probabilities of proficiency. package pronunciation import ( "fmt" "math" "sort" "strings" "time" "unicode" "golang.org/x/text/unicode/norm" "speech-learning-api/internal/domain" ) func Word(s string) string { return norm.NFC.String(strings.ToLower(strings.TrimFunc(strings.TrimSpace(s), func(r rune) bool { return unicode.IsPunct(r) || unicode.IsSpace(r) }))) } func Key(kind, locale, alphabet, symbol string) string { return kind + ":" + locale + ":" + alphabet + ":" + norm.NFC.String(symbol) } func valid(v float64) bool { return !math.IsNaN(v) && !math.IsInf(v, 0) && v >= 0 && v <= 100 } // Observe preserves occurrence positions. Aggregation, not storage, collapses // repeated sounds and repeat recordings. No phoneme is inferred from spelling. func Observe(id, exercise, language string, at time.Time, r domain.PronunciationResult) []domain.PronunciationObservation { out := []domain.PronunciationObservation{} for wi, w := range r.WordScores { word := Word(w.Word) if word == "" { continue } kind := "word" if strings.EqualFold(w.ErrorType, "Omission") { kind = "omission" } if strings.EqualFold(w.ErrorType, "Insertion") { continue } base := domain.PronunciationObservation{AssessmentID: id, ExerciseID: exercise, Language: language, Locale: r.Locale, Alphabet: r.Alphabet, Word: word, WordIndex: wi, PhonemeIndex: -1, At: at} if kind == "omission" { o := base o.Kind = kind o.Symbol = word o.Accuracy = 0 out = append(out, o) continue } if valid(w.Accuracy) && (w.AccuracyMeasured == nil || *w.AccuracyMeasured) { o := base o.Kind = kind o.Symbol = word o.Accuracy = w.Accuracy out = append(out, o) // Completeness is a separate categorical signal: pronounced words // can resolve prior omissions without inventing phoneme scores. complete := base complete.Kind = "omission" complete.Symbol = word complete.Accuracy = 100 out = append(out, complete) } cursor := 0 for pi, p := range w.PhonemeScores { symbol := norm.NFC.String(strings.TrimSpace(p.Phoneme)) if symbol == "" || !valid(p.Accuracy) || r.Alphabet == "" { continue } o := base o.Kind = "phoneme" o.Symbol = symbol o.PhonemeIndex = pi if p.Position != nil { o.PhonemeIndex = *p.Position } else if len(w.Phonemes) > 0 { o.PhonemeIndex = -1 for cursor < len(w.Phonemes) { index := cursor cursor++ if w.Phonemes[index] == p.Phoneme { o.PhonemeIndex = index break } } } o.Accuracy = p.Accuracy out = append(out, o) } } return out } type sample struct { at time.Time exercise string assessment string values map[string][]float64 } func median(a []float64) float64 { b := append([]float64{}, a...) sort.Float64s(b) n := len(b) if n%2 == 1 { return b[n/2] } return (b[n/2-1] + b[n/2]) / 2 } func sampleMean(s *sample) float64 { sum := 0.0 for _, v := range s.values { sum += median(v) } return sum / float64(len(s.values)) } func Build(language string, now time.Time, observations []domain.PronunciationObservation) domain.PronunciationProfile { p := domain.PronunciationProfile{Algorithm: domain.PronunciationAlgorithm, Language: language, AsOf: now, WindowDays: 90, Targets: []domain.PronunciationTarget{}} // The latest measured occurrence for each target/task/UTC day is an independent unit. // Missing scores in a later recording must not erase an earlier measurement. latest := map[string]domain.PronunciationObservation{} for _, o := range observations { if o.Language != language || o.At.After(now) || o.At.Before(now.AddDate(0, 0, -90)) || !valid(o.Accuracy) { continue } unit := Key(o.Kind, o.Locale, o.Alphabet, o.Symbol) + "/" + o.ExerciseID + "/" + o.At.UTC().Format("2006-01-02") old, ok := latest[unit] if !ok || o.At.After(old.At) || (o.At.Equal(old.At) && o.AssessmentID > old.AssessmentID) { latest[unit] = o } } grouped := map[string]map[string]*sample{} meta := map[string]domain.PronunciationObservation{} raw := map[string]int{} recordings := map[string]bool{} for _, o := range observations { unit := Key(o.Kind, o.Locale, o.Alphabet, o.Symbol) + "/" + o.ExerciseID + "/" + o.At.UTC().Format("2006-01-02") last, ok := latest[unit] if !ok || last.AssessmentID != o.AssessmentID || !valid(o.Accuracy) { continue } recordings[o.AssessmentID] = true key := Key(o.Kind, o.Locale, o.Alphabet, o.Symbol) meta[key] = o raw[key]++ if grouped[key] == nil { grouped[key] = map[string]*sample{} } s := grouped[key][unit] if s == nil { s = &sample{at: o.At, exercise: o.ExerciseID, assessment: o.AssessmentID, values: map[string][]float64{}} grouped[key][unit] = s } s.values[o.Word] = append(s.values[o.Word], o.Accuracy) } p.ConfirmedRecordings = len(recordings) for key, units := range grouped { samples := []*sample{} for _, s := range units { samples = append(samples, s) } sort.Slice(samples, func(i, j int) bool { if samples[i].at.Equal(samples[j].at) { return samples[i].assessment > samples[j].assessment } return samples[i].at.After(samples[j].at) }) if len(samples) > 30 { samples = samples[:30] } o := meta[key] t := domain.PronunciationTarget{Key: key, Kind: o.Kind, Locale: o.Locale, Alphabet: o.Alphabet, Symbol: o.Symbol, Observations: raw[key], Samples: len(samples), Recordings: len(samples), LastSeen: samples[0].at, State: "limited", Trend: "insufficient", Examples: []domain.PronunciationExample{}} type weighted struct { sum, weak, weight float64 count int } words := map[string]*weighted{} tasks := map[string]bool{} bad := 0 for _, s := range samples { tasks[s.exercise] = true weight := math.Exp2(-now.Sub(s.at).Hours() / (24 * 14)) if sampleMean(s) < 75 { bad++ } for word, values := range s.values { v := median(values) w := words[word] if w == nil { w = &weighted{} words[word] = w } w.sum += weight * v w.weight += weight w.count++ if v < 75 { w.weak += weight } } } t.Tasks = len(tasks) t.Words = len(words) for word, w := range words { m := w.sum / w.weight t.Mean += m t.WeakRate += w.weak / w.weight t.Examples = append(t.Examples, domain.PronunciationExample{Word: word, Mean: m, Samples: w.count}) } t.Mean /= float64(t.Words) t.WeakRate /= float64(t.Words) // Do not expose omission targets for words never omitted in the window. if t.Kind == "omission" && bad == 0 { continue } sort.Slice(t.Examples, func(i, j int) bool { if t.Examples[i].Mean == t.Examples[j].Mean { return t.Examples[i].Word < t.Examples[j].Word } return t.Examples[i].Mean < t.Examples[j].Mean }) enough := t.Samples >= 3 && (t.Kind != "phoneme" || t.Words >= 2) if enough { t.State = "observed" if bad >= 2 && t.Mean < 85 { t.State = "needs_practice" } } // Track successful practice and spaced reviews chronologically. A genuine // weak observation resets the schedule, not merely one low historical score. streak := 0 streakWords := map[string]bool{} stage := 0 var due *time.Time intervals := []int{1, 3, 7, 14, 30} for i := len(samples) - 1; i >= 0; i-- { s := samples[i] v := sampleMean(s) if v < 75 { streak = 0 streakWords = map[string]bool{} due = nil stage = 0 continue } if v < 85 { streak = 0 streakWords = map[string]bool{} continue } streak++ for word := range s.values { streakWords[word] = true } if due == nil && streak >= 3 && (t.Kind != "phoneme" || len(streakWords) >= 2) { d := s.at.AddDate(0, 0, intervals[0]) due = &d stage = 0 } else if due != nil && !s.at.Before(*due) { if stage < 4 { stage++ } d := s.at.AddDate(0, 0, intervals[stage]) due = &d } } if due != nil { t.State = "improved" if stage >= 4 { t.State = "stable" } t.NextReview = due t.ReviewDue = !due.After(now) } if len(samples) >= 6 { n := len(samples) / 2 if n > 5 { n = 5 } a, b := 0.0, 0.0 for i := 0; i < n; i++ { a += sampleMean(samples[i]) b += sampleMean(samples[n+i]) } delta := (a - b) / float64(n) t.Trend = "steady" if delta >= 5 { t.Trend = "improving" } else if delta <= -5 { t.Trend = "declining" } } reliability := math.Min(float64(t.Samples)/5, 1) if t.Kind == "phoneme" { reliability *= math.Min(float64(t.Words)/3, 1) } t.Priority = .5*(100-t.Mean)/100 + .3*t.WeakRate + .2*reliability p.Targets = append(p.Targets, t) } sort.Slice(p.Targets, func(i, j int) bool { if p.Targets[i].Priority == p.Targets[j].Priority { return p.Targets[i].Key < p.Targets[j].Key } return p.Targets[i].Priority > p.Targets[j].Priority }) return p } // Select is deterministic for a profile and successful assignment history. // Weighted deficits approximate 60/25/15 without random streaks. func Select(p domain.PronunciationProfile, history []domain.PronunciationPlan, now time.Time) domain.PronunciationPlan { plan := domain.PronunciationPlan{Algorithm: p.Algorithm, Language: p.Language, Category: "explore", Mode: "general", RequiredWords: []string{}, KnownWords: []string{}, Reason: "Allgemeine Aussprachepraxis: noch kein gesichertes Trainingsziel.", CreatedAt: now} candidates := map[string][]domain.PronunciationTarget{"targeted": {}, "review": {}, "explore": {}} for _, t := range p.Targets { if t.ReviewDue { candidates["review"] = append(candidates["review"], t) } if (t.State == "needs_practice" || t.State == "limited" || t.State == "observed") && t.Mean < 75 { candidates["targeted"] = append(candidates["targeted"], t) } if t.Kind == "phoneme" && t.Samples >= 2 { candidates["explore"] = append(candidates["explore"], t) } } counts := map[string]int{} for _, h := range history { counts[h.Category]++ } weights := map[string]float64{"targeted": .6, "review": .25, "explore": .15} chosen := "" best := -1e9 for _, category := range []string{"targeted", "review", "explore"} { if len(candidates[category]) == 0 { continue } d := weights[category]*float64(len(history)+1) - float64(counts[category]) if d > best { best = d chosen = category } } if chosen == "" { return plan } list := candidates[chosen] // Confirmed patterns outrank isolated observations; within each tier profile // priority ranks severity, recurrence and evidence density. sort.SliceStable(list, func(i, j int) bool { a, b := list[i], list[j] if chosen == "review" { return a.NextReview.Before(*b.NextReview) } if (a.State == "needs_practice") != (b.State == "needs_practice") { return a.State == "needs_practice" } if a.Priority == b.Priority { return a.LastSeen.Before(b.LastSeen) } return a.Priority > b.Priority }) target := list[0] if len(history) >= 2 && history[0].Target != nil && history[1].Target != nil && history[0].Target.Key == target.Key && history[1].Target.Key == target.Key { found := false for _, other := range list[1:] { if other.Key != target.Key { target = other found = true break } } if !found { return plan } } plan.Category = chosen plan.Target = &target plan.Mode = "targeted" // Keep the brief bounded; exact public statistics remain in the profile. if len(plan.Target.Examples) > 3 { plan.Target.Examples = plan.Target.Examples[:3] } for _, example := range target.Examples { plan.KnownWords = append(plan.KnownWords, example.Word) } if chosen == "explore" { plan.Mode = "transfer" plan.TransferStatus = "unconfirmed" plan.Reason = fmt.Sprintf("Übertrage den gemessenen Laut /%s/ auf einen neuen Wortkontext; die Zuordnung wird erst durch Azure geprüft.", target.Symbol) } else { word := target.Examples[0].Word plan.RequiredWords = []string{word} if chosen == "review" { plan.Reason = fmt.Sprintf("Zeitversetzte Wiederholung für %s nach einer beobachteten Verbesserung.", label(target)) } else if target.State == "needs_practice" { plan.Reason = fmt.Sprintf("%s ist in %d unabhängigen Beobachtungen wiederholt schwierig.", label(target), target.Samples) } else { plan.Reason = fmt.Sprintf("%s nachprüfen: bisher wenige oder uneinheitliche Nachweise.", label(target)) } } return plan } func label(t domain.PronunciationTarget) string { if t.Kind == "phoneme" { return "Laut /" + t.Symbol + "/" } if t.Kind == "omission" { return "Vollständigkeit beim Wort „" + t.Symbol + "“" } return "Wort „" + t.Symbol + "“" } // SetNativeLanguage formats only the reason of a newly selected plan. Evidence, // priority, required words and historical plans remain unchanged. func SetNativeLanguage(plan *domain.PronunciationPlan, native string) { plan.NativeLanguage = native if native != "ru-RU" { return } if plan.Target == nil { plan.Reason = "Общая практика произношения: пока нет подтверждённой цели тренировки." return } target := plan.Target label := "Слово «" + target.Symbol + "»" if target.Kind == "phoneme" { label = "Звук /" + target.Symbol + "/" } if target.Kind == "omission" { label = "Полнота произнесения слова «" + target.Symbol + "»" } switch { case plan.Mode == "transfer": plan.Reason = fmt.Sprintf("Потренируйте измеренный звук /%s/ в новом слове; соответствие ещё должно быть проверено Azure.", target.Symbol) case plan.Category == "review": plan.Reason = fmt.Sprintf("Повторение после перерыва: %s. Ранее наблюдалось улучшение.", label) case target.State == "needs_practice": plan.Reason = fmt.Sprintf("%s: повторные затруднения в независимых наблюдениях (%d).", label, target.Samples) default: plan.Reason = fmt.Sprintf("%s: нужна дополнительная проверка, пока наблюдений мало или они неоднородны.", label) } }