Skip to content

README.md

Latest commit

 

History

History
177 lines (132 loc) · 9.28 KB

README.md

File metadata and controls

177 lines (132 loc) · 9.28 KB
Raw

KI-Koch-Assistent 🍳

Ein sprachgesteuerter KI-Küchenassistent für Tablet und Desktop – powered by Google Gemini.

Author: Dr. Andreas Gotter, Aachen, Germany
License: MIT
GitHub: Andy1977D/Koch-Assistent

Executive Summary

Der KI-Koch-Assistent ist eine sprachgesteuerte, Tablet-optimierte Webanwendung für die Küche. Er ermöglicht es, freihändig durch persönliche Rezepte zu navigieren, Zutaten abzufragen und sich Schritt für Schritt durch den Kochprozess führen zu lassen – komplett über natürliche Sprache.

Was macht der Kochassistent?

  • Sprachsteuerung & -ausgabe: Hört auf Kommandos, beantwortet Fragen und liest Rezeptschritte sowie Zutaten laut vor.
  • Intelligente Rezeptvorschläge: Findet passende Rezepte basierend auf vorhandenen Zutaten oder spontanen Wünschen.
  • Dynamische Portionsskalierung: Rechnet Zutatenmengen automatisch und intelligent auf die gewünschte Personenzahl um.
  • Schritt-für-Schritt-Navigation: Führt im eigenen Tempo durch die Zubereitung – man kann jederzeit vor- und zurückspringen oder sich Dinge wiederholen lassen.
  • Timer mit Alarm: Stellt automatisch Küchentimer, wenn ein Rezeptschritt eine Wartezeit enthält.
  • Hands-Free-Betrieb: Speziell entwickelt, um das Tablet während des Kochens mit schmutzigen Händen nicht berühren zu müssen.
  • Live-Modus: Echtzeit-Audio-Streaming über die Gemini Live API für ein natürliches Gesprächserlebnis.

Aufbau & Komponenten

Architektur

┌───────────────────────────────────────────────┐
│  Browser (Tablet/Desktop)                     │
│  index.html + app.js + style.css              │
│  ├── SpeechRecognition (Mikrofon-Input)        │
│  ├── SpeechSynthesis (TTS-Output)              │
│  ├── Gemini Live WebSocket (Echtzeit-Audio)    │
│  └── PWA / Fullscreen-Modus                    │
└──────────────┬────────────────────────────────┘
               │ HTTP (Port 8077)
┌──────────────▼────────────────────────────────┐
│  server.py (ThreadedHTTPServer)                │
│  ├── /api/chat    → Gemini Chat                │
│  ├── /api/reset   → Session zurücksetzen       │
│  ├── /api/feedback → Rezept-Feedback           │
│  ├── /api/live-config → Live-API-Konfiguration │
│  ├── /api/token   → Ephemeral Token            │
│  └── static/      → Frontend-Dateien           │
└──────────────┬────────────────────────────────┘
               │ HTTPS (google-genai SDK)
┌──────────────▼────────────────────────────────┐
│  Google Gemini / Gemma API                     │
│  Modell konfigurierbar via .env                │
└───────────────────────────────────────────────┘

Warum diese Komponenten?

  • Frontend (HTML/JS/CSS): Eine PWA-fähige (Progressive Web App) Benutzeroberfläche. Nutzt die systemeigene Web Speech API (SpeechRecognition & SpeechSynthesis) für Spracheingabe und -ausgabe – keine externen Abhängigkeiten, kein Framework-Overhead. Ein Tablet-optimiertes Dark-Theme schont die Augen und den Akku.
  • Backend (Python): Ein leichtgewichtiger, blockierungsfreier HTTP-Server (server.py). Python wurde gewählt, weil das google-genai SDK hervorragend unterstützt wird und der Server bewusst minimalistisch gehalten ist – keine Datenbank, kein Docker, keine komplexe Infrastruktur.
  • KI-Integration (Gemini / Gemma): Das KI-Modell analysiert die Nutzeranfragen, verarbeitet den Rezeptkontext und steuert das Frontend über eine strukturierte JSON-API. Mehrere Modelle sind konfigurierbar, mit automatischer Fallback-Kette.
  • Lokale Rezeptdatenbank (JSON): Rezepte liegen als strukturierte JSON-Dateien im Ordner Rezepte_JSON/. Dadurch bleibt alles lokal, versionierbar und leicht zu bearbeiten – ohne externe Datenbank.

How to use? (Typischer Dialog)

