Time Series and Line Movement Analysis for Betting Agents

"""
Line Movement Analysis Module for Betting Agents.

Requires:
  pip install pandas numpy statsmodels requests

Integrates with The Odds API for real-time odds data.
"""

import numpy as np
import pandas as pd
from dataclasses import dataclass, field
from datetime import datetime, timedelta
from typing import Optional
from statsmodels.tsa.arima.model import ARIMA
from statsmodels.tsa.holtwinters import ExponentialSmoothing
import requests


# ── Data Structures ────────────────────────────────────────────

@dataclass
class OddsSnapshot:
    """Single odds observation from one sportsbook."""
    timestamp: datetime
    book: str
    spread: float
    price: int  # American odds, e.g., -110
    sport: str
    event: str


@dataclass
class RLMSignal:
    """Reverse line movement detection result."""
    event: str
    public_pct: float
    opening_line: float
    current_line: float
    line_delta: float
    rlm_detected: bool
    rlm_score: float
    sharp_side: str


@dataclass
class SteamSignal:
    """Steam move detection result."""
    event: str
    direction: str
    books_moved: int
    books_tracked: int
    cascade_seconds: float
    avg_move_size: float
    steam_score: float
    originating_book: str
    timestamp: datetime


# ── Reverse Line Movement Detection ───────────────────────────

def detect_rlm(
    opening_line: float,
    current_line: float,
    public_pct_side_a: float,
    event: str = "",
    side_a_name: str = "Home",
    side_b_name: str = "Away"
) -> RLMSignal:
    """
    Detect reverse line movement.

    Args:
        opening_line: Opening spread (negative = side A favored).
        current_line: Current spread.
        public_pct_side_a: Fraction of bets on side A (0.0 to 1.0).
        event: Event description for logging.
        side_a_name: Name of side A.
        side_b_name: Name of side B.

    Returns:
        RLMSignal with detection result and score.
    """
    line_delta = current_line - opening_line
    # Positive delta means line moved toward side A (more negative spread)
    # For spreads: opening -3.5, current -4.0, delta = -0.5 (moved toward A)

    public_direction = 1 if public_pct_side_a > 0.5 else -1
    line_direction = -1 if line_delta < 0 else (1 if line_delta > 0 else 0)

    # RLM: public on one side, line moves the other
    rlm_detected = (
        line_direction != 0
        and public_direction != line_direction
    )

    rlm_score = abs(public_pct_side_a - 0.5) * abs(line_delta) * (1 if rlm_detected else 0)

    sharp_side = ""
    if rlm_detected:
        sharp_side = side_a_name if line_direction < 0 else side_b_name

    return RLMSignal(
        event=event,
        public_pct=public_pct_side_a,
        opening_line=opening_line,
        current_line=current_line,
        line_delta=line_delta,
        rlm_detected=rlm_detected,
        rlm_score=rlm_score,
        sharp_side=sharp_side,
    )


# ── Steam Move Detection ──────────────────────────────────────

