| name | baml-core |
| description | Minimal BAML skill. BAML is a statically-typed, expression-oriented language with first-class LLM functions — TypeScript-like, snake_case methods, etc. Useful for building ai workflows, agents, evals. |
| metadata | {"baml-toolchain-version":"{{BAML_TOOLCHAIN_VERSION}}"} |
baml
BAML is a statically-typed, expression-oriented language — TypeScript with snake_case methods, name: type, fields, enums, interfaces, generics, closures, optional chaining, backtick strings with ${...} interpolation, .to_string() on any value, a real stdlib. And a declarative DSL for LLM calls (function … { client: prompt: }, test) that desugars into it, so a model's structured output is just a typed return value.
The CLI is the documentation. Discover via baml describe:
brew install baml
baml init
baml help <command>
baml describe baml.json
baml describe Array --budget 120
baml check
baml run -e 'expr'
baml test --list && baml test
baml fmt baml_src/main.baml
baml describe <name> prints the full source body of stdlib functions — the fastest way to verify behavior, and the only path for embedded builtins like assert (no on-disk file). Pure functions need no test/client — check them with baml run -e 'add(2, 3)'.
Don’t describe APIs already demonstrated below unless you run into some errors. You can start based off the examples and use it if you run into more errors or you want actual stdlib details.
Mostly it behaves like JavaScript/TypeScript, with very similar syntax — but BAML is more sound/strict.
Best practices and info
- LLM function = typed return. The RETURN TYPE is the schema the model must produce (
class, enum, literal union, string[], T?). Structured output is just a typed value — hand it to ordinary code.
- Prompts are backtick strings with
${...} interpolation. Write prompt: … ${arg} …, and always inject ${ctx.output_format} for a structured return. Escape with \`` / ${`; nest with extra backticks.
- Clients are values, not config blocks.
client Fast = openai.ResponsesClient.new(model = "…", api_key = env.OPENAI_API_KEY); — the old client<llm> Name { provider: …, options: {…} } block is removed. Anything implementing ai.Client works (openai.ResponsesClient, openai.ChatClient, anthropic.AnthropicClient, …; constructor parameters differ by provider). api_key and base_url accept ai.Credential: a literal string, null for the provider default, or a late-bound env.NAME reference resolved at request time. Compose reliability by wrapping: ai.clients.Retry.new(inner = c, max_attempts = 3) and ai.clients.RoundRobin.new(members = […]) have .new, but ai.clients.Fallback { members: […] } does not — construct it as a class literal. Then use client: Fast in the function, or the shorthand client: "openai/gpt-4o-mini". baml describe openai / baml describe ai.Credential / baml describe ai.clients.
- Shape the schema with field attributes.
@description("…") adds a /// hint the model sees in ${ctx.output_format}; @alias("name") renames the emitted JSON key. Chain: tags: string[] @alias("labels") @description("…").
- Test the pure code, not the model. Unit-test orchestration/post-processing on literal data with
assert.*. Calling an LLM function in a test makes a real request — not an offline test. (f$parse/f$render_prompt/f$build_request exist for debugging.)
- Build strings with interpolation, not coercion.
score=${n} stringifies any value (implicit .to_string()); call .to_string() for the string alone. + needs both sides already strings ("n=" + 5 won't compile).
catch for some, catch_all for all. expr catch (e) { baml.errors.ParseError => fallback } handles a specific error; expr catch_all (e) { _ => fallback } is exhaustive — for a workflow top / entrypoint. Errors propagate implicitly; callers needn't re-declare. Raise with throw baml.errors.InvalidArgument { message: "…" } (error types are the builtin baml.errors.* classes — InvalidArgument/ParseError/Io/Timeout/…; baml describe baml.errors); annotate a fallible signature with -> T throws ErrType. Prefer a typed result union (type R = Ok | Err) over throwing for ordinary control flow.- Interfaces = shared behavior + dynamic dispatch.
interface I { function m(self) -> T } (methods may have default bodies); a class opts in via implements I { … }; a value typed I (or I[]) dispatches to the implementor at runtime. Interfaces can also declare associated types and generic bounds. baml describe interfaces.
- Pattern matching.
match (v) { … } over values/types; arms are pattern => expr — literals, let x: T (bind + narrow), class destructure T { f: let y }, or-patterns A | B, guards … if cond, _; must be exhaustive. Also v is T → bool (narrows) and if let x: T = v { … } else { … }. baml describe patterns.
- Concurrency = green threads.
spawn { … } returns a Future; await collects it. Combine many with baml.future.all / all_complete / race / any (JS Promise.*). Configure a spawn with a with clause: spawn with baml.spawn.options(group = g, cancel = tok, detach = true) { … } — baml.spawn.TaskGroup.new(n) caps concurrency (excess spawns queue FIFO), a baml.spawn.CancelToken cancels cooperatively. baml describe spawn / baml describe baml.future.
- Resource safety —
defer, cleanup, catch (e, ctx). defer { … } runs a block at scope exit, LIFO, on every path (return / throw / fall-through) — like Go. A class method named function cleanup(self) -> void is a finalizer: it runs at most once per instance whether you call it, defer it, or the GC reclaims it. catch (e, ctx) binds an ErrorContext alongside the error — an error thrown while handling another chains onto it, so ctx.root_cause() / ctx.cause walk back to the original failure and ctx.to_string() renders the whole chain (Python __context__-style). while let PATTERN = expr { … } loops until the pattern fails (e.g. draining a T?-returning .pop()).
- Call BAML from Python / TS. Declare a
[generator.<name>] in baml.toml, run baml generate, then import the typed baml_sdk. Install + usage: baml describe python / baml describe typescript / baml describe baml_sdk.
- Safe access over indexing. Subscript panics on a missing index/key; use
.at(i)/.get(k) (→ T?), reach through with ?., default with ?? (parenthesize: (m.get(k) ?? 0) + 1).
- Stdlib methods are snake_case, called on a value. Some return new, some mutate in place, a few do both (
sort_by_key sorts the receiver and returns it) — to read the docs, baml describe <word/type/identifier/keyword/etc>.
- Class fields
name: type,; construct Type { field: val }. Methods take a bare self; factories are free functions. Fields are mutable (like TS): obj.field = v and obj.field += n work, and a self method can mutate in place — a side-effect method returns void. Classes are reference types: find/at(i)/subscript return a live alias, not a copy, so mutating the result mutates that element inside the array (xs.find(p)?.n += 1 updates xs), and a class passed to a function can be mutated by the callee. Struct-update spread is supported: User { ...u, tier: Tier.Free }. Empty classes are legal (class Marker {}) — handy as union variants. Enums are plain variants — no methods, no associated data (E.A.foo() won't compile); put behavior in free functions that match. enum E { A, B }, access E.A.
- Blocks are expressions — last expression is the value (no
;); return x; for early exit. A side-effect-only function returns void; its block's unit value is null. for (let x in xs) iterates VALUES; while (cond) { … } loops. Closures (x) -> { ... } infer param/return from context (annotate (x: T) -> R only when ambiguous; the -> is required). .map/.filter return arrays directly (no .collect()). Empty map needs a type: let m: map<string, int> = {};.
- No ternary —
if/else is the expression. There's no cond ? a : b; if (cond) { a } else { b } is an expression that returns a value, so assign it directly: let label = if (x > 3) { "big" } else { "small" };. Each branch is a block whose last expression is its value (no return). Chain with else if, and pair with if let PATTERN = expr { … } else { … } for bind-and-narrow.
- Conditions use truthiness.
if, while, match guards, &&, ||, and ! accept any value. Falsy values are false, null, numeric zero, empty strings, empty arrays/maps, and empty bytes; everything else is truthy. && and || still return bool, not an operand value. A truthy optional narrows in the taken branch.
- Arrays have a JS-like method set —
map/filter/filter_map/reduce/find/some/every/flat_map/slice/concat/join/includes/length(), plus in-place push/pop/shift/unshift/sort_by/sort_by_key. Most take closures that can throws. baml describe Array gives more info.
- Local let bindings are reassignable (x = x + 1) — no mut keyword (it's TS let, not Rust); there's no const either.
- Args: defaults with
=, keyword calls with = (never :). Declare a default in the signature: function f(a: int, b: int = 10); call f(1) or f(1, b = 2). A defaulted param must be passed by name — f(1, 2) is an error (defaulted parameter 'b' must be passed by name). Any param (even required) may be passed by name (f(a = 1, b = 2)), and you can skip a middle default to set a later one (f(1, c = 9)). Keyword syntax is name = value; name: value won't parse (: is for types/fields). T? does NOT make an argument optional — unlike TS b?: T, a b: T? param is still required (you must pass null, else expected N argument(s), got …); add = null to make it omittable. Built-ins follow this: baml.http.fetch(url, timeout = baml.time.Duration.from_seconds(10)).
- Where it diverges from TS (the silent traps): arithmetic is type-driven, not TS-style.
int / int is truncating integer division (285 / 100 == 2, NOT 2.85) and % is the remainder (285 % 100 == 85); this compiles fine and just gives a quietly-wrong number, so it's the highest-value gotcha. Mix in a float to get float division (285 / 100.0 == 2.85, 285.0 / 100 == 2.85); any mixed int/float op promotes to float (5 + 2.0 == 7.0). There is no .to_float() — convert an int with n * 1.0 (or divide by a float). An int result does not auto-coerce to float on assignment (let x: float = 285 / 100 is a compile error). + is numeric-only: string concat needs both sides already string ("n=" + 5 won't compile — use ${...} interpolation). Comparisons (==, <, …, structural ==) and &&/||/! are TS-like.
- Tests: lone
test "name" { ... } (no wrapper); testset only GROUPS. Asserts (only 6): assert.equal/approx_equal/is_true/is_type/not_null/contains. assert.equal compares structurally (deep, across classes/arrays/maps) — and so does plain ==, which is the bool form. assert.equal is exact on floats; use assert.approx_equal(actual, expected, eps) for computed ones. Last assert: no trailing ;. Canonical IDs are root::TestName for a top-level test and root::Testset::TestName inside a testset. Run one with baml test -i "root::TestName" (-x to exclude); baml test --list prints valid selectors.