Der Assistent ist darauf ausgelegt, natürliche Gespräche zu führen. Ein typischer Ablauf sieht so aus:

  1. Start & Auswahl:
    „Ich habe noch Äpfel und Mehl da, was kann ich backen?"
    → Der Assistent schlägt z. B. einen Apfelkuchen vor und zeigt die Rezeptkarte.

  2. Portionen anpassen:
    „Rechne das Rezept bitte auf 4 Personen hoch."
    → Die Zutatenliste wird automatisch umgerechnet und im Panel aktualisiert.

  3. Zutaten-Check:
    „Was brauche ich für den Teig?"
    → Der Assistent listet die Zutaten auf. Auf dem Bildschirm können diese abgehakt werden.

  4. Kochen / Backen:
    „Lass uns anfangen."
    → Der Assistent liest den ersten Schritt vor (z. B. „Heize den Ofen auf 180 Grad vor").

  5. Navigation & Rückfragen:
    „Weiter", „Nochmal wiederholen" oder Zwischenfragen wie „Wie viel Mehl brauchte ich noch gleich?"
    → Man kann jederzeit vor- und zurückspringen, ohne den Faden zu verlieren.

  6. Timer:
    „Der Kuchen ist jetzt im Ofen."
    → Der Assistent erkennt die Backzeit aus dem Rezept und startet automatisch einen Timer mit Alarm.

Installation & Setup

Voraussetzungen

Schritte

# 1. Repository klonen
git clone https://github.com/Andy1977D/Koch-Assistent.git
cd Koch-Assistent

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

# 3. API-Key konfigurieren
# Erstelle eine Datei .env mit folgendem Inhalt:
#   GEMINI_API_KEY=dein_api_key_hier
#   GEMINI_MODEL=gemma-4-31b-it

# 4. Server starten
python -u server.py

Der Server läuft dann auf http://localhost:8077.

Hinweis zu start_koch_assistent.bat

Die enthaltene Batch-Datei start_koch_assistent.bat ist ein Beispiel-Startskript für Windows. Sie enthält einen hardcodierten Pfad (c:\python\RezeptServer), der auf den eigenen Installationspfad angepasst werden muss. Alternativ kann der Server einfach mit python -u server.py gestartet werden.

Zugriff von Tablet / Smartphone

Für den Zugriff von anderen Geräten im lokalen Netzwerk bietet der Server unter /setup eine Setup-Seite mit Anleitungen für Android (Chrome-Flag) und iOS (Zertifikat) an.

Die Beispielrezepte

Dem Projekt liegen 28 erprobte Beispielrezepte bei, um den Einstieg zu erleichtern. Der Fokus liegt auf vollwertigen, oft pflanzlichen Rezepten – darunter:

Kategorie Beispiele
🍰 Kuchen & Süßes Veganer Apfelkuchen (versch. Varianten), Schoko-Kirsch-Kuchen, Mohnkuchen, Pflaumenkuchen, Chia-Schoko-Pudding
🥗 Salate & Suppen Italienischer Bohnensalat, Süßkartoffel-Karotten-Suppe, Blumenkohl-Suppe
🍝 Hauptgerichte Tomatenlasagne, Nudelauflauf, Vegane Quiche
🍛 Curries Süßkartoffel-Curry, Bananencurry, Mandarinen-Rosinen-Curry, Blumenkohl-Rosinen-Curry
🫕 Pfannenzauber-Serie 8 Einzelkomponenten (Suppe, Quinoa, Soja-Medaillons, Soßen, Dressings, Krokant, Dessert)

Jedes Rezept enthält neben den Metadaten detailliert strukturierte Zutatenlisten (ggf. unterteilt in Sektionen wie „Teig", „Belag") und klare Schritt-für-Schritt-Anweisungen.

Eigene Lieblingsrezepte erstellen

Das Hinzufügen eigener Rezepte ist einfach: Eine JSON-Datei im Ordner Rezepte_JSON/ ablegen – fertig.

Manuell

Orientiere dich an den bestehenden Rezepten. Die wichtigsten Felder:

  • name, kurzbeschreibung, typ, portionen, quelle
  • zutaten: Array aus Strings oder Gruppen-Objekten mit gruppe und zutaten_liste
  • zubereitungsanleitung: Array von Strings (ein Eintrag pro Schritt)

KI-basiert (empfohlen)

Am schnellsten geht es mit einem LLM wie ChatGPT oder der Google Gemini App. Kopiere einfach folgenden Prompt und füge Dein Rezept ein:

Bitte wandle das folgende Rezept in ein strukturiertes JSON-Format für meinen Koch-Assistenten um.

Anforderungen an das JSON:
- Felder: "name", "kurzbeschreibung", "typ" (Array von Strings, z.B. ["Kuchen", "Vegan"]),
  "portionen" (Zahl), "quelle", "fertiges_gericht_bild" (Dateiname oder null),
  "handschriftliche_anmerkungen" (Array von Strings).
- "zutaten": Ein Array. Einfache Zutaten sind Strings (z.B. "200 g Mehl").
  Für Gruppen verwende Objekte: {"gruppe": "Teig", "zutaten_liste": ["200 g Mehl", "100 g Zucker"]}.
- "zubereitungsanleitung": Ein Array von Strings. Jeder String ist ein Arbeitsschritt.
  Formuliere die Schritte klar und knapp – sie werden dem Nutzer vorgelesen.

Hier ist mein Rezept:
[FÜGE HIER DEIN REZEPT ODER EINEN LINK ZUM REZEPT EIN]

Speichere das generierte JSON als z. B. 22_mein_rezept.json im Ordner Rezepte_JSON/ und starte den Server neu.

Lizenz

Dieses Projekt steht unter der MIT-Lizenz – frei nutzbar für private Zwecke.