unirating 0.1.0__py3-none-any.whl

unirating/__init__.py

@@ -0,0 +1,35 @@
+"""unirating — Bayesian inverse-variance fusion of FIDE, Chess.com and Lichess ratings.
+
+Public API:
+    Rating, Prior, Calibration, TimeControl, FusionResult, fuse
+    InvalidRatingError, MissingSigmaWarning, ProvisionalRatingWarning
+
+See README.md and docs/derivation.md for the mathematical background.
+"""
+
+from __future__ import annotations
+
+from ._version import __version__
+from .calibration import Calibration, TimeControl
+from .exceptions import (
+    InvalidRatingError,
+    MissingSigmaWarning,
+    ProvisionalRatingWarning,
+    UniratingError,
+)
+from .fusion import fuse
+from .models import FusionResult, Prior, Rating
+
+__all__ = [
+    "Calibration",
+    "FusionResult",
+    "InvalidRatingError",
+    "MissingSigmaWarning",
+    "Prior",
+    "ProvisionalRatingWarning",
+    "Rating",
+    "TimeControl",
+    "UniratingError",
+    "__version__",
+    "fuse",
+]

unirating/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

unirating/calibration.py

@@ -0,0 +1,103 @@
+"""Source <-> FIDE affine calibration constants per time control.
+
+A measurement on a non-FIDE source is modelled as
+
+    R_source = alpha + beta * theta + noise
+
+so the FIDE-equivalent estimate is
+
+    theta_hat = (R_source - alpha) / beta
+
+with variance (sigma_source / beta)^2.
+
+The default constants below come from community regressions; they are not
+authoritative. Pass your own `Calibration` instance to `fuse()` when you have
+better-fitted constants (e.g. a dataset of players holding ratings on multiple
+sites for the time control you care about).
+
+Default sigma values are coarse fallbacks used only when the caller does not
+supply an explicit sigma for a Rating. They will trigger MissingSigmaWarning.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class TimeControl(str, Enum):
+    """Standard chess time-control buckets."""
+
+    BULLET = "bullet"
+    BLITZ = "blitz"
+    RAPID = "rapid"
+    CLASSICAL = "classical"
+
+
+# (chesscom_alpha, chesscom_beta, lichess_alpha, lichess_beta)
+# Source: see docs/citations.md (Lichess FAQ, Chess.com community regressions,
+# Reddit r/chess long-running comparisons).
+_DEFAULT_CALIBRATION_BY_TC: dict[TimeControl, tuple[float, float, float, float]] = {
+    TimeControl.BULLET:    (150.0, 1.0, 400.0, 1.0),
+    TimeControl.BLITZ:     (120.0, 1.0, 350.0, 1.0),
+    TimeControl.RAPID:     (100.0, 1.0, 250.0, 1.0),
+    TimeControl.CLASSICAL: ( 50.0, 1.0, 200.0, 1.0),
+}
+
+
+# Default fallback sigmas (per native scale) when a Rating supplies no sigma.
+# Deliberately conservative so a missing-sigma input contributes little.
+_DEFAULT_SIGMA_BY_TC: dict[TimeControl, dict[str, float]] = {
+    TimeControl.BULLET:    {"fide": 100.0, "chesscom": 100.0, "lichess": 100.0},
+    TimeControl.BLITZ:     {"fide":  90.0, "chesscom":  90.0, "lichess":  90.0},
+    TimeControl.RAPID:     {"fide":  80.0, "chesscom":  80.0, "lichess":  80.0},
+    TimeControl.CLASSICAL: {"fide":  70.0, "chesscom":  70.0, "lichess":  70.0},
+}
+
+
+@dataclass(frozen=True)
+class Calibration:
+    """Affine calibration source -> FIDE.
+
+    For FIDE the identity is implicit: alpha=0, beta=1.
+
+    Override any subset of fields; the rest are filled from the time-control
+    defaults at fuse() time.
+    """
+
+    chesscom_alpha: float = float("nan")
+    chesscom_beta: float = float("nan")
+    lichess_alpha: float = float("nan")
+    lichess_beta: float = float("nan")
+
+    @classmethod
+    def for_time_control(cls, tc: TimeControl) -> Calibration:
+        a_c, b_c, a_l, b_l = _DEFAULT_CALIBRATION_BY_TC[tc]
+        return cls(
+            chesscom_alpha=a_c,
+            chesscom_beta=b_c,
+            lichess_alpha=a_l,
+            lichess_beta=b_l,
+        )
+
+    def filled(self, tc: TimeControl) -> Calibration:
+        """Return a Calibration with NaN slots filled from the TC defaults."""
+        import math
+
+        a_c, b_c, a_l, b_l = _DEFAULT_CALIBRATION_BY_TC[tc]
+        return Calibration(
+            chesscom_alpha=self.chesscom_alpha if math.isfinite(self.chesscom_alpha) else a_c,
+            chesscom_beta=self.chesscom_beta if math.isfinite(self.chesscom_beta) else b_c,
+            lichess_alpha=self.lichess_alpha if math.isfinite(self.lichess_alpha) else a_l,
+            lichess_beta=self.lichess_beta if math.isfinite(self.lichess_beta) else b_l,
+        )
+
+
+def default_sigma(tc: TimeControl, source: str) -> float:
+    """Fallback sigma on the source's native scale when the caller omits one."""
+    try:
+        return _DEFAULT_SIGMA_BY_TC[tc][source]
+    except KeyError as exc:
+        raise KeyError(
+            f"no default sigma registered for time_control={tc!r} source={source!r}"
+        ) from exc

