Update to BirdieAPI

{
  "description": "Converts golf outright prices to implied probability, measures the overround of a many-runner winner market, and devigs it with the proportional, power and Shin methods. Use when the user asks what a price means as a probability, how much margin a golf outright carries, how to remove the vig from a field of 100+ golfers, what the true win chance of a favourite or longshot is, or how a price should be read. Do not use for finding the best book or movement -- see odds-explorer. Do not use for two-way or each-way markets; each-way terms are not in the data.",
  "included_files": [],
  "name": "odds-analysis",
  "skill_md_contents": "---\nname: odds-analysis\ndescription: \"Converts golf outright prices to implied probability, measures the overround of a many-runner winner market, and devigs it with the proportional, power and Shin methods. Use when the user asks what a price means as a probability, how much margin a golf outright carries, how to remove the vig from a field of 100+ golfers, what the true win chance of a favourite or longshot is, or how a price should be read. Do not use for finding the best book or movement -- see odds-explorer. Do not use for two-way or each-way markets; each-way terms are not in the data.\"\nmetadata:\n  version: 1.0.0\n  author: BirdieAPI\n---\n\n# Odds Analysis\n\n> **Default data tool:** BirdieAPI (`birdieapi-tool`).\n> `get_winner_odds` (5 credits) supplies prices. The method below is arithmetic you run yourself.\n> With the user's own prices, no credits are used.\n\nYou are an expert in turning prices into probabilities. Golf outrights are the hard case: one winner among about 90 to 156 runners, margins that tend to sit in the longshots, and a sum of implied probabilities far above 1. Do this carefully or every downstream edge is wrong.\n\n## When to Use\n\n- \"What is +400 as a probability?\"\n- \"How much margin is in this market?\"\n- \"What is Scheffler's true win probability once I take the vig out?\"\n- Choosing between proportional, power and Shin devigging for a big field\n- Checking whether a user's model probability for a golfer is even in range\n\n## When NOT to Use\n\n- Finding the best book or reading movement -- see `odds-explorer`\n- Two-way markets (matchups, round bets) and each-way terms -- not in the data; the same formulas apply to the user's own two-way lines with a different normalisation\n\n## Commands Available\n\n| Command | What It Does | Credits |\n|---------|-------------|---------|\n| `get_winner_odds` | Winner prices by golfer and book with raw implied probability | 5 |\n\nEverything else here is calculation.\n\n## Commands That Do NOT Exist\n\n| Not Available | Use Instead |\n|--------------|-------------|\n| `get_devigged_odds`, `get_true_probability` | Compute from `get_winner_odds` with the methods below |\n| `get_each_way_terms` | Not available; do not assume terms |\n| `get_odds` for non-majors | Not available |\n\n## Step 1: Price to implied probability\n\nAmerican price `a`:\n- positive: `p = 100 / (a + 100)`. +400 gives 0.200. +1000 gives 0.0909.\n- negative: `p = |a| / (|a| + 100)`. -150 gives 0.600.\n\n`get_winner_odds` already returns this as `implied_prob`. It is the raw probability and it includes the book's margin. It is not a belief.\n\nDecimal odds `d = a/100 + 1` for positive `a`. Profit per unit stake `b = d - 1`.\n\n## Step 2: Overround of the whole field\n\nSum the raw implied probabilities of every golfer at one book at one snapshot:\n\n```\noverround = sum(p_i) - 1\n```\n\nReal example: 2024 Masters, DraftKings latest pregame price, all 115 golfers priced.\n\n```\nget_winner_odds {\"tournament_id\": \"401580344\", \"limit\": 200, \"bookmaker\": \"draftkings\"}\n```\n\n```\ngolfers priced: 115\nsum of latest implied probabilities: 1.642   (overround 64%)\nsum of opening implied probabilities: 1.632\ntop of the board (raw): Scheffler 20.0% (+400), McIlroy 9.1% (+1000), Rahm 7.7% (+1200),\n                        Koepka 5.3% (+1800), Schauffele 4.8% (+2000), Spieth 4.3% (+2200)\ntail: Olazabal +500000 (0.02%)\n```\n\nA 64% overround is not a 64% hold on every bet. It is the sum of many small margins, and most of it sits in the longshots. A book shading a +20000 to +15000 adds little in absolute probability but a hundred such prices add up.\n\nDo not report a \"vig of 164%\". Say: \"the 115 prices sum to 1.64, so staking every golfer in proportion to his implied probability would return about 61 cents per dollar\" (1/1.642 = 0.609). That is the average across the board, and the margin is far smaller on the favourite than in the tail.\n\n## Step 3: Devig\n\nThree methods. For an outright with a long tail, only the second and third are defensible.\n\n**Proportional (multiplicative):** `q_i = p_i / sum(p)`. Divides every golfer by 1.642. It cuts the favourite and the longshot by the same percentage, so it understates favourites and overstates longshots when the margin is concentrated in the tail.\n\n**Power:** find `k > 1` such that `sum(p_i^k) = 1`, then `q_i = p_i^k`. Because `p < 1`, raising to a power shrinks small probabilities more, which matches margin concentrated in longshots. Solve `k` by bisection.\n\n**Shin:** solves for a proportion `z` of insider money and sets\n`q_i = (sqrt(z^2 + 4(1 - z) p_i^2 / S) - z) / (2(1 - z))` with `S = sum(p)`, choosing `z` so `sum(q_i) = 1`. It is the usual choice when the field is large and favourite-longshot bias is visible.\n\nReal comparison for the same market (computed from the 115 DraftKings prices):\n\n| Golfer | Raw | Proportional | Power (k = 1.142) | Shin (z = 0.0075) |\n|--------|-----|--------------|-------------------|-------------------|\n| Scheffler | 20.0% | 12.2% | 15.9% | 15.3% |\n| McIlroy | 9.1% | 5.5% | 6.5% | 6.8% |\n| Rahm | 7.7% | 4.7% | 5.3% | 5.7% |\n| Koepka | 5.3% | 3.2% | 3.5% | 3.8% |\n| Schauffele | 4.8% | 2.9% | 3.1% | 3.4% |\n| Spieth | 4.3% | 2.6% | 2.8% | 3.0% |\n\nThe range for Scheffler across methods is 12.2% to 15.9%. That spread is larger than most claimed edges. State it. A model that says 16% is \"an edge\" under proportional and \"no edge\" under power.\n\n```python\nimport numpy as np\n\ndef devig_power(p, tol=1e-12):\n    lo, hi = 1.0, 10.0\n    for _ in range(200):\n        k = (lo + hi) / 2\n        if np.sum(p ** k) > 1: lo = k\n        else: hi = k\n    return p ** k, k\n\ndef devig_shin(p):\n    S = p.sum()\n    def total(z): return np.sum((np.sqrt(z*z + 4*(1-z)*p*p/S) - z) / (2*(1-z)))\n    lo, hi = 0.0, 0.999\n    for _ in range(200):\n        z = (lo + hi) / 2\n        if total(z) > 1: lo = z\n        else: hi = z\n    q = (np.sqrt(z*z + 4*(1-z)*p*p/S) - z) / (2*(1-z))\n    return q, z\n```\n\n## Step 4: Use more than one book\n\nA single book's margin is a property of that book. Devig each book separately, then average the devigged probabilities (not the American prices). A sharp book such as Pinnacle, when present, usually carries a smaller margin; check `books[]` rather than assuming. Report the spread of devigged values across books as the market's uncertainty.\n\n## Step 5: Sanity checks before using the number\n\n- Devigged probabilities must sum to 1 (to within 1e-6).\n- Never report a probability below the smallest meaningful value for the field. A +500000 price is not a 0.02% belief; the tail is noise. Group golfers beyond rank 40 as \"the field\".\n- A major winner prior: with 89 to 156 starters in recent majors the average golfer has roughly a 1% chance or less (1 in 89 to 1 in 156). A model giving 3% to a rank-60 player needs a reason.\n\n## Credit Usage\n\n| Operation | Credits | Notes |\n|-----------|---------|-------|\n| Price one major at one book | 5 | `limit` 200 and `bookmaker` |\n| Compare all books for the top 20 | 5 | default call |\n| Devig math | 0 | local |\n\n## Anti-patterns\n\n| What the Model Might Do | Why It's Wrong | Do This Instead |\n|---------------------|---------------|-----------------|\n| Treat `implied_prob` as the true probability | It includes margin | Devig the full field |\n| Proportional-devig a 115-runner market and call it true | Over-credits longshots, under-credits favourites | Show power or Shin beside it |\n| Devig only the top 20 golfers | The tail's mass is missing, so the sum is below the real total | Devig the whole priced field |\n| Average American odds across books | Not linear | Average devigged probabilities |\n| Quote one devigged number to two decimals | False precision | Quote a range across methods and books |\n| Assume each-way terms | Not in the data | Ask the user |\n\n## Output Format\n\n```\n2024 Masters, DraftKings latest pregame (115 golfers)\nRaw implied sum: 1.642\nScottie Scheffler: +400 = 20.0% raw\n  devigged: 12.2% proportional / 15.9% power / 15.3% Shin\n  working range: 15% to 16% (power and Shin agree; proportional likely too low)\n```\n\n## What to Do Next\n\n| What You Found | Next Action | Skill |\n|----------------|-------------|-------|\n| Need the prices first | Pull and compare books | `odds-explorer` |\n| Model probabilities look off | Check calibration | `probability-calibration` |\n"
}