# REOS AI SDK

# REOS AI SDK

**REOS AI** ist die gebündelte KI-Schicht im Platform-SDK. Dein Tool wählt einen **Tier**, nicht ein Modell. Welches Modell dahinter läuft, entscheidet die Plattform (oder BYOK); du musst es nie kennen.

## Tier statt Modell

`import { reosAi } from "@reosa/sdk"`

```typescript
const ai = reosAi.resolve({ tier: "bulk", billing: "credits", byok });

ai.available;      // false = kein Modell konfiguriert → nutze deinen eigenen Fallback
ai.modelLabel;     // "REOS AI · Bulk"; der Modell-Name ist immer versteckt
ai.bypassCredits;  // true bei usage/byok (keine Plattform-Credits)

const { text, usage } = await ai.complete({
  systemPrompt, userPrompt, jsonMode: true, maxTokens: 1400,
});
```

- **`bulk`**: günstige/kostenlose Modelle für Massen-Aufgaben (z. B. ein Briefing pro Datensatz).
- **`standard` / `premium`**: reserviert für die Assistant-Modi (folgt).

## Abrechnungs-Modi

| Modus | `bypassCredits` | Bedeutung |
|---|---|---|
| `credits` | false | Über Plattform-Credits (Reserve→Commit/Refund). Warne den Nutzer vor teuren Läufen. |
| `usage` | true | Nutzungsbasiert, kein Credit-Limit. Emittiere ein Metered-Usage-Event. |
| `byok` | true | Eigener Provider-Key. REOS AI berechnet keine KI. |

## Zero-Config-Regel

Ist kein Modell konfiguriert (`available === false`), nutze deinen eigenen deterministischen Pfad. So funktioniert dein Tool sofort, auch ohne API-Key. `reosAi` crasht nie, es meldet nur „nicht verfügbar“.

## Kosten-Schätzung für Warnungen

```typescript
reosAi.estimateCredits({ tier: "bulk", items: 15000 }); // grobe Credit-Schätzung
reosAi.creditsPerItem("bulk");                          // Credit-Floor pro Lauf
```

Nutze das für einen „teure AI-Aktion“-Hinweis, bevor du im `credits`-Modus loslegst.

## Regeln

- **Modell-Name nie im Tenant-UI zeigen**: nutze `modelLabel`.
- **BYOK-Key nie speichern**: nur eine `keyRef`; der Key kommt serverseitig aus env/Vault. Der Tenant-Key wird unter `REOS_AI_BYOK_<keyRef>` bereitgestellt (Sonderzeichen im `keyRef` werden zu `_` normalisiert). BYOK greift **nie** auf den Plattform-Key zurück: fehlt der eigene Key des Tenants, meldet `resolve()` `available === false` (fail-closed), statt einen credit-freien Lauf auf dem Plattform-Konto zuzulassen.
- **1 Credit = 0,02 €** (kanonisch).

Architektur-Details: siehe die interne Doku `reosa-docs/03-platform-sdk/reos-ai.md`.