unirating/cli.py

@@ -0,0 +1,113 @@
+"""Command-line interface for unirating."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from . import __version__
+from .calibration import TimeControl
+from .fusion import fuse
+from .models import Prior, Rating
+
+
+def _maybe_rating(value: float | None, sigma: float | None) -> Rating | None:
+    if value is None:
+        return None
+    return Rating(value=value, sigma=sigma)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="unirating",
+        description=(
+            "Fuse FIDE, Chess.com and Lichess ratings into a single FIDE-scale "
+            "rating using Bayesian inverse-variance weighting."
+        ),
+    )
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    p.add_argument(
+        "--time-control", "-t",
+        choices=[tc.value for tc in TimeControl],
+        default=TimeControl.RAPID.value,
+        help="Time control bucket all ratings belong to (default: rapid).",
+    )
+    p.add_argument("--fide", type=float, default=None, help="FIDE rating value.")
+    p.add_argument("--fide-sigma", type=float, default=None,
+                   help="FIDE rating 1-sigma uncertainty (default: time-control fallback).")
+    p.add_argument("--chesscom", type=float, default=None, help="Chess.com rating value.")
+    p.add_argument("--chesscom-rd", type=float, default=None,
+                   help="Chess.com Glicko RD (preferred name for --chesscom-sigma).")
+    p.add_argument("--chesscom-sigma", type=float, default=None,
+                   help=argparse.SUPPRESS)
+    p.add_argument("--lichess", type=float, default=None, help="Lichess rating value.")
+    p.add_argument("--lichess-rd", type=float, default=None,
+                   help="Lichess Glicko-2 RD (preferred name for --lichess-sigma).")
+    p.add_argument("--lichess-sigma", type=float, default=None,
+                   help=argparse.SUPPRESS)
+    p.add_argument("--prior-mu", type=float, default=None,
+                   help="Prior mean on the FIDE scale (default: 1500).")
+    p.add_argument("--prior-sigma", type=float, default=None,
+                   help="Prior std-dev on the FIDE scale (default: 350).")
+    p.add_argument("--json", action="store_true",
+                   help="Emit a JSON object instead of human-readable output.")
+    return p
+
+
+def _pct(x: float) -> str:
+    return f"{100.0 * x:.0f}%"
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    tc = TimeControl(args.time_control)
+
+    cc_sigma = args.chesscom_rd if args.chesscom_rd is not None else args.chesscom_sigma
+    li_sigma = args.lichess_rd if args.lichess_rd is not None else args.lichess_sigma
+
+    prior_kwargs = {}
+    if args.prior_mu is not None:
+        prior_kwargs["mu"] = args.prior_mu
+    if args.prior_sigma is not None:
+        prior_kwargs["sigma"] = args.prior_sigma
+    prior = Prior(**prior_kwargs) if prior_kwargs else None
+
+    result = fuse(
+        fide=_maybe_rating(args.fide, args.fide_sigma),
+        chesscom=_maybe_rating(args.chesscom, cc_sigma),
+        lichess=_maybe_rating(args.lichess, li_sigma),
+        time_control=tc,
+        prior=prior,
+    )
+
+    if args.json:
+        import json
+
+        payload = {
+            "rating": result.rating,
+            "sigma": result.sigma,
+            "ci95_low": result.ci95[0],
+            "ci95_high": result.ci95[1],
+            "used_sources": list(result.used_sources),
+            "is_prior_only": result.is_prior_only,
+            "contributions": dict(result.contributions),
+            "prior": {"mu": result.prior.mu, "sigma": result.prior.sigma},
+            "time_control": tc.value,
+        }
+        print(json.dumps(payload, indent=2))
+    else:
+        low, high = result.ci95
+        sources = ", ".join(result.used_sources) if result.used_sources else "(none, prior only)"
+        contrib_parts = [f"{k}={_pct(v)}" for k, v in result.contributions.items()]
+        print(f"Unified rating (FIDE scale): {result.rating:.0f} +/- {result.sigma:.0f}")
+        print(f"95% CI: [{low:.0f}, {high:.0f}]")
+        print(f"Sources used: {sources}")
+        print(f"Contributions: {'  '.join(contrib_parts)}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

unirating/exceptions.py

@@ -0,0 +1,35 @@
+"""Exception and warning types raised by unirating."""
+
+from __future__ import annotations
+
+
+class UniratingError(Exception):
+    """Base class for all errors raised by this package."""
+
+
+class InvalidRatingError(UniratingError, ValueError):
+    """Raised when a Rating or Prior contains an invalid value.
+
+    Cases:
+        - non-finite value or sigma (NaN, +/-inf)
+        - non-positive sigma
+        - rating outside the configured plausible bounds
+    """
+
+
+class MissingSigmaWarning(UserWarning):
+    """Emitted when a Rating has no sigma and a default had to be substituted.
+
+    A default sigma is a coarse approximation. Pass an explicit sigma whenever
+    you can — Lichess exposes RD via the public API, and Chess.com exposes it
+    via /pub/player/{user}/stats.
+    """
+
+
+class ProvisionalRatingWarning(UserWarning):
+    """Emitted when a rating's sigma indicates a provisional account.
+
+    Glicko-2 considers RD >= 110 provisional (Lichess shows '?' next to it).
+    The fusion still works — such ratings simply receive near-zero weight —
+    but the caller is warned in case they want to treat it specially.
+    """

unirating/fusion.py

@@ -0,0 +1,161 @@
+"""The fusion entry point.
+
+`fuse()` computes the Bayesian posterior mean and standard deviation of the
+latent FIDE-scale skill theta given any subset of {FIDE, Chess.com, Lichess}
+ratings, with a Gaussian prior. See docs/derivation.md for the proof.
+"""
+
+from __future__ import annotations
+
+import math
+import warnings
+
+from .calibration import Calibration, TimeControl, default_sigma
+from .exceptions import (
+    InvalidRatingError,
+    MissingSigmaWarning,
+    ProvisionalRatingWarning,
+)
+from .models import FusionResult, Prior, Rating
+
+# Glicko-2 threshold beyond which Lichess displays '?' (provisional).
+_PROVISIONAL_RD_THRESHOLD = 110.0
+
+
+def _coerce_sigma(
+    source: str,
+    rating: Rating,
+    tc: TimeControl,
+) -> float:
+    """Return the sigma to use for `rating`, emitting warnings where needed."""
+    if rating.sigma is None:
+        fallback = default_sigma(tc, source)
+        warnings.warn(
+            f"{source}: no sigma supplied; using default {fallback} for "
+            f"time_control={tc.value!r}. Pass an explicit sigma (e.g. the "
+            "Glicko RD from the API) for a tighter estimate.",
+            MissingSigmaWarning,
+            stacklevel=3,
+        )
+        return fallback
+
+    sigma = float(rating.sigma)
+    if source in {"chesscom", "lichess"} and sigma >= _PROVISIONAL_RD_THRESHOLD:
+        warnings.warn(
+            f"{source}: sigma={sigma} indicates a provisional rating "
+            f"(>= {_PROVISIONAL_RD_THRESHOLD}); it will receive very little "
+            "weight in the fusion.",
+            ProvisionalRatingWarning,
+            stacklevel=3,
+        )
+    return sigma
+
+
+def fuse(
+    *,
+    fide: Rating | None = None,
+    chesscom: Rating | None = None,
+    lichess: Rating | None = None,
+    time_control: TimeControl = TimeControl.RAPID,
+    prior: Prior | None = None,
+    calibration: Calibration | None = None,
+) -> FusionResult:
+    """Fuse up to three ratings into a single FIDE-scale rating.
+
+    Args:
+        fide: FIDE rating measurement, or None if unavailable.
+        chesscom: Chess.com rating measurement, or None if unavailable.
+        lichess: Lichess rating measurement, or None if unavailable.
+        time_control: Which time-control bucket the ratings belong to.
+            All three Rating arguments MUST be from the same bucket --
+            mixing time controls is a user error this function cannot
+            detect, so the caller is responsible.
+        prior: Gaussian prior over the latent skill theta on the FIDE scale.
+            Defaults to N(1500, 350^2).
+        calibration: Affine source->FIDE calibration. Any field left as NaN
+            is filled from the per-time-control defaults. Defaults to the
+            time-control defaults entirely.
+
+    Returns:
+        A FusionResult on the FIDE scale.
+
+    Raises:
+        TypeError: if `time_control` is not a TimeControl.
+        InvalidRatingError: if any Rating or Prior is malformed
+            (already raised at construction time, but re-raised here for
+            programmatic checks like negative beta).
+    """
+    if not isinstance(time_control, TimeControl):
+        raise TypeError(
+            f"time_control must be a TimeControl, got {type(time_control).__name__}"
+        )
+
+    prior = prior if prior is not None else Prior()
+    calibration = (calibration or Calibration()).filled(time_control)
+
+    # Sanity-check calibration slopes -- a zero or non-finite beta would
+    # produce a degenerate (infinite-variance) calibrated estimate.
+    for name, beta in (
+        ("chesscom_beta", calibration.chesscom_beta),
+        ("lichess_beta", calibration.lichess_beta),
+    ):
+        if not math.isfinite(beta) or beta <= 0.0:
+            raise InvalidRatingError(
+                f"Calibration.{name} must be a positive finite number, got {beta!r}"
+            )
+
+    # Accumulators on the FIDE scale.
+    # We work in PRECISION space (1/variance) to avoid catastrophic
+    # cancellation when one source dominates the others.
+    w_total = prior.precision
+    wx_total = prior.mu * prior.precision
+
+    per_source_weight: dict[str, float] = {"prior": prior.precision}
+    used_sources: list[str] = []
+
+    if fide is not None:
+        sigma = _coerce_sigma("fide", fide, time_control)
+        theta_hat = float(fide.value)            # alpha=0, beta=1
+        tau2 = sigma * sigma                     # variance on FIDE scale
+        w = 1.0 / tau2
+        w_total += w
+        wx_total += w * theta_hat
+        per_source_weight["fide"] = w
+        used_sources.append("fide")
+
+    if chesscom is not None:
+        sigma = _coerce_sigma("chesscom", chesscom, time_control)
+        a, b = calibration.chesscom_alpha, calibration.chesscom_beta
+        theta_hat = (float(chesscom.value) - a) / b
+        tau2 = (sigma * sigma) / (b * b)
+        w = 1.0 / tau2
+        w_total += w
+        wx_total += w * theta_hat
+        per_source_weight["chesscom"] = w
+        used_sources.append("chesscom")
+
+    if lichess is not None:
+        sigma = _coerce_sigma("lichess", lichess, time_control)
+        a, b = calibration.lichess_alpha, calibration.lichess_beta
+        theta_hat = (float(lichess.value) - a) / b
+        tau2 = (sigma * sigma) / (b * b)
+        w = 1.0 / tau2
+        w_total += w
+        wx_total += w * theta_hat
+        per_source_weight["lichess"] = w
+        used_sources.append("lichess")
+
+    # w_total can never be 0: the prior always contributes prior.precision > 0.
+    posterior_mu = wx_total / w_total
+    posterior_sigma = math.sqrt(1.0 / w_total)
+
+    contributions = {k: v / w_total for k, v in per_source_weight.items()}
+
+    return FusionResult(
+        rating=posterior_mu,
+        sigma=posterior_sigma,
+        contributions=contributions,
+        used_sources=tuple(used_sources),
+        is_prior_only=len(used_sources) == 0,
+        prior=prior,
+    )

unirating/models.py

@@ -0,0 +1,143 @@
+"""Data models: Rating, Prior, FusionResult.
+
+All models are immutable (frozen dataclasses) and validate on construction.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+
+from .exceptions import InvalidRatingError
+
+# Plausible rating bounds on the native scale of any of the three systems.
+# Wide enough to admit any human rating ever recorded; tight enough to catch
+# obvious typos (e.g. someone passing a percentage instead of an Elo).
+_DEFAULT_MIN_RATING = 100.0
+_DEFAULT_MAX_RATING = 3500.0
+
+# Default prior on the FIDE scale.
+# mu0=1500 is the historical Elo starting point and roughly the world median
+# of rated adult club players. sigma0=350 covers ~800-2200 within +/-2sigma.
+_DEFAULT_PRIOR_MU = 1500.0
+_DEFAULT_PRIOR_SIGMA = 350.0
+
+
+def _validate_finite(name: str, value: float) -> None:
+    if not math.isfinite(value):
+        raise InvalidRatingError(f"{name} must be a finite number, got {value!r}")
+
+
+def _validate_rating_bounds(
+    value: float,
+    min_value: float = _DEFAULT_MIN_RATING,
+    max_value: float = _DEFAULT_MAX_RATING,
+) -> None:
+    if not (min_value <= value <= max_value):
+        raise InvalidRatingError(
+            f"rating value {value!r} is outside the plausible range "
+            f"[{min_value}, {max_value}]. If your data legitimately lies "
+            f"outside, construct Rating with min_value/max_value overrides."
+        )
+
+
+@dataclass(frozen=True)
+class Rating:
+    """A noisy measurement of a player's strength from a single source.
+
+    Attributes:
+        value: The rating on the source's native scale (FIDE Elo, Chess.com
+            Glicko, Lichess Glicko-2, etc.).
+        sigma: The 1-sigma measurement uncertainty on the same native scale.
+            For Lichess and Chess.com this is the Glicko RD exposed by the API.
+            For FIDE, use a rule of thumb (~60 for settled players) or
+            leave as None to fall back to a coarse default.
+        min_value, max_value: Plausibility bounds for the rating value.
+            Defaults reject anything outside [100, 3500].
+    """
+
+    value: float
+    sigma: float | None = None
+    min_value: float = _DEFAULT_MIN_RATING
+    max_value: float = _DEFAULT_MAX_RATING
+
+    def __post_init__(self) -> None:
+        _validate_finite("Rating.value", float(self.value))
+        _validate_rating_bounds(float(self.value), self.min_value, self.max_value)
+        if self.sigma is not None:
+            _validate_finite("Rating.sigma", float(self.sigma))
+            if self.sigma <= 0.0:
+                raise InvalidRatingError(
+                    f"Rating.sigma must be strictly positive, got {self.sigma!r}. "
+                    "A non-positive sigma implies infinite precision, which is "
+                    "never true of a real rating measurement."
+                )
+
+
+@dataclass(frozen=True)
+class Prior:
+    """Gaussian prior on the latent FIDE-scale skill theta.
+
+    Defaults to N(1500, 350^2), appropriate for an adult club-player
+    population. Lower mu for juniors, raise it for titled-player populations.
+
+    Attributes:
+        mu: Prior mean of latent skill (FIDE scale).
+        sigma: Prior standard deviation. MUST be strictly positive and finite;
+            use a large value (e.g. 1e6) to obtain an effectively flat prior.
+    """
+
+    mu: float = _DEFAULT_PRIOR_MU
+    sigma: float = _DEFAULT_PRIOR_SIGMA
+
+    def __post_init__(self) -> None:
+        _validate_finite("Prior.mu", float(self.mu))
+        _validate_finite("Prior.sigma", float(self.sigma))
+        if self.sigma <= 0.0:
+            raise InvalidRatingError(
+                f"Prior.sigma must be strictly positive, got {self.sigma!r}."
+            )
+
+    @property
+    def precision(self) -> float:
+        """1 / sigma^2."""
+        return 1.0 / (self.sigma * self.sigma)
+
+
+@dataclass(frozen=True)
+class FusionResult:
+    """The output of `fuse()`.
+
+    Attributes:
+        rating: The unified rating on the FIDE scale (posterior mean of theta).
+        sigma: 1-sigma posterior uncertainty on the FIDE scale.
+        contributions: For each source key ('prior', 'fide', 'chesscom',
+            'lichess'), its share of the total precision -- i.e. how much
+            it pulled the answer. Always sums to 1.0.
+        used_sources: The subset of {'fide', 'chesscom', 'lichess'} that
+            actually contributed observations (sigma>0 and value present).
+        is_prior_only: True iff no rating sources were available and the
+            returned (rating, sigma) is exactly the prior.
+        prior: The Prior used.
+    """
+
+    rating: float
+    sigma: float
+    contributions: Mapping[str, float] = field(default_factory=dict)
+    used_sources: tuple[str, ...] = ()
+    is_prior_only: bool = False
+    prior: Prior = field(default_factory=Prior)
+
+    @property
+    def ci95(self) -> tuple[float, float]:
+        """The 95% credible interval, computed as mean +/- 1.96 sigma."""
+        half = 1.96 * self.sigma
+        return (self.rating - half, self.rating + half)
+
+    def __repr__(self) -> str:
+        sources = ",".join(self.used_sources) if self.used_sources else "prior-only"
+        return (
+            f"FusionResult(rating={self.rating:.1f}, sigma={self.sigma:.1f}, "
+            f"sources=[{sources}])"
+        )

