KI Tamagotchi (Android, Kotlin + Jetpack Compose)

Ein KI-Haustier fürs Handy: Byte, ein kleiner Cartoon-Roboter, der von dir lernt.

Funktionen

• Tamagotchi-Kern: Hunger, Energie, Laune, Wissen, XP/Level, 5 Entwicklungsstufen (Funke → Baby → Kind → Teen → Meister). Werte sinken in Echtzeit, auch bei geschlossener App (Nachrechnung aus Zeitstempeln). Krank bei Vernachlässigung, aber kein Tod.
• Aktionen: Füttern, Spielen (Mini-Spiel „Bit-Fangen“), Schlafen (Licht aus), Streicheln (auch durch Antippen), Gesund pflegen.
• KI: Beibringen (Fakt/Regel/Vorliebe, Byte bestätigt in eigenen Worten), Gedächtnis (Suche, Bearbeiten, Löschen), Chat (offline per Stichwortsuche oder mit einer OpenAI-kompatiblen API), „merk dir: …“ im Chat, Lernen aus Gewohnheiten.
• Datenschutz: API-Keys/Passwörter werden vor dem Speichern und vor dem Senden geschwärzt; der eigene API-Key liegt mit Android Keystore verschlüsselt auf dem Gerät.
• Benachrichtigungen über WorkManager (alle ~30 Min. Prüfung, höchstens alle 3 Std. eine Meldung).

Voraussetzungen

• JDK 17 (auch für Gradle in Android Studio einstellen).
• Android Studio mit Unterstützung für das Android-Gradle-Plugin aus gradle/libs.versions.toml.
• Android SDK: Plattform API 37 zum Kompilieren sowie die von Gradle benötigten Build-Tools. Die App läuft ab Android 8 / API 26, Zielplattform ist API 36.
• Internetzugriff beim ersten Build auf Google Maven, Maven Central, das Gradle Plugin Portal und die Gradle-Distribution. Robolectric lädt beim ersten Test zusätzlich Android-Testartefakte.

Ein API-Key, ein Emulator oder Signierschlüssel sind für Build und lokale JVM-Tests nicht erforderlich. Die App funktioniert standardmäßig offline.

Einrichtung und lokale Entwicklung

1. Repository herunterladen und das Projektverzeichnis in Android Studio öffnen.

2. JDK 17 als Gradle-JDK wählen und die SDK-Lizenzen im SDK Manager akzeptieren.

3. SDK-Pfad über ANDROID_HOME setzen oder eine nicht eingecheckte local.properties anlegen:

   sdk.dir=/absoluter/pfad/zum/Android/Sdk
   

4. Im Projektverzeichnis ausführen (unter Windows gradlew.bat verwenden):

   ./gradlew :app:assembleDebug
   ./gradlew :app:testDebugUnitTest
   ./gradlew :app:lintDebug
   

Die Debug-APK liegt unter app/build/outputs/apk/debug/app-debug.apk. Zum Starten ein Gerät oder einen Emulator ab API 26 auswählen und in Android Studio Run verwenden; alternativ:

adb install -r app/build/outputs/apk/debug/app-debug.apk
adb shell am start -n de.crypto.kitamagotchi/.MainActivity

Tests, Standards und der PR-Ablauf stehen in CONTRIBUTING.md.

Nutzung

• Haustier: Byte füttern, streicheln, schlafen lassen oder ein Mini-Spiel starten. Vernachlässigung verändert seine Werte auch bei geschlossener App.
• Beibringen: Zum Beispiel „Mein Hund heißt Bello“ als Fakt hinterlegen.
• Chat: „Wie heißt mein Hund?“ fragt das lokale Gedächtnis ab. „merk dir: Ich mag Pizza“ speichert eine neue Erinnerung.
• Gedächtnis: Erinnerungen suchen, korrigieren oder löschen.
• Einstellungen: Name und Benachrichtigungen ändern. Für Online-Antworten optional „KI-Antworten nutzen“ aktivieren, Basis-URL, Modell und eigenen API-Key eintragen, Verbindung testen und Speichern wählen.

