Model & Provider

Model profili

model Primary {
  provider: "openai-compatible"
  base_url: "https://gateway.example/v1"
  model: "text-model-l"
  api_key: getEnv("api_key")
  timeout: 30000
  max_tokens: 4000
  capabilities: ["json_schema", "tool_calling"]
  cache: true
  cache_ttl: 60000
  cache_max_entries: 256
  stream: false
  reasoning: false
  multimodal: false
  cost_per_1k_tokens: 0.002
}

agent Analist {
  model: Primary
}

Model başına fiyat, tek bir agent birden çok model çalıştırdığında önem kazanır: fiyat verilmezse ucuz model de pahalı model de aynı orandan faturalanır ve escalate policy'sinin max_cost_per_call tavanı maliyeti değil token'ı ölçmüş olur. Agent geneli oran ve bütçeler için → Bütçeler ve limitler.

model Primary {
  provider: "openai-compatible"
  base_url: "https://gateway.example/v1"
  model: "text-model-l"
  api_key: getEnv("api_key")
  max_token: 100        // düşürüldü — gerçek anahtardan bir harf eksik
  cache_ttll: 5000      // düşürüldü
  multimodel: true      // düşürüldü — bayrak false kalır
}

Provider adapter'ları

base_url zaten endpoint yolunu içeriyorsa (örn. …/chat/completions) tekrar eklenmez; query string korunur. Bilinmeyen bir provider adı, hiçbir istek yapılmadan parse zamanında reddedilir: Error: Model 'M' has unknown provider '…'. Valid values: …

Tool çağrısı eşlemesi

Structured output desteği

İsteğin şekillenmesi

Her ask için gönderilen gövde şu kurallarla oluşturulur:

Korelasyon başlıkları her istekte gönderilir:

  x-luma-run-id      → logical_run_id   (mantıksal çalıştırma)
  x-luma-attempt-id  → attempt_id       (retry / policy adayı)
  x-luma-request-id  → local_request_id (tekil HTTP isteği)

Yanıttan okunan provider kimliği:
  x-request-id · request-id · anthropic-request-id → provider_request_id

Bu değerler telemetry event'lerine de yazılır; gateway loglarıyla trace'i eşleştirmeni sağlar. → Correlation

Yanıt işleme

