Communitygithub.com

V4TIME/V4SKILL

Erstelle Flask AI-Apps in Termux mit NaraRouter-Integration.

Was ist V4SKILL?

Diese Fähigkeit (Skill) ermöglicht es dir, eine lokale Webanwendung mit Python/Flask auf einem Android-Gerät mit Termux zu erstellen und auszuführen. Sie integriert dabei AI-APIs, insbesondere NaraRouter, und optional Hermes Agent als Reasoning-Backend. Der Skill bietet detaillierte Anleitungen für den schnellen Start, API-Integrationsmuster (NaraRouter, NVIDIA NIM) und eine Architektur, bei der das Web-App als Interface und Hermes Agent als 'Gehirn' fungiert. Die Beschreibung enthält konkrete Codebeispiele, Debugging-Strategien und Designpräferenzen für ein minimales, professionelles Erscheinungsbild ohne KI-generierten Look. Besonderer Wert wird auf die Verwendung von stdlib urllib anstelle von requests gelegt, um Zeitüberschreitungen bei der Installation in Termux zu vermeiden. Der Skill ist für Termux auf Android optimiert und behandelt Themen wie Port-Konflikte, Pip-Installations-Timeouts und die Sicherung von Daten durch GitHub-Backups. Einzigartig ist die Betonung auf Beschreibungsbasiertem Routing zwischen mehreren APIs und die explizite Anweisung, vor der Installation von Paketen den Benutzer zu fragen und keine Sicherheitsvorträge zu halten.

Funktioniert mit✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/V4TIME/V4SKILL/tree/HEAD/termux-flask

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Lokale KI-Web-App in Termux

Erstelle und betreibe eine lokale Webanwendung auf einem Android-Gerät mit Termux, die KI-APIs (insbesondere NaraRouter) und optional Hermes Agent als Reasoning-Backend integriert.

Wann verwenden

  • Benutzer möchte eine lokale KI-Assistenten/Chat-Oberfläche auf dem Telefon
  • Erstellen einer Web-App in Termux mit Python/Flask
  • Integration mehrerer KI-APIs mit beschreibungsbasiertem Routing
  • Hinzufügen von Sprachmodus über die Web Speech API des Browsers
  • Verwaltung von Sitzungen und Speicher über Chats hinweg
  • Benutzer fügt Installationsanweisungen für ein Entwicklerwerkzeug (Binary-Release, Rust/cargo, npm/npx, pip) ein und sagt, es zu installieren und zu verwenden – bewerten Sie zuerst die Machbarkeit für die Telefon-/Termux-Umgebung, dann installieren Sie mit Erlaubnis

Architekturmuster

Browser (Chrome auf Android) → Flask-Backend (Termux) → KI-API(s)
                                 ↓
                             Hermes Agent (optional, als Gehirn)

Schlüsselprinzip: Die Web-App ist die Schnittstellenschicht. Hermes Agent (falls verwendet) ist das Gehirn. Das Flask-Backend verbindet sie.

Schnellstart

# In Termux
mkdir ~/sayip && cd ~/sayip
mkdir -p templates static/css static/js storage/sessions
# app.py — minimaler Flask-Starter
from flask import Flask, render_template, request, jsonify
from pathlib import Path
import json, time, uuid, os

app = Flask(__name__, template_folder="templates")
HERMES_HOME = Path(os.path.expanduser("~/.hermes"))
SAYIP_STORAGE = Path(os.path.expanduser("~/sayip/storage"))

@app.route("/")
def index():
    return render_template("chat.html")

@app.route("/api/chat", methods=["POST"])
def chat():
    data = request.get_json()
    # ... Nachricht verarbeiten, API aufrufen, Antwort zurückgeben

if __name__ == "__main__":
    app.run(host="127.0.0.1", port=5000)
# Ausführen
python3 app.py
# Öffnen in Chrome: http://127.0.0.1:5000

API-Integrationsmuster

NaraRouter (primäre Empfehlung)

NaraRouter ist ein einheitliches KI-Gateway mit 53+ Modellen, kostenlose Stufe verfügbar.

Schlüsselformat: sk-nry-... (beginnt mit sk-nry-)

Endpunkte (alle unter derselben Basis-URL + Bearer-Key):

