First release to Hugging Face

Dockerfile

@@ -0,0 +1,23 @@
+FROM python:3.11-slim
+
+# Set up a working directory
+WORKDIR /code
+
+# Install requirements
+COPY ./requirements.txt /code/requirements.txt
+RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt
+
+# Copy the entire python/model directory into the container
+COPY . /code
+
+# Set permissions for Hugging Face Spaces (runs as user 1000)
+RUN useradd -m -u 1000 user
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH
+
+WORKDIR $HOME/app
+COPY --chown=user . $HOME/app
+
+# Hugging Face Spaces require the app to listen on port 7860
+CMD ["uvicorn", "api:app", "--host", "0.0.0.0", "--port", "7860"]

api.py

@@ -0,0 +1,67 @@
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from typing import List, Optional
+from pydantic import BaseModel
+import os
+
+from predict import get_predictions
+
+app = FastAPI(title="2026 World Cup Prediction API", version="1.0.0")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],  # Allow all origins for local dev; can restrict later
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+class PredictionModel(BaseModel):
+    match_id: str
+    home_team_id: str
+    away_team_id: str
+    prob_home_win: float
+    prob_draw: float
+    prob_away_win: float
+    manual_features_applied: bool = False
+
+class SkippedMatchModel(BaseModel):
+    match_id: str
+    home_team_id: Optional[str] = None
+    away_team_id: Optional[str] = None
+    reason: str
+
+class PredictionResponse(BaseModel):
+    predictions: List[PredictionModel]
+    skipped: List[SkippedMatchModel]
+    predictions_count: int
+    skipped_count: int
+
+@app.get("/api/predict", response_model=PredictionResponse)
+def predict_upcoming():
+    """
+    Returns Win/Draw/Loss probabilities for all scheduled/active matches where
+    both teams are known.
+    """
+    try:
+        # Resolve artifacts path relative to the current file
+        current_dir = os.path.dirname(os.path.abspath(__file__))
+        artifacts_dir = os.path.join(current_dir, "artifacts")
+        
+        data = get_predictions(model_dir=artifacts_dir)
+        
+        return {
+            "predictions": data["predictions"],
+            "skipped": data["skipped"],
+            "predictions_count": len(data["predictions"]),
+            "skipped_count": len(data["skipped"])
+        }
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=503, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Internal prediction error: {str(e)}")
+
+# Add a simple health check
+@app.get("/api/health")
+def health():
+    return {"status": "ok"}

data_loader.py

@@ -0,0 +1,67 @@
+import os
+import pandas as pd
+from dotenv import load_dotenv
+from sqlalchemy import create_engine
+
+load_dotenv('../../.env.local')
+
+class DataLoader:
+    def __init__(self):
+        db_url = os.getenv("SUPABASE_DB_URL")
+        if not db_url:
+            raise ValueError("SUPABASE_DB_URL not found in .env.local")
+        # SQLAlchemy requires postgresql:// instead of postgres:// in some versions, 
+        # but supabase usually provides postgresql://
+        self.engine = create_engine(db_url)
+
+    def get_rankings(self):
+        query = """
+            SELECT team_id, rating, rank 
+            FROM worldcup_team_rankings
+        """
+        df = pd.read_sql(query, self.engine)
+        return df.set_index('team_id')
+
+    def get_team_form(self):
+        query = """
+            SELECT team_id, match_date, opponent_elo, goals_for, goals_against, is_home 
+            FROM worldcup_team_form
+            ORDER BY team_id, match_date DESC
+        """
+        return pd.read_sql(query, self.engine)
+
+    def get_teams(self):
+        query = """
+            SELECT id as team_id, is_host 
+            FROM worldcup_teams
+        """
+        df = pd.read_sql(query, self.engine)
+        return df.set_index('team_id')
+
+    def get_matches(self):
+        query = """
+            SELECT id, stage, round, home_team_id, away_team_id, 
+                   home_score_90, away_score_90, status
+            FROM worldcup_matches
+            WHERE status != 'cancelled'
+        """
+        return pd.read_sql(query, self.engine)
+
+    def get_manual_features(self):
+        query = """
+            SELECT match_id, odds_1x2_home, odds_1x2_draw, odds_1x2_away,
+                   injury_impact_home, injury_impact_away,
+                   lineup_strength_home, lineup_strength_away
+            FROM worldcup_manual_features
+        """
+        df = pd.read_sql(query, self.engine)
+        return df.set_index('match_id')
+
+    def close(self):
+        self.engine.dispose()
+
+if __name__ == "__main__":
+    loader = DataLoader()
+    print("Rankings loaded:", len(loader.get_rankings()))
+    print("Matches loaded:", len(loader.get_matches()))
+    loader.close()

