add new guide files

2026-02-26 21:07:24 +01:00
parent a68f5182e4
commit 71f86f112b
2 changed files with 696 additions and 0 deletions
--- a/COMMAND_REF.md
+++ b/COMMAND_REF.md
@@ -0,0 +1,294 @@
+# RAG System – CLI Command Reference
+**Projektstand: rag.zip (aktueller Code-Stand)**  
+Namespace-Konvention: `mto:agent:*`
+
+Diese Dokumentation beschreibt alle verfügbaren Symfony-Console-Commands des Systems inklusive Zweck, Einsatzszenario und typischer Aufrufe.
+
+---
+
+# 1. Agent / Chat
+
+## `mto:agent:chat`
+Interaktiver CLI-Chat mit dem Agenten.
+
+**Zweck**
+- Direkter Zugriff auf AgentRunner
+- Streaming-Ausgabe im Terminal
+- Nutzt vollständige Retrieval- und Prompt-Logik
+
+**Start**
+```bash
+bin/console mto:agent:chat
+```
+
+**Eigenschaften**
+- Streaming-first
+- Think-Suppression wird im AgentRunner gesteuert
+- Voller Kontext + Retrieval aktiv
+
+---
+
+# 2. Dokument-Ingest
+
+## `mto:agent:ingest:version`
+Ingest einer konkreten Dokumentversion.
+
+**Zweck**
+- Chunking
+- NDJSON-Append / Compaction
+- Vollständiger FAISS-Rebuild
+- index_meta.json Update
+
+**Beispiel**
+```bash
+bin/console mto:agent:ingest:version <documentVersionUuid>
+```
+
+---
+
+## `mto:agent:ingest:run`
+Führt einen einzelnen IngestJob aus.
+
+**Zweck**
+- Job-basierte Verarbeitung (QUEUE → RUNNING → COMPLETED/FAILED)
+- Wird intern bei Aktivierung einer Dokumentversion verwendet
+
+**Beispiel**
+```bash
+bin/console mto:agent:ingest:run <jobUuid>
+```
+
+---
+
+## `mto:agent:vector:rebuild`
+Erzwingt vollständigen Vector-Rebuild aus `index.ndjson`.
+
+**Zweck**
+- FAISS komplett neu aufbauen
+- Kein Re-Chunking
+- Reine Vektor-Neuerstellung
+
+```bash
+bin/console mto:agent:vector:rebuild
+```
+
+---
+
+# 3. Vector Service (Python / FastAPI)
+
+## `mto:agent:vector:control`
+Steuert den persistenten Python-Vector-Service.
+
+**Beschreibung**
+Production-sicheres Management des uvicorn-FastAPI-Dienstes.
+
+### Optionen
+
+| Option | Beschreibung |
+|--------|--------------|
+| `--install` | Fehlende Python-Dependencies installieren |
+| `--start` | Service starten |
+| `--stop` | Service stoppen |
+| `--force` | Hard-Stop (SIGKILL) |
+| `--reload` | /reload Trigger |
+| `--status` | Status anzeigen |
+| `--foreground` | Vordergrundstart |
+| `--port=8090` | Port |
+| `--host=0.0.0.0` | Host |
+
+### Beispiele
+
+Installieren:
+```bash
+bin/console mto:agent:vector:control --install
+```
+
+Starten:
+```bash
+bin/console mto:agent:vector:control --start
+```
+
+Status:
+```bash
+bin/console mto:agent:vector:control --status
+```
+
+Reload:
+```bash
+bin/console mto:agent:vector:control --reload
+```
+
+---
+
+## `mto:agent:vector:health`
+Gesundheitscheck von:
+
+- index.ndjson
+- vector.index
+- index_meta.json
+- Embedding-Dimensionen
+- Konsistenz
+
+```bash
+bin/console mto:agent:vector:health
+```
+
+Ausgabe erfolgt als JSON.
+
+---
+
+## `mto:agent:test-vector`
+Testet direkte Vector-Suche.
+
+```bash
+bin/console mto:agent:test-vector "Suchanfrage"
+```
+
+---
+
+# 4. Tag-System
+
+## `mto:agent:tags:export`
+Exportiert alle Tags in `tags.ndjson`.
+
+**Zweck**
+- Grundlage für tag-basiertes Routing
+- Keine Vector-Erstellung
+
+```bash
+bin/console mto:agent:tags:export
+```
+
+---
+
+## `mto:agent:tags:rebuild`
+Vollständiger Tag-Rebuild:
+
+1. Export `tags.ndjson`
+2. Erstellen von `vector_tags.index`
+3. index_meta.json Update
+
+```bash
+bin/console mto:agent:tags:rebuild
+```
+
+---
+
+## `mto:agent:tags:job:run`
+Führt einen einzelnen TagRebuildJob aus.
+
+**Mit Lock-Mechanismus.**
+
+```bash
+bin/console mto:agent:tags:job:run <jobUuid>
+```
+
+---
+
+# 5. User-Management
+
+## `mto:agent:user:create`
+Erstellt einen neuen Admin-User.
+
+Interaktiver Ablauf:
+- E-Mail
+- Passwort
+- Rollenwahl
+
+```bash
+bin/console mto:agent:user:create
+```
+
+---
+
+# 6. Architektur-Zusammenhang der Commands
+
+| Bereich | Command-Typ |
+|----------|------------|
+| Dokumente | ingest:version |
+| Jobs | ingest:run |
+| Vector Index | vector:rebuild |
+| Vector Service | vector:control |
+| Vector Health | vector:health |
+| Tag Export | tags:export |
+| Tag Rebuild | tags:rebuild |
+| Tag Job | tags:job:run |
+| Agent CLI | chat |
+| User | user:create |
+
+---
+
+# 7. Typischer Produktions-Workflow
+
+### 1️⃣ Dokument aktivieren
+→ erzeugt IngestJob
+
+### 2️⃣ Job ausführen
+```bash
+bin/console mto:agent:ingest:run <jobUuid>
+```
+
+### 3️⃣ Vector-Service prüfen
+```bash
+bin/console mto:agent:vector:health
+```
+
+### 4️⃣ Optional: Service reload
+```bash
+bin/console mto:agent:vector:control --reload
+```
+
+---
+
+# 8. System-Ebenen
+
+| Ebene | Technologie |
+|--------|------------|
+| Symfony | PHP / Doctrine |
+| Retrieval | NDJSON + FAISS |
+| Vector Service | Python FastAPI |
+| Persistence | index.ndjson |
+| Governance | index_meta.json |
+| Streaming | SSE |
+| CLI | Symfony Console |
+
+---
+
+# 9. Wichtige Dateien (Runtime)
+
+```
+var/
+ ├── run/
+ │    └── vector.pid
+ ├── index.ndjson
+ ├── index_meta.json
+ ├── vector.index
+ └── vector_tags.index
+```
+
+---
+
+# 10. Sicherheit & Locks
+
+- IngestFlow schützt mit LockService
+- Tag-Rebuild verwendet File-Lock
+- Vector-Service PID-basiert
+- Global Rebuild atomar via `.tmp` + rename()
+
+---
+
+# 11. Empfohlene Admin-Checks
+
+Regelmäßig ausführen:
+
+```bash
+bin/console mto:agent:vector:health
+```
+
+Bei Änderungen am Embedding-Modell:
+→ vollständiger Rebuild
+
+---
+
+# Ende der Command-Dokumentation
+System-Stand: rag.zip (aktueller Projektzustand)
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -0,0 +1,402 @@
+# RAG-System – Enterprise Installationsanleitung
+
+Stand: Februar 2026  
+Architektur: Symfony (PHP 8.2+) + MariaDB 10.11 + Python Vector Service (FAISS) + Ollama LLM  
+Betriebsmodus: On-Prem / Containerfähig / CPU-basiert
+
+Diese Anleitung beschreibt eine vollständige Neuinstallation auf sauberer Infrastruktur.
+
+---
+
+# 1. Systemvoraussetzungen
+
+## 1.1 Betriebssystem
+
+Empfohlen:
+- Ubuntu 22.04 LTS (Server)
+
+Alternativ:
+- Debian 12
+- macOS (Entwicklung)
+- Windows nur via WSL2
+
+---
+
+## 1.2 PHP
+
+Version:
+- PHP 8.2 oder höher
+
+Erforderliche Extensions:
+- pdo
+- pdo_mysql
+- mbstring
+- intl
+- curl
+- json
+- zip
+
+Prüfung:
+
+```bash
+php -v
+php -m
+```
+
+---
+
+## 1.3 Composer
+
+```bash
+composer --version
+```
+
+Falls nicht vorhanden:
+
+```bash
+sudo apt install composer
+```
+
+---
+
+## 1.4 Datenbank
+
+Version:
+- MariaDB 10.11.x (entspricht aktueller ENV)
+
+Installation:
+
+```bash
+sudo apt install mariadb-server
+```
+
+Datenbank und Benutzer anlegen:
+
+```sql
+CREATE DATABASE db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+CREATE USER 'db'@'%' IDENTIFIED BY 'db';
+GRANT ALL PRIVILEGES ON db.* TO 'db'@'%';
+FLUSH PRIVILEGES;
+```
+
+---
+
+## 1.5 Python
+
+Version:
+- Python 3.10 oder höher
+
+Installation:
+
+```bash
+sudo apt install python3 python3-venv python3-pip
+```
+
+Prüfen:
+
+```bash
+python3 --version
+```
+
+---
+
+## 1.6 Ollama (LLM Backend)
+
+Installation:
+
+```bash
+curl -fsSL https://ollama.com/install.sh | sh
+```
+
+Modell bereitstellen:
+
+```bash
+ollama pull qwen3
+oder
+ollama pull mto-model (Wenn eigens KI-Model erstellt wurde)
+```
+
+Verfügbarkeit prüfen:
+
+```bash
+curl http://127.0.0.1:11434/api/tags
+```
+
+---
+
+# 2. Projektbereitstellung
+
+## 2.1 Entpacken
+
+```bash
+unzip rag.zip
+cd rag
+```
+
+oder via Git:
+
+```bash
+git clone <repository>
+cd <repository>
+```
+
+---
+
+## 2.2 PHP-Abhängigkeiten installieren
+
+```bash
+composer install --no-interaction
+```
+
+Für Produktion:
+
+```bash
+composer install --no-dev --optimize-autoloader
+```
+
+---
+
+# 3. Environment-Konfiguration
+
+Datei `.env` im Projektroot konfigurieren.
+
+## 3.1 Symfony Core
+
+```env
+APP_ENV=dev
+APP_SECRET=09333662211af45850ff13d68a40f8e3
+```
+
+Produktion:
+
+```env
+APP_ENV=prod
+```
+
+---
+
+## 3.2 AI Agent Core
+
+```env
+AI_LLM_API_URL=http://host.docker.internal:11434/api/generate
+AI_LLM_MODEL=mto-model
+AI_LLM_TIMEOUT=600
+
+AI_HISTORY_DIR=var/agent-history
+AI_CONTEXT_LINES=20
+AI_CONTEXT_LINES_FULL=500
+```
+
+Hinweise:
+- Timeout unter 600 Sekunden wird nicht empfohlen.
+- API-URL an Infrastruktur anpassen (Docker vs. Localhost).
+
+---
+
+## 3.3 Debug-Konfiguration
+
+```env
+AI_DEBUG=false
+AI_LOG_PROMPT=false
+AI_LOG_CONTEXT=false
+```
+
+In Entwicklungsumgebung optional aktivieren.
+
+---
+
+## 3.4 Datenbank (aktive Konfiguration)
+
+Nur diese DATABASE_URL verwenden:
+
+```env
+DATABASE_URL="mysql://db:db@db:3306/db?sslmode=disable&charset=utf8mb4&serverVersion=10.11.0-mariadb"
+DATABASE_VERSION="10.11.0-mariadb"
+DATABASE_DRIVER="mysql"
+DATABASE_HOST="db"
+DATABASE_PORT="3306"
+DATABASE_USER="db"
+DATABASE_PASSWORD="db"
+DATABASE_NAME="db"
+DATABASE_SERVER="mysql://db:3306"
+```
+
+Wichtig:
+- PostgreSQL-Konfiguration entfernen.
+- Nur eine DATABASE_URL definieren.
+
+---
+
+## 3.5 Messenger
+
+```env
+MESSENGER_TRANSPORT_DSN=doctrine://default?auto_setup=0
+```
+
+Queue läuft über Datenbank.
+
+---
+
+## 3.6 Mailer (optional)
+
+```env
+MAILER_DSN="smtp://127.0.0.1:1025"
+MAILER_HOST="127.0.0.1"
+MAILER_PORT="1025"
+MAILER_DRIVER="smtp"
+MAILER_AUTH_MODE=""
+MAILER_USERNAME=""
+MAILER_PASSWORD=""
+MAILER_CATCHER="1"
+MAILER_WEB_URL="https://rag.ddev.site:8026"
+```
+
+Nur relevant wenn Mailfunktionen aktiv genutzt werden.
+
+---
+
+# 4. Datenbankmigration
+
+```bash
+php bin/console doctrine:migrations:migrate --no-interaction
+```
+
+---
+
+# 5. Python Vector Service
+
+## 5.1 Virtual Environment anlegen
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+---
+
+## 5.2 Abhängigkeiten installieren
+
+Automatisiert:
+
+```bash
+php bin/console mto:agent:vector:control --install
+```
+
+Alternativ manuell:
+
+```bash
+pip install fastapi uvicorn sentence-transformers faiss-cpu numpy
+```
+
+CPU-Version von FAISS ist ausreichend.
+
+---
+
+## 5.3 Vector Service starten
+
+```bash
+php bin/console mto:agent:vector:control --start
+```
+
+Status prüfen:
+
+```bash
+php bin/console mto:agent:vector:control --status
+```
+
+---
+
+# 6. Initialer Reindex
+
+Vor produktiver Nutzung zwingend erforderlich:
+
+```bash
+php bin/console mto:agent:ingest:global
+```
+
+Ohne Reindex ist kein Retrieval möglich.
+
+---
+
+# 7. Anwendung starten
+
+Entwicklung:
+
+```bash
+php -S 127.0.0.1:8000 -t public
+```
+
+Produktion:
+- Über Nginx oder Apache bereitstellen
+- APP_ENV=prod setzen
+- Cache warmup durchführen
+
+```bash
+php bin/console cache:clear --env=prod
+php bin/console cache:warmup --env=prod
+```
+
+---
+
+# 8. Funktionstest
+
+1. Datenbank erreichbar
+2. Migration erfolgreich
+3. Vector Service aktiv
+4. Ollama erreichbar
+5. Global Reindex durchgeführt
+6. Dokument hochgeladen
+7. Version aktiviert
+8. Chat liefert Antwort
+
+---
+
+# 9. Betriebsrelevante Hinweise
+
+## Modellwechsel
+
+Bei Änderung von:
+- AI_LLM_MODEL
+
+Kein Reindex erforderlich.
+
+Bei Änderung von:
+- Embedding-Modell (Python-Seite)
+- Embedding-Dimension
+- Chunking-Parametern
+
+Global Reindex zwingend erforderlich.
+
+---
+
+## NDJSON und Vector Index
+
+Speicherort:
+```
+var/vector/
+```
+
+Nicht manuell verändern.  
+Index ist deterministisch und wird vollständig neu aufgebaut.
+
+---
+
+## Produktionsbetrieb
+
+Empfohlen:
+- Reverse Proxy (Nginx)
+- Systemd Service für Vector Service
+- Eigener Service für Ollama
+- Backup von Datenbank + var/vector/
+
+---
+
+# Installation abgeschlossen
+
+Das System ist betriebsbereit für:
+
+- Versionierte Dokumentverwaltung
+- Deterministischen NDJSON-Ingest
+- FAISS-Vektorindex
+- Hybrid Retrieval
+- LLM-gestützte Antwortgenerierung