tiebreak-core 1.2.0__py3-none-any.whl

tiebreak_core/__init__.py

@@ -0,0 +1,240 @@
+"""
+tiebreak-core — standalone chess tie-break calculation library.
+
+Extracted behavior-preserving from chess-manager ``domain/tiebreak/``.
+No Flask, no SQLAlchemy, no persistence, no network.
+
+Calculation (``calculate``/``calculate_all``) and ordering
+(``ranking.rank_standings``/``order_ids``) are independent. Tournament
+seeding stays outside the core (see ``ranking`` docstring).
+
+Rules versioning: calculations select an explicit ruleset
+(``legacy-0.1.0`` frozen, ``fide-2024`` frozen, ``fide-2026``
+implemented). See ``tiebreak_core.rules`` and
+``docs/KNOWN_LIMITATIONS.md``.
+"""
+
+from tiebreak_core.models import (
+    GameRecord,
+    PlayerTiebreakData,
+    TiebreakResult,
+    PlayerResult,
+    StandingsResult,
+    GAME_KINDS,
+    VIRTUAL_KINDS,
+    PLAYED,
+    PAIRING_BYE,
+    FORFEIT_WIN,
+    FORFEIT_LOSS,
+    REQUESTED_BYE,
+    UNPLAYED,
+    ABSENT,
+    normalize_kind,
+)
+from tiebreak_core.calculators import (
+    buchholz,
+    buchholz_cut1,
+    buchholz_cut2,
+    median_buchholz,
+    median_buchholz_2,
+    sonneborn_berger,
+    progressive,
+    wins_count,
+    wins_with_black,
+    games_with_black,
+    average_rating_opponents,
+    koya,
+    direct_encounter,
+    buchholz_sum,
+    arpo,
+    calculate,
+    calculate_all,
+    TIEBREAK_REGISTRY,
+)
+from tiebreak_core.registry import (
+    TIEBREAK_IDS,
+    TIEBREAK_FIDE_REF,
+    DEFAULT_CRITERIA,
+    frozen_registry,
+    is_known,
+    register_criterion,
+    unregister_criterion,
+)
+from tiebreak_core.errors import (
+    TiebreakError,
+    UnknownCriterionError,
+    UnsupportedRulesetError,
+    UnsupportedCriterionError,
+    InvalidGameRecordError,
+    InvalidPlayerDataError,
+    DuplicatePlayerIdError,
+    RegistryError,
+    InvalidDescriptorError,
+)
+from tiebreak_core.strict import (
+    calculate_strict,
+    calculate_all_strict,
+    rank_standings_strict,
+    order_ids_strict,
+    calculate_descriptor_strict,
+    rank_descriptors_strict,
+    calculate_team_strict,
+    rank_teams_strict,
+    validate_game,
+    validate_player,
+    validate_players,
+    require_criteria,
+    require_ruleset,
+)
+from tiebreak_core.ranking import rank_standings, order_ids, sort_key
+from tiebreak_core.modifiers import (
+    ModifierSpec,
+    parse_descriptor,
+    canonical_id,
+    calculate_descriptor,
+    rank_descriptors,
+)
+from tiebreak_core.team import (
+    TeamMatch,
+    TeamRecord,
+    TeamFormat,
+    TeamResult,
+    TeamStandingsResult,
+    TEAM_KINDS,
+    validate_match,
+    validate_team,
+    validate_teams,
+    canonical_team_id,
+    calculate_team,
+    rank_team_standings,
+)
+from tiebreak_core.article16 import (
+    Article16Policy,
+    FIDE_2024_POLICY,
+    FIDE_2026_SWISS_POLICY,
+    FIDE_2026_RR_POLICY,
+    resolve_policy,
+)
+from tiebreak_core.scoring import (
+    ScoringScheme,
+    STANDARD,
+    is_standard,
+    require_standard_or_explicit,
+)
+from tiebreak_core.rules import (
+    CALCULATION_RULES_VERSION,
+    FIDE_REFERENCE,
+    SUPPORTED_RULESETS,
+    RulesetInfo,
+    available_rulesets,
+    describe_ruleset,
+    is_supported,
+)
+
+__version__ = "1.2.0"
+__fide_reference__ = FIDE_REFERENCE
+__rules_version__ = CALCULATION_RULES_VERSION
+
+__all__ = [
+    "GameRecord",
+    "PlayerTiebreakData",
+    "TiebreakResult",
+    "PlayerResult",
+    "StandingsResult",
+    "GAME_KINDS",
+    "VIRTUAL_KINDS",
+    "PLAYED",
+    "PAIRING_BYE",
+    "FORFEIT_WIN",
+    "FORFEIT_LOSS",
+    "REQUESTED_BYE",
+    "UNPLAYED",
+    "ABSENT",
+    "normalize_kind",
+    "buchholz",
+    "buchholz_cut1",
+    "buchholz_cut2",
+    "median_buchholz",
+    "median_buchholz_2",
+    "sonneborn_berger",
+    "progressive",
+    "wins_count",
+    "wins_with_black",
+    "games_with_black",
+    "average_rating_opponents",
+    "koya",
+    "direct_encounter",
+    "buchholz_sum",
+    "arpo",
+    "calculate",
+    "calculate_all",
+    "TIEBREAK_REGISTRY",
+    "TIEBREAK_IDS",
+    "TIEBREAK_FIDE_REF",
+    "DEFAULT_CRITERIA",
+    "frozen_registry",
+    "is_known",
+    "register_criterion",
+    "unregister_criterion",
+    "TiebreakError",
+    "UnknownCriterionError",
+    "UnsupportedRulesetError",
+    "UnsupportedCriterionError",
+    "InvalidGameRecordError",
+    "InvalidPlayerDataError",
+    "DuplicatePlayerIdError",
+    "RegistryError",
+    "InvalidDescriptorError",
+    "ModifierSpec",
+    "parse_descriptor",
+    "canonical_id",
+    "calculate_descriptor",
+    "rank_descriptors",
+    "TeamMatch",
+    "TeamRecord",
+    "TeamFormat",
+    "TeamResult",
+    "TeamStandingsResult",
+    "TEAM_KINDS",
+    "validate_match",
+    "validate_team",
+    "validate_teams",
+    "canonical_team_id",
+    "calculate_team",
+    "rank_team_standings",
+    "Article16Policy",
+    "FIDE_2024_POLICY",
+    "FIDE_2026_SWISS_POLICY",
+    "FIDE_2026_RR_POLICY",
+    "resolve_policy",
+    "ScoringScheme",
+    "STANDARD",
+    "is_standard",
+    "require_standard_or_explicit",
+    "calculate_strict",
+    "calculate_all_strict",
+    "rank_standings_strict",
+    "order_ids_strict",
+    "calculate_descriptor_strict",
+    "rank_descriptors_strict",
+    "calculate_team_strict",
+    "rank_teams_strict",
+    "validate_game",
+    "validate_player",
+    "validate_players",
+    "require_criteria",
+    "require_ruleset",
+    "rank_standings",
+    "order_ids",
+    "sort_key",
+    "CALCULATION_RULES_VERSION",
+    "FIDE_REFERENCE",
+    "SUPPORTED_RULESETS",
+    "RulesetInfo",
+    "available_rulesets",
+    "describe_ruleset",
+    "is_supported",
+    "__version__",
+    "__fide_reference__",
+    "__rules_version__",
+]

