---
name: kelly-event-sizer
description: 將二元事件的機率、可成交賠率、成本與本金整理成可檢查的凱利部位。當使用者問「押多少」、分數凱利、預測市場或運彩的下注比例、相關事件配置，或想用歷史預測校準收縮係數時使用；支援單一事件、最多三個相關事件與機率紀錄校準。
---

# Kelly Event Sizer

把使用者的假設與實際賠率分開，讓程式決定部位。**所有計算數字只能來自腳本輸出**；AI 負責問問題、核對事件與轉述結果，不能改用心算。

## 資料未齊時的唯一回覆

**本節優先於後面的計算、提早結束與結果卡規則。** 下列資料未明確提供時，先補問：

- 事件定義與結算規則：什麼算 YES、結算時間、判定方、取消／退款方式。
- 使用者的機率 `p` 與理由；沒有額外資訊也可如實記錄，不替理由打分。
- 市場或外部基準 `q` 與來源；沒有基準時，須由使用者明確選擇 `k` 模式及倍數。
- 至少一側的實際可成交報價與報酬定義。`q` 不是淨賠率 `b`，價格也不是 `b`；不得由「市場 70%」推導成交價格或每股回收。
- 買入費與淨利抽成，兩項均須確認；使用者明確說明零費用才填零。明確包含全部費用的總成本或最終淨賠率，則不重問費用。
- 可用於這類決定的總本金，以及是否已有或計畫建立相關部位。

每輪將**已確認的累積資料**交給 `intake`。未知欄位省略或設 `null`，不填「合理」假設；`outcomes` 只放實際已提供報價的方向，未知側不放佔位物件。腳本不會判定資料是否真的由使用者提供，這是 AI 的責任。`awaiting_input` 時只用一句話列缺項、最多問兩件事，接著等待回答。依 `missing_fields` 只問缺少的子欄位，不重問已答內容。資料齊全時 `questions: []`，不再多問。

**等待時禁止給方向（包括「傾向買 NO」）、下注比例、金額、單位、成長率、財富情境或結果卡。** 不以「假設零費用」「以本金 1,000 示範」或條件式數字補洞，也不能先給數字再追問。不得把 YES 的補數冒充 NO 的成交價。缺另一側報價不必強迫補齊：只評估已提供的一側，另一側仍未知。

只有使用者**明確要求合成試算**時，才可使用假設：設定 `purpose: example`、`example_requested: true`，逐項列出事件、報酬、成本、本金等假設，並提供完整輸入通過 `intake`。所有結果都標示「合成示範」，不當作使用者的實際部位。不得自行切換成示範。唯一保留的數值預設是 λ 模式的 `lambda: 0.5`；它不能補足其他缺項。

例如只收到「我估勝選 60%，市場 70%」時，可以回覆：

> 還缺事件與結算規則、實際可成交報價與報酬、費用、機率理由、基準來源、本金及相關部位。
> 1. 這是哪一屆、哪個選區的事件？合約如何判定與結算，取消時如何處理？
> 2. 你實際能成交的是哪一方向？價格或賠率是多少，勝出時的回收如何定義？

下一輪已補事件與報價，就只追問剩下的費用、理由、本金等缺項；不要先選邊。完整的待補資料 JSON 見 `assets/incomplete-input.json` 與 `assets/incomplete-result.json`。

核心流程不依賴平台。Polymarket、其他預測市場、運彩與二元選擇權都是可選輸入；不主動推薦市場、不替使用者估計機率、不暗示事件會發生。不構成投資建議，在地法規請自行確認。

## 執行前

- 先讀 [輸入與輸出格式](references/schema.md)；需要推導或統計方法時再讀 [公式與校準](references/formulas.md)。
- 優先使用環境內既有的 NumPy、SciPy。缺套件時在這個 Skill 的獨立虛擬環境使用 `uv sync --locked --no-build`，使用已修補 uv、保持 TLS 驗證，不全域安裝。工具本身不連網。
- 需要能執行 Python 的 AI 環境。只有文字對話時說明無法計算，不編造金額。網站上的固定示範不是即時試算器。
- `scripts/kelly.py` 提供 `intake`、`normalize`、`single`、`joint`、`calibrate`；JSON 經 stdin 或 `--input FILE` 傳入，stdout 輸出一個 JSON。缺資料回 `awaiting_input`，正常退出；格式錯誤回 `status: error` 與非零退出狀態。

