ARIA-AGENT/docs/plan-local-llm-router.md

Plan B — Lokaler LLM-Router (Gamebox) neben Claude

Ziel: „Gemini-Feeling" für den Alltag, ohne die Claude-Max-Subscription aufzugeben. Ein schnelles lokales LLM beantwortet die einfachen ~80 % der Turns in <1 s; nur die schweren 20 % (Tiefe, Code, Tools, Pentest, langer Kontext) gehen an Claude. Claude bleibt das Tiefen-Hirn.

Warum das der einzige realistische Weg zu „live" ist

Gemessen (10.07.2026): CLI-Round-trip über den Claude-Max-Proxy hat einen harten Boden von ~3,5 s (Subprozess-Start pro Turn). Streaming-API würde das brechen, kostet aber API-Geld → verliert die Max-Subscription. Ein lokales LLM für die einfachen Turns umgeht den 3,5-s-Boden komplett und ist gratis (läuft auf vorhandener Gamebox-GPU). Echtes Speech-to-Speech-Duplex (Gemini Live nativ) ist mit einem Text-Modell als Hirn prinzipiell nicht drin.

Modell & Serving (entschieden)

• Modell: Qwen3 8B, GGUF Q4_K_M (~6 GB). Bestes Tool-Calling der 7/8B- Klasse, solides Deutsch, Apache-2.0. Alt.: Mistral Small 3 7B (schneller, weniger Tool-Calling).
• Serving: llama.cpp llama-server im Docker-Container auf der Gamebox (kein Ollama nötig — nativer OpenAI-kompatibler /v1/chat/completions).
• VRAM-Budget: 12-GB-Karte, Whisper-small (~1–2 GB) + F5-TTS (~1–2 GB) → ~8–9 GB frei → passt. (FLUX ist auf 12 GB eh raus.)

Anbindung: über den RVS, wie TTS/STT (kein IP-Pflegen)

Die Gamebox ist ein anderer Host als das Brain. Statt direktem HTTP (IP/Port/ Firewall) läuft das LLM über den RVS-Token-Room, exakt wie Whisper/F5-TTS:

• llama.cpp hört nur auf localhost der Gamebox.
• Ein dünner RVS-Adapter daneben (Vorbild: whisper-/xtts-Bridge) verbindet sich mit dem RVS-Token, lauscht auf llm_request, ruft lokal llama-server, schickt llm_response (korreliert per requestId) zurück.
• rvs/server.js ALLOWED_TYPES um llm_request, llm_response und (Phase 2) llm_partial erweitern.
• Das Brain bekommt einen zweiten „Proxy" — nur über RVS statt direktem HTTP.

Router-Logik im Brain

Reihenfolge pro Turn (früh raus = schnell):

• Tier 0 — Fast-Path (existiert): reine Steuerbefehle (Spotify, Licht) → Skill direkt, kein LLM. <1 s.
• Tier 1 — Lokal (Qwen3): einfache Konversation, kurze Fakten, Smalltalk, Bestätigungen. Ziel <1 s.
• Tier 2 — Claude: tief/technisch, Code, Tool-Use nötig, Pentest-Projekt, langer/komplexer Kontext.

Routing-Signal (heuristisch zuerst, deterministisch & schnell): Nachrichtenlänge, Schlüsselwörter, ob ein Tool nötig scheint, Projekt-Kontext (Pentest-Projekt → immer Claude), Konversationstiefe.

Escalation statt perfekter Vorab-Klassifikation: Das lokale Modell bekommt die Anweisung, bei Unsicherheit oder Tool-Bedarf NICHT zu raten, sondern zu eskalieren (z.B. Antwort <<ESCALATE>>). Das Brain routet den Turn dann an Claude. So sind Fehlklassifikationen billig — lieber einmal lokal→Claude als eine falsche lokale Antwort.

Modus „Nur lokales LLM" (Diagnostic-Checkbox, Eval-Schalter): Ein Flag localLlmOnly (in Diagnostic setzbar, vom Brain beim Routen gelesen). Ist es an: JEDER Turn geht ans lokale LLM, <<ESCALATE>> / „zu schwer" werden ignoriert (kein Claude-Fallback) — damit Stefan die echte Staerke/Schwaeche des lokalen Modells sieht, ohne dass Claude die schweren Turns rettet. Haken aus = normale Heuristik + Escalation. Ehrlicher Hinweis: im Nur-lokal-Modus funktionieren werkzeug-abhaengige Turns (Wetter, Timer, Memory, Bild) nicht — das lokale Tier hat keine Tools; das ist ein Gespraechs-Eval-Modus, kein Voll-ARIA. Fast-Path (Spotify etc.) laeuft davon unberuehrt weiter.

