An LLM call is not a library,
it is a language construct

Languages are being patched

Asking a model a question and getting a structured answer back works the same way in every language today: send text, receive text, and figure out the rest yourself. The sum of those workarounds has become a patch layer that repeats in every LLM project.

The pragmatic approach

Luma is not a new general-purpose language and does not try to be. It takes over only the layer where the patches pile up — the boundary where you talk to the model, and since v0.4.0 the boundaries either side of it: the database rows going in and the results going back out. The real code of your tools and your database driver stays in your own JS/TS file, and the rest of your application stays in its own language. That is the pragmatic part: it does not change everything, it changes exactly what is broken.

Concretely, that is one step of a pipeline. Something upstream schedules it; Luma pulls typed rows, reshapes them, sends the hard part to a model under a bounded fan-out, and writes the result back. Scheduling, DAG dependencies and backfill stay with your orchestrator — see Data & Integration for where that line is drawn and why.

1 · One definition, three jobs

You write a schema. The runtime uses it in three separate places:

Wiring this by hand means three separate pieces of code and three separate sources of failure. Here they are three views of the same definition; they cannot fall out of sync.

2 · The parser holds the non-determinism boundary

io fn save(path: string, content: string) -> string {
  return io.writeText(path, content)
}

agent Analyst {
  fn analyze(text: string) -> Analysis {
    ask "Analyze: {text}" -> Analysis
  }
}

pure fn total(items: LineItem[]) -> float {
  s = ask "Sum these: {items}" -> Sum
  return s.value
}
// 'ask' cannot be used inside a pure fn.

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

Whether a function reaches a model, and whether it performs IO, is visible from its body — and that separation is a parse-time rule, not a convention. This is why schema validation is always deterministic: the same data always produces the same result.

3 · Side effects are part of the type

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 Writer {
  tools: [db_write]
  tool_scopes: ["db:write"]
  tool_policy: "approval"
}

"The model accidentally wrote to the database" is not something code review has to catch here — it is something the runtime refuses. Permission, credentials, effect class and replay safety all live in the contract itself.

4 · Observability is not added later

A single --trace-file flag gives you, without a line of instrumentation: every provider request (model, duration, tokens, cost, correlation IDs), every tool execution (cache hit, timeout, idempotency) and every validation rule — including the ones that passed.

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

You read why an extraction failed instead of guessing. → Telemetry & Tracing

5 · The type system does not stop at one shape

A schema takes type parameters, and a union can be resolved by a tag instead of by trial. Both exist for the same reason: at the model boundary, a shape you had to write twice is a shape that can disagree with itself, and a branch chosen by guessing is a wrong answer reported as a correct one.

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> is written once and expanded while the file is parsed: Page<Document> becomes an ordinary schema named Page_Document, and no genericity whatsoever reaches the provider — the request carries a plain object schema. Pair<A, B>, Box<int> and Page<Envelope<LineItem>> work the same way, each instantiation expanded once under a name built from its arguments.

tagged by kind is the part that changes answers rather than ergonomics. Invoice and Receipt above both carry total, so a value holding only a total validates against both. An untagged Invoice | Receipt tries members in order, the first fit wins, and the run reports success — the value became an invoice because of the order the members were typed in. Under a tag, the kind field names exactly one member and nothing is tried. → Type system

A complete Luma program

The file below is an entire runnable program — no framework to import, no class to set up, no glue code to write.

input text: string

schema Analysis @desc("Structured analysis of a piece of text") {
  summary: string @length(20, 400)
  sentiment: enum["positive", "neutral", "negative"]
  tags: string[] @minItems(1) @maxItems(5) @unique
  confidence: 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 Analyst {
  model: Primary
  role: "Be brief, neutral, and rely only on the text you are given."
  temperature: 0
  retry: 2

  fn analyze(text: string) -> Analysis {
    ask "Analyze the following text:\n\n{text}" -> Analysis
  }
}

analyst = Analyst()
result = analyst.analyze(text)

{
  "summary": "The delivery was two days late, but the support team resolved it quickly.",
  "sentiment": "neutral",
  "tags": ["shipping", "delay", "support"],
  "confidence": 0.82
}

What runs in this single file:

• The Analysis schema was converted to JSON Schema and sent to the gateway with strict: true.
• The response was validated locally: the length of summary, enum membership of sentiment, minItems/maxItems/unique for tags, and the [0..1] range for confidence — and a field not present in the schema would have been an error too.
• Had validation failed, the error text would have been appended to the prompt and retried up to two more times (retry: 2).
• The API key lives in the environment, not the code; nothing but getEnv can reach it, and it never leaks into traces, prompts or the cache.
• The model call, its duration, its token usage and every validation rule were recorded as telemetry events.

The result: when you write result.confidence you know that value really is a float between 0 and 1 — because if it were not, the program would never have reached that line.

Execution model

The path a .luma file takes when it runs:

  .luma source
       │
       ├─ comment strip → import resolution → block extraction
       ├─ schema / model / run_policy / tool / agent / pure fn parse
       ├─ static analysis  (unreachable code, unknown schema field,
       │                    dependency cycle, infinite loop, unused variable)
       ↓
  program model
       │
       ├─ model credential resolution (getEnv)
       ├─ tool registry + tool module loading
       ├─ capability probe (GET /models → json_schema, tool_calling…)
       ↓
  operation execution  (in source order)
       │
       ├── deterministic steps      assign · map/filter/reduce · if/switch/for/while
       ├── direct tool              tool calculate({...})  → policy → validate → run
       ├── ask                      schema → JSON Schema → provider adapter
       │        └── native tool loop    tool_calls → run → send result back → 2nd turn
       ├── run policy               fallback · parallel · race · vote · fusion · combo · escalate
       ├── parallel blocks          fan-out → fan-in (nested/flat) → merge
       ├── query / command          bridge → row limit → schema validation per row
       ├── parallel over            one body per element → input-order result store
       ├── http / state             subprocess request · atomic key/value write
       └── a telemetry event at every step
       ↓
  stdout JSON  +  trace.json / trace.jsonl / otel.json

Capability map

Design principles

Writing conventions

schema InvoiceLine {
  unit_price: float
  quantity: int
}

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

Schema invoiceLine {     // keywords are not capitalized
  Unit_Price: Float       // built-in type names are lowercase
}

Agent extractor {         // declaration names start with a capital
  Fn Extract() -> ... {}
}

Keywords are always lowercase (schema, agent, tool, fn, ask); declaration names start with a capital letter (Invoice, Analyst); built-in types are lowercase (string, int, float, bool).

Where to go next