Lotto-Tip-Generator/README.md

# Lotto 6aus49 Analyse & Generator

Automatisiertes System zur Analyse von Lotto 6aus49-Daten und Generierung von KI-gestützten Tipps mit Telegram-Benachrichtigungen. Schwesterprojekt von [Eurojackpot](../Eurojackpot) — gleiche Architektur, angepasst an das Lotto-Format (6 Zahlen aus 49 + 1 Superzahl).

Eine detaillierte Architektur- und Datenfluss-Beschreibung steht in [documentation/ARCHITECTURE.md](documentation/ARCHITECTURE.md).

## 🎲 Features

- **🧠 AI/ML-basierte Tipp-Generierung**: Random Forest + LSTM (PyTorch) Hybrid-Predictor
- **🎨 Pattern-Analyse**: Historische Verteilungsmuster (N/M/H-Zonen)
- **⚡ 4-Strategien-System**: HYBRID-OPT, BALANCED-SPREAD, HIGH-EV, SOFT-CONTRARIAN mit adaptiver Gewichtung
- **💰 EV-Optimierung**: Quality-Score gewichtet gezielt auf unpopuläre (aber gleich wahrscheinliche) Zahlenkombinationen, um den Gewinnanteil im Trefferfall zu erhöhen
- **📚 Real-Time Learning**: Kontinuierliches Retraining bei neuen Ziehungen
- **🤖 Automatisierung**: Tipp-Generierung & Datenupdate via launchd, mit täglichem Watchdog gegen verpasste Läufe
- **📲 Telegram-Benachrichtigungen**: Automatische Tipps direkt aufs Smartphone, plus Watchdog-Alarm bei Problemen
- **🔄 Data-Updates**: API-Kette (Lottoland → GitHub-Archiv → lottoAPI) mit Web-Scraping- und manuellem Fallback

## 📁 Verzeichnisstruktur

```text
Lotto/
├── README.md
├── config/
│   └── notifications.json          # Telegram/Email Config
├── data/
│   ├── AlleLottozahlen.csv         # Ziehungshistorie
│   ├── backups/                    # CSV-Backups (automatisch rotiert, letzte 30)
│   ├── ultimate_ml_models/         # Trainierte Modelle (RF + LSTM)
│   └── generated_tips/             # Generierte Tipps
├── scripts/
│   ├── generators/
│   │   └── ultimate_ai_ml_hybrid_generator.py   # aktiver Generator
│   ├── automation/
│   │   ├── auto_update_and_learn.py   # Update + Retraining
│   │   ├── weekly_tip_generator.py    # Tipp-Generierung
│   │   ├── com.lotto.update.plist
│   │   ├── com.lotto.weekly.plist
│   │   └── com.lotto.watchdog.plist
│   └── utils/
│       ├── notifier.py              # Telegram/Email
│       ├── update_from_api.py       # API-Updater (aktiv)
│       ├── update_from_web.py       # Web-Scraping-Fallback (automatisch, wenn API nichts liefert)
│       ├── simple_update.py         # Manuelle Eingabe
│       ├── watchdog.py              # Prüft Daten-/Modell-Aktualität, alarmiert per Telegram
│       ├── validate_csv.py          # manuelles Utility
│       ├── verify_draws.py          # manuelles Utility
│       └── health_check.py          # manuelles Utility
├── documentation/
│   └── ARCHITECTURE.md
├── results/                        # Auswertungen (z.B. Superzahl-Statistik)
├── run_tip_generator.sh
├── run_update_and_learn.sh
├── run_watchdog.sh
└── logs/
```

## 🚀 Quick Start

### 1. Installation

```bash
python3 -m venv venv
source venv/bin/activate
pip install pandas numpy scikit-learn requests torch beautifulsoup4
```

### 2. Telegram-Bot einrichten

