Dil Referansı

Program yapısı

Bir .luma dosyası üst düzey deklarasyonlardan ve operation'lardan oluşur. Deklarasyonların sırası önemsizdir; operation'lar ise kaynakta göründükleri sırayla çalışır.

Operation'lar (üst düzey, sırayla çalışır)

x = ask "..." -> Schema [retry 2]      // direct LLM call
y = tool calculate({ a: 1, b: 2 })     // direct tool call
inst = AgentName(constructorArg)       // agent instance
z = inst.method(arg1, arg2)            // agent method call
p = parallel [options] { ... }         // fan-out / fan-in block
rows = query Orders(since)             // datasource read       (v0.4.0)
n = command MarkExported(since, tag)   // datasource write      (v0.4.0)
out = parallel over rows as row limit 4 -> Out[] {   // per-element fan-out (v0.4.0)
  return { id: row.id }
}

Program en az bir operation içermelidir ve yukarıdaki biçimlerin hepsi sayılır — tek başına bir query yeter. Hiçbiri yoksa alınan mesaj hâlâ yalnızca ilk üçünü adlandırır (ask, agent call or parallel not found.); bu, veri biçimleri hakkında bir kural değil, onlardan eski kalmış bir ifadedir. Çıktı olarak son operation'ın sonucu yazdırılır; --all ise her operation'ın sonucunu, atandığı değişken adıyla birlikte basar. Düz atamalar (x = 42) operation değildir ve iki çıktıda da görünmez.

parallel ile parallel over, aynı kelimeyi paylaşan iki ayrı operation'dır. parallel { … } yazdığın dallar üzerinde fan-out yapar — sabit, adlandırılmış adımlar kümesi — ve agent method'unun içinde de yazılabilir. parallel over rows as row limit 4 -> Out[] { … } ise veri üzerinde fan-out yapar: eleman başına bir gövde, opsiyonel olmayan bir limit ve yalnızca üst düzey. Kendi kuralları — giriş sırası, on_error, memory scope tuzağı — Veri & Entegrasyon sayfasındadır.

Error: 'filter' can only be used in an agent method or fn body (line 2).

Error: Unrecognized top-level line (line 1): n = 42

Gramer satır tabanlıdır

schema Result {
  count: int
  total: float
}

pure fn f() -> Result {
  a = 1
  b = 2
  return { count: a, total: b }
}

schema Result {
  count: int, total: float
}
// A schema line may define only one field: count: int, total: float

pure fn f() -> Result {
  a = 1  b = 2
  return {
    count: a
  }
}

Bir satır; @ ile ya da ikili operatör, virgül veya nokta ile — yani şunlardan biriyle — başlıyorsa önceki satırın devamı sayılır: || · && · === · !== · <= · >= · == · != · + · - · * · / · < · > · , · .. => bu kümede değildir. @ biçimi sayesinde uzun annotation zincirleri bölünebilir:

schema Answer {
  summary: string
    @desc("Yalnızca verilen belgeye dayalı özet")
    @length(20, 400)
  confidence: float [0..1]
}

// ✓ valid — the continuation line starts with ||
where a == null || b == null
   || num.approximatelyEqual(a * b, t, 0.01)
  @feedback("a * b toplamına uymuyor")

// ✗ invalid — 'require' is a keyword, not a continuation token
when kind == "kurumsal"
  require [tax_id]

luma program.luma --fmt           # kanonik biçimi bas
luma program.luma --fmt --write   # dosyayı yerinde yeniden yaz

// Grading schema
schema Answer   {
      title:string
   @desc("Kısa bir başlık")
  score  : float
 where score > 0
      && score < 100
}


agent Grader   {
      // one method
    fn grade() -> Answer {
result: Answer = { title: "ok", score: 10 }
      return result
  }
}
grader = Grader()
result = grader.grade()

// Grading schema
schema Answer {
  title: string
    @desc("Kısa bir başlık")
  score: float
  where score > 0
    && score < 100
}

agent Grader {
  // one method
  fn grade() -> Answer {
    result: Answer = { title: "ok", score: 10 }
    return result
  }
}
grader = Grader()
result = grader.grade()

input — dışarıdan gelen değerler

input topic: string
input document: file

Yol, .luma dosyasının bulunduğu klasöre göre çözülür. Bildirilen bir input verilmezse program Input missing: --document ile durur.

context — dosyayı kaynak olarak bağlama

context contract = file("docs/contract.md")
context spec     = file("docs/spec.md")

