# Credits und Abrechnung

Wie das Kontingent eines Kunden funktioniert, welche Stellschrauben es gibt und
was die Verwaltung setzen muss. Stand 2026-07-25 (Portierung aus dem Lokal-Fork,
Sätze auf die am 23.07.2026 beschlossenen Verkaufswerte gesetzt).

## Begriffe

Der Kunde sieht **Credits**, nicht Token und nicht Dollar. Das ist Absicht.
"Token" ist ein KI-Fachbegriff mit einer festen Bedeutung, und 10.000 echte
Token wären etwa 7.500 Wörter, also ein einziger längerer Artikel. Wer den
Begriff kennt, hält so eine Angabe für einen Fehler. Intern heißen die Felder
`credits_*`, nach außen steht überall "Credits" (Entscheidung vom 25.07.2026,
einheitlich in Monitor und Verwaltungsportal).

## Was eine Aktion kostet

Im Modus `flat` (Voreinstellung) kostet jede Aktion einen festen Satz,
unabhängig davon, was sie uns tatsächlich verursacht hat. 1 Credit entspricht
0,20 USD. Die wirksamen Sätze stehen seit 25.07.2026 in der geteilten Tabelle
`billing_tariff` und sind über den Verbrauchsrechner des Verwaltungsportals
pflegbar. `CREDIT_TARIFF` in `src/config.py` befüllt die Tabelle beim ersten
Start und bleibt Rückfallebene für fehlende Schlüssel.

| Aktion | Credits | Herkunft des Werts |
|---|---|---|
| Live-Refresh (adhoc) | 45 | beschlossen 23.07.2026 (gemessener Median 24 Credits = 4,76 USD) |
| Recherche je Durchlauf | 40 | beschlossen 23.07.2026 (gemessener Median 33 Credits = 6,54 USD) |
| Analyse-Baustein (Studio) | 12 | geschätzt, rund ein Viertel eines Live-Laufs |
| Faktencheck-Baustein (Studio) | 12 | geschätzt |
| Chat, Beschreibungs-Assistent, Globe | 1 | real 0,02 bis 0,03 USD je Aufruf |

Die erste Aktualisierung einer Recherche-Lage fährt drei Durchläufe, kostet also
120 Credits. Die Verkaufssätze liegen bewusst über den gemessenen Medianen.
Messgrundlage sind 1.341 abgeschlossene Refreshes des Live-Systems aus dem
Zeitraum 28.02.2026 bis 21.06.2026 (`refresh_log`). Der Verbrauchsrechner im
Verwaltungsportal rechnet mit denselben Sätzen.

### Warum feste Sätze und nicht die echten Kosten

Vorher wurde `echte_kosten / cost_per_credit` abgebucht. Das hatte zwei Nachteile.
Der Kunde konnte nicht planen, weil ein Refresh einer großen Lage ein Vielfaches
eines Refreshs einer frischen kostet, ohne dass er den Unterschied sieht. Und
sobald das Modell-Backend billiger wird, etwa beim Wechsel von Anthropic auf eine
EU-Cloud, hätte derselbe Kunde plötzlich ein Vielfaches an Aktionen bekommen,
oder wir hätten `cost_per_credit` nachziehen müssen, was nach einer heimlichen
Preiserhöhung aussieht.

Der alte Modus lebt weiter unter `BILLING_MODE=actual` als Rückfallebene. Die
echten Kosten wandern in beiden Modi unverändert nach `token_usage_monthly`, die
interne Kostenkontrolle bleibt also vollständig erhalten.

## Abrechnungsperiode

`licenses.credits_period` steuert den Bezugszeitraum.

- `monthly` (Voreinstellung) füllt die Credits zum Monatswechsel neu auf.
- `total` lässt das Kontingent für die gesamte Lizenzlaufzeit gelten.

Der Wechsel passiert träge bei der nächsten Lizenzprüfung, nicht über einen
Zeitplan. Ein verpasster Monatswechsel wird dadurch beim nächsten Zugriff
nachgeholt, und ohne Nutzung wird ohnehin nichts verbraucht.

`credits_rollover` überträgt ungenutzte Credits in den Folgemonat, gedeckelt
auf ein Monatskontingent. Der Übertrag steht in `credits_carried` und zählt beim
Hard-Stop mit. Das ist empfehlenswert, weil OSINT-Nutzung ereignisgetrieben ist.
Bricht eine Krise aus, braucht der Kunde in einer Woche mehr als sonst im
Quartal, und genau dann darf das System nicht dichtmachen.

Eine Bestandslizenz ohne Periodenmarke bekommt beim ersten Zugriff die aktuelle
Periode eingetragen, **ohne** den Verbrauch zurückzusetzen. Sonst würden ihr
Credits geschenkt, die im laufenden Monat bereits verbraucht wurden.

## Warnung und Sperre

