# RetrieX v1.6.0 – Installationsanleitung

Stand: Version **1.6.0** auf Basis des aktuellen `rag-inprogress.zip`.

Diese Anleitung beschreibt eine codebasierte Neuinstallation des aktuellen Systems. Sie ersetzt ältere Installationshinweise, die noch von `rag.zip`, einem Stand vom 15.04.2026 oder einer rein statischen Chat-Startseite ausgehen.

---

## 1. Architektur des aktuellen Stands

RetrieX v1.6.0 besteht aus diesen Hauptbausteinen:

- Symfony 7.4 auf PHP 8.2+
- Doctrine ORM und Doctrine Migrations
- MariaDB/MySQL-orientierte Migrationen mit binären UUIDs
- dateibasierte Knowledge-Artefakte unter `var/knowledge`
- Python-Vektorlayer mit FastAPI, uvicorn, FAISS und SentenceTransformers
- Ollama-kompatibler LLM-Generate-Endpunkt über `AI_LLM_API_URL`
- hybrides Retrieval über NDJSON, FAISS, Keyword-/Lexical-Komponenten und Tag-Routing
- optionaler Shopware-Store-API-Commercepfad
- Twig-basierte Chat- und Adminoberflächen
- Job-basierter SSE-Flow für Browserantworten
- getrennte Admin- und Chat-Firewalls mit Rollenmodell
- Admin-Benutzerverwaltung, Fehlerseiten und Access-Denied-UX
- Config-/Governance-/Regression-Commands für sichere Änderungen

Wichtige Ordner:

```text
var/knowledge/        NDJSON, FAISS-Indizes, Tags, Uploads
var/log/              Symfony-, Agent-, Ingest- und Vector-Logs
var/run/              PID-Dateien, z. B. vector_service.pid
var/locks/            globale Locks, z. B. ingest.lock
python/vector/        Python-Control-, Search- und Ingest-Skripte
config/retriex/       Runtime-, Retrieval-, Commerce-, Prompt- und Genre-Konfiguration
```

---

## 2. Wichtige Änderungen gegenüber älteren Ständen

- Das Chat-Frontend läuft nicht mehr über eine statische `public/index.html`, sondern über `App\Controller\Chat\ChatController` mit `/` und `/chat`.
- Chat- und Adminbereiche sind architektonisch und sicherheitsseitig getrennt.
- Admin-Routen liegen unter `/admin...`; Chat-/Ask-/SSE-/History-Routen liegen in der Chat-Firewall.
- `ROLE_USER` allein reicht nicht mehr für Chat oder Admin.
- `ROLE_CHAT_USER` schaltet Chat-Zugriff frei.
- `ROLE_ADMIN_AREA`, `ROLE_EDITOR`, `ROLE_KNOWLEDGE_ADMIN` und `ROLE_SUPER_ADMIN` schalten Adminbereiche gestuft frei.
- Die CLI umfasst inzwischen 21 projektspezifische Commands unter `mto:agent:*`.
- `mto:agent:test:shop-search` unterstützt jetzt `--intent`, `--history` und optional `--repair`; die ältere Warnung über eine falsche Service-Signatur ist nicht mehr zutreffend.
- Der produktive Loader unterstützt PDF, TXT und Markdown (`.md`).
- `genre.yaml` ist die zentrale fachliche Source-of-Truth für Produktrollen, Query-Guards, Follow-up-Auflösung und Regression-Anker.

---

## 3. Systemvoraussetzungen

### 3.1 Betriebssystem

Empfohlen:

- Linux Server oder VM
- Ubuntu 22.04/24.04 oder Debian 12

Lokal ist Entwicklung auch auf macOS oder WSL möglich, produktiv sollte ein regulärer Webserver mit PHP-FPM verwendet werden.

### 3.2 PHP

Erforderlich:

- PHP 8.2 oder neuer
- Composer

Relevante PHP-Erweiterungen aus `composer.json` und Runtime:

- `ctype`
- `curl`
- `dom`
- `iconv`
- `libxml`
- `pdo_mysql`
- `mbstring`
- `zip`
- `sqlite3`

Prüfen:

```bash
php -v
php -m
composer --version
```

### 3.3 Datenbank

Die mitgelieferten Migrationen sind praktisch auf MariaDB/MySQL ausgelegt, z. B. durch `BINARY(16)`, `TINYINT`, `LONGTEXT`, `JSON` und MariaDB-kompatible UUID-Strukturen.

