harden system

MATRIX_PARAMS.md

@@ -1,4 +1,4 @@
-# Tabelle 1: Alle Parameter, die Retrieval beeinflussen (mit Kurz-Erklärung)
+# Alle Parameter, die Retrieval beeinflussen (mit Kurz-Erklärung)
 
 | Ebene | Ort | Parameter | Standard / aktuell | Zweck / Einfluss |
 |---|---|---|---:|---|

RAG_SYSTEM_OVERVIEW.md

@@ -0,0 +1,140 @@
+# RAG-System - Wie funktioniert das System?
+
+## Grundidee
+
+Dieses System ist ein sogenanntes **RAG-System** (Retrieval Augmented Generation).
+
+Das bedeutet:
+
+> Die KI antwortet nicht frei oder kreativ,  
+> sondern ausschließlich auf Basis der hier hinterlegten Wissensdokumente.
+
+Oder einfacher gesagt:
+
+Die KI „weiß“ nur das, was Sie ihr hier als Dokumente geben.
+
+---
+
+# Die drei Ebenen des Systems
+
+## 1. Dokumente (Ihre Wissensquelle)
+
+Sie laden Dokumente hoch (z. B. PDF, DOCX, Markdown, TXT).
+
+Diese Dokumente sind:
+
+- versioniert
+- unveränderlich gespeichert
+- die einzige Wissensgrundlage des Systems
+
+Wichtig:  
+Dokumente werden nicht direkt beantwortet, sondern technisch vorbereitet.
+
+---
+
+## 2. Ingest & Indexierung (technische Aufbereitung)
+
+Sobald ein Dokument aktiviert wird:
+
+1. Es wird in kleinere Textabschnitte („Chunks“) zerlegt
+2. Diese Chunks werden strukturiert gespeichert (NDJSON)
+3. Der Vektorindex wird vollständig neu aufgebaut
+
+Nur aktive Dokumentversionen werden berücksichtigt.
+
+Das System arbeitet deterministisch und reproduzierbar.
+
+---
+
+## 3. Anfrage & Antwort
+
+Wenn ein Nutzer im Frontend eine Frage stellt:
+
+1. Das System durchsucht den Index nach passenden Inhalten
+2. Relevante Textstellen werden ausgewählt
+3. Diese werden an das KI-Modell übergeben
+4. Die KI formuliert daraus eine Antwort
+
+Die KI erfindet keine Inhalte.  
+Sie formuliert ausschließlich das, was in Ihren Dokumenten steht.
+
+---
+
+# Steuerungsmöglichkeiten im Adminbereich
+
+Im Adminbereich können zentrale Parameter gesteuert werden.  
+Diese beeinflussen, wie das System antwortet und wie es Inhalte verarbeitet.
+
+## Modell- & Antwortparameter
+
+| Parameter | Bedeutung | Wirkung |
+|------------|------------|----------|
+| **Modell** | Auswahl des KI-Modells | Bestimmt Stil, Qualität und Sprachverhalten |
+| **Temperatur** | Kreativitätsgrad der Antwort | Niedrig = sachlich & stabil, Hoch = freier formuliert |
+| **Top K (LLM)** | Token-Auswahlbreite | Steuert Varianz bei der Wortauswahl |
+| **Top P** | Wahrscheinlichkeitsfilter | Begrenzt unplausible Wortkombinationen |
+| **Streaming** | Antwort wird live ausgegeben | Verbessert UX im Frontend |
+
+---
+
+## Retrieval- & Wissensparameter
+
+| Parameter | Bedeutung | Wirkung |
+|------------|------------|----------|
+| **vectorTopK** | Anzahl gefundener Chunks | Mehr = breiter Kontext, weniger = fokussierter |
+| **maxChunks** | Maximale Übergabe an das Modell | Begrenzt Kontextgröße |
+| **Tag-Routing aktiv** | Aktiviert Tag-Vorselektion | Präzisere Themenfilterung |
+| **Scoring-Version** | Bewertungslogik | Steuert Priorisierung relevanter Inhalte |
+
+---
+
+## Ingest- & Indexparameter
+
+| Parameter | Bedeutung | Wirkung |
+|------------|------------|----------|
+| **Chunk-Größe** | Länge eines Textabschnitts | Klein = präziser, Groß = mehr Kontext |
+| **Chunk-Overlap** | Überlappung zwischen Chunks | Verhindert Kontextverlust |
+| **Embedding-Modell** | Modell für Vektorisierung | Bestimmt Suchqualität |
+| **Global Reindex** | Vollständiger Neuaufbau | Erzwingt saubere Reproduzierbarkeit |
+
+---
+
+# Was bedeutet das für Sie als Admin?
+
+Sie steuern:
+
+- Welche Dokumente aktiv sind
+- Welche Versionen gültig sind
+- Wie Inhalte indexiert werden
+- Wie stark gefiltert wird
+- Wie das Modell antwortet
+
+Die Qualität der Antworten hängt direkt ab von:
+
+- der Dokumentstruktur
+- der Chunk-Logik
+- der Retrieval-Konfiguration
+- der Modellkonfiguration
+
+---
+
+# Grundprinzip des Systems
+
+> „Wir nutzen KI nicht, um kreativ zu raten,  
+> sondern um verlässlich auf Basis Ihres Wissens zu antworten.“
+
+Das System ist:
+
+- deterministisch
+- versioniert
+- governance-stabil
+- reproduzierbar
+
+---
+
+# Kurz zusammengefasst
+
+Dokumente → werden aufbereitet → indexiert → gezielt durchsucht → KI formuliert Antwort.
+
+Sie kontrollieren das Wissen.  
+Die KI formuliert es.

src/Intent/CatalogIntentLite.php

@@ -29,13 +29,13 @@ final class CatalogIntentLite
      * Minimaler Similarity-Score.
      * Verhindert Rauschen.
      */
-    private const MIN_SCORE = 0.50;
+    private const MIN_SCORE = 0.75;
 
     /**
      * Differenz zwischen Top1 und Top2,
      * damit kein unsicherer Treffer akzeptiert wird.
      */
-    private const AMBIGUITY_DELTA = 0.01;
+    private const AMBIGUITY_DELTA = 0.03;
 
     public function __construct(
         private readonly TagVectorSearchClient $tagVectorClient,

templates/admin/base.html.twig

@@ -147,6 +147,36 @@
 
     </div>
 </div>
+<script>
+    document.addEventListener('DOMContentLoaded', function () {
 
+        const requiredFields = document.querySelectorAll(
+            'input[required], select[required], textarea[required]'
+        );
+
+        requiredFields.forEach(field => {
+
+            const wrapper = field.parentElement;
+            if (!wrapper) return;
+
+            // Suche Label im gleichen Container
+            const label = wrapper.querySelector('label');
+            if (!label) return;
+
+            // Nicht doppelt markieren
+            if (label.dataset.requiredMarked) return;
+
+            const star = document.createElement('span');
+            star.textContent = ' *';
+            star.style.color = '#dc3545';
+            star.style.marginLeft = '4px';
+            star.style.fontWeight = '600';
+
+            label.appendChild(star);
+            label.dataset.requiredMarked = 'true';
+        });
+
+    });
+</script>
 </body>
 </html>

templates/admin/tag/index.html.twig

@@ -154,7 +154,8 @@
                     <label class="form-label small text-muted">Beschreibung</label>
                     <input class="form-control form-control-sm"
                            name="description"
-                           placeholder="Optional"/>
+                           placeholder="Semantische Beschreibung des Tags"
+                    required/>
                 </div>
 
                 <div class="mb-3">