LLM çağrısı bir kütüphane değil,
dil yapısıdır

Diller yamanıyor

Bir modele soru sorup yapılandırılmış cevap almak bugün her dilde aynı şekilde yapılıyor: metin gönder, metin al, geri kalanına kendin çare bul. Bu çarelerin toplamı artık her LLM projesinde tekrar eden bir yama katmanı oluşturuyor.

Pragmatik yaklaşım

Luma yeni bir genel amaçlı dil değildir, olmaya da çalışmaz. Yalnızca yamanın biriktiği katmanı devralır — modelle konuşulan sınırı ve v0.4.0'dan beri onun iki yanındaki sınırları: içeri giren veritabanı satırlarını ve dışarı çıkan sonuçları. Tool'ların ve veritabanı sürücünün gerçek kodu senin JS/TS dosyanda kalır, uygulamanın geri kalanı kendi dilinde kalır. Pragmatik olan kısım budur: her şeyi değiştirmez, tam olarak bozuk olan yeri değiştirir.

Somut olarak bu, bir pipeline'ın tek adımıdır. Yukarıdan bir şey onu zamanlar; Luma tipli satırları çeker, yeniden şekillendirir, zor kısmı sınırlı bir fan-out altında modele gönderir ve sonucu geri yazar. Scheduling, DAG bağımlılıkları ve backfill senin orchestrator'ında kalır — bu çizginin nerede ve neden çekildiği için Veri & Entegrasyon'a bak.

1 · Tek tanım, üç iş

Bir schema yazarsın. Runtime onu birbirinden ayrı üç yerde kullanır:

Bunları elle kurmak üç ayrı kod parçası ve üç ayrı hata kaynağı demektir. Burada aynı tanımın üç görünümüdür; senkronizasyonu kaybolamaz.

2 · Belirsizlik sınırını parser tutar

io fn kaydet(yol: string, icerik: string) -> string {
  return io.writeText(yol, icerik)
}

agent Analist {
  fn incele(metin: string) -> Analiz {
    ask "Analiz et: {metin}" -> Analiz
  }
}

pure fn toplam(kalemler: Kalem[]) -> float {
  s = ask "Topla: {kalemler}" -> Sonuc
  return s.deger
}
// 'ask' cannot be used inside a pure fn.

schema Fatura {
  toplam: float
  where io.exists("@x.json")
}
// where is deterministic and cannot use IO.

Bir fonksiyonun modele ulaşıp ulaşmadığı, IO yapıp yapmadığı gövdesine bakınca görünür — ve bu ayrım konvansiyon değil, parse zamanı kuralıdır. Schema doğrulaması bu sayede her zaman deterministiktir: aynı veri her zaman aynı sonucu verir.

3 · Yan etki tipin parçasıdır

tool db_write(request_id: string, value: string) -> DbResult {
  side_effects: "write"
  scope: "db:write"
  credential: "DB_PASSWORD"
  idempotent: true
  idempotency_key: request_id
}

agent Yazici {
  tools: [db_write]
  tool_scopes: ["db:write"]
  tool_policy: "approval"
}

"Model yanlışlıkla veritabanına yazdı" burada code review'un yakalaması gereken bir şey değil, runtime'ın reddettiği bir şeydir. İzin, kimlik bilgisi, yan etki sınıfı ve tekrar güvenliği contract'ın kendisinde durur.

4 · Gözlemlenebilirlik sonradan eklenmez