result = ask "Yalnızca bu belgelere dayan:\n\n{contract}\n\n{spec}" -> Answer

context, dosya içeriğini programa bağlar ve adını bir kaynak kimliği yapar. Schema'nda sources: string[] alanı varsa modelin oraya yazdığı her değer tanımlı context adlarından biri olmak zorundadır — bu, kaynak uydurmayı engellemenin doğrudan yoludur. Erişimi agent bazında daraltmak için contexts: allowlist'i kullanılır.

Yorumlar

// Line comment — a // inside a string literal is not affected
url = "https://example.com/v1"   // this is a comment, the one above is not

Yalnızca // satır yorumu vardır; blok yorumu (/* */) yoktur.

Değişkenler ve atama

number   = 42
text     = "Luma"
flag     = true
empty    = null
list     = [1, 2, 3]
object   = { name: "Ayşe", active: true }
field    = object.name

Tipli yerel değişkenler

Bir atamaya tip eklersen değer atandığı anda doğrulanır ve bu tip değişkene yapışır — sonraki atamalar da aynı tipe göre kontrol edilir.

request: CalcInput = { a: 4, b: 6, operation: "add" }
result: CalcResult = tool calculate(request)
items: LineItem[] = [{ amount: 10 }, { amount: 5 }]

String interpolasyonu

Prompt ve role metinleri içinde {variable} ve istediğin derinlikte noktalı yol yazılabilir — {variable.field}, {cift.sol.ad}:

ask "Şu konuyu özetle: {topic}\n\nBelge:\n{document}" -> Summary
ask "Önceki bulgu: {analysis.finding} (güven {analysis.confidence})" -> Report

• Değer string ise doğrudan yazılır; değilse JSON.stringify(value, null, 2) ile 2 boşluk girintili JSON'a çevrilir.
• Tanımsız değişken referansı 'x' variable is not defined yet., kuyruğu var olmayan bir yol ise Field 'x.y' was not found. hatası verir.
• Süslü parantez arasındaki metin geçerli bir referans değilse — { }, {1x}, {a.} — prompt'ta yazıldığı gibi kalır, hata verilmez. Bu bilinçli: modele JSON örneği gösteren bir prompt süslü parantez doludur ve onları bozuk yer tutucu saymak o prompt'ları yazılamaz kılardı.
• Agent'ta contexts: [...] listesi varsa, listede olmayan bir context adını interpole etmek Agent context access was denied: x hatası verir.

İnterpolasyon yalnızca prompt/role string'lerinde çalışır — normal bir atamadaki string literal'da {x} düz metindir. Orada birleştirme için + kullan.

Expression dili

Operatörler ve öncelik

Çağrı sonucunu doğrudan okumak

Çağrı bir ifadedir, dolayısıyla döndürdüğü şey yerinde okunabilir — ara değişken gerekmez:

flag  = mk(1).flag              // alan
deep  = mk(1).inner.deep       // zincir
first = mk(1).arr[0]           // alan, sonra indeks
pick  = mk(1).arr[idx(0)]      // indeksin kendisi de çağrı olabilir
name  = schema.describe(Doc).name   // standard library çağrısı da

Bu, where, when ve @valid içinde de geçerlidir — @valid(v => chk(v).ok) gibi çıplak boolean biçimi dahil. v0.11.0'a kadar çağrı sonucunda yalnız indeksleme çalışıyordu; alan erişimi çağrıyı tanımsız değişken olarak bildiriyor, standard library biçimi ise suçu modülün kendisine atıyordu.

Error: Dependency call 'd.m' must be its own step — write 'result = d.m(...)' first, then use 'result'; a dependency method may reach a model, so it cannot run inside an expression.

Orada olmayan bir alan sessizce null olmak yerine hata olarak kalır — mk(1).yok için Field 'mk(1).yok' was not found., değişkenin izlediği kuralın aynısı. Bir nesneyi sayıyla indekslemek kendi tip hatasını korur: mk(1) key must be a string, got int.

b = a > 3
positive = filter item in items => item.amount > 0
actives  = map item in items => item.active && item.amount > 0

true || false && false     // true  — şöyle okunur:  true || (false && false)
                           // eşit olsalardı: (true || false) && false = false

Error: '??' cannot be mixed with '&&' or '||' without parentheses: n ?? b || b

?? — null için varsayılan

a ?? b, a null değilse a'ya, null ise b'ye değerlenir. Sağ taraf yalnızca gerektiğinde değerlendirilir; tıpkı && ve || gibi.

