feat: Kelly criterion stake sizing (domain + MyBets helper)

- Add KellyCalculator (Domain/Betting): pure fractional-Kelly stake from win
  probability, decimal odds, bankroll, and fraction (default quarter-Kelly).
  Returns 0 on non-positive edge; truncates the suggestion down to 2 decimals
  so it never exceeds the computed figure. 19 unit tests.
- MyBets: add a page-local stake helper (bankroll + win-probability inputs) that
  suggests a quarter-Kelly stake from the form's rate, with an Apply button and a
  no-edge message. Win probability is user-supplied, not derived from a signal.
- Localization (en+ru) for the Kelly helper and the export-hub keys (shared resx).
This commit is contained in:
2026-05-28 22:46:33 +03:00
parent 250a93e718
commit 0e3c4b8d47
5 changed files with 309 additions and 0 deletions
@@ -0,0 +1,82 @@
namespace Marathon.Domain.Betting;
/// <summary>
/// Pure fractional-Kelly stake sizing for a single back bet at decimal odds.
/// </summary>
/// <remarks>
/// <para>
/// The Kelly criterion maximises the long-run growth rate of a bankroll by staking
/// a fraction of it proportional to the edge. For decimal odds <c>o</c> and an
/// estimated win probability <c>p</c>, the full-Kelly fraction of bankroll is:
/// </para>
/// <code>f* = (p·o 1) / (o 1)</code>
/// <para>
/// When <c>f*</c> is zero or negative there is no positive expected value, and the
/// suggested stake is <c>0</c> — the calculator never recommends betting into a
/// negative-EV price. Most disciplined bettors stake a <i>fraction</i> of full
/// Kelly (e.g. quarter-Kelly, <c>fraction = 0.25</c>) to cut variance and blunt the
/// impact of probability-estimation error; full Kelly is famously over-aggressive
/// once <c>p</c> is even slightly wrong.
/// </para>
/// <para>
/// The win probability is an input the bettor supplies — it is intentionally NOT
/// derived from an anomaly score here, so the calculator stays a pure, reusable
/// money-management primitive independent of any signal source.
/// </para>
/// </remarks>
public static class KellyCalculator
{
/// <summary>Default Kelly fraction: quarter-Kelly — the conventional variance-safe choice.</summary>
public const decimal DefaultFraction = 0.25m;
/// <summary>
/// Full-Kelly fraction of bankroll <c>(p·o 1)/(o 1)</c>. May be negative or
/// zero, signalling no positive edge. Exposed for callers that want the raw
/// figure (e.g. to display the edge) rather than a clamped stake.
/// </summary>
/// <param name="winProbability">Estimated win probability in the closed interval [0, 1].</param>
/// <param name="decimalOdds">Decimal odds, strictly greater than 1.0.</param>
public static decimal FullKellyFraction(decimal winProbability, decimal decimalOdds)
{
if (winProbability is < 0m or > 1m)
throw new ArgumentOutOfRangeException(nameof(winProbability), winProbability, "Must be in [0, 1].");
if (decimalOdds <= 1m)
throw new ArgumentOutOfRangeException(nameof(decimalOdds), decimalOdds, "Decimal odds must be greater than 1.0.");
return (winProbability * decimalOdds - 1m) / (decimalOdds - 1m);
}
/// <summary>
/// Suggested stake using fractional Kelly, rounded down to two decimals so the
/// suggestion is never larger than the theoretical figure. Returns <c>0</c> when
/// there is no positive edge.
/// </summary>
/// <param name="winProbability">Estimated win probability in the open interval (0, 1).</param>
/// <param name="decimalOdds">Decimal odds, strictly greater than 1.0.</param>
/// <param name="bankroll">Total bankroll; must be non-negative.</param>
/// <param name="fraction">Kelly fraction in (0, 1]; defaults to <see cref="DefaultFraction"/>.</param>
public static decimal SuggestStake(
decimal winProbability,
decimal decimalOdds,
decimal bankroll,
decimal fraction = DefaultFraction)
{
if (winProbability is <= 0m or >= 1m)
throw new ArgumentOutOfRangeException(nameof(winProbability), winProbability, "Must be in the open interval (0, 1).");
if (bankroll < 0m)
throw new ArgumentOutOfRangeException(nameof(bankroll), bankroll, "Must be non-negative.");
if (fraction is <= 0m or > 1m)
throw new ArgumentOutOfRangeException(nameof(fraction), fraction, "Kelly fraction must be in (0, 1].");
// FullKellyFraction validates decimalOdds.
var full = FullKellyFraction(winProbability, decimalOdds);
if (full <= 0m)
return 0m;
var stake = fraction * full * bankroll;
// Truncate (floor toward zero) to two decimals so a stake suggestion never
// exceeds the computed figure — a conservative bias for real-money sizing.
return Math.Truncate(stake * 100m) / 100m;
}
}
@@ -9,6 +9,7 @@
@page "/my-bets" @page "/my-bets"
@using Marathon.Application.Betting @using Marathon.Application.Betting
@using Marathon.Domain.Betting
@implements IDisposable @implements IDisposable
@inject IStringLocalizer<SharedResource> L @inject IStringLocalizer<SharedResource> L
@inject IBetJournalService Service @inject IBetJournalService Service
@@ -184,6 +185,50 @@
data-test="journal-add-stake" /> data-test="journal-add-stake" />
</div> </div>
<div class="m-journal__form-field m-journal__form-field--wide" data-test="journal-kelly">
<label class="m-journal__form-label">@L["Journal.Kelly.Title"]</label>
<div style="display:flex; flex-wrap:wrap; gap:var(--m-space-3); align-items:flex-end;">
<div style="flex:1 1 150px;">
<span class="m-journal__form-hint">@L["Journal.Kelly.Bankroll"]</span>
<MudNumericField T="decimal?"
@bind-Value="_kellyBankroll"
Min="0m" Step="50m"
Variant="Variant.Outlined"
data-test="journal-kelly-bankroll" />
</div>
<div style="flex:1 1 150px;">
<span class="m-journal__form-hint">@L["Journal.Kelly.Probability"]</span>
<MudNumericField T="decimal?"
@bind-Value="_kellyProbabilityPercent"
Min="0m" Max="100m" Step="1m"
Variant="Variant.Outlined"
data-test="journal-kelly-prob" />
</div>
</div>
@if (KellySuggestion is { } suggestion)
{
@if (suggestion > 0m)
{
<div style="margin-top:var(--m-space-2); display:flex; align-items:center; gap:var(--m-space-3); flex-wrap:wrap;">
<span class="m-journal__form-hint" data-test="journal-kelly-suggestion">
@string.Format(CultureInfo.CurrentCulture, L["Journal.Kelly.Suggestion"].Value, suggestion)
</span>
<button type="button" class="m-chip" @onclick="ApplyKellyStake" data-test="journal-kelly-apply">
@L["Journal.Kelly.Apply"]
</button>
</div>
}
else
{
<span class="m-journal__form-hint" data-test="journal-kelly-noedge">@L["Journal.Kelly.NoEdge"]</span>
}
}
else
{
<span class="m-journal__form-hint">@L["Journal.Kelly.Hint"]</span>
}
</div>
<div class="m-journal__form-field m-journal__form-field--wide"> <div class="m-journal__form-field m-journal__form-field--wide">
<label class="m-journal__form-label">@L["Journal.Field.Notes"]</label> <label class="m-journal__form-label">@L["Journal.Field.Notes"]</label>
<MudTextField T="string" <MudTextField T="string"
@@ -644,6 +689,33 @@
private string? _formError; private string? _formError;
private Guid? _pendingDeleteId; private Guid? _pendingDeleteId;
private AddBetForm _form = new(); private AddBetForm _form = new();
// Kelly stake-helper state — page-local (not persisted with the bet). Bankroll
// intentionally survives form resets so it carries across successive entries.
private decimal? _kellyBankroll;
private decimal? _kellyProbabilityPercent;
/// <summary>
/// Quarter-Kelly suggested stake from the entered bankroll + win probability and
/// the form's current rate. Null when inputs are incomplete/invalid; 0 when the
/// price carries no positive edge.
/// </summary>
private decimal? KellySuggestion
{
get
{
if (_kellyBankroll is not { } bankroll || bankroll <= 0m) return null;
if (_kellyProbabilityPercent is not { } pct || pct <= 0m || pct >= 100m) return null;
if (_form.Rate <= 1m) return null;
return KellyCalculator.SuggestStake(pct / 100m, _form.Rate, bankroll, KellyCalculator.DefaultFraction);
}
}
private void ApplyKellyStake()
{
if (KellySuggestion is { } s && s > 0m)
_form.Stake = s;
}
private CancellationTokenSource? _loadCts; private CancellationTokenSource? _loadCts;
protected override async Task OnInitializedAsync() protected override async Task OnInitializedAsync()
@@ -64,6 +64,7 @@
<data name="Nav.Anomalies"><value>Anomalies</value></data> <data name="Nav.Anomalies"><value>Anomalies</value></data>
<data name="Nav.Results"><value>Results</value></data> <data name="Nav.Results"><value>Results</value></data>
<data name="Nav.Settings"><value>Settings</value></data> <data name="Nav.Settings"><value>Settings</value></data>
<data name="Nav.Export"><value>Export</value></data>
<data name="Home.Kicker"><value>Briefing</value></data> <data name="Home.Kicker"><value>Briefing</value></data>
<data name="Home.Title"><value>Hunting odds-flip anomalies</value></data> <data name="Home.Title"><value>Hunting odds-flip anomalies</value></data>
@@ -262,6 +263,9 @@
<data name="Export.Submit"><value>Export</value></data> <data name="Export.Submit"><value>Export</value></data>
<data name="Export.Cancel"><value>Cancel</value></data> <data name="Export.Cancel"><value>Cancel</value></data>
<data name="Export.Success"><value>Export saved to {0}</value></data> <data name="Export.Success"><value>Export saved to {0}</value></data>
<data name="Export.Hub.Lede"><value>Export captured odds snapshots to an Excel workbook for any date range — no need to open a specific event first.</value></data>
<data name="Export.Hub.Action"><value>Configure export</value></data>
<data name="Export.Hub.FilenameHint"><value>Saved as Marathon_&lt;from&gt;_to_&lt;to&gt;.xlsx in the configured export directory.</value></data>
<data name="Export.Error.MissingDates"><value>Pick a start and end date.</value></data> <data name="Export.Error.MissingDates"><value>Pick a start and end date.</value></data>
<data name="Export.Error.InvalidRange"><value>End date must be on or after the start date.</value></data> <data name="Export.Error.InvalidRange"><value>End date must be on or after the start date.</value></data>
<data name="Export.Error.Failed"><value>Export failed.</value></data> <data name="Export.Error.Failed"><value>Export failed.</value></data>
@@ -416,6 +420,13 @@
<data name="Journal.Empty.NotApplicable"><value>—</value></data> <data name="Journal.Empty.NotApplicable"><value>—</value></data>
<data name="Journal.Error.Generic"><value>Failed to save bet — check the event ID and try again.</value></data> <data name="Journal.Error.Generic"><value>Failed to save bet — check the event ID and try again.</value></data>
<data name="Journal.Submitted"><value>Bet recorded.</value></data> <data name="Journal.Submitted"><value>Bet recorded.</value></data>
<data name="Journal.Kelly.Title"><value>Stake helper (¼-Kelly)</value></data>
<data name="Journal.Kelly.Bankroll"><value>Bankroll</value></data>
<data name="Journal.Kelly.Probability"><value>Win probability (%)</value></data>
<data name="Journal.Kelly.Suggestion"><value>Suggested stake: {0:0.00}</value></data>
<data name="Journal.Kelly.Apply"><value>Apply</value></data>
<data name="Journal.Kelly.NoEdge"><value>No positive edge at this price.</value></data>
<data name="Journal.Kelly.Hint"><value>Enter bankroll + win probability for a ¼-Kelly stake.</value></data>
<data name="Journal.Resolve.None"><value>No pending bets needed grading.</value></data> <data name="Journal.Resolve.None"><value>No pending bets needed grading.</value></data>
<data name="Journal.Resolve.Done"><value>Graded {0} pending bet(s).</value></data> <data name="Journal.Resolve.Done"><value>Graded {0} pending bet(s).</value></data>
<data name="Journal.Confirm.Delete"><value>Delete this bet permanently?</value></data> <data name="Journal.Confirm.Delete"><value>Delete this bet permanently?</value></data>
@@ -66,6 +66,7 @@
<data name="Nav.Anomalies"><value>Аномалии</value></data> <data name="Nav.Anomalies"><value>Аномалии</value></data>
<data name="Nav.Results"><value>Результаты</value></data> <data name="Nav.Results"><value>Результаты</value></data>
<data name="Nav.Settings"><value>Настройки</value></data> <data name="Nav.Settings"><value>Настройки</value></data>
<data name="Nav.Export"><value>Экспорт</value></data>
<!-- Home / Dashboard --> <!-- Home / Dashboard -->
<data name="Home.Kicker"><value>Сводка</value></data> <data name="Home.Kicker"><value>Сводка</value></data>
@@ -275,6 +276,9 @@
<data name="Export.Submit"><value>Экспорт</value></data> <data name="Export.Submit"><value>Экспорт</value></data>
<data name="Export.Cancel"><value>Отмена</value></data> <data name="Export.Cancel"><value>Отмена</value></data>
<data name="Export.Success"><value>Файл сохранён в {0}</value></data> <data name="Export.Success"><value>Файл сохранён в {0}</value></data>
<data name="Export.Hub.Lede"><value>Экспорт собранных снимков коэффициентов в книгу Excel за любой диапазон дат — без необходимости открывать конкретное событие.</value></data>
<data name="Export.Hub.Action"><value>Настроить экспорт</value></data>
<data name="Export.Hub.FilenameHint"><value>Сохраняется как Marathon_&lt;от&gt;_to_&lt;до&gt;.xlsx в указанной папке экспорта.</value></data>
<data name="Export.Error.MissingDates"><value>Выберите даты начала и конца.</value></data> <data name="Export.Error.MissingDates"><value>Выберите даты начала и конца.</value></data>
<data name="Export.Error.InvalidRange"><value>Дата конца должна быть не раньше даты начала.</value></data> <data name="Export.Error.InvalidRange"><value>Дата конца должна быть не раньше даты начала.</value></data>
<data name="Export.Error.Failed"><value>Экспорт не удался.</value></data> <data name="Export.Error.Failed"><value>Экспорт не удался.</value></data>
@@ -429,6 +433,13 @@
<data name="Journal.Empty.NotApplicable"><value>—</value></data> <data name="Journal.Empty.NotApplicable"><value>—</value></data>
<data name="Journal.Error.Generic"><value>Не удалось сохранить ставку — проверьте ID события и повторите.</value></data> <data name="Journal.Error.Generic"><value>Не удалось сохранить ставку — проверьте ID события и повторите.</value></data>
<data name="Journal.Submitted"><value>Ставка записана.</value></data> <data name="Journal.Submitted"><value>Ставка записана.</value></data>
<data name="Journal.Kelly.Title"><value>Калькулятор ставки (¼-Келли)</value></data>
<data name="Journal.Kelly.Bankroll"><value>Банкролл</value></data>
<data name="Journal.Kelly.Probability"><value>Вероятность выигрыша (%)</value></data>
<data name="Journal.Kelly.Suggestion"><value>Рекомендуемая ставка: {0:0.00}</value></data>
<data name="Journal.Kelly.Apply"><value>Применить</value></data>
<data name="Journal.Kelly.NoEdge"><value>Нет преимущества при этом коэффициенте.</value></data>
<data name="Journal.Kelly.Hint"><value>Введите банкролл и вероятность для ставки по ¼-Келли.</value></data>
<data name="Journal.Resolve.None"><value>Ожидающих ставок к расчёту нет.</value></data> <data name="Journal.Resolve.None"><value>Ожидающих ставок к расчёту нет.</value></data>
<data name="Journal.Resolve.Done"><value>Рассчитано ожидающих: {0}.</value></data> <data name="Journal.Resolve.Done"><value>Рассчитано ожидающих: {0}.</value></data>
<data name="Journal.Confirm.Delete"><value>Удалить эту ставку безвозвратно?</value></data> <data name="Journal.Confirm.Delete"><value>Удалить эту ставку безвозвратно?</value></data>
@@ -0,0 +1,133 @@
using FluentAssertions;
using Marathon.Domain.Betting;
namespace Marathon.Domain.Tests.Betting;
public sealed class KellyCalculatorTests
{
// ── SuggestStake: edge handling ───────────────────────────────────────────
[Fact]
public void Should_ReturnZeroStake_When_NoPositiveEdge()
{
// p·o = 0.50 × 1.90 = 0.95 < 1 → negative edge.
var stake = KellyCalculator.SuggestStake(
winProbability: 0.50m, decimalOdds: 1.90m, bankroll: 1000m);
stake.Should().Be(0m);
}
[Fact]
public void Should_ReturnZeroStake_When_ExactlyBreakeven()
{
// p·o = 0.50 × 2.00 = 1 → zero edge.
var stake = KellyCalculator.SuggestStake(
winProbability: 0.50m, decimalOdds: 2.00m, bankroll: 1000m);
stake.Should().Be(0m);
}
[Fact]
public void Should_SizeQuarterKellyStake_When_PositiveEdge()
{
// full = (0.55×2.10 1)/(2.10 1) = 0.155/1.10 = 0.140909…
// quarter = 0.0352272… × 1000 = 35.2272… → truncated to 35.22.
var stake = KellyCalculator.SuggestStake(
winProbability: 0.55m, decimalOdds: 2.10m, bankroll: 1000m, fraction: 0.25m);
stake.Should().Be(35.22m);
}
[Fact]
public void Should_UseFullKelly_When_FractionIsOne()
{
// full = (0.60×2.00 1)/(2.00 1) = 0.20 → 0.20 × 1000 = 200.
var stake = KellyCalculator.SuggestStake(
winProbability: 0.60m, decimalOdds: 2.00m, bankroll: 1000m, fraction: 1.0m);
stake.Should().Be(200m);
}
[Fact]
public void Should_ScaleStake_Proportionally_WithBankroll()
{
var small = KellyCalculator.SuggestStake(0.60m, 2.00m, bankroll: 500m, fraction: 1.0m);
var large = KellyCalculator.SuggestStake(0.60m, 2.00m, bankroll: 1000m, fraction: 1.0m);
small.Should().Be(100m);
large.Should().Be(200m);
}
[Fact]
public void Should_NeverExceedComputedFigure_When_Truncating()
{
// Raw quarter-Kelly stake is 35.2272…; the suggestion must floor, not round up.
var stake = KellyCalculator.SuggestStake(0.55m, 2.10m, bankroll: 1000m, fraction: 0.25m);
stake.Should().BeLessThanOrEqualTo(0.25m * KellyCalculator.FullKellyFraction(0.55m, 2.10m) * 1000m);
}
// ── FullKellyFraction ─────────────────────────────────────────────────────
[Fact]
public void FullKellyFraction_Should_ComputeEdgeFraction()
{
KellyCalculator.FullKellyFraction(0.55m, 2.10m)
.Should().BeApproximately(0.140909m, 0.000001m);
}
[Fact]
public void FullKellyFraction_Should_BeNegative_When_NoEdge()
{
KellyCalculator.FullKellyFraction(0.40m, 2.00m).Should().Be(-0.20m);
}
[Fact]
public void FullKellyFraction_Should_BeZero_When_Breakeven()
{
KellyCalculator.FullKellyFraction(0.50m, 2.00m).Should().Be(0m);
}
// ── Guard clauses ─────────────────────────────────────────────────────────
[Theory]
[InlineData(0.0)]
[InlineData(1.0)]
[InlineData(-0.1)]
[InlineData(1.1)]
public void SuggestStake_Should_Throw_When_ProbabilityOutOfOpenInterval(double probability)
{
var act = () => KellyCalculator.SuggestStake((decimal)probability, 2.0m, 1000m);
act.Should().Throw<ArgumentOutOfRangeException>();
}
[Theory]
[InlineData(1.0)]
[InlineData(0.5)]
public void SuggestStake_Should_Throw_When_OddsNotGreaterThanOne(double odds)
{
var act = () => KellyCalculator.SuggestStake(0.55m, (decimal)odds, 1000m);
act.Should().Throw<ArgumentOutOfRangeException>();
}
[Fact]
public void SuggestStake_Should_Throw_When_BankrollNegative()
{
var act = () => KellyCalculator.SuggestStake(0.55m, 2.10m, bankroll: -1m);
act.Should().Throw<ArgumentOutOfRangeException>();
}
[Theory]
[InlineData(0.0)]
[InlineData(-0.25)]
[InlineData(1.5)]
public void SuggestStake_Should_Throw_When_FractionOutOfRange(double fraction)
{
var act = () => KellyCalculator.SuggestStake(0.55m, 2.10m, 1000m, (decimal)fraction);
act.Should().Throw<ArgumentOutOfRangeException>();
}
}