Skip to content

Latest commit

 

History

History
656 lines (538 loc) · 36.7 KB

README_de.md

File metadata and controls

656 lines (538 loc) · 36.7 KB

clutch banner

English · Deutsch · Español · 简体中文 · 日本語 · Русский

clutch

Provider-neutrale LLM-Orchestrierungsengine und Modell-Router mit automatischem Lernen

Version 0.6.3 CI Pytest Python 3.10+ Plattformen Lizenz: MIT Provider Drittanbieter-Lizenzen: Geprüft Marketing-Log: Aktiv Sicherheits-SLA: 48h Code style: ruff Sicherheit: Local-First Privatsphäre: Zero-Egress Non-Elevation Ökosystem: ellmos-ai Dachorganisation: open-bricks Discovery: llms.txt

clutch (deutsch: Kupplung) verwendet eine intuitive automobile Fahrmetapher, um Aufgaben intelligent an optimale LLM-Modelle verschiedener Anbieter weiterzuleiten. Das System analysiert Aufgabenkomplexität und -zweck, wählt die passende Gangstufe und das ideale Reasoning-Level, verfolgt Budgets mit einer Vier-Zonen-Tankuhr, setzt persistente Circuit-Breaker durch und lernt aus Erfahrungen. Verwendbar als Bibliothek, CLI oder lokale Web-App.

Note

Für KI-Agenten, Crawler und automatisierte Indexierer stehen maschinenlesbare Metadaten und Entdeckungskontexte in llms.txt bereit.


Schnellnavigation

  1. Funktionen & Highlights
  2. Architektur & Metaphern-Abbildung
  3. Zielgruppen & Auffindbarkeit
  4. Vergleichsmatrix gegenüber Alternativen
  5. Duale Mermaid-Diagramme
  6. Governance- & Laufzeit-Invarianten
  7. Streckentypen & Aufgabenklassifikation
  8. Installation & Voraussetzungen
  9. Schnellstart & Kurzanleitung
  10. Kommandozeilen-Schnittstelle (CLI)
  11. API-Keys & Zugangsdaten
  12. Konfiguration & Benutzer-Overlays
  13. Unterstützte Provider & Modell-Gänge
  14. Ausführungsmuster
  15. Verwandte Tools & Ökosystem
  16. Drittanbieter-Lizenzen & Transparenz
  17. Sicherheitsrichtlinie & Haftung
  18. Verifikation & Testsuite

1. Funktionen & Highlights

  • Provider-neutral -- Anthropic (Claude), Google (Gemini), OpenAI (GPT/Codex), Ollama (lokal & remote), Claude Code, agy via companion-for-agy sowie Kimi (Moonshot API / CLI / Ollama Cloud)
  • Automatisches Routing -- analysiert Aufgabenkomplexität und Zweck (Coding, Vision, Recherche, Bulk) und wählt optimales Modell + Reasoning-Level
  • Zweck- und Vision-bewusst -- leitet Bild-/Dokumenteingaben an vision-fähige Modelle weiter; passt Aufgaben an Modellstärken an
  • CLI + Web-UI -- clutch route/run/chat/models/stats, plus optionale FastAPI-Web-Chat-Oberfläche (clutch serve --web)
  • Credential-Speicher -- API-Keys sicher in ~/.clutch/credentials.json ablegen (clutch keys ...); Umgebungsvariablen haben Vorrang
  • Modell-Erkennung -- automatische Erkennung installierter Ollama-Modelle (lokal/remote) und OpenAI-kompatibler /v1/models-Endpunkte
  • Budget-Tracking -- Tankuhr mit vier Zonen (grün/gelb/orange/rot) mit täglichen und monatlichen Limits
  • Lernengine -- Fitness-Scoring und Epsilon-Greedy-Exploration, die das Routing im Laufe der Zeit verbessert
  • Ausführungsmuster -- Einzelaufgaben, Ketten (Kolonne), parallele Teams und Schwarm-Verarbeitung
  • Persistente Verfügbarkeit -- Circuit-Breaker und Kontingentsperren überleben One-Shot-Prozesse; rote Anthropic-5h/7d-Fenster, notaus und Provider-Rate-Limits werden bis zum Reset umgangen
  • Update-festes Nutzer-Overlay -- Modelle deaktivieren, Modelle/Provider bevorzugen, Gangstufen begrenzen, Aliase und Modellkosten in ~/.clutch/user_overrides.json pflegen
  • Beleggestützte Ausführungsselektoren -- Runner-, Familien- und exakte Modellbindungen ohne stille Ersetzung auflösen; Provider-Adapter halten fünf Verfügbarkeitsstufen getrennt
  • Routing-Wünsche pro Aufruf -- Gänge bevorzugen oder ausschließen, Zweck/Effort überschreiben und zwei gerankte Fallback-Alternativen erhalten
  • Gesundheitsüberwachung -- persistente Circuit-Breaker, Latenz-Tracking, Overkill/Token-Explosion-Alarme, Provider-Failover
  • SQLite-Metriken -- persistentes Fahrtenbuch, Chat-Sitzungen, Prompt-Bibliothek und Profile

