Hugging Face's logo

maxkru92
/
mama-bot

Model card Files
xet
 Community

🤖 Mama Bot – Persönlicher KI-Assistent für ältere Personen

Ein liebevoller, geduldiger WhatsApp-Bot für eine ältere Privatperson (55–65 Jahre). Läuft kostenlos auf Hugging Face Spaces mit Hugging Face Inference API.

📋 Inhaltsverzeichnis

  1. Architektur-Übersicht
  2. Kostenübersicht
  3. Deployment auf Hugging Face Spaces
  4. WhatsApp-Anbindung
  5. Konfiguration
  6. Funktionen
  7. Keep-Alive: Space wach halten
  8. Monitoring
  9. Erweiterung
  10. Bekannte Limitierungen

🏗️ Architektur-Übersicht 

┌─────────────────────────────────────────────────────────────┐
│                   Hugging Face Space                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │   FastAPI     │  │  Scheduler   │  │  Memory (JSON)   │  │
│  │   Webhook     │  │  (Morgen,    │  │  user_profile    │  │
│  │   Handler     │  │   Check-in)  │  │  topics_sent     │  │
│  └──────┬───────┘  └──────┬───────┘  └──────────────────┘  │
│         │                  │                                  │
│         └────────┬─────────┘                                  │
│                  │                                            │
│         ┌────────▼────────┐                                  │
│         │  HF Inference   │  ← kostenlos, kein API-Key      │
│         │  API (Mistral)  │    nötig für öffentliche Spaces  │
│         └─────────────────┘                                  │
└─────────────────────────────────────────────────────────────┘
           │                              ▲
           │ WhatsApp-Nachrichten         │ Antworten
           ▼                              │
┌──────────────────────┐       ┌──────────┴─────────┐
│   WAHA Container     │       │   WhatsApp-App      │
│   (WhatsApp HTTP     │──────▶│   auf dem Handy     │
│    API, selbst-      │       │   der Person        │
│    gehostet)         │       └─────────────────────┘
└──────────────────────┘

Warum Hugging Face Spaces?

Kriterium HF Spaces Railway Oracle Cloud
Kosten 0 € 0 € (5 $/Monat Credit) 0 € (Free Tier)
RAM 16 GB 8 GB 1 GB (ARM: 24 GB)
CPU 2 vCPU 1 vCPU 1-4 vCPU
Speicher 50 GB 1 GB 50 GB
Docker ✅ ✅ ✅
Einfachheit ⭐⭐⭐⭐⭐ ⭐⭐⭐⭐ ⭐⭐⭐
Inference API ✅ (kostenlos) ❌ ❌

Empfehlung: Hugging Face Spaces – einfachste Einrichtung, kostenlose Inference API, genug Rechenpower.

Warum Hugging Face Inference API?

  • Kostenlos – kein API-Key nötig auf öffentlichen Spaces
  • Deutsch – Mistral 7B versteht und spricht exzellent Deutsch
  • Schnell – keine Warteliste, sofort verfügbar
  • Datenschutz – Daten bleiben innerhalb der HF-Infrastruktur

Warum WAHA für WhatsApp?

Option Kosten Business-Account Einfachheit
WAHA 0 € (selbst-gehostet) ❌ nicht nötig ⭐⭐⭐⭐
Green API 0 € (Developer Tier) ❌ nicht nötig ⭐⭐⭐⭐⭐
Meta WABA 0 € (1.000 Gespräche/Monat) ✅ nötig ⭐⭐⭐

Empfehlung: Green API für den Einstieg (einfachste Einrichtung), WAHA für volle Kontrolle.

💰 Kostenübersicht

Komponente Kosten Bemerkung
Hugging Face Space 0 € Free Tier, Docker-basiert
HF Inference API 0 € Auf Spaces inkludiert
Green API 0 € Developer Tier: 100 Nachrichten/Tag
WAHA (selbst-gehostet) 0 € Läuft im gleichen Space oder VPS
Gesamt 0 €/Monat 🎉

🚀 Deployment auf Hugging Face Spaces

Schritt 1: Hugging Face Account erstellen

  1. Gehe zu huggingface.co
  2. Klicke auf "Sign Up" und erstelle einen kostenlosen Account
  3. Bestätige deine E-Mail-Adresse

