Puck.Backends.Baml.TypeBuilder (Puck v0.2.23)

Converts Zoi schemas to BamlElixir.TypeBuilder structs.

When using the BAML backend with output_schema, Zoi schemas define the expected output structure but BAML's Rust runtime has no knowledge of these types. This module bridges the gap by converting Zoi schemas into BamlElixir.TypeBuilder structs that can be passed as the :tb option, giving BAML full knowledge of the schema for Schema-Aligned Parsing and prompt formatting via ctx.output_format.

Pipeline

Normalize struct schemas to object schemas (structs can't be JSON encoded)
Convert to JSON Schema via Zoi.to_json_schema/1
Recursively convert JSON Schema nodes to TypeBuilder structs

Examples

iex> schema = Zoi.object(%{name: Zoi.string(), age: Zoi.integer()})
iex> types = Puck.Backends.Baml.TypeBuilder.from_schema(schema)
iex> [%BamlElixir.TypeBuilder.Class{name: "DynamicOutput"}] = types

Summary

Functions

from_dynamic_union(union, dynamic_classes, schema_descriptions \\ %{})

Builds TypeBuilder structs for a union schema with dynamic classes.

from_schema(zoi_schema, opts \\ [])

Converts a Zoi schema to a list of BamlElixir.TypeBuilder structs.

Functions

from_dynamic_union(union, dynamic_classes, schema_descriptions \\ %{})

Builds TypeBuilder structs for a union schema with dynamic classes.

When a union schema has runtime-declared dynamic classes, this function emits a TB.Enum for the type discriminator (with per-value descriptions) and a TB.Class for the shared dynamic fields. Non-type fields are collected from all dynamic schemas and emitted as string | null unions.

Returns a flat list of TB.Enum and TB.Class structs.

from_schema(zoi_schema, opts \\ [])

Converts a Zoi schema to a list of BamlElixir.TypeBuilder structs.

Returns a list of named types (classes, enums) that BAML's Rust runtime needs to know about. Inline types (lists, maps, unions, literals) are embedded directly in field type references.

Options

:name - Root type name (default: "DynamicOutput")