TypeBuilder — Boundary Documentation

TypeBuilder is used to create or modify output schemas at runtime. It’s particularly useful when you have dynamic output structures that can’t be determined at compile time - like categories from a database or user-provided schemas.

Here’s a simple example of using TypeBuilder to add new enum values before calling a BAML function:

BAML Code

1 enum Category {
2   RED
3   BLUE
4   @@dynamic  // Makes this enum modifiable at runtime
5 }
6 
7 function Categorize(text: string) -> Category {
8   prompt #"
9     Categorize this text:
10     {{ text }}
11 
12     {{ ctx.output_format }}
13   "#
14 }

Runtime Usage

1 from baml_client.type_builder import TypeBuilder
2 from baml_client import b
3 
4 # Create a TypeBuilder instance
5 tb = TypeBuilder()
6 
7 # Add new values to the Category enum
8 tb.Category.add_value('GREEN') 
9 tb.Category.add_value('YELLOW')
10 
11 # Pass the typebuilder when calling the function
12 result = await b.Categorize("The sun is bright", {"tb": tb})
13 # result can now be RED, BLUE, GREEN, or YELLOW

Dynamic Types

There are two ways to use TypeBuilder:

Modifying existing BAML types marked with @@dynamic
Creating entirely new types at runtime

Modifying Existing Types

To modify an existing BAML type, mark it with @@dynamic:

Classes

example

1 class User {
2   name string
3   age int
4   @@dynamic  // Allow adding more properties
5 }

Runtime Usage

1 tb = TypeBuilder()
2 tb.User.add_property('email', tb.string())
3 tb.User.add_property('address', tb.string())

Enums

example

1 enum Category {
2   VALUE1
3   VALUE2
4   @@dynamic  // Allow adding more values
5 }

Runtime Usage

1 tb = TypeBuilder()
2 tb.Category.add_value('VALUE3')
3 tb.Category.add_value('VALUE4')

Creating New Types

You can also create entirely new types at runtime:

1 tb = TypeBuilder()
2 
3 # Create a new enum
4 hobbies = tb.add_enum("Hobbies")
5 hobbies.add_value("Soccer")
6 hobbies.add_value("Reading")
7 
8 # Create a new class
9 address = tb.add_class("Address") 
10 address.add_property("street", tb.string())
11 address.add_property("city", tb.string())
12 
13 # Attach new types to existing BAML type
14 tb.User.add_property("hobbies", hobbies.type().list())
15 tb.User.add_property("address", address.type())

Type Builders

TypeBuilder provides methods for building different kinds of types:

Method	Description	Example
`string()`	Creates a string type	`tb.string()`
`int()`	Creates an integer type	`tb.int()`
`float()`	Creates a float type	`tb.float()`
`bool()`	Creates a boolean type	`tb.bool()`
`list()`	Makes a type into a list	`tb.string().list()`
`optional()`	Makes a type optional	`tb.string().optional()`

Adding Descriptions

You can add descriptions to properties and enum values to help guide the LLM:

1 tb = TypeBuilder()
2 
3 # Add description to a property
4 tb.User.add_property("email", tb.string()) \
5    .description("User's primary email address")
6 
7 # Add description to an enum value 
8 tb.Category.add_value("URGENT") \
9    .description("Needs immediate attention")

Common Patterns

Here are some common patterns when using TypeBuilder:

Dynamic Categories: When categories come from a database or external source

1 categories = fetch_categories_from_db()
2 tb = TypeBuilder()
3 for category in categories:
4     tb.Category.add_value(category)

Form Fields: When extracting dynamic form fields

1 fields = get_form_fields()
2 tb = TypeBuilder()
3 form = tb.add_class("Form")
4 for field in fields:
5     form.add_property(field.name, tb.string())

Optional Properties: When some fields might not be present

1 tb = TypeBuilder()
2 tb.User.add_property("middle_name", tb.string().optional())

All types added through TypeBuilder must be connected to the return type of your BAML function. Standalone types that aren’t referenced won’t affect the output schema.

Future Features

We’re working on additional features for TypeBuilder:

JSON Schema support (awaiting use cases)
OpenAPI schema integration
Pydantic model support

If you’re interested in these features, please join the discussion in our GitHub issues.

1	enum Category {
2	RED
3	BLUE
4	@@dynamic // Makes this enum modifiable at runtime
5	}
6
7	function Categorize(text: string) -> Category {
8	prompt #"
9	Categorize this text:
10	{{ text }}
11
12	{{ ctx.output_format }}
13	"#
14	}

1	from baml_client.type_builder import TypeBuilder
2	from baml_client import b
3
4	# Create a TypeBuilder instance
5	tb = TypeBuilder()
6
7	# Add new values to the Category enum
8	tb.Category.add_value('GREEN')
9	tb.Category.add_value('YELLOW')
10
11	# Pass the typebuilder when calling the function
12	result = await b.Categorize("The sun is bright", {"tb": tb})
13	# result can now be RED, BLUE, GREEN, or YELLOW

1	class User {
2	name string
3	age int
4	@@dynamic // Allow adding more properties
5	}

1	tb = TypeBuilder()
2	tb.User.add_property('email', tb.string())
3	tb.User.add_property('address', tb.string())

1	enum Category {
2	VALUE1
3	VALUE2
4	@@dynamic // Allow adding more values
5	}

1	tb = TypeBuilder()
2	tb.Category.add_value('VALUE3')
3	tb.Category.add_value('VALUE4')

1	tb = TypeBuilder()
2
3	# Create a new enum
4	hobbies = tb.add_enum("Hobbies")
5	hobbies.add_value("Soccer")
6	hobbies.add_value("Reading")
7
8	# Create a new class
9	address = tb.add_class("Address")
10	address.add_property("street", tb.string())
11	address.add_property("city", tb.string())
12
13	# Attach new types to existing BAML type
14	tb.User.add_property("hobbies", hobbies.type().list())
15	tb.User.add_property("address", address.type())

1	tb = TypeBuilder()
2
3	# Add description to a property
4	tb.User.add_property("email", tb.string()) \
5	.description("User's primary email address")
6
7	# Add description to an enum value
8	tb.Category.add_value("URGENT") \
9	.description("Needs immediate attention")

1	categories = fetch_categories_from_db()
2	tb = TypeBuilder()
3	for category in categories:
4	tb.Category.add_value(category)

1	fields = get_form_fields()
2	tb = TypeBuilder()
3	form = tb.add_class("Form")
4	for field in fields:
5	form.add_property(field.name, tb.string())

1	tb = TypeBuilder()
2	tb.User.add_property("middle_name", tb.string().optional())