my_voice_assistant_v3_jamulix/Docs/weg2-tool-calling.md

# Design: Web-Suche per Tool-Calling (Weg 2)

> Stand: Entwurf. Beschreibt das Konzept für die Frische-/Web-Such-Funktion auf
> Basis von agentischem Tool-Calling. Modellwahl und Schwellen sind durch den
> Eval-Harness (`eval/tool_calling/`) belegt; Implementierung folgt diesem Dokument.

## 1. Ziel & Leitidee

Das zentrale LLM kennt nur Wissen bis zu seinem Trainings-Cutoff. Fragt der Nutzer
nach etwas, das sich seither geändert haben könnte (aktuelle Amtsträger, Preise,
Wetter, Nachrichten, „lebt X noch", Öffnungszeiten …), soll das Modell **selbst**
eine Web-Suche auslösen, die frischen Fakten holen und die Antwort **in der
Alexis-Persona** formulieren.

**Weg 2 = Tool-Calling + Anreichern:** Das Antwortmodell entscheidet via Werkzeug,
ob es sucht; die Suche liefert nur Fakten, das Modell formuliert. Vorteil:
durchgängige Stimme, Persona/Safety/History bleiben beim Hauptmodell. Bewusst
verworfen wurde der separate Vorab-Klassifikator („Weg 1"), weil das gewählte
Modell sich zuverlässig genug selbst triggert (siehe §7).

## 2. Modellwahl (belegt)

`mistralai/mistral-small-3.2-24b-instruct` über OpenRouter. Eval-Ergebnis
(69 Fälle × 5 Läufe): Trigger-Recall **93 %**, Vorrang-Treue **100 %**,
Wohlgeformtheit **100 %**, gefährliche Kategorien (Amtsträger/Preise/Nachrichten/
Sport/Releases) **100 %**, Wetter inkl. implizitem Ort 98 %. Günstig und klein →
niedrige Latenz (im Senioren-Kontext doppelt wertvoll). Details und Vergleich
(Flash/Pro/alte Baseline) in der Memory-Notiz bzw. `eval/tool_calling/`.

> Achtung: Die bisherige TOML-Baseline `mistral-small-24b-instruct-2501` kann
> **kein** Tool-Calling (OpenRouter 404 „No endpoints found that support tool use").
> Ein Revert darauf würde Weg 2 abschalten.

## 3. Keystone: Der Tool-Loop lebt *im* LLM-Provider

Ein neuer Wrapper **`ToolCallingLLM`** implementiert die bestehende
`LLMProvider`-Schnittstelle (`complete()`/`stream()`), wickelt aber intern die
Agenten-Schleife ab. Der Orchestrator ruft weiter nur `self.llm.stream(...)` und
weiß nichts von Tools. Folge: **ein neuer `LLM_REGISTRY`-Eintrag**, keine
Kern-Änderung, volle Kompatibilität mit `resolve_route`, Fallback-Ketten und
Profilen. Das ist das Leitprinzip „jede Achse austauschbar".

`ToolCallingLLM` enthält einen **eigenen** tool-fähigen OpenRouter-Client (Keim:
`eval/tool_calling/client.py`) — nicht den plain `OpenRouterLLMProvider`, da
dessen `complete()` keine `tools` kennt.

## 4. Datenfluss

**Kein-Tool-Turn (Normalfall, kein Latenz-Regress):**
```
stream() → Modell mit tools=[…] → Text-Deltas → 1:1 an on_token/SentenceChunker
```

**Such-Turn (augment):**
```
(0) Koreferenz-Vorstufe: Pronomen aus History auflösen (gegated)
(1) Modell → tool_call("web_search", query)
(2) on_tool_start(language) → Filler SOFORT sprechen/anzeigen
(3) SonarTool(query) → Fakten   (~1–3 s, vom Filler überdeckt)
(4) Modell-Runde 2 mit tool-Ergebnis → finale Antwort, gestreamt, in Persona
```

## 5. Komponenten

### 5.1 `SonarTool`
Ruft `perplexity/sonar` über OpenRouter (gleiche Chat-API wie `OpenRouterLLMProvider`).
Prompt an Sonar: knapp, Zielsprache, reine Fakten. Rückgabe als `tool`-Message ans
Modell. **Citations** als strukturierte Metadaten an die UI-Bubble (nicht ins TTS).
Timeout/Fehler → Sentinel „keine aktuellen Daten verfügbar", damit das Modell
ehrlich punktet statt zu hängen.

### 5.2 `ToolCallingLLM`
Begrenzte Schleife (max. ~3 Runden gegen Runaway). System-Prompt =
Senioren-Persona (`SYSTEM_PROMPT` aus `openrouter.py`) **+** kalibrierte
Trigger-Leitlinie **+** Vorrang-Regel („Tool-Ergebnis ist maßgeblich und neuer
als dein Wissen; bei Widerspruch folge dem Tool, nicht mischen"). Implementiert
`complete()` (für `chat_text`/`translate`) und `stream()`.

### 5.3 Koreferenz-Vorstufe (in v1)
Schließt die einzige nicht-triviale Eval-Restkante (`ctx_alive_nl`:
nl + Pronomen-aus-History; benannt + de-Pronomen sind 5/5). Ein
dekontextualisierender Rewrite macht die letzte Äußerung mit Hilfe des Verlaufs
selbstständig („hij" → „Rutger Hauer"). **Gegated**: nur bei kurzer Folgefrage
*mit* Pronomen *und* vorhandener History, damit er nicht jeden Turn kostet.

### 5.4 Filler / Beruhigung
`stream()` erhält einen `on_tool_start(language)`-Callback. Der Orchestrator
verdrahtet ihn auf: lokalisierten Satz (rotierender Pool je Sprache, Muster wie
die `_NOTICE`-Dicts) → `spoken_adapter`/`tts_normalizer`/`tts` → `on_audio` **und**
`on_token`. **Ephemeralität (Invariante):** Der Filler läuft über *diesen
Callback*, nicht über den Delta-Stream — dadurch landet er **nicht** in
`trace.semantic_response` und **nicht** im gespeicherten History-Turn. Bei langen/
mehreren Tools gestaffelt eskalieren („Moment …" → „Bitte noch einen Augenblick …").
Server-TTS ist ein kleiner Eingriff; **„Im Gerät" ist Fast-follow** (eigener
Event-Typ → Browser-`speak()`, Gesten-/Voices-Absicherung).

### 5.5 Konfiguration & Opt-out
`web_search_enabled: bool = True` — **global an per Default**, pro Nutzer/Profil
**abschaltbar** (Opt-out greift über die bestehende Präzedenz
Defaults < Profil < Nutzer-Prefs). Der Schalter ist die nutzerfreundliche
Admin-/Profil-Option; intern wählt `build_orchestrator` daraufhin den
tool-fähigen vs. den plain Provider — **beide mit demselben konfigurierten
Modell** (`openrouter_llm_model`), damit der Modellwechsel an *einer* Stelle bleibt.

### 5.6 Resilienz & Metriken
Fallback: Sonar-Ausfall → honest-punt im Loop; totaler Modellausfall → bestehende
`llm_fallback`-Kette. **Metriken** (`app/metrics.py`): Tool-Calls und Sonar-Calls
separat zählen — Kostensicht **und** Live-Beobachtung der Trigger-Rate.
**Kein** eigenes Sonar-Kontingent in v1 (erst Metrik-Sicht; `quota.py`-Anbindung
später bei Bedarf).

## 6. Die zwei harten Stellen (bewusst benannt)

- **Streaming + Tool-Erkennung.** Beim gestreamten ersten Call kommen
  `tool_call`-Deltas fragmentiert. Der Wrapper setzt sie zusammen und
  unterscheidet: Text-Deltas → durchreichen (kein Regress im Normalfall);
  materialisiert sich ein Tool-Call → Stream verwerfen, Filler, Sonar, zweite
  Runde streamen. mistral emittiert *entweder* Tool-Call *oder* Text — das macht
  es handhabbar; das Delta-Zusammensetzen ist die eigentliche Arbeit.
- **Filler-Ephemeralität.** Spielt in Bubble *und* TTS, darf aber nie in
  `semantic_response`/Store/`history`. Der Callback-Weg löst das by-design — beim
  Implementieren strikt einhalten.

## 7. Warum nicht Weg 1 (separater Klassifikator)

Der Eval zeigte: das Modell self-triggert auf den gefährlichen, konfident-
veraltbaren Kategorien zu 100 %; die Recall-Lücke (→93 %) liegt nur in
low-/medium-harm-Slices (Logistik honest-punt, eine nl-Koreferenz-Kante).
Tool-Calling spart den Vorab-Roundtrip und ist zugleich die Basis für den
späteren Multitool-Ausbau (weitere Werkzeuge in dieselbe Schleife, Vorrang-Regel
wird zur Tool-Rangordnung).

## 8. Phasenplan

- **v1:** `SonarTool` + `ToolCallingLLM` (Loop, Persona+Vorrang-Prompt, eigener
  Tool-Client) + Koreferenz-Vorstufe + Registry-Eintrag + `web_search_enabled`
  (global an, Opt-out) + Filler für **Server-TTS** + Tool/Sonar-Metriken.
  schedule_hours-honest-punt akzeptiert.
- **Fast-follow:** Filler für **Gerät-TTS** (Event-Protokoll) → Citations in die
  UI-Bubble → ggf. deterministischer Logistik-Nudge.
- **Später (Multitool):** weitere Tools in dieselbe `ToolCallingLLM`-Schleife
  (Kalender, Erinnerungen, Medizin-Safety) mit Tool-Rangordnung.

## 9. Berührte Dateien (Implementierungs-Landkarte)

- neu: `app/providers/llm/tool_calling.py` (`ToolCallingLLM`), `app/tools/web_search.py` (`SonarTool`), `app/pipeline/decontextualizer.py` (Koreferenz-Vorstufe)
- `app/dependencies.py` — `LLM_REGISTRY`-Eintrag; `build_orchestrator` (tool vs. plain je `web_search_enabled`)
- `app/core/orchestrator.py` — `on_tool_start`-Callback in `chat_stream`, Filler-Emission (ephemer)
- `app/config.py` / `app/runtime_config.py` — `web_search_enabled` (Default true, RUNTIME_SETTABLE + Nutzer-Pref-Opt-out)
- `app/metrics.py` — Zähler `tool_calls_total`, `sonar_calls_total`
- Filler-Texte je Sprache (Pool)