Skip to navigation
Generated baml_client

with_options

Added in 0.79.0

The with_options function creates a new client with default configuration options for logging, client registry, and type builders. These options are automatically applied to all function calls made through this client, but can be overridden on a per-call basis when needed.

Quick Start

from baml_client import b
from baml_py import ClientRegistry, Collector
# Simple: just set the client name
my_b = b.with_options(client="openai/gpt-5-mini")
# Or with full options for advanced use cases
collector = Collector(name="my-collector")
client_registry = ClientRegistry()
client_registry.set_primary("openai/gpt-5-mini")
env = {"BAML_LOG": "DEBUG", "OPENAI_API_KEY": "key-123"}
# Create client with default options
my_b = b.with_options(collector=collector, client_registry=client_registry, env=env)
# Uses the default options
result = my_b.ExtractResume("...")
# Override options for a specific call
other_collector = Collector(name="other-collector")
result2 = my_b.ExtractResume("...", baml_options={"collector": other_collector})

Common Use Cases

Basic Configuration

Use with_options to create a client with default settings that will be applied to all function calls made through this client. These defaults can be overridden when needed.

from baml_client import b
from baml_py import ClientRegistry, Collector
def run():
    # Configure options
    collector = Collector(name="my-collector")
    client_registry = ClientRegistry()
    client_registry.set_primary("openai/gpt-5-mini")
    # Create configured client
    my_b = b.with_options(collector=collector, client_registry=client_registry)
    # All calls will use the configured options
    res = my_b.ExtractResume("...")
    invoice = my_b.ExtractInvoice("...")
    # Access configuration
    print(my_b.client_registry)
    # Access logs from the collector
    print(collector.logs)
    print(collector.last)

Per-call Tags

Add tags to a specific BAML function call. Tags are useful for correlating requests, A/B versions, user IDs, etc.

from baml_client import b
from baml_py import Collector
collector = Collector(name="tags-collector")
res = b.TestOpenAIGPT4oMini(
    "hello",
    baml_options={
        "collector": collector,
        "tags": {"call_id": "first", "version": "v1"},
    },
)
print(collector.last.tags)

Parallel Execution

When running functions in parallel, with_options helps maintain consistent configuration across all calls. This works seamlessly with the Collector functionality.

from baml_client.async_client import b
from baml_py import ClientRegistry, Collector
import asyncio
async def run():
    collector = Collector(name="my-collector")
    my_b = b.with_options(collector=collector, client_registry=client_registry)
    # Run multiple functions in parallel
    res, invoice = await asyncio.gather(
        my_b.ExtractResume("..."),
        my_b.ExtractInvoice("...")
    )
    # Access results and logs
    print(res)
    print(invoice)
    # Use tags or iterate logs to correlate specific calls
    for log in collector.logs:
        print(log.usage)

Streaming Mode

with_options can be used with streaming functions while maintaining all configured options.

from baml_client.async_client import b
from baml_py import Collector
async def run():
    collector = Collector(name="my-collector")
    my_b = b.with_options(collector=collector, client_registry=client_registry)
    stream = my_b.stream.ExtractResume("...")
    async for chunk in stream:
        print(chunk)
    
    result = await stream.get_final_result()
    # Use tags or collector.last / collector.logs for usage
    print(collector.last.usage)

API Reference

with_options Parameters

These can always be overridden on a per-call basis with the baml_options parameter in any function call.

ParameterTypeDescription
clientstringClient name to use for all calls (shorthand for client_registry.set_primary())
collectorCollectorCollector instance for tracking function calls and usage metrics
client_registryClientRegistryRegistry for managing LLM clients and their configurations
type_builderTypeBuilderCustom type builder for function inputs and outputs
envDict/ObjectEnvironment variables to set for the client
tags (per-call)Dict/ObjectArbitrary metadata for this call; merged with parent trace tags

Configured Client Properties

The configured client maintains the same interface as the base baml_client, so you can use all the same functions and methods.

The configured client maintains the same interface as the base client, so you can use all the same functions and methods.