def detect_steam(
    snapshots: list[OddsSnapshot],
    window_minutes: float = 15.0,
    min_books: int = 3,
    min_move_size: float = 0.5
) -> Optional[SteamSignal]:
    """
    Detect steam moves from a time-ordered list of odds snapshots.

    Groups snapshots by book, detects synchronized moves within
    the time window, and scores the steam signal.

    Args:
        snapshots: Time-ordered odds snapshots across multiple books.
        window_minutes: Max time window for cascade detection.
        min_books: Minimum books that must move to qualify.
        min_move_size: Minimum point move to count.

    Returns:
        SteamSignal if detected, None otherwise.
    """
    if len(snapshots) < 2:
        return None

    df = pd.DataFrame([
        {
            "timestamp": s.timestamp,
            "book": s.book,
            "spread": s.spread,
            "event": s.event,
        }
        for s in snapshots
    ]).sort_values("timestamp")

    # Get first and last snapshot per book
    book_moves = []
    for book, group in df.groupby("book"):
        if len(group) < 2:
            continue
        first = group.iloc[0]
        last = group.iloc[-1]
        move = last["spread"] - first["spread"]
        if abs(move) >= min_move_size:
            book_moves.append({
                "book": book,
                "move": move,
                "first_time": first["timestamp"],
                "move_time": last["timestamp"],
            })

    if len(book_moves) < min_books:
        return None

    moves_df = pd.DataFrame(book_moves)

    # Check direction consensus
    directions = np.sign(moves_df["move"].values)
    dominant_direction = np.sign(np.sum(directions))
    aligned = moves_df[np.sign(moves_df["move"]) == dominant_direction]

    if len(aligned) < min_books:
        return None

    first_move_time = aligned["move_time"].min()
    last_move_time = aligned["move_time"].max()
    cascade_seconds = (last_move_time - first_move_time).total_seconds()

    if cascade_seconds > window_minutes * 60:
        return None

    originator = aligned.loc[aligned["move_time"].idxmin(), "book"]
    avg_move = aligned["move"].abs().mean()
    cascade_min = max(cascade_seconds / 60, 0.5)  # floor at 30 sec

    steam_score = (
        (len(aligned) / df["book"].nunique())
        * (1 / cascade_min)
        * avg_move
    )

    return SteamSignal(
        event=snapshots[0].event,
        direction="favorite" if dominant_direction < 0 else "underdog",
        books_moved=len(aligned),
        books_tracked=df["book"].nunique(),
        cascade_seconds=cascade_seconds,
        avg_move_size=avg_move,
        steam_score=steam_score,
        originating_book=originator,
        timestamp=first_move_time,
    )


# ── Time Series Decomposition ─────────────────────────────────

def decompose_line_movement(
    timestamps: list[datetime],
    lines: list[float],
    period: int = 24
) -> dict[str, np.ndarray]:
    """
    Decompose a line movement time series into trend, seasonal,
    and noise components using STL-like additive decomposition.

    Args:
        timestamps: Observation timestamps.
        lines: Corresponding line values.
        period: Seasonal period in observation units (24 = daily for hourly data).

    Returns:
        Dict with 'trend', 'seasonal', 'noise' arrays.
    """
    series = pd.Series(lines, index=pd.DatetimeIndex(timestamps))
    series = series.asfreq("h", method="ffill")

    # Trend: rolling mean with window = period
    trend = series.rolling(window=period, center=True, min_periods=1).mean()

    # Detrended
    detrended = series - trend

    # Seasonal: average detrended value for each hour-of-day
    seasonal_avg = detrended.groupby(detrended.index.hour).transform("mean")

    # Noise: residual
    noise = series - trend - seasonal_avg

    return {
        "observed": series.values,
        "trend": trend.values,
        "seasonal": seasonal_avg.values,
        "noise": noise.values,
        "timestamps": series.index,
    }


# ── ARIMA Forecasting ─────────────────────────────────────────

def forecast_line_arima(
    lines: list[float],
    steps: int = 3,
    order: tuple[int, int, int] = (1, 1, 1)
) -> dict:
    """
    Forecast future line values using ARIMA.

    Args:
        lines: Historical line values (evenly spaced).
        steps: Number of steps to forecast.
        order: ARIMA(p, d, q) order.

    Returns:
        Dict with 'forecast' values and 'confidence_intervals'.
    """
    series = pd.Series(lines, dtype=float)

    model = ARIMA(series, order=order)
    fitted = model.fit()

    forecast_result = fitted.get_forecast(steps=steps)
    forecast_values = forecast_result.predicted_mean.values
    conf_int = forecast_result.conf_int(alpha=0.05)

    return {
        "forecast": forecast_values,
        "lower_ci": conf_int.iloc[:, 0].values,
        "upper_ci": conf_int.iloc[:, 1].values,
        "aic": fitted.aic,
        "bic": fitted.bic,
    }