2. Architektur & Metaphern-Abbildung

Das gesamte System folgt einer Auto-/Fahrmetapher:

                    +----------------------------------+
                    |            FAHRER                 |
                    |        (Driver / Orchestrator)    |
                    |     Any LLM: Opus, Gemini, ...   |
                    +--------+----------+--------------+
                             |          |
                +------------+          +-------------+
                |                                     |
        +-------v--------+                   +--------v-------+
        |    STRECKE      |                   |    GETRIEBE    |
        | (Road / Task    |                   | (Gearbox /     |
        |  Analysis)      |                   |  Model Registry|
        +----------------+                   |                |
                                              | G1: Haiku      |
        +----------------+                   | G2: Flash      |
        |   GAS / BREMSE  |                   | G3: Sonnet     |
        | (Throttle/Brake |                   | G4: Gemini Pro |
        |  Reasoning Lvl) |                   | G5: Opus       |
        +----------------+                   | + Ollama local |
                                              +----------------+
        +----------------+
        |    KUPPLUNG     |    +------------+    +-------------+
        | (Clutch / Model |    |   TACHO    |    |  TANKUHR    |
        |  Switching)     |    | (Metrics)  |    | (Budget)    |
        +----------------+    +------------+    +-------------+
Komponente Rolle Modul
Fahrer (Driver) Orchestrator -- wählt Modell, Reasoning und Ausführungsmuster fahrer.py
Strecke (Road) Aufgabenanalyse und -klassifikation strecke.py
Getriebe (Gearbox) Provider-neutrale Modell-Registry getriebe.py
Gang (Gear) Ein konkretes Modell (G1--G5) getriebe.py
Gas / Bremse (Throttle/Brake) Reasoning-Level (0--100%) gas_bremse.py
Kupplung (Clutch) Schaltmechanismus zwischen Modellen kupplung.py
MotorBlock (Engine) Einheitliche API-Aufrufschicht motorblock.py
Tacho (Speedometer) Metriken-Erfassung tacho.py
Tankuhr (Fuel Gauge) Budget-Tracking (4 Zonen) tankuhr.py
Bordcomputer (Onboard Computer) Health-Monitor, Circuit-Breaker bordcomputer.py
Fahrtenbuch (Trip Log) SQLite-Metrikspeicher fahrtenbuch.py
Fahrschule (Driving School) Lernengine / Auto-Tuning fahrschule.py
Token-Throughput (Schattenzone) Anthropic 5h/7d-Rate-Limit-Fenster als zweite Zone -- siehe docs/STAGED-MIGRATION.md token_throughput.py

3. Zielgruppen & Auffindbarkeit

clutch wurde für vier technische Zielgruppen konzipiert, die präzise Kontrolle über Modelldispatch, Kostenkalkulation und strikte Null-Telemetrie benötigen:

[PERSONA-01] Autonome KI-Agenten-Entwickler & Multi-Agenten-Architekten

  • Kontext: Aufbau von Multi-Agenten-Systemen, kontinuierlichen Hintergrund-Workern und werkzeuggestützten Agenten-Schleifen (z. B. LangGraph, CrewAI, AutoGen oder native CLI-Agenten).
  • Herausforderung: Statisches Hardcoding teurer Frontier-Modelle führt zu explodierenden Token-Kosten; starre SDKs crashen bei Quotenlimits oder 429-Rate-Limits.
  • Lösung durch clutch: Dynamisches Provider-Hot-Swapping (Anthropic, Gemini, OpenAI, Ollama, Kimi), orthogonale Steuerung des Reasoning-Aufwands, prozessübergreifende Circuit-Breaker und deterministische Fallback-Ketten.

[PERSONA-02] Multi-Host- & Edge-Infrastruktur-Systemingenieure

  • Kontext: Betrieb heterogener Rechenumgebungen bestehend aus lokalen GPU-Workstations, Laptops, Edge-Knoten und Cloud-APIs.
  • Herausforderung: Ungleichmäßige Hardware-Verfügbarkeit macht starre Konfigurationen fragil; zentrale Cloud-Gateways erhöhen die Latenz und bilden Single Points of Failure.
  • Lösung durch clutch: Automatische Erkennung lokaler/entfernter Ollama-Instanzen neben Cloud-Providern, belegte Selektor-Auflösung ohne verdeckte Ersetzungen und saubere Host-Isolation.

[PERSONA-03] Solo-Entwickler & Tool-Builder

  • Kontext: Entwicklung von Individualsoftware, Entwickler-Werkzeugen und CLI-Tools, die KI-Funktionalität ohne aufwendige Gateway-Infrastruktur benötigen.
  • Herausforderung: Das Aufsetzen schwergewichtiger Docker-Proxys (LiteLLM, Portkey) ist Overkill; eigene Skripte entbehren oft Metriken und Budget-Sicherungen.
  • Lösung durch clutch: Direkte Python-Bibliothek (from clutch import Fahrer) und CLI (clutch run) mit intuitiver Auto-Metapher, Vier-Zonen-Tankuhr, SQLite-Fahrtenbuch und ohne Hintergrund-Dämonen.

[PERSONA-04] Datenschutz- & Compliance-Verantwortliche

  • Kontext: Gewährleistung von DSGVO-, HIPAA- und IP-Schutzanforderungen in KI-gestützten Unternehmens- und Entwicklungs-Pipelines.
  • Herausforderung: SaaS-Gateways leiten vertrauliche Prompts über fremde Server; unklare Lizenzen oder administrative Berechtigungen stellen ein Audit-Risiko dar.
  • Lösung durch clutch: 100% Local-First-Architektur ohne Telemetrie-Egress (Verbindungen ausschließlich zu konfigurierten Provider-Endpunkten), unprivilegierte Benutzerrechte (RunAsInvoker), permissive MIT-Lizenz und transparente SPDX-Lizenzübersicht.

High-Intent-Suchbegriffe & KI-Auffindbarkeit

Zur semantischen Erkennung durch Entwicklerverzeichnisse und KI-Suchmaschinen:

  • provider-neutral LLM orchestration engine and model router -- Open-Source Python-Routing-Bibliothek für Anthropic, Gemini, OpenAI, Ollama und Kimi.
  • local-first zero-egress LLM budget tracking fuel gauge -- 4-Zonen-Budgetkontrolle mit Token-Throughput-Schattenfenster.
  • automotive metaphor LLM routing Anthropic Gemini OpenAI Ollama Kimi -- Intuitive Steuerung über Fahrer, Strecke, Getriebe, Gas/Bremse und Kupplung.
  • persistent circuit breaker quota failover multi-agent system -- Prozessüberdauernde Sperren zur Vermeidung von Quotenschleifen.
  • adaptive reasoning effort throttle brake model switching -- Entkopplung von Denkintensität und Modellwahl.
  • evidence-bearing execution selector model resolution -- Fünfstufige Nachweiserbringung ohne unbemerkte Modellsubstitution.
  • unprivileged user-mode LLM router RunAsInvoker MIT license -- Sichere Ausführung im unprivilegierten Benutzermodus mit permissiver Software-Inventur.

4. Vergleichsmatrix gegenüber Alternativen

Die folgende Matrix vergleicht clutch mit etablierten Routing- und Gateway-Paradigmen anhand von 10 technischen Dimensionen, die direkt auf unsere Governance-Invarianten abgestimmt sind:

| Technische Dimension | Governance-Invariante | clutch | Klassische Einzel-Provider-SDKs | Cloud-Modell-Gateways (LiteLLM / OpenRouter) | Agenten-Framework-Router (CrewAI / AutoGen) | Ad-Hoc Skripte & Prompt-Router | |---|:---:|:---:|:---:|:---:|:---:| | 1. Multi-Provider-Neutralität | INV-LOCAL-01 | Vollständiges Hot-Swapping (Anthropic, Gemini, OpenAI, Ollama, Kimi) | Keine (Vendor-Lock-in) | Hoch (Multi-Provider API-Wrapper) | Mittel (Framework-spezifische Adapter) | Gering (Manueller Aufwand pro API) | | 2. Offline-First & Zero Egress | INV-LOCAL-02 | 100% Lokal (Lokale Daten, keine Telemetrie) | Hoch (Direkte API-Aufrufe) | Gering (Zentrale Cloud-Telemetrie / SaaS) | Gering (Oft integrierte Cloud-Telemetrie) | Hoch (Eigener Code) | | 3. Unprivilegierte Ausführung | INV-UNPRIV-03 | Strikter RunAsInvoker (User-Mode, kein Daemon) | Hoch (User-Space-Bibliothek) | Erfordert oft Hintergrund-Dienst / Docker | Hoch (User-Space-Bibliothek) | Hoch (User-Space-Skript) | | 4. Persistente Circuit-Breaker | INV-CIRCUIT-04 | Persistente availability.json (Überlebt Neustart) | Keine (Bricht bei 429 direkt ab) | Ephemer / Im Arbeitsspeicher (Nach Neustart verloren) | Ephemer (Mit Workflow-Ende verloren) | Keine (Skript stürzt ab oder schleift) | | 5. Update-sichere Benutzer-Overlays | INV-OVERLAY-05 | Persistente user_overrides.json & Aliase | Keine (Code-Anpassung nötig) | Basis (Konfigurationsdatei / DB) | Code-Konfiguration | Hardcodierte Variablen | | 6. Zweifache gerankte Fallback-Gänge | INV-FALLBACK-06 | Primärer Gang + 2 gerankte Alternativen | Keine | Basis (Lineare Wiederholungsliste) | Partiell (Pauschale Fehlerabfangung) | Keine (Harter Abbruch) | | 7. 4-Zonen-Budget-Tankuhr | INV-BUDGET-07 | Tankuhr (Grün/Gelb/Orange/Rot + Durchsatz) | Keine (Nur externes Billing-Dashboard) | Basis (Ausgabenlimits / Guthabenprüfung) | Keine (Keine nativen Budget-Schranken) | Keine (Unkontrollierte API-Kosten) | | 8. Zweck- & Vision-Ausrichtung | INV-PURPOSE-08 | Automatische Modalitäts-Zuordnung (Vision/Code) | Manuell | Manuelle Modellauswahl | Partiell (Rollen-Prompts) | Keine | | 9. Transaktionssicheres Audit-Ledger | INV-LEDGER-09 | ACID SQLite Fahrtenbuch & Chat-Historie | Keine (Zustandslos) | Cloud-Logging-Dashboard | Ephemer im Arbeitsspeicher | Keine / Reine Textdateien | | 10. Plattform-Parität & Sicherheits-SLA | INV-SLA-10 | 48h SLA / Multi-OS CI / Zero-Copyleft MIT | Enterprise-Vertragsbedingungen | Gemischte / Proprietäre Bedingungen | Unterschiedlich je Open-Source-Projekt | Keine (Ungepflegte Skripte) |


5. Duale Mermaid-Diagramme

1. Systemarchitektur-Topologie

flowchart TD
    subgraph CLIENTS["Clients & Steuerungs-Oberflächen"]
        CLI["clutch CLI (route / run / chat / stats)"]
        Web["FastAPI Web-UI (clutch serve --web)"]
        API["OpenAI-kompatibler /v1/chat/completions Endpunkt"]
        Lib["Python SDK (from clutch import Fahrer)"]
    end

    subgraph ORCHESTRATION["Kern-Orchestrierungsschicht"]
        Fahrer["FAHRER (Orchestrator)"]
        Strecke["STRECKE (Aufgaben- & Zweck-Klassifikator)"]
        GasBremse["GAS / BREMSE (Reasoning-Aufwand 0-100%)"]
        Kupplung["KUPPLUNG (Modellwechsler & Failover)"]
    end

    subgraph REGISTRY["Modell-Registry & Governance"]
        Getriebe["GETRIEBE (Modell-Gänge G1-G5 & Lokales Ollama)"]
        Bordcomputer["BORDCOMPUTER (Circuit Breaker & Verfügbarkeit)"]
        Tankuhr["TANKUHR (4-Zonen-Budget & Schattenfenster)"]
        UserOverrides["Benutzer-Overlays (~/.clutch/user_overrides.json)"]
    end

    subgraph ENGINES["Einheitliche MotorBlock-Provider-Schicht"]
        MotorBlock["MOTORBLOCK (Einheitlicher API-Adapter)"]
        Anthropic["Anthropic (Claude Sonnet / Opus / Haiku)"]
        Gemini["Google (Gemini 3.7 Flash / 3.5 Fallback / Pro)"]
        OpenAI["OpenAI (GPT-5.6 / Codex)"]
        Ollama["Ollama (Lokale & Remote Modelle)"]
        Agy["agy (companion-for-agy)"]
        Kimi["Kimi (Moonshot API & CLI)"]
    end

    subgraph TELEMETRY["Telemetrie, Ledger & Lernsystem"]
        Tacho["TACHO (Latenz & Token-Durchsatz)"]
        Fahrtenbuch[("FAHRTENBUCH (SQLite Fahrten-Ledger)")]
        Fahrschule["FAHRSCHULE (Lernengine & Fitness-Optimierung)"]
    end

    CLIENTS --> Fahrer
    Fahrer --> Strecke
    Strecke --> Getriebe
    Fahrer --> GasBremse
    Fahrer --> Kupplung
    Getriebe <--> Bordcomputer
    Getriebe <--> UserOverrides
    Bordcomputer <--> Tankuhr
    Kupplung --> MotorBlock
    MotorBlock --> Anthropic
    MotorBlock --> Gemini
    MotorBlock --> OpenAI
    MotorBlock --> Ollama
    MotorBlock --> Agy
    MotorBlock --> Kimi
    MotorBlock --> Tacho
    Tacho --> Fahrtenbuch
    Fahrtenbuch --> Fahrschule
    Fahrschule -. Fitness-Feedback .-> Getriebe
Loading

2. End-to-End Task- & Routing-Lebenszyklus

sequenceDiagram
    autonumber
    actor User as Nutzer / Agent
    participant Fahrer as Fahrer (Orchestrator)
    participant Strecke as Strecke (Klassifikator)
    participant Getriebe as Getriebe (Registry)
    participant Bord as Bordcomputer (Health/Quota)
    participant Motor as MotorBlock (Einheitliche Engine)
    participant Provider as Modell-Provider (API/Lokal)
    participant Tacho as Tacho & Tankuhr (Telemetrie)
    participant Ledger as Fahrtenbuch (SQLite)
    participant School as Fahrschule (Lernengine)

    User->>Fahrer: Aufgabe übergeben (Prompt, Präferenzen, Ausschluss, Zweck, Effort)
    Fahrer->>Strecke: strecke_analysieren(prompt)
    Strecke-->>Fahrer: StreckenProfil (Streckentyp, Schwierigkeit, Zweck, Vision-Bedarf)
    Fahrer->>Getriebe: get_candidates(profil, zweck)
    Getriebe->>Bord: pruefe_verfuegbarkeit(kandidaten, user_overrides)
    Bord-->>Getriebe: Aktive rote Quota-Fenster & ausgelöste Circuit-Breaker herausfiltern
    Getriebe-->>Fahrer: FahrtConfig (Hauptgang + 2 gerankte Fallback-Alternativen)
    Fahrer->>Motor: ausfuehren(task, hauptgang, effort)
    alt Reguläre Ausführung erfolgreich
        Motor->>Provider: API-Aufruf absetzen
        Provider-->>Motor: Antwort-Tokens & Verbrauchsmetadaten streamen
    else Provider-Fehler / Rate-Limit (429 / Quota)
        Motor->>Bord: Temporäre Provider-Sperre setzen (in availability.json persistiert)
        Motor->>Provider: Automatischer Wechsel auf gerankte Fallback-Alternative
        Provider-->>Motor: Antwort über Fallback-Modell streamen
    end
    Motor->>Tacho: Tokens, Latenz & Token-Durchsatz (EMA) aufzeichnen
    Tacho->>Fahrer: Budget-Zonen (Tankuhr) und Tacho-Messwerte aktualisieren
    Fahrer->>Ledger: record_trip(trip_log, dauer, fitness)
    Ledger->>School: Lernzyklus anstoßen
    School-->>Getriebe: Epsilon-Greedy-Fitnessgewichte anpassen
    Fahrer-->>User: MotorErgebnis (Antwortinhalt, Konfiguration, Telemetrie, Alternativen)
Loading

6. Governance- & Laufzeit-Invarianten

# Invariante Geltungsbereich Betriebliche Garantie
1 Provider-Agnostizismus & Zero Lock-in Engine Keine feste Herstellerbindung; nahtloses Umschalten zwischen Anthropic, Google Gemini, OpenAI, Ollama und Kimi.
2 100% Local-First & Zero Egress Netzwerk Keine Tracking-, Analyse- oder Telemetrie-Abflüsse; Netzwerkverkehr entsteht ausschließlich zu konfigurierten Providern.
3 Non-Elevation User Mode Prozess Alle CLI-Befehle, Hintergrund-Worker und FastAPI-Server laufen strikt im unprivilegierten Benutzerkontext.
4 Fail-Closed Circuit Breaker Zuverlässigkeit Erschöpfte Quotas, rote Fenster und API-Fehler führen zu persistenten Sperren in ~/.clutch/availability.json statt Endlosschleifen.
5 Update-feste Nutzer-Overlays Konfiguration Nutzerpräferenzen, Modellausschlüsse, Aliase und Kostenanpassungen in ~/.clutch/user_overrides.json überleben Paket-Updates.
6 Zwei gerankte Fallback-Alternativen Routing Jede Routing-Entscheidung liefert verlässlich einen Hauptgang sowie zwei gerankte Fallback-Alternativen (alternativen).
7 Zweidimensionale Telemetrie Budget Kombiniert finanzielle USD-Verbrauchszonen (Tankuhr) mit realen Token-Durchsatz-Raten (token_throughput.py).
8 Zweck- und Vision-Passgenauigkeit Klassifikation Bild- und Dokumentaufgaben werden strikt an vision-fähige Modelle geroutet; Coding-Tasks erhalten spezialisierte Coding-Gänge.
9 Transaktionssicheres SQLite-Ledger Persistenz Alle Fahrten, Ausführungsdaten, Chat-Sitzungen und Prompt-Vorlagen werden ACID-konform lokal in SQLite gespeichert.
10 Plattformübergreifende Multi-OS Parität Plattform Vollständig identisches Verhalten, CLI-Ergonomie, Testabdeckung und Routing-Semantik unter Linux, Windows und macOS.

7. Streckentypen & Aufgabenklassifikation

Strecke Schwierigkeit Standard-Gang Gas/Throttle Muster
Feldweg Trivial Haiku (G1) 30% Single
Landstrasse Standard Sonnet (G3) 50% Single
Bundesstrasse Bugfix Sonnet (G3) 70% Single
Autobahn Architektur Opus (G5) 90% Single
Rallye Bulk ops Haiku (G1) 30% Swarm
Konvoi Pipeline Sonnet (G3) 50% Chain
Teamfahrt Multi-File Sonnet (G3) 50% Team
Langstrecke Komplex Opus (G5) 90% Hybrid

8. Installation & Voraussetzungen

git clone https://github.com/ellmos-ai/clutch.git
cd clutch
pip install -e .

Optionale Web-Oberfläche

pip install -e .[web]

Voraussetzungen

  • Python 3.10+
  • API-Schlüssel für gewünschte Provider (als Umgebungsvariablen oder via clutch keys set):
    • ANTHROPIC_API_KEY für Claude-Modelle
    • GOOGLE_API_KEY für Gemini-Modelle
    • OPENAI_API_KEY für GPT- und Codex-Modelle
    • MOONSHOT_API_KEY für Kimi-API-Modelle
    • Lokales Ollama für lokale Open-Source-Modelle

9. Schnellstart & Kurzanleitung

from clutch import Fahrer

# Fahrer instanziieren (nutzt alle konfigurierten Provider)
fahrer = Fahrer()

# Aufgabe übergeben -- der Fahrer übernimmt Analyse und Ausführung
ergebnis = fahrer.fahren(
    "Fix den Authentifizierungsbug im Login-Modul",
    handler=mein_handler,
)

# Gewählte Konfiguration inspizieren
print(ergebnis.config.gang.name)       # "claude-sonnet"
print(ergebnis.config.gang.provider)   # "anthropic"
print(ergebnis.config.gas.wert)        # 0.7

# Dashboard abfragen
status = fahrer.status()
print(status["tankuhr"]["zone"])       # "green"
print(status["getriebe"])              # "Getriebe[haiku(G1), flash(G2), ...]"

# Aus bisherigen Fahrten lernen
fahrer.trainieren()

10. Kommandozeilen-Schnittstelle (CLI)

Nach pip install -e . steht das clutch-Kommando bereit:

clutch route "Fix den Auth-Bug"        # Zeigt Routing-Entscheidung (Dry-Run, kein API-Call)
clutch route "..." --prefer codex --exclude claude-sonnet --zweck coding --effort high
clutch "Erkläre Quantencomputing"     # One-Shot: Route + Ausführung, gibt Antwort aus
clutch run "..." --json                # Maschinenlesbare Ausgabe (für KI-Agenten)
clutch chat                            # Interaktive REPL-Sitzung
clutch models [--status] [--json]      # Modelle inklusive Verfügbarkeit & Sperrgrund
clutch models disable claude-sonnet    # Persistentes, update-festes Nutzer-Overlay
clutch models enable claude-sonnet
clutch resolve gpt5 --runner codex --json  # nur auflösen; führt kein Modell aus
clutch config prefer openai            # Modell oder Provider dauerhaft bevorzugen
clutch stats                           # Nutzungs-, Budget- und Health-Dashboard
clutch config <key> [value]            # CLI-Einstellungen lesen/schreiben
clutch keys set MOONSHOT_API_KEY       # API-Key sicher speichern (Maskierte Eingabe)
clutch keys list                       # Gespeicherte Key-Namen auflisten (keine Werte)
clutch serve --web                     # Lokale Web-UI starten (benötigt: pip install clutch[web])

11. API-Keys & Zugangsdaten

clutch löst Schlüssel in folgender Reihenfolge auf (der erste Treffer gewinnt):

  1. Umgebungsvariable (z. B. MOONSHOT_API_KEY) -- bevorzugt für Server und CI
  2. clutch-Store ~/.clutch/credentials.json (via clutch keys set, Berechtigung 0600)
  3. ~/.credentials/<name>-Dateien (Interoperabilität mit Geschwistertools)

Schlüsselwerte werden niemals ausgegeben, geloggt oder in Git committet.


12. Konfiguration & Benutzer-Overlays

Standardkonfigurationen liegen in clutch/config/. Eigene Overlays werden in ~/.clutch/user_overrides.json abgelegt:

{
  "disabled_models": ["claude-sonnet"],
  "preferred_models": ["openai-codex"],
  "preferred_providers": ["openai"],
  "model_max_gang": {"openai-codex": 4},
  "aliases": {"codex": "openai-codex"},
  "model_cost_override": {
    "ollama-kimi-k2": {"kosten_input_1k": 0.001, "kosten_output_1k": 0.004}
  }
}

Ausführungsselektoren und Provider-Evidenz

resolve_execution_selector() löst Runnerprofile (claude, codex, agy, clutch, ollama, kimi), self, Familien wie gpt5 sowie exakte Registrynamen oder Modell-IDs auf. Exakte Selektoren werden niemals ersetzt. Das JSON-Ergebnis trennt resolved (Selektor existiert) von claimable (alle erforderlichen Belege liegen vor) und enthält einen deterministischen Registry-Fingerprint.

Für Claimability müssen fünf unabhängige Stufen wahr sein: provider_documented, provider_api_listed, account_accessible, runner_compatible und host_ready. Gebündelte Katalogdaten leiten weder Accountzugriff noch Hostbereitschaft ab und bleiben deshalb fail-closed, bis ein Aufrufer einen belegten ProviderCatalogSnapshot anwendet.

Provider-I/O bleibt außerhalb des Kernpakets. Injizierte ProviderCatalogAdapter liefern validierte Snapshots; refresh_provider_catalog() weist den Diff aus und behält bei einem Fehler den letzten belegten Snapshot. Das Anwenden eines Snapshots darf bestehende kuratierte Gänge anreichern, aber niemals ein providerseitig gefundenes Modell neu in die Registry aufnehmen.


Die Bibliothek akzeptiert dieselben Wünsche wie die CLI:

profil = fahrer.strecke_analysieren("Implementiere den Parser")
config = fahrer.kuppeln(
    profil,
    zweck="coding",
    effort_override="high",
    ausschluss=["claude-sonnet"],
    praeferenz=["codex", "openai"],
)
print(config.gang.name)
print(config.alternativen)  # zwei gerankte Fallback-Gänge

Harte Grenzen (deaktivierte/nicht verfügbare/ausgeschlossene Gänge, Budget, Vertrauen und erforderliche Vision-Fähigkeit) gelten vor Präferenzen. Das Route-JSON enthält immer alternativen.

Reasoning-Effort

Modellwahl und Reasoning-Effort sind orthogonal: clutch entscheidet welches Modell (Gang) und hält im optionalen Feld effort fest, wie tief ein kompatibler Agent arbeiten soll. Aufgabenklassen in strecken.json können verwenden:

  • high für routinemäßige, klar begrenzte Arbeit
  • xhigh als reguläres gründliches Session-Level
  • max-delegate für einen transparent angekündigten, gezielten Max-Worker beim härtesten Einzelschritt; dadurch entsteht kein dauerhafter Max-Modus

Aufrufer können die Empfehlung für genau einen Aufruf mit kontext={"effort": "high"} überschreiben. ultracode ist bewusst kein Effort-Wert: Es beschreibt Breite (Team-/Schwarm-Fan-out), nicht tiefere Analyse; teure Fan-outs brauchen weiterhin eine ausdrückliche Bestätigung. Lange Rechenarbeit wird in beobachtbare Schritte zerlegt. Dauert ein einzelner Schritt voraussichtlich etwa 10--15 Minuten oder länger, gehört dieser Schritt auf den Mac-Studio-Compute-Pfad.

Budget-Zonen

Zone Auslastung Erlaubte Gänge
Grün 0--30 % Alle (G1--G5)
Gelb 30--60 % G1--G3
Orange 60--80 % Nur G1--G2
Rot 80--100 % Keine (Budget erschöpft)

clutch/config/fitness_criteria.json ist die einzige Laufzeitquelle für diese Grenzen. Bordcomputer und Kupplung lesen dieselbe Policy; bei Rot stoppt das Routing, bevor ein LLM ausgewählt wird.


13. Unterstützte Provider & Modell-Gänge

Provider Modelle Lokal
Anthropic Claude Fable 5, Haiku, Sonnet, Opus Nein
Google Gemini 3.7 Flash (bevorzugt), Gemini 3.5 Flash als Fallback, Gemini 3.1 Pro Preview Nein
OpenAI GPT-5.6 Luna/Terra/Sol via Responses API, GPT-5.3-Codex Nein
Ollama Qwen, Mistral und weitere (lokal & remote); Kimi K3, GLM 5.3, K2.7 Code via Ollama Cloud Ja / Cloud
Claude Code Subprozess-CLI-Sitzung Ja
agy Live erkanntes Gemini-, Claude- und GPT-OSS-Inventar via companion-for-agy CLI-Sitzung
Kimi (Moonshot) kimi-k2.7-code, kimi-k2.6 via OpenAI-kompatible API; kimi-cli/kimi-code CLI; Ollama Cloud API / CLI
OpenAI-kompatibel Beliebiger /v1/chat/completions-Endpunkt (base_url setzbar) Nein / Lokal

14. Ausführungsmuster

  • Einzelfahrt (Single) -- Ein Modell, ein Task
  • Kolonne (Convoy) -- Sequentiell, Ausgabe N wird Eingabe für N+1
  • Team -- Parallele spezialisierte Worker, Ergebnisse zusammengeführt
  • Schwarm (Swarm) -- Massiv parallele Mikrotasks (z. B. 20x Haiku), danach Aggregation
  • Hybrid -- Kombination aus Kolonnen- und Team-Phasen

15. Verwandte Tools & Ökosystem

Teil der ellmos-ai Multi-Agenten-Infrastruktur und des übergeordneten open-bricks Open-Source-Ökosystems:

Tool Organisation Beschreibung
coma ellmos-ai Multi-Agenten-Orchestrator und Ausführungskoordinator
swarm-ai ellmos-ai Schwarmintelligenz und autonomer Agentenkonsens
system-explorer ellmos-ai Lokale Systemerkennung und Ressourcen-Monitor
policy-registry ellmos-ai Einheitliche Berechtigungs- und Richtlinien-Engine
sqlite-transit-sync ellmos-ai Multi-Agenten Zustandssynchronisation via SQLite WAL
workflowhooker ellmos-ai Ereignis-Hooks und Agenten-Workflow-Trigger
memoryhooker ellmos-ai Transparentes SQLite/FTS5-Arbeitsgedächtnis für Agenten
agent-ops-stack ellmos-ai Operativer Sidecar-Stack für autonome Agenten
convergence-reconciler ellmos-ai Modell-Konvergenzprüfung und Konsens-Engine
DevCenter dev-bricks Entwickler-Leitstand, Repository-Dashboard und Umgebungsmanager
CodeBox dev-bricks Polyglotter Code-Snippet-Manager und Entwickler-Werkbank
open-bricks open-bricks Dachorganisation für modulare Open-Source Softwarewerkzeuge

16. Drittanbieter-Lizenzen & Transparenz

clutch verpflichtet sich zu absoluter Softwaretransparenz, Lizenz-Compliance und Schutz der Lieferkette:

  • Vollständige SPDX-Software-Inventur: Jede zwingende Laufzeitabhängigkeit (anthropic, google-genai, requests), optionale Web-Abhängigkeit (fastapi, uvicorn, python-multipart) und Entwicklungswerkzeuge (pytest, ruff) sind mit exakten SPDX-Kennungen in THIRD_PARTY_LICENSES.md dokumentiert.
  • Zero-Copyleft-Garantie: 100% aller Abhängigkeiten nutzen permissive, wirtschaftsfreundliche Open-Source-Lizenzen (MIT, Apache-2.0, BSD-3-Clause, PSF). Es existieren keinerlei GPL-, AGPL- oder virale Copyleft-Komponenten.
  • Unprivilegierter Benutzermodus (RunAsInvoker): Alle CLI-Befehle, Web-Oberflächen und lokalen Datenbanken laufen im regulären Benutzerkontext ohne administrative Privilegienerweiterung.
  • Laufzeit-Governance-Invarianten: Formale Bestätigung der 10 Governance- und Laufzeit-Invarianten (INV-LOCAL-01 bis INV-SLA-10).

Vollständige Abhängigkeitstabellen, Lizenztexte und Urheberrechtshinweise finden sich in THIRD_PARTY_LICENSES.md.


17. Sicherheitsrichtlinie & Haftung

Details zu unterstützten Versionen, Reaktionszeiten und Meldeverfahren finden sich in SECURITY.md.

Haftungsausschluss / Liability Disclaimer

Dieses Projekt ist eine unentgeltliche Open-Source-Schenkung im Sinne der §§ 516 ff. BGB. Die Haftung des Urhebers ist gemäß § 521 BGB auf Vorsatz und grobe Fahrlässigkeit beschränkt. Ergänzend gelten die Haftungsausschlüsse der MIT-Lizenz.

Nutzung auf eigenes Risiko. Keine Wartungszusage, keine Verfügbarkeitsgarantie, keine Gewähr für Fehlerfreiheit oder Eignung für einen bestimmten Zweck.

This project is an unpaid open-source donation. Liability is limited to intent and gross negligence (§ 521 German Civil Code). Use at your own risk. No warranty, no maintenance guarantee, no fitness-for-purpose assumed.


18. Verifikation & Testsuite

clutch verfügt über eine umfassende automatisierte Testsuite mit 100% Erfolgsquote unter Linux, Windows und macOS:

# Unit-, Vertrags- und Regressionstests ausführen
python -m pytest -ra -v

# Schneller Durchlauf
pytest -q

# Code-Stil und Linter prüfen
ruff check .

# Bytecode-Kompilierung validieren
python -m compileall clutch tests

Die Testsuite prüft:

  • Routing-Mechanik, Aufgabenanalyse und Zweck-Zuordnung (test_route.py, test_clutch.py)
  • Automobile Ausführungsmuster: Kolonne, Team, Schwarm und Hybrid (test_patterns.py)
  • Lernengine, Epsilon-Greedy-Exploration und Fitness-Feedback (test_learning.py)
  • Provider-Engines und Modellkatalog-Parität (test_kimi_motoren.py, test_motorblock.py)
  • Metadaten-Verträge, zweisprachige Doku-Parität, CI-Timeouts, Gitignore-Hygiene und Lizenz-Integrität (test_metadata.py)