Skip to content

Setup

Requirements

  • Python 3.13 or later. CI tests Linux with Python 3.13 only. Other systems and later Python versions are not tested yet.
  • A package installer such as pip or uv.
  • An API key for an LLM provider. The default is OpenRouter's free router, which needs no paid plan. You can use another provider instead: see Choosing the model.
  • The BAML toolchain 0.25, only in a source checkout (step 1).

Install from PyPI

pip install ebaml            # or: uv add ebaml
pip install "ebaml[mcp]"     # with the MCP server, or: uv add "ebaml[mcp]"

The wheel holds the generated SDK, so it needs no BAML toolchain. Then set the API key (step 3), and go on with Usage. The wheel needs one version of baml-bridge, and it pins that version. To change a prompt or the provider in a .baml file, work from a source checkout.

Work from a source checkout

Steps 1, 2, 4, 5 and 6 are for a source checkout. Step 3 also applies to an installation from PyPI.

1. Install the BAML toolchain

curl -fsSL https://pkg.boundaryml.com/install.sh | sh -s

The installer prints a line to add to your shell profile. Add it, then open a new shell:

. "$HOME/.baml/env"

Check it:

baml --version   # toolchain 0.25 or later

If baml resolves to an older install (Homebrew baml, or baml-py in a virtualenv), remove it or put ~/.baml/bin first on PATH. The old CLIs have no describe, generate add or agent commands.

If a command stops with "the BAML agent skill is required", run baml agent install and retry.

2. Get the code and install the Python dependencies

git clone https://github.com/johnny-godoy/EBaMl.git
cd EBaMl
uv sync

3. Set the API key of your LLM provider

For the default provider, OpenRouter:

  1. Create an account at https://openrouter.ai and open https://openrouter.ai/settings/keys.
  2. Create a key. Keys start with sk-or-.
  3. Export it in the shell you run the code from:
export OPENROUTER_API_KEY=sk-or-...

The key is read from the environment when a request is sent. It is never written to a .baml file.

Using another provider? Set its variable instead (ANTHROPIC_API_KEY, OPENAI_API_KEY, ...) and pass model= as described in Choosing the model. Local models (Ollama) need no key.

4. Generate the Python SDK

baml generate

This writes the src/baml_sdk/ package from baml_src/, next to ebaml, so it imports wherever the project is installed. Rerun it every time a .baml file changes, including when you change the provider.

If src/baml_sdk/ does not exist, the first use of describe_graph, describe_ebm or explain_instance runs baml generate. import ebaml alone does not run it. If the package was generated by another BAML toolchain than the one that baml-bridge expects (a version skew), the first use runs baml toolchain use <version> and baml generate. If the agent skill check stops baml generate, the first use runs it again with --agent-skill-check off. If none of this works, SDKUnavailableError lists the steps that fix the cause.

5. Check the setup

OPENROUTER_API_KEY=unused baml test -x root::Live   # offline tests on a scripted client, no network
baml run main                         # prints "hello from baml"

These two do not call an LLM, so they pass without a working key or provider. They check the toolchain and the SDK.

6. Live test (optional)

Makes real requests to your provider (9 on the OpenRouter free router, so it can be slow or rate limited). It does nothing without OPENROUTER_API_KEY, so with another provider run the example of Usage instead.

OPENROUTER_API_KEY=sk-or-... uv run python scripts/llm/openrouter.py

It fits a small EBM, runs the three-turn chain directly and checks that the provider reports token usage, then runs describe_graph and describe_ebm. It exits non-zero on the first failed assertion.

Troubleshooting

Symptom Cause and fix
baml: command not found In a source checkout, the profile line from step 1 is not loaded. Open a new shell or run . "$HOME/.baml/env".
unknown command: describe (or generate add, agent) An older baml is first on PATH. See step 1.
SDKUnavailableError, or ModuleNotFoundError: baml_sdk The SDK is not generated or has the wrong version, and ebaml could not fix it. The message of the error lists the steps. Run baml generate (step 4).
MissingAPIKeyError The key of the provider is not exported in this shell. The message names the variable. See Choosing the model for the variable of each provider.
APIKeyRejectedError The provider rejected the key. Check the key, its account and its credit.
RateLimitedError The provider limited the rate. Lower the concurrency, describe_ebm(DescribeEBMRequest(ebm, max_concurrency=2)), or pin a paid model.
ProviderUnreachableError A request did not reach the provider. Check the network, HTTPS_PROXY and base_url.