feature_engineer.py

@@ -0,0 +1,136 @@
+import pandas as pd
+import numpy as np
+
+class FeatureEngineer:
+    def __init__(self, rankings_df, form_df, teams_df, manual_features_df=None):
+        self.rankings = rankings_df
+        self.form = form_df
+        self.teams = teams_df
+        self.manual_features = manual_features_df if manual_features_df is not None else pd.DataFrame()
+        
+        self.team_momentum = self._calculate_momentum()
+
+    def _calculate_momentum(self):
+        """
+        Calculate a form momentum score for each team based on their last 10 matches.
+        A win against a strong opponent (high Elo) gives more momentum than against a weak one.
+        """
+        momentum = {}
+        for team_id, group in self.form.groupby('team_id'):
+            # Take up to 10 most recent matches
+            recent = group.head(10).copy()
+            if len(recent) == 0:
+                momentum[team_id] = 0
+                continue
+                
+            # Points: 3 for win, 1 for draw, 0 for loss
+            recent['points'] = np.where(recent['goals_for'] > recent['goals_against'], 3,
+                               np.where(recent['goals_for'] == recent['goals_against'], 1, 0))
+            
+            # Weight points by opponent Elo (normalized roughly around 1500)
+            # E.g., beating an 1800 Elo team gives weight 1.2, a 1200 Elo team gives 0.8
+            recent['weight'] = recent['opponent_elo'] / 1500.0
+            
+            # Weighted average points
+            score = (recent['points'] * recent['weight']).sum() / recent['weight'].sum()
+            momentum[team_id] = score
+            
+        return pd.Series(momentum, name='momentum')
+
+    def engineer_match_features(self, match_id, home_team_id, away_team_id):
+        """
+        Given match_id and home/away team IDs, return a feature dictionary.
+        """
+        # Elo rating
+        if home_team_id not in self.rankings.index:
+            raise ValueError(f"Missing ranking for home team: {home_team_id}")
+        if away_team_id not in self.rankings.index:
+            raise ValueError(f"Missing ranking for away team: {away_team_id}")
+            
+        home_rating = self.rankings.loc[home_team_id, 'rating']
+        away_rating = self.rankings.loc[away_team_id, 'rating']
+        
+        if pd.isna(home_rating) or pd.isna(away_rating):
+            raise ValueError(f"NaN rating for {home_team_id} or {away_team_id}")
+        
+        # Momentum
+        home_mom = self.team_momentum.get(home_team_id, 1.0)
+        away_mom = self.team_momentum.get(away_team_id, 1.0)
+        
+        # Host advantage
+        home_host = 1 if (home_team_id in self.teams.index and self.teams.loc[home_team_id, 'is_host']) else 0
+        away_host = 1 if (away_team_id in self.teams.index and self.teams.loc[away_team_id, 'is_host']) else 0
+        
+        # In World Cup, if home team is host, they have home advantage.
+        # Often neither is host, meaning neutral venue.
+        home_advantage = 1 if home_host else 0
+        
+        # Manual Features Extraction
+        injury_impact_home = 0.0
+        injury_impact_away = 0.0
+        lineup_strength_home = 1.0
+        lineup_strength_away = 1.0
+        odds_implied_home_prob = 0.0
+        odds_implied_away_prob = 0.0
+        
+        if match_id in self.manual_features.index:
+            m_feat = self.manual_features.loc[match_id]
+            injury_impact_home = m_feat.get('injury_impact_home') or 0.0
+            injury_impact_away = m_feat.get('injury_impact_away') or 0.0
+            lineup_strength_home = m_feat.get('lineup_strength_home') or 1.0
+            lineup_strength_away = m_feat.get('lineup_strength_away') or 1.0
+            
+            odds_h = m_feat.get('odds_1x2_home')
+            odds_d = m_feat.get('odds_1x2_draw')
+            odds_a = m_feat.get('odds_1x2_away')
+            
+            # Simple implied probability from odds (1/odds)
+            if pd.notna(odds_h) and pd.notna(odds_d) and pd.notna(odds_a):
+                margin = (1/odds_h) + (1/odds_d) + (1/odds_a)
+                odds_implied_home_prob = (1/odds_h) / margin
+                odds_implied_away_prob = (1/odds_a) / margin
+
+        return {
+            'elo_diff': home_rating - away_rating,
+            'momentum_diff': home_mom - away_mom,
+            'home_advantage': home_advantage,
+            'injury_impact_home': float(injury_impact_home),
+            'injury_impact_away': float(injury_impact_away),
+            'lineup_strength_home': float(lineup_strength_home),
+            'lineup_strength_away': float(lineup_strength_away),
+            'odds_implied_home_prob': float(odds_implied_home_prob),
+            'odds_implied_away_prob': float(odds_implied_away_prob)
+        }
+
+    def build_dataset(self, matches_df):
+        """
+        Build a training dataset from a matches dataframe.
+        """
+        features = []
+        labels = []
+        
+        for _, row in matches_df.iterrows():
+            if pd.isna(row['home_team_id']) or pd.isna(row['away_team_id']):
+                continue
+            
+            try:
+                # Extract features
+                f = self.engineer_match_features(row['id'], row['home_team_id'], row['away_team_id'])
+                # Track the original index to match back easily
+                f['match_id'] = row['id']
+                features.append(f)
+                
+                # Determine label (0: Away Win, 1: Draw, 2: Home Win)
+                if not pd.isna(row['home_score_90']) and not pd.isna(row['away_score_90']):
+                    if row['home_score_90'] > row['away_score_90']:
+                        labels.append(2)
+                    elif row['home_score_90'] == row['away_score_90']:
+                        labels.append(1)
+                    else:
+                        labels.append(0)
+                else:
+                    labels.append(None) # Unplayed
+            except ValueError as e:
+                print(f"Skipping match {row['id']}: {e}")
+                
+        return pd.DataFrame(features), pd.Series(labels)

