Metadata-Version: 2.5
Name: r055y
Version: 1.4.0
Summary: Analytics utilities and modelling foundations for R-LAY.
Author: Ross Lindsay
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: pydantic<3,>=2.8
Provides-Extra: test
Requires-Dist: pytest<10,>=8; extra == 'test'
Description-Content-Type: text/markdown

# 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

```bash
pip install r055y
```

`r055y` supports Python 3.10 and newer.

## What is included

The published 1.3.0 line provides these 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.
- **Markets and training** — American-odds de-vigging, point-in-time observations, chronological splits, deterministic logistic fitting, scorecards, and champion/challenger gates.

The next minor release is in development under `Unreleased`. It adds dependency-light ridge regression for continuous outcomes, calibrated distribution forecasts with empirical 80% ranges, and deterministic Gaussian-copula simulation for correlated legs. The installed package remains 1.3.0 until a deliberate release.

## Quick start

### Elo ratings

```python
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

```python
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

```python
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

```text
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
  props/        Continuous calibration and joint-event probability
```

## Development

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

`r055y` stays deliberately small and provider-neutral. Feature stores, licensed data, bookmaker adapters, model artifacts, and product interfaces belong to applications such as R-LAY.