Empfohlen:

- MariaDB 10.11.x oder kompatibles MySQL 8.x

Beispiel:

```sql
CREATE DATABASE retriex CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'retriex'@'%' IDENTIFIED BY 'change-me';
GRANT ALL PRIVILEGES ON retriex.* TO 'retriex'@'%';
FLUSH PRIVILEGES;
```

Die mitgelieferte `.env` kann noch Platzhalter enthalten. Für Betrieb eine eigene `.env.local` verwenden.

### 3.4 Python

Erforderlich:

- Python 3.10 oder neuer
- `python3-venv`
- `python3-pip`

Python-Abhängigkeiten aus `requirements.txt`:

- `fastapi`
- `uvicorn`
- `faiss-cpu`
- `sentence-transformers`
- `numpy`

### 3.5 LLM-Endpunkt

RetrieX spricht den LLM über `AI_LLM_API_URL` an. Erwartet wird ein Ollama-kompatibler `/api/generate`-Endpoint.

Beispiel:

```bash
curl http://127.0.0.1:11434/api/tags
```

Das konkret verwendete Modell wird über die aktive `ModelGenerationConfig` im Admin gesteuert, nicht allein über `.env`.

### 3.6 Optional: Shopware Store API

Für Commerce-/Shopfragen kann die Shopware Store API angebunden werden.

Relevante Variablen:

- `SHOPWARE_STORE_API_BASE_URL`
- `SHOPWARE_SALES_CHANNEL_ACCESS_KEY`
- `SHOPWARE_STORE_API_MAX_RESULT`

Wenn keine Shopware-Suche gewünscht ist, Commerce bewusst deaktivieren oder sauber mit leeren/ungefährlichen Testwerten konfigurieren.

---

## 4. Projekt bereitstellen

Beispiel mit ZIP:

```bash
unzip rag-inprogress.zip -d retriex
cd retriex
```

Oder über Repository-Checkout, falls der Stand in Git verwaltet wird.

---

## 5. PHP-Abhängigkeiten installieren

Entwicklung:

```bash
composer install --no-interaction
```

Produktion:

```bash
composer install --no-dev --optimize-autoloader --no-interaction
```

Danach sollte `bin/console` ausführbar sein:

```bash
php bin/console list mto:agent
```

---

## 6. Umgebung konfigurieren

Eine lokale `.env.local` anlegen und mindestens Datenbank und LLM-Endpunkt setzen.

Beispiel:

```dotenv
APP_ENV=prod
APP_SECRET=change-me
DATABASE_URL="mysql://retriex:change-me@127.0.0.1:3306/retriex?serverVersion=10.11.2-MariaDB&charset=utf8mb4"
AI_LLM_API_URL="http://127.0.0.1:11434/api/generate"
```

Optional für Shopware:

```dotenv
SHOPWARE_STORE_API_BASE_URL="https://example.invalid/store-api"
SHOPWARE_SALES_CHANNEL_ACCESS_KEY="change-me"
SHOPWARE_STORE_API_MAX_RESULT=10
```

Wichtig: keine produktiven Secrets in die versionierte `.env` schreiben.

---

## 7. Datenbank initialisieren

```bash
php bin/console doctrine:database:create --if-not-exists
php bin/console doctrine:migrations:migrate --no-interaction
```

Bei Produktionsbetrieb danach Cache aufbauen:

```bash
php bin/console cache:clear --env=prod
php bin/console cache:warmup --env=prod
```

---

## 8. Python-Umgebung aufbauen

Virtuelle Umgebung anlegen:

```bash
python3 -m venv .venv
source .venv/bin/activate
```

Abhängigkeiten installieren:

```bash
pip install --upgrade pip
pip install -r requirements.txt
```

Alternativ nach angelegter `.venv` über den Symfony-Wrapper:

```bash
php bin/console mto:agent:vector:control --install
```

Der Wrapper erwartet eine vorhandene `.venv`; er legt sie nicht selbst an.

---

## 9. Vector-Service starten

Start:

```bash
php bin/console mto:agent:vector:control --start
```

Status:

```bash
php bin/console mto:agent:vector:control --status
```

Reload:

```bash
php bin/console mto:agent:vector:control --reload
```

Standardwerte aus dem aktuellen Command/Service-Setup:

- Host: `0.0.0.0`
- Port: `8090`
- PHP-Service-URL: typischerweise `http://127.0.0.1:8090`
- PID-Datei: `var/run/vector_service.pid`

