Dynamic Types - TypeBuilder — Boundary Documentation

Sometimes you have output schemas that change at runtime — for example if you have a list of Categories that you need to classify that come from a database, or your schema is user-provided.

TypeBuilder is used to create or modify dynamic types at runtime to achieve this.

Dynamic BAML Enums

Imagine we want to make a categorizer prompt, but the list of categories to output come from a database.

Add @@dynamic to the class or enum definition to mark it as dynamic in BAML.

baml

1 enum Category {
2   VALUE1 // normal static enum values that don't change
3   VALUE2
4   @@dynamic // this enum can have more values added at runtime
5 } 
6 
7 // The Category enum can now be modified at runtime!
8 function DynamicCategorizer(input: string) -> Category {
9   client GPT4
10   prompt #"
11     Given a string, classify it into a category
12     {{ input }}
13      
14     {{ ctx.output_format }}
15   "#
16 }

Import the TypeBuilder from baml_client in your runtime code and modify Category. All dynamic types you define in BAML will be available as properties of TypeBuilder. Think of the typebuilder as a registry of modified runtime types that the baml function will read from when building the output schema in the prompt.

Python

TypeScript

Ruby

OpenAPI

1 from baml_client.type_builder import TypeBuilder
2 from baml_client import b
3 
4 async def run():
5   tb = TypeBuilder()
6   tb.Category.add_value('VALUE3')
7   tb.Category.add_value('VALUE4')
8   # Pass the typebuilder in the baml_options argument -- the last argument of the function.
9   res = await b.DynamicCategorizer("some input", { "tb": tb })
10   # Now res can be VALUE1, VALUE2, VALUE3, or VALUE4
11   print(res)

Dynamic BAML Classes

Now we’ll add some properties to a User class at runtime using @@dynamic.

BAML

1 class User {
2   name string
3   age int
4   @@dynamic
5 }
6 
7 function DynamicUserCreator(user_info: string) -> User {
8   client GPT4
9   prompt #"
10     Extract the information from this chunk of text:
11     "{{ user_info }}"
12      
13     {{ ctx.output_format }}
14   "#
15 }

We can then modify the User schema at runtime. Since we marked User with @@dynamic, it’ll be available as a property of TypeBuilder.

1 from baml_client.type_builder import TypeBuilder
2 from baml_client import b
3 
4 async def run():
5   tb = TypeBuilder()
6   tb.User.add_property('email', tb.string())
7   tb.User.add_property('address', tb.string()).description("The user's address")
8   res = await b.DynamicUserCreator("some user info", { "tb": tb })
9   # Now res can have email and address fields
10   print(res)

Creating new dynamic classes or enums not in BAML

The previous examples showed how to modify existing types. Here we create a new Hobbies enum, and a new class called Address without having them defined in BAML.

Note that you must attach the new types to the existing Return Type of your BAML function(in this case it’s User).

1 from baml_client.type_builder import TypeBuilder
2 from baml_client.async_client import b
3 
4 async def run():
5   tb = TypeBuilder()
6   hobbies_enum = tb.add_enum("Hobbies")
7   hobbies_enum.add_value("Soccer")
8   hobbies_enum.add_value("Reading")
9 
10   address_class = tb.add_class("Address")
11   address_class.add_property("street", tb.string()).description("The user's street address")
12 
13   tb.User.add_property("hobby", hobbies_enum.type().optional())
14   tb.User.add_property("address", address_class.type().optional())
15   res = await b.DynamicUserCreator("some user info", {"tb": tb})
16   # Now res might have the hobby property, which can be Soccer or Reading
17   print(res)

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 to dynamic types

1 tb = TypeBuilder()
2 tb.User.add_property("email", tb.string()).description("The user's email")

Building dynamic types from JSON schema

We have a working implementation of this, but are waiting for a concrete use case to merge it. Please chime in on the GitHub issue if this is something you’d like to use.

1 import pydantic
2 from baml_client import b
3 
4 class Person(pydantic.BaseModel):
5     last_name: list[str]
6     height: Optional[float] = pydantic.Field(description="Height in meters")
7 
8 tb = TypeBuilder()
9 tb.unstable_features.add_json_schema(Person.model_json_schema())
10 
11 res = await b.ExtractPeople(
12     "My name is Harrison. My hair is black and I'm 6 feet tall. I'm pretty good around the hoop. I like giraffes.",
13     {"tb": tb},
14 )

Testing dynamic types in BAML

This feature is coming soon! Let us know if you’re interested in testing it out!

You can still write tests in Python, TypeScript, Ruby, etc in the meantime.

1	enum Category {
2	VALUE1 // normal static enum values that don't change
3	VALUE2
4	@@dynamic // this enum can have more values added at runtime
5	}
6
7	// The Category enum can now be modified at runtime!
8	function DynamicCategorizer(input: string) -> Category {
9	client GPT4
10	prompt #"
11	Given a string, classify it into a category
12	{{ input }}
13
14	{{ ctx.output_format }}
15	"#
16	}

1	from baml_client.type_builder import TypeBuilder
2	from baml_client import b
3
4	async def run():
5	tb = TypeBuilder()
6	tb.Category.add_value('VALUE3')
7	tb.Category.add_value('VALUE4')
8	# Pass the typebuilder in the baml_options argument -- the last argument of the function.
9	res = await b.DynamicCategorizer("some input", { "tb": tb })
10	# Now res can be VALUE1, VALUE2, VALUE3, or VALUE4
11	print(res)

1	class User {
2	name string
3	age int
4	@@dynamic
5	}
6
7	function DynamicUserCreator(user_info: string) -> User {
8	client GPT4
9	prompt #"
10	Extract the information from this chunk of text:
11	"{{ user_info }}"
12
13	{{ ctx.output_format }}
14	"#
15	}

1	from baml_client.type_builder import TypeBuilder
2	from baml_client.async_client import b
3
4	async def run():
5	tb = TypeBuilder()
6	hobbies_enum = tb.add_enum("Hobbies")
7	hobbies_enum.add_value("Soccer")
8	hobbies_enum.add_value("Reading")
9
10	address_class = tb.add_class("Address")
11	address_class.add_property("street", tb.string()).description("The user's street address")
12
13	tb.User.add_property("hobby", hobbies_enum.type().optional())
14	tb.User.add_property("address", address_class.type().optional())
15	res = await b.DynamicUserCreator("some user info", {"tb": tb})
16	# Now res might have the hobby property, which can be Soccer or Reading
17	print(res)

1	tb = TypeBuilder()
2	tb.User.add_property("email", tb.string()).description("The user's email")

1	import pydantic
2	from baml_client import b
3
4	class Person(pydantic.BaseModel):
5	last_name: list[str]
6	height: Optional[float] = pydantic.Field(description="Height in meters")
7
8	tb = TypeBuilder()
9	tb.unstable_features.add_json_schema(Person.model_json_schema())
10
11	res = await b.ExtractPeople(
12	"My name is Harrison. My hair is black and I'm 6 feet tall. I'm pretty good around the hoop. I like giraffes.",
13	{"tb": tb},
14	)