diff --git a/mds/v28-pro-max-architecture.md b/mds/v28-pro-max-architecture.md new file mode 100644 index 0000000..bf577f8 --- /dev/null +++ b/mds/v28-pro-max-architecture.md @@ -0,0 +1,370 @@ +# V28-Pro-Max Model Architecture Documentation + +> **Model Version:** `v28-pro-max` +> **Engine File:** `ai-engine/services/single_match_orchestrator.py` (4656 satır) +> **Son Güncelleme:** 2026-04-24 + +--- + +## 1. Genel Bakış + +V28-Pro-Max, üç bağımsız tahmin katmanını (V25, V27, V28) tek bir orchestrator içinde birleştiren **üçlü hibrit AI tahmin motorudur**. Her maç için 13+ bahis pazarını analiz eder, olasılık hesaplar, risk değerlendirir ve "Value Bet" tespiti yapar. + +``` +┌─────────────────────────────────────────────────────┐ +│ SingleMatchOrchestrator │ +│ │ +│ ┌──────────┐ ┌──────────┐ ┌────────────────┐ │ +│ │ V25 │ │ V27 │ │ V28 │ │ +│ │ Ensemble │ │ Dual-Eng │ │ Odds-Band │ │ +│ │ (XGB+LGB)│ │ Divergnce│ │ Historical │ │ +│ └────┬─────┘ └────┬─────┘ └───────┬────────┘ │ +│ │ │ │ │ +│ └──────────────┼────────────────┘ │ +│ ▼ │ +│ FullMatchPrediction │ +│ │ │ +│ ┌───────────┼───────────┐ │ +│ ▼ ▼ ▼ │ +│ Market Rows Risk Calc Triple Value │ +│ │ │ │ │ +│ └───────────┼───────────┘ │ +│ ▼ │ +│ _build_prediction_package() │ +│ → JSON Response (v28-pro-max) │ +└─────────────────────────────────────────────────────┘ +``` + +--- + +## 2. Katman Detayları + +### 2.1 V25 — Ensemble ML Katmanı +**Dosya:** `ai-engine/models/v25_ensemble.py` + +- **Algoritmalar:** XGBoost + LightGBM ensemble +- **Girdi:** Pre-match feature vektörü (form, elo, odds, kadro, hakem vb.) +- **Çıktı:** Tüm pazarlar için olasılık dağılımları + confidence skorları +- **Özellik:** Odds-aware (bahis oranlarını feature olarak kullanır) +- **Target leakage koruması:** Maç sonucu bilgisi asla feature olarak kullanılmaz + +```python +# V25 çağrılma noktası (orchestrator L310-315) +v25_signal = v25_predictor.predict(features) +# Çıktı: {MS: {home: 0.45, draw: 0.28, away: 0.27}, OU25: {...}, BTTS: {...}, ...} +``` + +### 2.2 V27 — Dual-Engine Divergence Katmanı +**Dosya:** `ai-engine/models/v27_predictor.py` + +- **Amaç:** Odds-FREE temel olasılıkları hesaplar (sadece form/elo/kadro) +- **Mekanizma:** V25 (odds-aware) vs V27 (odds-free) karşılaştırması +- **Divergence Tespiti:** İki motor arasındaki fark → bahisçinin fiyatlandırma hatasını tespit eder +- **Çıktı:** `ms_divergence`, `ou25_divergence`, `is_value` sinyalleri + +```python +# Divergence hesaplama (orchestrator L830-863) +ms_divergence = { + "home": v25_home_prob - v27_home_prob, # Pozitif = V25 bahisçiyle hemfikir + "away": v25_away_prob - v27_away_prob, # Negatif = Model bahisçiden farklı düşünüyor +} +ms_value = { + "home": {"is_value": v27_home > implied_home and abs(div) > 0.05}, + "away": {"is_value": v27_away > implied_away and abs(div) > 0.05}, +} +``` + +### 2.3 V28 — Odds-Band Historical Performance Katmanı +**Dosya:** `ai-engine/features/odds_band_analyzer.py` + +- **Amaç:** "Bu oran bandında tarihsel olarak ne oldu?" sorusunu yanıtlar +- **Mekanizma:** Maçın mevcut oranını bir banda yerleştirir (ör: MS Home 1.70-1.90), ardından veritabanındaki aynı banddaki geçmiş maçları sorgular +- **Sorgu:** PostgreSQL üzerinden takım-spesifik tarihsel performans + +```python +# OddsBandAnalyzer.compute_all() çıktısı — 18 pazar için band metrikleri: +{ + "home_band_ms_win_rate": 0.62, # Ev sahibi bu oran bandında %62 kazanmış + "home_band_ms_sample": 34, # 34 maçlık örneklem + "band_ou25_over_rate": 0.58, # Bu banddaki maçların %58'i 2.5 üst + "band_btts_yes_rate": 0.51, # KG Var oranı + "band_htft_11_rate": 0.28, # İY/MS 1/1 oranı + "band_cards_referee_avg": 4.2, # Hakem kart ortalaması + # ... toplam 60+ feature +} +``` + +--- + +## 3. Analiz Edilen Bahis Pazarları (13+) + +| # | Pazar | Kod | Olasılık Alanları | Odds Anahtarları | +|---|-------|-----|-------------------|------------------| +| 1 | Maç Sonucu | `MS` | home/draw/away | ms_h, ms_d, ms_a | +| 2 | Çifte Şans | `DC` | 1X/X2/12 | dc_1x, dc_x2, dc_12 | +| 3 | Üst/Alt 1.5 | `OU15` | over/under | ou15_o, ou15_u | +| 4 | Üst/Alt 2.5 | `OU25` | over/under | ou25_o, ou25_u | +| 5 | Üst/Alt 3.5 | `OU35` | over/under | ou35_o, ou35_u | +| 6 | Karşılıklı Gol | `BTTS` | yes/no | btts_y, btts_n | +| 7 | İlk Yarı Sonucu | `HT` | 1/X/2 | ht_h, ht_d, ht_a | +| 8 | İY/MS (9 kombo) | `HTFT` | 1/1, 1/X, 1/2, X/1, X/X, X/2, 2/1, 2/X, 2/2 | htft_11..htft_22 | +| 9 | Tek/Çift | `OE` | odd/even | oe_odd, oe_even | +| 10 | İY Üst/Alt 0.5 | `HT_OU05` | over/under | ht_ou05_o, ht_ou05_u | +| 11 | İY Üst/Alt 1.5 | `HT_OU15` | over/under | ht_ou15_o, ht_ou15_u | +| 12 | Kartlar | `CARDS` | over/under | cards_o, cards_u | +| 13 | Handikap | `HCAP` | 1/X/2 | hcap_h, hcap_d, hcap_a | + +--- + +## 4. Triple Value Detection (V28 Ana Yeniliği) + +V28'in en kritik özelliği: **3 bağımsız kaynağı çapraz kontrol ederek "gerçek değer" tespiti yapması.** + +``` +Triple Value = V27 Divergence + V28 Band Rate + Odds Implied Probability + +Koşullar (hepsi sağlanmalı): + 1. V27 olasılığı > bahisçi implied olasılığı (v27_confirms) + 2. Band tarihsel oranı > implied olasılık (band_confirms) + 3. Kombine edge > %5 (edge > 0.05) + 4. Band örneklem >= 8 maç (band_sample >= 8) + +→ Tüm koşullar sağlanırsa: is_value = True +``` + +**Örnek:** +``` +Galatasaray vs Beşiktaş — MS Home (1.85 oran) +├── Implied Prob: 1/1.85 = 0.54 (%54) +├── V27 (odds-free): 0.61 (%61) → ✅ V27 confirms (0.61 > 0.54) +├── V28 Band Rate: 0.62 (%62, 34 maç) → ✅ Band confirms (0.62 > 0.54) +├── Combined Prob: (0.61 + 0.62) / 2 = 0.615 +├── Edge: 0.615 - 0.54 = 0.075 (%7.5) → ✅ Edge > 5% +└── is_value = TRUE → "Bu bahis değerli!" +``` + +--- + +## 5. Market Row Dekorasyon Pipeline'ı + +Her pazar aşağıdaki pipeline'dan geçer: + +``` +_build_market_rows() → Ham market row'ları oluştur (13 pazar) + ↓ +_apply_market_consistency() → Pazarlar arası tutarlılık kontrolü + ↓ +_decorate_market_row() → Her row'a playability, grading, staking ekle + ↓ +Sort by (playable, play_score) → En iyi pick'ler başa gelir +``` + +### 5.1 Decorate Market Row — Quant Hybrid Sistemi + +Her market row şu metriklerle dekore edilir: + +| Metrik | Formül | Açıklama | +|--------|--------|----------| +| `calibrated_confidence` | `raw_conf × market_calibration` | Kalibre edilmiş güven | +| `ev_edge` | `(prob × odds) - 1.0` | Expected Value edge | +| `simple_edge` | `prob - (1/odds)` | Basit olasılık farkı | +| `play_score` | `cal_conf + (edge × 100 × edge_mult) - penalties` | Oynanabilirlik skoru | +| `stake_units` | Quarter-Kelly Criterion | Önerilen bahis miktarı | +| `bet_grade` | A/B/C/PASS | EV edge bazlı not | + +### 5.2 Playability Gates (Güvenlik Kapıları) + +Bir market row'un "playable" olması için tüm kapılardan geçmesi gerekir: + +1. **Confidence Gate:** `calibrated_conf >= min_conf` (pazar bazlı eşik) +2. **Odds Gate:** Odds-required pazarlarda `odds > 1.01` +3. **Risk-Quality Gate:** HIGH/EXTREME risk + LOW kalite → BLOK +4. **Negative Edge Gate:** `simple_edge < neg_threshold` → BLOK +5. **EV Edge Gate:** `ev_edge < min_edge` → BLOK +6. **Play Score Gate:** `play_score < min_play_score` → BLOK + +### 5.3 Kelly Criterion Staking + +```python +# Quarter-Kelly (¼ Kelly, 10-unit bankroll) +f* = ((b × p) - q) / b # Full Kelly +stake = f* × 0.25 × 10 # Quarter Kelly × bankroll +stake = min(stake, 3.0) # Cap: max 3 unit +stake = max(stake, 0.25) # Floor: min 0.25 unit +``` + +--- + +## 6. Guaranteed Pick Logic (V32 Calibration-Aware) + +Ana pick seçimi 4 öncelik sırasıyla yapılır: + +``` +Priority 1: HIGH_ACCURACY markets (DC, OU15, HT_OU05) + + Odds >= 1.30 + Confidence >= 44% + → is_guaranteed = True, reason = "high_accuracy_market" + +Priority 2: Any playable + Odds >= 1.30 + Conf >= 44% + → is_guaranteed = True, reason = "confidence_threshold_met" + +Priority 3: Any playable + Odds >= 1.30 + → is_guaranteed = False, reason = "odds_only_fallback" + +Priority 4: Best non-playable (last resort) + → is_guaranteed = False, reason = "last_resort" +``` + +**Value Pick:** `main_pick`'ten farklı, odds >= 1.60, confidence >= %40 olan en iyi alternatif. + +**Aggressive Pick:** HT/FT reversal senaryoları (1/2, 2/1, X/1, X/2) arasından en yüksek olasılıklı. + +--- + +## 7. Risk Assessment Sistemi + +```python +risk_score = 100 - max_market_conf + lineup_penalty + referee_penalty + parity_penalty + +# Penalty'ler: +lineup_penalty = 12.0 (kadro yok) | 7.0 (probable_xi) | 0.0 (confirmed) +referee_penalty = 6.0 (hakem yok) | 0.0 +parity_penalty = 8.0 (|ms_edge| < 0.08) | 0.0 + +# Risk seviyeleri: +EXTREME: score >= 78 +HIGH: score >= 62 +MEDIUM: score >= 40 +LOW: score < 40 +``` + +### Surprise Risk Tespiti +- `is_surprise_risk = True` → Risk HIGH/EXTREME VEYA draw_prob >= %30 +- `surprise_type`: `balanced_match_risk` veya `draw_pressure` + +--- + +## 8. xG ve Skor Tahmini + +```python +base_home_xg = (home_goals_avg + away_xga) / 2 +base_away_xg = (away_goals_avg + home_xga) / 2 + +# MS edge ve BTTS etkisiyle düzeltme: +home_xg = base_home_xg + (ms_edge × 0.55) + (btts_prob - 0.5) × 0.18 +away_xg = base_away_xg - (ms_edge × 0.55) + (btts_prob - 0.5) × 0.18 + +# Liga ortalamasıyla ölçekleme: +total_target = league_avg_goals × 0.55 + team_avgs × 0.45 + ou25_signal × 1.15 +scale = total_target / (home_xg + away_xg) +final_home_xg = home_xg × scale +final_away_xg = away_xg × scale + +# Skor tahmini: +FT = round(home_xg) - round(away_xg) +HT = round(home_xg × 0.45) - round(away_xg × 0.45) +Top5 = Poisson dağılımı ile en olası 5 skor +``` + +--- + +## 9. Data Quality Skoru + +```python +quality_score = odds_score × 0.35 + lineup_score × 0.35 + ref_score × 0.15 + form_score × 0.15 + +# Etiketleme: +HIGH: score >= 0.75 +MEDIUM: score >= 0.45 +LOW: score < 0.45 +``` + +--- + +## 10. Çıktı JSON Kontratı + +```json +{ + "model_version": "v28-pro-max", + "match_info": { "match_id", "home_team", "away_team", "league", ... }, + "data_quality": { "label", "score", "lineup_source", "flags" }, + "risk": { "level", "score", "is_surprise_risk", "warnings" }, + "engine_breakdown": { "team", "player", "odds", "referee" }, + "main_pick": { "market", "pick", "confidence", "odds", "ev_edge", "bet_grade", "is_guaranteed" }, + "value_pick": { ... }, + "aggressive_pick": { "market": "HT/FT", "pick": "1/2", ... }, + "bet_advice": { "playable", "suggested_stake_units", "reason" }, + "bet_summary": [ { "market", "pick", "calibrated_confidence", "bet_grade", "ev_edge", ... } ], + "supporting_picks": [ ... ], + "score_prediction": { "ft", "ht", "xg_home", "xg_away", "xg_total" }, + "scenario_top5": [ "1-0", "2-1", ... ], + "market_board": { "MS": {...}, "DC": {...}, "OU25": {...}, ... }, + "v25_signal": { "available", "markets", "value_bets" }, + "reasoning_factors": [ ... ] +} +``` + +--- + +## 11. League-Specific Odds Reliability (V31) + +Bazı liglerin bahis oranları daha güvenilirdir. Bu bilgi `_decorate_market_row` içinde edge ağırlıklandırmasında kullanılır: + +```python +odds_rel = league_reliability.get(league_id, 0.35) # 0.0 - 1.0 +edge_multiplier = 0.60 + (odds_rel × 0.60) # 0.60 - 1.20 + +# Güvenilir lig → edge daha fazla ağırlık alır +# Güvenilsiz lig → model confidence'a daha çok güvenilir +``` + +--- + +## 12. Dosya Haritası + +``` +ai-engine/ +├── services/ +│ └── single_match_orchestrator.py ← Ana orchestrator (4656 satır) +├── models/ +│ ├── v25_ensemble.py ← XGBoost + LightGBM ensemble +│ └── v27_predictor.py ← Odds-free fundamental predictor +├── features/ +│ └── odds_band_analyzer.py ← V28 tarihsel band analizi +└── main.py ← FastAPI endpoint (/predict) +``` + +--- + +## 13. Akış Özeti + +``` +HTTP POST /predict {match_id} + │ + ▼ +SingleMatchOrchestrator.analyze_match(match_id) + │ + ├── _load_match_data() → DB'den maç + odds + kadro + form + │ + ├── V25: v25_predictor.predict(features) + │ → 13 pazar olasılık + confidence + │ + ├── V27: v27_predictor.predict(features) + │ → Odds-free MS/OU25 olasılıkları + │ → Divergence hesaplama + │ + ├── V28: odds_band_analyzer.compute_all() + │ → 18 pazar için tarihsel band metrikleri + │ + ├── Triple Value Detection + │ → V27 + V28 + Implied çapraz kontrol + │ + ├── _enrich_prediction() → xG, risk, skor tahmini + │ + ├── _build_market_rows() → 13+ ham market row + ├── _apply_market_consistency() + ├── _decorate_market_row() → EV, Kelly, grading + │ + ├── Guaranteed Pick Selection → main_pick, value_pick, aggressive_pick + │ + └── _build_prediction_package() → Final JSON kontratı +```