feat(agent): add index bootstrap and answer feedback

docs/API.md

@@ -23,6 +23,7 @@ Aufbewahrung. Ein allgemeiner API-Key allein reicht dafür nicht aus.
 |---|---|---|---|
 | `GET` | `/` | Eingabe im UI | Test-Frontend |
 | `POST` | `/v1/ask` | Service-Key | belegte Wissensantwort |
+| `POST` | `/v1/ratings` | Service-Key | Antwort bewerten |
 | `GET` | `/v1/health` | öffentlich | Readiness ohne interne Hostdetails |
 | `POST` | `/v1/reindex` | Admin-Key | Index nach KB-Änderung neu aufbauen |
 
@@ -147,10 +148,40 @@ Response (gekürzt):
   in v1 aber leer. Der Dienst errät diese Strukturen nicht aus Freitext; ihre
   spätere Befüllung benötigt einen eigenen belegbaren Generierungsvertrag.
 - `grounding.data_scope=knowledge_base_only` ist in v1 unveränderlich.
+- `ratings_enabled` zeigt, ob diese Antwort über `/v1/ratings` bewertet werden
+  kann.
 
 Der Client darf `verified=false` nicht als normale Fachantwort darstellen.
 Empfohlen ist ein sichtbarer Warnzustand ohne automatische Folgeverarbeitung.
 
+## `POST /v1/ratings`
+
+Eine zuvor protokollierte Antwort kann über ihre `request_id` bewertet werden:
+
+```json
+{
+  "request_id": "odoo-request-123",
+  "rating": "up",
+  "feedback": "Die Quellen beantworten die Frage nachvollziehbar."
+}
+```
+
+`rating` ist `up` oder `down`, `feedback` optional und auf 1.000 Zeichen
+begrenzt. Pro Antwort wird eine Bewertung gespeichert; ein weiterer Request
+aktualisiert sie. Unbekannte Request-IDs liefern `404`, deaktiviertes Audit
+`503`. Das Frontend blendet die Bewertungsfunktion nur bei
+`ratings_enabled=true` ein.
+
+## Audit-Protokoll
+
+Bei `PV_AUDIT_ENABLED=true` werden Interaktionen und Bewertungen in der über
+`PV_AUDIT_DB_PATH` festgelegten SQLite-Datei gespeichert. Mit
+`PV_AUDIT_STDOUT=true` werden strukturierte JSON-Ereignisse zusätzlich mit dem
+Präfix `AUDIT ` nach stdout geschrieben. `PV_AUDIT_LOG_CONTENT=false` entfernt
+Freitext einschließlich Frage, Antwort, Quellenbeschreibungen, Konflikten,
+Suchplan und Bewertungskommentar; technische Metriken und KB-IDs bleiben.
+API-Key und Authorization-Header werden nie protokolliert.
+
 ## Request-Korrelation
 
 Ein Client kann einen technisch neutralen Header mitsenden:

docs/DOCKER.md

@@ -2,14 +2,14 @@
 
 Der Compose-Stack betreibt Test-Frontend und FastAPI-Agent gemeinsam. Er startet
 keinen zweiten Ollama-Container, sondern verbindet sich mit dem vorhandenen
-externen Docker-Netz `ollama-default`.
+externen Docker-Netz `ollama_default`.
 
 ## Voraussetzungen
 
 Auf dem Zielhost müssen vorhanden sein:
 
 - Docker Engine mit Compose-Plugin;
-- das externe Netz `ollama-default`;
+- das externe Netz `ollama_default`;
 - ein darin erreichbarer Ollama-Container;
 - die Modelle `qwen3.8:27b` und `bge-m3` in dieser Ollama-Instanz;
 - `wissensbasis/` und entweder ein vorhandenes `data/index.db` oder genügend
@@ -18,7 +18,7 @@ Auf dem Zielhost müssen vorhanden sein:
 Das Netz und seine Container/Aliase prüfen:
 
 ```bash
-docker network inspect ollama-default
+docker network inspect ollama_default
 ```
 
 Der Compose-Beispielwert nimmt den DNS-Namen `ollama` und den internen
@@ -47,12 +47,24 @@ Dann `.env` anpassen:
 3. `OLLAMA_URL` anhand des Netzwerk-Alias prüfen;
 4. `PUID`/`PGID` auf den Besitzer von `data/` setzen.
 
+Vor dem ersten Start das gitignored Bind-Mount mit diesen IDs anlegen (Beispiel
+für `1000:1000`):
+
+```bash
+mkdir -p data
+sudo chown 1000:1000 data
+```
+
+Ohne diesen Schritt kann Docker ein fehlendes Verzeichnis als `root` anlegen;
+der absichtlich unprivilegierte Agent könnte dann weder `index.db` noch
+`audit.db` schreiben.
+
 `.env` ist gitignored und darf nicht committed werden. Compose verwendet die
 Datei nur zur Interpolation der ausdrücklich in `compose.yaml` aufgelisteten
 Variablen; sonstige lokale Secrets werden nicht pauschal in den Container
 durchgereicht.
 
