bet-hedge-calculator 0.1.1
CLI & library to compute sports bet hedging scenarios — guaranteed profit regardless of outcome.
License: MIT
Requires Python: >=3.10
Keywords: betting, hedging, sports, odds, calculator, finance

# bet-hedge-calculator

A CLI tool and Python library for computing sports bet hedging scenarios.

Given a bet already placed on **Team A**, it shows you exactly what odds and stake you need on **Team B** to guarantee a fixed profit — regardless of which team wins.

---

## Installation

```bash
pip install bet-hedge-calculator
```

---

## CLI Usage

After installation a `bet-hedge-calc` command is available globally.

**Interactive mode** (prompts for input):
```bash
bet-hedge-calc
```

**Direct mode** (pass values as flags):
```bash
bet-hedge-calc --odds-a 2.50 --stake-a 100
```

**Custom ROI range and step**:
```bash
bet-hedge-calc --odds-a 3.0 --stake-a 200 --roi-min -10 --roi-max 100 --roi-step 2.5
```

**All options**:
```
--odds-a    Decimal odds of Team A (e.g. 2.50)
--stake-a   Your stake on Team A (e.g. 100)
--roi-min   Minimum target ROI % (default: -20)
--roi-max   Maximum target ROI % (default: 200)
--roi-step  ROI step size in % (default: 5)
--currency  Currency symbol (default: £)
```

### Example output

```
═══ Bet Hedging Calculator ═══

╭─────────────────────────────────────────────────────────────────────────────────────╮
│         Hedging Calculator  —  Team A odds: 2.5  |  Stake on A: £100.00            │
├───────────────┬─────────────────┬───────────────┬─────────────────┬───────────────┤
│    Target ROI │ Required Odds B │  Stake on B   │ Total Invested  │  Guaranteed   │
│               │                 │     (£)       │      (£)        │   Profit (£)  │
├───────────────┼─────────────────┼───────────────┼─────────────────┼───────────────┤
│        -20.0% │         1.1765  │      £212.50  │       £312.50   │      -£62.50  │
│        -15.0% │         1.2195  │      £205.00  │       £305.00   │      -£45.75  │
│        -10.0% │         1.2658  │      £197.50  │       £297.50   │      -£29.75  │
│         -5.0% │         1.3158  │      £190.00  │       £290.00   │      -£14.50  │
│          0.0% │         1.6667  │      £150.00  │       £250.00   │        £0.00  │
│         +5.0% │         1.7500  │      £142.86  │       £242.86   │       £12.14  │
│        +10.0% │         1.8333  │      £136.36  │       £236.36   │       £23.64  │
│        +20.0% │         2.0000  │      £125.00  │       £225.00   │       £45.00  │
│        +50.0% │         2.5000  │      £100.00  │       £200.00   │      £100.00  │
│       +100.0% │              —  │            —  │             —   │            —  │
│               │                 Not achievable                                     │
╰─────────────────────────────────────────────────────────────────────────────────────╯
```

---

## Python API

Import the library directly to get raw data or render the table programmatically.

### Get hedging data

```python
from bet_hedge_calculator import calculate_scenarios

scenarios = calculate_scenarios(odds_a=2.5, stake_a=100)

for s in scenarios:
    if s.valid:
        print(f"ROI {s.roi_pct:+.1f}%  →  odds B: {s.odds_b:.4f}  |  stake B: £{s.stake_b:.2f}  |  profit: £{s.guaranteed_profit:.2f}")
```

Output:
```
ROI -20.0%  →  odds B: 1.1765  |  stake B: £212.50  |  profit: £-62.50
ROI -15.0%  →  odds B: 1.2195  |  stake B: £205.00  |  profit: £-45.75
...
ROI +10.0%  →  odds B: 1.8333  |  stake B: £136.36  |  profit: £23.64
```

### Render the rich table

```python
from bet_hedge_calculator import calculate_scenarios, render_table

scenarios = calculate_scenarios(odds_a=2.5, stake_a=100)
render_table(scenarios, odds_a=2.5, stake_a=100, currency="$")
```

### Single scenario

```python
from bet_hedge_calculator import calculate_scenario

s = calculate_scenario(odds_a=3.0, stake_a=200, roi=0.10)  # 10% ROI
if s.valid:
    print(f"Stake £{s.stake_b:.2f} on Team B at odds {s.odds_b:.4f}")
    print(f"Guaranteed profit: £{s.guaranteed_profit:.2f}")
```

### Custom ROI range

```python
from bet_hedge_calculator import calculate_scenarios

scenarios = calculate_scenarios(
    odds_a=2.5,
    stake_a=100,
    roi_min_pct=0.0,
    roi_max_pct=50.0,
    roi_step_pct=2.5,
)
```

### HedgeScenario dataclass

Each scenario is a `HedgeScenario` with these fields:

| Field | Type | Description |
|---|---|---|
| `roi_pct` | `float` | Target ROI in percent (e.g. `10.0`) |
| `valid` | `bool` | `False` when the scenario is mathematically unachievable |
| `odds_b` | `float \| None` | Required decimal odds for Team B |
| `stake_b` | `float \| None` | Required stake on Team B |
| `total_invested` | `float \| None` | Combined stake on A + B |
| `guaranteed_profit` | `float \| None` | Profit regardless of outcome |

---

## The maths

For a bet already placed on **Team A** (decimal odds `O_A`, stake `S_A`), we want a guaranteed profit `P` regardless of which team wins:

```
If A wins:  S_A × O_A − S_A − S_B = P
If B wins:  S_B × O_B − S_B − S_A = P
```

Both equations give `S_A × O_A = S_B × O_B`, so:

```
O_B = O_A × (1 + ROI) / (O_A − 1 − ROI)
S_B = S_A × O_A / O_B
```

This is valid only when `ROI < O_A − 1`. Rows outside this range are marked **Not achievable**.

---

## Development

```bash
git clone https://github.com/your-username/bet-hedge-calculator
cd bet-hedge-calculator
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/ -v
```

---

## License

MIT