my_voice_assistant_v3_jamulix/Docs/kosten-erfassung.md

Konzept: Pro-Nutzer-Kostenerfassung (USD)

Stand: Entwurf. Dokumentiert, wie die tatsächlichen Kosten je Runde erfasst, pro Nutzer/Tag akkumuliert und im Admin angezeigt werden. Bewusst so geschnitten, dass der kommende Multitool-Ausbau (plan-multitool-ausbau, MULTITOOL_AUSBAU_PLAN.md) weitere Kostenverursacher ohne Umbau anhängen kann.

1. Ziel & Leitidee

Dokumentieren, wie viele Dollar jeder Nutzer verbraucht — zur Aktivitäts- und Ressourcendokumentation. Zwei Klassen von Kosten:

• Exakt gemessen: Alles, was über OpenRouter läuft (LLM cloud, Web-Suche via perplexity/sonar, OpenRouter-TTS). OpenRouter liefert mit usage:{include:true} die Ist-Kosten jeder Generierung inline (geprüft: non-stream, Streaming im finalen usage-Chunk, Sonar — inkl. cost_details und gecachten Tokens).
• Geschätzt: Kosten außerhalb OpenRouter (Cartesia-TTS, Notruf-SMS/-Anruf, künftige externe Tool-APIs) — aus Menge × konfiguriertem Preis.

Währung: USD (nativer OpenRouter-Wert; geschätzte Quellen ebenfalls in USD konfiguriert). €-Umrechnung später optional.

2. Kostenquellen

Quelle	Erfassung	Genauigkeit
LLM cloud (OpenRouter)	inline usage.cost	exakt
Web-Suche (Sonar via OpenRouter)	inline usage.cost (~0,005 $/Suche!)	exakt
OpenRouter-TTS (gpt-audio)	inline usage.cost	exakt
Lokales LLM (Ollama/llama.cpp)	—	0 $ (nicht über OpenRouter; Strom = amortisierte Infrastruktur, NICHT pro Anfrage)
Cartesia-TTS	synth. Zeichen × Preis (100k Credits ≈ 100.000 Zeichen → 0,00005 $/Zeichen)	geschätzt
piper / Gerät-TTS	—	0 $
Notruf (SMS+Voice)	pro emergency_event × Preis (≈ 0,22 $)	geschätzt
Multitool (künftig)	je nach Tool: OpenRouter-geroutet → exakt; externe API → Tool meldet eigene Kosten; lokal/DB → 0 $	gemischt

Die Web-Suche ist der mit Abstand größte Pro-Turn-Treiber (~0,005 $ gegen Bruchteile eines Cents fürs LLM).

3. Keystone: request-weiter Kosten-Zähler über ContextVars

Kosten entstehen in vielen, nicht zusammenhängenden Schichten (LLM-Provider, Tool, TTS-Provider, Koreferenz-Vorstufe, Notruf-Modul). Callbacks durch alle Signaturen zu fädeln wäre invasiv und brüchig. Stattdessen ein request-scoped CostMeter (app/core/costs.py) via contextvars:

# app/core/costs.py
import contextvars
_meter = contextvars.ContextVar("cost_meter", default=None)

class CostMeter:
    def __init__(self): self.total = 0.0; self.by_cat: dict[str, float] = {}
    def add(self, usd: float, category: str):
        if not usd: return
        self.total += usd
        self.by_cat[category] = self.by_cat.get(category, 0.0) + usd

def start_meter() -> CostMeter:
    m = CostMeter(); _meter.set(m); return m

def add_cost(usd: float, category: str):
    m = _meter.get()
    if m is not None: m.add(usd, category)

def current_meter() -> "CostMeter | None":
    return _meter.get()

• Jede kostenverursachende Stelle ruft add_cost(betrag, kategorie) — egal in welcher Schicht, ohne Signatur-Änderung.
• Die API-Schicht (ws.py / chat.py) öffnet pro Turn start_meter(), fährt den Turn, liest danach current_meter() und persistiert.
• asyncio.create_task kopiert den Kontext und referenziert dasselbe (mutable) CostMeter-Objekt → auch Hintergrund-Tasks (Filler-/Geduld-Schleife) tragen korrekt ein. Voraussetzung: das Objekt einmal pro Turn setzen, nicht neu setzen.

