first (part 2: other directories)

mds/archive/update_v10_6_character_analysis.md

@@ -0,0 +1,86 @@
+# Update Log: v10.6 - Dynamic Team Character Analysis & Reverse Engineering
+
+**Date:** January 23, 2026
+**Version:** v10.6-character
+
+## Overview
+
+This update introduces a sophisticated **Dynamic Odds Character Analysis** system to the AI Engine. Instead of static statistical analysis, the system now performs "Reverse Engineering" on historical data to understand how teams behave under specific odds conditions. This allows for nuanced insights like "Bodo/Glimt often loses as an underdog, but wins specifically in European home games against strong opponents."
+
+## Key Features
+
+### 1. Dynamic Team Character (Dual Analysis)
+
+We now analyze **BOTH** the Home Team and Away Team separately, based on their specific context:
+
+- **Home Team Analysis:**
+  - Finds finding closest 15 historical "Home" matches where the team had similar odds (±0.30 margin).
+  - Calculates Win Rate, BTTS Rate, and Over 2.5 Rate for this specific "Odds Cluster".
+  - **Labels:**
+    - `Banko Ev Sahibi` (Win Rate >= 80%)
+    - `Güvensiz Favori` (Win Rate <= 35% at low odds)
+    - `Underdog (Beklenen)` (High odds, low win rate)
+    - `Golcü Karakter` (BTTS >= 70%)
+- **Away Team Analysis:**
+  - Finds closest 15 historical "Away" matches where the team had similar odds.
+  - Generates separate insights (e.g., Man. City might be "İstikrarlı" away, while their opponent is "Underdog").
+
+### 2. Match Story Integration
+
+The match story generator (`_generate_match_story`) now dynamically acts on these character insights:
+
+- **Narrative Injection:** Adds a dedicated "Takım Karakteri" section at the start of the analysis.
+- **Example Output:**
+  > **Bodo/Glimt Karakteri (Underdog):** Evinde bu oranlarda son 15 maçta %13 galibiyet, %46 KG Var.
+  > **Man. City Karakteri (İstikrarlı):** Deplasmanda bu oranlarda son 15 maçta %73 galibiyet, %53 KG Var.
+
+### 3. Terminology Standardization
+
+Fixed confusing terminology in the API response:
+
+- **Previous:** `KG: Üst/Var`, `2.5 Alt: Üst/Var` (Confusing)
+- **Fixed:**
+  - **KG:** `Var` / `Yok`
+  - **Over/Under:** `Üst` / `Alt`
+
+### 4. Reverse Engineering Script (`reverse_engineer.py`)
+
+Added a standalone script to manually "debug" team psychology:
+
+- Can query specific conditions like "When does Man. City lose away at 1.25 odds?"
+- Used to discover hidden patterns (e.g., Bodo's only underdog win was vs Lazio in Europa League).
+
+## Technical Changes
+
+### Backend (`predictions.service.ts`)
+
+- **Model Version:** Updated to `v10.6-character`.
+- **DTO:** Added `teamCharacter` field to `MatchPredictionDto`.
+- **Mapping:** Now maps Python's `analysis.character` object to the frontend response.
+
+### AI Engine (`train_v10_full.py`)
+
+- **New Method:** `_analyze_odds_character(home_id, away_id, home_odd, away_odd)`
+- **Logic Update:** `predict_match` now fetches odds for both teams and triggers the dual analysis.
+- **Fix:** Resolved `UnboundLocalError` for `officials_df` in live info fetching.
+
+## Usage
+
+The new character analysis runs automatically for every match prediction request where odds data is available.
+
+```json
+"teamCharacter": {
+    "home": {
+        "label": "Underdog (Beklenen)",
+        "win_rate": 13,
+        "btts_rate": 46,
+        "matches": 15
+    },
+    "away": {
+        "label": "İstikrarlı",
+        "win_rate": 73,
+        "btts_rate": 53,
+        "matches": 15
+    }
+}
+```