# Portabilität: SYSTEM
# Version: 3.0.0
# Zuletzt validiert: 2026-05-17
# Nächste Prüfung: 2026-11-17
# Ressourcen: [hub/schwarm.py, tools/schwarm/, skills/workflows/schwarm-operationen.md]

SWARM - Parallele LLM-Operationen und Schwarm-Intelligenz
============================================================

STAND: 2026-05-17 (v3.11.1)
CLI: bach swarm (alias: bach schwarm)

Das Swarm-System ermöglicht parallele LLM-Ausführung mit verschiedenen
Koordinationsmustern. Mehrere LLM-Instanzen arbeiten gleichzeitig an
Teilaufgaben und werden automatisch koordiniert.

Ref: SQ016

SWARM PATTERNS
--------------

1. PARALLEL-CHUNKS [AKTIV]
   Aufgabe wird in Chunks aufgeteilt, parallel verarbeitet, zusammengefügt.
   Einsatz: Übersetzung, Code-Review, Dokumentation.
   Koordination: Zentral (Chunker + Aggregator)
   Skalierung: Hoch (linear mit Worker-Anzahl)

2. HIERARCHY (Boss + Worker) [AKTIV]
   Ein Coordinator verteilt Aufgaben an Worker, ein Aggregator fasst zusammen.
   Einsatz: Komplexe Projekte mit Abhängigkeiten.
   Koordination: Zentral (Boss-Worker-Pattern)
   Skalierung: Mittel (durch Boss begrenzt)

3. STIGMERGY (Pheromon-basiert) [AKTIV]
   Agenten hinterlassen Spuren (Pheromone) in SharedMemory.
   Andere Agenten folgen starken Pfaden.
   Einsatz: Exploration, Optimierung, dezentrale Koordination.
   Koordination: Dezentral (indirekt über Umgebung)
   Skalierung: Hoch (emergent)

4. CONSENSUS (Mehrheitsentscheid) [AKTIV]
   Mehrere LLMs beantworten dieselbe Frage unabhängig.
   Konsens wird durch Similarity-Scoring oder Majority-Vote ermittelt.
   Einsatz: Kritische Entscheidungen, Qualitätssicherung.
   Koordination: Zentral (Voter + Evaluator)
   Skalierung: Niedrig (O(n) Kosten pro Frage)

   Methoden:
     similarity  Paarweise Textähnlichkeit, höchster Avg-Score gewinnt
     majority    Antworten gruppieren, größte Gruppe gewinnt

5. SPECIALIST (Boss-Routing) [AKTIV]
   Bereits in BACH integriert (11 Boss-Agenten).
   Aufgabe wird an den passenden Spezialisten geroutet.

CLI-BEFEHLE
-----------

  bach swarm list
      Verfügbare Schwarm-Muster mit Status anzeigen.

  bach swarm run <muster> <aufgabe>
      Schwarm-Muster ausführen.
      Beispiel: bach swarm run consensus "Was ist der beste Python-Linter?"

  bach swarm translate [optionen]
      Parallel-Chunks-Übersetzung (DE->EN) für BACH-Texte.

      Optionen:
        --namespace <ns>    Nur einen Namespace übersetzen
        --workers N         Parallele Worker (default: 8)
        --chunk-size N      Texte pro API-Call (default: 10)
        --limit N           Max. Texte übersetzen
        --inventory         Nur Status anzeigen
        --dry-run           Simulation ohne API-Aufrufe

  bach swarm summarize [optionen]
      Chunk-Zusammenfassungen generieren (Parallel-Chunks Stufe 3).

      Optionen:
        --batch-size N      Chunks pro Batch (default: 10)
        --model MODEL       haiku oder sonnet (default: haiku)
        --dry-run           Simulation

  bach swarm benchmark [optionen]
      Performance-Benchmark: sequentiell vs. parallel.

      Optionen:
        --compare           Beide Modi vergleichen
        --parallel          Nur paralleler Modus
        --sequential        Nur sequentieller Modus
        --run               Benchmark tatsaechlich ausführen
        --workers N         Parallele Worker (default: 3)
        --category CAT      software_dev, research, wiki
        --model MODEL       LLM-Modell (default: haiku)
        --export FILE       Ergebnisse als JSON exportieren

  bach swarm consensus "<frage>" [optionen]
      Konsensus-Abstimmung: Mehrere LLMs beantworten dieselbe Frage.

      Optionen:
        --voters N          Anzahl Voter (default: 3, min: 2)
        --model MODEL       haiku, sonnet, opus (default: haiku)
        --method METHOD     similarity oder majority (default: similarity)

  bach swarm status [N]
      Letzte N Schwarm-Runs anzeigen (default: 20).
      Inkl. Kosten-Statistik und Token-Verbrauch.

KOSTEN-TRACKING
---------------

Jeder Schwarm-Run wird in der DB protokolliert (Tabelle: schwarm_runs).
Erfasst werden: Muster, Aufgabe, Tokens (in/out), Kosten (USD),
Worker-Anzahl, Dauer, Status. Abrufbar via: bach swarm status

Kosten-Schätzung (pro 1M Tokens):
  Haiku:   $1.00 Input / $5.00 Output   (guenstig, für Bulk)
  Sonnet:  $3.00 Input / $15.00 Output   (Standard)
  Opus:    $15.00 Input / $75.00 Output   (Premium)

DB-Schema (schwarm_runs):
  id, pattern, task, tokens_in, tokens_out, cost_usd,
  workers, duration_ms, status, result_summary, created_at

KONFIGURATION
-------------

API-Key-Quellen (Fallback-Reihenfolge):
1. BACH Secrets-System (~/.bach/bach_secrets.json)
2. Umgebungsvariable ANTHROPIC_API_KEY

DATEIEN
-------

  system/hub/schwarm.py              Handler (Auto-Discovery)
  system/tools/schwarm/              Tool-Sammlung
    __init__.py                      Paket-Init
    runner.py                        Claude CLI Wrapper + Kosten-Tracking
    translate_swarm.py               Parallel-Chunks-Übersetzung (SQ062)
    summarize_chunks.py              Chunk-Zusammenfassungen (SQ047)
    benchmark.py                     Performance-Benchmark
    consensus.py                     Konsensus-Muster

BEISPIELE
---------

  # Fehlende Übersetzungen prüfen
  bach swarm translate --inventory

  # Übersetzung starten (8 Worker, 10er Chunks)
  bach swarm translate --workers 8 --chunk-size 10

  # 5 Voter fragen, Konsens via Majority ermitteln
  bach swarm consensus "Soll ich asyncio oder threading verwenden?" --voters 5 --method majority

  # Benchmark mit Vergleich und Export
  bach swarm benchmark --compare --workers 5 --export results.json

  # Status aller Schwarm-Runs (letzte 50)
  bach swarm status 50

SIEHE AUCH
----------

- chain.txt (LLM-Ketten / llmauto)
- agent.txt (Boss-Agenten-System)
- skills/workflows/schwarm-operationen.md (Muster-Dokumentation)
- skills/workflows/schwarm-entscheidungsbaum.md (Routing-Logik)