Bei Erreichen von `budget_warning_percent` (Voreinstellung 80) bekommen alle
aktiven Nutzer der Organisation eine Meldung im Benachrichtigungsbereich. Das
Flag `budget_warning_sent` verhindert, dass sich die Warnung bei jeder weiteren
Buchung wiederholt, und wird beim Periodenwechsel zurückgesetzt.

Sind die Credits aufgebraucht, wechselt die Organisation in den Nur-Lese-Modus.
Bestehende Lagen bleiben vollständig lesbar, es lassen sich nur keine neuen
Aktualisierungen mehr starten. Abgeschaltet wird nichts.

**Offen.** Die Warnung geht bisher nur in die Oberfläche, nicht per E-Mail. Wer
sich nicht anmeldet, sieht sie nicht. Ein Versand über `email_utils` wäre der
nächste Schritt.

## Was die Verwaltung je Lizenz setzen muss

| Spalte | Bedeutung | Beispiel |
|---|---|---|
| `credits_total` | Kontingent je Periode | 10000 |
| `cost_per_credit` | nur für `BILLING_MODE=actual` und die interne Rechnung | 0.20 |
| `credits_period` | `monthly` oder `total` | monthly |
| `credits_rollover` | Übertrag erlauben | 1 |
| `budget_warning_percent` | Warnschwelle in Prozent | 80 |
| `unlimited_budget` | Kontingent aushebeln | 0 |

Ohne `credits_total` läuft die Organisation ohne Kontingent, dann wird nichts
belastet. So stehen aktuell alle vier Live-Lizenzen (`unlimited_budget=1`), die
Umstellung ändert für sie nichts, bis ihnen ein Kontingent gesetzt wird.
Das Verwaltungsportal hat für diese Stellwerte noch keine Eingabefelder, das ist
ein eigenes, offenes Arbeitspaket auf der Portal-Seite.

## Einordnung der Größenordnung

Bei einem Satz von 45 Credits je Live-Lauf entspricht ein Monatskontingent von
10.000 Credits rund 222 Live-Refreshes oder rund 83 neu angelegten Recherchen.
Zum Vergleich, das gesamte Live-System mit 46 aktiven Lagen verbrauchte im Mai
2026 nach den gemessenen Medianen rund 11.700 Credits, mit den Verkaufssätzen
bewertet wären es grob 20.000 bis 22.000.

Ein Hinweis zur Fortschreibung. Die Ist-Kosten je Refresh sind zwischen März und
Mai 2026 von 3,54 auf 7,80 Dollar gestiegen, vermutlich weil ein Lagebild mit
wachsendem Materialbestand auf mehr Kontext aufsetzt. Falls sich das bestätigt,
verbraucht derselbe Kunde im zweiten Jahr mehr als im ersten. Die Sätze in
`CREDIT_TARIFF` sollten deshalb regelmäßig gegen `token_usage_monthly` geprüft
werden.

## Auto-Refresh-Takt

Der Takt ist die wichtigste Stellschraube am Verbrauch. Achtung, im Online-Monitor
liegt die Untergrenze derzeit noch bei 10 Minuten und die Voreinstellung bei
15 Minuten. Ein Live-Refresh dauert gemessen im Median aber 12,7 Minuten, jeder
zehnte länger als 22,9 Minuten, und im 15-Minuten-Takt verbraucht eine einzige
Lage bei 45 Credits je Lauf rund 130.000 Credits im Monat. Der Lokal-Fork hat
dafür bereits eine Lösung (Untergrenze 30 Minuten, Voreinstellung 12 Stunden,
Kostenvorschau im Anlege-Dialog, Commit 5b0b578), deren Portierung noch offen ist.

Zur Orientierung bei einem Kontingent von 10.000 Credits und 45 Credits je Lauf.

| Takt | Refreshes je Monat | Credits | Anteil |
|---|---|---|---|
| 30 Min | 1.440 | 64.800 | 648 Prozent |
| 1 Stunde | 720 | 32.400 | 324 Prozent |
| 6 Stunden | 120 | 5.400 | 54 Prozent |
| 12 Stunden | 60 | 2.700 | 27 Prozent |
| 24 Stunden | 30 | 1.350 | 14 Prozent |

## Offene Punkte

- E-Mail-Versand der Budget-Warnung.
- Takt-Untergrenze und Kostenvorschau aus dem Lokal-Fork portieren (siehe oben).
- Nachkaufpakete. Ohne sie ist der Deckel eine Sackgasse, mit ihnen eine
  Umsatzquelle. Der Verkauf gehört ins Verwaltungsportal, im Monitor müsste nur
  der Hinweistext bei aufgebrauchten Credits darauf zeigen.
- Sätze für die Studio-Bausteine sind geschätzt und sollten nachgemessen werden,
  sobald `token_usage_monthly` Zeilen mit `source='analysis'` und `'factcheck'`
  enthält.