orkestra — katmanlı LLM orkestrasyonu

01 — mimari

Nasıl çalışır

Muhakeme gerektirmeyen mikro-görevler ucuz modellere, her çıktının doğrulaması ve son sentez güçlü modele gider. Ucuz modelin hatası duvara örülmeden kalfada yakalanır; güçlü modelin pahalı muhakemesi yalnız üç yerde harcanır: bölmek, hakemlik, sentez.

şef → hamal → kalfa → birleştirici · kesikli kırmızı: retry döngüsü · kesikli gri: bütçe vanası ve kullanım defteri

Neden ucuz model muhakeme yapmaz? Ucuz modelin hata modu "kendinden emin uydurma"dır — ona muhakeme verirsen hatasını denetleyecek başka ucuz model gerekir, sonsuz regres. Bunun yerine görev tanımı daralır: tek iş, tek çıktı şeması. "Bilmiyorum" meşru bir cevaptır; uydurmak ise kalfanın şema + alıntı kontrollerinde garantili yakalanır.

Koşudan önce

Strong model: --strong veya tier: strong ilk kayıtlı model — yoksa EngineError, sessiz fallback yok.
Hamal havuzu: tüm tier: cheap modeller — boşsa EngineError.
--budget verildiyse her modelde --cost-in/--cost-out ipucu zorunlu; vana çalışamayacaksa koşu başlamaz.

Koşu sonunda

run() her zaman rapor döner: {status, pieces, usage, errors}.
Parça içi hatalar rapora yazılır; koşuyu imkânsız kılan hatalar exception fırlatılır.
Birleştirici başarısız parça id'lerini bilir ve çıktıda açıkça belirtir — hiçbir şey sessizce "geçmiş" sayılmaz.

02 — kadro

Roller

Dört rol, iki model katmanı. Strong katman yalnız karar gereken yerde çalışır; hacim işi cheap havuzundadır.

Rol	Kim	Girdi → Çıktı	Altın kural
ŞEF	`tier: strong` model	Görev → mikro-görev listesi (JSON plan)	Her parçanın doğruluğu mekanik kontrol edilebilmeli. "Araştır" değil, "şu 20 URL'deki fiyatları tabloya dök" yazar.
HAMAL	`tier: cheap` model havuzu	Mikro-görev → katı şemalı JSON	Muhakeme yasak: emin değilse uydurmaz, `"unknown"`/`null` yazar. Paralel çalışır (`--max-parallel`).
KALFA	Önce kod, sonra strong model	Worker çıktısı → `{pass, reasons[], fix_hint}`	Aşama 1 deterministik: şema geçerli mi, `x-from-input` alıntısı input'ta var mı. Aşama 2 (gri alan) strong modele sorulur.
BİRLEŞTİRİCİ	`tier: strong` model	Doğrulanmış parçalar → nihai çıktı	Sadece geçmiş parçaları görür; sentezdeki muhakeme onundur.

03 — hata sözleşmesi

Retry politikası

Bir parça asla "idare eder" diye geçmez. Kalan çıktı önce ucuz denemeyle düzeltilir, tükenirse güçlü modele yükseltilir — o da kalırsa dürüstçe başarısız sayılır.

Deterministik denetim bedava

JSON ayrıştı mı, output_schema'ya uyuyor mu, x-from-input alanları input listesinin elemanı mı. İhlaller modele sorulmadan doğrudan reasons olur.

fix_hint ile retry cheap

Kalan parça, violation listesi + fix_hint ile hamala geri döner. En fazla max_retries (varsayılan 2) deneme.

Strong'a yükseltme ×1

Retry tükenince parça bir kez strong modelde çalışır ve yine kalfadan geçmek zorundadır. Geçerse escalated sayılır.

failed — dürüst rapor son

O da kalırsa parça failed. Birleştirici hangi parçaların eksik olduğunu çıktıda açıkça belirtir; koşu partial veya failed.

ok partial failed budget_exceeded

Durum	Davranış
Hamal çıktısı bozuk JSON	Deneme sayılır → fix_hint ile retry
Şema / alıntı ihlali	Deterministik kalfa reddi → retry
Gri alan ihlali	Strong hakem reddi → retry
Retry tükendi	Strong modele 1 yükseltme denemesi
Yükseltme de kaldı	Parça `failed`; koşu `partial`/`failed`
Şef planı bozuk	1 düzeltme hakkı → `EngineError`
Hakem bozuk karar verir	1 retry → `EngineError` (altyapı arızası)
Bütçe doldu	Koşu durur → `budget_exceeded`
Strong/cheap model yok	Başlamadan `EngineError`

