Keeks

A Python library for optimal bankroll allocation and betting strategies, with a focus on the Kelly Criterion and its variants.

Full documentation at keeks.mcginniscommawill.com.

Nine-strategy risk benchmark — what growth, drawdown and early-stop behaviour each shipped strategy actually produces under identical, seeded assumptions, and how that changes with edge, cost, probability-estimate error and the bankroll's loss cap. Regenerate every number with uv run python benchmarks/strategy_benchmark.py.

What is Keeks?

Keeks is a specialized Python library designed to help you implement and test various betting and investment strategies. It provides tools for:

• Bankroll management: Track and manage your funds with built-in protection against excessive losses
• Betting strategies: Implement mathematically optimal strategies like the Kelly Criterion
• Simulation: Test your strategies under different conditions before risking real money

Whether you're a sports bettor, a financial trader, or a researcher in decision theory, Keeks provides the tools to make more informed decisions about capital allocation.

Why Use Keeks?

• Mathematically sound: Based on proven mathematical principles like the Kelly Criterion
• Risk management: Built-in protection against ruin with configurable drawdown limits
• Simulation-driven: Test strategies in various scenarios before applying them with real money
• Flexible: Supports different types of betting scenarios and probability distributions
• Educational: Learn about optimal betting strategies through practical implementation

Disclaimer: This library is for educational purposes only. It is not intended to provide investment, legal, or tax advice. Always be responsible and consult with a professional before applying these strategies to real-world betting or investment scenarios. The authors and contributors of this library are not liable for any financial losses or damages that may result from the use of this software.

Installation

pip install keeks

Quick Start

Here's a simple example of how to use Keeks to simulate a betting strategy:

from keeks.bankroll import BankRoll
from keeks.binary_strategies.kelly import KellyCriterion
from keeks.simulators.repeated_binary import RepeatedBinarySimulator

# Create a bankroll with initial funds
bankroll = BankRoll(initial_funds=1000.0, max_draw_down=0.3)

# Create a Kelly Criterion strategy
# Parameters: payoff, loss, transaction_cost
strategy = KellyCriterion(payoff=1.0, loss=1.0, transaction_cost=0.01)

# Create a simulator with a fixed probability
simulator = RepeatedBinarySimulator(
    payoff=1.0,
    loss=1.0,
    transaction_costs=0.01,
    probability=0.55,  # 55% chance of winning
    trials=1000,
)

# Run the simulation
simulator.evaluate_strategy(strategy, bankroll)

# Plot the results
bankroll.plot_history()

Examples

St. Petersburg Paradox Simulation

The St. Petersburg paradox is a theoretical game with infinite expected value but finite practical outcomes. Our example compares all binary strategies using a simplified binary model with favorable odds.

python -m examples.st_petersburg_comparison

The example simulates various strategies under favorable betting conditions and visualizes the results:

This chart shows the distribution of final bankrolls across different betting strategies after multiple simulations. Notice how Optimal-F and Kelly Criterion achieved the highest returns but with greater volatility, while more conservative strategies like Quarter Kelly had more consistent (but lower) returns.

For more examples, check the examples directory.

Key Features

Bankroll Management

The BankRoll class provides a way to track your funds and enforce risk management:

# Create a bankroll with $1000, allowing only 80% to be bet, and a 30% max drawdown limit
bankroll = BankRoll(initial_funds=1000.0, percent_bettable=0.8, max_draw_down=0.3)

Betting Strategies

Keeks implements several betting strategies:

1. Kelly Criterion: The mathematically optimal strategy for maximizing the logarithm of wealth

   kelly = KellyCriterion(payoff=1.0, loss=1.0, transaction_cost=0.01)
   

2. Fractional Kelly: A more conservative version of Kelly that reduces volatility

   fractional_kelly = FractionalKellyCriterion(
       payoff=1.0, loss=1.0, transaction_cost=0.01, fraction=0.5
   )
   