Tek bir --trace-file bayrağı, hiçbir enstrümantasyon kodu yazmadan şunu verir: her provider isteği (model, süre, token, maliyet, correlation ID'leri), her tool çalıştırması (cache isabeti, timeout, idempotency) ve her doğrulama kuralı — başarılı olanlar dahil.

jq -r '.events[] | select(.type=="validation" and .ok==false)
        | "\(.name) [\(.metadata.rule)] \(.error)"' trace.json

Bir çıkarımın neden başarısız olduğunu tahmin etmek yerine okursun. → Telemetry & Trace

5 · Tip sistemi tek bir şekilde durmaz

Bir schema type parameter alabilir ve bir union deneme yanılmayla değil tag ile çözülebilir. İkisi de aynı sebeple var: model sınırında, iki kez yazmak zorunda kaldığınız bir şekil kendisiyle çelişebilen bir şekildir ve tahminle seçilen bir dal, doğru diye raporlanan yanlış bir cevaptır.

schema Invoice {
  invoice_number: string
  total: float
}

schema Receipt {
  reference: string
  total: float
}

schema Document = Invoice | Receipt tagged by kind

schema Page<T> {
  items: T[]
  count: int
}

agent Desk {
  fn list() -> Page<Document> {
    ask "List the documents in this batch." -> Page<Document>
  }
}

Page<T> bir kez yazılır ve dosya parse edilirken açılır: Page<Document>, Page_Document adlı sıradan bir schema'ya dönüşür ve provider'a hiçbir genericlik ulaşmaz — istek düz bir object schema'sı taşır. Pair<A, B>, Box<int> ve Page<Envelope<LineItem>> aynı şekilde çalışır; her instantiation, argümanlarından kurulan bir adla bir kez açılır.

Ergonomiyi değil cevabı değiştiren kısım tagged by kind. Yukarıdaki Invoice ile Receipt'in ikisi de total taşıyor, dolayısıyla yalnızca bir toplam içeren bir değer her ikisine de uyar. Tag'siz bir Invoice | Receipt member'ları sırayla dener, ilk uyan kazanır ve koşu başarı raporlar — değer, member'ları hangi sırayla yazdığınız yüzünden fatura oldu. Tag altında kind alanı tam olarak bir member'ı adlandırır ve hiçbir şey denenmez. → Tip sistemi

Eksiksiz bir Luma programı

Aşağıdaki dosya çalıştırılabilir bir programın tamamıdır — import edilecek framework, kurulacak class, yazılacak glue kod yoktur.

input metin: string

schema Analiz @desc("Bir metin parçasının yapılandırılmış analizi") {
  ozet: string @length(20, 400)
  duygu: enum["olumlu", "notr", "olumsuz"]
  etiketler: string[] @minItems(1) @maxItems(5) @unique
  guven: float [0..1]
}

model Primary {
  provider: "openai-compatible"
  base_url: "https://gateway.example/v1"
  model: "text-model-l"
  api_key: getEnv("api_key")
  capabilities: ["json_schema"]
}

agent Analist {
  model: Primary
  role: "Kısa, tarafsız ve yalnızca verilen metne dayalı analiz üret."
  temperature: 0
  retry: 2

  fn incele(metin: string) -> Analiz {
    ask "Aşağıdaki metni analiz et:\n\n{metin}" -> Analiz
  }
}

analist = Analist()
sonuc = analist.incele(metin)

{
  "ozet": "Kargo teslimatı iki gün gecikmiş, ancak destek ekibi sorunu hızla çözmüş.",
  "duygu": "notr",
  "etiketler": ["kargo", "gecikme", "destek"],
  "guven": 0.82
}

Bu tek dosyada çalışan şeyler:

• Analiz schema'sı JSON Schema'ya çevrilip strict: true ile gateway'e gönderildi.
• Yanıt yerel olarak doğrulandı: ozet uzunluğu, duygu enum üyeliği, etiketler için minItems/maxItems/unique, guven için [0..1] aralığı — ve schema'da olmayan bir alan gelseydi o da hata olurdu.
• Doğrulama başarısız olsaydı hata metni prompt'a eklenip en fazla 2 kez daha denenecekti (retry: 2).
• API key koda değil environment'a yazıldı; getEnv dışında hiçbir yerden erişilemez ve trace/prompt/cache içine sızmaz.
• Model çağrısı, süresi, token kullanımı ve her doğrulama kuralı telemetry event'i olarak kaydedildi.

Sonuç: sonuc.guven yazdığında bu değerin gerçekten 0 ile 1 arasında bir float olduğunu bilirsin — çünkü öyle olmasaydı program o satıra hiç gelmezdi.

Çalışma modeli

Bir .luma dosyası çalıştırıldığında izlenen yol:

  .luma kaynak
       │
       ├─ comment strip → import çözümleme → blok çıkarımı
       ├─ schema / model / run_policy / tool / agent / pure fn parse
       ├─ static analysis  (ulaşılmaz kod, bilinmeyen schema alanı,
       │                    dependency cycle, sonsuz loop, kullanılmayan değişken)
       ↓
  program modeli
       │
       ├─ model credential çözümleme (getEnv)
       ├─ tool registry + tool module yükleme
       ├─ capability probe (GET /models → json_schema, tool_calling…)
       ↓
  operation yürütme  (kaynaktaki sırayla)
       │
       ├── deterministik adımlar   assign · map/filter/reduce · if/switch/for/while
       ├── direct tool             tool hesapla({...})   → policy → validate → çalıştır
       ├── ask                     schema → JSON Schema → provider adapter
       │        └── native tool loop   tool_calls → çalıştır → sonucu geri gönder → 2. tur
       ├── run policy              fallback · parallel · race · vote · fusion · combo · escalate
       ├── parallel blokları       fan-out → fan-in (nested/flat) → merge
       ├── query / command         köprü → satır tavanı → satır başına schema doğrulama
       ├── parallel over           eleman başına bir gövde → girdi sıralı sonuç deposu
       ├── http / state            alt süreçte istek · atomik key/value yazma
       └── her adımda telemetry event'i
       ↓
  stdout JSON  +  trace.json / trace.jsonl / otel.json

Yetenek haritası

Tasarım ilkeleri

Yazım kuralları

schema InvoiceLine {
  unit_price: float
  quantity: int
}

agent Extractor {
  fn extract(md: string) -> InvoiceLine {
    ask "..." -> InvoiceLine
  }
}

Schema invoiceLine {     // keyword büyük harf değil
  Unit_Price: Float       // tip adı lowercase olmalı
}

Agent extractor {         // declaration adı büyük harfle başlar
  Fn Extract() -> ... {}
}

Keyword'ler daima küçük harf (schema, agent, tool, fn, ask); declaration isimleri büyük harfle başlar (Invoice, Analist); yerleşik tipler küçük harftir (string, int, float, bool).

Nereden devam etmeli