update

.planer/einheiten/backend__tft__model__learn.py.md

@@ -0,0 +1,46 @@
+# Einheiten: backend/tft/model/learn.py
+stand: f41ac76b5789
+
+## backend/tft/model/learn.py::_multiplier
+beschreibung: Berechnet einen um Bayessche Schrumpfung zentrierten Stärke-Multiplikator aus einer Liste von Platzierungen.
+input: eine Liste von Platzierungswerten (Integers)
+output: ein Float-Multiplikator in [0.8, 1.25], der bei 1.0 bei mittlerer Platzierung liegt
+entscheidungen:
+- Schrupfung gegen das Schnitt-Niveau (MEAN_PLACEMENT) erfolgt via PSEUDO_COUNT Pseudo-Beobachtungen.
+  beleg: "(sum(placements) + MEAN_PLACEMENT * PSEUDO_COUNT) / (n + PSEUDO_COUNT)"
+- Pro Platzierungs-Punkt Abweichung vom Mittelwert wird DELTA_SCALE = 0.06 aufaddiert.
+  beleg: "mult = 1.0 + (MEAN_PLACEMENT - mean) * DELTA_SCALE"
+- Der Ergebniswert wird auf das Intervall MULT_CAP = (0.8, 1.25) gekappt.
+  beleg: "return min(max(mult, MULT_CAP[0]), MULT_CAP[1])"
+kanten:
+- wird-genutzt-von: backend/tft/model/learn.py::learn
+
+## backend/tft/model/learn.py::learn
+beschreibung: Aggregiert Endboard-Zeilen zu placementsbezogenen Multiplikatoren für Einheiten, Traits, Items, Augments und Paare.
+input: eine Liste von Tupeln (placement, units_json, traits_json, augments_json)
+output: ein Dict mit Multiplikatoren je Kategorie, signifikanten Paar-Lifts sowie Brett-Zähler
+entscheidungen:
+- Top-4-Paarungen werden nur gezählt, wenn die Beobachtungszahl PAIR_MIN_N erreicht und ein Erwartungswert > 0 vorliegt.
+  beleg: "if n_ab < PAIR_MIN_N:"
+- Nur aktive Traits (tier_current > 0) gehen in die Trait-Aggregation ein.
+  beleg: "if t.get(\"tier_current\", 0) > 0:"
+- Paar-Lifts werden auf PAIR_LIFT_CAP gekappt und auf 4 Nachkommastellen gerundet zurückgegeben.
+  beleg: "lift = min(max(lift, PAIR_LIFT_CAP[0]), PAIR_LIFT_CAP[1])"
+- Alle vier Kategorie-Multiplikatoren werden ebenfalls auf 4 Nachkommastellen gerundet.
+  beleg: "{k: round(_multiplier(v), 4) for k, v in unit_placements.items()},"
+kanten:
+- ruft-auf: backend/tft/model/learn.py::_multiplier
+- wird-genutzt-von: backend/tft/model/learn.py::learn_from_db
+
+## backend/tft/model/learn.py::learn_from_db
+beschreibung: Liest Endboard-Zeilen eines Sets aus einer SQL-Verbindung und gibt das gelernte Multiplikator-Dict zurück.
+input: eine SQL-Connection, eine Set-Nummer und ein Flag zum Ausschluss von Holdout-Matches
+output: das von learn() erzeugte Multiplikator-Dict
+entscheidungen:
+- Bei exclude_holdout werden Matches ausgefiltert, deren match_id auf '0' oder '5' endet.
+  beleg: "where += \" AND substr(match_id, -1) NOT IN ('0', '5')\""
+- Die Selektion projiziert nur die für learn() nötigen Spalten.
+  beleg: "\"SELECT placement, units, traits, augments FROM endboards {where}\""
+kanten:
+- ruft-auf: backend/tft/model/learn.py::learn
+- nutzt: backend/tft/model/learn.py::learn