Registry / llm-agents / baml-py

baml-py

JSON →
library0.222.0pypypi✓ verified 84d ago

BAML (Basically a Made-up Language) is a domain-specific language and toolchain designed to build reliable AI workflows and agents by transforming prompt engineering into schema engineering. It generates type-safe client code for Python (and other languages like TypeScript, Ruby, Go), enabling structured outputs from Large Language Models with built-in features like streaming, retries, and broad model support. The library is actively maintained with frequent releases, currently at version 0.220.0.

pip install baml-py
INSTALL
IMPORT
SIG · BAML-PY
B
baml-py
llm-agentspythonv0.222.0
Install
2.2s avg
Import
Disk
77MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.222.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 78.8MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 2.2s · import 0.000s · 79MB
77MB installed
● package 77MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

BamlRuntime
from baml_py import BamlRuntime
from baml_client.sync_client import b
ClientRegistry
from baml_py import ClientRegistry
BamlStream
from baml_py import BamlStream

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.")
baml --version
Debug
Known issues
breakingMaintain 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`.
affects: All versions
gotchaThe `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.
affects: All versions
gotchaAPI 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.
affects: All versions
gotchaWhen 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(...)`).
affects: All versions
gotchaAll 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.
affects: All versions
Upgrade
Version history
0.222.0latest on PyPI · released Apr 27, 2026
Audit
Dependencies
python-dotenvoptionalRecommended for managing API keys for LLMs.
Agent activity
24 hits · last 30 days
node
20
OpenAI (training)
1
Resources
baml-py — pip install baml-py · libregistry