Bütçe vanası

--budget (USD) ve --token-budget her çağrıdan önce kontrol edilir. Vana kapanırsa koşu durur — o ana kadarki kullanım ve parça raporu kaybolmaz.

Sessiz hata yok

--no-arbitrate ile hakemlik kapatılırsa kriterler unchecked_acceptance olarak rapora yazılır. Hiçbir kontrol sessizce atlanmaz.

Dürüst ölçüm

Provider usage döndürmezse token'lar ~4 karakter/token tahmin edilir ve estimated: true işaretlenir. Rapor dürüst kalır.

04 — uçtan uca

Örnek senaryo: 20 URL → fiyat tablosu

Klasik altın görev: şef 20 parçaya böler, hamal havuzu çıkarır, kalfa alıntıyı denetler, birleştirici tabloyu kurar.

t-000Şef görevi 20 parçaya böler: t-001..t-020, her biri tek URL + output_schema {fiyat:number, kaynak:string(x-from-input)}.

poolHamal havuzu parçaları paylaşır; her parça tek çağrıda JSON döner.

denyKalfa deterministik denetler: kaynak input URL'lerinden biri değilse anında citation ihlali → retry.

t-007İki kez kalırsa → strong modele yükseltilir, escalated olarak geçer.

t-013Her şeye rağmen kalırsa → failed; birleştirici çıktıda "t-013 eksik" diye belirtir, status partial.

outRapor: tablo + parça durumları + çağrı başına token/maliyet dökümü.

bashkayıt + koşu

# provider + modeller (bir kez)
export OPENAI_API_KEY="sk-..."
orkestra providers add openai -u https://api.openai.com/v1 -k OPENAI_API_KEY
orkestra models add brain -p openai -t strong --model-id gpt-5 \
    --cost-in 2.0 --cost-out 8.0
orkestra models add mule  -p openai -t cheap --model-id gpt-5-mini \
    --purpose micro-task --cost-in 0.10 --cost-out 0.40

# koşu
orkestra run "Şu 20 ürün sayfasındaki fiyatları TL'ye çevirip tablo yap: ..." \
    --budget 0.50 --max-parallel 4

Şef'in ürettiği mikro-görev hamalın aldığı tek şeydir — dar talimat + input + output_schema + acceptance kriterleri + budget_tokens kotası. Kalan her şey orkestradadır.

05 — başla

CLI hızlı başlangıç

OpenAI-uyumlu herhangi bir endpoint kaydedilir; API anahtarları asla dosyaya yazılmaz — yalnızca env var adı saklanır.

# kurulum

git clone https://github.com/ZoriaSoft/orkestra.git
cd orkestra
pip install -e .

# geliştirme
pip install -e ".[dev]" && pytest

# 5 dakikada ilk koşu

export OPENAI_API_KEY="sk-..."
orkestra providers add openai --base-url https://api.openai.com/v1 \
    --api-key-env OPENAI_API_KEY
orkestra providers test openai
orkestra models add planner -p openai -t strong --model-id gpt-5
orkestra models add worker  -p openai -t cheap \
    --purpose micro-task --model-id gpt-5-mini
orkestra run "görevin" --budget 1.00

Konfigürasyon ~/.orkestra/config.yaml'da durur (ilk yazımda oluşur, mod 0600). Ana dizini ORKESTRA_HOME ile değiştirebilirsin.

# komutlar

Komut	İş
`providers add NAME -u URL [-k ENV] [-H 'K=V']`	OpenAI-uyumlu endpoint kaydet
`providers test NAME [--all]`	`/v1/models` probu: gecikme + ulaşılabilir modeller
`providers list / remove`	Provider tablosu / silme (kullanımdayken reddeder)
`models add NAME -p P -t strong\|cheap ...`	Model kaydet (`--purpose --model-id --cost-in --cost-out`)
`models list [--tier T] [--purpose P]`	Filtreli model tablosu
`config path / show`	Konfigürasyonun yeri ve içeriği
`run "TASK" [--budget $] [--token-budget N] [--max-parallel N] [--no-arbitrate] [--json]`	Görevi orkestradan uçtan uca çalıştır

Detaylı Türkçe rehberler depoda: docs/kurulum.md · docs/provider-ekleme.md · docs/model-ekleme.md · docs/orkestra-mantigi.md (tasarım gerekçesi).