keeks 0.2.0__py3-none-any.whl

keeks/__init__.py

@@ -0,0 +1,14 @@
+"""
+Keeks: A Python package for simulating and evaluating betting strategies.
+
+Keeks provides tools for implementing and testing various betting strategies,
+particularly focusing on the Kelly Criterion and its variants. The package
+includes:
+
+- Bankroll management: Track and manage funds for betting
+- Binary betting strategies: Implementations of Kelly Criterion and other strategies
+- Simulators: Tools to evaluate strategies under different conditions
+
+The package is designed for educational purposes and to help understand
+optimal betting strategies in various scenarios.
+"""

keeks/bankroll.py

@@ -0,0 +1,175 @@
+import matplotlib.pyplot as plt
+
+from keeks.utils import RuinError
+
+
+class BankRoll:
+    """
+    A class representing a bankroll for betting or investment strategies.
+
+    The BankRoll class manages funds, tracks history, and enforces drawdown limits
+    to prevent catastrophic losses. It provides methods for depositing and withdrawing
+    funds, as well as visualizing the bankroll history.
+
+    Parameters
+    ----------
+    initial_funds : float, default=0.0
+        The starting amount of money in the bankroll.
+    percent_bettable : float, default=1.0
+        The percentage of total funds that can be used for betting (0.0 to 1.0).
+    max_draw_down : float, default=0.3
+        The maximum percentage of funds that can be lost in a single withdrawal (0.0 to 1.0).
+        If None, no drawdown limit is enforced.
+    verbose : int, default=0
+        Controls the verbosity level of the bankroll operations.
+
+    Attributes
+    ----------
+    history : list
+        A list tracking the total funds after each transaction.
+    """
+
+    def __init__(
+        self, initial_funds=0.0, percent_bettable=1.0, max_draw_down=0.3, verbose=0
+    ):
+        self._bank = initial_funds
+        self.percent_bettable = percent_bettable
+        self.max_draw_down = max_draw_down
+        self.verbose = verbose
+        self.history = [initial_funds]
+
+    def update_history(self):
+        """
+        Update the history list with the current total funds.
+
+        This method is called automatically after deposits and withdrawals.
+        """
+        self.history.append(self.total_funds)
+
+    @property
+    def bettable_funds(self):
+        """
+        Calculate the amount of funds available for betting.
+
+        Returns
+        -------
+        float
+            The amount of funds available for betting, calculated as
+            total funds multiplied by the percent_bettable parameter.
+        """
+        return round(self._bank * self.percent_bettable, 2)
+
+    @property
+    def total_funds(self):
+        """
+        Get the total amount of funds in the bankroll.
+
+        Returns
+        -------
+        float
+            The total amount of funds, rounded to 2 decimal places.
+        """
+        return round(self._bank, 2)
+
+    def deposit(self, amt):
+        """
+        Add funds to the bankroll.
+
+        Parameters
+        ----------
+        amt : float
+            The amount to deposit into the bankroll.
+        """
+        self._bank += amt
+        self.update_history()
+
+    def withdraw(self, amt):
+        """
+        Remove funds from the bankroll.
+
+        This method enforces the max_draw_down limit if set, raising a RuinError
+        if the withdrawal would exceed the allowed drawdown.
+
+        Parameters
+        ----------
+        amt : float
+            The amount to withdraw from the bankroll.
+
+        Raises
+        ------
+        RuinError
+            If the withdrawal would exceed the maximum allowed drawdown.
+        """
+        self._bank -= amt
+        if self.max_draw_down and amt > self.max_draw_down * self.total_funds:
+            raise RuinError("You lost too much money buddy, slow down.")
+
+        self.update_history()
+
+    def bet(self, amount):
+        """
+        Place a bet with the specified amount.
+
+        Parameters
+        ----------
+        amount : float
+            The amount to bet.
+
+        Raises
+        ------
+        ValueError
+            If the bet amount exceeds the bettable funds.
+        """
+        if amount > self.bettable_funds:
+            raise ValueError("Bet amount exceeds bettable funds")
+        self._bank -= amount
+        self.update_history()
+
+    def add_funds(self, amount):
+        """
+        Add funds to the bankroll after a winning bet.
+
+        Parameters
+        ----------
+        amount : float
+            The amount to add to the bankroll.
+        """
+        self._bank += amount
+        self.update_history()
+
+    def remove_funds(self, amount):
+        """
+        Remove funds from the bankroll after a losing bet.
+
+        Parameters
+        ----------
+        amount : float
+            The amount to remove from the bankroll.
+
+        Raises
+        ------
+        RuinError
+            If the removal would exceed the maximum allowed drawdown.
+        """
+        if self.max_draw_down and amount > self.max_draw_down * self.total_funds:
+            raise RuinError("You lost too much money buddy, slow down.")
+        self._bank -= amount
+        self.update_history()
+
+    def plot_history(self, fname=None):
+        """
+        Plot the history of the bankroll over time.
+
+        Creates a line plot showing the bankroll value after each transaction.
+
+        Parameters
+        ----------
+        fname : str, optional
+            If provided, saves the plot to the specified filename instead of displaying it.
+        """
+        plt.figure()
+        plt.plot(list(range(len(self.history))), self.history, fmt="bo-")
+        if fname:
+            plt.savefig(fname)
+        else:
+            plt.show()

