BAML

Bitfab integrates with BAML to automatically capture rendered prompts and LLM metadata, with no manual setPrompt or addContext calls. Under an opt-out trace root, BAML calls are recorded on their own (see below). With opt-in spans, wrap a BAML method with wrapBAML / wrap_baml and Bitfab extracts everything onto the current span. Canonical signatures: TypeScript wrapBAML · Python wrap_baml

Client capture off applies to BAML. With captureEnabled: false in TypeScript or capture_enabled=False in Python, wrapped BAML functions continue to run but send no span, and bitfab.call() sends no internal trace for its local execution. Replay items and seedTrace / seed_trace still record when explicitly invoked.

Under a trace root (opt-out tracing)

Beneath a withTrace() / trace() root, BAML calls are recorded without wrapBAML / wrap_baml. Each call on your generated BAML client (b.ClassifyText(...), sync or async) becomes its own llm span named after the client class and function, such as BamlAsyncClient.ClassifyText, carrying the same prompt, model, provider, token counts, and duration listed under What Gets Captured.

import { Bitfab } from "@bitfab/sdk"
import { b } from "./baml_client"

const bitfab = new Bitfab({ apiKey: process.env.BITFAB_API_KEY })

const handleTicket = bitfab.withTrace("handle-ticket", async (text: string) => {
  const label = await b.ClassifyText(text)
  return route(label)
})

import os
from bitfab import Bitfab
from baml_client import b

bitfab = Bitfab(api_key=os.environ["BITFAB_API_KEY"])

@bitfab.trace("handle-ticket")
async def handle_ticket(text: str):
    label = await b.ClassifyText(text)
    return route(label)

TypeScript needs the SDK’s build transform in the server build, the same requirement as the rest of opt-out tracing. The transform recognizes files BAML generated, records only the client’s function calls from them, and skips the rest of the generated code (withOptions, b.stream, parsers, request builders).
Python needs Python 3.12+, as opt-out tracing does. The generated client must already be imported when the root starts, which a module-level from baml_client import b guarantees. It is recorded whether or not baml_client sits inside the root’s package.
Your own collectors keep working. Bitfab adds its collector beside any you pass in the call options or set with b.withOptions({ collector }) / b.with_options(collector=...).
exclude matches the function name (ClassifyText). Excluding it runs the call without recording it. Replay mocking follows the root’s mockOnReplay / mock_on_replay default.
Existing wrapBAML / wrap_baml calls are safe. Under a root, the prompt and usage land on the BAML call’s span, never also on the function that called it.
withNode / node() on a BAML call configures that call’s one span. Pass the bound method or a wrapBAML / wrap_baml wrapper, and the node’s name, replay mocking, and other options apply to the BAML call’s span, which keeps its prompt and usage. Its type stays llm unless the node sets one. No second span is opened beneath it.

const classify = bitfab.withNode(
  { name: "classify", mockOnReplay: true },
  b.ClassifyText.bind(b),
)

classify = bitfab.node(name="classify", mock_on_replay=True)(b.ClassifyText)

A node on your own function stays a separate span. When the node wraps a function of yours that calls BAML, the trace shows your function’s span with the BAML call’s llm span beneath it, and the prompt and usage appear only on the BAML span.
Outside a trace root, BAML calls run exactly as before and record nothing.

The streaming limitation below still applies: b.stream.* calls are not recorded as llm spans.

Supported Languages

Language	Method	Status
TypeScript	`wrapBAML()`	✅ Supported
Python	`wrap_baml()`	✅ Supported
Ruby	-	Not yet supported
Go	-	Not yet supported

Quick Start

import { Bitfab } from "@bitfab/sdk"
import { b } from "./baml_client"

const bitfab = new Bitfab({
  apiKey: process.env.BITFAB_API_KEY,
  bamlClient: b,
})

const tracedClassify = bitfab.withSpan(
  "classify",
  { type: "llm" },
  bitfab.wrapBAML(b.ClassifyText),
)

const result = await tracedClassify("Hello world")

import os
from bitfab import Bitfab
from baml_client import b

bitfab = Bitfab(api_key=os.environ["BITFAB_API_KEY"], baml_client=b)
classify_fn = bitfab.get_function("classify")

@classify_fn.span(type="llm")
async def classify(text: str):
    return await bitfab.wrap_baml(b.ClassifyText)(text=text)

