Agent Bankroll Theory: Optimal Staking for Long-Term Survival

def kelly_fraction(win_prob: float, win_payout: float, kelly_factor: float = 0.25) -> float:
    """
    Compute fractional Kelly stake.

    Args:
        win_prob: probability of winning (0 to 1)
        win_payout: net payout per unit staked (e.g., 1.0 = even money, 2.0 = 2:1)
        kelly_factor: fraction of full Kelly to use (default 1/4 = 0.25)

    Returns:
        Optimal bet as fraction of bankroll (0 to 1).
        Returns 0 if the bet has negative expected value.
    """
    loss_prob = 1.0 - win_prob
    full_kelly = (win_payout * win_prob - loss_prob) / win_payout
    fractional = full_kelly * kelly_factor
    return max(0.0, fractional)  # never bet negative


# Purple Flea casino: coin flip pays 1.96x (2% house edge)
f = kelly_fraction(win_prob=0.50, win_payout=0.96, kelly_factor=0.25)
# Slightly negative EV, so kelly_fraction returns 0 — don't bet!
# An agent MUST have an edge before Kelly applies.

# Trading with a 55% win rate and 1.5:1 reward-to-risk
f = kelly_fraction(win_prob=0.55, win_payout=1.5, kelly_factor=0.25)
# f ~ 0.075 = bet 7.5% of bankroll per trade

import math

def ruin_probability(
    win_prob: float,
    bet_fraction: float,
    num_rounds: int = 1000,
    simulations: int = 10000,
    ruin_threshold: float = 0.10
) -> float:
    """
    Monte Carlo ruin probability estimation.

    Args:
        win_prob: probability of winning each round
        bet_fraction: fraction of current bankroll bet per round
        num_rounds: rounds per simulation
        simulations: number of Monte Carlo runs
        ruin_threshold: bankroll fraction below which agent is "ruined"

    Returns:
        Estimated probability of ruin (0.0 to 1.0)
    """
    import random
    ruin_count = 0
    for _ in range(simulations):
        bankroll = 1.0
        for _ in range(num_rounds):
            bet = bankroll * bet_fraction
            if random.random() < win_prob:
                bankroll += bet
            else:
                bankroll -= bet
            if bankroll <= ruin_threshold:
                ruin_count += 1
                break
    return ruin_count / simulations


# Compare ruin probabilities across bet fractions (55% win rate)
for fraction in [0.01, 0.05, 0.10, 0.25, 0.50]:
    p_ruin = ruin_probability(0.55, fraction, num_rounds=500, simulations=5000)
    print(f"Bet {fraction*100:.0f}% per round: ruin prob = {p_ruin:.3f}")

import logging
from dataclasses import dataclass, field
from typing import Optional, List

log = logging.getLogger("BankrollManager")

@dataclass
class BetResult:
    amount: float
    won: bool
    pnl: float
    bankroll_after: float

@dataclass
class BankrollConfig:
    initial_bankroll: float = 100.0
    kelly_factor: float = 0.25    # 1/4 Kelly default
    max_bet_fraction: float = 0.10  # cap at 10% regardless of Kelly
    min_bet_usdc: float = 1.0
    max_bet_usdc: float = 500.0
    drawdown_step_threshold: float = 0.20  # reduce kelly_factor at 20% DD
    drawdown_halt_threshold: float = 0.50  # halt at 50% DD
    session_loss_limit: float = 0.15       # max 15% loss per session


