baml-demos

Use when calling BAML from host code, or when BAML needs a host capability it lacks (DBs, sockets, crypto). Today's supported host is Python via `baml generate` -> the `baml_sdk` package (NOT the older `baml_client` name). Covers the `generator target { ... }` block (in a `.baml` file, NOT TOML), the generated `b.<function>` API, and the host-bridge pattern (BAML shells out to a thin Python entrypoint via `baml.sys.shell`). Other host languages exist upstream but should not be assumed in this repo. Prerequisite: baml-core.

Foundation knowledge for writing BAML. ALWAYS load this first when working in .baml files, when the user asks how to install / use BAML, or when answering any BAML question. Covers install, project layout with `ns_*` namespaces, the `baml run / describe / fmt / generate` agent loop, syntax essentials (classes with `: Type,` fields, snake_case functions, type aliases ending in `;`), stdlib (Collections/Strings, JSON via `baml.json.*`, files/HTTP/shell/env via `baml.fs/http/sys/env`), `match` + typed `throws / catch`, and common pitfalls. BAML is a general-purpose typed language with LLM-function support — not just a prompt DSL. Load the other baml-* skills only as the task demands.

Use when defining or editing a BAML LLM function — any `function X(...) -> T { client: ... prompt: #"..."# }` declaration. Covers the `client<llm>` block (UpperCamelCase) with `provider` + `options`, the inline `client:` (colon) binding in the function body, the `client: "provider/model"` shorthand, Jinja prompts with `{{ ctx.output_format }}`, and structured output via the return type. Prerequisite: baml-core.

Use when composing multiple BAML functions into a typed pipeline — `let stage1 = ...; let stage2 = ...; Result { ... }`. Covers function-to-function composition with typed values flowing between stages, dispatch via `match` on enums / literal unions / `let <name>: <Type> =>` bindings, error propagation with `throws T` / `catch (e) { T => ... }` type-only arms, and fan-out patterns (sequential in BAML, parallel via host). Prerequisite: baml-core. Often paired with baml-llm-functions.

Use when writing or running BAML tests. Covers `testset` / `test` blocks with `let` bindings + `assert.equal` / `assert.*`, running tests with `baml test --list / -i / -e`, decoding cached LLM replies and fixtures via `baml.json.from_string<T>(raw)` or the compiler-synthesized `F$parse(raw)` companion (you don't hand-write `$` names, but the generated one is callable), and nested testsets for grouping. Prerequisite: baml-core. Pair with baml-llm-functions or baml-pipelines if the function under test calls an LLM.