MtoRagSystem/COMMAND_REF.md

# RetrieX v1.6.0 – CLI Command Reference

Basis: aktueller `rag-inprogress.zip`-Stand der Version **1.6.0**.  
Scope: projektspezifische Symfony-Commands unter `src/Command`.  
Namespace-Konvention: `mto:agent:*`.

Diese Referenz ist gegen die real vorhandenen Command-Klassen im Paket abgeglichen.

---

## 1. Überblick

| Command | Bereich | Kurzbeschreibung |
| --- | --- | --- |
| `mto:agent:chat` | Agent / CLI | Interaktiver Terminal-Chat gegen den `AgentRunner` |
| `mto:agent:eval:run` | Evaluation | Führt versionierte Eval-Cases aus |
| `mto:agent:ingest:version` | Ingest | Startet den Ingest für eine konkrete Dokumentversion |
| `mto:agent:ingest:run` | Ingest Jobs | Führt einen vorhandenen `IngestJob` aus |
| `mto:agent:system:rebuild` | System | Globaler Hard-Rebuild von Knowledge-, Vector- und optional Tag-Artefakten |
| `mto:agent:vector:rebuild` | Vector | Baut den Chunk-Vektorindex aus `index.ndjson` neu |
| `mto:agent:vector:control` | Vector Service | Install, Start, Stop, Reload und Status des Python-Vector-Service |
| `mto:agent:vector:health` | Vector | Konsistenzcheck für Chunk-NDJSON und Vektorindex |
| `mto:agent:test-vector` | Debug | Testet Tag- und Chunk-Vector-Clients direkt |
| `mto:agent:retrieval:test` | Retrieval Debug | Testet den realen hybriden Retrieval-Pfad mit Debugausgabe |
| `mto:agent:tags:export` | Tags | Exportiert Tags nach `tags.ndjson` |
| `mto:agent:tags:rebuild` | Tags | Exportiert Tags und baut `vector_tags.index` neu |
| `mto:agent:tags:job:run` | Tag Jobs | Führt einen vorhandenen Tag-Rebuild-Job aus oder erstellt direkt einen neuen |
| `mto:agent:tag:health` | Tags | Konsistenzcheck für Tag-NDJSON und Tag-Vektorindex |
| `mto:agent:test:shop-search` | Commerce / Debug | Testkommando für Shopware-Suche und optional Search Repair |
| `mto:agent:user:create` | User | Interaktive Anlage eines Users |
| `mto:agent:config:validate` | Config / Governance | Validiert die effektive RetrieX-Konfiguration |
| `mto:agent:config:audit-source` | Config / Governance | Auditiert YAML-Mappings gegen PHP-Fallbacks und Defaults |
| `mto:agent:config:audit-patterns` | Config / Governance | Auditiert fachliche Pattern-, Token- und Signalreste im PHP-Core |
| `mto:agent:config:dump-effective` | Config / Governance | Gibt die effektive Konfigurationsinventur aus |
| `mto:agent:regression:test` | Config / Governance | Führt Offline-Regression-Guards für stabile Pfade aus |

---

## 2. Agent / Chat

### `mto:agent:chat`

Interaktiver CLI-Chat mit dem Agenten.

**Signatur**

```bash
php bin/console mto:agent:chat [user-id]
```

**Argumente**

- `user-id` optional, Default `cli`

**Reales Verhalten**

- startet eine Terminal-Schleife mit `Question` → `Answer`
- ruft pro Eingabe `AgentRunner->run($prompt, $userId)` auf
- streamt Tokens direkt ins Terminal
- beendet sich bei EOF, leerer Eingabe oder `exit`

**Beispiele**

```bash
php bin/console mto:agent:chat
php bin/console mto:agent:chat cli-debug
```

---

## 3. Evaluation

### `mto:agent:eval:run`

Führt versionierte Eval-Cases aus.

**Signatur**

```bash
php bin/console mto:agent:eval:run [type] [--case=CASE_ID] [--json] [--no-write]
```

**Argumente / Optionen**

