ncaa_eval.model.base module

Model abstract base classes and configuration.

Defines the Model ABC, the StatefulModel template subclass for sequential-update models, and the ModelConfig Pydantic base used by every model’s hyperparameter schema.

class ncaa_eval.model.base.Model

Bases: ABC

Abstract base class for all NCAA prediction models.

Every model — stateful or stateless — must implement these five methods so that the training CLI, evaluation engine, and persistence layer can treat all models uniformly.

feature_config

Declarative specification of which feature blocks the model expects. Set by subclass __init__.

Type:

ncaa_eval.transform.feature_serving.FeatureConfig

feature_config: FeatureConfig

abstractmethod fit(X: DataFrame, y: Series) → None

Train the model on feature matrix X and labels y.

abstractmethod get_config() → ModelConfig

Return the Pydantic-validated configuration for this model.

get_feature_importances() → list[tuple[str, float]] | None

Return feature name/importance pairs, or None if unavailable.

The default returns None. Models that support feature importances (e.g. XGBoost) should override this method.

abstractmethod classmethod load(path: Path) → Self

Load a previously-saved model from path.

abstractmethod predict_proba(X: DataFrame) → Series

Return P(team_a wins) in [0, 1] for each row of X.

abstractmethod save(path: Path) → None

Persist the trained model to path.

class ncaa_eval.model.base.ModelConfig(*, model_name: str, calibration_method: Literal['isotonic', 'sigmoid'] | None = None)

Bases: BaseModel

Base configuration shared by all model implementations.

Subclasses add model-specific hyperparameters as additional fields.

calibration_method: CalibrationMethod | None

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_name: str

class ncaa_eval.model.base.StatefulModel

Bases: Model

Template base for models that process games sequentially.

Concrete methods fit and predict_proba are provided as template methods. Subclasses implement the abstract hooks:

• update(game) — absorb a single game result

• _predict_one(team_a_id, team_b_id) — return P(team_a wins)

• start_season(season) — reset / prepare for a new season

• get_state() / set_state(state) — snapshot / restore ratings

fit(X: DataFrame, y: Series) → None

Reconstruct games from X/y and update sequentially.

Reconstructs Game objects from the feature matrix and labels, then iterates chronologically, calling start_season() on season boundaries and update() per game.

abstractmethod get_state() → dict[str, Any]

Return a serialisable snapshot of internal ratings.

predict_matchup(team_a_id: int, team_b_id: int) → float

Return P(team_a wins) for a single matchup.

Delegates to the _predict_one abstract hook.

predict_proba(X: DataFrame) → Series

Call _predict_one per row using itertuples.

abstractmethod set_state(state: dict[str, Any]) → None

Restore internal ratings from a snapshot.

abstractmethod start_season(season: int) → None

Called before the first game of each season.

abstractmethod update(game: Game) → None

Absorb the result of a single game.