Files
Speech/apps/api/internal/pronunciation/profile.go
T
Eugenius Naumenko 16cceae28a Muttersprache koppeln und russischen A1-Kurs ergänzen
GUI und neue Erklärungen verwenden gemeinsam native_language. Deutsch und
Russisch sind die beiden Muttersprachen; Englisch bleibt die Lernsprache.
Kompatibilitätsfelder werden atomar gekoppelt, widersprüchliche Eingaben
abgewiesen und bestehende Profile sowie eingefrorene Inhalte erhalten.

Ergänzt vollständige russische GUI-Kataloge und 840 geprüfte Aufgabenansichten
in sieben Modulen einschließlich A1-Test, mit getrennten Sprachrollen für
Ausgangs- und Lernmaterial. Äquivalente Ansichten teilen ihre Nachweisidentität.
Stabile API-Fehlercodes, neue deterministische Hilfen und Trainingsbegründungen
berücksichtigen die Muttersprache. Dokumentiert das Sprachmodell in AGENTS.md.

Validierung: Go-Race-Suite mit eigener lokaler PostgreSQL-Testdatenbank, go vet,
Web-Build, Offline-Bank-/Variantenaudit, Diff-Prüfung sowie lokale Browser-Smokes
für Sprachen, Kurs, Administration, Aussprache und Aufnahme. Keine Live-Anbieter,
Produktionsprofile, Deployment-Schritte oder historischen Neubewertungen.
2026-11-07 17:02:17 +00:00

442 lines
14 KiB
Go

// 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)
}
}