Technische Architektur und Design-Entscheidungen.
┌──────────────────────────────────────────────────────┐
│ Telegram Nutzer │
└──────────────────────┬───────────────────────────────┘
│ Nachricht
▼
┌──────────────────────────────────────────────────────┐
│ 🔒 SECURITY LAYER — src/security/ │
│ ┌────────────────┐ ┌────────────────────────────┐ │
│ │ input_sanitizer │ │ prompt_injection_check │ │
│ │ Ctrl-Chars │ │ 11 Regex-Patterns │ │
│ │ 4000-Char-Limit │ │ PII-Detection │ │
│ │ SSRF-Validation │ │ System/User-Trennung │ │
│ └────────┬───────┘ └─────────────┬──────────────┘ │
│ └────────────┬───────────┘ │
│ ▼ │
├──────────────────────────────────────────────────────┤
│ src/telegram/ │
│ ┌──────────┐ ┌────────┐ ┌──────────────────────┐ │
│ │ auth.py │ │ bot.py │ │ handlers/ (23) │ │
│ │ User-ID │ │ PTB │ │ help, sleep, tasks, │ │
│ │ check │ │ Setup │ │ goals, health, │ │
│ │ │ │ │ │ feedback, timer, │ │
│ │ contact_ │ │ conv. │ │ workout, budget, │ │
│ │ chat.py │ │ engine │ │ gmail, settings ... │ │
│ └──────────┘ └────────┘ └──────┬───────────────┘ │
│ ┌────────────────────────────────┴────────────────┐ │
│ │ router.py — Regex-First Intent Router │ │
│ │ ~60% per Regex erkannt → direkte Antwort │ │
│ │ ~40% → intent_fallback.py → LLM │ │
│ └──────────────────────┬──────────────────────────┘ │
└─────────────────────────┼────────────────────────────┘
│
┌───────────┴───────────┐
▼ ▼
┌─────────────────────┐ ┌──────────────────────────────┐
│ src/llm/ │ │ src/services/ │
│ ┌────────────────┐ │ │ ┌────────────────────────┐ │
│ │ client.py │ │ │ │ briefing.py │ │
│ │ OpenRouter API │ │ │ │ sleep_tracker.py │ │
│ ├────────────────┤ │ │ │ goal_manager.py │ │
│ │ tool_registry │ │ │ │ health_tracker.py │ │
│ │ (70+ Tools) │ │ │ │ meal_planner.py │ │
│ ├────────────────┤ │ │ │ sport_planner.py │ │
│ │ tool_executor │ │ │ │ memory.py │ │
│ ├────────────────┤ │ │ │ contact_service.py │ │
│ │ intent_parser │ │ │ │ plant_service.py │ │
│ ├────────────────┤ │ │ │ timer_service.py │ │
│ │ cache.py │ │ │ │ appointment_coord.py │ │
│ │ cost.py │ │ │ │ decision_helper.py │ │
│ └────────────────┘ │ │ │ mood_journal.py │ │
└─────────────────────┘ │ │ streak_tracker.py │ │
│ │ bill_tracker.py │ │
│ │ medication_tracker.py │ │
│ │ grocery_list.py │ │
│ │ location_context.py │ │
│ │ task_prioritizer.py │ │
│ │ task_templates.py │ │
│ │ finance_helper.py │ │
│ │ goals.py │ │
│ │ health_digest.py │ │
│ │ contact_messaging.py │ │
│ └────────────────────────┘ │
│ │
│ src/integrations/ (20) │
│ ┌────────────────────────┐ │
│ │ weather.py │ │
│ │ home_assistant.py │ │
│ │ calendar.py │ │
│ │ web_search.py │ │
│ │ wikipedia_tool.py │ │
│ │ apple_health.py │ │
│ │ gmail_client.py │ │
│ │ whatsapp_client.py │ │
│ │ ha_alexa.py │ │
│ │ ha_buttons.py │ │
│ │ ha_events.py │ │
│ │ ha_sensors.py │ │
│ │ calendar_google.py │ │
│ │ calendar_ics.py │ │
│ │ calendar_oauth.py │ │
│ │ google_oauth.py │ │
│ │ gmail_oauth.py │ │
│ └────────────────────────┘ │
│ │
│ src/tools/ (12 Module) │
│ ┌────────────────────────┐ │
│ │ reminders · tasks │ │
│ │ health · contacts │ │
│ │ plants · alexa │ │
│ │ settings · ha │ │
│ │ workout · presence │ │
│ │ smart_button · calendar │ │
│ └────────────────────────┘ │
└──────────────────────────────┘
┌─────────────────────┐
│ src/scheduler/ │ ┌──────────────────────────────┐
│ ┌────────────────┐ │ │ src/intelligence/ (20+) │
│ │ engine.py │ │ │ adaptive_briefing.py │
│ │ (APScheduler) │ │ │ adaptive_routines.py │
│ ├────────────────┤ │ │ conversation_starter.py │
│ │ jobs/ (27) │ │ │ insight_engine.py │
│ │ morning, │ │ │ proactive.py │
│ │ evening, │ │ │ self_improve.py │
│ │ daytime, │ │ │ sleep_analyzer.py │
│ │ sleep, │ │ │ summarizer.py │
│ │ plants, │ │ │ workflow.py │
│ │ timer, ... │ │ │ sleep_conversation.py │
│ └────────────────┘ │ │ daytime_assistant.py │
└─────────────────────┘ │ │ tomorrow_prep.py │
│ │ vacation_manager.py │
┌─────────────────────┐ │ │ workout_analyzer.py │
│ src/learning/ (7) │ │ │ context_engine.py │
│ pattern_tracker.py │ │ │ habit_stacker.py │
│ knowledge_graph.py │ │ │ presence_detector.py │
│ preference_learner │ │ │ appointment_conversation.py│
│ prompt_optimizer.py │ │ │ plant_conversation.py │
│ prompt_rules.py │ │ │ training_triggers.py │
│ reinforcement.py │ │ │ ha_learner.py │
│ dynamic_knowledge │ │ └──────────────────────────────┘
└─────────────────────┘ │
│ src/webhooks/
│ ┌────────────────────────┐ │
│ │ apple_health.py │ │
│ └────────────────────────┘ │
│ │
┌──────────────────────────────┐
│ 🔒 src/scripts/ │
│ ┌────────────────────────┐ │
│ │ engine.py │ │
│ │ (Script-Sandbox) │ │
│ │ Timeout 30s │ │
│ │ No-Network │ │
│ │ Path-Restriction │ │
│ ├────────────────────────┤ │
│ │ builtin/ (21) │ │
│ └────────────────────────┘ │
└──────────────────────────────┘
┌──────────────────────────────┐
│ src/database/ │
┌──────────────────────────┐ SQLAlchemy 2.0 Models │
│ 🔒 src/system/ │ 15+ Tabellen: │
│ ┌────────────────────┐ │ user_profile, tasks, │
│ │ rate_limiter.py │ │ reminders, habits, │
│ │ 30 msg/min │ │ notes, sleep_logs, │
│ │ 50 LLM/h · 10 web/h│ │ agent_memory, contacts, │
│ ├────────────────────┤ │ plants, medications, ... │
│ │ error_recovery.py │ │ └──────────────────────────┘
│ │ health.py │ │
│ └────────────────────┘ │
│ ← vor allen externen │
│ API-Calls │
└──────────────────────────┘
│ 🔒 src/security/
│ ┌────────────────────┐
│ │ input_sanitizer.py │
│ │ contact_filter.py │
│ └────────────────────┘
- bot.py: python-telegram-bot Setup, Application Factory
- auth.py: User-ID Validierung (nur erlaubte Nutzer)
- router.py: Nachrichten-Routing (Regex → Handler → LLM-Fallback)
- handlers/: 23 spezialisierte Handler
- conversation_engine.py: Multi-Turn-Konversationen
- contact_chat.py: Genehmigungspflichtige Nachrichten an Kontakte
- custom_messages.py: Benutzerdefinierte Nachrichtenvorlagen
- Services (24): Business-Logik (Schlaf, Ziele, Gesundheit, Memory, Kontakte, Pflanzen, Timer, Termine, Mahlzeiten, Medikamente, Finanzen, Stimmung, Standort)
- Tools (12 Module): LLM-Tool-Implementierungen (Produktivität, Gesundheit, Smart Home, Kontakte, Pflanzen, Alexa, Präsenz, Buttons, Kalender, Workout, Einstellungen)
- LLM: OpenRouter-Client, Tool-Registry/Executor, Intent-Parser
- 20 Module: Externe APIs — Wetter, HA, Kalender (Multi-Provider), Web, Wikipedia, Apple Health, Gmail (OAuth), WhatsApp, HA-Erweiterungen (Alexa, Buttons, Events, Sensoren)
- Webhooks:
src/webhooks/— Apple Health Webhook-Endpoint
- Intelligence (20+): Insights, Summarizer, Workflow, Proaktivität, Adaptive Routinen, Schlaf-Coach, Tages-Assistent, Abend-Routine, Terminplanung, Pflanzen-Coach, Präsenz-Detection, Kontext-Engine, Urlaubs-Manager, Training-Trigger, Workout-Analyse, Morgen-Vorbereitung, HA-Lerner
- Learning (7): Pattern Tracking, Knowledge Graph, Preference Learning, Prompt Optimization, Prompt Rules, Reinforcement, Dynamic Knowledge
- Scheduler: 27 periodische Jobs (Morgen/Abend/Tag-Routinen, Schlaf-Assistent, Pflanzen-Erinnerungen, Timer-Dispatcher, Gesundheits-Digest, Urlaubs-Relay, Daten-Bereinigung u.v.m.)
- Scripts: 21 eingebaute Abläufe (inkl. Daten-Export/Import, Abend-Reflexion, Morgen-Routine)
- Database: SQLAlchemy 2.0 async, SQLite (15+ Tabellen)
- System: Rate Limiter, Error Recovery, Health Checks
- Cache: State Cache, Entity Cache, LLM Response Cache
- Security: Input Sanitizer (Prompt Injection Detection), Contact Communication Filter
Warum: 60% der Nutzereingaben sind vorhersehbar (Schlaf-Phrasen, Check-in-Antworten, einfache Befehle). Diese per Regex abzufangen spart LLM-Kosten und Latenz.
# router.py — Prioritäts-Reihenfolge
1. Exakte Befehle: /start, /hilfe, /today
2. Regex-Phrasen: "Gehe schlafen", "Bin aufgewacht"
3. LLM Intent-Parser: Alles andere → OpenRouter- cheap_model: Schnelle, einfache Antworten (~80% der LLM-Calls)
- strong_model: Analysen, Zusammenfassungen (~15%)
- reasoning_model: Komplexe Denk-Aufgaben (~5%)
Alle I/O-Operationen sind asynchron:
aiohttpfür HTTP (Telegram, OpenRouter, HA, Wetter)aiosqlitefür Datenbank-Zugriffeapschedulermit AsyncIO-Executor
Jedes Modul exportiert über __init__.py eine saubere öffentliche API:
# src/llm/__init__.py
from .client import LLMClient
from .tool_registry import get_all_tools
from .tool_executor import ToolExecutorDer Agent funktioniert auch bei Teilausfällen:
- Home Assistant offline → HA-Tools geben "nicht verfügbar" zurück
- Wetter-API down → Briefing ohne Wetter
- OpenRouter down → Nur Regex-Erkennung funktioniert
SQLite mit 15+ Tabellen:
| Tabelle | Zweck |
|---|---|
user_profile |
Key-Value Store für Nutzer-Einstellungen |
user_goals |
Ziele mit Status und Fortschritt |
user_habits |
Gewohnheiten mit Frequenz und Streaks |
tasks |
Aufgaben mit Priorität und Deadline |
reminders |
Erinnerungen mit Zeit und Status |
notes |
Notizen mit Kategorie |
sleep_logs |
Schlaf-Einträge (Dauer, Qualität) |
health_logs |
Symptome, Energie, Mahlzeiten |
workout_logs |
Trainings-Einträge |
agent_memory |
KI-Gedächtnis (Fakten, Beobachtungen) |
mood_entries |
Stimmungs-Tracking |
budget_entries |
Ausgaben-Tracking |
checkin_logs |
Proaktive Check-in Antworten |
contacts |
Kontakte mit Geburtstagen und Beziehungen |
plants |
Pflanzen mit Gieß-Intervallen und Standorten |
medications |
Medikamente mit Einnahme-Zeitplan |
Zwei Ebenen:
- config.yaml: Nicht-geheime Einstellungen (Modelle, Intervalle, Features)
- .env: Secrets (Tokens, Keys) — via
${VAR}in config.yaml referenziert
# config.yaml
telegram:
bot_token: ${TELEGRAM_BOT_TOKEN} # aus .env
llm:
cheap_model: deepseek/deepseek-chat| Paket | Version | Verwendung |
|---|---|---|
python-telegram-bot |
21.x | Telegram Bot Framework |
sqlalchemy[asyncio] |
2.0.x | ORM + async DB |
aiohttp |
3.x | Async HTTP Client |
apscheduler |
3.x | Job Scheduling |
httpx |
0.28.x | HTTP Client (OpenRouter) |
openai |
1.x | OpenAI-kompatible API (OpenRouter) |
structlog |
24.x | Strukturiertes Logging |
pyyaml |
6.x | YAML Config Parsing |
aiosqlite |
0.20.x | Async SQLite Driver |