Provider-neutral LLM orchestration engine with auto-learning
clutch (German: Kupplung) uses a driving metaphor to intelligently route tasks to optimal LLM models across multiple providers. It analyzes task complexity, selects the right model and reasoning level, tracks budgets, and learns from experience.
- Provider-neutral -- seamlessly switch between Anthropic (Claude), Google (Gemini), Ollama (local), and Claude Code
- Auto-routing -- analyzes task complexity and picks the optimal model + reasoning level
- Budget tracking -- four-zone fuel gauge (green/yellow/orange/red) with daily and monthly limits
- Learning engine -- fitness scoring and epsilon-greedy exploration that improves routing over time
- Execution patterns -- single tasks, chains (convoy), parallel teams, and swarm processing
- Health monitoring -- circuit breakers, latency tracking, and provider failover
- SQLite metrics -- persistent trip log for analysis and optimization
The entire system follows a car/driving metaphor:
+----------------------------------+
| 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) |
+----------------+ +------------+ +-------------+
| Component | Role | Module |
|---|---|---|
| Fahrer (Driver) | Orchestrator -- picks model, reasoning, pattern | fahrer.py |
| Strecke (Road) | Task analysis and classification | strecke.py |
| Getriebe (Gearbox) | Provider-neutral model registry | getriebe.py |
| Gang (Gear) | A specific model (G1--G5) | getriebe.py |
| Gas/Bremse (Throttle/Brake) | Reasoning level (0--100%) | gas_bremse.py |
| Kupplung (Clutch) | Model switching mechanism | kupplung.py |
| MotorBlock (Engine) | Unified API call layer | motorblock.py |
| Tacho (Speedometer) | Metrics collection | tacho.py |
| Tankuhr (Fuel Gauge) | Budget tracking (4 zones) | tankuhr.py |
| Bordcomputer (Onboard Computer) | Health monitor, circuit breaker | bordcomputer.py |
| Fahrtenbuch (Trip Log) | SQLite metrics storage | fahrtenbuch.py |
| Fahrschule (Driving School) | Learning / evolution engine | fahrschule.py |
| Road | Difficulty | Default Gear | Throttle | Pattern |
|---|---|---|---|---|
| Feldweg (Dirt road) | Trivial | Haiku (G1) | 30% | Single |
| Landstrasse (Country road) | Standard | Sonnet (G3) | 50% | Single |
| Bundesstrasse (Highway) | Bugfix | Sonnet (G3) | 70% | Single |
| Autobahn (Motorway) | Architecture | Opus (G5) | 90% | Single |
| Rallye (Rally) | Bulk ops | Haiku (G1) | 30% | Swarm |
| Konvoi (Convoy) | Pipeline | Sonnet (G3) | 50% | Chain |
| Teamfahrt (Team drive) | Multi-file | Sonnet (G3) | 50% | Team |
| Langstrecke (Long distance) | Complex | Opus (G5) | 90% | Hybrid |
git clone https://github.com/ellmos-ai/clutch.git
cd clutch
pip install -e .- Python 3.10+
- API keys for your desired providers (set as environment variables):
ANTHROPIC_API_KEYfor Claude modelsGOOGLE_API_KEYfor Gemini models- Ollama running locally for local models
from kupplung import Fahrer
# Create a driver (uses all configured providers)
fahrer = Fahrer()
# Describe your task -- the driver handles everything
result = fahrer.fahren(
"Fix the authentication bug in the login module",
handler=my_handler,
)
# Inspect what was chosen
print(result.config.gang.name) # "claude-sonnet"
print(result.config.gang.provider) # "anthropic"
print(result.config.gas.wert) # 0.7
# Dashboard
status = fahrer.status()
print(status["tankuhr"]["zone"]) # "green"
print(status["getriebe"]) # "Getriebe[haiku(G1), flash(G2), ...]"
# Learn from past runs
fahrer.trainieren()All config lives in config/:
| File | Purpose |
|---|---|
kupplung.json |
Global settings (driver defaults, swarm limits, budget) |
getriebe.json |
All gears + provider mappings |
strecken.json |
Road type to gear/throttle mapping |
fitness_criteria.json |
Learning engine thresholds |
| Zone | Usage | Allowed Gears |
|---|---|---|
| Green | 0--30% | All (G1--G5) |
| Yellow | 30--60% | G1--G3 |
| Orange | 60--80% | G1--G2 only |
| Red | 80--100% | None (budget exhausted) |
| Provider | Models | Local |
|---|---|---|
| Anthropic | Claude Haiku, Sonnet, Opus | No |
| Gemini Flash, Pro | No | |
| Ollama | Qwen, Mistral, and more | Yes |
| Claude Code | Via subprocess | Yes |
- Single -- one model, one task
- Convoy (Kolonne) -- sequential chain, output N feeds input N+1
- Team -- parallel specialized workers, results merged
- Swarm -- massively parallel micro-tasks (e.g., 20x Haiku), then aggregation
Kupplung/
├── kupplung/
│ ├── __init__.py
│ ├── fahrer.py # Orchestrator
│ ├── strecke.py # Task analysis
│ ├── getriebe.py # Model registry
│ ├── kupplung.py # Model switching
│ ├── motorblock.py # Unified API layer
│ ├── gas_bremse.py # Reasoning level
│ ├── fahrtenbuch.py # SQLite metrics
│ ├── bordcomputer.py # Health monitor
│ ├── tankuhr.py # Budget tracking
│ ├── tacho.py # Metrics
│ ├── fahrschule.py # Learning engine
│ └── patterns/
│ ├── kolonne.py # Chain pattern
│ ├── team.py # Parallel pattern
│ └── schwarm.py # Swarm pattern
├── config/
│ ├── kupplung.json
│ ├── getriebe.json
│ ├── strecken.json
│ └── fitness_criteria.json
├── tests/
│ └── test_kupplung.py
└── data/ # Runtime data (not tracked)
See CONTRIBUTING.md for guidelines.
MIT License. See LICENSE for details.
clutch (deutsch: Kupplung) ist eine provider-neutrale LLM-Orchestration-Engine. Das gesamte System nutzt eine durchgaengige Auto-Metapher als Domain Language -- die deutschen Code-Identifier sind bewusst gewaehlt.
| Deutsch (Code) | Englisch | Beschreibung |
|---|---|---|
| Fahrer | Driver | Der Orchestrator -- waehlt Modell, Reasoning-Level und Ausfuehrungsmuster |
| Strecke | Road / Route | Der Task bzw. die Aufgabe, die analysiert und klassifiziert wird |
| Getriebe | Gearbox | Die Modell-Registry -- verwaltet alle Gaenge ueber alle Provider |
| Gang | Gear | Ein konkretes LLM-Modell (G1=Haiku bis G5=Opus) |
| Kupplung | Clutch | Der Schaltmechanismus -- entscheidet wann und wie zwischen Modellen gewechselt wird |
| Gas / Bremse | Throttle / Brake | Reasoning-Level: Gas = gruendlicher (mehr Tokens), Bremse = direkter (weniger) |
| MotorBlock | Engine Block | Die einheitliche API-Aufrufschicht fuer alle Provider |
| Tacho | Speedometer | Metriken-Erfassung waehrend der Task-Ausfuehrung |
| Tankuhr | Fuel Gauge | Budget-Tracking mit 4 Zonen (gruen/gelb/orange/rot) |
| Bordcomputer | Onboard Computer | Health-Monitor mit Circuit-Breaker und Anomalie-Erkennung |
| Fahrtenbuch | Trip Log | SQLite-basierter Metrik-Speicher fuer alle Fahrten |
| Fahrschule | Driving School | Lernengine -- optimiert das Routing durch Fitness-Scoring |
| Strecke | Schwierigkeit | Beispiel |
|---|---|---|
| Feldweg | Trivial | Typos, Formatierung, Kommentare |
| Landstrasse | Standard | Feature-Entwicklung, einfaches Refactoring |
| Bundesstrasse | Mittel | Bugfixes, Debugging |
| Autobahn | Hoch | Architektur-Design, System-Migration |
| Pruefstrecke | Review | Code-Review, Qualitaetspruefung |
| Rallye | Bulk | Massenformatierung, Batch-Operationen |
| Konvoi | Pipeline | Sequentielle Verarbeitung (Output N -> Input N+1) |
| Teamfahrt | Parallel | Multi-File-Features, parallele Spezialisten |
| Langstrecke | Komplex | Grosse mehrstufige Projekte (Hybrid-Muster) |
| Testfahrt | Tests | Automatische Test-Generierung |
| Muster | Metapher | Beschreibung |
|---|---|---|
| Einzelfahrt | Ein Auto | Ein Modell, ein Task |
| Kolonne | Fahrzeugkolonne | Sequentiell -- Output von Schritt N wird Input fuer N+1 |
| Team | Fahrgemeinschaft | Parallel -- spezialisierte Worker, Ergebnisse zusammengefuehrt |
| Schwarm | Autobahnverkehr | Massiv parallel -- viele guenstige Worker fuer Mikrotasks |
| Hybrid | Rallye mit Etappen | Kombination aus Kolonne- und Team-Phasen |
from kupplung import Fahrer
fahrer = Fahrer()
ergebnis = fahrer.fahren(
"Fix den Bug in der Auth-Komponente",
handler=mein_handler,
)
print(ergebnis.config.gang.name) # "claude-sonnet"
print(ergebnis.config.gas.wert) # 0.7
print(fahrer.status()["tankuhr"]) # Budget-StandDieses 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 aus GPL-3.0 / MIT / Apache-2.0 §§ 15–16 (je nach gewählter 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.