Persona auf BEIDEN Modellen

Das lokale Modell braucht ARIAs Identität, sonst bricht es aus der Rolle (gelernt aus dem --system-prompt-Debakel). Aber schlanker:

• IDENTITY_SEED + Kern-Persona: ja.
• Volles Memory / ALLE Skill-Schemas: nein — nur eine kuratierte, kleine Tool-Auswahl (siehe unten). Haelt den lokalen Prompt klein → schnell.
• Persona kommt lokal auch als echter System-Prompt (llama.cpp system-Rolle).

Tool-Calling lokal (kuratierte Auswahl)

Das lokale LLM DARF Werkzeuge nutzen (Qwen3 = natives OpenAI-Tool-Calling, von llama.cpp --jinja unterstuetzt). Ablauf wie bei Claude: Brain schickt messages + tools → Qwen antwortet mit tool_calls → Brain fuehrt via _dispatch_tool aus → Ergebnis zurueck → finale Antwort. Tool-Loop im Brain, Ziel = lokales LLM statt Claude-Proxy.

Awareness ≠ Authority. Das lokale Modell soll WISSEN, was ARIA alles kann (damit es gezielt eskaliert statt zu halluzinieren), aber nicht alles ausfuehren.

Harte Grenze = Kontext/VRAM, nicht Misstrauen. Das volle Tool-Schema sind ~15-20 K Tokens. Qwens Kontext steht auf 8 K (LLM_CTX=8192) — es passt nicht rein. Hochdrehen auf 32 K kostet mehrere GB KV-Cache extra → OOM auf der geteilten 12-GB-3060 (Whisper + F5-TTS liegen mit drauf). Claude im RZ hat 200 K-1 M Kontext und ist zuverlaessig → kann sich das ganze Arsenal leisten; das lokale 8B auf Heim-Hardware nicht. Andere Hardware-Klasse, anderes Budget.

