TypeBuilder

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 = 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:

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

Modifying Existing Types

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

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')

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:

In addition to the methods above, all types marked with @@dynamic will also appear in the TypeBuilder.

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())

FieldType

FieldType is a type that represents a field in a type. It can be used to add descriptions, constraints, and other metadata to a field.

ClassBuilder

ClassBuilder is a type that represents a class in a type. It can be used to add properties to a class.

ClassPropertyBuilder

ClassPropertyBuilder is a type that represents a property in a class. It can be used to add descriptions, constraints, and other metadata to a property.

EnumBuilder

EnumBuilder is a type that represents an enum in a type. It can be used to add values to an enum.

EnumValueBuilder

EnumValueBuilder is a type that represents a value in an enum. It can be used to add descriptions, constraints, and other metadata to a value.

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")

Creating/modyfing dynamic types with the add_baml method

The TypeBuilder has a higher level API for creating dynamic types at runtime. Here’s an example:

1
tb = TypeBuilder()
2
tb.add_baml("""
3
  // Creates a new class Address that does not exist in the BAML source.
4
  class Address {
5
    street string
6
    city string
7
    state string
8
  }
9
10
  // Modifies the existing @@dynamic User class to add the new address property.
11
  dynamic class User {
12
    address Address
13
  }
14
15
  // Modifies the existing @@dynamic Category enum to add a new variant.
16
  dynamic enum Category {
17
    PURPLE
18
  }
19
""")

Common Patterns

Here are some common patterns when using TypeBuilder:

1. 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)

2. 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())

3. Optional Properties: When some fields might not be present

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

Testing Dynamic Types

See the advanced dynamic types tests guide for examples of testing functions that use dynamic types. See also the reference for syntax.

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.