---

## 10. Ersten Benutzer anlegen

Ohne Benutzer ist weder Chat noch Admin sinnvoll nutzbar.

```bash
php bin/console mto:agent:user:create
```

Der Command fragt ab:

- E-Mail
- Passwort mit Wiederholung
- eine oder mehrere Rollen
- Aktivstatus

Für die Erstinstallation ist typischerweise `ROLE_SUPER_ADMIN` sinnvoll. Diese Rolle enthält über die Hierarchie auch Admin-, Editor-, Knowledge-Admin- und Chat-Rechte.

---

## 11. Anwendung starten

Lokaler Test:

```bash
php -S 127.0.0.1:8000 -t public
```

Relevante Einstiegspunkte:

- Chat: `http://127.0.0.1:8000/`
- Chat-Login: `http://127.0.0.1:8000/chat/login`
- Admin-Login: `http://127.0.0.1:8000/admin/login`

Für Produktion Nginx/Apache + PHP-FPM verwenden und `public/` als Document Root setzen.

---

## 12. Pflicht-Initialisierung im Admin

### 12.1 System Prompt anlegen

Pfad:

```text
/admin/system/prompt
```

Ohne aktiven System Prompt kann der finale PromptBuilder keine saubere Antwortgrundlage erzeugen.

### 12.2 ModelGenerationConfig anlegen

Pfad:

```text
/admin/model-config/
```

Sinnvolle Startwerte:

| Feld | Beispiel |
| --- | --- |
| Modellname | `qwen3:latest` oder der lokal verfügbare Ollama-Name |
| Streaming | aktiv |
| Temperature | `0.2` bis `0.4` |
| Top K | `40` |
| Top P | `0.9` |
| Repeat Penalty | `1.1` |
| num_ctx | `8192` oder höher, passend zum Modell |
| Retrieval Max Chunks | `25` |
| Retrieval Vector Top K | `25` |

### 12.3 Optional: Ingest-Profil prüfen

Pfad:

```text
/admin/ingest-profiles/
```

Wenn kein Profil aktiv ist, gelten die Fallbackwerte aus der technischen Konfiguration. Für produktive Systeme sollte ein bewusstes Profil gepflegt werden.

---

## 13. Dokumente ingestieren

Unterstützte Formate im aktuellen Ingest-Loader:

- `.pdf`
- `.txt`
- `.md`

Ablauf im Admin:

1. Als Benutzer mit `ROLE_EDITOR` oder höher einloggen.
2. Dokument anlegen oder öffnen.
3. Version hochladen.
4. Version ingestieren bzw. aktivieren.
5. Ingest-Job prüfen.
6. Danach Vector-/Tag-Health prüfen.

CLI-Ingest einer konkreten Version:

```bash
php bin/console mto:agent:ingest:version <documentVersionUuid> <userUuid>
```

Vorhandenen Job ausführen:

```bash
php bin/console mto:agent:ingest:run <jobUuid>
```

---

## 14. Rebuild und Konsistenzprüfung

Vollständiger Hard-Rebuild:

```bash
php bin/console mto:agent:system:rebuild --hard
```

Optionen:

```bash
php bin/console mto:agent:system:rebuild --hard --dry-run
php bin/console mto:agent:system:rebuild --hard --no-tags
php bin/console mto:agent:system:rebuild --hard --no-reload
php bin/console mto:agent:system:rebuild --hard --no-health
```

Health-Checks:

```bash
php bin/console mto:agent:vector:health
php bin/console mto:agent:tag:health --summary
```

Tag-Retrieval neu aufbauen:

```bash
php bin/console mto:agent:tags:rebuild
```

---

## 15. Governance-Checks nach Installation oder Änderungen

Für Konfigurations- und Prompt-/Retrieval-/Commerce-Änderungen:

```bash
php bin/console mto:agent:config:validate
php bin/console mto:agent:config:audit-source --details
php bin/console mto:agent:config:audit-patterns --details
php bin/console mto:agent:regression:test
```

Zur Übersicht:

```bash
php bin/console mto:agent:config:dump-effective --summary
```

Für reale Pfadtests:

```bash
php bin/console mto:agent:retrieval:test "niedrigster Grenzwert Wasserhärte"
php bin/console mto:agent:test:shop-search "testomat 808 300 indikator" --repair
php bin/console mto:agent:chat cli-debug
```

---