result = await classify("Hello world")

What Gets Captured

wrapBAML / wrap_baml creates a BAML Collector, runs the method through a tracked client, then extracts:

Data	Span Field	Source
Rendered prompt (system + user messages)	`span_data.prompt`	BAML Collector HTTP request body
Model name	`span_data.contexts[].model`	BAML Collector HTTP request body or URL
Provider	`span_data.contexts[].provider`	BAML Collector call metadata
Input tokens	`span_data.contexts[].inputTokens`	BAML Collector usage
Output tokens	`span_data.contexts[].outputTokens`	BAML Collector usage
Duration	`span_data.contexts[].durationMs`	BAML Collector timing

If @boundaryml/baml (TypeScript) or baml-py (Python) is not installed, the BAML method is called directly without instrumentation.

Limitations

Streaming functions are not auto-instrumented. wrapBAML / wrap_baml awaits a single result, so streaming calls (b.stream.ClassifyText, which return a stream rather than a final value) are not captured. Instrument the non-streaming form (b.ClassifyText), or capture the call manually with setPrompt / addContext inside a withSpan / @span root after draining the stream.
Functions that make more than one LLM call capture only one of them. When a BAML function issues multiple HTTP calls (retry policies, fallback clients, round-robin clients), the captured prompt, model, and provider come from the selected call (or the first one if none is marked selected). Token usage is taken from the Collector’s aggregate, so on a fallback chain the recorded model / provider may not correspond to the call that produced the tokens.

TypeScript

Installation

npm install @bitfab/sdk @boundaryml/baml

If your server code is bundled (Next.js with Turbopack, for example), add this import once in server code that loads before your BAML calls, such as the module that creates your Bitfab client:

import "@bitfab/sdk/baml"

Bundlers such as Turbopack rename external packages, so the SDK cannot find @boundaryml/baml by name at runtime. This import lets the bundler resolve it, and the SDK uses the module it loads. Without it, wrapBAML runs untraced and logs a one-time [bitfab] warning.

Method Signature

// Form 1: bamlClient passed in constructor
bitfab.wrapBAML(method: Function): WrappedBamlFn
bitfab.wrapBAML(method: Function, options: WrapBAMLOptions): WrappedBamlFn

// Form 2: bamlClient passed at call site
bitfab.wrapBAML(bamlClient: unknown, method: Function): WrappedBamlFn
bitfab.wrapBAML(bamlClient: unknown, method: Function, options: WrapBAMLOptions): WrappedBamlFn

Parameters:

method (Function, required) - The BAML method to wrap (e.g., b.ClassifyText)
bamlClient (unknown, optional) - The BAML client instance. Required if not passed in the Bitfab constructor
options (WrapBAMLOptions, optional) - Configuration options

WrapBAMLOptions:

onCollector?: (collector: unknown) => void - Callback fired after each invocation with the BAML Collector instance

Returns: A WrappedBamlFn - an async function with the same signature as the original, plus a .collector property.

Usage

Constructor-Based (Recommended)

import { Bitfab } from "@bitfab/sdk"
import { b } from "./baml_client"

const bitfab = new Bitfab({
  apiKey: process.env.BITFAB_API_KEY,
  bamlClient: b,
})

const tracedClassify = bitfab.withSpan(
  "classify",
  { type: "llm" },
  bitfab.wrapBAML(b.ClassifyText),
)

const result = await tracedClassify("Hello world")

Explicit Client

const bitfab = new Bitfab({ apiKey: process.env.BITFAB_API_KEY })

const tracedClassify = bitfab.withSpan(
  "classify",
  { type: "llm" },
  bitfab.wrapBAML(b, b.ClassifyText),
)

Accessing the BAML Collector

The wrapped function exposes a .collector property containing the BAML Collector from the most recent call:

const tracedClassify = bitfab.withSpan(
  "classify",
  { type: "llm" },
  bitfab.wrapBAML(b.ClassifyText),
)

await tracedClassify("Hello world")

const collector = tracedClassify.collector // BAML Collector instance

The .collector is null before the first call or if @boundaryml/baml is not installed.

`onCollector` Callback

For more control, pass an onCollector callback:

const tracedClassify = bitfab.withSpan(
  "classify",
  { type: "llm" },
  bitfab.wrapBAML(b.ClassifyText, {
    onCollector: (collector) => {
      console.log("BAML collector:", collector)
    },
  }),
)

With the explicit client form, options go in the third argument:

bitfab.wrapBAML(b, b.ClassifyText, {
  onCollector: (collector) => { /* ... */ },
})

If the callback throws, the error is silently caught and never crashes your application.

Error Handling

If @boundaryml/baml cannot be loaded (not installed, or bundled without import "@bitfab/sdk/baml"), wrapBAML calls the method directly on the BAML client without instrumentation, does not call onCollector, and logs a one-time [bitfab] warning. Metadata extraction errors are silently caught.

Python

Installation

pip install bitfab-py baml-py

Method Signature

# Form 1: baml_client passed in constructor
bitfab.wrap_baml(method: Callable, *, on_collector: Callable | None = None) -> Callable

# Form 2: baml_client passed at call site
bitfab.wrap_baml(baml_client: Any, method: Callable, *, on_collector: Callable | None = None) -> Callable

Parameters:

method (Callable, required) - The BAML method to wrap (e.g., b.ClassifyText)
baml_client (Any, optional) - The BAML client instance. Required if not passed in the Bitfab constructor
on_collector (Callable, optional, keyword-only): Callback fired after each invocation with the BAML Collector instance

Returns: An async wrapper with the same signature as the original method, plus a .collector attribute holding the most recent call’s Collector (None before the first call or if baml-py is not installed).

Usage

Constructor-Based (Recommended)

import os
from bitfab import Bitfab
from baml_client import b

bitfab = Bitfab(api_key=os.environ["BITFAB_API_KEY"], baml_client=b)
classify_fn = bitfab.get_function("classify")

@classify_fn.span(type="llm")
async def classify(text: str):
    return await bitfab.wrap_baml(b.ClassifyText)(text=text)

result = await classify("Hello world")

Explicit Client

bitfab = Bitfab(api_key=os.environ["BITFAB_API_KEY"])
classify_fn = bitfab.get_function("classify")

@classify_fn.span(type="llm")
async def classify(text: str):
    return await bitfab.wrap_baml(b, b.ClassifyText)(text=text)

Accessing the BAML Collector

The wrapper exposes a .collector attribute with the BAML Collector from the most recent call, and accepts an on_collector callback fired after each invocation:

classify_fn = bitfab.get_function("classify")
classify = bitfab.wrap_baml(
    b.ClassifyText,
    on_collector=lambda collector: print("BAML collector:", collector),
)

@classify_fn.span(type="llm")
async def run(text: str):
    return await classify(text=text)

await run("Hello world")

collector = classify.collector  # BAML Collector instance (None before first call)

If the callback throws, the error is silently caught and never crashes your application.

Error Handling

If baml-py is not installed, wrap_baml falls back to calling the method directly on the BAML client without instrumentation. Metadata extraction errors are silently caught.

Getting Started

Primitives

Account

SDKs

Framework Integrations

Integrations

Web Portal

Reference

Changelog

Under a trace root (opt-out tracing)

Supported Languages

Quick Start

What Gets Captured

Limitations

TypeScript

Installation

Method Signature

Usage

Constructor-Based (Recommended)

Explicit Client

Accessing the BAML Collector

`onCollector` Callback

Error Handling

Python

Installation

Method Signature

Usage

Constructor-Based (Recommended)

Explicit Client

Accessing the BAML Collector

Error Handling

​Under a trace root (opt-out tracing)

​Supported Languages

​Quick Start

​What Gets Captured

​Limitations

​TypeScript

​Installation

​Method Signature

​Usage

​Constructor-Based (Recommended)

​Explicit Client

​Accessing the BAML Collector

​onCollector Callback

​Error Handling

​Python

​Installation

​Method Signature

​Usage

​Constructor-Based (Recommended)

​Explicit Client

​Accessing the BAML Collector

​Error Handling

Under a trace root (opt-out tracing)

Supported Languages

Quick Start

What Gets Captured

Limitations

TypeScript

Installation

Method Signature

Usage

Constructor-Based (Recommended)

Explicit Client

Accessing the BAML Collector

`onCollector` Callback

Error Handling

Python

Installation

Method Signature

Usage

Constructor-Based (Recommended)

Explicit Client

Accessing the BAML Collector

Error Handling