amount = raw_amount ?? 0.0           // nullable alan, varsayılanla
label  = (title ?? subtitle) ?? "-"  // soldan sağa zincirlenir
total  = reduce item in items with 0 => acc + (item.amount ?? 0)

Var olma sebebi şu: || bu işi yapamaz. Luma'da || katı boolean'dır, dolayısıyla null bir değer üzerinde value || 5 varsayılan vermek yerine Boolean if condition expected: value ile düşer. Nullable alanlar ise extraction'ın olağan hâli — T | null, bir şemanın modele "bulamadım" dedirtme biçimidir — yani varsayılan vermek bir operatörü hak ediyor.

Error: Field 'm.missing' was not found.

İfade yazılabilen her yerde geçerlidir: atama, pure fn gövdesi, agent method'u, nesne ya da liste literal'inin içi, where, when, @valid, map/filter/reduce, if/while. Bu bölümün dayandığı "tek evaluator" sözünün aynısı.

Karmaşık bir predicate'i okunaklı tutmak için hâlâ pure fn kullanabilirsin:

positive = filter item in items => item.amount > 0

large = filter item in items => item.amount > 100
  && item.active

pure fn isEligible(item: LineItem) -> bool {
  if item.amount == null {
    return false
  }
  return item.amount > 100 && item.active
}

eligible = filter item in items => isEligible(item)

Literal'ler

String birleştirme

root   = "@" + folder             // "@0213"
label  = "adet: " + length(list)   // the number is appended as a string automatically
path   = root + "/ext.json"

+ operatörü JavaScript semantiği taşır: taraflardan biri string ise sonuç string olur.

Import gerektirmeyen fonksiyonlar