EndpunktTypVerwendung für
https://router.bynara.id/v1/chat/completionsOpenAI-kompatibelChat, allgemeine Aufgaben
https://router.bynara.id/v1/messagesAnthropic-kompatibelAnthropic-Format-Anfragen
https://router.bynara.id/v1/responsesOpenAI ResponsesZustandsbehaftete Antworten-API
https://router.bynara.id/v1/embeddingsOpenAI EmbeddingsVektor-Embeddings
https://router.bynara.id/v1/modelsLISTEVerfügbare Modelle für Ihren Plan abrufen
https://api-images.bynara.id/v1/images/generationsBildgenText-zu-Bild
https://api-images.bynara.id/v1/images/editsBildbearbeitungBildbearbeitung

Testen Sie einen Schlüssel vor der Verwendung:

curl -s -X POST https://router.bynara.id/v1/chat/completions \
  -H "Authorization: Bearer sk-nry-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"agnes-2.5-flash","messages":[{"role":"user","content":"hi"}],"max_tokens":10}'

Bekannte funktionierende Free-Tier-Modelle: agnes-2.5-flash, agnes-2.0-flash

Überprüfen Sie die Modelle Ihres Plans:

curl -s https://router.bynara.id/v1/models \
  -H "Authorization: Bearer sk-nry-YOUR_KEY" | python3 -c "import sys,json; [print(m['id']) for m in json.load(sys.stdin).get('data',[])]"

WICHTIG: Nicht alle 53 Modelle sind in jedem Plan enthalten. deepseek-v4-pro-0813-bynara erfordert Credits. deepseek-v4-flash-free ist möglicherweise nicht enthalten. Testen Sie immer vor der Konfiguration.

NVIDIA NIM API (integrate.api.nvidia.com/v1)

NVIDIA NIM bietet 82+ Modelle über einen einzigen OpenAI-kompatiblen Endpunkt. Basis-URL: https://integrate.api.nvidia.com/v1 Endpunkt: https://integrate.api.nvidia.com/v1/chat/completions Schlüsselformat: nvapi- (z.B. nvapi-_qJeGmEP...)

Testen Sie einen Schlüssel vor der Verwendung:

curl -s -X POST https://integrate.api.nvidia.com/v1/chat/completions \
  -H "Authorization: Bearer nvapi-..." \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"model":"nvidia/nemotron-3.5-lightning-30b-a3b","messages":[{"role":"user","content":"hi"}],"max_tokens":10,"stream":true}'

Bekannte funktionierende Free-Tier-Modelle (getestet auf Termux-Mobilfunknetz):

Modell-IDSchlüsselStatusHinweise
nvidia/nemotron-3.5-lightning-30b-a3bnvapi-...FunktioniertSchnell (~5-7s für Einfaches), starke Argumentation, unterstützt Denkmodus. Am zuverlässigsten auf Mobilgeräten.
gpt-oss-20bnvapi-...FunktioniertOpenAI-kompatibel
deepseek-ai/deepseek-v4-pro-0813nvapi-...Timeout-RisikoFunktioniert auf dem Desktop, bei Termux-Mobilfunknetz häufig Timeout
moonshotai/kimi-k3nvapi-...Timeout-RisikoVision-fähig, aber Timeout im Mobilfunknetz

Warnung zur Schlüsselasymmetrie: Nicht alle Modelle sind auf allen Schlüsseln verfügbar. Schlüssel 1 (nvapi-_qJeGmEP...) hat breiteren Zugriff. Schlüssel 2 (nvapi-WDb7Rr...) ist eingeschränkter – einige Modelle geben 404 zurück. Testen Sie ein Modell immer mit einem bestimmten Schlüssel, bevor Sie es konfigurieren.

