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:
- Create an account at https://openrouter.ai and open https://openrouter.ai/settings/keys.
- Create a key. Keys start with
sk-or-. - 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. |