Skip to content

README_ru.md

Latest commit

 

History

History
264 lines (209 loc) · 17.3 KB

README_ru.md

File metadata and controls

264 lines (209 loc) · 17.3 KB
Raw

clutch

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

clutch

Независимый от провайдера движок оркестрации LLM с автоматическим обучением

Python 3.10+ License MIT Version 0.4.0

clutch (нем. Kupplung — «сцепление») использует автомобильную метафору для интеллектуальной маршрутизации задач к оптимальным LLM-моделям нескольких провайдеров. Система анализирует сложность и цель задачи, выбирает подходящую модель и уровень рассуждений, отслеживает бюджет и учится на опыте. Доступна в виде библиотеки, CLI или локального веб-приложения.

Возможности

  • Независимость от провайдера — Anthropic (Claude), Google (Gemini), Ollama (локально и удалённо), Claude Code и Kimi (Moonshot API / CLI / Ollama Cloud)
  • Автоматическая маршрутизация — анализирует сложность и цель задачи (программирование, видение, исследование, пакетная обработка) и выбирает оптимальную модель + уровень рассуждений
  • Учёт цели и визуальных данных — направляет ввод изображений/документов к моделям с поддержкой Vision; сопоставляет задачи с сильными сторонами моделей
  • CLI + веб-интерфейс — clutch route/run/chat/models/stats, а также опциональный веб-чат на FastAPI (clutch serve --web)
  • Хранилище учётных данных — хранит API-ключи в ~/.clutch/credentials.json (clutch keys ...); переменные окружения имеют приоритет
  • Обнаружение моделей — автоматическое обнаружение установленных моделей Ollama (локальных/удалённых) и совместимых с OpenAI эндпоинтов /v1/models
  • Отслеживание бюджета — четырёхзонный индикатор топлива (зелёный/жёлтый/оранжевый/красный) с дневными и месячными лимитами
  • Движок обучения — оценка пригодности и epsilon-жадное исследование, постепенно улучшающие маршрутизацию
  • Паттерны выполнения — одиночные задачи, цепочки (Kolonne/конвой), параллельные команды и роевая обработка
  • Мониторинг состояния — автоматические выключатели, отслеживание задержек, оповещения об избыточном использовании/взрыве токенов, отказоустойчивость провайдеров
  • SQLite-метрики — постоянный журнал поездок, чат-сессии, библиотека промптов и профили

Архитектура

Вся система следует автомобильной метафоре (идентификаторы кода — на немецком языке):

                    +----------------------------------+
                    |            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)    |
        +----------------+    +------------+    +-------------+
Компонент Роль Модуль
Fahrer (Водитель) Оркестратор — выбирает модель, рассуждение и паттерн выполнения fahrer.py
Strecke (Трасса) Анализ и классификация задач strecke.py
Getriebe (Коробка передач) Независимый от провайдера реестр моделей getriebe.py
Gang (Передача) Конкретная модель (G1--G5) getriebe.py
Gas/Bremse (Газ/Тормоз) Уровень рассуждений (0--100%) gas_bremse.py
Kupplung (Сцепление) Механизм переключения моделей kupplung.py
MotorBlock (Блок двигателя) Унифицированный слой вызовов API motorblock.py
Tacho (Спидометр) Сбор метрик tacho.py
Tankuhr (Указатель топлива) Отслеживание бюджета (4 зоны) tankuhr.py
Bordcomputer (Бортовой компьютер) Монитор состояния, автоматический выключатель bordcomputer.py
Fahrtenbuch (Путевой журнал) SQLite-хранилище метрик fahrtenbuch.py
Fahrschule (Автошкола) Движок обучения / эволюции fahrschule.py

Типы трасс

Трасса Сложность Передача по умолч. Газ Паттерн
Feldweg (Грунтовая дорога) Тривиально Haiku (G1) 30% Одиночный
Landstrasse (Просёлочная дорога) Стандартно Sonnet (G3) 50% Одиночный
Bundesstrasse (Шоссе) Исправление ошибок Sonnet (G3) 70% Одиночный
Autobahn (Автобан) Архитектура Opus (G5) 90% Одиночный
Rallye (Ралли) Пакетные операции Haiku (G1) 30% Рой
Konvoi (Конвой) Конвейер Sonnet (G3) 50% Цепочка
Teamfahrt (Командная поездка) Несколько файлов Sonnet (G3) 50% Команда
Langstrecke (Дальняя дистанция) Сложные задачи Opus (G5) 90% Гибрид

Установка

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

Требования

  • Python 3.10+
  • API-ключи для нужных провайдеров (задаются как переменные окружения):
    • ANTHROPIC_API_KEY для моделей Claude
    • GOOGLE_API_KEY для моделей Gemini
    • Локально запущенный Ollama для локальных моделей

Быстрый старт

from clutch import Fahrer

# Создать водителя (использует все настроенные провайдеры)
fahrer = Fahrer()

# Описать задачу — водитель берёт всё на себя
result = fahrer.fahren(
    "Fix the authentication bug in the login module",
    handler=my_handler,
)

# Проверить выбранную конфигурацию
print(result.config.gang.name)       # "claude-sonnet"
print(result.config.gang.provider)   # "anthropic"
print(result.config.gas.wert)        # 0.7

# Панель управления
status = fahrer.status()
print(status["tankuhr"]["zone"])     # "green"
print(status["getriebe"])            # "Getriebe[haiku(G1), flash(G2), ...]"

# Учиться на прошлых запусках
fahrer.trainieren()

Интерфейс командной строки