Design (gibt „im Bilde" ohne VRAM zu sprengen):

• Ausfuehrbar lokal: kleiner, risikoarmer Start-Satz — Wetter, Uhrzeit, memory_search (lesen), trigger_timer, Spotify-Steuerung, Licht/Smart-Home.
• Awareness-Liste (billig, ~paar hundert Tokens im System-Prompt): kurze Aufzaehlung des Rests — „ARIA kann ausserdem: Skills bauen, OAuth, Projekte, Bilder, ins Gedaechtnis schreiben — dafuer <<ESCALATE>>." Kein volles Schema.
• Bleibt bei Claude (Authority): skill_create/update/delete, oauth_*, project_*, flux_generate, memory_save.

Escalation-Netz bleibt: braucht ein Turn ein Tool, das lokal nicht ausfuehrbar ist → <<ESCALATE>> → Claude mit vollem Arsenal. Der „Nur lokales LLM"-Haken dient dazu, spaeter datengetrieben zu messen, ob der ausfuehrbare Satz erweitert werden kann.

Implementierung (B1): Adapter reicht tools an llama.cpp + gibt tool_calls zurueck; Bridge schleust beides durch (llm_request/llm_response); Brain-Tool-Loop mit Ziel lokal.

Phasen

• B0 — Infra: llama.cpp-Container + RVS-Adapter auf der Gamebox, ALLOWED_TYPES, local_llm_chat() im Brain. Isoliert testen („sag hallo").
• B1 — Router + lokale Tools: Heuristik Tier-1/2 + Escalation, schlanke Persona lokal, kuratierte Tool-Auswahl lokal (Adapter/Bridge/Brain-Tool- Loop, siehe oben) + „Nur lokales LLM"-Checkbox. Einfache Turns → lokal. Messen: Trefferquote, Tool-Zuverlaessigkeit & Latenz.
• B2 — Streaming/Voice: llm_partial → TTS beginnt beim ersten Satz → der „live"-Sprung. Hier den Gong-/Ohr-Re-Arm-Bug mit-fixen (Barge-In, sauberes Re-Listen).
• B3 (optional): lokalen Tool-Satz erweitern, sobald Qwen sich als zuverlaessig erweist (z.B. memory_save).

Offene Entscheidungen (für Stefan)

1. Modell: Qwen3 8B (Tool-Calling) — oder doch Mistral Small 3 7B (Speed)?
2. Routing v1: rein heuristisch + Escalation (entschieden).
3. Tools lokal: kuratierte kleine Auswahl (entschieden — Start-Satz oben; Stefan bestaetigt/justiert die konkrete Liste vor dem B1-Bau).

Folge-Baustein: Modell-Auswahl in ARIA Diagnostic (B0.5)

Ziel: In Diagnostic ein Modell auswählen; ist es nicht da, lädt der Container es on-demand und aktiviert es. Spiegelt zwei bestehende Muster: den whisperModel-Hotswap (RVS-Config-Broadcast → Bridge hot-swapped) und die kuratierte Claude-Tier-Liste aus models.json.

Kernproblem: llama.cpp-Server serviert ein Modell pro Prozess — „anderes aktivieren" = neu laden/swappen.

Lösung: llama-swap (Proxy vor llama.cpp): kennt eine Liste von Modellen, lädt bei Anfrage das gewünschte on-demand (Download via -hf beim ersten Mal), swappt bei VRAM-Knappheit das alte raus. OpenAI-kompatibel — der llm-adapter zeigt statt auf llama:8081 auf llama-swap.

Bausteine:

• llama-swap-Service in xtts/docker-compose.yml (ersetzt/ergänzt llama), Config mit den verfügbaren Modellen (Name → -hf-Command).
• Kuratierte Liste local_models.json (analog models.json) — Diagnostic-UI liest sie, zeigt Dropdown „Lokales Modell".
• Diagnostic → RVS-Config-Broadcast localLlmModel → llm-adapter setzt das model-Feld seiner llama-swap-Requests → swap/Download passiert automatisch.
• Status zurück an Diagnostic (lädt / bereit / VRAM-OOM), analog whisper-Status.

Konkret gewünschte UI (Stefan):

• Modell-Status sichtbar: lädt (mit Fortschrittsbalken) → heruntergeladen → aktiviert. Ist ein Modell schon im Cache: nicht neu laden, nur aktivieren (llama.cpp/llama-swap macht das nativ ueber den Cache).
• Testchat-Zeile in Diagnostic: kurze Nachricht direkt ans lokale LLM schicken, Antwort + Latenz anzeigen. Nutzt denselben RVS-Pfad (llm_request/llm_response) wie der Self-Test — kein neuer Kanal noetig.

Bis dahin: ein Modell via -hf Auto-Download (B0, erledigt). Erst end-to-end grün, dann dieser Komfort-Layer.

Skalierung: VRAM, Multi-GPU, „Cluster"

Wichtige Klarstellung: Roher VRAM/GPU ist NICHT ueber RVS teilbar. RVS ist ein Nachrichten-Relay; GPUs werden lokal per CUDA/PCIe angesprochen. Ueber RVS teilt man Inferenz-Faehigkeit (transkribiere/vervollstaendige), nicht VRAM. Es gibt daher keinen „GPU-Broker-Container", der Karten uebers Netz verleiht.

Skalierungspfade (echt):

• Mehr Karten in EINER Box → VRAM-Pool. llama.cpp/vLLM splitten ein Modell ueber mehrere GPUs (--tensor-split). 2×3060 = 24 GB → groesseres Modell ODER Qwen8B mit grossem Kontext → volles Tool-Schema passt rein. Das ist der Weg zum „vollen Arsenal lokal".
• Ein Modell ueber mehrere HOSTS splitten (llama.cpp --rpc): moeglich, aber langsam (Layer-Grenzen ueber's Netz) — nur schnelles LAN, fuer „schnell" ungeeignet. Nicht empfohlen.
• Mehrere eigenstaendige Modell-Server, je einer pro GPU/Host, Router waehlt: einfach, = unser RVS-Muster. Zweiter GPU-Host = noch ein llm-adapter, meldet sich am RVS an, Router load-balanced. Das ist der sinnvolle „Cluster".
• Innerhalb eines Hosts: ein geteilter Inferenz-Server (llama-swap/vLLM) statt VRAM-Duplikat pro Container — kommt mit B0.5.

Diagnostic ⓘ (Feature): Checkbox „volleres Arsenal" + Info-Icon mit VRAM-Bedarf: 12 GB (1×3060) = kuratierte Tools; 24 GB (2×3060, eine Box) = Qwen mit grossem Kontext/volles Schema oder groesseres Modell; Cluster = weitere GPU-Hosts als Modell-Server ueber RVS. (B0.5/B1-UI.)

„Waechter" / Orchestrator (Ausbaustufe, gestaffelt)

Idee: ein Dienst, der auf den am RVS angemeldeten Hosts Container startet/stoppt. Zerfaellt in zwei Teile:

• Billig & bald nuetzlich — Registrierung + Heartbeat: jeder GPU-Host meldet dem RVS „lebe, GPUs, VRAM frei, laufende Dienste" (kleine Erweiterung der Adapter; whisper broadcastet schon Status). Nutzen: Diagnostic zeigt die Flotte (Live-Daten fuers ⓘ), Router weiss ob lokal erreichbar (sonst Claude).
• Teuer & aufschiebbar — Steuerung (Container start/stop): Agent pro Host (Docker-Socket) + Controller mit Placement-Policy + Reconciliation + Broadcast-Kollisions-Vermeidung (nicht 2× dieselbe Faehigkeit). = Mini-Nomad.

Empfehlung: Fuer 2 Gameboxen NICHT bauen — statische Platzierung reicht (Gamebox1=LLM, Gamebox2=Voice). Dynamisches Laden/Entladen zum VRAM-Freimachen deckt llama-swap innerhalb eines Hosts (B0.5). Waechst die Flotte: erst den billigen Heartbeat-Teil; fuer echte Orchestrierung Docker Swarm / Nomad nehmen statt selbst einen Scheduler zu bauen.

ENTSCHIEDEN: manuelle Platzierung + read-only GPU-Dashboard (kein Auto)

Statt Auto-Controller (Semi-Auto verworfen — Host wechselt selten, Komplexitaet lohnt nicht):

• Pin = Docker Compose Profiles. Services kriegen profiles: [...], jeder Host setzt COMPOSE_PROFILES=<seins> in der .env; docker compose up startet nur die eigenen. „In Config gepinnt", nativ, kein Code.
• Verschiebe-Regel: up auf neuem Host + docker compose rm -sf <svc> auf altem (sonst holt restart: unless-stopped den Dienst beim Reboot zurueck → Broadcast-Kollision; Profile gelten nur beim up, nicht beim Daemon-Restart).
• GPU-Dashboard in Diagnostic (read-only): jeder GPU-Host sendet periodisch einen Heartbeat via RVS (Host, GPU-Util, VRAM frei/belegt, laufende GPU-Container). Diagnostic zeigt pro Host VRAM-Balken + Dienste + „Host X hat N GB frei". Kein Start/Stop, nur Sicht + Hinweis wohin verschiebbar.
• Zukunft (Gamebox3, 4×3060 = 48 GB): neuer Host, eigenes Profil, up → erscheint im Dashboard; grosses lokales LLM oder FLUX-Vollausbau dorthin. Ohne Orchestrator.

Verschieben-Button (Semi-Auto) — reboot-sicher via Platzierungs-Config

Wenn ein „Verschieben"-Button in Diagnostic gewuenscht ist (Dropdown Ziel-Host + Button = hier stoppen, dort starten), braucht das remote Container-Steuerung → kleiner Agent pro GPU-Host (Docker-Zugriff, hoert RVS-Befehle). Das ist der zuvor „teure" Teil, aber in der DUMMEN Variante:

• Eine Platzierungs-Config ist Single Source of Truth: /shared/config/gpu_placement.json = {service: host}.
• Dummer Reconcile-Agent pro Host: bei Start UND Config-Aenderung — starte die mir zugewiesenen Dienste, stoppe die anderen. Keine Policy, kein VRAM-Placement. Mensch = Scheduler (Button), Agent = befolgt nur Config.
• Button aendert nur die Config → Agenten reconcilen (alt stoppt, neu startet). Reboot liest Config → kein Divergieren, keine Kollision.
• Reboot-Falle vermieden: NIE Laufzeit-Move ohne Config-Update (sonst holt restart: unless-stopped den Dienst beim Reboot zurueck). Config = Wahrheit.

Deploy-Story: Code liegt via git auf allen Hosts (pull+build), aber up -d startet nichts GPU-maessig von selbst — die Platzierungs-Config (bzw. COMPOSE_PROFILES) entscheidet, was wo laeuft. Neuer Host = zuweisen, Agent startet.

Reihenfolge: NACH B0/B1. Fallback ohne Button: reine COMPOSE_PROFILES pro Host + Verschieben von Hand (null neue Infra).

Nicht-Ziele

• Kein echter Gemini-Live-Duplex-Klon (Text-Modell als Hirn).
• FLUX bleibt optional/später (dickere GPU). Bild-Generierung separat als pluggbarer Provider (ChatGPT/DALL·E-Alternative) — eigenes Feature, nicht Teil B.