Aşağıdaki 11 fonksiyon dilin içindedir ve import olmadan her yerde (agent method'u, pure fn, where, @valid) çağrılabilir. Bunların dışındaki her şey standard library üzerinden gelir.

n = length("Luma")      // 4
m = length([1, 2, 3])   // 3

contains("Ayşe Yılmaz", "Ayşe")    // true
contains(["vip", "active"], "vip")  // true

trim("  Ayşe  Yılmaz  ")   // "Ayşe  Yılmaz"

replace("a-b-c", "-", "/")   // "a/b/c"

flatten([["a"], ["b", ["c"]]])   // ["a", "b", "c"]

Kontrol akışı

if / else

if stats.words > 3 {
  bonus = tool calculate({ a: stats.words, b: 2, operation: "multiply" })
} else if stats.words > 0 {
  bonus = tool calculate({ a: stats.words, b: 1, operation: "add" })
} else {
  bonus = tool calculate({ a: 0, b: 0, operation: "add" })
}

Koşul boolean üretmelidir; sayısal karşılaştırmalarda iki taraf da sayı olmalıdır, aksi halde Numeric if comparison expected. hatası alınır.

switch

switch counter {
  case 1 {
    result = tool calculate({ a: 1, b: 0, operation: "add" })
    return result
  }
  case > 1 {
    result = tool calculate({ a: 0, b: 0, operation: "add" })
    return result
  }
  case _ {
    return { result: 0 }
  }
}

Bir switch en az bir case veya default içermelidir. Case'ler sırayla denenir, ilk eşleşen çalışır ve düşme (fall-through) yoktur.

match

match, tagged union değerinin çalışma zamanındaki etiketine göre dallanır. Her case union'ın bir üyesini adlandırır ve değeri yeni bir isme bağlar; o dalın içinde bu isim üyenin kendi somut tipini taşır, dolayısıyla alanlarına doğrudan erişilir ve alanlar nullable değildir.

schema Invoice {
  invoice_number: string
}

schema Receipt {
  reference: string
}

schema Document = Invoice | Receipt tagged by kind

agent Router {
  fn route(document: Document) -> Result {
    match document {
      case Invoice invoice {
        return { value: invoice.invoice_number }
      }
      case Receipt receipt {
        return { value: receipt.reference }
      }
    }
  }
}

Eksik üye, default kullanımı ve union dışından bir schema adlandıran case — üçü de parse zamanında reddedilir:

Error: Match for tagged union 'Document' must handle member 'Receipt'.
Error: Match does not allow a default branch.
Error: Match case 'Result' is not a member of tagged union 'Document'.

Parser'ın görebildiği ve göremediği

"Parser'ın görebildiği bir tip" kuralın tamamıdır ve bunu somutlaştırmaya değer. Alan yolu her adımı bildirilmiş bir alanı adlandırdığı sürece istediğiniz derinlikte çözülür; match extraction.data ve match envelope.inner.data araya yerel değişken koymadan çalışır. for döngüsü bağı da çözülür — koleksiyonun eleman tipi bağa taşınır — ve doküman listesini yönlendirmeyi sıradan bir döngü hâline getiren şey budur:

for document in batch.documents {
  match document {
    case Invoice invoice { … }
    case Receipt receipt { … }
  }
}

Parser'ın reddettiği şey, hiçbir şekilde bir union'a çözemediği ifadedir — union olmayan bir alan ya da any tipli bir değer. O zaman Match expression 'x' requires a tagged union type. alırsınız ve çözüm döngüyü yeniden kurmak değil, değere parser'ın okuyabileceği bir tip vermektir.

Union listesini katlamanın iki yolu

Bir match dalı sıradan bir bloktur: atama yapabilir ve atama daldan sağ çıkar, dolayısıyla liste boyunca biriktirme başka her yerde nasıl yazılıyorsa öyle yazılır. Yalnızca bağlanan member değişkeni (invoice, receipt) dala özeldir ve sonrasında yoktur.

agent Desk {
  fn tally(documents: Document[]) -> Tally {
    invoices = 0
    receipts = 0
    for document in documents {
      match document {
        case Invoice invoice { invoices = invoices + 1 }
        case Receipt receipt { receipts = receipts + 1 }
      }
    }
    return { invoices: invoices, receipts: receipts }
  }
}

Diğer yol pure fn'dir; o, union'ı doğrudan açmaya yetkilidir: içinde tag ve member alanları sıradan alan okumasıdır, match de yoktur bütünlük kontrolü de.

pure fn label(document: Document) -> string {
  if document.kind == "Invoice" {
    return document.invoice_number
  }
  return document.reference
}

agent Desk {
  fn labels(documents: Document[]) -> Labels {
    found = map document in documents => label(document)
    return { values: found }
  }
}

Aynı document.kind bir agent method'unda yazılırsa reddedilir — Desk.labels: schema field 'document.kind' was not found. — çünkü union schema'sının kendine ait alanı yoktur. Yani seçim neyin denetlenmesini istediğinizle ilgili: agent method'undaki match bütünlük açısından denetlenir, union'a bir member eklediğinizde onu ele alana kadar her match düşer. pure fn denetlenmez; map ve reduce içine girebilmesini sağlayan da budur, yeni bir member'ın sessizce son dala düşecek olmasının sebebi de. Member kümesi önemliyse döngüye, pipeline'ın şekli önemliyse pure fn'e uzanın.

for / while / break / continue

for page in pages {
  files  = io.readFiles([page])
  part   = ask "Bu sayfayı Markdown'a çevir: {files}" -> Page
  markdown = markdown + part.text + "\n\n"
}

i = 0
while i < 3 {
  i = i + 1
  if i == 2 {
    continue
  }
  if i > 2 {
    break
  }
}

try / catch

try {
  data   = ask "1-3 arası sayısal item üret." -> Data
  clean  = map item in data.items => item.value
  total  = reduce item in clean with 0 => acc + item
  result = tool calculate({ a: total, b: 0, operation: "add" })
  return result
} catch error {
  fallback = tool calculate({ a: 0, b: 0, operation: "add" })
  return fallback
}

catch zorunludur (try tek başına kullanılamaz). Yakalanan değişken yapılandırılmış bir hata nesnesidir:

{ "code": "TOOL_INPUT_INVALID", "message": "calculate.input.a must be a number.", "retryable": false }

Tool ve model hataları code / message / retryable (ve varsa details) taşır; diğer hatalar yalnızca message içerir. Bu alanlara std/agent veya std/json ile erişilir:

import agent from "std/agent"

} catch error {
  code = agent.errorCode(error)
  if agent.isRetryable(error) {
    ...
  }
}

İndeksleme (v0.4.0)

Listeler ve map'ler [] ile indekslenir — okuma ve yazma, zincirler dahil:

first = rows[0]
name = rows[i].customer.name
value = m["key"]
buckets[key] = col.append(existing, row)   // yazma: mutasyon, x = v ile aynı scope kuralları
xs[0].field = 3                            // ✗ Error: Unrecognized step in A.run (line 5): xs[0].field = 3

Her sınır durumu adlandırılmış hatadır — indeksleme asla sessiz null dönmez:

Koleksiyon işlemleri

map, filter ve reduce dilin yerleşik statement'larıdır — fonksiyon değil, kendi söz dizimleri vardır ve her biri tek bir statement'tır — diğer statement'lar gibi operatörden bölünerek satırlara yayılabilir.