Das ist die multitool-sichere Grundlage: ein neues Tool muss nur add_cost(...) rufen (oder seine Kosten im ToolResult melden, s. §5).

4. Erfassung je Quelle

• OpenRouter-Calls (LLM in tool_calling.py/openrouter.py/local_*-Cloud, Sonar in web_search.py, Koreferenz in decontextualizer.py, OpenRouter-TTS): in jeden Payload "usage": {"include": True}; nach dem Parsen add_cost(data["usage"]["cost"], kategorie). Beim Streaming den finalen usage-Chunk auslesen (unser _stream_chat ignoriert ihn heute). Ein gemeinsamer Helfer record_openrouter_cost(usage, category) vermeidet Duplikate.
• Cartesia-TTS (cartesia.py): add_cost(len(text) * cfg.cartesia_usd_per_char, "tts").
• Lokales LLM: kein cost-Feld → trägt 0 bei (fällt automatisch heraus).
• Notruf (safety/emergency.py): pro tatsächlich gesendetem Alarm add_cost(cfg.emergency_alert_usd, "alert") — nur Dokumentation, nie Sperre (sicherheitskritisch). Notrufe laufen über einen eigenen Endpunkt → dort eigenes start_meter()/Persist, da nicht Teil eines Chat-Turns.

Doppelzählung vermeiden: Jede Kostenquelle meldet genau einmal, an der Schicht, an der sie anfällt. Sonars Kosten kommen aus seinem OpenRouter-Call (§4, Kategorie web_search) — SonarTool meldet keine zusätzlichen Kosten im Result.

5. Multitool-Vorsorge

Künftige Tools (MULTITOOL_AUSBAU_PLAN.md) fügen sich ohne Umbau ein:

• OpenRouter-geroutetes Tool (z. B. eine LLM-Klassifikation, Medizin-Safety): Kosten werden am OpenRouter-Call automatisch erfasst (Kategorie z. B. tool:medsafety).
• Externe-API-Tool (z. B. Wetter, Karten, Kalender mit Bezahl-API): Das Tool kennt seine Kosten selbst → es meldet sie. Dafür bekommt ToolResult ein optionales Feld cost_usd: float | None; ToolCallingLLM._run_tool ruft bei cost_usd add_cost(result.cost_usd, f"tool:{name}"). (OpenRouter-Tools lassen cost_usd=None.)
• Lokales/DB-Tool (Erinnerungen, Profil): 0 $.

→ Kategorien sind frei (Strings), die Speicherung (§6) ist zeilenbasiert → neue Kostenarten erscheinen automatisch als neue Kategorie, ohne Schema-Änderung.

6. Speicherung

Eine kategorie-zeilenbasierte Tages-Tabelle (extensibel, kein Spalten-ALTER bei neuen Kostenarten):

CREATE TABLE IF NOT EXISTS cost_usage (
    user_id  TEXT NOT NULL,
    day      TEXT NOT NULL,          -- UTC, wie usage/web_search_usage
    category TEXT NOT NULL,          -- llm | web_search | tts | alert | tool:<name>
    amount_usd REAL NOT NULL DEFAULT 0,
    PRIMARY KEY (user_id, day, category)
);

Store-Methoden: add_cost(user_id, category, usd, day=None) (UPSERT), get_cost(user_id, day=None) / Aggregation über Fenster; kaskadiert in delete_user und wird von delete_user_history nicht angetastet (Kosten bleiben). In der API-Schicht nach dem Turn: meter.by_cat zeilenweise in cost_usage buchen. Aggregation für die Statistik = SUM über Kategorien/Fenster.

7. Konfiguration (neue Settings)

• cost_tracking_enabled: bool = True
• cartesia_usd_per_char: float = 0.00005 (100k Credits ≈ 100.000 Zeichen)
• emergency_alert_usd: float = 0.22 (SMS+Voice ≈ 20 €-Cent)
• (später) usd_per_eur für optionale €-Anzeige.

