ReadMe exscapper_python_analyzer

# exscapper_python_analyzer

## Úvod a Účel Nástroja

**exscapper_python_analyzer** je pokročilý analytický nástroj napísaný v Pythone, navrhnutý na automatizovanú analýzu stávkových dát exportovaných zo služby Excapper. Excapper monitoruje pohyby kurzov a objemy stávok na burze Betfair Exchange v reálnom čase.

Tento skript implementuje sofistikovaný algoritmus, ktorý vychádza z metodológie a konceptov podrobne popísaných v dokumentácii služby Excapper (vrátane dodatkov pre profesionálov). Jeho hlavným cieľom je:

1.  **Spracovať** chronologické stávkové dáta z poskytnutého Markdown súboru (`data.md`).
2.  **Aplikovať** vylepšený algoritmus na identifikáciu potenciálnych **value betting príležitostí** (situácií, kde kurz nemusí presne odrážať reálnu pravdepodobnosť) a ďalších trhových signálov.
3.  **Detegovať** anomálie ako **Sharp Bets** (prudké nárasty objemu) a analyzovať **Money Way** (distribúciu peňazí).
4.  **Vygenerovať** prehľadný **Markdown report**, ktorý sumarizuje kľúčové zistenia, identifikované value príležitosti a významné signály.

Nástroj je určený pre stávkarov a traderov, ktorí chcú získať hlbší, dátovo podložený pohľad na dynamiku stávkových trhov a automatizovať časť svojho analytického procesu.

## Kľúčové Funkcie

*   **Automatické Parsovanie:** Načíta a spracuje štruktúrované dáta z Excapper Markdown exportu.
*   **Vylepšený Algoritmus:** Implementuje pokročilý algoritmus na detekciu value príležitostí, ktorý zahŕňa:
    *   Analýzu **Mismatch** (nesúladu) medzi Money Way a implikovanou pravdepodobnosťou.
    *   Detekciu **Sharp Bet** signálov (objem aj percentuálna zmena).
    *   Analýzu **trendov**, **perzistencie** a **akcelerácie** objemov a kurzov.
    *   **Dynamické prahové hodnoty** prispôsobené fáze zápasu a skóre.
    *   **Vážený skórovací systém** pre komplexné hodnotenie sily signálu.
    *   **Validáciu signálov** na zníženie falošných pozitív.
*   **Konfigurovateľnosť:** Umožňuje jednoduchú úpravu všetkých kľúčových parametrov a prahových hodnôt algoritmu. Ponúka prednastavené profily pre rôzne typy zápasov.
*   **Prehľadné Reportovanie:** Generuje detailný Markdown report s kľúčovými zisteniami, tabuľkami value príležitostí a Sharp Bet signálov.
*   **Flexibilita:** Možnosť spúšťania cez príkazový riadok s argumentmi pre vstupný súbor a profil nastavení.

## Požiadavky a Inštalácia

*   **Python:** Verzia 3.6 alebo vyššia.
*   **Knižnice:** `pandas`, `numpy`.
    *   Inštalácia potrebných knižníc (ak ich ešte nemáte):
        ```bash
        pip install pandas numpy
        ```

## Použitie Skriptu

Skript sa spúšťa z príkazového riadku (terminálu).

### Základné Spustenie

1.  Uistite sa, že máte súbor so stávkovými dátami z Excapperu uložený ako `data.md` v **rovnakej zložke** ako skript `exscapper_python_analyzer.py`.
2.  Otvorte terminál alebo príkazový riadok v tejto zložke.
3.  Spustite skript príkazom:
    ```bash
    python exscapper_python_analyzer.py
    ```
4.  Skript automaticky spracuje `data.md`, použije predvolený profil nastavení (`default`) a vygeneruje Markdown report v tej istej zložke (napr. `Nazov_Zapasu_analyza_YYYYMMDD_HHMMSS.md`).

### Pokročilé Spustenie (Argumenty)

Môžete špecifikovať vstupný súbor a profil nastavení pomocou argumentov:

*   `--input <cesta_k_suboru.md>`: Určuje cestu k vstupnému Markdown súboru s dátami.
*   `--settings <profil>`: Určuje, ktorý profil nastavení sa má použiť. Dostupné profily:
    *   `default`: Optimalizované pre zápasy s jasným favoritom (predvolené).
    *   `low_liquidity`: Upravené pre zápasy s nižšou likviditou.
    *   `balanced`: Upravené pre vyrovnanejšie zápasy.

**Príklady:**