Schritt 2: Neuen Space erstellen

  1. Klicke auf dein Profil → "New Space"
  2. Einstellungen:
    • Name: mama-bot
    • License: MIT
    • Space SDK: Docker
    • Visibility: Public (für kostenlose Inference API)
    • Hardware: CPU Basic (kostenlos)
  3. Klicke auf "Create Space"

Schritt 3: Dateien hochladen

Option A: Über die Web-Oberfläche

  1. Gehe zu deinem neuen Space
  2. Klicke auf "Files" → "Upload files"
  3. Lade alle Dateien hoch:
    • app.py
    • scheduler.py
    • bot_config.py
    • requirements.txt
    • Dockerfile
    • topics/italy.json
    • topics/tenerife.json
    • topics/recipes.json
    • topics/travel_nature.json
    • memory/user_profile.json

Option B: Über Git (empfohlen)

# Auf deinem lokalen Rechner
cd /Users/maximiliankrupp/Documents/mama-bot

# Git initialisieren
git init
git add .
git commit -m "Initial commit - Mama Bot"

# Remote hinzufügen (ersetze <dein-username>)
git remote add origin https://huggingface.co/spaces/<dein-username>/mama-bot

# Hochladen
git push -u origin main

Schritt 4: Secrets konfigurieren

  1. Gehe zu deinem Space → "Settings" → "Repository secrets"
  2. Füge folgende Secrets hinzu:
Secret Name Wert Beschreibung
HF_TOKEN hf_xxxxx Hugging Face API Token (optional für öffentliche Spaces)
USER_NAME Maria Name der Person
USER_PHONE 491711234567 WhatsApp-Nummer (mit Ländervorwahl, ohne +)
MORNING_HOUR 8 Uhrzeit für Morgennachrichten
MORNING_MINUTE 0 Minute für Morgennachrichten
CHECKIN_DAYS 3 Tage ohne Kontakt bis Check-in
  1. Klicke auf "Save"

Schritt 5: Space starten

  1. Gehe zu "Settings" → "Container"
  2. Klicke auf "Restart Space"
  3. Warte 2-3 Minuten bis der Space gestartet ist
  4. Prüfe unter "Logs" ob alles läuft

Schritt 6: Webhook-URL notieren

Die Webhook-URL ist:

https://<dein-username>-mama-bot.hf.space/webhook

Du brauchst sie für die WhatsApp-Konfiguration.

📱 WhatsApp-Anbindung

Option A: Green API (empfohlen für Einstieg)

  1. Gehe zu green-api.com

  2. Erstelle einen kostenlosen Developer-Account

  3. Erstelle eine neue Instanz (Instance)

  4. Scanne den QR-Code mit der WhatsApp-App der Person

  5. Notiere:

    • idInstance
    • apiTokenInstance

  6. Webhook einrichten:

    • Gehe zu deiner Instanz → "Settings"
    • Setze Webhook URL: https://<dein-username>-mama-bot.hf.space/webhook
    • Aktiviere: "incomingMessageReceived"

Option B: WAHA (selbst-gehostet)

Für VPS oder lokale Installation:

# WAHA starten
docker run -d \
  --name waha \
  -p 3000:3000 \
  -e WHATSAPP_HOOK_URL=https://<dein-username>-mama-bot.hf.space/webhook \
  -e WHATSAPP_HOOK_EVENTS=messages \
  devlikeapro/waha:latest

# QR-Code anzeigen (zum Scannen mit WhatsApp)
docker logs waha

Scanne den QR-Code mit der WhatsApp-App der Person.

⚙️ Konfiguration

Umgebungsvariablen

Variable Standard Beschreibung
HF_TOKEN "" Hugging Face API Token
HF_MODEL mistralai/Mistral-7B-Instruct-v0.3 Modell für Inference API
USER_NAME Liebe/r Nutzer/in Name der Person
USER_PHONE "" WhatsApp-Nummer
MORNING_HOUR 8 Stunde für Morgennachrichten
MORNING_MINUTE 0 Minute für Morgennachrichten
CHECKIN_DAYS 3 Tage ohne Kontakt bis Check-in
WAHA_API_URL http://waha:3000 WAHA API URL
WAHA_API_KEY "" WAHA API Key