predict.py

@@ -0,0 +1,95 @@
+import os
+import joblib
+import pandas as pd
+from data_loader import DataLoader
+from feature_engineer import FeatureEngineer
+from rule_based_model import RuleBasedModel
+
+def get_predictions(model_dir='artifacts'):
+    loader = DataLoader()
+    rankings = loader.get_rankings()
+    form = loader.get_team_form()
+    teams = loader.get_teams()
+    matches = loader.get_matches()
+    try:
+        manual_features = loader.get_manual_features()
+    except Exception as e:
+        print(f"WARNING: Could not load manual features: {e}")
+        manual_features = None
+    loader.close()
+    
+    engineer = FeatureEngineer(rankings, form, teams, manual_features)
+    
+    # Select upcoming matches
+    upcoming = matches[matches['status'].isin(['scheduled', 'active'])].copy()
+    if len(upcoming) == 0:
+        return {"predictions": [], "skipped": []}
+        
+    X_pred, _ = engineer.build_dataset(upcoming)
+    
+    # Load model
+    model_path = os.path.join(model_dir, 'rule_based_baseline.pkl')
+    if not os.path.exists(model_path):
+        raise FileNotFoundError(f"Model not found at {model_path}. Run train.py first.")
+        
+    clf = joblib.load(model_path)
+    
+    # Predict probabilities
+    probs = clf.predict_proba(X_pred)
+    
+    X_pred['prob_away_win'] = probs[:, 0]
+    X_pred['prob_draw'] = probs[:, 1]
+    X_pred['prob_home_win'] = probs[:, 2]
+    
+    # Merge back to upcoming by match_id
+    upcoming = upcoming.merge(X_pred[['match_id', 'prob_away_win', 'prob_draw', 'prob_home_win']], left_on='id', right_on='match_id', how='left')
+    
+    results = []
+    skipped = []
+    
+    for _, row in upcoming.iterrows():
+        if pd.isna(row['prob_home_win']):
+            # Determine reason
+            reason = "unknown"
+            if pd.isna(row['home_team_id']) or pd.isna(row['away_team_id']):
+                reason = "missing_team_placeholder"
+            else:
+                reason = "missing_features"
+                
+            skipped.append({
+                "match_id": row['id'],
+                "home_team_id": row['home_team_id'] if not pd.isna(row['home_team_id']) else None,
+                "away_team_id": row['away_team_id'] if not pd.isna(row['away_team_id']) else None,
+                "reason": reason
+            })
+            continue
+            
+        # Check if manual features were applied
+        applied = False
+        if manual_features is not None and row['id'] in manual_features.index:
+            applied = True
+
+        results.append({
+            "match_id": row['id'],
+            "home_team_id": row['home_team_id'],
+            "away_team_id": row['away_team_id'],
+            "prob_home_win": float(row['prob_home_win']),
+            "prob_draw": float(row['prob_draw']),
+            "prob_away_win": float(row['prob_away_win']),
+            "manual_features_applied": applied
+        })
+        
+    return {
+        "predictions": results,
+        "skipped": skipped
+    }
+
+def run_predictions():
+    data = get_predictions()
+    print("\nUpcoming Match Predictions:")
+    for p in data['predictions']:
+        print(f"Match {p['match_id']} | {p['home_team_id']} vs {p['away_team_id']} "
+              f"| 1: {p['prob_home_win']:.2f} X: {p['prob_draw']:.2f} 2: {p['prob_away_win']:.2f}")
+
+if __name__ == "__main__":
+    run_predictions()