- `type` optional, Default `retrieval`
- `--case=CASE_ID` führt nur einen einzelnen Case aus
- `--json` gibt den vollständigen Report als JSON aus
- `--no-write` verhindert das Schreiben des Report-Files

**Reales Verhalten**

- lädt Cases über `EvalCaseLoader`
- filtert optional auf eine Case-ID
- führt Cases über `AgentEvalRunner` aus
- schreibt standardmäßig einen Report über `EvalReportWriter`
- Exit-Code ist fehlerhaft, wenn mindestens ein Case fehlschlägt

**Beispiele**

```bash
php bin/console mto:agent:eval:run
php bin/console mto:agent:eval:run retrieval --case=water-hardness-lowest
php bin/console mto:agent:eval:run retrieval --json --no-write
```

---

## 4. Ingest / Jobs

### `mto:agent:ingest:version`

Startet einen Ingest für eine konkrete `DocumentVersion` mit explizitem Benutzerkontext.

**Signatur**

```bash
php bin/console mto:agent:ingest:version <versionId> <userId>
```

**Argumente**

- `versionId` erforderlich, UUID einer `DocumentVersion`
- `userId` erforderlich, UUID des auslösenden Users

**Reales Verhalten**

- lädt `DocumentVersion` und `User` aus Doctrine
- bricht ab, wenn Version oder User nicht existieren
- ruft `IngestOrchestrator->runForVersion($version, $user)` auf
- gibt nach Abschluss die erzeugte Job-ID aus

**Beispiel**

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

### `mto:agent:ingest:run`

Führt einen bereits existierenden `IngestJob` aus.

**Signatur**

```bash
php bin/console mto:agent:ingest:run <jobId> [--dry-run]
```

**Argumente / Optionen**

- `jobId` erforderlich, UUID eines `IngestJob`
- `--dry-run` simuliert schwere Operationen ohne tatsächliche Ausführung

**Reales Verhalten**

- lädt den Job aus der Datenbank
- beendet sich erfolgreich, wenn der Job bereits terminal ist (`COMPLETED`, `FAILED`, `ABORTED`)
- ruft sonst `IngestOrchestrator->runExistingJob($job, $dryRun)` auf

**Beispiele**

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

### `mto:agent:system:rebuild`

Globaler Hard-Rebuild des Systems.

**Signatur**

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

**Optionen**

- `--hard` Pflicht-Sicherheitsschalter; ohne diese Option bricht das Kommando ab
- `--no-tags` überspringt Tag-Rebuild
- `--no-reload` überspringt Reload/Start des Vector-Service
- `--no-health` überspringt abschließende Health-Checks
- `--dry-run` simuliert Schritte ohne Schreiboperationen

**Reales Verhalten**

1. erzeugt einen globalen Reindex-Job
2. führt den globalen Reindex über den Orchestrator aus
3. exportiert optional Tags und baut `vector_tags.index` neu
4. startet oder reloadet optional den Python-Vector-Service
5. führt optional Chunk- und Tag-Health-Checks aus

**Beispiele**

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

---

## 5. Vector / Retrieval

### `mto:agent:vector:rebuild`

Baut den Chunk-Vektorindex aus `index.ndjson` neu.

**Signatur**

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

**Reales Verhalten**

- schreibt `Rebuilding vector index...`
- ruft `VectorIndexBuilder->rebuildFromNdjson()` auf
- schreibt anschließend `Done.`

### `mto:agent:vector:control`

Steuert den persistenten Python-Vector-Service über `python/vector/vector_control.py`.

**Signatur**

```bash
php bin/console mto:agent:vector:control [--install] [--start] [--stop] [--force] [--reload] [--status] [--foreground] [--port=8090] [--host=0.0.0.0]
```

**Optionen**

- `--install` installiert fehlende Python-Abhängigkeiten in `.venv`
- `--start` startet den Service, falls er nicht läuft
- `--stop` stoppt den Service anhand der PID-Datei
- `--force` erzwingt einen Hard-Stop
- `--reload` triggert den `/reload`-Endpoint
- `--status` gibt den aktuellen Status aus
- `--foreground` startet im Vordergrund
- `--port` setzt den Port, Default `8090`
- `--host` setzt den Host, Default `0.0.0.0`