Benutzerprofil anpassen

Die Datei memory/user_profile.json enthält:

{
  "name": "Maria",
  "preferences": ["Italien", "Kochen", "Garten"],
  "concerns": ["Rente", "Gesundheit"],
  "phone_number": "491711234567",
  "topics_sent": [],
  "last_contact": null,
  "last_morning_message": null
}

Du kannst sie über die API aktualisieren:

curl -X PUT https://<dein-username>-mama-bot.hf.space/profile \
  -H "Content-Type: application/json" \
  -d '{"name": "Maria", "preferences": ["Italien", "Kochen"]}'

🎯 Funktionen

1. Automatische Morgennachrichten

  • Zeit: Täglich um 08:00 Uhr (konfigurierbar)
  • Rotation: 4 Themen-Kategorien, rotierend nach Wochentag
  • Anti-Wiederholung: Gesendete Themen werden getrackt
  • Montags: Zusätzliche Frage zum Wochenprogramm

2. Interaktiver Chat-Assistent

  • Normaler Chat: Freundliche, einfache Antworten
  • Notfall-Modus: Sofortige Telefonnummern und Schritt-für-Schritt-Anleitung
  • Behörden & Rente: Erklärungen in einfacher Sprache, Fristen, Beratungsstellen
  • Gesundheit & Pflege: Pflegegrad, MDK, Pflegegeld erklärt
  • Vergesslichkeits-Helper: Reminder-Funktion

3. Check-in System

  • Sendet eine sanfte Nachricht nach 3 Tagen ohne Kontakt
  • Konfigurierbar über CHECKIN_DAYS

4. Kontextuelles Gedächtnis

  • Speichert Name, Vorlieben, bekannte Probleme
  • Konversationshistorie der letzten 10 Nachrichten
  • Persistent in JSON-Dateien

🔄 Keep-Alive: Space wach halten

Problem: Hugging Face Free-Tier-Spaces schlafen nach 48 Stunden Inaktivität ein. Wenn der Space schläft, reagiert der Bot nicht mehr auf Nachrichten.

Lösung: Der Mama Bot hat einen doppelten Keep-Alive-Mechanismus:

A) Interner Self-Ping (automatisch ✅)

Der Bot pingt sich selbst alle 30 Minuten über einen internen Thread. Das kostet nichts und funktioniert sofort nach dem Deployment – keine Konfiguration nötig!

# Der Self-Ping Thread wird automatisch gestartet
# Pingt http://127.0.0.1:7860/keepalive alle 30 Minuten

B) Externer Ping (zusätzliche Sicherheit)

Für maximale Zuverlässigkeit kannst du einen kostenlosen externen Service einrichten:

Option 1: cron-job.org (empfohlen)

  1. Gehe zu cron-job.org
  2. Erstelle einen kostenlosen Account
  3. Klicke auf "Cronjobs erstellen"
  4. Einstellungen:
    • URL: https://<dein-username>-mama-bot.hf.space/keepalive
    • Intervall: Alle 30 Minuten
    • Name: Mama Bot Keep-Alive
  5. Speichern – fertig!

Option 2: UptimeRobot

  1. Gehe zu uptimerobot.com
  2. Erstelle einen kostenlosen Account
  3. Klicke auf "Add New Monitor"
  4. Einstellungen:
    • Monitor Type: HTTP(s)
    • URL: https://<dein-username>-mama-bot.hf.space/ping
    • Monitoring Interval: 5 Minuten
  5. Speichern – fertig!

Option 3: Freshping

  1. Gehe zu freshping.io
  2. Erstelle einen kostenlosen Account
  3. Füge eine neue URL hinzu:
    • URL: https://<dein-username>-mama-bot.hf.space/keepalive
    • Intervall: 1 Minute
  4. Speichern – fertig!

Keep-Alive Endpoints

Endpoint Zweck Antwort
/keepalive Vollständiger Keep-Alive mit Status {"status": "alive", ...}
/ping Einfacher Ping (UptimeRobot-kompatibel) pong
/health Detaillierter Health Check JSON mit allen Infos

Empfehlung

