Metadata-Version: 2.4
Name: kelzer
Version: 1.0.0
Summary: Stupidly fast Kelly Criterion calculator, in C++
Author-email: Odin Glynn-Martin <odin@odinglynn.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/odinglynn/kelzer
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Kelzer

> Based on: Kelly, J. L., Jr. (1956). "A New Interpretation of Information Rate."
> *Bell System Technical Journal*, 35(4), 917–926.
> [doi:10.1002/j.1538-7305.1956.tb03809.x](https://doi.org/10.1002/j.1538-7305.1956.tb03809.x)

A stupidly fast, native C++ Python extension implementing the Kelly Criterion for optimal bet (but lets call them 'investments' instead) sizing.

## Install

```bash
pip install kelzer
```

## Usage

```python
import kelzer
```

### `kelzer.fraction(win_prob, decimal_odds, multiplier=1.0, decimals=4)`

Returns the optimal fraction of bankroll to wager.

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `win_prob` | float | yes | — | Probability of winning, in (0, 1) |
| `decimal_odds` | float | yes | — | Decimal odds, must be > 1 |
| `multiplier` | float | no | 1.0 | Fraction of Kelly to apply, in (0, 1] |
| `decimals` | int | no | 4 | Decimal places to round result to (0–15) |

### Examples

```python
import kelzer

# Full Kelly — 60% chance at 2.0 odds
kelzer.fraction(0.6, 2.0)
# 0.2

# Quarter Kelly
kelzer.fraction(0.6, 2.0, multiplier=0.25)
# 0.05

# Half Kelly, 6 decimal places
kelzer.fraction(0.55, 1.9, multiplier=0.5, decimals=6)
# 0.055556

# Negative edge — don't bet
kelzer.fraction(0.3, 2.0)
# -0.4
```

### Error handling

```python
kelzer.fraction(0.0, 2.0)    # ValueError: win_prob must be in (0, 1)
kelzer.fraction(0.6, 1.0)    # ValueError: decimal_odds must be > 1
kelzer.fraction(0.6, 2.0, multiplier=0.0)  # ValueError: multiplier must be in (0, 1]
```

## The formula

```
f* = (b·p − q) / b
```

Where `b = decimal_odds − 1`, `p = win_prob`, `q = 1 − p`. The result is then scaled by `multiplier`.

## License

Apache 2.0
