iddaai-be/mds/v28-pro-max-architecture.md

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

# 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

# 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

# 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

# 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

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

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

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ı

{
  "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:

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ı