Metadata-Version: 2.4
Name: r055y
Version: 1.1.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 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.

## 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.

## Package layout

```text
src/r055y/
  contracts/    Portable analytics input/output schemas
  evaluation/   Probability scoring and reliability summaries
  ratings/      Transparent rating baselines
```

## Development

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

`r055y` is deliberately small today. Additional feature, modelling, simulation, and optimization utilities will be added as their contracts and evaluation requirements become dependable.
