Language Reference

Program structure

A .luma file consists of top-level declarations and operations. The order of the declarations does not matter; operations run in the order they appear in the source.

Operations (top level, run in order)

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 }
}

A program must contain at least one operation, and any of the forms above counts — a query on its own is enough. The message you get when there is none still names only the original three (ask, agent call or parallel not found.), which is a wording that predates the data forms rather than a rule about them. The result of the last operation is printed as the output; --all prints the result of every operation, keyed by the variable it was assigned to. Plain assignments (x = 42) are not operations and do not appear in either output.

parallel and parallel over are two different operations that share a word. parallel { … } fans out over branches you wrote down — a fixed set of named steps — and it may also be written inside an agent method. parallel over rows as row limit 4 -> Out[] { … } fans out over data: one body evaluated per element, a limit that is not optional, and top level only. Its own rules — input ordering, on_error, the memory-scope trap — are on the Data & Integration page.

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

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

The grammar is line-based

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
  }
}

A line counts as a continuation of the line before it when it begins with @, or with a binary operator, a comma or a dot — that is, one of || · && · === · !== · <= · >= · == · != · + · - · * · / · < · > · , · .. Note that => is not in that set. The @ form is what lets long annotation chains be split:

schema Answer {
  summary: string
    @desc("A summary based only on the given document")
    @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("does not match the a * b total")

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

luma program.luma --fmt           # print the canonical form
luma program.luma --fmt --write   # rewrite the file in place

// Grading schema
schema Answer   {
      title:string
   @desc("A short title")
  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("A short title")
  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 — values that come from outside

input topic: string
input document: file

The path is resolved relative to the folder that contains the .luma file. If a declared input is not supplied, the program stops with Input missing: --document.

context — binding a file as a source

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

result = ask "Rely only on these documents:\n\n{contract}\n\n{spec}" -> Answer

context binds file content into the program and makes its name a source ID. If your schema has a sources: string[] field — the name is fixed, the runtime recognises sources and nothing else — then every value the model writes there must be one of the defined context names; this is the direct way to stop the model from inventing sources. To narrow access per agent, use the contexts: allowlist.

Comments

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

There is only the // line comment; there is no block comment (/* */).

Variables and assignment

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

Typed local variables

If you add a type to an assignment, the value is validated at the moment it is assigned and that type sticks to the variable — later assignments are checked against the same type.

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

String interpolation

Inside prompt and role texts you can write {variable} and a dotted path of any depth — {variable.field}, {pair.left.name}:

ask "Summarize this topic: {topic}\n\nDocument:\n{document}" -> Summary
ask "Previous finding: {analysis.finding} (confidence {analysis.confidence})" -> Report

• If the value is a string it is written directly; otherwise it is turned into JSON indented by two spaces with JSON.stringify(value, null, 2).
• A reference to an undefined variable produces the error 'x' variable is not defined yet., and a path whose tail does not exist produces Field 'x.y' was not found.
• Text between braces that is not a valid reference — { }, {1x}, {a.} — is left in the prompt exactly as written, with no error. That is deliberate: a prompt that shows the model a JSON example is full of braces, and treating them as broken placeholders would make those prompts unwritable.
• If the agent has a contexts: [...] list, interpolating a context name that is not on the list produces the error Agent context access was denied: x.

Interpolation works only in prompt/role strings — in a string literal of an ordinary assignment {x} is plain text. Use + for concatenation there.

The expression language

Operators and precedence

Reading a call result directly

A call is an expression, so what it returns can be read on the spot — no intermediate variable required:

flag  = mk(1).flag              // field
deep  = mk(1).inner.deep       // chained
first = mk(1).arr[0]           // field, then index
pick  = mk(1).arr[idx(0)]      // the index may itself be a call
name  = schema.describe(Doc).name   // a standard-library call too

This is also valid inside where, when and @valid — including the bare boolean form @valid(v => chk(v).ok). Until v0.11.0 only indexing worked on a call result; field access reported the call as an undefined variable, and the standard-library form blamed the module itself.

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.

A field that is not there stays an error rather than quietly becoming null — mk(1).yok reports Field 'mk(1).yok' was not found., the same rule a variable follows. Indexing an object with a number keeps its own type error: mk(1) key must be a string, got int.

true || false && false     // true  — reads as  true || (false && false)
                           // were they equal: (true || false) && false = false

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

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

?? — a default for null

a ?? b evaluates to a when a is not null, and to b when it is. The right-hand side is evaluated only when it is needed, exactly like && and ||.

amount = raw_amount ?? 0.0           // a nullable field, defaulted
label  = (title ?? subtitle) ?? "-"  // chains left to right
total  = reduce item in items with 0 => acc + (item.amount ?? 0)

It exists because || cannot do this job: || is strictly boolean in Luma, so value || 5 on a null fails with Boolean if condition expected: value rather than defaulting. Nullable fields are the normal case in extraction — T | null is how a schema lets a model say "I did not find it" — so the default is worth an operator.

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

Valid wherever an expression is: assignment, a pure fn body, an agent method, inside an object or list literal, where, when, @valid, map/filter/reduce, if/while. That is the same "single evaluator" promise this section rests on.

You can still use a pure fn to keep a complex predicate readable:

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)

Literals

String concatenation

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

The + operator carries JavaScript semantics: if either side is a string, the result is a string.

Functions that need no import

The 11 functions below are part of the language and can be called anywhere (an agent method, a pure fn, where, @valid) without an import. Everything beyond them comes through the standard library.

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

contains("Ada Lovelace", "Ada")     // true
contains(["vip", "active"], "vip")  // true

trim("  Ada  Lovelace  ")   // "Ada  Lovelace"

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

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

Control flow

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" })
}

