docs(ops): AI cost per document, monthly limits and action at the limit (#109)

[Fluory]

Warum

Refs #109 (nicht „Fixes“: das Kriterium „Budget-Alarm beim Anbieter eingerichtet“ ist eine Kontoaktion des Orchestrators und bleibt offen) · Lücke aus dem Add-on-Audit #65 (AI/RAG-Checkliste #15 „Kostenlimits & Modellwahl dokumentiert“, Betriebs-Checkliste #13 „Budget-Alert“). Start: Orchestrator „mach weiter“ am 2026-10-16.

Arbeitsstand

• Ziel: Nachvollziehbar dokumentiert, was ein Dokument an KI kostet, welches Monatslimit gilt, wer gewarnt wird und was am Limit passiert.
• Nicht-Ziele: Kosten-Dashboard in der App (laut Issue); Modellwechsel 3.5 → 3.6; Code-Änderung am KI-Dienst (→ feat(ai): cap output tokens and document text per model call #123).
• Erledigt: Abschnitt „AI cost“ in operations.md (Formel, Tokenquelle, datierte Preise, Wiederholungen als Kostenfaktor, Grenzen der Upload-Caps, Monatslimits, Budget-Alarm, Schritte am Limit); Hinweis unter der Dienstleister-Tabelle in architecture.md; Folge-Issue feat(ai): cap output tokens and document text per model call #123.
• Offen: Orchestrator: Monatslimits bestätigen, Budget-Alarm einrichten (Schwellen 50/90/100 %), sobald der Showcase den Free Tier verlässt (spätestens 2026-10-31); offizieller Preis für gemini-3.5-flash oder Modellentscheidung.
• Annahmen: gleiche Tokenzahlen für 3.6 wie für 3.5 (nicht gemessen); Vertex-Listenpreise nicht geprüft; Pilot-Annahme 5 Personen × ~15 Dokumente/Arbeitstag.
• Nächster kleinster Schritt: Review und Merge durch den Orchestrator; danach Kontoaktion Budget-Alarm.

Was ist passiert (Klartext)

Bisher war offen, was die KI pro Anfrage kostet und was passiert, wenn das Geld ausgeht. Jetzt steht in der Betriebsdoku: Ein Dokument kostet nach den zwei aufgezeichneten Beispielen etwa 1 bis 3 Cent – mit dem Hinweis, dass Google den Preis des aktuell genutzten Modells nicht mehr offiziell veröffentlicht. Vorgeschlagen sind 10 € im Monat für den Showcase und 50 € für den Pilotbetrieb, mit Warnungen bei 50, 90 und 100 %. Dabei kam heraus: Die Upload-Grenzen begrenzen nur die Anzahl der KI-Aufrufe, nicht deren Größe – ein sehr großes Dokument kann deutlich mehr kosten. Dafür gibt es jetzt ein eigenes Issue (#123). Am Limit gibt es eine klare Reihenfolge: KI-Aufrufe stoppen, Ursache finden, erst nach Freigabe weitermachen.

Plan-Pflicht (SYSTEM.md §4)

• Kein Auslöser – nur Doku; keine Modulgrenze, API, Migration, Auth-Änderung, kein neuer Infrapfad, umkehrbar
• Auslöser zutreffend – Impact Manifest ausgefüllt (Plan vor Code)

Geändert

• docs/technical/operations.md: neuer Abschnitt „AI cost“ (vor „Frequent failures“)
• docs/technical/architecture.md: Hinweis unter „External services & interfaces“ mit Link

Nachweis (SYSTEM.md §11)

• Rechnung reproduzierbar: Formel input × Inputpreis + (total − input) × Outputpreis, Tokens aus src/features/samples/data/*.recording.json (Pumpe P204: 1280 in / 4522 total; Werk Ost: 1281 / 3558), Preise vom 2026-10-15/16: Gemini-API-Preisseite (3.6 Flash 0,75/3,75 USD bis 2026-12-31, 1,50/7,50 ab 2027; Output inkl. Thinking-Tokens); 3.5 Flash dort nicht mehr gelistet → Drittquellen 1,50/9,00 USD, als unbestätigt markiert; Abschaltung laut Deprecations-Seite: keine
• Aussagen gegen Code geprüft: ein Modellaufruf je Dokument (src/features/jobs/process-request.ts), kein max_output_tokens und keine Textgrenze (services/ai/src/requestflow_ai/extraction/model_client.py, prompt.py), Showcase: UPLOAD_MAX_FILES 3, UPLOAD_MAX_PER_HOUR im Runbook nur als Beispiel 20 (deployment-vercel.md §4) – tatsächlicher Wert ist eine Vercel-Einstellung
• scripts/doku-check.sh: grün (0 WARN); scripts/pr-check.sh lokal gegen diese Beschreibung: grün
• Frischer Review (unabhängiger Subagent): 1 blockierend (Wiederholungen eines Jobs rufen das Modell für alle Dokumente erneut auf, bis zu 6 Versuche) + 5 Nits – behoben in 7973361; Details im PR-Kommentar
• verify: grün – CI check Run 38878680446 am PR-Kopf 7973361 (nur Doku: Doku- und PR-Guard; kein Code geändert)
• Budget-Alarm: nicht eingerichtet (Kontoaktion, Showcase noch im Free Tier)

Doku-Entscheidung (genau eine)

• Keine langlebige Doku betroffen – Begründung: –
• Doku betroffen und im selben PR aktualisiert:
  • Produktdoku: –
  • Technische Doku: operations.md (AI cost), architecture.md (Hinweis bei den Dienstleistern)
  • Architekturkarte: –
  • ADR: –
  • CHANGELOG [Unreleased]: kein Produktverhalten geändert

Entferntes oder Umbenanntes: nichts

Dateigrößen und neue Bausteine (SYSTEM.md §7)

Dateien über 500 Zeilen im Diff (Ausnahmen: generierter Code, Lockfiles, Fixtures, Migrationen, Schemas, Ressourcen, Doku, Konfiguration):

• keine
• bewusst belassen – Begründung: –
• im selben PR nach fachlicher Verantwortung geteilt
• Folge-Issue –

Über 800 Zeilen mit neuer Fachlogik oder über 1000 Zeilen (P1/P2): nicht betroffen

Neue Shared-Komponente, Utility-Datei, Adapter oder fachlicher Service:

• nein
• ja – gesucht nach: –

Subagent-Einsätze

• 1 Review-Subagent (nur lesend, frischer Kontext): Rechnung, Code-Aussagen und Schritte am Limit geprüft; Ergebnis im PR-Kommentar

Risiken / offene Punkte

• Der Preis des produktiv genutzten Modells ist nicht offiziell belegt; die Showcase-Ausnahme (Free Tier) endet spätestens 2026-10-31 – bis dahin sollte die Modellentscheidung (3.5 bleibt erreichbar, Google empfiehlt 3.6) fallen.
• Basiert auf main: Die Verweise auf den Incident-Abschnitt (docs(ops): incident process with the GDPR 72-hour step (#111) #122) und die Metrics-Seite (docs(product): success signals for the pilot with targets and queries (#113) #121) stehen als Text, nicht als Link, damit nichts ins Leere zeigt, falls die Reihenfolge der Merges anders ist.

🤖 Generated with Claude Code

https://claude.ai/code/session_0117LRiQKt8ycJEHW7vxLWG3

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
requestflow	Ready	Preview	Oct 16, 2026 9:11am UTC

[Fluory]

Fresh review (independent subagent, read-only) – result and how it was handled

Verdict: changes needed (1 blocking, 5 nits). Arithmetic, token split (total − input = output incl. thinking; input + output ≠ total in both recordings), code claims and at-limit steps checked as correct.

• Blocking – retries multiply calls. model_output_invalid / model_error are retryable (src/features/extraction/ai-client.ts), the process queue retries the job up to 5 more times (src/features/jobs/queues.ts), and each attempt calls the model for every document again; failed attempts store no tokens → fixed in 7973361: up to 6 attempts named, worst case 360 calls/person-hour while answers fail, S4 understates.
• Nit – Werk Ost on 3.6 rounds to 0.009 → fixed.
• Nit – EUR limits divided as USD → column now says "1 EUR counted as 1 USD – conservative".
• Nit – docs/product/metrics.md not on this branch → marked "pending in docs(product): success signals for the pilot with targets and queries (#113) #121".
• Nit – "10 USD" vs. 10 EUR limit → reworded.
• Nit – German quotes in an English doc → plain quotes.

Follow-up note for #123: re-calling documents that already succeeded on a job retry is a cost multiplier worth fixing there or in its own issue.

---

Generated by Claude Code