def forecast_line_ets(
    lines: list[float],
    steps: int = 3,
    seasonal_period: int = 24
) -> np.ndarray:
    """
    Forecast line movement using Exponential Smoothing (Holt-Winters).

    Lighter weight than ARIMA. Good for agents that need fast forecasts
    with minimal computation.

    Args:
        lines: Historical line values.
        steps: Steps ahead to forecast.
        seasonal_period: Seasonal cycle length.

    Returns:
        Array of forecasted values.
    """
    series = pd.Series(lines, dtype=float)

    if len(series) < 2 * seasonal_period:
        # Not enough data for seasonal model — use simple exponential smoothing
        model = ExponentialSmoothing(
            series, trend="add", seasonal=None
        )
    else:
        model = ExponentialSmoothing(
            series, trend="add", seasonal="add",
            seasonal_periods=seasonal_period
        )

    fitted = model.fit(optimized=True)
    return fitted.forecast(steps).values


# ── Opening Line Value Calculator ──────────────────────────────

def calculate_olv(
    opening_lines: list[float],
    closing_lines: list[float],
    bet_lines: list[float]
) -> dict:
    """
    Calculate Opening Line Value metrics across a sample of bets.

    Args:
        opening_lines: Opening spread for each event.
        closing_lines: Closing spread for each event.
        bet_lines: The spread at which the agent actually bet.

    Returns:
        Dict with OLV statistics.
    """
    opening = np.array(opening_lines)
    closing = np.array(closing_lines)
    bet = np.array(bet_lines)

    # Line movement from open to close
    total_movement = closing - opening
    avg_movement = np.mean(np.abs(total_movement))

    # CLV: how much better the agent's line was vs. closing
    clv = closing - bet  # positive = agent beat the close
    avg_clv = np.mean(clv)
    pct_beat_close = np.mean(clv > 0) * 100

    # OLV: how much the opening line differed from closing
    olv = np.abs(opening - closing)
    avg_olv = np.mean(olv)

    # What fraction of OLV did the agent capture?
    olv_captured = np.where(
        olv > 0,
        np.clip((closing - bet) / (closing - opening), 0, 1),
        0
    )
    avg_olv_captured = np.mean(olv_captured) * 100

    return {
        "avg_line_movement": avg_movement,
        "avg_clv": avg_clv,
        "pct_beat_closing_line": pct_beat_close,
        "avg_olv_points": avg_olv,
        "pct_olv_captured": avg_olv_captured,
        "sample_size": len(opening),
    }


# ── The Odds API Integration ──────────────────────────────────

def fetch_odds_history(
    api_key: str,
    sport: str = "americanfootball_nfl",
    regions: str = "us",
    markets: str = "spreads",
    days_back: int = 3
) -> pd.DataFrame:
    """
    Fetch historical odds snapshots from The Odds API.

    Args:
        api_key: The Odds API key.
        sport: Sport key (e.g., 'americanfootball_nfl').
        regions: Comma-separated regions.
        markets: Market type ('spreads', 'totals', 'h2h').
        days_back: How many days of history to fetch.

    Returns:
        DataFrame with columns: timestamp, event, book, spread, price.
    """
    base_url = "https://api.the-odds-api.com/v4/sports"
    date_from = (datetime.utcnow() - timedelta(days=days_back)).isoformat() + "Z"

    resp = requests.get(
        f"{base_url}/{sport}/odds-history",
        params={
            "apiKey": api_key,
            "regions": regions,
            "markets": markets,
            "dateFormat": "iso",
            "date": date_from,
        },
    )
    resp.raise_for_status()
    data = resp.json()

    rows = []
    for event in data.get("data", []):
        event_name = f"{event['away_team']} @ {event['home_team']}"
        for bookmaker in event.get("bookmakers", []):
            book = bookmaker["key"]
            for market in bookmaker.get("markets", []):
                if market["key"] == "spreads":
                    for outcome in market["outcomes"]:
                        rows.append({
                            "timestamp": pd.Timestamp(bookmaker["last_update"]),
                            "event": event_name,
                            "book": book,
                            "team": outcome["name"],
                            "spread": outcome.get("point", 0),
                            "price": outcome["price"],
                        })

    return pd.DataFrame(rows)


# ── Volume-Weighted Line Movement Scoring ──────────────────────

