Generováno z docs/manual/prirucka.md · 2026-07-13

ElectionX — Příručka uživatele

Kanonický zdroj: docs/manual/prirucka.md · 2026-07-13 · In-app verze: http://localhost:3100/napoveda

1. Co ElectionX je a není

ElectionX je osobní poradce pro sázky na volby. Sleduje průzkumy a tržní kurzy, počítá vlastní pravděpodobnosti a ukazuje, kde se trh podle modelu mýlí. Nic víc.

Co ElectionX JE:

• Poradce: počítá pravděpodobnosti, hlídá čerstvost dat a značkuje příležitosti (FLAG / WATCH).
• Multi-venue: umí predikční trhy (Polymarket, Kalshi) i CZ/EU bookmakery (Tipsport, Fortuna, Chance, Betano, Sazka).
• Účetní: vede track record vypořádaných rad (hit rate, P&L, CLV, Brier), aby bylo poctivě vidět, jestli model něčemu pomáhá.

Co ElectionX NENÍ:

• ❌ Nesází. Žádné napojení na sázkové účty, žádná exekuce. Sázíš vždycky ty, ručně, u bookmakera. Exekuční vrstva (arming, entry policy, approval gaty) byla z kódu záměrně odstraněna (bundle 084).
• ❌ Žádná automatika bez tebe. Zdroje dat i sledování volby schvaluješ ručně. Výsledky voleb zadáváš ručně. Systém sám od sebe nic neschválí a nic nevsadí.
• ❌ Ne orákulum. Čísla jsou pravděpodobnosti s přiznanou nejistotou, ne předpovědi. Když jsou data stará (červený semafor), radám nevěř.

2. Rychlý start

Všechno běží lokálně na tvém Macu. LaunchAgents startují samy po přihlášení — normálně není co spouštět.

1. Otevři http://localhost:3100 — dashboard (Next.js).
2. Výchozí záložka Přehled má dva pohledy: - Doporučení — aktuální rady a stav sledovaných voleb, - Track record — vyhodnocení už vypořádaných rad.
3. Když dashboard neběží, viz kapitola 9 (Provoz) — restart příkazy.

Backend API běží na http://localhost:8100 (FastAPI). Datový cyklus (kurzy, průzkumy, doporučení) běží automaticky 4× denně (v 01, 07, 13 a 19 hodin). Ručně ho vyvoláš přes MCP nástroj run_cycle_now (kap. 8) nebo launchctl (kap. 9).

3. Jak číst přehled (Doporučení)

Přehled ukazuje pro každou sledovanou volbu tabulku kandidátů/sázek se sloupci Model · Blend · Trh · Edge · Doporučení · Sázka.

Tři pravděpodobnosti

Proč blend? Trh nese informaci taky. Kdybychom brali čistý model jako pravdu, vyráběli bychom si fantomový edge. Váha 0.35 znamená, že trh má skoro dvojnásobné slovo.

Edge, FLAG a WATCH

Sloupec Edge je edge_adjusted v procentních bodech (pp):

edge_adjusted = edge_raw − náklady platformy − 5pp nejistota modelu

• FLAG (zeleně) — edge_adjusted ≥ 5 pp. Teprve tady vzniká rada (BET_CANDIDATE). Práh je 5 pp proto, že menší edge se vejde do chybové úsečky samotného modelu (5pp fundamentální nejistota) — nebyl by to signál, ale šum.
• WATCH (žlutě) — edge v pásmu 3–5 pp. Sledovat, nesázet.
• Nad 8 pp je edge označen jako silný.

Návrh sázky

Sloupec Sázka (suggested_stake_czk) se ukazuje jen u FLAG řádků. Výpočet: frakční Kelly 15 % (konzervativní zlomek plného Kellyho) nad osobním poradním bankrollem, s capy:

• max 3 % bankrollu na jednu radu,
• max 6 % bankrollu na jednu volbu (korelovaná skupina rad).

Výchozí bankroll je 50 000 Kč; změníš ho MCP nástrojem set_bankroll (kap. 8) nebo přes API (PUT /parameter-overrides/global/advisor-bankroll). Návrh sázky je poradní číslo, nic víc — rozhodnutí je tvoje.

Řádky bez modelu

Když pro daný typ kontraktu model neexistuje, řádek ukáže jen poslední tržní cenu a pomlčky. Žádná čísla se nevymýšlejí.

4. Freshness semafor

Každá sledovaná volba má semafor čerstvosti dat (traffic_light). Klasifikuje se stáří každého datového feedu (průzkumy, kurzy) a bere se nejhorší z nich:

Pole reasons (tooltip na semaforu) říká, co konkrétně je staré — např. „polls stale 9.3d".