*   Spracovanie iného súboru s predvolenými nastaveniami:
    ```bash
    python exscapper_python_analyzer.py --input "Iny_Zapas_Data.md"
    ```
*   Spracovanie `data.md` s nastaveniami pre nízku likviditu:
    ```bash
    python exscapper_python_analyzer.py --settings low_liquidity
    ```
*   Kombinácia oboch argumentov:
    ```bash
    python exscapper_python_analyzer.py --input "Cesta/K/Mojim/Datam.md" --settings balanced
    ```

## Popis Vstupných Dát (`data.md`)

Skript očakáva vstupný súbor v Markdown formáte, ktorý obsahuje tabuľku s chronologickými dátami exportovanými zo služby Excapper. Kľúčové stĺpce, ktoré skript spracováva, sú:

*   `Type`: `live` alebo `prematch`.
*   `Date`: Časový údaj záznamu (napr. `23:42 26.03`).
*   `Market`: Identifikátor trhu (napr. `1`, `X`, `2`).
*   `Summ`: Celkový spárovaný objem na danom trhu (€).
*   `Change`: Zmena objemu od predchádzajúceho záznamu (napr. `2€ / 0%`). Skript extrahuje objemovú aj percentuálnu zmenu.
*   `Time`: Minúta zápasu (pre `live` dáta).
*   `Score`: Aktuálne skóre (pre `live` dáta).
*   `Odds`: Aktuálny kurz na danom trhu.
*   `Change %`: Percentuálna zmena kurzu (ak je dostupná).
*   `All`: Celkový spárovaný objem na všetkých relevantných trhoch zápasu (€).
*   `Percent money on market`: Percentuálny podiel objemu daného trhu na celkovom objeme (%).

Skript sa snaží byť robustný voči drobným odchýlkam vo formátovaní tabuľky.

## Interpretácia Výstupného Reportu (`*_analyza_*.md`)

Vygenerovaný Markdown report poskytuje komplexný prehľad analýzy:

1.  **Analysis Summary (Súhrn Analýzy):**
    *   Základné informácie o analyzovanom zápase a celkovom objeme.
    *   **Key Findings (Kľúčové Zistenia):**
        *   *Market Distribution (Final):* Finálne rozdelenie peňazí medzi trhy 1, X, 2.
        *   *Value Betting Opportunities:* Celkový počet nájdených príležitostí a ich rozdelenie podľa trhu a smeru (BACK/LAY).
        *   *Maximum Mismatch Observed:* Najväčší zistený rozdiel medzi Money Way (%) a implikovanou pravdepodobnosťou (1/kurz), vrátane času a trhu, kde nastal.
        *   *Maximum Sharp Bet Signal:* Najväčší zaznamenaný nárast objemu v jednom intervale (Sharp Bet).

2.  **Detailed Value Opportunities Detected (Detailné Value Príležitosti):**
    *   Tabuľka so všetkými momentmi, kde algoritmus identifikoval value príležitosť.
    *   *Timestamp:* Časový údaj signálu.
    *   *Mkt:* Trh (1, X, 2).
    *   *Dir:* Odporúčaný smer stávky (BACK - stávka na výsledok, LAY - stávka proti výsledku).
    *   *Odds:* Kurz v momente signálu.
    *   *Weight:* Celkové vážené skóre signálu vypočítané algoritmom.
    *   *Thresh:* Dynamická prahová hodnota použitá pre rozhodnutie v danom momente.
    *   *Conf:* Úroveň dôvery (Confidence Level) od 0.0 do 1.0, vypočítaná ako `Weight / Thresh`. Vyššia hodnota znamená silnejší signál nad prahom.
    *   *Key Factors:* Hlavné komponenty algoritmu, ktoré najviac prispeli k identifikácii signálu (napr. Mismatch, Sharp Bet, Persistent Volume).

3.  **Top 10 Significant Sharp Bet Signals (Top 10 Významných Sharp Bet Signálov):**
    *   Tabuľka zobrazujúca 10 najväčších nárastov objemu (podľa €) zaznamenaných počas analýzy.
    *   Užitočné pre sledovanie momentov najväčšej trhovej aktivity, aj keď neviedli priamo k value signálu.

## Konfigurácia a Ladenie Parametrov

Skript umožňuje detailné nastavenie parametrov algoritmu v sekcii `# Configuration section` na začiatku kódu.

### Prehľad Konfiguračných Profilov

Skript ponúka tri prednastavené profily (slovníky `DEFAULT_SETTINGS`, `LOW_LIQUIDITY_SETTINGS`, `BALANCED_MATCH_SETTINGS`), ktoré môžete aktivovať pomocou argumentu `--settings` pri spustení. Predvolený je `DEFAULT_SETTINGS`, optimalizovaný pre zápasy s jasným favoritom.

