Skip to content

SETUP.md

Latest commit

 

History

History
227 lines (170 loc) · 7.32 KB

SETUP.md

File metadata and controls

227 lines (170 loc) · 7.32 KB

Setup Guide — Personal AI Platform

Schritt-für-Schritt-Anleitung zur Einrichtung deines persönlichen KI-Agenten.

🔒 Security-First Defaults

Die Personal AI Platform startet mit maximalen Sicherheitseinstellungen:

  • First-Run-Lockdown: Beim ersten Start funktioniert nur /setup — alle anderen Befehle und Features sind deaktiviert, bis der Setup-Wizard abgeschlossen ist. Dies verhindert unbefugten Zugriff vor der Konfiguration.
  • Alle Integrationen deaktiviert: Wetter, Home Assistant, Google Kalender, Web-Suche und Wikipedia sind standardmäßig aus. Du musst sie explizit im Setup-Wizard oder in der config.yaml aktivieren.
  • User-ID-Validierung: Nur deine Telegram-User-ID (während des Setups erkannt) kann mit dem Bot interagieren. Unbekannte Absender werden automatisch abgewiesen.
  • Feature Gates: Alle 29 Features sind einzeln an-/abschaltbar. Inaktive Features generieren keine LLM-Calls und übertragen keine Daten.
  • Local Mode verfügbar: Du kannst alle externen APIs deaktivieren — der Agent läuft dann vollständig lokal (nur Telegram + LLM).

💡 Explizite Zustimmung erforderlich: Kein Feature wird ohne deine ausdrückliche Konfiguration aktiv.

Voraussetzungen

  • Python 3.12+ installiert (python.org)
  • Telegram-Account auf deinem Handy oder Desktop
  • Terminal (CMD, PowerShell, bash) — Grundkenntnisse hilfreich
  • Optional: Home Assistant Instanz im lokalen Netzwerk

1. Repository clonen

git clone https://github.com/DevOpsOfChaos/personal-ai-platform.git
cd personal-ai-platform

2. Abhängigkeiten installieren

# Optional: Virtual Environment erstellen
python -m venv .venv
.venv\Scripts\activate  # Windows
source .venv/bin/activate  # Linux/Mac

# Abhängigkeiten installieren
pip install -r requirements.txt

3. Setup Wizard starten

python setup_wizard.py

Der Wizard führt dich durch 7 Schritte:

Schritt 1: Grundeinstellungen

  • Dein Name
  • Sprache (Deutsch/Englisch)
  • Zeitzone (z.B. Europe/Berlin)
  • Standort (für Wetter)
  • Antwort-Stil (kurz/normal/ausführlich)
  • Emoji-Nutzung

Schritt 2: Telegram Bot

BotFather aufrufen

  1. Öffne Telegram auf deinem Handy oder Desktop
  2. Suche nach @BotFather (offizieller Bot von Telegram)
  3. Sende /newbot
  4. Gib einen Namen ein (z.B. Mein Agent)
  5. Gib einen Username ein — muss auf bot enden (z.B. mein_agent_bot)

Du: Mein Agent

Du: mein_agent_bot

BotFather: Done! Congratulations on your new bot. Use this token to access the HTTP API: 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz-123456 Keep your token secure and store it safely.


6. **Kopiere den Token** (die lange Zeichenkette) und gib ihn im Wizard ein
7. Sende `/start` an deinen neuen Bot in Telegram
8. Der Wizard findet deine User-ID automatisch

### Schritt 3: OpenRouter (LLM)