1. Erstelle einen Bot mit [@BotFather](https://t.me/botfather)
2. Kopiere den Bot-Token, hole deine Chat-ID (z.B. mit [@userinfobot](https://t.me/userinfobot))
3. Konfiguriere `config/notifications.json` (siehe [TELEGRAM_BOT_SETUP.md](TELEGRAM_BOT_SETUP.md)):

```json
{
    "telegram": {
        "enabled": true,
        "bot_token": "YOUR_BOT_TOKEN",
        "chat_id": "YOUR_CHAT_ID"
    }
}
```

Test-Benachrichtigung senden:

```bash
python scripts/utils/notifier.py --test
```

### 3. Tipps manuell generieren

```bash
python scripts/automation/weekly_tip_generator.py --force --num-tips 10

# Nur Historie anzeigen
python scripts/automation/weekly_tip_generator.py --history
```

### 4. Daten manuell aktualisieren + Modelle neu trainieren

```bash
./run_update_and_learn.sh
```

## 🧠 Generator-Strategien

Der Ultimate AI/ML Hybrid Generator (`scripts/generators/ultimate_ai_ml_hybrid_generator.py`) verteilt pro Lauf 10 Tipps über 4 Strategien, deren Gewichtung sich anhand der bisherigen Trefferleistung selbst anpasst (Startwerte in Klammern):

1. **HYBRID-OPT** (40%): AI-Score + historisches Pattern-Gewicht kombiniert
2. **BALANCED-SPREAD** (30%): erzwingt Verteilung über N/M/H-Zonen, kontrollierter Summenbereich
3. **HIGH-EV** (20%): 2–3 Zahlen >31, meidet empirisch belegte populäre Einzelzahlen — auf EV statt Trefferwahrscheinlichkeit optimiert
4. **SOFT-CONTRARIAN** (10%): bevorzugt in den letzten 30 Ziehungen unterrepräsentierte Zahlen

### Warum EV statt Trefferwahrscheinlichkeit?

Lotto-Ziehungen sind unabhängige Zufallsereignisse — kein Modell kann die
Trefferwahrscheinlichkeit über den statistischen Erwartungswert heben. Der
Quality-Score optimiert deshalb bewusst auf **Expected Value**: unpopuläre
Zahlenkombinationen haben bei einem Treffer weniger Mitgewinner und damit eine
höhere Auszahlung. Details und Quellen dazu in
[documentation/ARCHITECTURE.md](documentation/ARCHITECTURE.md#3-design-entscheidung-quality-score--ev-optimierung).

## 🔄 Daten aktualisieren

Der automatisierte Workflow (`auto_update_and_learn.py`) versucht in dieser
Reihenfolge: **1.** `LottoAPIUpdater.fetch_from_all_apis()` (Lottoland zuerst,
liefert die neueste Ziehung meist noch am Ziehungstag, dann GitHub-Archiv für
die Historie), **2.** bei leerem API-Ergebnis automatisch der Web-Scraper
(`update_from_web.py`, lotto.de) als Fallback.

Für manuelle Läufe steht zusätzlich bereit:

```bash
# Letzter Fallback: manuelle Eingabe / CSV-Import
python scripts/utils/simple_update.py
```

Jedes Update erstellt automatisch ein Backup unter `data/backups/` und
rotiert alte Backups (behält die letzten 30).

## 🐶 Watchdog

`scripts/utils/watchdog.py` läuft täglich (`com.lotto.watchdog.plist`) und
prüft, ob die letzte Ziehung in den Daten älter als 5 Tage ist bzw. ob die
Modelle noch auf einem älteren Stand trainiert sind als die neueste Ziehung.
Das fängt genau den Fall ab, dass ein `StartCalendarInterval`-Job verpasst
wurde (z.B. weil der Rechner im Schlaf war) — launchd holt das selbst nicht
nach. Bei einem Problem kommt ein Telegram-Alarm, sonst bleibt es still.

## 🤖 Automatisierung

Läuft über **launchd** (`~/Library/LaunchAgents/`), nicht crontab:

| Job | Plist | Zeitplan |
| --- | --- | --- |
| Update & Learning | `com.lotto.update.plist` | Mi + Sa, 20:00 Uhr |
| Tipp-Generierung | `com.lotto.weekly.plist` | Di + Fr, 21:00 Uhr |
| Watchdog | `com.lotto.watchdog.plist` | täglich, 21:30 Uhr |

## 📲 Telegram-Benachrichtigungen

Bei erfolgreicher Tipp-Generierung bzw. nach jeder ausgewerteten Ziehung
verschickt `LottoNotifier` automatisch eine Zusammenfassung (bester Tipp, Ø
Confidence/Quality, Trefferauswertung). Der Watchdog nutzt denselben Kanal
für Alarme.

## 📈 Performance Tracking

Alle Generierungen werden in `data/generated_tips/generation_history.json`
protokolliert, alle Ziehungsauswertungen in `data/learning_log.json`.

## 🧪 Tests

Regressionstests für den Popularity/EV-Score (`tests/test_popularity_score.py`):

```bash
pip install pytest
pytest tests/
```

## 🗂️ Datenformat

`data/AlleLottozahlen.csv` (Semikolon-getrennt):

```csv
datum;Z1;Z2;Z3;Z4;Z5;Z6;SZ
2026-08-08;2;8;22;30;38;43;4
```

## Hinweise

- Lotto 6aus49: 6 Zahlen aus 49 + 1 Superzahl (0–9), Ziehungen Mi + Sa
- Keine Gewinngarantie — statistisches Analyse-Tool, keine Vorhersagekraft
  über den Zufalls-Erwartungswert hinaus (siehe Abschnitt "Warum EV statt
  Trefferwahrscheinlichkeit?")
- Bot-Token niemals öffentlich teilen

## 🙋 Support

1. Logs prüfen: `logs/update_stdout.log`, `logs/stdout.log`, `logs/watchdog_stdout.log`
2. Test-Benachrichtigung: `python scripts/utils/notifier.py --test`
3. Historie prüfen: `python scripts/automation/weekly_tip_generator.py --history`

---

**🍀 Viel Glück bei der nächsten Ziehung! 🍀**