```bash
uv run --locked python scripts/kelly.py intake --input assets/incomplete-input.json
uv run --locked python scripts/kelly.py single --input assets/video-example-input.json
uv run --locked python -m unittest discover -s scripts -p 'test_*.py'
```

也可將 `scripts/` 加入 module search path 後匯入 `kelly`，呼叫同名函式。

## 對話流程

**每輪最多問兩件事。** 已提供的資訊直接採用，只問缺少的項目；不要把八步合成一輪問卷。

1. **定義事件。** 確認什麼算發生、何時結算、由誰依哪套規則判定。規則不清，或取消／退款尚未釐清時停在這裡。只接受兩種互斥且涵蓋全部結果的事件。
2. **取得使用者的 `p` 與理由。** 問事件發生機率，追問「你知道什麼是市場或基準不知道的？」記下原話供第 5 步使用。不替使用者估 p；說不出數字時，請他從大概三成、五成或七成選一個再自行微調。p 為 0 或 1 時追問是否真的確定，說明凱利可能建議全押或不押，確認後才傳 `certainty_confirmed: true`。
3. **取得外部基準 `q`。** 有 YES 買賣報價時用中間價；雙邊賠率用去抽水機率；沒有市場時採使用者提供的歷史基準率或專家共識，記錄來源與時間。兩者都沒有時，明說「沒有基準可以收縮」，只用 `k` 模式，請使用者選凱利倍數。
4. **取得可成交賠率與成本。** 每側分別取得實際能買到的價格，不能把 YES 補數冒充 NO 成交價。「押 X 贏 Y」必問 Y 是淨利還是含本金總回收。`contract` 只用於已確認勝出每股回收一單位的合約。`q` 是基準機率，`b` 是每單位投入能淨賺的賠率；兩者與成交價刻意分開。確認買入費及抽成，或使用者提供的含全費總成本／最終淨賠率。資料齊全後可用 `normalize` 核對，不把中途正規化結果當作建議。
5. **取得本金與 λ。** 問「願意拿來做這類決定的總資金」，不問「這筆要押多少」。白話選項是完全相信自己（1）、和基準各半（0.5）、基準大概比我準（0.25）。沒選時採 0.5，說明這是暫時各占一半的預設，不是已校準準確度。第 2 步說不出額外資訊時建議 λ 不超過 0.25，最終由使用者決定。有歷史預測紀錄就提議校準。可另設單筆占本金比例上限 `cap`。
6. **檢查相關部位。** 問是否持有相關部位，或打算同時押相關事件。有則切換聯合模式，最多三件；取得每件已選方向、賠率與現有資金占比。不能忽略既有曝險，不符合支援格式時先停下說明缺口。
7. **執行腳本。** `intake` 確認 `ready` 後才呼叫 `single` 或 `joint`；兩個入口也會自行檢查，缺資料仍回 `awaiting_input`。聯合檢查須給 `operation: joint`。依下節處理停止狀態；腳本失敗就回報錯誤與待修輸入，不心算。只有一側報價時，明說另一側尚未評估。
8. **結果與收尾。** 依 JSON 轉述，不把條件數字說成保證報酬。最後一定請使用者寫下「看到什麼證據，我會改變 p」。

資料通過檢查後，兩側都沒有正比例就結束、解釋原因，**不給下注金額**。缺另一側報價時，只能說已知方向無優勢。資料未齊一律回到補問流程，不能提早宣告有或沒有優勢。

## 模式與護欄

### 單一事件