### Detailný Popis Parametrov (v rámci `ACTIVE_SETTINGS`)

*   **`VALUE_THRESHOLD` (float):** Základná prahová hodnota pre celkové vážené skóre signálu. Ak je skóre signálu (po všetkých úpravách a penalizáciách) vyššie alebo rovné tejto hodnote (upravenej dynamicky), je identifikovaná value príležitosť. *Nižšia hodnota = viac signálov (vyššia citlivosť), ale potenciálne menej spoľahlivých.*
*   **`MIN_VOLUME_CHANGE` (int):** Minimálny absolútny nárast objemu v EUR v jednom časovom kroku (zvyčajne 1 minúta), aby bol braný do úvahy ako súčasť Sharp Bet signálu. *Nižšia hodnota = citlivejšie na menšie objemové špičky.*
*   **`MIN_PERCENT_CHANGE` (float):** Minimálny percentuálny nárast objemu v jednom časovom kroku (vzťahujúci sa k predchádzajúcemu celkovému objemu na trhu), aby bol braný do úvahy ako súčasť Sharp Bet signálu. *Nižšia hodnota = citlivejšie na relatívne malé zmeny pri nízkych objemoch.*
*   **`THRESHOLD_HIGH_MISMATCH` (float):** Prahová hodnota pre *vysoký* rozdiel (mismatch) medzi Money Way (%) a implikovanou pravdepodobnosťou (1/kurz). Napr. 0.15 znamená 15 percentuálnych bodov rozdielu. Prispieva najviac k váženému skóre.
*   **`THRESHOLD_MEDIUM_MISMATCH` (float):** Prahová hodnota pre *stredný* mismatch. Prispieva menej k skóre ako vysoký mismatch.
*   **`THRESHOLD_LOW_MISMATCH` (float):** Prahová hodnota pre *nízky* mismatch. Prispieva najmenej k skóre.
*   **`MIN_MARKET_VOLUME` (int):** Minimálny celkový spárovaný objem na *konkrétnom trhu* (1, X alebo 2), aby bol signál z tohto trhu považovaný za spoľahlivý. Signály z trhov pod týmto objemom sú penalizované. *Vyššia hodnota = ignoruje signály na menej likvidných trhoch.*
*   **`CRITICAL_LOW_VOLUME` (int):** Absolútne minimálny objem na trhu. Ak je objem nižší, signál je automaticky invalidovaný, bez ohľadu na skóre. Slúži ako bezpečnostná poistka proti signálom z extrémne nelikvidných trhov.
*   **`CRITICAL_MINUTES` (List[int]):** Zoznam minút zápasu (zvyčajne okolo polčasu a konca zápasu), kedy môžu byť signály menej spoľahlivé kvôli zvýšenej volatilite alebo špecifickému správaniu trhu. Signály v týchto minútach sú mierne penalizované.

### Tipy na Ladenie (Čo robiť, ak...)

*   **Príliš veľa signálov / Nízka kvalita:**
    *   **Zvýšte `VALUE_THRESHOLD`:** Najefektívnejší spôsob, ako sprísniť kritériá. Skúste zvyšovať po krokoch (napr. z 3.2 na 3.5, potom na 4.0).
    *   **Zvýšte prahy pre mismatch:** Mierne zvýšte `THRESHOLD_HIGH/MEDIUM/LOW_MISMATCH` (napr. o 0.01 - 0.03).
    *   **Sprísnite Sharp Bet kritériá:** Zvýšte `MIN_VOLUME_CHANGE` a/alebo `MIN_PERCENT_CHANGE`.
    *   **Zvýšte `MIN_MARKET_VOLUME`:** Ignorujte signály z menej likvidných trhov.
    *   **Rozšírte `CRITICAL_MINUTES`:** Pridajte viac minút, kde očakávate šum.

*   **Príliš málo signálov / Chýbajúce príležitosti:**
    *   **Znížte `VALUE_THRESHOLD`:** Opatrne znižujte prahovú hodnotu (napr. z 4.0 na 3.5, potom na 3.2). Pozor na zvýšenie počtu falošných signálov.
    *   **Znížte prahy pre mismatch:** Mierne znížte `THRESHOLD_HIGH/MEDIUM/LOW_MISMATCH`.
    *   **Znížte `MIN_MARKET_VOLUME`:** Zahrňte do analýzy aj menej likvidné trhy (zvýšené riziko!).
    *   **Analyzujte váhy:** Skontrolujte logiku váh vo funkcii `identify_value_opportunity` – možno niektorý dôležitý faktor nedostáva dostatočnú váhu vo vašom type zápasov.

