Engineering deep-dive

The engineering behind Toots

A Discord bartender that answers questions, runs a play-money sportsbook, calls live games, remembers its regulars, and ships its own code. This is how the hard parts actually work.

A few of them: it answers freeform questions under a grounding classifier that won't let it invent a number; it calls live matches in a bartender's voice off real box scores and odds; it remembers its regulars and does callbacks weeks later; and — the one that still surprises people — you can ask it for a feature in chat and it files its own issue, writes the pull request, runs the tests, and ships it.

Breadth is easy to claim. So here is one surface end to end — the one with the least room to hand-wave, because it moves money.

The Bookie — a worked example

A play-money sportsbook inside the bot. It settles real games off live data — and never pays the wrong team.

Bet coins on who wins a live or upcoming game. The bot freezes the line, watches the game end, and pays out in front of the whole room. It looks like a toy. The hard part hides inside "watches the game end and settles correctly": there is no single source of truth for a sports result, and the dropdown you bet from has a three-second deadline.

The hard problems, in one breath:

• 🧩 a game has no stable ID across providers → so we mint one
• 💸 settle by team name, never position → never pay the wrong team
• ⏱️ a 3-second autocomplete over a 5-second fetch → never block
• 🛏️ three feeds, each behind a breaker → never go dark

What it feels like

How it's wired

1 · A game has no stable ID

Three feeds describe the same match differently — flipped home/away, different spellings (BiH vs Bosnia & Herzegovina), even different ideas of whether it is still live. So we don't trust any provider's ID. We mint our own: sport + the two team names, accent-folded, order-independent, alias-collapsed.

def match_key_parts(sport, home, away, title=""):
    # sorted() -> order-independent (a home/away flip can't split it)
    # canonical_team -> folds "BiH" and "Bosnia & Herzegovina" onto one name
    teams = "@".join(sorted(t for t in (_canonical_team(home), _canonical_team(away)) if t))
    return f"{_norm(sport)}:{teams}" if teams else f"{_norm(sport)}:{_norm(title)}"

2 · Settle the money, never wrong

A bet stores the team it backed, not a side. Settlement matches by name — so a provider flipping orientation can't pay the wrong team — and if a name can't be reconciled, the bet refunds. The house eats ambiguity; a player never loses a stake to a spelling gap.

def bookie_bet_outcome(side, side_label, winner, home, away, stake, decimal_odds):
    if winner is None:                                   # no result yet
        return "void", stake                             #   -> refund the stake
    if winner == "draw":
        return ("won", round(stake * decimal_odds)) if side == "draw" else ("lost", 0)
    if side == "draw":
        return "lost", 0
    sl = _canonical_team(side_label)
    if sl and sl == _canonical_team(winner):
        return "won", round(stake * decimal_odds)        # backed the winner
    if sl and sl in (_canonical_team(home), _canonical_team(away)):
        return "lost", 0                                 # backed the loser
    return "void", stake                                 # can't reconcile a name -> refund, never wrongly lose

Two settlers, one payout. A five-minute settle loop and the live commentator can both reach a finished game at the same moment. The fix is one transaction that touches only the still-open rows, FOR UPDATE: whoever gets there second finds nothing to do. Each bet pays exactly once.

async def settle_bookie_game(game_key, winner):
    async with pool.acquire() as conn, conn.transaction():
        # one transaction: lock the market AND settle every open bet on it
        await conn.execute("INSERT INTO locked_games (game_key) VALUES ($1) "
                           "ON CONFLICT DO NOTHING", game_key)
        rows = await conn.fetch(
            "SELECT * FROM bets WHERE game_key=$1 AND status='open' FOR UPDATE", game_key)
        for r in rows:                                   # the loser of the race finds zero rows here
            status, payout = bookie_bet_outcome(...)     # the pure decision above
            await conn.execute("UPDATE bets SET status=$2, payout=$3 WHERE id=$1", r.id, status, payout)
            if payout:
                await conn.execute("UPDATE balances SET balance = balance + $2 "
                                   "WHERE user_id=$1", r.user_id, payout)

3 · The dropdown can't wait

Discord kills a slash interaction after about three seconds. A cold odds fan-out across the leagues is about five. So the picker is never allowed to block on a live fetch — it serves a warm cache and refreshes behind the scenes.

4 · Three feeds, never dark

Each outbound feed sits behind its own circuit breaker — a sustained failure trips it and stops the hammering instead of stalling every request. One feed is a dual backstop: it can fill the betting slate and settle games, and it's budget-guarded so a metered key can never be drained.

The money always conserves

Placement is one transaction — ensure the account exists, apply the daily top-up, check funds, debit, insert the bet — so a balance can't go negative and a double-spend can't slip through. And every balance reduces to one invariant: start − open stakes + settled payouts. If that ever stops holding, coins were conjured from nothing. It is the single check that proves the whole ledger.

Odds → payout

A sportsbook line and a prediction-market price reduce to the same decimal multiplier, so they compare and pay out on one scale — and the multiplier is frozen at the moment you place the bet, so a later line move never changes what a settled bet pays.

The payoff: your bets in the live play-by-play

The bot doesn't just take bets — it calls the games, live, in a sharp bartender voice, and folds the sportsbook into the broadcast on the bookend beats:

It settles the game with that same idempotent transaction, then hands the result to the commentary as grounded context (names and numbers only, never invented). It's the moment the feature stops feeling like a slash command and starts feeling like a sportsbook with a live announcer who knows your name.

This document is self-contained — every diagram and code sample is embedded, nothing links out. The code lives in a private repository; the snippets above are lightly trimmed to the teaching essence.