**Beispiele**

```bash
php bin/console mto:agent:vector:control --install
php bin/console mto:agent:vector:control --start
php bin/console mto:agent:vector:control --status
php bin/console mto:agent:vector:control --reload
php bin/console mto:agent:vector:control --stop --force
```

### `mto:agent:vector:health`

Health-Check für Chunk-NDJSON und Chunk-Vektorindex.

**Signatur**

```bash
php bin/console mto:agent:vector:health
```

**Reales Verhalten**

- ruft `VectorIndexHealthService->check()` auf
- gibt JSON aus
- Exit-Code `0`, wenn `status` mit `OK` beginnt; sonst `1`

### `mto:agent:test-vector`

Debug-Kommando für Tag- und Chunk-Vector-Clients.

**Signatur**

```bash
php bin/console mto:agent:test-vector <prompt>
```

**Argumente**

- `prompt` erforderlich

**Reales Verhalten**

- führt Tag-Routing über `TagVectorSearchClient` aus
- führt Chunk-Retrieval über `VectorSearchClient` aus
- misst Tag-, Chunk- und Gesamtdauer
- gibt beide Result-Sets als JSON aus

**Beispiel**

```bash
php bin/console mto:agent:test-vector "welche dokumente behandeln den ingest-flow?"
```

### `mto:agent:retrieval:test`

Testet den realen hybriden Retrieval-Pfad mit Debugausgabe.

**Signatur**

```bash
php bin/console mto:agent:retrieval:test <prompt> [--json] [--show-text]
```

**Argumente / Optionen**

- `prompt` erforderlich
- `--json` gibt das rohe Debugresultat als JSON aus
- `--show-text` zeigt vollständige Chunktexte statt gekürzter Vorschau

**Reales Verhalten**

- ruft `NdjsonHybridRetriever->retrieveDebug($prompt)` auf
- zeigt Pipeline Summary, Scope Candidates, Hit Counts, Boosts und ausgewählte Chunks
- bricht bei leerem Prompt oder Retrieval-Exception mit Fehler ab

**Beispiele**

```bash
php bin/console mto:agent:retrieval:test "niedrigster Grenzwert Wasserhärte"
php bin/console mto:agent:retrieval:test "Testomat 808 SIO2" --json
php bin/console mto:agent:retrieval:test "Indikatortyp 300" --show-text
```

---

## 6. Tag-System

### `mto:agent:tags:export`

Exportiert die Tag-Datenbasis nach `tags.ndjson`.

**Signatur**

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

**Reales Verhalten**

- ruft `TagNdjsonExporter->export()` auf
- gibt Pfad, Tag-Anzahl, Zeilen und Bytes aus

### `mto:agent:tags:rebuild`

Kompletter Neuaufbau des Tag-Retrievals.

**Signatur**

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

**Reales Verhalten**

1. exportiert `tags.ndjson`
2. baut `vector_tags.index`
3. setzt einen Runtime-Marker über `IndexMetaManager->touchRuntime()`

### `mto:agent:tags:job:run`

Führt einen Tag-Rebuild-Job mit File-Lock aus.

**Signatur**

```bash
php bin/console mto:agent:tags:job:run [jobId] [--create]
```

**Argumente / Optionen**

- `jobId` optional, UUID eines bestehenden `TagRebuildJob`
- `--create` erstellt und startet sofort einen neuen `TagRebuildJob`

**Regeln**

- entweder `jobId` oder `--create`
- beides zusammen ist ungültig
- keines von beiden ist ebenfalls ungültig

**Beispiele**

```bash
php bin/console mto:agent:tags:job:run --create
php bin/console mto:agent:tags:job:run <jobUuid>
```

### `mto:agent:tag:health`

Health-Check für das Tag-Retrieval.

**Signatur**

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