3. Drawdown-Adjusted Kelly: A Kelly variant that adjusts bet sizing based on risk tolerance

   drawdown_kelly = DrawdownAdjustedKelly(
       payoff=1.0, loss=1.0, transaction_cost=0.01, max_acceptable_drawdown=0.2
   )
   

4. OptimalF (Ralph Vince): Strategy that maximizes geometric growth rate

   from keeks.binary_strategies.simple import OptimalF
   
   optimal_f = OptimalF(
       payoff=1.0, loss=1.0, transaction_cost=0.01, win_rate=0.55, max_risk_fraction=0.2
   )
   

5. Fixed Fraction: Simple strategy that bets a constant percentage of the bankroll

   fixed_fraction = FixedFractionStrategy(
       fraction=0.05, payoff=1.0, loss=1.0, transaction_cost=0.01, min_probability=0.5
   )
   

6. CPPI (Constant Proportion Portfolio Insurance): Strategy that protects a floor value while allowing upside exposure

   cppi = CPPIStrategy(
       floor_fraction=0.5,
       multiplier=2.0,
       initial_bankroll=1000.0,
       payoff=1.0,
       loss=1.0,
       transaction_cost=0.01,
   )
   

7. Dynamic Bankroll Management: Adaptive strategy based on recent performance

   dynamic = DynamicBankrollManagement(
       base_fraction=0.1, payoff=1.0, loss=1.0, transaction_cost=0.01, window_size=10
   )
   

8. Merton Share (CRRA Utility): Based on Merton's portfolio problem with constant relative risk aversion

   from keeks.binary_strategies.simple import MertonShare
   
   merton = MertonShare(payoff=1.0, loss=1.0, transaction_cost=0.01, risk_aversion=2.0)
   

9. Naive Strategy: A simple strategy that bets the full amount when expected value is positive

   naive = NaiveStrategy(payoff=1.0, loss=1.0, transaction_cost=0.01)
   

Utility Functions

For one-time decision problems (e.g., "What should I pay for this opportunity?"), keeks provides CRRA utility functions:

from keeks.utils import find_indifference_price

# Calculate maximum price you'd pay for a gamble
# Example: St. Petersburg paradox
outcomes = [2**n for n in range(1, 31)]
probabilities = [(0.5) ** n for n in range(1, 31)]

max_price = find_indifference_price(
    outcomes=outcomes,
    probabilities=probabilities,
    current_wealth=10000,
    risk_aversion=2.0,  # 1.0=Kelly, 2.0=moderate, 5.0=conservative
)
# Returns: ~$12.80 despite infinite expected value!

See examples/st_petersburg_paradox.py for a complete demonstration.

Simulators

Test your strategies with different simulators:

1. RepeatedBinarySimulator: For scenarios with a fixed probability
2. RandomBinarySimulator: For scenarios with varying probabilities
3. RandomUncertainBinarySimulator: For scenarios where your probability estimate has uncertainty

Applications

Keeks can be applied to various domains:

• Sports Betting: Optimize your bet sizing based on your edge
• Financial Trading: Apply Kelly principles to portfolio management
• Gambling: Understand the mathematics behind optimal betting
• Research: Study the behavior of different betting strategies
• Education: Learn about probability, statistics, and risk management

Documentation

To build the docs locally:

git clone https://github.com/wdm0006/keeks.git
cd keeks
pip install -e ".[dev]"
make docs

Development

To set up the development environment:

git clone https://github.com/wdm0006/keeks.git
cd keeks
make setup
make install-dev

Run tests:

make test

References

• [1] A New Interpretation of Information Rate - The original Kelly Criterion paper
• [2] The Kelly Criterion in Blackjack, Sports Betting, and the Stock Market - A practical guide to applying the Kelly Criterion
• [3] Fortune's Formula - The untold story of the scientific betting system that beat the casinos and Wall Street

License

MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.