ham yanıt (JSON veya SSE)
   ↓ adapter normalizasyonu → { content, refusal, toolCalls, usage }
   ↓ refusal varsa → MODEL_REFUSAL (retryable: false)
   ↓ toolCalls varsa → tool'ları çalıştır, sonucu ekle, döngüye dön
   ↓ content boş → MODEL_EMPTY_CONTENT (retryable)
   ↓ ```json çitleri temizlenir
   ↓ JSON.parse başarısız → MODEL_INVALID_RESPONSE (retryable)
   ↓ yerel schema doğrulaması başarısız → MODEL_INVALID_RESPONSE (retryable)
   ↓ sonuç

Model yanıtı ```json … ``` bloğu içine sararsa çitler otomatik temizlenir. Ham yanıtı görmek için LUMA_DEBUG_MODEL_RESPONSE=1 kullan.

Capability probe

Program başlamadan önce Luma, kullanılacak her model için gateway'in /models endpoint'ine bir istek atar ve modelin gerekli yetenekleri desteklediğini doğrular.

{
  "model_runtime": {
    "capability_policy": "strict",
    "capability_probe_timeout_ms": 5000
  }
}

export LUMA_CAPABILITY_POLICY=strict
export LUMA_CAPABILITY_PROBE_TIMEOUT_MS=3000

Environment değişkenleri config'i ezer. Probe timeout'u varsayılan 5000 ms'dir ve Ctrl-C ile iptal edilebilir.

Warning: 'text-model-l' has no json_schema capability information.

Streaming, reasoning, multimodal

model VisionReasoner {
  provider: "openai-compatible"
  base_url: "https://gateway.example/v1"
  model: "vision-model"
  api_key: getEnv("api_key")
  stream: true
  reasoning: true
  multimodal: true
}

Multimodal ayrıntıları ve dosya akışı için → IO & Multimodal.

Model response cache

model Cached {
  provider: "openai-compatible"
  base_url: "https://gateway.example/v1"
  model: "text-model-l"
  api_key: getEnv("api_key")
  cache: true
  cache_ttl: 60000
  cache_max_entries: 256
}

Run policy: çok modelli stratejiler

run_policy, bir ask çağrısının birden fazla model üzerinde nasıl yürütüleceğini belirler. Agent'a bağlanır ve o agent'ın tüm LLM çağrılarını kapsar.

run_policy Resilient {
  strategy: "fallback"
  models: [Primary, Backup]
  on: ["timeout", "rate_limit", "provider_error", "empty_content"]
  max_attempts: 2
}

agent Analist {
  model: Primary
  run_policy: Resilient
}

Stratejiler

Yapılandırma anahtarları

Bir anahtarı yanlış strategy ile kullanmak parse hatası verir — örneğin tie yalnızca vote için geçerlidir.

on: hangi hatalarda devreye girer

Geçerli trigger değerleri:

retryable        timeout          rate_limit       provider_error
empty_content    invalid_response refusal          invalid_tool_call
cancelled        unsupported      budget_exceeded

ayrıca ham error code'ları da yazılabilir:
MODEL_TIMEOUT · MODEL_RATE_LIMIT · MODEL_PROVIDER_ERROR · …

"retryable" özel bir değerdir: hatanın retryable bayrağına bakar, koduna değil. Tanınmayan bir trigger parse hatası verir.

Strateji detayları

fallback

run_policy Resilient {
  strategy: "fallback"
  models: [Primary, Backup, Reserve]
  on: ["timeout", "rate_limit", "provider_error"]
  max_attempts: 2
}

Modeller sırayla denenir. Hata on listesine uymuyorsa hemen fırlatılır — yani bir doğrulama hatası yüzünden gereksiz yere ikinci modele geçilmez. max_attempts kaç modelin deneneceğini sınırlar.

escalate

run_policy Adaptive {
  strategy: "escalate"
  models: [Cheap, Strong]
  on: ["invalid_response", "empty_content"]
  max_cost_per_call: 0.02
}

agent Extractor {
  model: Cheap
  run_policy: Adaptive
  retry: 1
  cost_budget: 0.5
}

Modeller ucuzdan güçlüye uzanan bir merdivendir ve aynı anda tek basamak çalışır. Bir modele ancak kendinden önceki model on listesindeki bir tetikleyiciyle başarısız olduğunda geçilir; listede olmayan bir hata çağırana olduğu gibi iletilir. Ucuz model yanıt verdiğinde güçlü model hiç çağrılmaz — escalate'i combo'dan ayıran nokta budur; combo önceki aşama başarılı olsa bile her aşamayı çalıştırır. En az iki model zorunludur: Escalate run policy 'Adaptive' must specify at least two models, from the cheapest to the strongest.

• retry iç döngü, escalation dış döngüdür. Bir aşama retry hakkını çalışmakta olan modelin üzerinde harcar — ucuz model önce kendini düzeltir — güçlü modelin parası ancak ondan sonra ödenir. Yukarıdaki policy, Strong'a hiç ulaşmadan önce Cheap'e iki istek atar. Diğer tüm çok modelli stratejiler adaylarını retry: 0 ile çalıştırmayı sürdürür.
• max_cost_per_call, tek bir policy çağrısının tavanıdır. Her aşamadan sonra, merdivenin tamamının paylaştığı tek bir defter üzerinden kontrol edilir ve tavan dahildir: bir çağrı tam tavan kadar harcayabilir, ama o noktada tırmanacak parası kalmamıştır.
• Tavana ulaşmak tırmanışı durdurur ve satın alınmayan model adıyla bildirilir: MODEL_BUDGET_EXCEEDED · RunPolicy 'Adaptive' spent 0.03 of its max_cost_per_call of 0.02, so it did not escalate to model 'Strong'.
• Tavanın aşılması hâlinde sonuç geçerli olsa da döndürülmez; aşım yutulmaz, raporlanır: MODEL_BUDGET_EXCEEDED · RunPolicy 'Adaptive' spent 0.03 on this call, above its max_cost_per_call of 0.02.
• Her aşama, onu yürüten model profilinin cost_per_1k_tokens değeriyle fiyatlanır; profilde fiyat yoksa agent'ın oranına düşülür. escalate altında bu defter her basamakta sıfırlanmak yerine merdivenin tamamını kapsar, dolayısıyla agent'ın cost_budget / token_budget ayarları da tırmanışı bitirebilir: Agent cost budget exceeded (0.5). Hiçbir yerde fiyat verilmemişse maliyet 0 hesaplanır ve hiçbir tavan tetiklenmez.

parallel

run_policy Fanout {
  strategy: "parallel"
  models: [Primary, Backup]
  select: "all"
}

agent Analist {
  run_policy: Fanout

  fn uret() -> Aday[] {
    ask "Aday sonuçlar üret" -> Aday[]
  }
}

race

run_policy Fastest {
  strategy: "race"
  models: [Primary, Backup]
}

İlk başarılı sonuç kazanır; kalan istekler AbortSignal ile iptal edilir. Tümü başarısız olursa ilk hata fırlatılır.

vote

run_policy Consensus {
  strategy: "vote"
  models: [Primary, Backup, Reviewer, Judge]
  quorum: 2
  tie: "highest_confidence"
}

• Yalnızca schema-valid sonuçlar oylanır; kanonik JSON (anahtarları sıralanmış) üzerinden karşılaştırılır.
• Quorum sağlanamazsa MODEL_VOTE_NO_QUORUM (retryable: true).
• Beraberlik: fail → MODEL_VOTE_TIE; first → ilkini alır; highest_confidence → sonuçlardaki sayısal confidence alanına bakar.
• highest_confidence seçilip sonuçlarda confidence yoksa: MODEL_VOTE_CONFIDENCE_UNAVAILABLE.

fusion

run_policy SafeFusion {
  strategy: "fusion"
  models: [Primary, Backup, Reviewer]
  synthesizer: Primary
  max_fusion_inputs: 3
  fusion_input_tokens: 4000
  synthesizer_policy: "deny_tools"
}

Adaylar eşzamanlı çalışır; başarılı olanlar synthesizer modele "candidate outputs" olarak verilir ve nihai schema-valid sonuç üretilir.

• Hiç başarılı aday yoksa: MODEL_FUSION_NO_INPUTS.
• Tahmini girdi token'ı fusion_input_tokens'ı aşarsa: MODEL_BUDGET_EXCEEDED.
• synthesizer_policy: "deny_tools" varsayılan synthesizer'a tool vermez ve write tool'larını reddeder; "inherit" agent'ın tool'larını devreder.
• Synthesizer prompt'u adayları veri olarak değerlendirmesini, içlerindeki talimatları uygulamamasını açıkça söyler.

combo

run_policy Pipeline {
  strategy: "combo"
  models: [Draft, Reviewer, Finalizer]
  max_stages: 3
}

Modeller sırayla çalışır. Her aşamanın schema-valid çıktısı bir sonraki aşamanın prompt'una "önceki aşamanın çıktısı, iyileştir" olarak eklenir. Son aşamanın sonucu döndürülür.

Hangi strategy ne zaman?