Co dělat u červené:

1. Nevěř radám pro tu volbu, dokud se data neobnoví.
2. Spusť cyklus ručně: MCP run_cycle_now, nebo launchctl kickstart gui/$UID/com.xlab.election-alpha-runner.
3. Když červená přetrvá, podívej se na zdroje volby (drill-down → Sources): schválený zdroj může mít rozbité URL (health check failing) — oprav URL, nebo zdroj degraduj a schval jiný.
4. Log cyklu: /tmp/election-alpha-runner.log (řádky CYCLE-SUMMARY).

5. Životní cyklus volby

Stavový graf (elections.status):

candidate ──► active ──► awaiting_results ──► resolved
     (kterýkoli stav ──► archived)

• candidate — volba je v systému (deterministický kalendář ji založí sám), ale nic se nepočítá. Čeká na tebe.
• active — zdroje schváleny + tracking schválen → běží sběr kurzů, import průzkumů, model a doporučení.
• awaiting_results — datum volby prošlo. Noční sweep sem volbu přepne automaticky. Nová doporučení se už negenerují; kurzy se sbírají ještě 7 dní po volbě (kvůli closing lines / CLV).
• resolved — výsledky zadány (kap. 6) a všechny sledované kontrakty vypořádány. Sweep na resolved/archived nikdy nesahá.
• archived — ručně odloženo; z kteréhokoli stavu.

Tvoje jediná povinnost: schválit zdroje (a tracking)

Nová volba startuje jako candidate se seznamem kandidátských zdrojů průzkumů. V drill-downu volby → záložka Sources:

1. Projdi navržené zdroje a nastav source_status: approved (hlavní) / fallback (záložní) / blocked (nepoužívat).
2. Schval tracking (tracking_status = approved).

Bez aspoň jednoho použitelného zdroje a schváleného trackingu volba nikdy nezačne generovat doporučení — schválení je vždy tvoje ruční akce, systém ho neudělá za tebe.

6. Zadávání výsledků

Po volbě (stav awaiting_results) zadáš oficiální výsledky ručně. Vypořádání pak proběhne automaticky: každá rada dostane outcome win / lose / void, spočítá se P&L a CLV (proti closing price) a volba se přepne na resolved.

Poctivé upozornění: dashboard zatím nemá formulář pro zadání výsledků — zadává se přes MCP nebo přímo přes API.

Přes MCP (doporučená cesta)

V Claude Desktop / Claude Code (kap. 8) řekni např.:

„Zapiš výsledek volby X: kontrakt Y = yes, kontrakt Z = no."

Claude zavolá nástroj resolve_outcome — a protože je to zápisová operace, vždy si od tebe nejdřív vyžádá potvrzení.

Přes API

# Jedna opce:
curl -X POST http://localhost:8100/market-options/<market_option_id>/resolve \
  -H 'Content-Type: application/json' \
  -d '{"outcome": "yes", "note": "oficiální výsledek"}'

# Celá volba najednou (mapa market_option_id → yes/no/void):
curl -X POST http://localhost:8100/elections/<election_id>/resolve \
  -H 'Content-Type: application/json' \
  -d '{"outcomes": {"<market_option_id>": "yes", "<jiné_id>": "no"}}'

Pravidla:

• Outcome je yes / no / void (zrušený trh → sázky vráceny).
• Zápis je idempotentní — stejný outcome podruhé nic nerozbije.
• Změna už zapsaného outcome vyžaduje "force": true a zapíše se do audit logu.
• Volba se přepne na resolved, až když všechny sledované (TRADEABLE) kontrakty mají outcome. Částečné zadání je v pořádku — zbytek doplníš později.

7. Track record — jak poznat, že model pomáhá

Záložka Přehled → Track record je poctivý scoreboard vypořádaných rad. Agregáty: n (počet), hit rate, celkové P&L, průměrné CLV, Brier vs. tržní baseline. Pod tím tabulka jednotlivých záznamů (režim advice = éra poradce; paper = historická éra paper tradingu), volitelně seskupená po volbách.

Jak čísla číst:

• Hit rate sám o sobě nestačí — vyhrávat se dá i se špatnými cenami (a prohrávat s dobrými). Je to jen hrubý kontext.
• CLV (closing line value) — rozdíl mezi cenou v době rady a closing price. Dlouhodobě kladné CLV = rady předbíhají trh. To je nejrychlejší signál skillu, funguje i na malém vzorku.
• P&L — co by rady vydělaly. Na malém n hodně šumí.
• Brier vs. market baseline — kalibrace modelu proti trhu. Model pomáhá, když je jeho Brier nižší než baseline trhu. Pod 10 vypořádaných forecastů se místo skóre ukazuje „zatím neměřitelné (n=X)" — malé vzorky nefalšujeme falešnou přesností.