## 16. Rollenmodell für den Betrieb

| Rolle | Zweck |
| --- | --- |
| `ROLE_CHAT_USER` | Zugriff auf Chat, Ask/SSE, History und Frontend-Messages |
| `ROLE_ADMIN_AREA` | Adminbasis, Dashboard, Guides und Jobübersicht |
| `ROLE_EDITOR` | Dokumente, Versionen, Tags und Dokument-Ingest |
| `ROLE_KNOWLEDGE_ADMIN` | Modell-/Retrieval-Konfiguration und Ingest-Profile |
| `ROLE_SUPER_ADMIN` | Userverwaltung, Logs, System Prompt/Agent, kritische Aktionen, Global Reindex |

`ROLE_SUPER_ADMIN` enthält alle darunterliegenden Rollen. `ROLE_USER` ist nur technische Basisrolle.

---

## 17. Minimaler Go-Live-Check

Vor produktiver Nutzung prüfen:

- `.env.local` enthält produktive DB-, LLM- und ggf. Shopware-Werte.
- Datenbankmigrationen sind durchgelaufen.
- Mindestens ein aktiver `ROLE_SUPER_ADMIN` existiert.
- Mindestens ein aktiver Chat-User existiert.
- Aktiver System Prompt ist vorhanden.
- Aktive ModelGenerationConfig ist vorhanden.
- Vector-Service läuft.
- Mindestens ein aktives Dokument ist ingestiert.
- `mto:agent:vector:health` ist grün.
- `mto:agent:tag:health --summary` ist grün oder bewusst initial leer.
- `mto:agent:config:validate` ist grün.
- `mto:agent:regression:test` ist grün.
- Chat-Login und Admin-Login sind getrennt erreichbar.
- 403/404/500-Seiten funktionieren im gewünschten Layout.

---

## 18. Häufige Fehlerbilder

### `No active system prompt configured.`

Im Admin einen System Prompt anlegen und aktivieren.

### `No active ModelGenerationConfig found.`

Im Admin unter `/admin/model-config/` eine Modellkonfiguration anlegen und aktivieren.

### Vector-Service startet nicht

Prüfen:

```bash
source .venv/bin/activate
pip install -r requirements.txt
php bin/console mto:agent:vector:control --status
```

Außerdem prüfen, ob Port `8090` frei ist und `python/vector/vector_control.py` existiert.

### Rebuild bricht mit `no active documents found` ab

Mindestens ein Dokument und eine aktive, ingestierte Version anlegen.

### Chat zeigt Access Denied

Der Benutzer braucht `ROLE_CHAT_USER` oder eine übergeordnete Rolle.

### Admin zeigt Access Denied

Der Benutzer braucht mindestens `ROLE_ADMIN_AREA`; für Dokumente `ROLE_EDITOR`, für Modell-/Ingest-Konfiguration `ROLE_KNOWLEDGE_ADMIN`, für Userverwaltung und kritische Systemaktionen `ROLE_SUPER_ADMIN`.

### Nicht-PDF-Ingest

TXT und Markdown werden im aktuellen `DocumentLoader` unterstützt. Für andere Formate wie DOCX gibt es im aktuellen produktiven Ingest-Pfad keinen verifizierten Loader.

---

## 19. Produktionshinweise

- Webserver auf `public/` zeigen lassen.
- Schreibrechte für `var/` sicherstellen.
- `APP_ENV=prod` und `APP_DEBUG=0` setzen.
- Secrets nur in `.env.local` oder Secret-Management pflegen.
- Vector-Service über systemd, Supervisor oder Container-Prozessmanagement betreiben.
- Logs rotieren.
- Rebuilds nicht parallel ausführen.
- Vor Änderungen an `genre.yaml`, `commerce.yaml`, `prompt.yaml` oder Retrieval-Konfiguration immer Governance-Checks ausführen.
- Regelmäßig ein Backup von Datenbank und `var/knowledge` erstellen.

---

## 20. Ergebnis

Nach Abschluss der Installation stehen zur Verfügung:

- rollenbasierter Chat unter `/` und `/chat`
- rollenbasierter Adminbereich unter `/admin`
- dokumentenbasierter RAG-Ingest
- hybrides Retrieval mit Vector- und Tag-Komponenten
- optionaler Shopware-Commercepfad
- SSE-Streaming für Browserantworten
- CLI-Werkzeuge für Ingest, Rebuild, Health, Governance und Debugging