Für eine OpenAI-kompatible API beispielsweise https://api.openai.com/v1 als Basis-URL verwenden. Der Client ergänzt /chat/completions; eine vollständige Endpoint-URL ist ebenfalls möglich. Modell und Berechtigungen müssen zum Anbieter passen. Bei API-Fehlern antwortet der Chat weiterhin offline.

Datenschutz und Zugangsdaten

• Der API-Key wird lokal mit AES-GCM und einem Schlüssel aus dem Android Keystore verschlüsselt. Automatische Android-App-Backups sind deaktiviert.
• Erinnerungen und Chatverlauf liegen in einer nicht zusätzlich verschlüsselten Room-Datenbank im privaten App-Speicher; Zustand und Einstellungen in DataStore. Der Verlauf wird auf die neuesten 200 Nachrichten begrenzt.
• Bei aktiviertem Online-Modus gehen der aktuelle Text, bis zu zehn vorherige Chatnachrichten, relevante Erinnerungen sowie Haustierzustand/Gewohnheiten an den konfigurierten Anbieter. Dessen Datenschutz- und Kostenregeln gelten zusätzlich.
• Bekannte Geheimnismuster werden vor dem Speichern von Nutzereingaben und vor API-Anfragen geschwärzt. Das ist keine Garantie, alle sensiblen Inhalte zu erkennen: keine echten Passwörter oder vertraulichen Daten in Chats eingeben.
• Nur vertrauenswürdige HTTPS-Endpunkte verwenden. API-Keys ausschließlich im Key-Feld eintragen, nie in URLs, Quellcode, Screenshots oder Issues.
• HTTP-Fehler zeigen nur den Statuscode, nicht den möglicherweise sensiblen Antwortinhalt. Weiterleitungen werden nicht automatisch verfolgt: direkt die endgültige Endpoint-URL konfigurieren.
• Lokale Ollama-/LM-Studio-Server benötigen einen vom Gerät erreichbaren, vertrauenswürdigen HTTPS-Zugang. Android blockiert Klartext-HTTP standardmäßig; diese Schutzmaßnahme nicht für Produktionsbuilds abschalten. localhost auf einem Gerät bezeichnet nicht den Entwicklungsrechner.

Architektur

Ein Gradle-Modul app, Paket de.crypto.kitamagotchi:

Bereich unter app/src/main/java/de/crypto/kitamagotchi/	Verantwortung
core/	Android-unabhängige Spiellogik (PetEngine, PetState), Gewohnheiten, Stichwortsuche, Offline-Antworten und Schwärzung
data/	Room-Datenbank für Erinnerungen/Chat, Migration 1 → 2, DataStore und Keystore-Zugriff
ai/	OpenAI-kompatibler HTTP-Client mit Zeitlimits und Schwärzung ausgehender Texte
ui/	Compose-Oberflächen, Animationen und PetViewModel als Verbindung zwischen Logik und Persistenz
work/	Periodische Zustandsprüfung und Benachrichtigungen mit WorkManager
widget/	Android-Startbildschirm-Widget

Compose beobachtet StateFlows aus dem ViewModel. Aktionen gehen durch die Spiellogik und werden anschließend gespeichert. Zeitstempel erlauben die Nachrechnung des Zustands, ohne einen permanenten Hintergrunddienst zu betreiben.

Tests und CI

# Gezielte Logiktests
./gradlew :app:testDebugUnitTest --tests 'de.crypto.kitamagotchi.core.*'

# Netzwerkvertrags- und Datenbanktests ohne externe API
./gradlew :app:testDebugUnitTest \
  --tests 'de.crypto.kitamagotchi.ai.LlmClientTest' \
  --tests 'de.crypto.kitamagotchi.data.ChatHistoryTest'

# Gesamte lokale Validierung
./gradlew :app:lintDebug :app:testDebugUnitTest :app:assembleDebug --continue

🧠 Internes KI-Gehirn (v0.3.0)