Zkratka: CLV > 0 a Brier < market baseline na rostoucím n = model něčemu pomáhá. Cokoliv slabšího = zatím nevíme.

8. MCP — ovládání přes Claude

ElectionX má MCP server: poradce jde ovládat konverzačně z Claude Desktop nebo Claude Code. Server je tenký adaptér nad lokálním API (:8100) — žádná vlastní logika, žádné obcházení pravidel.

Připojení

• Claude Code: v adresáři repa funguje automaticky — server je deklarovaný v .mcp.json v rootu. Při prvním použití ho jen schválíš (trust gate).
• Claude Desktop: přidej server do ~/Library/Application Support/Claude/claude_desktop_config.json — hotový snippet je v docs/mcp_desktop_snippet.md.

Nástroje (8)

Zápisové nástroje (⚠️) mají v popisu instrukci, že Claude musí akci nejdřív explicitně potvrdit s tebou. Navíc je k dispozici resource electionx://guide — stručný výklad čísel pro agenta.

Příklady dotazů

• „Jsou teď nějaké FLAGy?" → get_advice
• „Ukaž mi čerstvost dat, něco mi tam svítí červeně." → get_freshness
• „Jak si vede track record za poslední volby?" → get_track_record
• „Nastav bankroll na 80 000 Kč." → set_bankroll (potvrdíš)
• „Volba X skončila, vítěz je Y — zapiš výsledky." → resolve_outcome (potvrdíš)

9. Provoz

Všechno běží jako macOS LaunchAgents (start po přihlášení, samy se drží naživu nebo běží podle plánu):

Restart

# Dashboard (:3100)
launchctl kickstart -k gui/$UID/com.xlab.election-alpha-dashboard

# API (:8100)
launchctl kickstart -k gui/$UID/com.xlab.election-alpha-api

# Datový cyklus hned teď (bez -k, jen spustit)
launchctl kickstart gui/$UID/com.xlab.election-alpha-runner

Logy

Data

PostgreSQL 16, databáze election_alpha na localhost:5432.

Rychlá diagnóza: dashboard má nahoře identity strip — zelená tečka = API connected; červená = API neběží (restartuj API, viz výše).

10. Metodika stručně

Detail vždy v decision notes (docs/agent_exchange/decisions/) a done reportech (docs/agent_exchange/done/) — tady jen mapa.

γ-kalibrace nejistoty (úloha 081A)

Syrová mezi-průzkumová disperze je systematicky moc těsná — model by byl přehnaně sebejistý (historicky např. 98.3 % na pozdějšího poraženého). LOO-CV kalibrace proto fituje inflační faktor γ (řádově ≈ 4.4×): σ_eff = γ · σ_disperze na vstupu Monte Carlo simulace. K tomu nezávisle drží 5pp floor fundamentální nejistoty (historická chyba průzkumů) a finální pravděpodobnosti se ořezávají do [0.01, 0.99] — kalibrovaný model nikdy netvrdí jistotu. Typ volby bez fitnutého artefaktu dostane nejkonzervativnější známé γ.

Shin — očištění kurzů o marži (úloha 081B)

Kurzy bookmakera obsahují marži (vig). Naivní normalizace 1/kurz ji rozprostře proporčně; Shin (1993) ji odstraňuje asymetricky a koriguje favorite-longshot bias. Fallback na proporční normalizaci jen při selhání solveru (loguje se). Ceny predikčních trhů se berou přímo; multi-outcome sada se sumou > 1.02 se normalizuje.

Shrinkage k trhu (úloha 081B)

p_blend = w·p_model + (1−w)·p_market, výchozí w = 0.35 — viz kap. 3. Váha je per-volba přenastavitelná přes parameter-override framework (market_blend_weight).

Cost model per platforma (úloha 081C)

Z hrubého edge se před prahem odečítají náklady:

Konstanty žijí na jednom místě: packages/parameters/advisor_policy.py.

Kam pro hloubku

• Pivot na poradce: decisions/2026-07-12_pivot_personal_betting_advisor_bundle_080.md
• Matematická vlna (γ + Shin + costs + Kelly): decisions/2026-07-12_wave_3_math_closure_bundle_081.md
• Data & freshness: decisions/2026-07-12_bundle_082a-082b-082c-082d-r9_closure.md
• Demolice exekuční vrstvy: decisions/2026-07-13_wave_4_demolition_closure_bundle_084.md
• Done reporty úloh 080A–085A: docs/agent_exchange/done/