docs(ev): correct kelly_percent units (0-100, not 0.0-1.0)#207
Merged
Conversation
…ly safety note
Issue 1 from #237: docs described kelly_percent as a fraction (0.0-1.0) but the
API actually emits a percentage (0-100). A consumer reading the docs literally
would interpret 34.43 as "3,443% of bankroll" or crash on values >1.0.
Fixes the schema in 6 doc pages:
- api-reference/opportunities-ev.mdx — schema row, 2 example values, Kelly
Criterion section (formula + sizing guide rewritten in 0-100 units)
- quickstart.mdx — example value 0.0218 -> 2.18
- api-reference/websocket.mdx — 2 example values 0.038 -> 3.8
- api-reference/stream.mdx — example value 0.038 -> 3.8
- examples/value-betting.mdx — Discord embed + Telegram template now
format as percentage with .toFixed(2)
- sdks/python.mdx — print formatters changed from {:.1%} (which
multiplies by 100, wrong for already-percentage values) to {:.2f}%
Adds an explicit safety callout in the Kelly Criterion section explaining
that the field is full Kelly with no quality-of-signal adjustment, and
recommending fractional Kelly (1/4 or 1/2) plus 1-2% bankroll cap when
warnings is non-empty or confidence_score < 80. This addresses the
secondary concern in #237 with documentation rather than a wire change.
Issue 2 (publishing full Kelly without quality adjustment) requires a
product call on whether to:
a) keep emitting full Kelly + add a kelly_percent_adjusted field, or
b) change kelly_percent in place + add kelly_percent_raw
Both options affect the wire and need migration discussion. Documenting
the safety note now is the minimum correct action.
Closes #237 (Issue 1)
Refs #237 (Issue 2 — needs product decision)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Mlaz-code
added a commit
that referenced
this pull request
May 7, 2026
…ly safety note (#207) Issue 1 from #237: docs described kelly_percent as a fraction (0.0-1.0) but the API actually emits a percentage (0-100). A consumer reading the docs literally would interpret 34.43 as "3,443% of bankroll" or crash on values >1.0. Fixes the schema in 6 doc pages: - api-reference/opportunities-ev.mdx — schema row, 2 example values, Kelly Criterion section (formula + sizing guide rewritten in 0-100 units) - quickstart.mdx — example value 0.0218 -> 2.18 - api-reference/websocket.mdx — 2 example values 0.038 -> 3.8 - api-reference/stream.mdx — example value 0.038 -> 3.8 - examples/value-betting.mdx — Discord embed + Telegram template now format as percentage with .toFixed(2) - sdks/python.mdx — print formatters changed from {:.1%} (which multiplies by 100, wrong for already-percentage values) to {:.2f}% Adds an explicit safety callout in the Kelly Criterion section explaining that the field is full Kelly with no quality-of-signal adjustment, and recommending fractional Kelly (1/4 or 1/2) plus 1-2% bankroll cap when warnings is non-empty or confidence_score < 80. This addresses the secondary concern in #237 with documentation rather than a wire change. Issue 2 (publishing full Kelly without quality adjustment) requires a product call on whether to: a) keep emitting full Kelly + add a kelly_percent_adjusted field, or b) change kelly_percent in place + add kelly_percent_raw Both options affect the wire and need migration discussion. Documenting the safety note now is the minimum correct action. Closes #237 (Issue 1) Refs #237 (Issue 2 — needs product decision) Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
kelly_percentas a fraction (0.0–1.0) but the API actually emits a percentage (0–100). Verified live:kelly_percent: 12.78,20.54, etc.Changes
content/en/api-reference/opportunities-ev.mdxcontent/en/quickstart.mdx0.0218→2.18content/en/api-reference/websocket.mdx0.038→3.8content/en/api-reference/stream.mdx0.038→3.8content/en/examples/value-betting.mdx.toFixed(2)%content/en/sdks/python.mdx{:.1%}(multiplies by 100, wrong for already-percentage values) →{:.2f}%The Python SDK formatter bug was the most subtle:
{:.1%}on a value of12.78would render as1278.0%. Fixed.Issue 2 (full Kelly without quality adjustment) — deferred
#237's second concern — that publishing full Kelly is dangerous without baking in
confidence_score/warnings— requires a wire-format product decision:kelly_percent_adjustedfieldkelly_percentin place + addkelly_percent_rawBoth options need migration discussion. Documenting the safety note now is the minimum correct action; the wire change can land separately once direction is chosen.
Test plan
npm run buildsucceedsgrep -r kelly_percent content/shows all references in 0–100 units, no remaining 0.0–x.x examplesCloses #237 (Issue 1)
Refs #237 (Issue 2 — needs product decision)
🤖 Generated with Claude Code