# AP3 – Anbindung KI-API ITM

| | |
|---|---|
| Status | in Arbeit; Schritte ab 3.2 detailliert, warten auf Freigabe |
| Aufwand | 0,5 PW offen |
| Zeitraum | KW 42 (Schnelltest, Einstellungen), KW 44 (Clients, Jobs) |
| Meilenstein | M1/M2 |
| Freigabe | offen |

## Ziel

Die Anwendung nutzt Dokumentdienst, `embed`, `rerank` und `chat` zuverlässig. Sie beachtet die
Grenzen der API und protokolliert jeden Aufruf ohne Inhalte und ohne Schlüssel. Die Schlüssel
liegen verschlüsselt in der Datenbank.

## Umfang

**Enthalten:**
- Schlüsselverwaltung, Clients, Hintergrund-Jobs, Ratenbegrenzung, Wiederholungen,
  Verbrauchsprotokoll, Statusprüfung

**Nicht enthalten:**
- Indexierung (AP4)
- Prompts für die Beurteilung (AP7)

## Voraussetzungen

- C4–C8 (Modelle, Grenzen); Schlüssel im Windows-Tresor, Proxy läuft (du)
- C1 (05.10.): Es gibt nur Schlüssel für die Produktion. Entwicklung, Staging und Produktion
  teilen sich Zählung, Kosten und das Limit von 120 Anfragen/min. Deshalb:
  - Automatische Tests und CI rufen die echte API nie auf (`Http::fake`).
  - Live-Aufrufe nur im Schnelltest (3.2) und gezielt, mit kleinen Testtexten.
  - Getrennte Schlüssel für Vorrang (C8) sind nicht zu erwarten; der Ratenbegrenzer (E3.1) muss
    das allein leisten.
- AP1 Schritt 1.7 (Rechte für Verwaltung)

## Entscheidungen

| Nr. | Frage | Vorschlag | Entschieden |
|---|---|---|---|
| E3.1 | Anteil der 120 Anfragen/min für interaktive Suche | 40/min reserviert, Rest für Hintergrund-Jobs; nach C8 anpassen | offen |
| E3.2 | Standardmodell für einfache Aufgaben | `chat-noreasoning`, `chat` nur für die Beurteilung (AP7) | offen |

## Schritte

- [x] **3.1** Schlüssel-Proxy (`tools/ki-proxy`), Sperr-Hook für Claude Code, gitleaks-Regel
- [ ] **3.2** Schnelltest über den Proxy, wenn du ihn gestartet hast. Nur Testtexte:
  - Modellverzeichnis
  - Dimension und Normalisierung von `embed` messen
  - `rerank`
  - `chat` mit Streaming

  → `docs/tests/ki-api-schnelltest.md`
- [ ] **3.3** Einstellungen KI-Schnittstelle:
  - Tabelle mit verschlüsselten Feldern
  - Verwaltungsmaske: Basis-URL, drei Schlüsselfelder (nur beschreibbar, Anzeige `zki_…a1b2`),
    Modellnamen, „Verbindung prüfen“
  - Protokolleintrag bei Änderung (ohne Wert)
  - In der Entwicklung zeigt die Basis-URL auf den Proxy, die Schlüssel bleiben leer.
- [ ] **3.4** Clients:
  - `Dokumentdienst` (einreichen, Status, Ergebnis Markdown/JSON)
  - `Embeddings` (Stapel; Instruct-Präfix für Suchanfragen nach C4)
  - `Rerank`
  - `Chat` (normal und Streaming)
- [ ] **3.5** Jobs und Ausfallsicherheit:
  - Ergebnisse abfragen im Abstand von 2 bis 10 s
  - Job-ID gleich nach dem Einreichen speichern, keine Doppel-Einreichung nach Timeout
  - Wiederholung bei 429 (Retry-After) und 5xx mit Backoff
  - Ratenbegrenzer nach E3.1
- [ ] **3.6** Verbrauchsprotokoll `ki_aufrufe`: Dienst, Modell, Dauer, Status, Tokens, Bezug.
  Keine Inhalte, keine Header.
- [ ] **3.7** Statusprüfung: Artisan-Befehl und Anzeige im Systemstatus (erreichbar, Antwortzeit,
  Auslastung); Alarm über AP11

## Abnahmekriterien

- „Verbindung prüfen“ zeigt alle Dienste grün.
- Die Schlüssel stehen nirgends im Klartext: nicht in der DB, nicht im Log, nicht in der Antwort
  der Maske.
- Ein Ausfall der API stoppt keine Seite; die Jobs laufen später weiter.

## Tests

- `Http::fake` für 200, 202, 409, 410, 404, 429, 5xx, Timeout und Streaming
- Ratenbegrenzer greift
- Log und Protokoll enthalten keinen Schlüssel
- Verwaltungsmaske nur für Administratoren

## Risiken

- Antworten von ITM fehlen (C4–C8): Werte messen (3.2) und Standardwerte konfigurierbar halten.