**Optionen**

- `--summary` gibt eine lesbare Zusammenfassung statt JSON aus

**Reales Verhalten**

- ruft `TagVectorIndexHealthService->check()` auf
- gibt JSON oder Summary aus
- Exit-Code `0`, wenn der Status als gesund gilt; sonst `1`

**Beispiele**

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

Wichtig: Der reale Command-Name ist `tag:health` im Singular.

---

## 7. Commerce / Shopware Debug

### `mto:agent:test:shop-search`

Testkommando für Shopware-Suche und optionalen Search-Repair-Test.

**Signatur**

```bash
php bin/console mto:agent:test:shop-search [query] [--intent=INTENT] [--history=TEXT] [--repair]
```

**Argumente / Optionen**

- `query` optional, Default `zeige mir testomat modelle wasserhärte unter 5000 euro`
- `--intent` optional, Default `CommerceIntentLite::ADVISORY_PRODUCT_SEARCH`
- `--history` optionaler Commerce-History-Kontext
- `--repair` aktiviert zusätzlich die Search-Repair-Auswertung

**Reales Verhalten**

- ruft `ShopSearchService->search($query, $intent, $history)` auf
- gibt Treffer mit ID, Produktnummer, Hersteller, Preis, Verfügbarkeit, URL, Description und Highlights aus
- bei `--repair` werden Knowledge-Chunks geholt und `SearchRepairService->repair(...)` ausgeführt
- zeigt dann verwendete Repair-Queries und finale gemergte Ergebnisse

**Beispiele**

```bash
php bin/console mto:agent:test:shop-search "testomat 808 300 indikator"
php bin/console mto:agent:test:shop-search "testomat 808 300 indikator" --repair
php bin/console mto:agent:test:shop-search "testomat lab cl" --intent=advisory_product_search
php bin/console mto:agent:test:shop-search "was kostet der indikator" --history="Testomat 808 Indikatortyp 300"
```

---

## 8. User-Management

### `mto:agent:user:create`

Interaktive Anlage eines Users.

**Signatur**

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

**Interaktiver Ablauf**

1. E-Mail eingeben
2. Passwort eingeben
3. Passwort wiederholen
4. eine oder mehrere Rollen wählen
5. Aktivstatus bestätigen

**Validierungen**

- E-Mail muss valide sein
- E-Mail darf noch nicht existieren
- Passwort muss mindestens 8 Zeichen lang sein
- Passwortwiederholung muss übereinstimmen
- mindestens eine Rolle muss gewählt werden

**Zuweisbare Rollen**

- `ROLE_SUPER_ADMIN`
- `ROLE_KNOWLEDGE_ADMIN`
- `ROLE_EDITOR`
- `ROLE_ADMIN_AREA`
- `ROLE_CHAT_USER`

`ROLE_USER` wird als technische Basisrolle über die Hierarchie genutzt, ist aber nicht als fachliche Zielrolle in der Auswahl vorgesehen.

---

## 9. Config / Governance

### `mto:agent:config:validate`

Validiert die effektive RetrieX-Konfiguration.

**Signatur**

```bash
php bin/console mto:agent:config:validate [--json]
```

**Erwartung vor Merge/Deployment**

- Status `OK`
- keine Errors

### `mto:agent:config:audit-source`

Auditiert YAML-backed Configuration gegen PHP-Defaults, Fallback-Accessors und Constructor-Defaults.

**Signatur**

```bash
php bin/console mto:agent:config:audit-source [--details] [--json]
```

**Optionen**

- `--details` zeigt reviewbare Detailzeilen
- `--json` gibt maschinenlesbares JSON aus

### `mto:agent:config:audit-patterns`

Auditiert verbleibende Pattern-, Token- und Signalnutzung im PHP-Core.

**Signatur**

```bash
php bin/console mto:agent:config:audit-patterns [--details] [--json] [--all]
```

**Zweck**

- findet konfigurierte Calls wie `preg_match`, `str_contains`, `in_array` usw.
- markiert WARN-Funde bei Domain-Marker-Terms
- bleibt revieworientiert und nicht selbst runtime-verändernd

