ncaa_eval.evaluation.scoring module

Scoring rule protocols, implementations, and registry.

Provides the ScoringRule protocol, concrete scoring implementations, and a decorator-based registry:

• ScoringRule — protocol for tournament bracket scoring rules.

• StandardScoring — ESPN-style 1-2-4-8-16-32.

• FibonacciScoring — 2-3-5-8-13-21.

• SeedDiffBonusScoring — base + seed-difference upset bonus.

• CustomScoring — user-defined callable-based scoring.

• DictScoring — dict-based scoring.

• register_scoring() — class decorator for registry registration.

• get_scoring() — retrieve a scoring class by name.

• list_scorings() — list all registered scoring names.

• scoring_from_config() — create a scoring rule from a config dict.

class ncaa_eval.evaluation.scoring.CustomScoring(scoring_fn: Callable[[int], float], scoring_name: str)

Bases: object

User-defined scoring rule wrapping a callable.

Parameters:

• scoring_fn – Callable mapping round_idx → points.

• scoring_name – Name for this custom rule.

property name: str

Return the custom rule name.

points_per_round(round_idx: int) → float

Return points from the wrapped callable.

class ncaa_eval.evaluation.scoring.DictScoring(points: dict[int, float], scoring_name: str)

Bases: object

Scoring rule from a dict mapping round_idx to points.

Parameters:

• points – Mapping of round_idx → points for rounds 0–5.

• scoring_name – Name for this rule.

Raises:

ValueError – If points does not contain exactly 6 entries (rounds 0–5).

property name: str

Return the rule name.

points_per_round(round_idx: int) → float

Return points for round_idx.

class ncaa_eval.evaluation.scoring.FibonacciScoring

Bases: object

Fibonacci-style scoring: 2-3-5-8-13-21 (231 total for perfect bracket).

property name: str

Return 'fibonacci'.

points_per_round(round_idx: int) → float

Return Fibonacci scoring points for round_idx.

exception ncaa_eval.evaluation.scoring.ScoringNotFoundError

Bases: KeyError

Raised when a requested scoring name is not in the registry.

class ncaa_eval.evaluation.scoring.ScoringRule(*args, **kwargs)

Bases: Protocol

Protocol for tournament bracket scoring rules.

property name: str

Human-readable name of the scoring rule.

points_per_round(round_idx: int) → float

Return points awarded for a correct pick in round round_idx.

Parameters:

round_idx – Zero-indexed round number (0=R64 through 5=NCG).

Returns:

Points as a float.

class ncaa_eval.evaluation.scoring.SeedDiffBonusScoring(seed_map: dict[int, int])

Bases: object

Base points + seed-difference bonus when lower seed wins.

Uses same base as StandardScoring (1-2-4-8-16-32). When the lower seed (higher seed number) wins, adds |seed_a - seed_b| bonus.

Note: This scoring rule’s points_per_round returns only the base points. Full EP computation for seed-diff scoring (which requires per-matchup seed information) is deferred to Story 6.6, which will add a dedicated compute_expected_points_seed_diff function.

Parameters:

seed_map – Mapping of team_id → seed_num.

property name: str

Return 'seed_diff_bonus'.

points_per_round(round_idx: int) → float

Return base points (excludes seed-diff bonus).

seed_diff_bonus(seed_a: int, seed_b: int) → float

Return bonus points when the lower seed wins.

Parameters:

• seed_a – Winner’s seed number.

• seed_b – Loser’s seed number.

Returns:

|seed_a - seed_b| if winner has higher seed number (lower seed = upset), else 0.

property seed_map: dict[int, int]

Return the seed lookup map.

class ncaa_eval.evaluation.scoring.StandardScoring

Bases: object

ESPN-style scoring: 1-2-4-8-16-32 (192 total for perfect bracket).

property name: str

Return 'standard'.

points_per_round(round_idx: int) → float

Return standard scoring points for round_idx.

ncaa_eval.evaluation.scoring.get_scoring(name: str) → type

Return the scoring class registered under name.

Raises:

ScoringNotFoundError – If name is not registered.

ncaa_eval.evaluation.scoring.list_scoring_display_names() → dict[str, str]

Return a mapping of registry keys to display names.

Returns:

Dict mapping scoring name → human-readable display name.

ncaa_eval.evaluation.scoring.list_scorings() → list[str]

Return all registered scoring names (sorted).

ncaa_eval.evaluation.scoring.register_scoring(name: str, *, display_name: str | None = None) → Callable[[_ST], _ST]

Class decorator that registers a scoring rule class.

Parameters:

• name – Registry key for the scoring rule.

• display_name – Optional human-readable label for UI display. Falls back to name if not provided.

Returns:

Decorator that registers the class and returns it unchanged.

Raises:

ValueError – If name is already registered.

ncaa_eval.evaluation.scoring.scoring_from_config(config: dict[str, Any]) → ScoringRule

Create a scoring rule from a configuration dict.

Dispatches on config["type"]:

• "standard" → StandardScoring

• "fibonacci" → FibonacciScoring

• "seed_diff_bonus" → SeedDiffBonusScoring (requires seed_map)

• "dict" → DictScoring (requires points and name)

• "custom" → CustomScoring (requires callable and name)

Parameters:

config – Configuration dict with at least a "type" key.

Returns:

Instantiated scoring rule.

Raises:

ValueError – If type is unknown or required keys are missing.