diff --git a/.gitignore b/.gitignore index 3b6a3e1..1d5004b 100644 --- a/.gitignore +++ b/.gitignore @@ -33,3 +33,6 @@ data/backups/ data/*.backup* data/generated_tips/weekly_tips_*.csv data/performance_reports/ + +# graphify Code-Graph (regenerierbar via /graphify --update) +graphify-out/ diff --git a/documentation/ARCHITECTURE.md b/documentation/ARCHITECTURE.md new file mode 100644 index 0000000..9108039 --- /dev/null +++ b/documentation/ARCHITECTURE.md @@ -0,0 +1,161 @@ +# Architektur + +Dieses Dokument beschreibt den aktiven Datenfluss, die Kernkomponenten und +bekannte Schwachstellen des Eurojackpot-Systems. Erstellt mit Hilfe einer +Code-Graph-Analyse (`graphify-out/`) analog zum Schwesterprojekt Lotto 6aus49 +— siehe dort `documentation/ARCHITECTURE.md` für den Vergleich. Format: 5 +Hauptzahlen (1–50) + 2 Eurozahlen. + +## 1. Aktiver Datenfluss + +```mermaid +flowchart LR + subgraph Ingestion["1. Daten-Ingestion"] + A1[lottoAPI / Lottoland / Sazka.cz] -->|EurojackpotAPIUpdater| B[AlleEurojackpotzahlen.csv] + A2[eurojackpot-zahlen.eu
Web-Scraper Fallback] -.->|nur falls API leer| B + end + + subgraph Training["2. Training"] + B --> C[EurojackpotFeatureEngineer] + C --> D[EurojackpotAIMLEngine
RandomForest] + C --> E[DeepLearningEngine
LSTM, PyTorch] + D --> F[Hybrid Predictor] + E --> F + end + + subgraph Generation["3. Tipp-Generierung"] + F --> G[UltimateAIMLEurojackpotGenerator] + G --> H1[HYBRID-OPT] + G --> H2[BALANCED-SPREAD] + G --> H3[HIGH-EV] + G --> H4[SOFT-CONTRARIAN] + H1 & H2 & H3 & H4 --> I[Quality/Popularity Score
5 Hauptzahlen + 2 Eurozahlen] + I --> J[10 Tipps als CSV] + end + + subgraph Learning["4. Learning-Loop"] + B -->|neue Ziehung| K[AutoUpdateAndLearn] + K -->|evaluiert| J + K -->|retrained| D + K -->|retrained| E + K --> L[EurojackpotRealTimeLearner /
strategy_weights] + end + + J --> M[EurojackpotNotifier
Telegram] + K --> M + + L -.->|beeinflusst nächsten Lauf| G +``` + +**Zwei launchd-Jobs** (nicht crontab — siehe Abschnitt 4): + +| Schritt | Entrypoint | Zeitplan (tatsächlich) | +|---|---|---| +| Ingestion + Training + Learning | `run_update_and_learn.sh` → `scripts/automation/auto_update_and_learn.py` | Mi + Sa, 08:00 Uhr (Morgen nach Di/Fr-Ziehung) | +| Tipp-Generierung | `run_tip_generator.sh` → `scripts/automation/weekly_tip_generator.py` | Mo + Do, 21:00 Uhr (Abend vor Di/Fr-Ziehung) | + +Anders als beim Lotto-Projekt prüft der Update-Job hier erst am **nächsten +Morgen**, nicht noch am Ziehungsabend — das gibt den Datenquellen mehr Zeit, +die Ziehung zu veröffentlichen. + +## 2. Kernkomponenten (aktive Pipeline) + +Alle Pfade relativ zum Projekt-Root. + +| Komponente | Datei | Rolle | +|---|---|---| +| `EurojackpotAPIUpdater` | `scripts/utils/update_from_api.py` | Holt neue Ziehungen über `fetch_from_all_apis()`: lottoAPI, Lottoland, Sazka.cz. `AutoUpdateAndLearn.update_data()` nutzt bereits `api_name='all'` **und** fällt bei leerem API-Ergebnis zusätzlich auf einen Web-Scraper zurück — robuster als die Lotto-Pipeline vor deren Fix. | +| `WebScraper` (`EurojackpotUpdater`) | `scripts/utils/update_from_eurojackpot_zahlen_eu.py` | Zweiter Fallback, wird nur aktiv wenn die API-Kette keine neuen Daten liefert. | +| `AutoUpdateAndLearn` | `scripts/automation/auto_update_and_learn.py` | Orchestriert: Daten aktualisieren → neue Ziehung prüfen → letzte Tipps evaluieren → Learning-Update (Retraining). | +| `EurojackpotFeatureEngineer` | `scripts/generators/ultimate_ai_ml_eurojackpot_generator.py` | Feature-Engineering (Frequenzen, Gaps, Momentum) für Haupt- und Eurozahlen. | +| `EurojackpotAIMLEngine` | `scripts/generators/ultimate_ai_ml_eurojackpot_generator.py` | RandomForest-Modelle. **Achtung:** eine Klasse mit identischem Namen existiert nochmal in der Backup-Datei (siehe Abschnitt 5) — beim Editieren die richtige Datei prüfen. | +| `DeepLearningEngine` | `scripts/utils/deep_learning_engine_pytorch.py` | LSTM (PyTorch), analog zu Lotto. | +| `UltimateAIMLEurojackpotGenerator` | `scripts/generators/ultimate_ai_ml_eurojackpot_generator.py` | **God Node der Pipeline** (40 Kanten im Code-Graph) — zentraler Einstiegspunkt `generate_ultimate_tips()`. | +| `EurojackpotPatternEngine`, `EurojackpotHybridOptimizer` | `scripts/generators/ultimate_ai_ml_eurojackpot_generator.py` | Wie bei Lotto: historische Muster bzw. Kandidaten-Generierung für HYBRID-OPT. | +| `EurojackpotRealTimeLearner` | `scripts/generators/ultimate_ai_ml_eurojackpot_generator.py` | Persistiert Learning-State, passt `strategy_weights` an. | +| `EurojackpotPerformanceTracker` | `scripts/generators/ultimate_ai_ml_eurojackpot_generator.py` | Loggt Trefferauswertungen. | +| `EurojackpotNotifier` | `scripts/utils/notifier.py` | Telegram-Benachrichtigungen. | + +### Die 4 Tipp-Strategien + +Analog zu Lotto: HYBRID-OPT, BALANCED-SPREAD, HIGH-EV, SOFT-CONTRARIAN — +gleiche Namen, gleiches Grundprinzip, aber Zahlenraum 1–50 (5 Hauptzahlen) +statt 1–49 (6 Zahlen) plus zusätzlich 2 Eurozahlen (`_get_smart_euro_numbers`). + +## 3. Design-Entscheidung: Quality-Score = EV-Optimierung — hier noch nicht nachgezogen + +Wie beim Lotto-Projekt gilt: Eurojackpot-Ziehungen sind unabhängige +Zufallsereignisse, kein Modell kann die Trefferwahrscheinlichkeit über den +Zufalls-Erwartungswert heben. `_calculate_quality_score()` sollte deshalb auf +Expected Value (unpopuläre Kombinationen → höhere Auszahlung bei Treffer) +optimieren. + +**Der Code hier entspricht noch dem alten, unrevidierten Lotto-Stand +(vor der Überarbeitung dort):** + +- `_calculate_popularity_score()` (Zeile 688) nutzt weiterhin die ad-hoc + `lucky_numbers = {3, 7, 9, 11, 13, 17, 19, 21, 23}`-Liste ohne empirische + Grundlage, statt der bei Lotto inzwischen verwendeten + `POPULAR_PLAYER_PICKS = {5, 7, 9, 11, 12, 13}`. +- Nur direkte ±1-Nachbarn werden als Muster erkannt, keine allgemeinen + arithmetischen Folgen (z.B. 5-10-15-20-25). +- Kein Odd/Even-Split-Kriterium. +- Popularity zählt nur 20% der Quality-Formel (`main_quality` 25%, + `euro_quality` 15%, `pattern_quality` 15%, `diversity` 10%, `popularity` + 20%, `recency` 15%) — Recency/Pattern-Anteile folgen Heuristiken, die auch + andere Systemspieler nutzen und damit das EV-Ziel eher unterlaufen. +- **`_get_smart_euro_numbers()`** (Zeile 673) hat **gar keine** + EV-Betrachtung — die 2 Eurozahlen werden rein nach AI-Score gewählt, analog + zur alten (inzwischen bei Lotto durch eine EV-Heuristik ersetzten) + Superzahl-Logik. + +Eine Übertragung der Lotto-Fixes (siehe dortiges `ARCHITECTURE.md` Abschnitt 3) +auf dieses Projekt steht noch aus. + +## 4. Automatisierung + +Läuft über **launchd** (`~/Library/LaunchAgents/`), nicht über `crontab`: + +| launchd Job | Plist | Zeitplan | +|---|---|---| +| `com.eurojackpot.update` | `scripts/automation/com.eurojackpot.update.plist` | Mi + Sa, 08:00 Uhr | +| `com.eurojackpot.weekly` | `scripts/automation/com.eurojackpot.weekly.plist` | Mo + Do, 21:00 Uhr | + +## 5. Bekannte Schwachstellen / offene Punkte + +- **Echtes Klassen-Duplikat:** `UltimateAIMLEurojackpotGenerator` (inkl. + `EurojackpotAIMLEngine`, `EurojackpotPatternEngine`, + `EurojackpotHybridOptimizer`) ist **wortgleich** sowohl in der aktiven + `scripts/generators/ultimate_ai_ml_eurojackpot_generator.py` als auch in + `scripts/generators/ultimate_ai_ml_eurojackpot_generator_v2.1_backup.py` + definiert. Nur die erste Datei wird importiert + (`auto_update_and_learn.py`, `weekly_tip_generator.py`). +- **Dritter, eigenständiger Generator:** `optimized_eurojackpot_generator.py` + (Klasse `UltimativerEurojackpotGenerator`) ist im README als Feature + dokumentiert, aber nirgends in der Automatisierung importiert. +- **Ungenutzter zweiter Updater:** `scripts/utils/update_historical_data.py` + (`EurojackpotDataUpdater`, eigene Quellen euro-jackpot.net/eurojackpot.de) + wird von keinem aktiven Skript referenziert. +- **~12 Standalone-Analyse-/Utility-Skripte** ohne Anbindung an die + Automatisierung: `eurojackpot_processor.py`, `eurojackpot_processor_fixed.py`, + `eurojackpot_simple.py`, `bereichskombinationen_analyse.py`, + `positionsanalyse.py`, `zahlen_umschluesseln.py`, + `treffer_analyse_umschluesselt.py`, `simple_bereichsanalyse.py`, + `create_example_files.py`, `tipp_generator_nmmhh.py`, + `tipp_generator_nmmhh_v2.py`, `eurojackpot_bereichsanalyse.py`, + `eurojackpot_generator.py`. +- **Popularity/Quality-Score veraltet** — siehe Abschnitt 3. +- **`documentation/`-Ordner** enthält laut README selbst "Alte Dokumentation" + (`README 2.md`, `NOTIFICATIONS_SETUP.md`, `ULTIMATE_GENERATOR_GUIDE.md`) — + Aktualität gegenüber dem laufenden Code nicht verifiziert. + +## 6. Code-Graph + +Navigierbare Graph-Ansicht unter `graphify-out/`: + +- `graphify-out/graph.html` — interaktive Visualisierung +- `graphify-out/GRAPH_REPORT.md` — God Nodes, Communities, auffällige Verbindungen +- `graphify-out/graph.json` — Rohdaten + +Bei strukturellen Änderungen: `/graphify --update` zum inkrementellen +Neuaufbau.