Metadata-Version: 2.5
Name: keeks-elote
Version: 0.2.0
Summary: A project integrating elote and keeks for rating systems and bankroll management.
Project-URL: Homepage, https://github.com/wdm0006/keeks-elote
Project-URL: Repository, https://github.com/wdm0006/keeks-elote
Project-URL: Issues, https://github.com/wdm0006/keeks-elote/issues
Author: Will McGinnis
License-Expression: MIT
License-File: LICENSE
Keywords: backtesting,bankroll,elo,kelly-criterion,rating-systems,sports
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
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 :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Requires-Dist: elote<1.4,>=1.3.0
Requires-Dist: keeks<0.8,>=0.3.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest-mock; extra == 'dev'
Requires-Dist: pytest>=6.2; extra == 'dev'
Requires-Dist: ruff>=0.0.1; extra == 'dev'
Description-Content-Type: text/markdown

# Keeks-Elote

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
<!-- Add badges for build status, coverage, etc. if available -->

A Python library integrating the [`elote`](https://elote.mcginniscommawill.com) rating system library and the [`keeks`](https://keeks.mcginniscommawill.com) bankroll management library to facilitate backtesting and evaluation of combined ranking and betting strategies.

## Purpose

The primary goal of `keeks-elote` is to provide a framework for simulating and analyzing the performance of different rating algorithms (like Elo, Glicko, etc.) when coupled with various bankroll management strategies (like Kelly Criterion, fixed betting, etc.). This allows users to explore how prediction accuracy from rating systems translates into profitability under different staking plans in competitive scenarios (e.g., sports betting, gaming).

## Why is this interesting? (Features)

*   **Integration:** Seamlessly combines rating generation (`elote`) with betting strategy simulation (`keeks`).
*   **Backtesting Framework:** Provides tools to run historical simulations on outcome data.
*   **Flexibility:** Supports multiple rating systems and bankroll management techniques available in the underlying libraries.
*   **Evaluation:** Enables analysis of strategy performance based on metrics like profit/loss, ROI, etc.
*   **Extensibility:** Designed to be potentially extended with custom rating models or betting strategies.

## Installation

```bash
pip install keeks-elote
```

Or from source:

```bash
git clone https://github.com/wdm0006/keeks-elote.git
cd keeks-elote
pip install -e .
```

For development, clone the repository and install in editable mode with development dependencies:

```bash
git clone https://github.com/wdm0006/keeks-elote.git
cd keeks-elote
pip install -e .[dev]
```

## How to Use It

The core idea is to use `elote` to generate ratings and predictions based on historical match/game data and then use `keeks` to simulate betting on those predictions according to a chosen bankroll strategy.

You provide historical outcomes as a `Dict[int, List[dict]]` keyed by period (e.g. week).
Each game dict needs `winner` and `loser` labels, plus optional `winner_odds`/`loser_odds`
in **American** odds (bets are only placed on games that include odds):

```python
from elote.arenas.lambda_arena import LambdaArena
from elote.competitors.glicko import GlickoCompetitor
from keeks.bankroll import BankRoll
from keeks.binary_strategies.kelly import KellyCriterion

from keeks_elote import Backtest

# Historical outcomes, keyed by period (e.g. week). Ratings update from the
# known winner/loser; odds drive the simulated bets in later periods.
data = {
    1: [{"winner": "Alabama", "loser": "Auburn", "winner_odds": -150, "loser_odds": 130}],
    2: [{"winner": "Georgia", "loser": "Florida", "winner_odds": -200, "loser_odds": 175}],
    # ... more periods ...
}

# The arena generates ratings and predictions from the game records. Every game's
# recorded winner is always forwarded to the ratings update, so the lambda is
# never asked to decide a result the data already knows.
arena = LambdaArena(lambda a, b: True, base_competitor=GlickoCompetitor)

# The bankroll and a betting strategy from keeks.
bankroll = BankRoll(initial_funds=10000, percent_bettable=0.5, max_draw_down=1.0)
strategy = KellyCriterion(payoff=1.0, loss=1.0, transaction_cost=0.0)

# Periods up to `period_to_start_betting` are dry runs that only build ratings;
# real bets begin after it. Returns the updated bankroll.
backtest = Backtest(arena)
result = backtest.run_explicit(data, strategy, bankroll, period_to_start_betting=1)
print(result.total_funds)

# Every wager the run settled is also recorded, so a comparison run can be read
# beyond its closing balance.
print(len(backtest.bet_history))
```

The closing `total_funds` conflates hit rate, stake sizing and how many bets were even
placed, so `run_explicit` also fills `Backtest.bet_history`: one dict per wager the run
considered, settled or not, carrying `period`, `label`, `opponent`, `fraction`, the
`stake` actually placed (after the period's exposure scaling and any clamp against
bettable funds), `payoff`, `won`, `profit` and `bankroll_after`. Candidates that moved
no money are recorded too, flagged with `skipped_zero_stake` or `error`, so every bet
the run considered is accounted for. The list is cleared at the start of each
`run_explicit` call, so reusing a `Backtest` never mixes two runs. Aggregations such as
ROI or hit rate are one line of caller code over it.

Failures are part of that accounting: a strategy that raises while pricing a candidate
is recorded the moment it fails (`fraction` of `None` plus the error message), and
`Backtest.run_summary()` condenses the ledger into counts -- placed, failed with their
reasons, skipped, wins/losses and net profit -- so a systematically broken strategy
reads as `failed_bets: N`, never as an empty, plausible-looking run.

Strategies that maintain state through keeks' `record_result(won, return_pct)` hook --
`DynamicBankrollManagement`'s streak and volatility windows, for example -- are notified
of every bet the run actually settles, so their sizing adapts as the backtest progresses.
Strategies without the hook are unaffected, and stateful strategies are always notified
on the instance you passed in, even when each bet is priced by a freshly constructed
re-priced copy. The notification is skipped for candidates that moved no money (a zero
stake or a failed settlement), since there is no settled result to record.

See [`examples/cfb.py`](examples/cfb.py) for a complete end-to-end example using real
college-football data.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