The condition must produce a boolean; in numeric comparisons both sides must be numbers, otherwise you get the error Numeric if comparison expected.

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 }
  }
}

A switch must contain at least one case or default. Cases are tried in order, the first match runs, and there is no fall-through.

match

match branches on the runtime tag of a tagged union value. Each case names one member of the union and binds the value under a fresh name; inside that branch the name carries the member's own concrete type, so its fields are reached directly and are not nullable.

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 }
      }
    }
  }
}

A missing member, a default, and a case naming a schema from outside the union are all rejected at parse time:

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'.

What the parser can and cannot see

"A type the parser can see" is the whole rule, and it is worth being concrete about. A field path resolves at any depth as long as every hop names a declared field, so match extraction.data and match envelope.inner.data both work with no intermediate local. A for-loop binding resolves too — the element type of the collection is carried into the binding — which is what makes routing a list of documents an ordinary loop:

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

What the parser refuses is an expression it cannot resolve to a union at all — a field that is not a union, or a value typed any. Then you get Match expression 'x' requires a tagged union type., and the fix is to give the value a type the parser can read rather than to restructure the loop.

Two ways to fold a list of union values

A match branch is an ordinary block: it may assign, and the assignment survives the branch, so accumulating across a list is written the way you would write it anywhere else. Only the bound member variable (invoice, receipt) is scoped to its branch and is gone afterwards.

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 }
  }
}

The other way is a pure fn, which is allowed to open a union directly: inside one, the tag and the member fields are ordinary field reads, with no match and no exhaustiveness check.

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 }
  }
}

The same document.kind written in an agent method is refused — Desk.labels: schema field 'document.kind' was not found. — because a union schema has no fields of its own. So the choice is about what you want checked: match in an agent method is verified exhaustive, and adding a member to the union breaks every match until you handle it. A pure fn is not checked, which is what lets it slot into map and reduce — and what means a new member will quietly fall through to its last branch. Reach for the loop when the set of members matters, and for the pure fn when the shape of the pipeline does.

for / while / break / continue

for page in pages {
  files  = io.readFiles([page])
  part   = ask "Convert this page to Markdown: {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 "Produce 1-3 numeric items." -> 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 is mandatory (try cannot be used on its own). The caught variable is a structured error object:

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

Tool and model errors carry code / message / retryable (and details when there is one); other errors contain only message. These fields are reached with std/agent or std/json:

import agent from "std/agent"

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

Indexing (v0.4.0)

Lists and maps are indexed with [] — reading and writing, including chains:

first = rows[0]
name = rows[i].customer.name
value = m["key"]
buckets[key] = col.append(existing, row)   // write: mutation, same scope rules as x = v
xs[0].field = 3                            // ✗ Error: Unrecognized step in A.run (line 5): xs[0].field = 3

Every boundary is a named error — indexing never returns a silent null:

Collection operations

map, filter and reduce are built-in statements of the language — not functions. They have their own syntax, and each one is a single statement — which may be wrapped across lines at an operator, like any other statement.

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

If the source is not an array you get the error the map/filter/reduce source must be an array.

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

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

Chaining

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

Each step is assigned to a separate variable on its own line; there is no chaining syntax (.filter().map()).

These three are the whole of the collection statement surface, and that is where the language stops rather than where collections stop. Sorting, grouping, chunking, slicing, deduplication and aggregation are functions — 25 of them in std/collections, conventionally imported as col, which is the col behind the col.append the indexing section uses. So the answer to "how do I sort or group this" is not a missing statement; it is a named local and a col.* call on the next line.

pure fn and io fn

Top-level functions are deterministic helpers. They can be called in schema where rules, inside @valid and in agent methods.

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
}

Parameters and validation

• Parameters must be typed and are validated at call time.
• Optional parameter: x?: string. If it is not supplied, its value is null.
• The return value is validated against the declared type as well.
• Field annotations can be added to parameters and they are really enforced at call time: pure fn f(code: string @match("^[A-Z]+$"), score: float @range(0, 10)) -> bool { … }. The same rule applies to io fn, agent method and tool parameters. One annotation is deliberately ignored here: @severity softens a rule only where a value is checked as a result. A parameter is an input, so the rule stays hard — a flagged value does not cross.

export and privacy

// 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)
}

Imports and modules

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)      // this
return { amount: r.amount }

return reviewer.review(doc)   // not this
return { amount: reviewer.review(doc).amount }   // nor this

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.

rules.luma  (export pure fn check)  ──>  bundle.luma  ──>  your program
                                          ✓ schemas arrive here
                                          ✓ check() too

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

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

Convention, not a requirement: the standard library page imports std modules with their canonical aliases (import math from "std/math", import str from "std/string", import col from "std/collections", import num from "std/numeric"). Every example on the standard library page uses these aliases.

Static analysis

Before the program starts running, the parser performs the checks below. Most of them are errors; one of them is a warning.

On top of these, model, run_policy, tool, agent and schema references are resolved: an undefined model, tool or agent name causes the program never to start at all.