BAML Python Bindings

Warnings

• breaking Maintain consistent versions across BAML components. The `baml-py` package, `baml-cli` (installed globally or via `uv`/`poetry`), the VSCode BAML extension, and the `generator` version specified in your `generators.baml` file must all be in sync. Mismatched versions can lead to code generation errors or runtime issues.
  Fix: After upgrading `baml-py`, update the `version` field in `generators.baml` and ensure your `baml-cli` and VSCode extension are also updated to match. Rerun `baml-cli generate`.
• gotcha The `baml_client` directory and its contents are entirely auto-generated. Do not manually edit files within `baml_client`, as changes will be overwritten the next time `baml-cli generate` (or the VSCode extension on save) runs.
  Fix: Define or modify your LLM functions, schemas, and clients only within the `.baml` files in your `baml_src` directory. The `baml_client` will be updated automatically.
• gotcha API keys for LLM providers (e.g., OpenAI, Anthropic, Google) are typically configured in `baml_src/clients.baml` and usually rely on environment variables (e.g., `env.OPENAI_API_KEY`). If these variables are not correctly set, BAML client calls will fail.
  Fix: Ensure all required environment variables are set in your execution environment or loaded via `python-dotenv`. For local development, check the playground settings in the VSCode extension.
• gotcha When using BAML in Jupyter Notebooks, the standard `from baml_client.sync_client import b` import pattern does not work well with the `%autoreload` extension. Changes in `.baml` files might not be reflected without a kernel restart.
  Fix: Use `%load_ext autoreload` and `%autoreload 2` at the start of your notebook. Then, import the `baml_client` module directly (e.g., `import app.baml_client as client`) and call functions with the module prefix (e.g., `client.b.ExtractResume(...)`).
• gotcha All BAML function prompts intended for structured output **must** include `{{ ctx.output_format }}` in the prompt template. Omitting this Jinja filter will prevent the final structured output step from occurring, leading to parsing failures or unexpected plain text output.
  Fix: Always include `{{ ctx.output_format }}` at the end of your BAML function's prompt string.

Install

• pip install baml-py Install baml-py
• baml-cli init Initialize BAML project
• baml-cli generate Generate Python client code

Imports

• b
  wrong:

  import baml_py

  correct:

  from baml_client.sync_client import b

  BAML generates a `baml_client` directory; interactions happen via this generated client, not directly through the `baml-py` package itself. `b` is typically the synchronous client instance. For async, use `from baml_client.async_client import b`.
• GeneratedTypes
  wrong:

  from baml_py.types import ...

  correct:

  from baml_client.types import YourSchemaName

  Custom types (schemas) defined in `.baml` files are converted into Pydantic models and placed in the generated `baml_client.types` module.
• AbortController

  from baml_py import AbortController

  Used for programmatic cancellation of BAML function calls.

Quickstart

This quickstart demonstrates how to use `baml-py` after initializing a BAML project and generating client code. First, install `baml-py` and use `baml-cli init` to create a `baml_src` directory with example BAML functions (e.g., `ExtractResume` defined in a `.baml` file). Then, run `baml-cli generate` to create the `baml_client` Python module. The generated client (`b`) allows you to call your BAML-defined functions directly from Python with type-safety. Ensure necessary LLM API keys (e.g., `OPENAI_API_KEY`) are set in your environment.

import os

# NOTE: This example assumes you have run 'baml-cli init' and 'baml-cli generate'.
# A 'baml_src' directory with a BAML function (e.g., ExtractResume) and a 'baml_client'
# directory with generated code must exist in your project.

# Example BAML function definition (e.g., in baml_src/main.baml):
# class Resume {
#   name string
#   title string
# }
# function ExtractResume(resume_text: string) -> Resume {
#   client "openai/gpt-4o"
#   prompt """
#     Parse the following resume and return structured data.
#     {{ resume_text }}
#     {{ ctx.output_format }}
#   """
# }

# Ensure your OpenAI API key is set as an environment variable
os.environ['OPENAI_API_KEY'] = os.environ.get('OPENAI_API_KEY', 'sk-fake-key-for-test')

from baml_client.sync_client import b
from baml_client.types import Resume

def process_resume(resume_text: str) -> Resume:
    print(f"Processing resume: {resume_text[:50]}...")
    try:
        # Call your BAML function, which is now a Python method on 'b'
        response = b.ExtractResume(resume_text=resume_text)
        print("Successfully extracted resume data:")
        print(f"  Name: {response.name}")
        print(f"  Title: {response.title}")
        return response
    except Exception as e:
        print(f"An error occurred: {e}")
        # In a real application, you'd handle specific BAML errors like BamlValidationError
        raise

if __name__ == "__main__":
    sample_resume = (
        "Name: Alice Wonderland\n"
        "Title: Software Engineer\n"
        "Experience: 5 years at ExampleCorp, developing scalable backend services.\n"
        "Education: M.S. Computer Science, University of XYZ"
    )
    
    # This call would only succeed if a baml_src/main.baml with ExtractResume is defined 
    # and baml-cli generate has been run.
    # mock_resume_data = process_resume(sample_resume)
    print("To run this, ensure baml-cli init and baml-cli generate have been executed.")
    print("And OPENAI_API_KEY is set in your environment.")