unirating-0.1.0.dist-info/METADATA

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: unirating
+Version: 0.1.0
+Summary: Bayesian inverse-variance fusion of FIDE, Chess.com and Lichess ratings into a single FIDE-scale rating.
+Project-URL: Homepage, https://github.com/souravsahums/unirating
+Project-URL: Documentation, https://github.com/souravsahums/unirating#readme
+Project-URL: Issues, https://github.com/souravsahums/unirating/issues
+Project-URL: Source, https://github.com/souravsahums/unirating
+Author-email: Sourav Sahu <souravsahu@duck.com>
+License: MIT License
+        
+        Copyright (c) 2026 Sourav Sahu
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: bayesian,chess,chess.com,elo,fide,glicko,lichess,meta-analysis,rating,sensor-fusion
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment :: Board Games
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: hypothesis>=6; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-cov>=4; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: hypothesis>=6; extra == 'test'
+Requires-Dist: pytest-cov>=4; extra == 'test'
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# unirating
+
+[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+> Author: **Sourav Sahu** ([@souravsahums](https://github.com/souravsahums))
+
+Bayesian inverse-variance **fusion** of a player's **FIDE**, **Chess.com** and **Lichess** ratings into a single number on the **FIDE scale**, with proper handling of missing ratings, calibrated per time control.
+
+The estimator is the **maximum-likelihood / Best Linear Unbiased Estimator** (Gauss–Markov) when all sources are present, and the **posterior mean of a Gaussian–Gaussian Bayesian model** when one or more sources are missing — so a player with no ratings at all gracefully degrades to the population prior (the "base rating") rather than crashing.
+
+Full mathematical derivation with proof: [docs/derivation.md](docs/derivation.md).
+Citations: [docs/citations.md](docs/citations.md).
+
+---
+
+## Install
+
+```bash
+pip install unirating
+```
+
+Zero runtime dependencies. Python 3.9+.
+
+---
+
+## Quick start
+
+```python
+from unirating import Rating, TimeControl, fuse
+
+result = fuse(
+    fide       = Rating(value=1820, sigma=60),   # FIDE Rapid, settled
+    chesscom   = Rating(value=1950, sigma=55),   # Chess.com Rapid, RD=55
+    lichess    = Rating(value=2100, sigma=50),   # Lichess Rapid, RD=50
+    time_control = TimeControl.RAPID,
+)
+
+print(result.rating)        # 1838.95  (FIDE scale)
+print(result.sigma)         # 31.36    (1-sigma uncertainty)
+print(result.ci95)          # (1777.5, 1900.4)
+print(result.contributions) # per-source weight share, sums to 1.0
+```
+
+A player with no ratings at all:
+
+```python
+from unirating import fuse, TimeControl
+
+result = fuse(time_control=TimeControl.RAPID)
+print(result.rating)  # 1500.0  (prior mean — the "base rating")
+print(result.sigma)   # 350.0   (prior std-dev — full uncertainty)
+print(result.is_prior_only)  # True
+```
+
+Lichess gives you the RD directly via API — pass it in. If you only have the rating number, the package will use a sensible default $\sigma$ but you should treat the result as approximate:
+
+```python
+from unirating import Rating, TimeControl, fuse
+
+result = fuse(
+    lichess = Rating(value=1850),   # sigma=None → default used + warning
+    time_control = TimeControl.RAPID,
+)
+```
+
+---
+
+## What's in the box
+
+| Module | Purpose |
+|---|---|
+| [`unirating.fuse`](src/unirating/fusion.py) | The main entry point — call this. |
+| [`unirating.Rating`](src/unirating/models.py) | Immutable `(value, sigma)` measurement. |
+| [`unirating.Prior`](src/unirating/models.py) | Gaussian prior over latent skill. Defaults to $\mathcal N(1500, 350^2)$. |
+| [`unirating.Calibration`](src/unirating/calibration.py) | Affine map source ↔ FIDE. Defaults per time control. |
+| [`unirating.TimeControl`](src/unirating/calibration.py) | `BULLET`, `BLITZ`, `RAPID`, `CLASSICAL`. |
+| [`unirating.FusionResult`](src/unirating/models.py) | `(rating, sigma, ci95, contributions, used_sources, …)`. |
+| `unirating` (CLI) | One-shot fusion from the shell. |
+
+---
+
+## CLI
+
+```bash
+unirating \
+  --fide 1820 --fide-sigma 60 \
+  --chesscom 1950 --chesscom-rd 55 \
+  --lichess 2100 --lichess-rd 50 \
+  --time-control rapid
+```
+
+Output:
+
+```
+Unified rating (FIDE scale): 1839 ± 31
+95% CI: [1778, 1900]
+Sources used: fide, chesscom, lichess
+Contributions: prior=1%  fide=27%  chesscom=33%  lichess=39%
+```
+
+---
+
+## How the math works (one paragraph)
+
+Each rating is treated as a noisy linear measurement $R_i = \alpha_i + \beta_i \theta + \varepsilon_i$, $\varepsilon_i \sim \mathcal N(0, \sigma_i^2)$, of the latent FIDE-equivalent skill $\theta$. After inverting each measurement to a FIDE-scale estimate $\hat\theta_i$ with variance $\tau_i^2 = \sigma_i^2/\beta_i^2$, the **posterior mean of $\theta$** given a Gaussian prior $\mathcal N(\mu_0, \sigma_0^2)$ is the precision-weighted average
+
+$$
+\hat\theta = \frac{\mu_0/\sigma_0^2 + \sum_{i \in S} \hat\theta_i/\tau_i^2}{1/\sigma_0^2 + \sum_{i \in S} 1/\tau_i^2}
+$$
+
+over whatever subset $S$ of sources is present. With no sources, the formula collapses to $\mu_0$. The full proof (MLE + Gauss–Markov + Bayes), the choice of constants, and a worked example are in [docs/derivation.md](docs/derivation.md).
+
+---
+
+## Calibration constants (defaults)
+
+| Time control | Chess.com $\alpha,\beta$ | Lichess $\alpha,\beta$ |
+|---|---|---|
+| `BULLET`    | 150, 1.0 | 400, 1.0 |
+| `BLITZ`     | 120, 1.0 | 350, 1.0 |
+| `RAPID`     | 100, 1.0 | 250, 1.0 |
+| `CLASSICAL` |  50, 1.0 | 200, 1.0 |
+
+Source: published community regressions (see [docs/citations.md](docs/citations.md)). You can override per call:
+
+```python
+from unirating import Calibration, fuse
+
+custom = Calibration(chesscom_alpha=80, lichess_alpha=300)
+result = fuse(..., calibration=custom)
+```
+
+---
+
+## Edge cases handled
+
+- **No ratings** → returns prior, `is_prior_only=True`.
+- **One rating** → posterior shrinks toward prior; weight reported.
+- **Missing $\sigma_i$** → fills with conservative default, emits `MissingSigmaWarning`.
+- **Provisional rating** (large RD, Lichess `?`) → naturally down-weighted; warns if RD > 110.
+- **Zero / negative $\sigma_i$** → raises `InvalidRatingError`.
+- **Non-finite values** (`nan`, `inf`) → raises `InvalidRatingError`.
+- **Out-of-range ratings** → raises `InvalidRatingError` (configurable bounds).
+- **Mixed time controls** → only one `TimeControl` per call; the calibration enforces consistency.
+- **Custom prior** → pass any `Prior(mu, sigma)` (e.g. for juniors, titled players).
+- **Numerical stability** → all sums computed in precision-space then inverted at the end.
+
+See [tests/](tests/) for the formal coverage.
+
+---
+
+## Citation
+
+If you use this package in academic work, please cite:
+
+```bibtex
+@software{sahu_unirating_2026,
+  author  = {Sahu, Sourav},
+  title   = {unirating: Bayesian inverse-variance fusion of FIDE,
+             Chess.com and Lichess ratings},
+  year    = {2026},
+  url     = {https://github.com/souravsahums/unirating},
+  version = {0.1.0},
+}
+```
+
+Plain text: Sahu, S. (2026). *unirating: Bayesian inverse-variance fusion of FIDE, Chess.com and Lichess ratings* (v0.1.0) [Computer software]. https://github.com/souravsahums/unirating
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE). Copyright © 2026 Sourav Sahu.

unirating-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+unirating/__init__.py,sha256=rZYr2a12EsiGLIi55zwiGauELPo7CLxiOc1dFMBultU,906
+unirating/_version.py,sha256=QTYqXqSTHFRkM9TEgpDFcHvwLbvqHDqvqfQ9EiXkcAM,23
+unirating/calibration.py,sha256=EUJnHamy6WOX8gikwNSvxnpIydfcC1F0fZC7L2EvQVM,3801
+unirating/cli.py,sha256=SW74NputKnLCcqxlWfvS2vTPVKAITs3zhN1U8MaDzjY,4419
+unirating/exceptions.py,sha256=4tDCFqcacPy2KicbEnHWG64fjb6hJaJWKe9LmncuyJg,1173
+unirating/fusion.py,sha256=NhtsJ-b2Idt_KIpXKsv03vDIIhBt10Fz8AqYd_NHV3E,6026
+unirating/models.py,sha256=KWOwVUrcE6GZPPzLqzQlrPgFjeMZl2McVGE6k33dBoQ,5464
+unirating/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+unirating-0.1.0.dist-info/METADATA,sha256=uoC_CksqW07d9bhRT7eo-UArfZqPDNLuj_OecoYUWPk,9481
+unirating-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+unirating-0.1.0.dist-info/entry_points.txt,sha256=gORoXeeDenHl7p6C_P13HNlbA1WfzU6gnrDjA8KQ2F8,49
+unirating-0.1.0.dist-info/licenses/LICENSE,sha256=pRsC9XFLTKAVp345FiHOt82M6gv5nhadRatN2d5HnPA,1089
+unirating-0.1.0.dist-info/RECORD,,

unirating-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

unirating-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+unirating = unirating.cli:main

unirating-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sourav Sahu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.