actives = filter item in items => item.active
names   = map item in actives => upper(item.name)
total   = reduce line in lines with 0 => acc + line.amount

Kaynak array değilse the map/filter/reduce source must be an array hatası alınır.

pure fn isLarge(line: LineItem) -> bool {
  if line.amount > 100 {
    return true
  }
  return false
}

large = filter line in lines => isLarge(line)

Zincirleme

active  = filter item in items => item.active
names   = map item in active => upper(item.name)
count   = length(names)

Her adım kendi satırında ayrı bir değişkene atanır; zincir sözdizimi (.filter().map()) yoktur.

Bu üçü koleksiyon statement yüzeyinin tamamıdır; burası dilin bittiği yerdir, koleksiyonların bittiği yer değil. Sıralama, gruplama, chunk'lama, dilimleme, tekilleştirme ve toplama fonksiyondur — std/collections içinde 25 tane, konvansiyon gereği col olarak import edilir; indeksleme bölümündeki col.append'in ardındaki col da odur. Yani "bunu nasıl sıralarım, nasıl gruplarım" sorusunun cevabı eksik bir statement değil; bir sonraki satırda adlandırılmış bir yerel değişken ve bir col.* çağrısıdır.

pure fn ve io fn

Üst düzey fonksiyonlar deterministik yardımcılardır. Schema where kurallarında, @valid içinde ve agent method'larında çağrılabilirler.

pure fn totalAmount(items: LineItem[]) -> float {
  total = reduce item in items with 0 => acc + item.amount
  return total
}

schema Invoice {
  items: LineItem[1..100]
  total_amount: float

  where totalAmount(items) == total_amount
}

Parametreler ve doğrulama

• Parametreler tipli olmak zorundadır ve çağrı anında doğrulanır.
• Opsiyonel parametre: x?: string. Verilmezse değeri null olur.
• Dönüş değeri de bildirilen tipe göre doğrulanır.
• Parametrelere field annotation'ları eklenebilir ve bunlar çağrı anında gerçekten uygulanır: pure fn f(code: string @match("^[A-Z]+$"), score: float @range(0, 10)) -> bool { … }. Aynı kural io fn, agent method ve tool parametreleri için de geçerlidir. Bir annotation burada bilinçli olarak yok sayılır: @severity bir kuralı yalnızca değerin sonuç olarak denetlendiği yerde yumuşatır. Parametre bir girdidir, dolayısıyla kural sert kalır — şerhli değer geçemez.

export ve gizlilik

// helpers.luma
export pure fn normalize(x: string) -> string {
  return lower(trim(x))
}

pure fn internal(x: string) -> string {   // no export → cannot be called from outside the module
  return upper(x)
}

Import ve modüller

import "std/math"              // unnamed: abs(...), sum(...) directly
import math from "std/math"    // namespaced: math.abs(...)
import "./helpers.luma"        // relative module inside the project

import mat from "std/math"
schema S { d: float }
agent A {
  fn f() -> S {
    d = mat.abs(0 - 7)     // ✓ works — 'mat' is an imported namespace
    return { d: d }
  }
}

r = reviewer.review(doc)      // böyle
return { amount: r.amount }

return reviewer.review(doc)   // böyle değil
return { amount: reviewer.review(doc).amount }   // bu da değil

Error: Dependency call 'a.f' must be its own step — write 'result = a.f(...)' first, then use 'result'; a dependency method may reach a model, so it cannot run inside an expression.

kural.luma  (export pure fn kontrol)  ──>  paket.luma  ──>  programın
                                            ✓ şemalar buraya ulaşır
                                            ✓ kontrol() de

Error: Unknown function 'yardimci': yardimci(1)

belge.luma  ─┬─>  fatura.luma   ─┐
             └─>  pos_fisi.luma ─┴─>  ortak.luma  (Taraf)

Zorunluluk değil, konvansiyon: standard library sayfası std modüllerini kanonik alias'larıyla import eder (import math from "std/math", import str from "std/string", import col from "std/collections", import num from "std/numeric"). Standard library sayfasındaki tüm örnekler bu alias'ları kullanır.

Statik analiz

Program çalışmaya başlamadan önce parser aşağıdaki kontrolleri yapar. Bunların çoğu hata, bir tanesi uyarıdır.

Bunlara ek olarak model, run_policy, tool, agent ve schema referansları çözümlenir: tanımsız bir model, tool veya agent adı programın hiç başlamamasına yol açar.