# 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)