Der interne Self-Ping reicht in den meisten Fällen aus. Für maximale Sicherheit (z.B. wenn der Space mal neu startet) empfehle ich zusätzlich cron-job.org – das ist kostenlos und zuverlässig.

📊 Monitoring

Health Check 

# Prüfen ob der Bot läuft
curl https://<dein-username>-mama-bot.hf.space/

# Detaillierter Health Check
curl https://<dein-username>-mama-bot.hf.space/health

Logs anzeigen

  1. Gehe zu deinem Space → "Logs"
  2. Dort siehst du alle Ausgaben des Bots

Aktive Reminders prüfen 

curl https://<dein-username>-mama-bot.hf.space/reminders

Profil prüfen 

curl https://<dein-username>-mama-bot.hf.space/profile

🔧 Erweiterung

Neue Themen hinzufügen

Erstelle eine neue JSON-Datei im topics/ Verzeichnis:

{
  "topics": [
    {
      "id": "new_001",
      "content": "Dein hier der Inhalt...",
      "fun_fact": "Interessante Zusatzinfo"
    }
  ]
}

Trage das neue Thema in bot_config.py ein:

TOPICS = {
    ...
    "new_topic": {
        "file": "topics/new_topic.json",
        "emoji": "🌟",
        "name": "Neues Thema",
        "description": "Beschreibung"
    }
}

Neuen Intent hinzufügen

  1. Keywords in bot_config.py definieren
  2. Handler-Funktion in app.py erstellen
  3. In detect_intent() und webhook() einbinden

Neues Modell verwenden

Ändere die Umgebungsvariable:

HF_MODEL=mistralai/Mistral-7B-Instruct-v0.3

Empfohlene kostenlose Modelle:

  • mistralai/Mistral-7B-Instruct-v0.3 (beste Deutsch-Qualität)
  • Qwen/Qwen2.5-7B-Instruct (sehr gut für Deutsch)
  • microsoft/Phi-3-mini-4k-instruct (schnell)

⚠️ Bekannte Limitierungen & Workarungen

1. HF Spaces schläft ein

Problem: Free Tier Spaces schlafen nach 48 Stunden Inaktivität ein.

Workaround (implementiert ✅):

  • Interner Self-Ping: Der Bot pingt sich selbst alle 30 Minuten (automatisch, kein Setup nötig)
  • Externer Ping (optional): cron-job.org, UptimeRobot oder Freshping rufen /keepalive auf
  • Siehe Abschnitt Keep-Alive für Details

2. Inference API Latenz

Problem: Die erste Anfrage kann 5-10 Sekunden dauern (Cold Start).

Workaround:

  • Der Bot sendet sofort eine Bestätigung, dann die eigentliche Antwort
  • Für Notfall-Anworten wird kein LLM verwendet (statische Antworten)

3. Kein persistentes Dateisystem

Problem: HF Spaces hat kein persistentes Dateisystem (außer dem Git-Repo).

Workaround:

  • Alle Daten werden in JSON-Dateien im Repo gespeichert
  • Bei Neustart werden die Daten aus dem Git-Repo geladen
  • Für produktive Nutzung: Externen Storage (z.B. HF Datasets) anbinden

4. WhatsApp-Verbindung

Problem: WAHA/Green API benötigt eine aktive WhatsApp-Verbindung.

Workaround:

  • Regelmäßige Health-Checks der WAHA-Instanz
  • Automatische Neustarts bei Verbindungsverlust
  • Green API Developer Tier: 100 Nachrichten/Tag (reicht für Privatnutzung)

5. LLM-Antworten können ungenau sein

Problem: Sprachmodelle können halluzinieren.

Workaround:

  • Kritische Domains (Notfall, Behörden, Gesundheit) haben statische Antworten
  • Immer Haftungshinweise hinzufügen
  • System-Prompt mit klaren Grenzen

📄 Lizenz

MIT License – frei verwendbar und modifizierbar.

🙏 Dankeschön

Erstellt mit ❤️ für eine liebe Mama.

Krupp Capital Quantitative Desk – Precision in Chaos, Alpha in Variance

Downloads last month

-

Downloads are not tracked for this model. How to track
Inference Providers NEW
This model isn't deployed by any Inference Provider. 🙋 Ask for provider support