1. Gehe zu [openrouter.ai/keys](https://openrouter.ai/keys)
2. Erstelle einen Account (kostenlos, keine Kreditkarte nötig)
3. Erstelle einen API-Key → kopieren
4. Im Wizard einfügen und **testen lassen**
5. Modelle wählen:
   - **Einfach**: Für schnelle Antworten (z.B. `deepseek/deepseek-chat`)
   - **Komplex**: Für Analysen & Zusammenfassungen
   - **Reasoning**: Optional, für Denk-Aufgaben
6. 💡 **Kostenlos-Tipp**: `:free` an Modellnamen anhängen:
   - `google/gemma-3-27b-it:free`
   - `meta-llama/llama-4-maverick:free`
   - `deepseek/deepseek-r1:free`

### Schritt 4: Integrationen (optional)

#### OpenWeatherMap (Wetter)
1. [openweathermap.org/api](https://openweathermap.org/api) → Sign Up
2. API-Key generieren (kostenloser Tarif: 1000 Calls/Tag)
3. Im Wizard einfügen → automatischer Test
4. ⚠️ Neue Keys brauchen oft 10-60 Min zur Aktivierung

#### Home Assistant (Smart Home)
1. Home Assistant öffnen → Profil (unten links)
2. **Sicherheit** → ganz runter scrollen
3. **Long-Lived Access Tokens** → "Token erstellen"
4. Namen eingeben (z.B. "Mein Agent") → OK
5. Token kopieren (wird nur EINMAL angezeigt!)
6. Im Wizard URL + Token eingeben → Verbindungstest

#### Google Kalender
- Läuft automatisch über Home Assistant (falls HA konfiguriert)
- Kein Extra-Setup nötig

### Schritt 5: Personalisierung
- Ziele, Gewohnheiten, Kontakte eintragen
- Lebensphase wählen
- Zusätzliche Infos über dich (wird für Personalisierung genutzt)

### Schritt 6: Kennenlerngespräch
- Kurzer Chat mit dem Agenten (wenn OpenRouter-Key vorhanden)
- Der Agent stellt 5-8 Fragen zum Kennenlernen

### Schritt 7: Speichern & Kosten-Übersicht
- Der Wizard zeigt eine **Kosten-Schätzung** basierend auf deinen Modellen
- Erstellt: `config.yaml`, `.env`, `deploy/seed_data.py`

## 4. Agent starten

```bash
python -m src.main

Erste Ausgabe sieht etwa so aus:

[INFO] Loading configuration...
[INFO] Database initialized
[INFO] Starting scheduler...
[INFO] Bot started. Waiting for messages...

5. Erste Schritte mit dem Bot

  1. Öffne deinen Bot in Telegram
  2. Sende /start
  3. Sende /hilfe für die Befehlsübersicht
  4. Probiere: Wie ist das Wetter? oder Erstelle eine Aufgabe: Einkaufen

Troubleshooting

"Bot antwortet nicht"

  • Prüfe ob python -m src.main läuft
  • Prüfe .env auf korrekten TELEGRAM_BOT_TOKEN
  • Prüfe ob du die richtige User-ID in ALLOWED_TELEGRAM_USER_ID hast
  • Bot in Telegram blockiert? → Entblocken + /start senden

"OpenRouter Fehler 401"

  • API-Key in .env prüfen (OPENROUTER_API_KEY)
  • Key auf openrouter.ai/keys überprüfen
  • Guthaben prüfen (auch kostenlose Modelle brauchen minimales Guthaben)

"Home Assistant nicht erreichbar"

  • URL prüfen (mit http:// und Port :8123)
  • Token prüfen (in HA unter Profil → Sicherheit)
  • Firewall: Port 8123 muss offen sein
  • HA und Agent laufen auf demselben Rechner? → http://localhost:8123

"Wetter funktioniert nicht"

  • Neuer API-Key? → bis zu 60 Min warten
  • Key auf openweathermap.org im Dashboard prüfen

Setup Wizard neu starten

# Fortschritt löschen und neu starten
rm data/.setup_progress.json  # Linux/Mac
del data\.setup_progress.json  # Windows
python setup_wizard.py

Deployment

Home Assistant OS Add-on

Für Home Assistant OS ist das Add-on der saubere Autostart-Weg. Es läuft als Supervisor-verwalteter Container und startet automatisch mit Home Assistant OS.

  1. Home Assistant → Einstellungen → Add-ons → Add-on Store
  2. Custom repository hinzufügen: https://github.com/DevOpsOfChaos/personal-ai-platform
  3. Add-on Personal AI Agent installieren
  4. Optionen ausfüllen:
    • telegram_bot_token
    • openrouter_api_key
    • telegram_user_id
    • optional ha_long_lived_token
  5. Start on boot aktivieren und Add-on starten

Secrets werden nur als Add-on-Optionen gespeichert. Sie gehören nicht in Git und werden nicht gepusht.

Details: ADDON.md

Systemd Service (Linux)

sudo cp deploy/pai-agent.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now pai-agent
sudo systemctl status pai-agent

Autostart (Windows)

Task Scheduler → Neue Aufgabe → Trigger: Bei Anmeldung → Aktion: python -m src.main

Nächste Schritte