keeks/binary_strategies/__init__.py

@@ -0,0 +1,41 @@
+"""
+Binary betting strategies for the keeks package.
+
+This module provides various strategies for binary betting scenarios, including:
+- Kelly Criterion: Optimal bet sizing based on probability and odds
+- Fractional Kelly: A more conservative version of Kelly using a fraction
+- Drawdown-Adjusted Kelly: Kelly variant that accounts for drawdown tolerance
+- Optimal f: Ralph Vince's method for maximizing geometric growth rate
+- Fixed Fraction: Simple strategy that bets a constant percentage
+- CPPI: Constant Proportion Portfolio Insurance for preserving capital
+- Dynamic Bankroll Management: Adaptive allocation based on recent performance
+- Naive Strategy: Simple strategy that bets full amount when expected value is positive
+
+All strategies implement the BaseStrategy interface.
+"""
+
+from keeks.binary_strategies.kelly import (
+    DrawdownAdjustedKelly,
+    FractionalKellyCriterion,
+    KellyCriterion,
+)
+from keeks.binary_strategies.simple import (
+    CPPIStrategy,
+    DynamicBankrollManagement,
+    FixedFractionStrategy,
+    NaiveStrategy,
+    OptimalF,
+)
+
+__author__ = "willmcginnis"
+
+__all__ = [
+    "KellyCriterion",
+    "FractionalKellyCriterion",
+    "DrawdownAdjustedKelly",
+    "OptimalF",
+    "NaiveStrategy",
+    "FixedFractionStrategy",
+    "CPPIStrategy",
+    "DynamicBankrollManagement",
+]

keeks/binary_strategies/base.py

@@ -0,0 +1,84 @@
+import abc
+
+__author__ = "willmcginnis"
+
+
+class BaseStrategy(abc.ABC):
+    """
+    Abstract base class for all binary betting strategies.
+
+    This class defines the interface that all binary betting strategies must implement.
+    Concrete strategy implementations should inherit from this class and implement
+    the evaluate method.
+    """
+
+    def __init__(self, payoff: float, loss: float, transaction_cost: float = 0):
+        """
+        Initialize the strategy.
+
+        Parameters
+        ----------
+        payoff : float
+            The payoff multiplier for winning.
+        loss : float
+            The loss multiplier for losing.
+        transaction_cost : float, optional
+            The transaction cost as a fraction of the bet, by default 0.
+
+        Raises
+        ------
+        ValueError
+            If payoff is not positive, loss is negative, or loss + transaction_cost is not positive.
+        """
+        if payoff <= 0:
+            raise ValueError("Payoff must be greater than 0")
+        if loss < 0:
+            raise ValueError("Loss must be non-negative")
+        if transaction_cost < 0:
+            raise ValueError("Transaction cost must be non-negative")
+        if loss + transaction_cost <= 0:
+            raise ValueError(
+                "Total cost (loss + transaction_cost) must be greater than 0"
+            )
+
+        self.payoff = payoff
+        self.loss = loss
+        self.transaction_cost = transaction_cost
+
+    def get_max_safe_bet(self, current_bankroll: float) -> float:
+        """
+        Calculate the maximum safe bet size based on current bankroll.
+
+        Parameters
+        ----------
+        current_bankroll : float
+            The current bankroll to use for calculations.
+
+        Returns
+        -------
+        float
+            The maximum safe bet size as a proportion of bankroll.
+        """
+        # Calculate maximum bet that won't result in negative bankroll
+        # after accounting for loss multiplier and transaction costs
+        max_bet = current_bankroll / (self.loss + self.transaction_cost)
+        return min(1.0, max_bet / current_bankroll)
+
+    @abc.abstractmethod
+    def evaluate(self, probability: float, current_bankroll: float) -> float:
+        """
+        Evaluate the strategy for a given probability.
+
+        Parameters
+        ----------
+        probability : float
+            The probability of winning.
+        current_bankroll : float
+            The current bankroll to use for calculations.
+
+        Returns
+        -------
+        float
+            The proportion of the bankroll to bet.
+        """
+        pass

