feat(position_sizing): add Kelly criterion estimator

Introduce estimate_kelly() with KellyResult for unified position
sizing; cap max_position_pct at 10% per risk policy.

Co-Authored-By: Claude <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 3 people

src/quant_platform_kit/position_sizing.py

@@ -0,0 +1,58 @@
+"""Kelly criterion position sizing utilities."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+_DEFAULT_MAX_POSITION_PCT = 0.10
+
+
+@dataclass(frozen=True)
+class KellyResult:
+    win_rate: float
+    avg_win: float
+    avg_loss: float
+    kelly_fraction: float
+    half_kelly: float
+    max_position_pct: float
+
+
+def estimate_kelly(returns: list[float]) -> KellyResult:
+    """Estimate Kelly fraction from a list of per-trade returns."""
+    if not returns:
+        return KellyResult(
+            win_rate=0.0,
+            avg_win=0.0,
+            avg_loss=0.0,
+            kelly_fraction=0.0,
+            half_kelly=0.0,
+            max_position_pct=0.0,
+        )
+
+    wins = [value for value in returns if value > 0]
+    losses = [value for value in returns if value < 0]
+
+    win_rate = len(wins) / len(returns)
+    avg_win = sum(wins) / len(wins) if wins else 0.0
+    avg_loss = abs(sum(losses) / len(losses)) if losses else 0.0
+
+    if avg_win <= 0.0:
+        kelly_fraction = 0.0
+    elif avg_loss <= 0.0:
+        kelly_fraction = min(win_rate, 1.0)
+    else:
+        payoff_ratio = avg_win / avg_loss
+        kelly_fraction = (win_rate * payoff_ratio - (1.0 - win_rate)) / payoff_ratio
+        kelly_fraction = max(0.0, min(kelly_fraction, 1.0))
+
+    half_kelly = kelly_fraction / 2.0
+    max_position_pct = min(half_kelly, _DEFAULT_MAX_POSITION_PCT)
+
+    return KellyResult(
+        win_rate=win_rate,
+        avg_win=avg_win,
+        avg_loss=avg_loss,
+        kelly_fraction=kelly_fraction,
+        half_kelly=half_kelly,
+        max_position_pct=max_position_pct,
+    )

tests/test_position_sizing.py

@@ -0,0 +1,104 @@
+"""Tests for quant_platform_kit.position_sizing."""
+
+from __future__ import annotations
+
+import unittest
+
+from quant_platform_kit.position_sizing import KellyResult, estimate_kelly
+
+
+class PositionSizingTests(unittest.TestCase):
+    def test_all_wins(self) -> None:
+        result = estimate_kelly([0.10, 0.05, 0.08])
+
+        self.assertEqual(result.win_rate, 1.0)
+        self.assertAlmostEqual(result.avg_win, (0.10 + 0.05 + 0.08) / 3)
+        self.assertEqual(result.avg_loss, 0.0)
+        self.assertEqual(result.kelly_fraction, 1.0)
+        self.assertEqual(result.half_kelly, 0.5)
+        self.assertEqual(result.max_position_pct, 0.10)
+
+    def test_all_losses(self) -> None:
+        result = estimate_kelly([-0.10, -0.05, -0.08])
+
+        self.assertEqual(result.win_rate, 0.0)
+        self.assertEqual(result.avg_win, 0.0)
+        self.assertAlmostEqual(result.avg_loss, (0.10 + 0.05 + 0.08) / 3)
+        self.assertEqual(result.kelly_fraction, 0.0)
+        self.assertEqual(result.half_kelly, 0.0)
+        self.assertEqual(result.max_position_pct, 0.0)
+
+    def test_break_even(self) -> None:
+        result = estimate_kelly([0.10, -0.10])
+
+        self.assertEqual(result.win_rate, 0.5)
+        self.assertAlmostEqual(result.avg_win, 0.10)
+        self.assertAlmostEqual(result.avg_loss, 0.10)
+        self.assertAlmostEqual(result.kelly_fraction, 0.0)
+        self.assertAlmostEqual(result.half_kelly, 0.0)
+        self.assertAlmostEqual(result.max_position_pct, 0.0)
+
+    def test_positive_edge(self) -> None:
+        result = estimate_kelly([0.20, 0.20, -0.10])
+
+        self.assertAlmostEqual(result.win_rate, 2 / 3)
+        self.assertAlmostEqual(result.avg_win, 0.20)
+        self.assertAlmostEqual(result.avg_loss, 0.10)
+        self.assertAlmostEqual(result.kelly_fraction, 0.5)
+        self.assertAlmostEqual(result.half_kelly, 0.25)
+        self.assertAlmostEqual(result.max_position_pct, 0.10)
+
+    def test_empty_returns(self) -> None:
+        result = estimate_kelly([])
+
+        self.assertEqual(
+            result,
+            KellyResult(
+                win_rate=0.0,
+                avg_win=0.0,
+                avg_loss=0.0,
+                kelly_fraction=0.0,
+                half_kelly=0.0,
+                max_position_pct=0.0,
+            ),
+        )
+
+    def test_zero_returns_are_neutral(self) -> None:
+        result = estimate_kelly([0.0, 0.0])
+
+        self.assertEqual(result.win_rate, 0.0)
+        self.assertEqual(result.avg_win, 0.0)
+        self.assertEqual(result.avg_loss, 0.0)
+        self.assertEqual(result.kelly_fraction, 0.0)
+
+    def test_single_win(self) -> None:
+        result = estimate_kelly([0.05])
+
+        self.assertEqual(result.win_rate, 1.0)
+        self.assertEqual(result.kelly_fraction, 1.0)
+        self.assertEqual(result.max_position_pct, 0.10)
+
+    def test_single_loss(self) -> None:
+        result = estimate_kelly([-0.05])
+
+        self.assertEqual(result.win_rate, 0.0)
+        self.assertEqual(result.kelly_fraction, 0.0)
+
+    def test_half_kelly_below_cap(self) -> None:
+        result = estimate_kelly([0.04, 0.04, -0.02])
+
+        self.assertAlmostEqual(result.kelly_fraction, 0.5)
+        self.assertAlmostEqual(result.half_kelly, 0.25)
+        self.assertAlmostEqual(result.max_position_pct, 0.10)
+
+    def test_negative_edge_clamped_to_zero(self) -> None:
+        result = estimate_kelly([0.05, -0.20, -0.20])
+
+        self.assertGreater(result.avg_loss, result.avg_win)
+        self.assertEqual(result.kelly_fraction, 0.0)
+        self.assertEqual(result.half_kelly, 0.0)
+        self.assertEqual(result.max_position_pct, 0.0)
+
+
+if __name__ == "__main__":
+    unittest.main()