Mit einem eigenen KI-Anbieter erweitern

Das ist eine Entwickler-Referenz zum Hinzufügen eines neuen KI-Anbieter-Adapters (Text-Modell, Bild-Modell oder beides) zur KI-Engine von Structura. Wenn du nur einen Anbieter in wp-admin auswählen willst, siehe KI-Einstellungen.

Die KI-Engine von Structura verwendet ein Adapter-Muster: Die Pipeline (Recherche → Entwurf → Bild) spricht mit einer kleinen Menge anbieter-agnostischer Interfaces, und jeder konkrete Anbieter — OpenAI, Gemini, Anthropic, Cloud — implementiert sie. Einen neuen Anbieter hinzuzufügen bedeutet, einen Adapter zu schreiben, der diese Interfaces erfüllt, und ihn bei der Engine zu registrieren.

Quelle der Wahrheit: functions/src/ai/engine.ts, specs/ai-provider-refactor-plan.md.

Was du schreiben wirst

Für einen Text-Anbieter:

Eine Klasse, die TextProviderAdapter implementiert, mit:
- id, displayName, supportedModels.
- generate(request): Promise<GenerationResult> — der Kernaufruf.
- estimateCost(request): Promise<CostEstimate> — genutzt für Cloud-Quota-Tracking und die Kostenzeile nach der Generierung auf der Protokoll-Seite.
- validateKey(key) — genutzt von Structura → Einstellungen → KI-Engine, um zu bestätigen, dass ein eingefügter Schlüssel vor dem Speichern gültig ist.

Für einen Bild-Anbieter:

Eine Klasse, die ImageProviderAdapter implementiert, mit:
- id, displayName, supportedSizes.
- generateImage(request): Promise<ImageResult>.
- validateKey(key).

Die meisten Adapter sind 150–300 Zeilen lang. Sieh dir die bestehenden OpenAIAdapter, GeminiAdapter und AnthropicAdapter für die Form an.

Den Adapter registrieren

Füge den Adapter der Export-Liste in functions/src/ai/providers/index.ts hinzu.
Füge ihn der Anbieter-Registry der Engine hinzu, sodass er für die Pipeline sichtbar ist.
Füge einen entsprechenden Eintrag im geteilten Typen-Paket (packages/types) hinzu, sodass die KI-Engine-Einstellungsseite des Clients die richtigen Formularfelder rendern kann.
Surface alle anbieterspezifischen Konfigurationen (z. B. ein Basis-URL-Override für selbst gehostete Modelle) im Einstellungsformular.

Tests

Das Adapter-Muster macht Adapter ausgezeichnet testbar:

Unit-teste deinen Adapter gegen aufgezeichnete Fixtures — keine echten API-Aufrufe in CI.
Füge Integrationstests gegen einen Dev-Schlüssel hinzu, falls möglich; gate sie hinter eine env-Variable, sodass CI ohne Schlüssel sie überspringen kann.

Siehe functions/src/ai/__tests__/ für die bestehenden Test-Muster.

Was die Engine deinem Adapter übergibt

Eine GenerationRequest sieht so aus:

prompt — die zusammengesetzten System- + User-Prompts für diese Stufe der Pipeline.
model — das vom Aufrufer bevorzugte Modell (dein Adapter kann ein Veto einlegen).
temperature, maxTokens usw.
context — strukturierte Metadaten (Kampagnen-ID, Stufenname) für deine Protokolle, niemals an das Modell übergeben.

Dein Adapter gibt ein GenerationResult zurück mit:

content — die Ausgabe des Modells.
usage — verbrauchte Tokens (oder Äquivalente).
costUsd — deine berechneten Kosten, sodass die Engine korrekt protokollieren und abrechnen kann.

Fehlerbehandlung

Adapter werfen typisierte Fehler:

AIAuthError — falscher Schlüssel, widerrufene Zugangsdaten.
AIRateLimitError — vorübergehende Drosselung.
AIQuotaError — Quota überschritten / Abrechnungsproblem.
AIProviderError — Sammelfehler für andere 4xx/5xx.

Die Engine nutzt den Typ, um zu entscheiden, ob sie wiederholt, den Durchlauf scheitern lässt oder eine spezifische Nachricht auf der Protokoll-Seite anzeigt.

Ausliefern

Sobald dein Adapter drin und getestet ist:

Schneide einen feat:-Commit. Das Changelog nennt den Anbieter automatisch.
Aktualisiere KI-Einstellungen mit den Setup-Schritten des neuen Anbieters (du schreibst zu diesem Zeitpunkt für Endnutzer, nicht für Entwickler).