README.md

Braintrust JavaScript SDK

An isomorphic JavaScript/TypeScript SDK for logging, tracing, and evaluating AI applications with Braintrust. For more details, see the TypeScript SDK docs.

Installation

Install the SDK:

npm install braintrust

Quickstart

Run a simple experiment (replace YOUR_API_KEY with your Braintrust API key):

import * as braintrust from "braintrust";

async function main() {
  const experiment = await braintrust.init("NodeTest", {
    apiKey: "YOUR_API_KEY",
  });

  experiment.log({
    input: { test: 1 },
    output: "foo",
    expected: "bar",
    scores: {
      n: 0.5,
    },
    metadata: {
      id: 1,
    },
  });

  console.log(await experiment.summarize());
}

main().catch(console.error);

Auto-Instrumentation

Braintrust can automatically instrument popular AI SDKs (OpenAI, Anthropic, Vercel AI SDK, and others) to log calls without manual wrapper code.

Node.js

Use the runtime import hook:

node --import braintrust/hook.mjs app.js

Bundled Apps

Use a bundler plugin:

Vite:

import { braintrustVitePlugin } from "braintrust/vite";

export default {
  plugins: [braintrustVitePlugin()],
};

Webpack:

const { braintrustWebpackPlugin } = require("braintrust/webpack");

module.exports = {
  plugins: [braintrustWebpackPlugin()],
};

esbuild:

import { braintrustEsbuildPlugin } from "braintrust/esbuild";

await esbuild.build({
  plugins: [braintrustEsbuildPlugin()],
});

Rollup:

import { braintrustRollupPlugin } from "braintrust/rollup";

export default {
  plugins: [braintrustRollupPlugin()],
};

If you use TypeScript or other transpilation plugins, place the Braintrust plugin after them so transformed output is instrumented.

For deeper details, see the auto-instrumentation architecture docs.

Migration Guides

Upgrading from 2.x to 3.x

See the Migrate from v2.x to v3.x guide.

In 3.x, browser usage should move to @braintrust/browser instead of relying on the legacy braintrust/browser path.

Upgrading from 1.x to 2.x

See the Migrate from v1.x to v2.x guide.

Upgrading from 0.x to 1.x

See the Migrate from v1.x to v2.x guide.

Compatibility

The braintrust package is compatible with Node.js versions 20.12.0, 22.13.0, for the respective major Node.js release lines and above.