После pip install -e . команда clutch становится доступной:

clutch route "Fix the auth bug"      # показать решение о маршрутизации (dry-run, без вызова LLM)
clutch "Explain quantum computing"    # однократно: маршрутизация + выполнение, вывод ответа
clutch run "..." --json               # машиночитаемый вывод (для других агентов)
clutch chat                           # интерактивный REPL
clutch models [--json]                # список всех передач (моделей)
clutch stats                          # панель использования / бюджета / состояния
clutch config <key> [value]           # чтение/установка настроек CLI
clutch keys set MOONSHOT_API_KEY      # сохранить API-ключ (скрытый ввод; значения никогда не отображаются)
clutch keys list                      # список сохранённых имён ключей (без значений)
clutch serve --web                    # запустить веб-интерфейс (требуется: pip install -e ".[web]")

Три режима использования: консоль (для людей), веб-интерфейс (для людей, графический) и CLI/API (другие LLM/агенты маршрутизируют задачи через --json или совместимый с OpenAI веб-эндпоинт).

API-ключи и учётные данные

clutch разрешает ключи в следующем порядке (побеждает первое непустое значение):

  1. Переменная окружения (например, MOONSHOT_API_KEY) — предпочтительно для CI/серверов
  2. Хранилище clutch ~/.clutch/credentials.json (через clutch keys set, режим файла 0600)
  3. Файлы ~/.credentials/<name> (совместимость с родственными инструментами)

Значения никогда не выводятся, не логируются и не коммитятся.

Конфигурация

Конфигурация по умолчанию находится в clutch/config/, чтобы редактируемые установки и wheels использовали одни и те же встроенные значения маршрутизации. Передайте пользовательский base_dir с собственной папкой config/ в Fahrer, если нужны переопределения для конкретного проекта.

Файл Назначение
kupplung.json Глобальные настройки (значения водителя по умолч., лимиты роя, бюджет)
getriebe.json Все передачи + сопоставления провайдеров
strecken.json Сопоставление типа трассы с передачей/газом
fitness_criteria.json Пороги движка обучения

Бюджетные зоны

Зона Использование Доступные передачи
Зелёная 0--30% Все (G1--G5)
Жёлтая 30--60% G1--G3
Оранжевая 60--80% Только G1--G2
Красная 80--100% Нет (бюджет исчерпан)

Поддерживаемые провайдеры

Провайдер Модели Локально
Anthropic Claude Haiku, Sonnet, Opus Нет
Google Gemini Flash, Pro Нет
Ollama Qwen, Mistral и другие (локально и удалённо) Да
Claude Code Через subprocess (CLI-сессия) Да
Kimi (Moonshot) kimi-k2.7-code, kimi-k2.6 через совместимый с OpenAI API; kimi-cli/kimi-code CLI; Ollama Cloud API / CLI
OpenAI-совместимые Любой эндпоинт /v1/chat/completions (задать base_url) Нет

Паттерны выполнения

  • Одиночный — одна модель, одна задача
  • Конвой (Kolonne) — последовательная цепочка, выход N подаётся на вход N+1
  • Команда — параллельные специализированные исполнители, результаты объединяются
  • Рой — массово-параллельные микрозадачи (например, 20× Haiku), затем агрегация

Структура проекта

clutch/
+-- clutch/
|   +-- __init__.py
|   +-- fahrer.py          # Оркестратор
|   +-- strecke.py         # Анализ задач
|   +-- getriebe.py        # Реестр моделей
|   +-- kupplung.py        # Переключение моделей
|   +-- motorblock.py      # Унифицированный слой API
|   +-- gas_bremse.py      # Уровень рассуждений
|   +-- fahrtenbuch.py     # SQLite-метрики
|   +-- bordcomputer.py    # Монитор состояния
|   +-- tankuhr.py         # Отслеживание бюджета
|   +-- tacho.py           # Метрики
|   +-- fahrschule.py      # Движок обучения
|   +-- patterns/
|       +-- kolonne.py     # Паттерн цепочки
|       +-- team.py        # Параллельный паттерн
|       +-- schwarm.py     # Паттерн роя
|       +-- hybrid.py      # Гибридный паттерн
|   +-- config/
|       +-- kupplung.json
|       +-- getriebe.json
|       +-- strecken.json
|       +-- fitness_criteria.json
+-- tests/
|   +-- test_clutch.py
|   +-- test_learning.py
|   +-- test_patterns.py
|   +-- test_route.py
+-- data/                  # Данные времени выполнения (не отслеживаются)

Тесты

pip install -e . pytest
pytest -q

Pytest настроен на сбор только из tests/. Скрипты в корневом каталоге, такие как demo.py, live_test.py и claude_code_test.py, — это ручные проверки провайдеров.

Участие в разработке

Руководство см. в CONTRIBUTING.md. Немецкая автомобильная терминология API описана в GLOSSARY.md.

Лицензия

Лицензия MIT. Подробности см. в LICENSE.

Ответственность / Haftung

Данный проект является безвозмездным пожертвованием с открытым исходным кодом в смысле §§ 516 и далее BGB (Германский гражданский кодекс). Ответственность автора в соответствии с § 521 BGB ограничена умыслом и грубой небрежностью. Дополнительно применяются положения об ограничении ответственности GPL-3.0 / MIT / Apache-2.0 §§ 15–16 (в зависимости от выбранной лицензии).

Использование на свой страх и риск. Никаких обязательств по обслуживанию, гарантий доступности, гарантий отсутствия ошибок или пригодности для какой-либо конкретной цели не предоставляется.

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.