- λ 模式先收縮 p 再求凱利；k 模式把原始 p 的凱利乘上指定倍數。兩種都保留原版完整凱利。
- 有兩側成交報價就兩側都算。一側有正比例則選該側，皆無則 `no_edge`；零倍數或零上限也不提供金額。
- 雙邊合約價格加總小於一，或淨賠率顯示潛在套利時，回傳 `arbitrage_out_of_scope` 並停止。費用與結算可能改變表面套利，不在這裡配置套利部位。
- `confirmation_required` 必須先取得使用者的確定性確認。不要自動設定確認旗標。
- 上限生效時列原建議與實際採用比例，財富與成長率一律依上限後部位重算。
- 只有 `selected.equivalent: true` 才能說 λ 收縮等於 λ 倍凱利。價差／費用使基準低於打平點時才會更低；任意歷史基準不一概如此。
- 合約單位可為小數，不模擬最小下單量或逐檔成交。沒有可確認每單位成本時 `units` 是 `null`，不能自行補算。

### 最多三個相關事件

- 兩件事件取得 `P(A)`、`P(B)`、`P(B | A)` 或完整四格表；三件取得八格表或由使用者明確選「彼此獨立」，不默認使用者的事件獨立。
- 表格每格非負、總和與各 p 邊際吻合。狀態位元代表**原事件 YES 是否發生**，程式處理選 NO 的反轉。
- 基準預設是各 q 的獨立乘積，明示此假設；有完整基準聯合表時改用它並核對邊際。
- λ 混合整張情境表後最佳化，不把各事件單獨部位相加。k 模式縮放聯合最佳解。
- 固定長部位用 `existing_fraction` 表示，與當前本金及所提供賠率採同一估值基準，分開列既有、追加與合計。固定既有部位只支援 λ，k 不可暗中縮放／賣出既有部位。不支援空頭、借貸或無法放入三事件表的曝險。
- 保留現金緩衝。公式假設共同結算，未建模結算順序與資金解鎖；不同到期日不能直接推導跨期策略。`days` 只用共同評估期間。

### λ 校準

- 只採結果揭曉前留下的 p、同時點 q 與結果 y，不補估歷史預測。時間戳全部提供或全部省略；有時間須含時區。
- 少於 30 筆不估計，回報樣本不足、建議 λ 不超過 0.5。
- 固定網格、裁切、平手取小與 bootstrap 的常數見公式文件。
- 有時間用滾動切分，同時點不跨訓練／測試邊界，至少六個不同時間；無時間用固定 seed 五折。相關／重複事件先適當分組，不能假裝每列獨立。
- 內層候選評分選 λ，外層測試評估每折在訓練資料上選出的 λ。最終 `lambda_hat` 用於下一筆預測；`scores.calibrated` 是**各折各自選 λ 的樣本外流程分數**，不能說是最終 λ 的獨立驗證。
- 同列基準、校準流程、個人預測的樣本外 log loss、Brier score 與 90% bootstrap 區間。λ 接近零代表紀錄未顯示超出基準的資訊，也可能受雜訊／校準影響；區間寬代表紀錄不足以判斷。

## 結果卡

僅在資料齊全且腳本允許的狀態下使用。`awaiting_input` 不使用本節格式；`confirmation_required` 先取得確認，其他停止狀態依其規則回覆。合成示範須在卡片前清楚標示及列出假設。

單一事件依序列出：

1. **方向與原因：** YES／NO／不下注與一句原因。
2. **比例與金額：** 原版凱利、收縮／倍數後建議、上限後實際比例與金額，能算時附單位數；完整凱利僅供參考。
3. **兩種結果本金：** YES 與 NO 發生時各剩多少，買 NO 不可顛倒。
4. **打平機率與優勢：** 所選側的機率減該側打平點，買 NO 用 NO 機率。
5. **期望對數成長：** `growth`、可選 `daily_growth`，說明採用的機率；不是單次報酬、年化收益或保證獲利。
6. **收縮說明：** 依 `equivalent` 說明是否等同 λ 倍凱利。

聯合模式另列各事件的完整／追加／合計部位、每種情境的機率與財富及整體成長。校準另列最終 λ、每折 λ、區間與分數解讀。

固定保留提醒：

- 先讀結算規則。
- 檢查與其他部位的相關性。
- 考慮資金鎖定時間。
- 價格會變，下單前重算。
- 不構成投資建議，在地法規請自行確認。
- 請使用者寫下「看到什麼證據，我會改變 p」。

本版不處理多結果事件、機率區間／分布、回撤限制、訂單簿深度與逐檔成交。`outcomes` 陣列預留擴充位置，目前仍拒絕多結果輸入。