**Beispiel**

```bash
php bin/console mto:agent:config:audit-patterns --details
```

### `mto:agent:config:dump-effective`

Gibt die effektive RetrieX-Konfigurationsinventur aus.

**Signatur**

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

**Beispiele**

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

### `mto:agent:regression:test`

Führt Offline-Regression-Guards für stabile Pfade aus.

**Signatur**

```bash
php bin/console mto:agent:regression:test [--json]
```

**Zweck**

- schützt regressionsempfindliche 1.4.x/1.5.x/1.6.0-Flows
- prüft Konfigurationspfade, Tokens und Guardrail-Erwartungen
- ist Pflichtcheck für Änderungen an YAML-, Prompt-, Retrieval-, Commerce- oder Agent-Logik

---

## 10. Typische Betriebsabläufe

### Manueller Ingest einer Version

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

### Vorhandenen Ingest-Job ausführen

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

### Nur Chunk-Vektorindex neu bauen

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

### Gesamtsystem hart neu aufbauen

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

### Vector-Service prüfen und reloaden

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

### Tag-Retrieval neu aufbauen

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

### Shopquery mit Repair testen

```bash
php bin/console mto:agent:test:shop-search "testomat 808 300 indikator" --repair
```

### Config-Änderung prüfen

```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
```

---

## 11. Wichtige Runtime-Dateien und Pfade

```text
var/
├── knowledge/
│   ├── index.ndjson
│   ├── index_meta.json
│   ├── index_runtime.json
│   ├── vector.index
│   ├── vector.index.meta.json
│   ├── tags.ndjson
│   ├── vector_tags.index
│   ├── vector_tags.index.meta.json
│   ├── uploads/
│   └── locks/
├── run/
│   └── vector_service.pid
└── locks/
    └── ingest.lock
```

Herkunft im Code:

- `config/services.yaml` bindet `mto.knowledge.*` an `retriex.knowledge.*`.
- `python/vector/vector_control.py` verwendet `var/run/vector_service.pid`.
- `App\Service\LockService` verwendet `var/locks/ingest.lock`.

---

## 12. Wichtige Korrekturen gegenüber älteren Referenzen

1. Der aktuelle Stand enthält **21** projektspezifische Commands, nicht nur die älteren 18.
2. `mto:agent:eval:run` ist Teil des aktuellen Command-Sets.
3. `mto:agent:retrieval:test` testet den realen hybriden Retrieval-Pfad und ergänzt `mto:agent:test-vector`.
4. `mto:agent:test:shop-search` ist im aktuellen Stand mit `query`, `--intent`, `--history` und `--repair` codekonform dokumentiert.
5. `mto:agent:tag:health` unterstützt `--summary`.
6. `mto:agent:user:create` kann mehrere Rollen auswählen und fragt Aktivstatus ab.
7. Zuweisbare Rollen umfassen `ROLE_ADMIN_AREA` und `ROLE_CHAT_USER`.
8. `mto:agent:ingest:version` braucht weiterhin zwei Pflichtargumente: `<versionId> <userId>`.
9. Der globale Rebuild läuft über `mto:agent:system:rebuild --hard`.
10. Runtime-Artefakte liegen überwiegend unter `var/knowledge/`.

---

## 13. Fazit

Für den operativen Betrieb sind besonders relevant:

- `mto:agent:system:rebuild --hard`
- `mto:agent:vector:control --status|--reload|--start`
- `mto:agent:vector:health`
- `mto:agent:tag:health --summary`
- `mto:agent:ingest:run`
- `mto:agent:config:validate`
- `mto:agent:regression:test`

Für Entwicklung und Fehlersuche sind besonders hilfreich:

- `mto:agent:chat`
- `mto:agent:retrieval:test`
- `mto:agent:test-vector`
- `mto:agent:test:shop-search --repair`
- `mto:agent:config:dump-effective --summary`
- `mto:agent:config:audit-patterns --details`