teachersbettextbook

The open betting-math textbook — the standard, teachable math behind sports-betting analytics, as a small, dependency-light Python/NumPy library.

It is the open half of Teacher's Bet: the same math the site shows its work with, extracted so you can import it, read it, and check it yourself. Every free lesson at teachersbet.com/learn is built on these functions.

Not betting advice. Every function is a calculation on the inputs you supply — not a prediction, pick, or direction to wager, and no guarantee of any outcome. For informational and educational use. You must be of legal age to gamble in your jurisdiction. Gamble responsibly — 1-800-GAMBLER.

Install

pip install teachersbettextbook

What's inside

Where a calculation has one headline number, the function returns it (teaser_breakeven, required_hit_rate, kalshi_fee). Where the point is the whole derivation, a *_breakdown function returns every intermediate value in one dict.

See FORMULAS.md for every equation, and the free guides at teachersbet.com/learn for the plain-language lessons.

Quick start

import teachersbettextbook as tb

# De-vig a two-sided moneyline into fair probabilities
tb.devig(-150, 130, method="shin")      # -> (p_a, p_b), summing to 1

# The book's margin (vig) baked into that line
tb.overround(-150, 130)                 # -> ~0.03

# Fractional Kelly stake for a 55% edge at even money (half-Kelly is the default)
tb.fractional_kelly(p=0.55, b=1.0)       # -> 0.05  (half of the full 0.10)

# Is there an arb across these books? How do you split the stake?
tb.find_arbitrage([
    {"book": "A", "ml_a": 110, "ml_b": -105},
    {"book": "B", "ml_a": -102, "ml_b": 115},
], total_stake=1000)                     # -> best prices, is_arb, stakes, return

# Kalshi: what a 100-contract taker fill at 50c really costs
tb.kalshi_fee(100, 0.50)                 # -> 1.75  (dollars; ceil-to-cent on the total)
tb.kalshi_breakeven(0.50)                # -> 0.5175  (price + fee, the true break-even)
tb.kalshi_fee_breakdown(100, 0.50)       # -> the whole worked cost, incl. round trip vs. hold

# One price, written every way, and what $100 does at it
tb.convert_price("10/11", "fractional")  # -> -110 American, 1.909 decimal, 52.38%, 52.4c
tb.payout(100, -110, other=-105)         # -> profit, total return, and the vig-free payout

# Hedge a $100 bet taken at +150, now that the other side is -130
tb.hedge_stake(100, 150, -130)           # -> 141.30  (S·d1/d2: the TOTAL return, not the profit)

# A middle: how often does the window have to land to break even?
tb.required_hit_rate(-110, -110)         # -> 0.0476  (sigma - 1, the overround on the pair)

# What a two-team six-point tease needs from its points
tb.teaser_breakeven(-120, 2)             # -> 0.7385 per leg
tb.points_needed(-120, 2, -110)          # -> 0.2147 probability per leg

# Does 55 of 100 at -110 prove anything yet? (No.)
tb.breakeven_win_rate(-110)              # -> 0.5238
tb.breakeven_breakdown(-110, bets=100, wins=55)   # -> z = 0.52, p = 0.60, 45.2% to 64.4%

Worked examples

Runnable, step-by-step walkthroughs live in examples/ — one per topic, each printing the full calculation with labelled intermediate values:

python examples/devig_example.py       # strip the vig from a moneyline three ways
python examples/odds_example.py        # one price in five notations, and what it pays
python examples/kelly_example.py       # f*, the growth curve, half-Kelly, joint sizing
python examples/arb_example.py         # detect a two-book arb and split the stake
python examples/hedge_example.py       # size a hedge, price the certainty, read a middle
python examples/multileg_example.py    # teaser points and round-robin tickets
python examples/breakeven_example.py   # the rate a price needs, and what a record proves
python examples/simulate_example.py    # Monte Carlo a season of fractional-Kelly bets
python examples/kalshi_example.py      # what a Kalshi fill costs, and why holding is cheaper

Tests

Every module has a comprehensive suite (known values, edge cases, and mathematical invariants) under tests/:

pip install teachersbettextbook[test]
pytest        # 230+ tests

Scope

This package is math only. It contains no web app, no odds-data feeds, no account or billing code, and none of the hosted service's proprietary sharp-consensus anchor detection. It reads and runs on its own, offline.

License

MIT. Copyright (c) 2026 Alex Thornton.