r055y

r055y ("rossy") is an open-source Python library for building auditable sports analytics and outcome-prediction systems.

It provides the reusable analytics foundation behind R-LAY: strict data contracts, probability evaluation, calibration summaries, and transparent rating baselines that can be used independently in other Python projects.

Install

pip install r055y

r055y supports Python 3.10 and newer.

What is included

The 1.1 release introduces three focused building blocks:

• Contracts — immutable Pydantic models for SPORT SELECT POOLS cards, game predictions, run artifacts, and reproducibility manifests.
• Evaluation — Brier score, binary log loss, and fixed-width calibration bins for probabilistic forecasts.
• Ratings — a stateful Elo baseline with configurable home advantage, neutral-site support, ties, and between-season mean reversion.

The next minor release is now in development and adds timestamped market/training contracts, American-odds de-vigging, chronological splits, a deterministic logistic baseline, and explicit champion/challenger promotion gates. These additions remain under Unreleased; the installed package version stays 1.1.0 until a deliberate 1.2.0 release.

Quick start

Elo ratings

from r055y import EloRatingSystem

ratings = EloRatingSystem()

pregame = ratings.predict("BUF", "MIA")
print(pregame.home_win_probability)

# Updates both teams after the result while preserving the pregame prediction.
ratings.update("BUF", "MIA", home_score=31, away_score=24)

Probability evaluation

from r055y import brier_score, calibration_bins, log_loss

probabilities = [0.72, 0.55, 0.31, 0.84]
outcomes = [1, 0, 0, 1]

print(brier_score(probabilities, outcomes))
print(log_loss(probabilities, outcomes))

for bucket in calibration_bins(probabilities, outcomes, bins=5):
    print(bucket)

Auditable predictions

from r055y import GamePrediction

prediction = GamePrediction(
    game_id="2026_01_MIA_BUF",
    model_name="example-rating-model",
    model_version="1.0.0",
    home_win_probability=0.72,
    predicted_home_margin=4.5,
    reasons=("home-field advantage", "higher pregame rating"),
)

print(prediction.model_dump_json(indent=2))

Contracts reject unknown fields, invalid probabilities, and timezone-naive timestamps so bad inputs fail visibly instead of drifting silently through an analytics pipeline.

Design principles

• Prefer calibrated probabilities over unsupported confidence labels.
• Keep model inputs, versions, outputs, and evaluations traceable.
• Use transparent baselines before adding model complexity.
• Keep provider credentials, scraping logic, operational schedules, private datasets, and website code outside the public library.

Training and model lifecycle

As the library grows, r055y will own the reusable data-science algorithms required to train and improve forecasting systems:

• point-in-time feature construction and temporal training folds;
• model fitting, tuning, ensembling, and probability calibration;
• de-vigged market baselines and prediction settlement against actual results;
• drift measurement and champion-versus-challenger evaluation; and
• versioned model metadata, promotion criteria, and reproducible training reports.

Large or licensed training datasets will not be bundled into the PyPI package. Applications provide their own timestamped odds, results, rosters, and feature tables through public contracts. r055y provides synthetic fixtures and reusable training machinery so the same experiment can be reproduced without embedding private data or credentials.

Continuous improvement does not mean silently changing a production model after every event. New results should create immutable training observations; candidate models should be retrained on a schedule and promoted only after they outperform the current model on predeclared out-of-time probability, calibration, and stability tests.

Package layout

src/r055y/
  contracts/    Portable analytics input/output schemas
  evaluation/   Probability scoring and reliability summaries
  markets/      Odds conversion and bookmaker-margin removal
  ratings/      Transparent rating baselines
  training/     Temporal splitting and deterministic estimators

Development

python -m pip install -e ".[test]"
python -m pytest

r055y is deliberately small today. The training, feature, modelling, simulation, and optimization roadmap above will be implemented as its contracts and evaluation requirements become dependable.