requirements.txt

@@ -0,0 +1,9 @@
+pandas>=2.1.4
+numpy>=1.26.2
+psycopg2-binary>=2.9.9
+SQLAlchemy>=2.0.0
+python-dotenv>=1.0.0
+joblib==1.3.2
+fastapi>=0.100.0
+uvicorn>=0.20.0
+httpx>=0.24.1

rule_based_model.py

@@ -0,0 +1,73 @@
+import numpy as np
+
+class RuleBasedModel:
+    """
+    A simple baseline model using Bradley-Terry curve for Elo differences.
+    """
+    def __init__(self):
+        self.classes_ = np.array([0, 1, 2])
+        
+    def fit(self, X, y):
+        pass # No training required for rule-based baseline
+        
+    def predict_proba(self, X):
+        # Base Elo difference
+        # We assume home advantage is roughly +50 Elo
+        # Momentum diff is scaled and added to Elo diff
+        
+        # Apply injury impact: injury_impact is in [-0.1, 0]. Assume -0.1 = -100 Elo points.
+        home_injury_penalty = X['injury_impact_home'] * 1000
+        away_injury_penalty = X['injury_impact_away'] * 1000
+        
+        # Apply lineup strength: lineup_strength is in [0.8, 1.2]. 
+        # A 1.2 multiplier represents a much stronger squad than normal.
+        # Let's say +0.1 = +100 Elo points.
+        home_lineup_bonus = (X['lineup_strength_home'] - 1.0) * 1000
+        away_lineup_bonus = (X['lineup_strength_away'] - 1.0) * 1000
+        
+        # Calculate modified Elo diff
+        base_elo_diff = X['elo_diff'] + (X['home_advantage'] * 50) + (X['momentum_diff'] * 100)
+        
+        # Add home adjustments and subtract away adjustments
+        modified_elo_diff = base_elo_diff + home_injury_penalty + home_lineup_bonus - away_injury_penalty - away_lineup_bonus
+        
+        # Expected win rate for home team (Bradley-Terry curve)
+        home_expected = 1.0 / (1.0 + 10.0 ** (-modified_elo_diff / 400.0))
+        
+        # Empirical draw probability in football is roughly 25-30% on evenly matched teams,
+        # dropping off as teams become mismatched.
+        prob_draw = 0.28 * np.exp(-(modified_elo_diff ** 2) / (2 * 400**2))
+        
+        # The remainder is split between home and away based on the expected score
+        remaining = 1.0 - prob_draw
+        prob_home = remaining * home_expected
+        prob_away = remaining * (1.0 - home_expected)
+        
+        # Blend with odds implied probability if available
+        has_odds = (X['odds_implied_home_prob'] > 0) & (X['odds_implied_away_prob'] > 0)
+        
+        # If odds exist, we do a 50/50 blend between our modified model and bookmaker odds
+        # Bookmakers don't explicitly give draw probability in the engineered features directly,
+        # but we can deduce it as 1 - odds_home - odds_away
+        odds_prob_home = X['odds_implied_home_prob']
+        odds_prob_away = X['odds_implied_away_prob']
+        odds_prob_draw = 1.0 - odds_prob_home - odds_prob_away
+        
+        # Ensure we don't have negative probabilities due to floating point inaccuracies
+        odds_prob_draw = np.maximum(odds_prob_draw, 0.0)
+        
+        final_prob_home = np.where(has_odds, 0.5 * prob_home + 0.5 * odds_prob_home, prob_home)
+        final_prob_away = np.where(has_odds, 0.5 * prob_away + 0.5 * odds_prob_away, prob_away)
+        final_prob_draw = np.where(has_odds, 0.5 * prob_draw + 0.5 * odds_prob_draw, prob_draw)
+        
+        # Normalize just to be safe
+        total = final_prob_home + final_prob_away + final_prob_draw
+        final_prob_home /= total
+        final_prob_away /= total
+        final_prob_draw /= total
+        
+        return np.column_stack([final_prob_away, final_prob_draw, final_prob_home])
+        
+    def predict(self, X):
+        probs = self.predict_proba(X)
+        return np.argmax(probs, axis=1)