• Gehirn-Modus in den Einstellungen: Extern (API) · Intern auf dem Gerät · Automatisch (API → internes Modell → Regel-Gehirn).
• Internes Modell: MediaPipe LLM Inference (com.google.mediapipe:tasks-genai:0.10.35). Standard-Download: Qwen2.5-0.5B-Instruct q8 (~520 MB, Apache-2.0, ohne Login) von huggingface.co/litert-community/Qwen2.5-0.5B-Instruct. Eigene .task-Modelle (z. B. Gemma 3 1B int4, dort Login/Lizenz nötig) per Dateiauswahl importierbar. Gespeichert im App-Ordner, löschbar. Benötigt arm64 und ≥ 3 GB RAM, sonst automatischer Rückfall aufs Regel-Gehirn.
• Regel-Gehirn (immer offline): Intent-Erkennung, Synonyme, kombinierte Erinnerungen, Stimme je Stufe/Stimmung, lernt automatisch Fakten aus dem Chat („Ich heiße …“, „Ich mag …“, „Mein … ist …“).
• APK ist jetzt nur für arm64-v8a gebaut. JUnit prüft Spiellogik, Suche und Schwärzung. Robolectric prüft SQLite-Migration, Chat-Persistenz, den API-Vertrag mit einem lokalen HTTP-Testserver und Compose-Render-Smoke-Tests. Diese Tests benötigen keinen echten API-Key und keine Anbieteranfragen. Die Render-Tests erzeugen app/build/screens/*.png zur Sichtprüfung; sie sind keine pixelgenauen Golden-Tests. Die Bilder in docs/ sind separat gepflegte Vorschauen und werden nicht automatisch überschrieben.

Auf PRs und Pushes nach main prüft CI Whitespace, Android Lint, Tests und Build. Testergebnisse und Render-Bilder sind sieben Tage als validation-reports verfügbar. Lokale Berichte: app/build/reports/tests/testDebugUnitTest/ und app/build/reports/lint-results-debug.html.

Der Security-Workflow analysiert Kotlin mit CodeQL auf PRs, auf main und wöchentlich. Auf vertrauenswürdigen Runs (nicht auf PRs) wird der aufgelöste Gradle-Abhängigkeitsgraph für Dependabot übermittelt. Dependabot prüft wöchentlich Gradle-Abhängigkeiten und GitHub Actions. Repository-Verantwortliche müssen Dependency graph, Dependabot alerts und ggf. Code scanning in den GitHub-Einstellungen aktivieren; private Repositories benötigen dafür die entsprechende GitHub-Lizenz. Bei eigener CodeQL-Konfiguration das Default-Setup deaktivieren, damit die Setups nicht konkurrieren.

Fehlerbehebung

Problem	Prüfen / Lösung
SDK location not found	ANDROID_HOME oder sdk.dir in der lokalen local.properties korrigieren.
Fehlende SDK-Plattform / Lizenzen	API 37 und benötigte Build-Tools im SDK Manager installieren; sdkmanager --licenses ausführen.
Plugin/Abhängigkeit nicht auflösbar	Netzwerk, DNS und Proxy für die oben genannten Repositories prüfen; genaue Versionen im Versionskatalog prüfen. Nicht willkürlich Toolchain-Versionen herabsetzen.
Falsche Java-Version	java -version, JAVA_HOME und das Gradle-JDK in Android Studio auf JDK 17 abstimmen.
Erster Robolectric-Test schlägt beim Download fehl	Internet-/Proxy-Zugriff für Maven-Artefakte prüfen und den Test erneut starten.
HTTP 401/403	API-Key, Modellfreigabe und Anbieterberechtigungen prüfen; keinen Key in Fehlerberichte kopieren.
HTTP 3xx/404 oder Klartext-Fehler	Endgültigen HTTPS-Endpoint mit korrektem /v1-Pfad konfigurieren; Weiterleitungen werden abgelehnt.
Keine Benachrichtigungen	In-App-Schalter und Android-Berechtigung prüfen. WorkManager läuft nicht minutengenau; Batteriesparfunktionen können verzögern.
API-Key nach Gerätewechsel nicht nutzbar	Neu eingeben: Keystore-Schlüssel sind gerätegebunden.