BAML | Respan Docs

Set up Respan

Sign up — Create an account at platform.respan.ai
Create an API key — Generate one on the API keys page
Add credits or a provider key — Add credits on the Credits page or connect your own provider key on the Integrations page

Use AI

Add the Docs MCP to your AI coding tool to get help building with Respan. No API key needed.

1 {
2   "mcpServers": {
3     "respan-docs": {
4       "url": "https://mcp.respan.ai/mcp/docs"
5     }
6   }
7 }

What is BAML?

BAML is a domain-specific language for building reliable LLM functions with structured outputs. It uses Pydantic-style type definitions and a compiler to generate type-safe client code. The Respan integration uses respan-tracing decorators to capture BAML function calls.

Setup

Install packages

$ pip install baml-py respan-tracing

Set environment variables

$ export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
$ export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"

Create instrumentation module

Create a baml_respan.py module that wraps BAML client functions with @task decorators:

1 from respan_tracing import RespanTelemetry, task
2 from baml_client import b
3 from baml_client.types import Collector
4 
5 telemetry = RespanTelemetry()
6 
7 def respan_baml_trace(func):
8     """Decorator that wraps a BAML function with Respan tracing."""
9     @task(name=func.__name__)
10     def wrapper(*args, **kwargs):
11         collector = Collector()
12         kwargs["baml_options"] = {"collector": collector}
13         result = func(*args, **kwargs)
14 
15         # Extract BAML-specific metrics from collector
16         from respan_tracing import get_client
17         client = get_client()
18         for log in collector.logs:
19             client.update_current_span(
20                 attributes={
21                     "baml.prompt_tokens": log.metadata.prompt_tokens,
22                     "baml.output_tokens": log.metadata.output_tokens,
23                     "baml.model": log.metadata.model,
24                 }
25             )
26         return result
27     return wrapper
28 
29 # Wrap your BAML functions
30 ExtractResume = respan_baml_trace(b.ExtractResume)
31 ClassifyIntent = respan_baml_trace(b.ClassifyIntent)

Use the instrumented functions

1 from baml_respan import ExtractResume
2 
3 result = ExtractResume(resume_text="John Doe, Software Engineer at Acme Corp...")
4 print(result)

View your trace

Open the Traces page to see your BAML function traces.

Attributes

Via respan-tracing SDK

1 from respan_tracing import get_client
2 
3 client = get_client()
4 client.update_current_span(
5     respan_params={
6         "customer_identifier": "user-123",
7         "metadata": {"baml_function": "ExtractResume"},
8     }
9 )

Via gateway headers

When using the Respan gateway, pass attributes as headers in your BAML client configuration:

X-Respan-Customer-Identifier: user-123

Looking for gateway integration? See Gateway > BAML.