test_api.py

@@ -0,0 +1,36 @@
+from fastapi.testclient import TestClient
+from api import app
+import math
+
+client = TestClient(app)
+
+def test_health():
+    response = client.get("/api/health")
+    assert response.status_code == 200
+    assert response.json() == {"status": "ok"}
+
+def test_predict_upcoming():
+    response = client.get("/api/predict")
+    assert response.status_code == 200
+    
+    data = response.json()
+    assert "predictions" in data
+    assert "skipped" in data
+    
+    # We expect 12 valid scheduled matches right now based on the DB state
+    predictions = data["predictions"]
+    assert len(predictions) == 12, f"Expected 12 predictions, got {len(predictions)}"
+    
+    # Check skipped count
+    assert data["predictions_count"] == 12
+    assert data["skipped_count"] >= 0
+    
+    for p in predictions:
+        # Sum of probabilities should be ~1
+        total_prob = p["prob_home_win"] + p["prob_draw"] + p["prob_away_win"]
+        assert math.isclose(total_prob, 1.0, rel_tol=1e-5), f"Match {p['match_id']} prob sum is {total_prob}"
+
+if __name__ == "__main__":
+    test_health()
+    test_predict_upcoming()
+    print("Smoke test passed: API returns 12 valid predictions summing to 1.")

train.py

@@ -0,0 +1,16 @@
+import os
+import joblib
+
+from rule_based_model import RuleBasedModel
+
+def train_baseline_model():
+    print("Initializing Rule-Based Baseline Model (avoiding time leakage from current matches)...")
+    clf = RuleBasedModel()
+    
+    # 6. Save Model
+    os.makedirs('artifacts', exist_ok=True)
+    joblib.dump(clf, 'artifacts/rule_based_baseline.pkl')
+    print("Model saved to artifacts/rule_based_baseline.pkl")
+
+if __name__ == "__main__":
+    train_baseline_model()