Foundations

Part I · Learn how source files, types, functions, and generated clients fit together.

A working mental model

A BAML project defines the contract between application code and an AI model. Types describe the data crossing that boundary, functions name the operation, and a generated client gives the host application a typed way to call it.

The source is the contract. Change the BAML declaration, check the project, and regenerate the client before relying on the new shape in application code.

A project can split related types and functions across files while the compiler checks them as one unit.

baml.toml

[package]
name = "docs_cross_file_types"

[package]
name = "docs_cross_file_types"

baml_src/functions.baml

function FirstItem(receipt: Receipt) -> ReceiptItem? {
  receipt.items[0]
}

function FirstItem(receipt: Receipt) -> ReceiptItem? {
  receipt.items[0]
}

baml_src/types.baml

class ReceiptItem {
  name string
  quantity int
}

class Receipt {
  items ReceiptItem[]
}

class ReceiptItem {
  name string
  quantity int
}

class Receipt {
  items ReceiptItem[]
}

Chapters

1. Functions

Define typed inputs and outputs, write a body, and understand the generated call surface.

Book or reference?

Read the book when you want concepts introduced in sequence. Use the function reference when you already know the concept and need its exact shape at a glance.