usage:{include:true} wird in allen OpenRouter-Payloads gesetzt (minimaler Mehraufwand, nur größerer Response).

8. Darstellung (Admin → Nutzungsstatistik)

Pro Nutzer:

• Kosten (laufender Monat) — passt zur OpenRouter-Abrechnung; umschaltbar Heute · 30 Tage · Monat · Gesamt (seit Erfassungsbeginn).
• Ø Kosten/Anfrage = Monatskosten / Anfragen — Verhaltens-Indikator.
• optional Aufschlüsselung je Kategorie (LLM / Web-Suche / TTS / Notruf / Tools).
• Gesamt-Zeile (alle Nutzer) = geschätzte Monatsrechnung; davon „exakt (OpenRouter): $X" zum Abgleich mit dem OpenRouter-Dashboard.

Exakt vs. geschätzt sichtbar kennzeichnen (OpenRouter-Kategorien = exakt; cartesia/alert/externe Tools = Schätzung). „Kosten erst ab Einführung der Erfassung; lokale Modelle = 0 $."

9. Optional: €-/$-Budget statt nur Web-Such-Budget

Das vorhandene Pro-Nutzer-Tagesbudget (web_search_daily_limit) lässt sich zu einem cost_daily_limit_usd erweitern: ist das Tagesbudget aufgebraucht, greift dieselbe Gate-/Hinweis-Mechanik (Web-Suche aus + freundliche Systemnachricht). Deckt dann alle Kostenarten statt nur Suchen. Notrufe bleiben ausgenommen.

10. Harte Stellen (bewusst benannt)

• Streaming-usage-Chunk auslesen (heute ignoriert) — sonst werden gestreamte Antworten (der Normalfall!) mit 0 $ gezählt.
• Doppelzählung vermeiden (§4): genau eine Meldung pro Quelle.
• ContextVar + Tasks: Meter einmal pro Turn setzen; Tasks kopieren den Kontext und mutieren dasselbe Objekt.
• Cartesia ist ein Abo ($5/100k): der Pro-Zeichen-Preis ist der implizite Stückpreis (Anteil am Credit-Pool), nicht streng marginal — als „anteilig" framen.
• Notruf nie blocken, nur dokumentieren.
• Reconciliation: nur der OpenRouter-Anteil ist 1:1 gegen die OpenRouter-Rechnung abgleichbar; Cartesia/Notruf gegen deren eigene Rechnungen.

11. Phasenplan

• Stufe 1 (80 %, exakt): CostMeter + OpenRouter-usage.cost (LLM, Sonar, OpenRouter-TTS) inkl. Streaming-Chunk; cost_usage-Tabelle; Statistik-Spalte „Kosten (Monat)" + Ø/Anfrage + Gesamt.
• Stufe 2 (Schätzungen): Cartesia (Zeichen×Preis) + Notruf (pro Event); exakt/geschätzt-Kennzeichnung; Aufschlüsselung.
• Stufe 3 (optional): cost_daily_limit_usd-Budget + Hinweis; €-Anzeige.
• Multitool: ToolResult.cost_usd + tool:<name>-Kategorien — greift dann automatisch (keine weitere Statistik-Änderung nötig).

12. Berührte Dateien (Landkarte)

• neu: app/core/costs.py (CostMeter, add_cost, start_meter)
• app/providers/llm/{tool_calling,openrouter,local_openai_compatible}.py, app/tools/web_search.py, app/pipeline/decontextualizer.py — usage:{include:true}
  • record_openrouter_cost(...); Streaming-usage-Chunk lesen
• app/providers/tts/{cartesia,openrouter}.py — TTS-Kosten
• app/safety/emergency.py — Notruf-Kosten (pro Event)
• app/api/ws.py / app/api/chat.py — start_meter() pro Turn + Persist
• app/store.py — cost_usage-Tabelle + add_cost/get_cost; delete_user-Kaskade
• app/config.py — neue Settings
• app/api/admin.py (get_all_usage um Kosten/Kategorien) + app/web/app.js (Spalten/Aufschlüsselung)