tiebreak_core/article16.py

@@ -0,0 +1,140 @@
+"""
+Article 16 policy abstraction (C.07 §§16.1–16.6).
+
+Scattered booleans (``mode``, ``forfeits_as_played``) currently select
+unplayed-round behavior at each call site. This module names the
+underlying policy so tournament regulations can explicitly override
+the FIDE-default behavior where FIDE permits it (§16.6: *"Unless the
+rules of a competition specify otherwise, ..."*).
+
+An :class:`Article16Policy` is a value object describing HOW unplayed
+rounds are managed; the engines document which policy their defaults
+reproduce. New code paths (modifiers, team fore-variants) resolve
+their behavior through :func:`resolve_policy`. Existing engine
+defaults are unchanged — :func:`default_policy` is pinned by
+conformance tests to reproduce ``fide-2024`` / ``fide-2026`` outputs
+exactly.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from tiebreak_core.errors import InvalidPlayerDataError
+
+DummyCapMode = Literal["uncapped", "capped"]
+ForfeitScope = Literal["swiss", "round_robin", "as_played"]
+
+
+@dataclass(frozen=True)
+class Article16Policy:
+    """Named unplayed-round management policy.
+
+    Attributes:
+        dummy_cap: ``"uncapped"`` (§16.4 2024: dummy = own score) or
+            ``"capped"`` (§16.4.1–16.4.2 2026: forfeit dummies capped
+            by the scheduled opponent's adjusted score, other
+            unplayed dummies capped by draw-points × rounds).
+        late_bye_value: adjusted-score value (§16.3) of a 16.2.5
+            trailing requested bye for opponents' use (FIDE: 0.5).
+        vur_cut_preference: whether cuts prefer VUR contributions
+            (§16.5.1; FIDE: True).
+        reapply_cuts: whether the cut exception reapplies per cut
+            (§16.5.2; FIDE: True).
+        forfeit_scope: ``"swiss"`` (Article 16: forfeits are unplayed
+            rounds), ``"round_robin"`` (§15.2 carve-out), or
+            ``"as_played"`` (MTB26 ``/P`` regulations opt-in).
+        keep_last_element: never cut the final remaining element
+            (documented edge guard, not a FIDE rule).
+    """
+
+    dummy_cap: DummyCapMode = "capped"
+    late_bye_value: float = 0.5
+    vur_cut_preference: bool = True
+    reapply_cuts: bool = True
+    forfeit_scope: ForfeitScope = "swiss"
+    keep_last_element: bool = True
+
+
+FIDE_2024_POLICY = Article16Policy(
+    dummy_cap="uncapped",
+    late_bye_value=0.5,
+    vur_cut_preference=True,
+    reapply_cuts=True,
+    forfeit_scope="swiss",
+    keep_last_element=True,
+)
+
+FIDE_2026_SWISS_POLICY = Article16Policy(
+    dummy_cap="capped",
+    late_bye_value=0.5,
+    vur_cut_preference=True,
+    reapply_cuts=True,
+    forfeit_scope="swiss",
+    keep_last_element=True,
+)
+
+FIDE_2026_RR_POLICY = Article16Policy(
+    dummy_cap="capped",
+    late_bye_value=0.5,
+    vur_cut_preference=True,
+    reapply_cuts=True,
+    forfeit_scope="round_robin",
+    keep_last_element=True,
+)
+
+
+def resolve_policy(ruleset: str, mode: str = "swiss",
+                   forfeits_as_played: bool = False,
+                   **overrides) -> Article16Policy:
+    """Resolve engine flags to the policy they implement.
+
+    ``§16.6`` overrides pass as keyword overrides (e.g.
+    ``late_bye_value=0.0``); unknown override names raise
+    :class:`InvalidPlayerDataError` (no silent misconfiguration).
+    """
+    if ruleset == "fide-2024":
+        base = FIDE_2024_POLICY
+    elif ruleset == "fide-2026":
+        if forfeits_as_played:
+            base = Article16Policy(
+                dummy_cap="capped", late_bye_value=0.5,
+                vur_cut_preference=True, reapply_cuts=True,
+                forfeit_scope="as_played", keep_last_element=True)
+        elif mode == "round_robin":
+            base = FIDE_2026_RR_POLICY
+        elif mode == "swiss":
+            base = FIDE_2026_SWISS_POLICY
+        else:
+            raise InvalidPlayerDataError(
+                f"mode must be 'swiss' or 'round_robin', got {mode!r}")
+    else:
+        raise InvalidPlayerDataError(
+            f"Article16Policy covers fide-2024/fide-2026, "
+            f"got ruleset {ruleset!r}")
+    if not overrides:
+        return base
+    fields = set(base.__dataclass_fields__)
+    unknown = [k for k in overrides if k not in fields]
+    if unknown:
+        raise InvalidPlayerDataError(
+            f"unknown Article-16 override(s): {unknown} "
+            f"(allowed: {sorted(fields)})")
+    if ("late_bye_value" in overrides
+            and overrides["late_bye_value"] not in (0.0, 0.5)):
+        raise InvalidPlayerDataError(
+            "late_bye_value override must be 0.0 or 0.5 "
+            f"(§16.3 draw semantics), got "
+            f"{overrides['late_bye_value']!r}")
+    values = {f: getattr(base, f) for f in fields}
+    values.update(overrides)
+    return Article16Policy(**values)
+
+
+__all__ = [
+    "Article16Policy",
+    "FIDE_2024_POLICY",
+    "FIDE_2026_SWISS_POLICY",
+    "FIDE_2026_RR_POLICY",
+    "resolve_policy",
+]