keeks/binary_strategies/kelly.py

@@ -0,0 +1,227 @@
+from keeks.binary_strategies.base import BaseStrategy
+
+__author__ = "willmcginnis"
+
+
+class KellyCriterion(BaseStrategy):
+    """
+    Implementation of the Kelly Criterion for binary betting.
+
+    The Kelly Criterion is a mathematical formula that determines the optimal
+    size of a series of bets to maximize long-term growth rate.
+
+    Parameters
+    ----------
+    payoff : float
+        The amount won per unit bet on a successful outcome.
+    loss : float
+        The amount lost per unit bet on an unsuccessful outcome.
+    transaction_cost : float
+        The fixed cost per transaction, regardless of outcome.
+    min_probability : float, default=0.5
+        The minimum probability required to place a bet.
+    """
+
+    def __init__(self, payoff, loss, transaction_cost, min_probability=0.5):
+        """
+        Initialize the Kelly Criterion strategy.
+
+        Parameters
+        ----------
+        payoff : float
+            The amount won per unit bet on a successful outcome.
+        loss : float
+            The amount lost per unit bet on an unsuccessful outcome.
+        transaction_cost : float
+            The fixed cost per transaction, regardless of outcome.
+        min_probability : float, default=0.5
+            The minimum probability required to place a bet.
+        """
+        if not 0 <= min_probability <= 1:
+            raise ValueError("Minimum probability must be between 0 and 1")
+
+        super().__init__(payoff, loss, transaction_cost)
+        self.min_probability = min_probability
+
+    def evaluate(self, probability, current_bankroll):
+        """
+        Calculate the optimal Kelly bet size.
+
+        The Kelly Criterion formula is:
+        f* = (bp - q) / b
+
+        where:
+        f* = fraction of current bankroll to bet
+        b = net odds received on the bet (payoff/loss)
+        p = probability of winning
+        q = probability of losing (1 - p)
+
+        Parameters
+        ----------
+        probability : float
+            The probability of a successful outcome, typically between 0 and 1.
+        current_bankroll : float
+            The current bankroll amount.
+
+        Returns
+        -------
+        float
+            The optimal proportion of the bankroll to bet.
+        """
+        if probability < self.min_probability:
+            return 0.0
+
+        # Calculate net odds
+        self.payoff / self.loss
+
+        # Calculate probability of losing
+        q = 1 - probability
+
+        # Calculate Kelly fraction with transaction costs incorporated
+        # Adjust payoff and loss for transaction costs
+        adjusted_payoff = self.payoff - self.transaction_cost
+        adjusted_loss = self.loss + self.transaction_cost
+
+        # Recalculate net odds with transaction costs
+        if adjusted_payoff <= 0 or adjusted_loss <= 0:
+            return 0.0  # If transaction costs make the bet unprofitable
+
+        adjusted_b = adjusted_payoff / adjusted_loss
+
+        # Calculate Kelly fraction with adjusted odds
+        kelly_fraction = (adjusted_b * probability - q) / adjusted_b
+
+        # Ensure we never bet more than would result in negative bankroll
+        return min(max(0, kelly_fraction), self.get_max_safe_bet(current_bankroll))
+
+
+class FractionalKellyCriterion(BaseStrategy):
+    """
+    Implementation of the Fractional Kelly Criterion for binary betting.
+
+    The Fractional Kelly Criterion applies a fraction to the full Kelly bet size,
+    which can reduce volatility at the expense of long-term growth rate.
+
+    Parameters
+    ----------
+    payoff : float
+        The amount won per unit bet on a successful outcome.
+    loss : float
+        The amount lost per unit bet on an unsuccessful outcome.
+    transaction_cost : float
+        The fixed cost per transaction, regardless of outcome.
+    fraction : float
+        The fraction of the full Kelly bet to use (typically between 0 and 1).
+    """
+
+    def __init__(self, payoff, loss, transaction_cost, fraction):
+        if not 0 <= fraction <= 1:
+            raise ValueError("Fraction must be between 0 and 1")
+
+        super().__init__(payoff, loss, transaction_cost)
+        self.fraction = fraction
+
+    def evaluate(self, probability, current_bankroll):
+        """
+        Calculate the fractional Kelly bet size.
+
+        Parameters
+        ----------
+        probability : float
+            The probability of a successful outcome, typically between 0 and 1.
+        current_bankroll : float
+            The current bankroll amount.
+
+        Returns
+        -------
+        float
+            The optimal proportion of the bankroll to bet, multiplied by the fraction parameter.
+        """
+        kelly = KellyCriterion(self.payoff, self.loss, self.transaction_cost)
+        return self.fraction * kelly.evaluate(probability, current_bankroll)
+
+
+class DrawdownAdjustedKelly(BaseStrategy):
+    """
+    Implementation of the Drawdown-Adjusted Kelly Criterion for binary betting.
+
+    This strategy adjusts the Kelly bet size based on a maximum acceptable drawdown.
+    It provides a more conservative approach by reducing the bet size to minimize
+    the risk of large drawdowns.
+
+    Parameters
+    ----------
+    payoff : float
+        The amount won per unit bet on a successful outcome.
+    loss : float
+        The amount lost per unit bet on an unsuccessful outcome.
+    transaction_cost : float
+        The fixed cost per transaction, regardless of outcome.
+    max_acceptable_drawdown : float
+        The maximum acceptable drawdown as a fraction of the bankroll (0 to 1).
+    """
+
+    def __init__(self, payoff, loss, transaction_cost, max_acceptable_drawdown=0.2):
+        """
+        Initialize the DrawdownAdjustedKelly strategy.
+
+        Parameters
+        ----------
+        payoff : float
+            The amount won per unit bet on a successful outcome.
+        loss : float
+            The amount lost per unit bet on an unsuccessful outcome.
+        transaction_cost : float
+            The fixed cost per transaction, regardless of outcome.
+        max_acceptable_drawdown : float, default=0.2
+            The maximum acceptable drawdown as a fraction of the bankroll.
+
+        Raises
+        ------
+        ValueError
+            If max_acceptable_drawdown is not between 0 and 1 (exclusive).
+        """
+        super().__init__(payoff, loss, transaction_cost)
+
+        if not 0 < max_acceptable_drawdown < 1:
+            raise ValueError(
+                "Maximum acceptable drawdown must be between 0 and 1 (exclusive)"
+            )
+
+        self.max_acceptable_drawdown = max_acceptable_drawdown
+
+    def evaluate(self, probability, current_bankroll):
+        """
+        Calculate the drawdown-adjusted Kelly bet size.
+
+        The adjustment is an approximation based on the relationship between
+        bet size and expected drawdown in repeated betting scenarios.
+
+        Parameters
+        ----------
+        probability : float
+            The probability of a successful outcome, typically between 0 and 1.
+        current_bankroll : float
+            The current bankroll amount.
+
+        Returns
+        -------
+        float
+            The drawdown-adjusted proportion of the bankroll to bet.
+        """
+        # Calculate the standard Kelly bet size
+        kelly = KellyCriterion(self.payoff, self.loss, self.transaction_cost)
+        full_kelly = kelly.evaluate(probability, current_bankroll)
+
+        # Adjust the Kelly fraction based on maximum acceptable drawdown
+        # This is a simplified approximation of the relationship
+        # Various research suggests specific formulas, but a common
+        # conservative approach is to scale Kelly by max drawdown / 0.5
+        # (since full Kelly has an expected drawdown of around 50%)
+        drawdown_factor = min(1.0, self.max_acceptable_drawdown / 0.5)
+
+        # Apply the drawdown adjustment
+        adjusted_kelly = drawdown_factor * full_kelly
+
+        # Ensure we never bet more than would result in negative bankroll
+        return min(adjusted_kelly, self.get_max_safe_bet(current_bankroll))