*   **Signály nie sú spoľahlivé (vedú k stratám):**
    *   **Zamerajte sa na kvalitu, nie kvantitu:** Použite prísnejšie nastavenia (vyššie prahy).
    *   **Analyzujte `Key Factors`:** V reporte sledujte, ktoré faktory najčastejšie vedú k ziskovým/stratovým signálom a upravte ich váhy v kóde (vyžaduje úpravu logiky váženia).
    *   **Pridajte ďalšie filtre:** Zvážte pridanie ďalších validačných krokov do funkcie `identify_value_opportunity` (napr. vyžadovať potvrdenie signálu na viacerých trhoch, alebo zohľadniť live štatistiky, ak sú dostupné).
    *   **Backtestujte:** Najlepší spôsob optimalizácie je systematický backtesting rôznych nastavení na historických dátach.

## Tipy pre Profesionálnych Traderov

*   **Integrácia do Workflow:** Výstupný report používajte ako **skener** potenciálnych príležitostí alebo ako **potvrdenie** vašej vlastnej analýzy, nie ako automatický pokyn na stávku.
*   **Kombinovanie Dát:** Spojte signály z tohto skriptu s ďalšími zdrojmi:
    *   *Live Štatistiky Zápasu:* Poskytujú kontext k pohybom kurzov a objemov. Dominancia tímu v štatistikách môže potvrdiť value signál.
    *   *Hĺbka Trhu (Order Book):* Analýza dostupných objemov na rôznych kurzoch na Betfair je kľúčová pre posúdenie realizovateľnosti vstupu/výstupu.
    *   *Porovnanie Bookmakerov:* Hľadajte arbitrážne alebo výrazné value príležitosti porovnaním kurzov z reportu s kurzami tradičných stávkových kancelárií.
    *   *Správy a Externé Faktory:* Zohľadnite novinky, zranenia, počasie atď.
*   **Optimalizácia Parametrov:** Neberte prednastavené profily ako dogmu. Experimentujte s parametrami a **backtestujte** rôzne konfigurácie na historických dátach z líg a zápasov, na ktoré sa špecializujete.
*   **Analýza Váh a Faktorov:** Skúmajte, ktoré `Key Factors` v reporte najčastejšie korelujú s úspešnými obchodmi a zvážte úpravu váhového systému v kóde skriptu.
*   **Vývoj Vlastných Signálov:** Použite tento skript ako základ a rozšírte ho o vlastné signály alebo komplexnejšie modely (napr. strojové učenie na predikciu krátkodobých pohybov kurzov).
*   **Manažment Rizika:** Aj najlepší signál môže zlyhať. Vždy používajte adekvátny bankroll management a stratégie riadenia rizika (stop-loss, hedging, veľkosť pozície podľa dôvery).

## Limity Nástroja a Dôležité Upozornenia

*   **Kvalita Vstupných Dát:** Analýza je priamo závislá od presnosti, úplnosti a časového rozlíšenia dát v vstupnom `data.md` súbore.
*   **Historická Analýza:** Skript analyzuje dáta *po* udalosti. Neposkytuje predikcie v reálnom čase.
*   **Absencia Herného Kontextu:** Skript nemá prístup k live štatistikám alebo vizuálnemu priebehu hry. Interpretácia signálov musí byť doplnená o tento kontext.
*   **Zjednodušené Modely:** Použité modely (napr. pre trendy, EV) sú zjednodušeniami komplexnej reality trhu.
*   **Žiadna Garancia Zisku:** Tento nástroj je analytická pomôcka. Identifikované "value" príležitosti nezaručujú zisk. Stávkovanie a trading sú spojené s rizikom. Rozhodnutia sú na zodpovednosti používateľa.
*   **Potreba Interpretácie:** Výstupy skriptu vyžadujú kritické zhodnotenie a interpretáciu skúseným používateľom.

## Poďakovanie (Credits)

Tento nástroj bol vyvinutý v rámci interaktívnej spolupráce. Osobitné poďakovanie patrí modelu **Claude 3.7 Sonnet** od Anthropic za jeho významný prínos pri návrhu vylepšeného algoritmu a generovaní podstatných častí kódu a analytických textov. Poďakovanie patrí aj používateľovi za cielené otázky a vedenie celého procesu.

## Licencia

(Tu môžete doplniť informácie o licencii, napr. MIT License, alebo uviesť, že kód je pre osobné použitie.)