-## Start mit vorhandenem Index
+## Start und automatischer Index-Bootstrap
 
 ```bash
 docker compose build
@@ -61,6 +73,21 @@ docker compose ps
 docker compose logs --follow pv-agent
 ```
 
+Vor dem API-Start führt das Image automatisch `python -m agent.bootstrap` aus.
+Der Bootstrap prüft, ob `data/index.db` Chunks und vollständige Vektoren für das
+konfigurierte Embedding-Modell enthält. Fehlt der Index oder ist er
+unvollständig, wird er aus dem read-only eingebundenen `wissensbasis/` über
+Ollama neu erzeugt. Erst danach startet FastAPI. Schlägt die Einbettung fehl,
+beendet sich der Container bewusst mit Fehler, statt einen unvollständigen
+Produktionsindex zu verwenden.
+
+Der Index wird absichtlich beim **ersten Containerstart**, nicht in einem
+Dockerfile-`RUN` erzeugt: Nur zur Laufzeit ist das externe Netz
+`ollama_default` zuverlässig verfügbar, und der Index bleibt als Hostdatenstand
+in `./data`, statt veraltet im Image zu liegen. Beim ersten Lauf kann der Start
+mehrere Minuten dauern; der Healthcheck hat dafür eine Startfrist von 15
+Minuten.
+
 Aufruf im Tailscale-Netz:
 
 ```text
@@ -69,25 +96,16 @@ http://100.103.83.12:8080/
 
 Im Frontend denselben Wert wie `PV_API_KEY` als Service-Key eingeben.
 
-## Initialen Index im Container bauen
-
-Falls `data/index.db` auf dem Zielhost noch fehlt:
-
-```bash
-mkdir -p data
-docker compose run --rm pv-agent python -m agent.cli ingest
-```
-
-Der Lauf verwendet `bge-m3` über `OLLAMA_URL` und schreibt den Index in das
-Bind-Mount `./data`. Danach den Dienst starten:
+Der Prozess läuft als `PUID:PGID`. `data/` muss für diese IDs schreibbar sein,
+damit Bootstrap, Audit-Log und `/v1/reindex` funktionieren. Ein manueller,
+erzwungener Neuaufbau bleibt möglich:
 
 ```bash
+docker compose down
+rm data/index.db
 docker compose up -d
 ```
 
-Der Prozess läuft als `PUID:PGID`. `data/` muss für diese IDs schreibbar sein,
-insbesondere wenn `/v1/reindex` verwendet werden soll.
-
 ## Smoke-Tests
 
 ```bash
@@ -103,6 +121,41 @@ curl --fail \
 der Regel, dass der Index fehlt oder Ollama unter dem konfigurierten
 Container-DNS-Namen nicht erreichbar ist.
 
+## Fragen-, Antwort- und Bewertungsprotokoll
+
+Compose aktiviert standardmäßig ein detailliertes Audit:
+
+- `data/audit.db`: persistente SQLite-Datenbank mit Request-ID, Frage, Antwort,
+  Status, Zitaten, Quellen, Konflikten, Suchplan, Modell, Laufzeit und
+  Regenerierungen;
+- Tabelle `ratings`: Daumen hoch/runter plus optionaler Kommentar;
+- `docker compose logs --follow pv-agent`: dieselben Ereignisse als mit
+  `AUDIT ` präfixierte JSON-Zeilen für die Betriebsdiagnose; Docker rotiert
+  diese Logs bei 50 MB und behält fünf Dateien.
+
+Letzte Einträge strukturiert anzeigen:
+
+```bash
+docker compose exec pv-agent python -m agent.cli audit --limit 20
+```
+
+Standardaufbewahrung: 30 Tage; Bereinigung erfolgt beim Öffnen des Audit-Stores.
+Konfiguration:
+
+```dotenv
+PV_AUDIT_ENABLED=true
+PV_AUDIT_LOG_CONTENT=true
+PV_AUDIT_STDOUT=true
+PV_AUDIT_RETENTION_DAYS=30
+```
+
+Fragen und Antworten können sensible Freitexte enthalten. Zugriff auf
+`data/audit.db`, Backups und Docker-Logs ist deshalb auf Administratoren zu
+beschränken. Mit `PV_AUDIT_LOG_CONTENT=false` bleiben nur technische Metadaten
+und KB-IDs erhalten; Frage, Antwort, Quellenbeschreibungen, Konflikttext,
+Suchplan und Bewertungskommentar werden dann nicht gespeichert oder nach stdout
+geschrieben. API-Keys und Authorization-Header werden nie protokolliert.
+
 ## Sicherheitsprofil
 
 - Port `8080` wird nur an die Tailscale-Adresse `100.103.83.12` gebunden.