braintrust-api

library0.6.0pypypi✓ verified 85d ago

The `braintrust-api` library is the official Python client for interacting with the Braintrust REST API. It provides convenient access to log, trace, and evaluate AI applications. The library includes type definitions for all request parameters and response fields, supporting both synchronous and asynchronous clients. It is actively maintained with frequent updates, with the current version being 0.6.0.

llm-agents ai-ml observability http-networking

pip install braintrust-api

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BRAINTRUST-API

braintrust-api

llm-agentspythonv0.6.0

Install

4.0s avg

Import

1184ms

Disk

33MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.6.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.10–3.920 runs

installs and imports cleanly · install 0.0s · import 1.237s · 34.9MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 4.0s · import 1.132s · 35MB

33MB installed

● package 33MB

Code

Verified usage

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

Braintrust

✓ from braintrust_api import Braintrust

AsyncBraintrust

✓ from braintrust_api import AsyncBraintrust

✗ from braintrust import AsyncBraintrust

The Braintrust SDK (`braintrust` package) and Braintrust API client (`braintrust-api` package) are distinct. Use `braintrust_api` for the REST API client.

Initializes the Braintrust API client using an API key from an environment variable and creates a new project. This demonstrates basic client initialization and a synchronous API call.

import os from braintrust_api import Braintrust # Ensure BRAINTRUST_API_KEY is set in your environment variables # e.g., export BRAINTRUST_API_KEY="bt_your_api_key_here" api_key = os.environ.get("BRAINTRUST_API_KEY") if not api_key: raise ValueError("BRAINTRUST_API_KEY environment variable not set.") client = Braintrust(api_key=api_key) try: # Create a new project project = client.projects.create(name="My New Project") print(f"Created project with ID: {project.id} and Name: {project.name}") # Optionally, list projects projects_list = client.projects.list(limit=1) for p in projects_list.objects: print(f"Existing project: {p.name} ({p.id})") except Exception as e: print(f"An error occurred: {e}")

Debug

Known issues

gotchaThe `braintrust-api` library (this client) is distinct from the `braintrust` SDK. They have different top-level imports and purposes (REST API access vs. AI logging/evaluation utilities). Ensure you install and import from the correct package based on your needs.

fix

For direct REST API access, `pip install braintrust-api` and `from braintrust_api import Braintrust`. For AI logging/evaluation, `pip install braintrust` and `from braintrust import Eval` or `init_logger`.

affects: All versions

gotchaAPI keys should not be hardcoded in your source code. They are sensitive credentials and should be managed securely, preferably through environment variables.

fix

Set the `BRAINTRUST_API_KEY` environment variable (e.g., `export BRAINTRUST_API_KEY='bt_your_api_key_here'`) or use a `.env` file with `python-dotenv`.

affects: All versions

gotchaThere are separate synchronous (`Braintrust`) and asynchronous (`AsyncBraintrust`) clients. Attempting to `await` a method of the synchronous client or calling an asynchronous method without `await` will lead to runtime errors.

fix

For async operations, import `AsyncBraintrust` and always use `await` with its methods. For sync operations, use `Braintrust` and call methods directly without `await`.

affects: All versions

Errors

Common errors & fixes

braintrust_api.APIStatusError: The API key is invalid or missing.

The `BRAINTRUST_API_KEY` environment variable is either not set, or the provided API key is incorrect or expired. This typically results in a 401 Unauthorized or 403 Forbidden status code.

fix

Verify that `BRAINTRUST_API_KEY` is correctly set in your environment and contains a valid Braintrust API key. You can generate API keys in your Braintrust organization settings.

ImportError: cannot import name 'Braintrust' from 'braintrust' (unknown location)

You have likely installed the `braintrust` SDK package instead of the `braintrust-api` client library, or are trying to import `Braintrust` from the wrong top-level package.

fix

Ensure you have installed `braintrust-api` (`pip install braintrust-api`) and are importing from `braintrust_api`: `from braintrust_api import Braintrust`.

AttributeError: 'Braintrust' object has no attribute 'create' (or similar method missing)

This usually indicates that the `Braintrust` client (or `AsyncBraintrust` client) was not properly initialized or an invalid API call was attempted. Alternatively, it might be a version mismatch where a method was removed or renamed.

fix

Double-check the official documentation for the correct API client initialization and method signatures for your installed version. Ensure your client object is correctly assigned and that you are calling a valid method (e.g., `client.projects.create(...)`).

Upgrade

Version history

0.6.0latest on PyPI · released Nov 28, 2024

Audit

Dependencies

PythonrequiredRequires Python 3.8 or higher.

Agent activity

19 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/braintrustdata/braintrust-api-py ↗

packagehttps://pypi.org/project/braintrust-api/ ↗

homepagehttps://www.braintrust.dev ↗