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

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

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

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

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

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

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

mto:agent:ingest:run

Führt einen bereits existierenden IngestJob aus.

Signatur

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

mto:agent:config:dump-effective

Gibt die effektive RetrieX-Konfigurationsinventur aus.

Signatur

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

Beispiele

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

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

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

Vorhandenen Ingest-Job ausführen

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

Nur Chunk-Vektorindex neu bauen

php bin/console mto:agent:vector:rebuild

Gesamtsystem hart neu aufbauen

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

Vector-Service prüfen und reloaden

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

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

Shopquery mit Repair testen

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

Config-Änderung prüfen

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

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