Anzeichen für einen toten Schlüssel:

  • 401 Unauthorized — Schlüssel ungültig/abgelaufen
  • 404 Not Found bei einem Modell — Modell nicht auf diesem Konto/Schlüssel
  • Verbindungs-Timeout (30s+) — API langsam/vom Netzwerk nicht erreichbar
  • Teamorouter sk-teamo-... Schlüssel → insufficient_balance auf OpenAI-Endpunkt (https://api.teamorouter.com/v1); Modell wird auf Anthropic-Endpunkt (https://api.teamorouter.com) nicht unterstützt. Tot. Stellt deepseek-v4-pro-free Modell bereit, aber ohne Guthaben nicht nutzbar.

Siehe references/nvidia-api.md für vollständige Details: modellspezifische Python-Muster (Nemotron Denkmodus, DeepSeek Nicht-Streaming, Kimi Vision multimodal), Streaming reasoning_content Extraktion, thread-basiertes hartes Timeout-Muster für urllib und Vision-Payload-Format.

API-Dispatch-Engine

Wenn Sie mehrere APIs konfiguriert haben, erstellen Sie einen Dispatcher, der:

  1. Die Aufgabe klassifiziert (Mathe, Codierung, Wissenschaft, Allgemein)
  2. Die beste API basierend auf dem Beschreibungstext auswählt
  3. Die API aufruft und das Ergebnis zurückgibt
  4. Auf andere APIs zurückfällt, wenn die erste fehlschlägt

Siehe references/nararouter-api.md für Integrationsdetails.

Verwenden Sie stdlib urllib, nicht requests

In Termux kann pip install requests bei großen Downloads zu Timeouts führen. Verwenden Sie stattdessen Python's stdlib urllib – es ist immer verfügbar und verarbeitet JSON-APIs problemlos:

import urllib.request, json

def call_api(url, payload, api_key):
    data = json.dumps(payload).encode()
    headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
    req = urllib.request.Request(url, data=data, headers=headers, method="POST")
    with urllib.request.urlopen(req, timeout=30) as resp:
        return json.loads(resp.read())

Designpräferenzen (benutzerspezifisch)

Minimales, professionelles, nicht KI-generiertes Aussehen:

  • Dunkles Design, enge Abstände, keine Farbverläufe, keine dekorativen Schatten
  • Monospace-Schriftarten wo angebracht (Code, API-Schlüssel, Zeitstempel)
  • Einfache Rechtecke für Chat-Bläschen – keine abgerundeten Ecken, es sei denn, sie sind funktional
  • Seitenleiste = einfache Liste, keine Symbole, es sei denn, sie sind sinnvoll
  • Suchen Sie nach Referenzimplementierungen, anstatt Designs von Grund auf neu zu generieren
  • Entfernen Sie im Zweifelsfall Funktionen, anstatt sie hinzuzufügen

Konkrete Anti-Patterns – diese lassen eine Web-App wie KI-generiert aussehen, entfernen Sie sie:

  • Emojis in jeder Überschrift/Kachel/Schaltfläche (🤖, ⚙, 🎭, 🔌, 🧠, 💬, 🎤) — entfernen. Nur einfache Textbeschriftungen.
  • Akzent-Glow / Box-Schatten bei Hover (box-shadow: 0 0 12px var(--accent-glow)) — entfernen. Nur flache Farben.
  • Bounce / Pulse / Slide-Down Keyframe-Animationen (@keyframes bounce, @keyframes pulse, @keyframes slideDown) — entfernen. Keine Bewegungsgestaltung.
  • Splash-Screen-Begrüßungskarte mit Symbolen (.welcome-screen mit welcome-icon, welcome-hints Raster) — durch einen einzeiligen Eingabeplatzhalter im Eingabebereich ersetzen.
  • Dekoratives Markensymbol neben dem Logo (.brand-icon mit Emoji) — entfernen.
  • Bänder, Abzeichen, Statuspunkte, die den Header dekorieren (.health-badge, .health-dot) — entfernen oder rein funktional gestalten.
  • Verlaufs-Hintergründe, Glas-Effekte, durchscheinende Überlagerungen — niemals.

Faustregel: Öffnen Sie die Seite im Browser und fragen Sie sich: „Würde ein menschlicher Entwickler dieses CSS für ein Dienstprogramm von Hand schreiben?“ Wenn die Antwort Nein ist (weil es Bewegung, Leuchten oder Emoji-Dekoration enthält), entfernen Sie es. Ein normales Tool sieht aus wie ein Terminal, eine Notizen-App oder ein minimalistischer Chat – nicht wie eine Landing Page.

Sprachmodus:

  • Verwenden Sie die Web Speech API (SpeechRecognition + SpeechSynthesis) – kostenlos, browserintegriert
  • Umschaltknopf zum Wechseln zwischen Text-/Sprachmodus
  • Im Sprachmodus: Mikrofon hört kontinuierlich zu, Sprache→Text→Senden, Antwort→Sprechen
  • Die Sprachqualität ist auf das beschränkt, was Chrome auf Android bietet – versprechen Sie keine „Ultron-Stimme“

Workflow-Präferenzen (benutzerspezifisch)

Vor der Installation von Paketen fragen: Bevor Sie pip install oder apt install ausführen, fragen Sie zuerst den Benutzer. Dies ist nicht verhandelbar.

Fortschritt kontinuierlich anzeigen: Wenn eine Aufgabe länger als ein paar Minuten dauert, zeigen Sie Zwischenergebnisse an. Verschwinden Sie nicht für längere Zeit ohne Ausgabe. Wenn Sie bei etwas feststecken, sagen Sie es und teilen Sie mit, was Sie versuchen.

Keine Sicherheitsvorträge: Der Benutzer versteht die Risiken von API-Schlüsseln. Halten Sie keine Vorträge über Schlüsselsicherheit, Offenlegung oder Best Practices, es sei denn, Sie werden ausdrücklich danach gefragt. Sie haben bei Bedarf ihre eigene Erklärung geliefert.

Funktionierende Lösungen bevorzugen statt perfekter Architektur: Bringen Sie zuerst etwas zum Laufen. Der NaraRouter-Schlüsseltest hat dies gezeigt – testen Sie den Schlüssel, finden Sie ein funktionierendes Modell, konfigurieren Sie es. Planen Sie nicht zu viel.

Speicher ist flüchtig – frühzeitig auf GitHub sichern: Auf Termux/Android kann der App-Speicher (~/sayip/storage/) bei Serverneustart, Termux-Neustart oder Geräteneustart gelöscht werden. Nach Einrichtung der API-Schlüssel und Konfiguration übertragen Sie das Projekt sofort per SSH in ein GitHub-Repository, damit die Konfiguration wiederhergestellt werden kann. Gehen Sie in der Sitzung nicht davon aus, dass storage/ einen Neustart überlebt – überprüfen Sie es nach jedem Neustart erneut. Der SSH-über-Port-443-Trick (siehe references/termux-git-ssh.md) wird oft benötigt, da Mobilfunknetze Port 22 blockieren.

Der Sprachmodus muss vor der Fertigmeldung Ende-zu-Ende getestet werden: Die Web Speech API-Verkabelung in chat.js (setupVoice, startListening, speakText) ist nicht dasselbe wie ein funktionierender Sprachmodus. Testen Sie, indem Sie tatsächlich in das Telefonmikrofon sprechen und die Antwort zurückhören. Chrome auf Android ist der Zielbrowser – das ist wichtig, nicht Desktop-Chrome.

Fehlerbehebung

Port 5000 bereits belegt:

fuser -k 5000/tcp  # Töte, was immer auf Port 5000 läuft
# Oder mit ss prüfen:
ss -tlnp | grep 5000

Flask-App startet nicht / stürzt ab:

  • Syntax prüfen: python3 -c "import py_compile; py_compile.compile('app.py', doraise=True)"
  • Prüfen, ob Port vor dem Start frei ist
  • Mit timeout 15 python3 app.py ausführen, um Startausgabe zu sehen, ohne zu blockieren

API gibt 401/403/payment_required zurück:

  • Der Schlüssel ist möglicherweise ungültig, abgelaufen oder das Modell ist nicht in Ihrem Plan enthalten
  • Testen Sie den Schlüssel direkt mit curl, bevor Sie ihn in der App konfigurieren
  • Überprüfen Sie /v1/models, um zu sehen, welche Modelle Ihr Plan tatsächlich enthält

Pip-Installations-Timeouts:

  • Termux auf Mobilgeräten kann für große Pakete langsame/unzuverlässige Netzwerke haben
  • Verwenden Sie nach Möglichkeit stdlib-Alternativen (urllib statt requests)
  • Falls Installation erforderlich, verwenden Sie pip3 install --timeout 30 <Paket> für schnellen Fehlschlag

Durch Force-Kill beendete Hintergrund-Flask-Prozesse halten den Port kurzzeitig:

  • Nach pkill -9 -f "[p]ython3 app.py" 2-3s warten, bevor Sie neu starten.
  • Wenn Sie "Address already in use" erhalten, hat der alte Prozess den Socket noch nicht vollständig freigegeben – länger warten.

Vor dem Neustart des Flask-Servers, um Codeänderungen zu übernehmen, zuerst den alten Prozess beenden:

  • Muster: pkill -9 -f "[p]ython3 app.py" && sleep 3 && cd ~/sayip && python3 app.py &
  • Das Überspringen des Kill-Befehls verursacht "Address already in use", und die neue Instanz startet nicht.
  • Überprüfen Sie nach dem Neustart immer mit curl -s --max-time 3 http://127.0.0.1:5000/api/health.

Wenn der Benutzer meldet, dass die Web-App defekt / JS fehlerhaft / nicht funktioniert ist, diagnostizieren Sie in dieser Reihenfolge:

  1. Bestätigen Sie, dass der Server läuft: curl -s --max-time 3 http://127.0.0.1:5000/api/health
  2. Überprüfen Sie, dass statische Dateien 200 liefern: curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:5000/static/style.css (und app.js, chat.js, voice.js, settings.js)
  3. Überprüfen Sie, welches HTML der Server tatsächlich ausliefert: curl -s http://127.0.0.1:5000/ | grep -E 'static/|style.css|app.js|chat.js|voice.js' – bestätigt, dass die Pfade im HTML mit dem übereinstimmen, was Flask ausliefert
  4. Wenn statische Dateien 404 zurückgeben, aber die HTML-Links relative Pfade wie style.css anstelle von /static/style.css anzeigen, ist das der Fehler – patchen Sie beide Templates, um das /static/-Präfix zu verwenden
  5. Lesen Sie die JS-Dateien und überprüfen Sie jeden document.querySelector / getElementById / .querySelector-Aufruf gegen das, was das HTML tatsächlich enthält – ein fehlendes Element stürzt das gesamte Skript ab
  6. Prüfen Sie auf Nullreferenz-Abstürze: el("hamburger") auf einer Seite ohne Hamburger-Element, messagesEl.querySelector(".wrap") wenn .wrap nicht existiert, document.querySelector(".composer .wrap") wenn .composer nicht existiert – diese stürzen das IIFE ab und legen das gesamte JS der Seite lahm
  7. Schützen Sie Element-Lookups: var el = document.querySelector(selector); if (!el) return; vor der Verwendung des Ergebnisses

Überprüfen Sie Frontend-Fixes nach jeder HTML/Template-Bearbeitung, indem Sie prüfen, was der Server tatsächlich ausliefert:

  • Ein curl auf die Seiten-URL und grep nach dem statischen Pfad (/static/style.css, /static/js/app.js) bestätigt, dass der Fix angekommen ist.
  • Ein curl direkt auf die statische Datei-URL mit -o /dev/null -w '%{http_code}' bestätigt, dass sie 200 liefert.
  • Gehen Sie nicht davon aus, dass eine HTML-Bearbeitung live ist, bis beide Prüfungen gegen den laufenden Server bestanden sind.

Die häufigste Ursache für „alles JS defekt“ in diesem Projekt:

  • HTML-Templates verwenden relative statische Pfade (style.css, app.js, chat.js) anstelle des Flask-/static/-Präfixes (/static/style.css, /static/js/app.js, /static/js/chat.js).
  • Der Browser fordert http://127.0.0.1:5000/style.css an → 404. Kein CSS, kein JS geladen → Seite ist ungestylt und funktionslos.
  • Fix: Patchen Sie beide Templates, um das /static/-Präfix in allen statischen Datei-Links zu verwenden.

Wenn der Benutzer fragt, warum die Seitenleiste nach dem Bearbeiten leer ist:

  • Die Seitenleiste (Chat-Verlaufsliste) wird durch einen separaten API-Aufruf (/api/conversations) nach dem Laden der Seite befüllt.
  • Wenn sie leer ist, liegt das Problem wahrscheinlich nicht im Template, sondern darin, dass ein JS-Fehler den API-Aufruf blockiert hat.
  • Fix: Öffnen Sie die Browser-Konsole und suchen Sie nach JS-Fehlern. Beheben Sie den zuerst auftretenden Fehler – die Seitenleiste wird dann normal geladen.

Wenn Fehler in der Chat-Antwort: „Object Object“ erscheint:

  • Das passiert, wenn JavaScript versucht, ein Objekt als Zeichenfolge zu rendern.
  • Wahrscheinliche Ursache: Die API-Antwort wurde nicht korrekt analysiert. Zum Beispiel: data.choices[0].message.content abrufen, wenn data bereits content ist.
  • Fix: Fügen Sie console.log('API-Antwort:', JSON.stringify(data, null, 2)) vor der Verarbeitung hinzu, um das tatsächliche Format zu sehen.

Referenzen

  • references/nararouter-api.md – NaraRouter-API-Details (Dispatch-Engine, Beschreibungen, Schlüsselverwaltung)
  • references/nvidia-api.md – NVIDIA NIM API-Details (Modellmuster, Timeout, multimodale Nutzung)
  • references/termux-git-ssh.md – SSH über Port 443 für GitHub in Termux
  • references/chat-html.md – Chat-HTML-Vorlage mit geteiltem Layout, lateralem Design, Sitzungsverwaltung, Einstellungen und Sprachmodus

Individual skills in this repo

This repo contains 12 individual skills — each has its own dedicated page.

Verwandte Skills