class BankrollManager:
    """
    Mathematically optimal bankroll management for AI agents.

    Implements fractional Kelly criterion with:
    - Dynamic drawdown protection
    - Session-level loss limits
    - Bet size flooring and capping
    - Full history tracking
    """

    def __init__(self, config: BankrollConfig = None):
        self.cfg = config or BankrollConfig()
        self.bankroll = self.cfg.initial_bankroll
        self.peak_bankroll = self.bankroll
        self.session_start = self.bankroll
        self.history: List[BetResult] = []
        self._halted = False
        self._effective_kelly = self.cfg.kelly_factor

    @property
    def drawdown(self) -> float:
        """Current drawdown from peak (0.0 = at peak, 0.5 = -50%)."""
        if self.peak_bankroll == 0:
            return 1.0
        return 1.0 - (self.bankroll / self.peak_bankroll)

    @property
    def session_loss(self) -> float:
        """Current session loss fraction from session start."""
        if self.session_start == 0:
            return 1.0
        return max(0.0, 1.0 - self.bankroll / self.session_start)

    def kelly_bet(self, win_prob: float, win_payout: float) -> Optional[float]:
        """
        Compute recommended bet size in USDC.
        Returns None if betting is halted or bet size is zero.
        """
        if self._halted:
            log.warning("Bankroll manager halted — drawdown limit reached")
            return None

        # Check session loss limit
        if self.session_loss >= self.cfg.session_loss_limit:
            log.warning(f"Session loss limit reached ({self.session_loss:.1%})")
            return None

        # Dynamic Kelly reduction on drawdown
        if self.drawdown >= self.cfg.drawdown_halt_threshold:
            self._halted = True
            log.error(f"HALT: drawdown {self.drawdown:.1%} exceeds limit")
            return None
        elif self.drawdown >= self.cfg.drawdown_step_threshold:
            effective_kelly = self.cfg.kelly_factor * 0.5
        else:
            effective_kelly = self.cfg.kelly_factor

        # Kelly computation
        loss_prob = 1.0 - win_prob
        full_kelly = (win_payout * win_prob - loss_prob) / win_payout
        fraction = full_kelly * effective_kelly

        if fraction <= 0:
            return None  # negative EV

        # Cap at max_bet_fraction
        fraction = min(fraction, self.cfg.max_bet_fraction)

        bet = self.bankroll * fraction
        bet = max(self.cfg.min_bet_usdc, min(self.cfg.max_bet_usdc, bet))
        return round(bet, 2)

    def record_result(self, amount: float, won: bool, payout: float) -> BetResult:
        """Record the result of a bet and update bankroll state."""
        if won:
            pnl = amount * payout
        else:
            pnl = -amount

        self.bankroll = max(0.0, self.bankroll + pnl)
        self.peak_bankroll = max(self.peak_bankroll, self.bankroll)

        result = BetResult(
            amount=amount, won=won, pnl=pnl,
            bankroll_after=self.bankroll
        )
        self.history.append(result)
        log.info(f"Bet ${amount:.2f} -> {'WIN' if won else 'LOSS'} PnL=${pnl:+.2f} Bankroll=${self.bankroll:.2f} DD={self.drawdown:.1%}")
        return result

    def reset_session(self):
        """Start a new session — resets session loss counter."""
        self.session_start = self.bankroll
        log.info(f"New session started at ${self.session_start:.2f}")

    def summary(self) -> dict:
        """Return bankroll performance summary."""
        if not self.history:
            return {"bets": 0}
        wins = [r for r in self.history if r.won]
        return {
            "bets": len(self.history),
            "win_rate": len(wins) / len(self.history),
            "total_pnl": sum(r.pnl for r in self.history),
            "current_bankroll": self.bankroll,
            "peak_bankroll": self.peak_bankroll,
            "max_drawdown": self.drawdown,
            "halted": self._halted
        }


# Example usage with Purple Flea Casino
import requests

cfg = BankrollConfig(
    initial_bankroll=100.0,
    kelly_factor=0.25,    # quarter Kelly
    max_bet_fraction=0.05, # hard cap at 5%
    session_loss_limit=0.15
)
mgr = BankrollManager(cfg)

# Determine bet for 55% win rate game paying 1.8x
bet_size = mgr.kelly_bet(win_prob=0.55, win_payout=1.8)

if bet_size:
    # Submit to Purple Flea Casino API
    result = requests.post(
        "https://purpleflea.com/api/casino/play",
        json={"game": "coin_flip", "bet": bet_size},
        headers={"Authorization": "Bearer your_api_key"}
    ).json()

    mgr.record_result(bet_size, result["won"], 1.8)
    print(mgr.summary())