From 95ecb1c0eef56485e4a65e54b23aaca71861ef66 Mon Sep 17 00:00:00 2001
From: Gulum <gulum@rismer.de>
Date: Sat, 6 Jun 2026 07:37:42 +0200
Subject: [PATCH] FEAT-12a: provider setup docs (env vars per provider incl.
 TrueNAS compose placement)

---
 docs/ai-provider.md | 50 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)
 create mode 100644 docs/ai-provider.md

diff --git a/docs/ai-provider.md b/docs/ai-provider.md
new file mode 100644
index 0000000..139c314
--- /dev/null
+++ b/docs/ai-provider.md
@@ -0,0 +1,50 @@
+# KI-Anbieter für das Abgabe-Inserat (FEAT-12a)
+
+`POST /gerbils/sale-ad` spricht einen beliebigen **OpenAI-kompatiblen**
+Chat-Completions-Endpunkt an — kein SDK, nur drei Einstellungen (Sektion `AI`),
+gesetzt als **Umgebungsvariablen oder user-secrets, niemals in appsettings
+committen**. Fehlt eine der drei, antwortet der Endpunkt mit
+`503 {code:"AiKeyMissing"}` und die Oberfläche zeigt den deutschen Hinweis.
+
+| Variable | Bedeutung |
+|---|---|
+| `AI__BaseUrl` | Basis-URL des Anbieters (ohne `/chat/completions`) |
+| `AI__ApiKey` | API-Schlüssel (Bearer) |
+| `AI__Model` | Modellname des Anbieters |
+
+## Anbieter-Matrix (alle mit derselben Implementierung getestet)
+
+| Anbieter | `AI__BaseUrl` | Beispiel-`AI__Model` | Kosten |
+|---|---|---|---|
+| **Google Gemini** (vermutlich Julians Wahl) | `https://generativelanguage.googleapis.com/v1beta/openai` | `gemini-2.0-flash` | Free Tier |
+| **Groq** | `https://api.groq.com/openai/v1` | `llama-3.3-70b-versatile` | Free Tier |
+| **Mistral** | `https://api.mistral.ai/v1` | `mistral-small-latest` | Free Tier |
+| **Ollama** (lokal/TrueNAS) | `http://<host>:11434/v1` | `llama3.2` | kostenlos, lokal |
+
+Ollama ignoriert den Schlüssel — `AI__ApiKey=ollama` als Platzhalter setzen
+(die Einstellung darf nur nicht leer sein).
+
+## Setzen der Variablen
+
+**Entwicklung (PowerShell, vor dem AppHost-Start):**
+
+```powershell
+$env:AI__BaseUrl = 'https://generativelanguage.googleapis.com/v1beta/openai'
+$env:AI__ApiKey  = '<schlüssel>'
+$env:AI__Model   = 'gemini-2.0-flash'
+```
+
+oder per user-secrets im API-Projekt:
+`dotnet user-secrets set "AI:ApiKey" "<schlüssel>" --project GerbilManagerWebAPI` (usw.).
+
+**TrueNAS / Docker Compose** (für Dwights Ops-Doku): im `environment:`-Block des
+API-Containers —
+
+```yaml
+services:
+  webapi:
+    environment:
+      AI__BaseUrl: https://generativelanguage.googleapis.com/v1beta/openai
+      AI__ApiKey: ${AI_API_KEY}        # Wert in der TrueNAS-App/.env hinterlegen
+      AI__Model: gemini-2.0-flash
+```