# Upgrade-Hinweise: Learning + Web-KB

## Neue/empfohlene Variablen

```env
OLLAMA_NUM_PREDICT=768
OLLAMA_JSON_RETRIES=1

LEARNING_ENABLED=true
LEARNING_MAX_EXAMPLES=500
LEARNING_EXAMPLES_PER_CATEGORY=5

# Nur bei authentifiziertem Dashboard aktivieren:
KNOWLEDGE_WEB_EDIT_ENABLED=true
```

`KNOWLEDGE_DIR` bleibt statisch/read-only. Im Dashboard erzeugte Artikel werden automatisch unter `DATA_DIR/knowledge-managed/` gespeichert. Bestätigte Kategorie-Lernbeispiele liegen in `DATA_DIR/category-learning.json`.

## Gitea-Registry / Linux

Das Image weiterhin in Gitea bauen. Auf dem Zielsystem ist kein lokaler Build erforderlich:

```bash
export AGENT_IMAGE=gitea.example.de/organisation/glpi-ai-agent:latest
mkdir -p data knowledge
sudo chown 65532:65532 data
docker compose -f docker-compose.registry.yml up -d --pull always
```

Der statische Ordner `./knowledge` bleibt read-only. Da Web-KB und Lernspeicher unter `./data` liegen, müssen nur die Daten für UID/GID `65532:65532` beschreibbar sein.

## Sicherer Start

Für die ersten Lernläufe empfohlen:

```env
DRY_RUN=true
AUTO_CATEGORY=true
AUTO_REPLY=false
CATEGORY_CONFIDENCE=0.90
```

Im Dashboard anschließend Entscheidungen bestätigen/korrigieren. Erst nach genügend beobachteten Tickets Schwellwerte oder Schreibrechte anpassen.

## GLPI Knowledge Base Connector

Für den neuen read-only GLPI-KB-Sync ergänzen Sie bei Bedarf:

```env
KNOWLEDGE_ALLOWED_SOURCES=internal-kb,glpi-kb
GLPI_KB_ENABLED=true
GLPI_KB_PATH=auto
GLPI_KB_SYNC_INTERVAL=10m
GLPI_KB_LIMIT=500
GLPI_KB_SOURCE=glpi-kb
GLPI_KB_AUTO_REPLY=false
GLPI_KB_AUTO_REPLY_CATEGORY_IDS=
```

Der sichere Start ist `GLPI_KB_AUTO_REPLY=false`. Erst nachdem die importierten Artikel im Dashboard geprüft wurden, sollte `glpi-kb` optional in `KNOWLEDGE_AUTO_REPLY_SOURCES` aufgenommen und eine explizite Whitelist von GLPI-Knowledge-Base-Kategorie-IDs gesetzt werden.

## Hybrid Knowledge Scoring

Diese Version ersetzt den einzelnen Dokument-Cosine-Score durch ein Hybrid-Scoring mit Body-Chunks, Titel, Keywords und Kategorie-/Lernsignalen. Der bestehende `data/embeddings.json` Cache wird bei Bedarf automatisch im neuen Format aufgebaut; ein manuelles Löschen ist nicht erforderlich.

Für bestehende `.env`-Dateien werden folgende Werte empfohlen:

```env
KNOWLEDGE_MIN_SCORE=0.70
KNOWLEDGE_WEIGHT_SEMANTIC=0.50
KNOWLEDGE_WEIGHT_TITLE=0.25
KNOWLEDGE_WEIGHT_KEYWORDS=0.15
KNOWLEDGE_WEIGHT_CATEGORY=0.10
KNOWLEDGE_CHUNK_WORDS=160
KNOWLEDGE_CHUNK_OVERLAP_WORDS=30
KNOWLEDGE_MAX_CHUNKS_PER_DOC=24
```

Der neue Hybrid-Score ist nicht direkt mit alten Cosine-Scores vergleichbar. Nach dem Upgrade zunächst im Dry-Run beobachten und den Mindestscore anhand realer Tickets kalibrieren.

## Dashboard / Knowledge-Editor v2

Das Dashboard wurde grundlegend überarbeitet. Es zeigt jetzt:

- eine Betriebsübersicht mit GLPI-/Ollama-/GLPI-KB-Gesundheit,
- die effektiven, nicht geheimen ENV-Werte gruppiert nach Agent, Ollama, RAG, GLPI-KB und Kontextquellen,
- eine Detailansicht je Verarbeitung mit KI- und Policy-Entscheidung,
- die Top-Knowledge-Kandidaten inklusive Hybrid-, Semantik-, Titel-, Keyword- und Kategorie/Lernscore,
- die tatsächlich verwendeten Ticket-/KB-Chunks,
- kompakte Details zu Changes, Major Incidents, Uptime-Kuma-Störungen und Benutzergeräten,
- Filter für Verarbeitungen, Knowledge Base und Lernbeispiele.

### Geänderte Knowledge-API

Der Webeditor verwendet jetzt explizite CRUD-Semantik:

- `GET /api/knowledge/{id}` lädt einen Artikel frisch vom Server.
- `POST /api/knowledge` legt einen neuen Web-Artikel an und liefert bei einer bereits existierenden ID `409 Conflict`.
- `PUT /api/knowledge/{id}` aktualisiert ausschließlich einen bestehenden, Web-verwalteten Artikel.
- Die ID eines Artikels kann beim Bearbeiten nicht geändert werden.
- `DELETE /api/knowledge/{id}` löscht weiterhin nur Web-verwaltete Artikel.

Statische Git-/Datei-Artikel und synchronisierte GLPI-KB-Artikel bleiben read-only.

Neue Läufe speichern zusätzlich die Top-Knowledge-Kandidaten und kompakte Kontextdetails im Audit. Ältere `runs.jsonl`-Einträge bleiben kompatibel; dort sind diese neuen Detailfelder naturgemäß leer.


## Rich-Text-Antworten aus der GLPI Knowledge Base

Synchronisierte GLPI-KB-Artikel behalten ab dieser Version zwei getrennte Darstellungen:

- `text` / `answer`: bereinigter Plaintext für RAG, Ranking und LLM-Kontext.
- `answer_html`: originales GLPI-Rich-Text-Markup ausschließlich für die spätere Ticketantwort.

Dadurch bleiben bei Auto-Replies unter anderem Überschriften, Fett/Kursiv, Listen, Tabellen und Links erhalten. Das Rich-Text-Markup wird nicht an Ollama gesendet und beeinflusst keine Embeddings. Anrede und Signatur werden HTML-sicher um den KB-Inhalt ergänzt.

Es sind keine neuen ENV-Variablen erforderlich. Nach dem Upgrade führt der initiale GLPI-KB-Sync automatisch dazu, dass `answer_html` im lokalen GLPI-KB-Cache ergänzt wird.