# Polyad

> Polyad — çok-modelli delegasyon

- Skill: `emircbngl/polyad` (Agent Skill)
- Install (CLI): `npx skillmds@latest add emircbngl/polyad`
- Raw SKILL.md: https://api.skillmd.com/api/skills/emircbngl/polyad/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: emircbngl (https://skillmd.com/u/emircbngl)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/emircbngl/polyad

---


# Polyad — çok-modelli delegasyon

SEN ana AI'sın (orkestratör). Zekâ sende; `polyad` CLI sadece boru tesisatı:
kanal keşfi, tek-tip çağrı yüzeyi, maliyet defteri. Katalog + kararlar SENDE.

CLI: `polyad` (PATH'te). Kaynak `~/.claude/tools/polyad/`, katalog `models.json`,
tasarım `DESIGN.md`. Ağ çağrısı yapar → Bash'te sandbox'sız çalıştır.

## Protokol (her delegasyon) — DETAYLI karar prosedürü: `ROUTING.md`

Karar hata-dirençli olmalı. İlke: model seçimini yargıyla YAPMA — `polyad route`
deterministik hesaplasın. Sen parçalar + her parçanın özelliklerini doğru yazarsın.

1. **Parçala + spec yaz.** İşi alt görevlere böl; HER birine `route_input.schema.json`
   spec'i doldur: `type` (agent/function), `quality` (critical/normal/bulk), `modality`
   (text/vision/...), `task_type` (router_table anahtarı), `est_ctx_k`, `privacy`
   (public/sensitive), `deps`, `verify`. Bu alanları düşünmek zorunda olman hata önler.
2. **Keşfet.** `polyad doctor` — ŞU AN canlı kanallar (codex login, API anahtarları, local
   sunucular + modelleri, CLI'lar). route bunu otomatik kullanır.
3. **Yönlendir (deterministik).** `polyad route --file subtasks.json [--budget max|mid|min|free]`.
   **Bütçe kademesi** (kullanıcı max/mid/min/free der ya da doğal dille; DEMEZSE sen karar ver):
   - `max` = maliyete bakma, en iyi kalite (router best) — planlama/kritik iş
   - `mid` = fiyat/performans, f/p kazananı (router best_value) — **belirtilmezse mantıklı varsayılan**
   - `min` = kalite tabanını geçen en ucuz (bedava/local'i tercih eder) — bulk/basit
   - `free` = sadece $0 kanallar (abonelik CLI + Gemini free + local)
   Kritik işte kalite tabanı korunur: `min` bile kritik işte çok zayıf modele düşmez.
   route SERT filtreler (modalite/bağlam/canlı-erişim/gizlilik) → YUMUŞAK sıralar (bütçe) →
   seçilen+adaylar+maliyet+komut verir; uygun yoksa `no_route` + neden. Kataloğu elle
   sorgulamak istersen: `polyad catalog --task <tip>|--free|--vision|--grep`.
4. **Plan doğrula.** route çıktısındaki `warnings` + `approve_before_spend`'i oku. Uyarı
   (no_route, kritik→düşük-kalite, kritik→verify-yok, döngü, maliyet eşiği) varsa DUR,
   düzelt, yeniden route et. Büyük/riskli iş → parçalamayı eleştirmen ajana incelet.
   Ücretli/hassas ise planı kullanıcıya özetleyip onay al.
5. **Yürüt.** route'un verdiği komutları bağımsızları PARALEL koştur. Fonksiyon işlerinde
   `--schema` ver. Bağımlılar öncül bitince.
6. **Doğrula + derle + raporla.** Her çıktıyı `verify`'a göre denetle (kritik → asla körü
   körüne). Parçaları SEN birleştir. `polyad costs --run <id>` ile maliyeti dürüstçe raporla.

## Çalışma modları (delegasyon TEK mod değil)

Görevi tanı, doğru modu seç — birden çok mod birleştirilebilir:

1. **Delegate** (yukarıdaki protokol): işi parçala → route → paralel yürüt → derle.
   Tanımlı, ayrıştırılabilir iş için.
2. **Consult / diyalog**: bir modelle KARŞILIKLI konuş, kendi kör noktanı bul, içine
   sinene kadar. Durum tutulur:
   `polyad converse --session S --channel C --model M "mesaj" [--system F] [--reset]`
   Aynı `--session` ile tekrar tekrar çağır; model önceki turları hatırlar. Tatmin olana
   kadar sürdür. Kendi çıktını eleştirt, itiraz et, savını test et.
3. **Panel / çok-ses**: aynı soruyu BİRDEN ÇOK modele aynı anda sor (çeşitlilik = kör-nokta
   bulma). `polyad panel "soru" --models "gemini:gemini-3.5-flash,lmstudio:qwen2.5-7b-instruct" [--schema F]`
   Farklı bakışları topla, sen sentezle. Adversarial doğrulama için ideal.
4. **Converge / yakınsama**: bul→düzelt→tekrar-kontrol, TEMİZ gelene kadar otonom döngü.
   `polyad converge --check "KONTROL_CMD" --fix "DÜZELT_CMD" [--until-clean 2] [--max-rounds 6]`
   KONTROL_CMD JSON `{clean:true}` veya `{issues:[...]}` basar; sorun varsa DÜZELT_CMD
   çalışır (`$POLYAD_ISSUES` sorun dosyasını gösterir), sonra tekrar kontrol — ard arda
   `until-clean` temiz tura kadar. "Bug raporu gelmeyene kadar" tam bu.
   Örnek: `--check 'polyad ask --channel gemini --model gemini-3.5-flash --schema bug.json "kodu incele"'`
   `--fix 'polyad agent --via codex --repo R "şu sorunları gider: $(cat $POLYAD_ISSUES)"'`

5. **Council / advanced planning**: iş BAŞLAMADAN önce güvenilen modellerle kurul kurup planı
   tartış. **BÜTÇE KADEMESİNE (max/mid/min/free) GÖRE ÖLÇEKLENİR** — planlama da route gibi
   kademeyle yönetilir:
   `polyad council "hedef" --budget max|mid|min|free [--context F]`
   - `max` → 4 üye / 2 tur, metered modeller de dahil (en geniş, en güçlü kurul)
   - `mid` → 3 üye / 2 tur (çeşitli sub+free)
   - `min` → 2 üye / 1 tur (sadece $0-marjinal, kısa)
   - `free` → 3 üye / 1 tur (yalnız $0: local + subs + free-gemini)
   Üyeler otomatik LAB-ÇEŞİTLİLİĞİYLE seçilir (aynı labdan 2 model YOK; GPT-5.6/Claude/Gemini
   farklı lineage). `--members` verirsen bütçe seçimini geçersiz kılar. Tur 2 çapraz-eleştiri.
   SEN sentezlersin: **anlaşmazlıkları** çıkar (bağımsız oy sayma). **Karar sende.**
   **NE ZAMAN:** büyük/riskli/belirsiz işten ÖNCE — kullanıcı max/mid dediyse KURULU KUR;
   min/free'de hafif tut ya da atla. Sonra aynı kademeyle `route` ile parçala.
   (Not: `claude -p` nested Claude oturumunda 401 verebilir; kendi terminalde çalışır. Üye
   düşse kurul sürer.)

Modlar birleşir: **council** ile planı sağlamlaştır → **route** ile parçala/dağıt → çıktıyı
**panel**'e eleştirt → **converge** ile temizle → kritik noktada **converse** ile didiş → derle.

## Gölge-mod: Polyad işe yarıyor mu? (ÖLÇÜM — en önemli disiplin)

Polyad'ın bakımını hak ettiğini kanıtlayabilecek TEK mekanizma. Gerçek işlerde kullan:

```bash
polyad shadow log --task "..." --file subtasks.json --budget mid   # Polyad'ın seçimi + düz abonelik TABAN ÇİZGİSİ kaydedilir
polyad shadow outcome --trial <ID> --arm polyad --duration-s N --actual-usd N [--retries N] [--rework] [--accepted] [--task-type T]
polyad shadow report                                                # iki kolu karşılaştır
```

- `differs=false` çıkıyorsa → Polyad taban çizgisiyle aynı seçimi yapmış, **yönlendirme fayda eklemiyor**; o iş tipinde delege etme.
- `--rework` işaretlersen ilgili modeller öğrenme defterine de düşer (otomatik downrank).
- Rapor n<10'da açıkça "SONUÇ ÇIKARMA" der. **20-30 karşılaştırılabilir görevden önce yeni mod ekleme** (Codex tavsiyesi).
- Kural: Polyad ancak taban çizgisinden DÜŞÜK rework/maliyet üretirse kullanılmaya değer. Aksi çıkarsa dürüstçe söyle.

**Stop-loss:** `polyad route ... --stop-loss 0.50` → plan tavanı aşarsa `stop_loss_triggered` + tek güçlü abonelik modeline düşme önerisi. Her plan zaten `baseline` alanında "yönlendirme yapmasan ne kullanırdın"ı gösterir — ucuz seçenek hep gözde.

## Emniyet / verimlilik kuralları

- **Delegasyon çıktısına körü körüne güvenme.** Fonksiyon işlerinde şema iste (`--schema`);
  ajan işlerinde doğrula (test/derleme/inceleme) — kritikse triad-tarzı ikinci göz.
- **Gizlilik:** Gemini FREE tier verisi Google'ca ürün geliştirmede kullanılır. Hassas
  içerik → local (Ollama/LM Studio) veya abonelik kanalları (codex/claude), free API'ye asla.
- **Maliyet kademesi işe göre.** Kullanıcı max/mid/min/free dediyse ona uy; DEMEDİYSE sen
  seç: bulk/basit → `min`; genel iş → `mid` (f/p); **planlama/council/kritik-inceleme →
  `max`** (en iyi çeşitli modeller: GPT-5.6, Claude, Gemini Pro), maliyet ikincil — plan
  birkaç çağrı, hata pahalı. "Sadece bedavaya gitmek" planlamada YANLIŞ. `--max-cost` ile
  çağrı tavanı; her şeyi frontier'a atmak da israf.
- **Katalog tazeliği:** `doctor` katalog >30 gün eskiyse uyarır → araştırma workflow'unu
  yeniden koş (bkz. DESIGN.md; polyad-model-catalog workflow). Fiyat/model hızlı değişir.
- **Yeni sağlayıcı eklemek:** kullanıcı bir API anahtarı girerse (`export X_API_KEY=...`),
  `doctor` onu otomatik görür; OpenAI-uyumlu sağlayıcılar (OpenRouter/DeepSeek/Groq...)
  preset'te hazır, `ask --channel <ad>` yeter. Egzotik endpoint → `connections.json`.

## Mevcut durum (2026-07-14, ilk kurulum)

- Canlı: codex (ChatGPT sub, gpt-5.6-terra) ✓ · Gemini free key ✓ · LM Studio server ✓ ·
  claude CLI ✓. Ollama daemon kapalı (açmak için `ollama serve`).
- Local modeller güncelliği: kullanıcının qwen2.5-7b + qwen2.5-coder-32b ESKİ →
  katalog qwen3.5:9b (vision dahil) + devstral-small-2:24b öneriyor (henüz çekilmedi).
- İlk gerçek çok-model delegasyonu + router kalibrasyonu henüz yapılmadı.

## Triad ile ilişki

Görsel Blender düzeltme döngüsü ayrı ve olgun: `/triad`. Polyad genel çerçeve; görsel-QA
işini triad'a yönlendir. Bakım: `polyad.py` (adaptörler), `models.json` (katalog),
`DESIGN.md` (mimari) — hepsi `~/.claude/tools/polyad/`. Değişiklikten sonra
`POLYAD_MOCK=1 polyad ...` ile anahtarsız test et.