def sharp_vs_public_score(
    line_moves: list[float],
    volumes: list[float],
    bet_counts: list[int]
) -> dict:
    """
    Score whether line movement is driven by sharp money or public money.

    Sharp money: large average bet size, line moves with the money.
    Public money: small average bet size, high bet count.

    Args:
        line_moves: Signed line movements (positive = toward favorite).
        volumes: Dollar volume behind each move.
        bet_counts: Number of individual bets behind each move.

    Returns:
        Dict with sharp_score and classification.
    """
    moves = np.array(line_moves)
    vols = np.array(volumes)
    counts = np.array(bet_counts)

    avg_bet_size = vols / np.maximum(counts, 1)

    # Volume-weighted average move direction
    vol_weighted_direction = np.sum(moves * vols) / np.sum(vols)

    # Count-weighted average move direction
    count_weighted_direction = np.sum(moves * counts) / np.sum(counts)

    # If volume says one thing and count says another → sharp vs public split
    divergence = vol_weighted_direction - count_weighted_direction

    # Sharp score: normalized divergence × average bet size factor
    median_bet = np.median(avg_bet_size)
    sharp_score = divergence * (median_bet / 1000)  # normalize to ~$1000 baseline

    if sharp_score > 0.1:
        classification = "sharp_dominant"
    elif sharp_score < -0.1:
        classification = "public_dominant"
    else:
        classification = "mixed"

    return {
        "sharp_score": sharp_score,
        "classification": classification,
        "vol_weighted_direction": vol_weighted_direction,
        "count_weighted_direction": count_weighted_direction,
        "avg_bet_size": float(np.mean(avg_bet_size)),
    }


# ── Agent Entry Timing ─────────────────────────────────────────

def optimal_entry_signal(
    current_line: float,
    agent_fair_line: float,
    arima_forecast: list[float],
    rlm_signal: Optional[RLMSignal] = None,
    steam_signal: Optional[SteamSignal] = None,
) -> dict:
    """
    Combine line movement signals to generate an entry timing decision.

    Args:
        current_line: Current market spread.
        agent_fair_line: Agent's model estimate of the true spread.
        arima_forecast: Forecasted line values for next N periods.
        rlm_signal: Optional RLM detection result.
        steam_signal: Optional steam detection result.

    Returns:
        Dict with entry recommendation and confidence.
    """
    edge = abs(agent_fair_line - current_line)
    forecasted_close = arima_forecast[-1] if arima_forecast else current_line

    # Will the line move toward or away from agent's position?
    line_moving_toward_agent = (
        abs(agent_fair_line - forecasted_close) < abs(agent_fair_line - current_line)
    )

    confidence_factors = []

    # Factor 1: Raw edge
    if edge >= 1.5:
        confidence_factors.append(("large_edge", 0.3))
    elif edge >= 0.5:
        confidence_factors.append(("moderate_edge", 0.15))

    # Factor 2: Line moving toward fair value (bet now before it corrects)
    if line_moving_toward_agent:
        confidence_factors.append(("line_converging", 0.25))

    # Factor 3: RLM confirms agent's side
    if rlm_signal and rlm_signal.rlm_detected and rlm_signal.rlm_score > 0.1:
        confidence_factors.append(("rlm_confirmation", 0.2))

    # Factor 4: Steam on agent's side (or stale line opportunity)
    if steam_signal and steam_signal.steam_score > 0.5:
        confidence_factors.append(("steam_active", 0.25))

    total_confidence = sum(f[1] for f in confidence_factors)

    if total_confidence >= 0.5 and edge >= 0.5:
        action = "bet_now"
    elif total_confidence >= 0.3 and edge >= 1.0:
        action = "bet_now"
    elif line_moving_toward_agent and edge > 0:
        action = "bet_now"
    else:
        action = "wait"

    return {
        "action": action,
        "edge_points": edge,
        "current_line": current_line,
        "fair_line": agent_fair_line,
        "forecasted_close": forecasted_close,
        "confidence": total_confidence,
        "factors": confidence_factors,
    }