diff --git a/CLAUDE.md b/CLAUDE.md index a73257713..c8a26c478 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,29 +1,26 @@ -# Braintrust SDK +# Braintrust JavaScript SDK Monorepo -JavaScript client for Braintrust, plus wrapper libraries for OpenAI, Anthropic, and other AI providers. +JavaScript/TypeScript SDKs and integrations for Braintrust. -This repo uses `pnpm` as it's package manager. +This repository uses `pnpm` workspaces. -## Structure +## Repository Structure +```text +. +├── js/ # Main `braintrust` package (see js/CLAUDE.md) +├── integrations/ # Integration packages (@braintrust/*) +├── docs/ # Docs and reference material +└── internal/ # Internal test fixtures and golden projects ``` -sdk/ -├── js/ # JavaScript SDK (see js/CLAUDE.md) -└── core/ # Shared core library -``` - -## Quick Reference - -| Task | Command | -| ------------- | ---------------- | -| Run all tests | `pnpm run test` | -| Build | `pnpm run build` | -| Lint check | `pnpm run lint` | -| Auto-fix | `pnpm run fix` | -## Setup +## Common Commands (repo root) ```bash -pnpm install # Install dependencies -pnpm run build # Build all packages +pnpm install # Install dependencies +pnpm run build # Build all workspace packages +pnpm run test # Run workspace tests (via turbo) +pnpm run lint # Prettier + ESLint checks +pnpm run fix # Auto-fix Prettier + ESLint +make test # Full JS-oriented test flow used in this repo ``` diff --git a/README.md b/README.md index 04e4befcd..a7316a771 100644 --- a/README.md +++ b/README.md @@ -1,72 +1,71 @@ -# Braintrust SDK +# Braintrust JavaScript SDKs -[Braintrust](https://www.braintrust.dev/) is a platform for evaluating and shipping AI products. To learn more about Braintrust or sign up for free, -visit our [website](https://www.braintrust.dev/) or check out the [docs](https://www.braintrust.dev/docs). +[Braintrust](https://www.braintrust.dev/) is a platform for evaluating and shipping AI products. Learn more at [braintrust.dev](https://www.braintrust.dev/) and in the [docs](https://www.braintrust.dev/docs). -This repository contains the JavaScript SDK for Braintrust. The SDK includes utilities to: +This repository contains Braintrust's JavaScript/TypeScript SDKs and integrations, including: -- Log experiments and datasets to Braintrust -- Run evaluations (via the `Eval` framework) +- The main `braintrust` SDK package (`./js`) +- Integration packages under `./integrations` +- Shared tooling and smoke tests for JavaScript SDK development ## Quickstart -First, install the Braintrust SDK: +Install the main SDK and autoeval scorers: ```bash npm install braintrust autoevals ``` -or +Create `tutorial.eval.ts`: -```bash - -yarn add braintrust autoevals - -``` - -Then, create a file named `tutorial.eval.ts` with the following code: - -```typescript +```ts import { Eval } from "braintrust"; import { LevenshteinScorer } from "autoevals"; Eval("Say Hi Bot", { - data: () => { - return [ - { - input: "Foo", - expected: "Hi Foo", - }, - { - input: "Bar", - expected: "Hello Bar", - }, - ]; // Replace with your eval dataset - }, - task: (input) => { - return "Hi " + input; // Replace with your LLM call - }, + data: () => [ + { input: "Foo", expected: "Hi Foo" }, + { input: "Bar", expected: "Hello Bar" }, + ], + task: (input) => "Hi " + input, scores: [LevenshteinScorer], }); ``` -Then, run the following command: +Run it: ```bash -BRAINTRUST_API_KEY= \ - npx braintrust eval tutorial.eval.ts +BRAINTRUST_API_KEY= npx braintrust eval tutorial.eval.ts ``` -## Integrations - -Braintrust provides integrations with several popular AI development tools and platforms: +## Packages -- **LangChain.js**: A callback handler to automatically log LangChain.js executions to Braintrust. [Learn more](integrations/langchain-js) -- **Val Town**: Examples and templates for using Braintrust with Val Town's serverless JavaScript/TypeScript environment. [Learn more](integrations/val.town) -- **Vercel AI SDK**: Integration with Vercel's AI SDK for building AI-powered applications. [Learn more](integrations/vercel-ai-sdk) +| Package | Purpose | npm | Docs | +| --------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | +| `braintrust` | Core JavaScript/TypeScript SDK for logging, tracing, evals, and CLI. | [![npm: braintrust](https://img.shields.io/npm/v/braintrust.svg)](https://www.npmjs.com/package/braintrust) | [js/README.md](js/README.md) | +| `@braintrust/browser` | Browser-focused SDK integration with AsyncLocalStorage polyfill support. | [![npm: @braintrust/browser](https://img.shields.io/npm/v/%40braintrust%2Fbrowser.svg)](https://www.npmjs.com/package/@braintrust/browser) | [integrations/browser-js/README.md](integrations/browser-js/README.md) | +| `@braintrust/langchain-js` | LangChain.js callback handler integration for automatic Braintrust logging. | [![npm: @braintrust/langchain-js](https://img.shields.io/npm/v/%40braintrust%2Flangchain-js.svg)](https://www.npmjs.com/package/@braintrust/langchain-js) | [integrations/langchain-js/README.md](integrations/langchain-js/README.md) | +| `@braintrust/openai-agents` | OpenAI Agents tracing integration for Braintrust. | [![npm: @braintrust/openai-agents](https://img.shields.io/npm/v/%40braintrust%2Fopenai-agents.svg)](https://www.npmjs.com/package/@braintrust/openai-agents) | [integrations/openai-agents-js/README.md](integrations/openai-agents-js/README.md) | +| `@braintrust/otel` | OpenTelemetry span processor and compatibility helpers for Braintrust tracing. | [![npm: @braintrust/otel](https://img.shields.io/npm/v/%40braintrust%2Fotel.svg)](https://www.npmjs.com/package/@braintrust/otel) | [integrations/otel-js/README.md](integrations/otel-js/README.md) | +| `@braintrust/temporal` | Temporal client/worker plugin and workflow interceptors for Braintrust tracing. | [![npm: @braintrust/temporal](https://img.shields.io/npm/v/%40braintrust%2Ftemporal.svg)](https://www.npmjs.com/package/@braintrust/temporal) | [integrations/temporal-js/README.md](integrations/temporal-js/README.md) | ## Documentation -For more information, check out the [docs](https://www.braintrust.dev/docs): +- TypeScript SDK docs: https://www.braintrust.dev/docs/reference/sdks/typescript +- Release notes: https://www.braintrust.dev/docs/reference/release-notes + +## License + +Apache-2.0 + +## Repository History + +This repository was previously named `braintrust-sdk` and was renamed to `braintrust-sdk-javascript`. The rename happened when Python SDK code was split out of this repository. The Python code now lives in a dedicated [`Braintrust Python SDK`](https://github.com/braintrustdata/braintrust-sdk-python) repository. + +## Contributors + +Thanks to everyone who contributed to the Braintrust JavaScript SDK! -- [TypeScript](https://www.braintrust.dev/docs/reference/sdks/typescript) + + + diff --git a/integrations/browser-js/README.md b/integrations/browser-js/README.md index 10f09ceaa..3903ef384 100644 --- a/integrations/browser-js/README.md +++ b/integrations/browser-js/README.md @@ -1,10 +1,12 @@ # Braintrust Browser SDK +[![npm version](https://img.shields.io/npm/v/%40braintrust%2Fbrowser.svg)](https://www.npmjs.com/package/@braintrust/browser) + Official browser-only SDK for [Braintrust](https://braintrust.dev). This is an integration package that provides browser-optimized builds of the Braintrust SDK with AsyncLocalStorage polyfill support for standard browsers. -Note: This package supports limited functionality in the browser. We're aware of a CORS issue that users may run into if they use this outside of the braintrust.dev domain. If you'd like to use this package in your own domain, please provide us feedback [support@braintrust.dev](mailto:support@braintrust.dev) +This package supports limited functionality in the browser. There is a known CORS limitation when used outside the `braintrust.dev` domain. If you need this for your own domain, contact [support@braintrust.dev](mailto:support@braintrust.dev). ## Installation @@ -16,9 +18,14 @@ pnpm add @braintrust/browser braintrust yarn add @braintrust/browser braintrust ``` -Note: `braintrust` is a peer dependency and must be installed alongside `@braintrust/browser`. +Note: Install both packages so your browser integration and main SDK stay on compatible versions. + +## Requirements -## Usage +- `braintrust` (installed alongside `@braintrust/browser`) +- `zod` (`^3.25.34 || ^4.0`) + +## Quickstart ```typescript import * as braintrust from "@braintrust/browser"; @@ -37,29 +44,20 @@ const result = await braintrust.traced( ); ``` -## Differences from Main Package - -This package: - -- **Includes** `als-browser` polyfill for AsyncLocalStorage (bundled) -- **Requires** `braintrust` - -## When to Use +## Notes Use `@braintrust/browser` when: - Building browser-only applications -- Need AsyncLocalStorage support in standard browsers +- Needing AsyncLocalStorage support in standard browsers Use `braintrust` directly when: - Building Node.js applications -- Using in Next.js or other full-stack frameworks (with proper module resolution) -- Need CLI tools or filesystem access - -## Features +- Using Next.js or other full-stack frameworks +- Needing CLI tools or filesystem access -All browser-compatible features from the main SDK: +Browser-compatible features include: - Logging and tracing - Experiments and datasets diff --git a/integrations/langchain-js/README.md b/integrations/langchain-js/README.md index d7d1b314b..d69106b16 100644 --- a/integrations/langchain-js/README.md +++ b/integrations/langchain-js/README.md @@ -1,5 +1,7 @@ # @braintrust/langchain-js +[![npm version](https://img.shields.io/npm/v/%40braintrust%2Flangchain-js.svg)](https://www.npmjs.com/package/@braintrust/langchain-js) + SDK for integrating [Braintrust](https://braintrust.dev) with [LangChain.js](https://langchain.com/js). This package provides a callback handler to automatically log LangChain.js executions to Braintrust. ## Installation @@ -17,7 +19,7 @@ pnpm add @braintrust/langchain-js - Node.js >= 16 - LangChain.js >= 0.3.42 (incl. 1.0.0) -## Usage +## Quickstart First, make sure you have your Braintrust API key set in your environment: @@ -25,8 +27,6 @@ First, make sure you have your Braintrust API key set in your environment: export BRAINTRUST_API_KEY="your-api-key" ``` -### Basic Usage - ```typescript import { ChatOpenAI } from "@langchain/openai"; import { @@ -77,19 +77,7 @@ The callback handler supports logging for: Review the [LangChain.js documentation](https://js.langchain.com/docs/how_to/#callbacks) for more information on how to use callbacks. -## Development - -Contributions are welcomed! - -```bash -git clone https://github.com/braintrustdata/sdk.git +## Documentation -cd sdk/integrations/langchain-js - -pnpm install - -# work on the code - -pnpm test -pnpm build -``` +- Braintrust docs: [https://www.braintrust.dev/docs](https://www.braintrust.dev/docs) +- LangChain callback docs: [https://js.langchain.com/docs/how_to/#callbacks](https://js.langchain.com/docs/how_to/#callbacks) diff --git a/integrations/openai-agents-js/README.md b/integrations/openai-agents-js/README.md index 9592e9aaa..d04d51d67 100644 --- a/integrations/openai-agents-js/README.md +++ b/integrations/openai-agents-js/README.md @@ -1,14 +1,25 @@ # @braintrust/openai-agents +[![npm version](https://img.shields.io/npm/v/%40braintrust%2Fopenai-agents.svg)](https://www.npmjs.com/package/@braintrust/openai-agents) + SDK for integrating Braintrust with OpenAI Agents. ## Installation ```bash npm install braintrust @braintrust/openai-agents @openai/agents +# or +yarn add braintrust @braintrust/openai-agents @openai/agents +# or +pnpm add braintrust @braintrust/openai-agents @openai/agents ``` -## Usage +## Requirements + +- `braintrust` +- `@openai/agents` + +## Quickstart ```typescript import { initLogger } from "braintrust"; @@ -52,3 +63,8 @@ new OpenAIAgentsTraceProcessor(options?: OpenAIAgentsTraceProcessorOptions) - `logger?: Logger` - A Braintrust `Span`, `Experiment`, or `Logger` to use for logging. If undefined, the current span, experiment, or logger will be selected exactly as in `startSpan`. - `maxTraces?: number` - Maximum number of concurrent traces to keep in memory (default: 10000). When exceeded, oldest traces are evicted using LRU policy to prevent memory leaks. + +## Documentation + +- Braintrust docs: [https://www.braintrust.dev/docs](https://www.braintrust.dev/docs) +- OpenAI Agents docs: [https://openai.github.io/openai-agents-js/](https://openai.github.io/openai-agents-js/) diff --git a/integrations/otel-js/README.md b/integrations/otel-js/README.md index f4b702b2c..716bfd5b4 100644 --- a/integrations/otel-js/README.md +++ b/integrations/otel-js/README.md @@ -1,5 +1,7 @@ # @braintrust/otel +[![npm version](https://img.shields.io/npm/v/%40braintrust%2Fotel.svg)](https://www.npmjs.com/package/@braintrust/otel) + SDK for integrating [Braintrust](https://braintrust.dev) with [OpenTelemetry](https://opentelemetry.io/). This package enables you to send OpenTelemetry spans to Braintrust for logging and observability, and provides seamless interoperability between Braintrust and OpenTelemetry tracing contexts. ## Installation @@ -29,16 +31,16 @@ npm install @opentelemetry/context-async-hooks This package supports both OpenTelemetry 1.x and 2.x versions. -Note: You may run into a known [OpenTelemetry browser bug](https://github.com/open-telemetry/opentelemetry-js/issues/3545)) with `@opentelemetry/exporter-trace-otlp-http` < 0.205.0. If you encounter this issue, upgrade the `@opentelemetry/exporter-trace-otlp-http` and related packages to a minimum of: +Note: You may run into a known [OpenTelemetry browser bug](https://github.com/open-telemetry/opentelemetry-js/issues/3545) with `@opentelemetry/exporter-trace-otlp-http` < 0.205.0. If you encounter this issue, upgrade the `@opentelemetry/exporter-trace-otlp-http` and related packages to a minimum of: - `@opentelemetry/exporter-trace-otlp-http` >= 0.205.0 - `@opentelemetry/sdk-trace-base` >= 2.1.0 - `@opentelemetry/api` >= 2.1.0 - `@opentelemetry/core` >= 2.1.0 -It's **important** you do not mix `@opentelemetry/core` and related packages with 1.x with 2.x packages. +It's **important** that `@opentelemetry/core` and related packages all use the same major version (1.x or 2.x). -## Overview +## Capabilities This integration provides two main capabilities: @@ -218,40 +220,7 @@ The following environment variables can be used to configure the integration: - `BRAINTRUST_PARENT`: Parent project identifier (e.g., `project_name:my_project`) - `BRAINTRUST_API_URL`: Braintrust API endpoint (defaults to `https://api.braintrust.dev`) -## Development - -This package is designed to work with both OpenTelemetry 1.x and 2.x. The development structure ensures compatibility across versions: - -### Testing Structure - -- **`src/`**: Main source code that is compatible with both OpenTelemetry 1.x and 2.x -- **`otel-v1/`**: Test package that runs tests against OpenTelemetry 1.x dependencies -- **`otel-v2/`**: Test package that runs tests against OpenTelemetry 2.x dependencies - -### Running Tests - -```bash -# Run tests for both OpenTelemetry versions -pnpm test - -# Run tests for OpenTelemetry 1.x only -pnpm test:v1 - -# Run tests for OpenTelemetry 2.x only -pnpm test:v2 -``` - -### How It Works - -The `otel-v1` and `otel-v2` directories are separate packages that: - -1. Reference the main `src/` code from the parent directory -2. Install different versions of OpenTelemetry dependencies -3. Run the same test suites against their respective OpenTelemetry versions - -This approach ensures the package works correctly with both major OpenTelemetry versions while maintaining a single source codebase. - -## Learn More +## Documentation - [Braintrust Documentation](https://www.braintrust.dev/docs) - [OpenTelemetry Documentation](https://opentelemetry.io/docs/) diff --git a/integrations/temporal-js/README.md b/integrations/temporal-js/README.md index 7521e2567..0d8c97b1a 100644 --- a/integrations/temporal-js/README.md +++ b/integrations/temporal-js/README.md @@ -1,5 +1,7 @@ # @braintrust/temporal +[![npm version](https://img.shields.io/npm/v/%40braintrust%2Ftemporal.svg)](https://www.npmjs.com/package/@braintrust/temporal) + SDK for integrating [Braintrust](https://braintrust.dev) tracing with [Temporal](https://temporal.io/) workflows and activities. ## Installation @@ -14,7 +16,16 @@ yarn add @braintrust/temporal braintrust @temporalio/client @temporalio/worker @ pnpm add @braintrust/temporal braintrust @temporalio/client @temporalio/worker @temporalio/workflow @temporalio/activity @temporalio/common ``` -## Usage +## Requirements + +- `braintrust` +- `@temporalio/client` +- `@temporalio/worker` +- `@temporalio/workflow` +- `@temporalio/activity` +- `@temporalio/common` + +## Quickstart Initialize Braintrust, then install the plugin on both the Temporal client and worker. @@ -46,7 +57,7 @@ const worker = await Worker.create({ }); ``` -## Workflow interceptors +## Workflow Interceptors This package also exports workflow interceptors that are loaded into the Temporal workflow isolate: @@ -54,6 +65,11 @@ This package also exports workflow interceptors that are loaded into the Tempora The `BraintrustTemporalPlugin` automatically configures `workflowModules` to include these interceptors when used on a worker. -## Example +## Examples + +See the examples in `examples/temporal-cjs`, `examples/temporal-esm`, and `examples/temporal-ai-sdk`. + +## Documentation -See the example app in `examples/temporal`. +- Braintrust docs: [https://www.braintrust.dev/docs](https://www.braintrust.dev/docs) +- Temporal docs: [https://docs.temporal.io/](https://docs.temporal.io/) diff --git a/integrations/temporal-js/examples/temporal-esm/README.md b/integrations/temporal-js/examples/temporal-esm/README.md index 2395eb259..af305bb3b 100644 --- a/integrations/temporal-js/examples/temporal-esm/README.md +++ b/integrations/temporal-js/examples/temporal-esm/README.md @@ -48,7 +48,7 @@ pnpm run client Notes and troubleshooting: -- **File references:** worker is at [src/worker.ts](sdk/integrations/temporal-js/examples/temporal-esm/src/worker.ts), the client at [src/client.ts](sdk/integrations/temporal-js/examples/temporal-esm/src/client.ts), and workflows at [src/workflows.ts](sdk/integrations/temporal-js/examples/temporal-esm/src/workflows.ts). +- **File references:** worker is at [src/worker.ts](src/worker.ts), the client at [src/client.ts](src/client.ts), and workflows at [src/workflows.ts](src/workflows.ts). - The example expects the local `@braintrust/temporal` integration to be built (see `pnpm build` step). Building the integration ensures the example uses the local package code. - Use separate terminals for the Temporal server, worker, and client to observe logs independently. - This example uses modern Node ESM. `tsx` is recommended as the runtime for a smooth ESM experience; if you prefer `ts-node`, adapt the commands accordingly. diff --git a/integrations/val.town/README.md b/integrations/val.town/README.md index 3349c294a..080e901d1 100644 --- a/integrations/val.town/README.md +++ b/integrations/val.town/README.md @@ -2,9 +2,7 @@ A collection of example vals showing how to use Braintrust with Val Town. -## Examples - -### Tutorial +## Tutorial [![Open Val Town Template](https://stevekrouse-badge.web.val.run/?3)](https://esm.town/v/braintrust/sdk) @@ -20,7 +18,7 @@ A simple example showing how to use the Braintrust SDK to evaluate an AI functio 2. Follow the setup instructions in the example's README 3. Fork and run the val to see it in action -## Resources +## Documentation - [Braintrust documentation](https://www.braintrust.dev/docs) - [Val Town documentation](https://docs.val.town) diff --git a/js/CLAUDE.md b/js/CLAUDE.md index c4deea798..a81db0a1e 100644 --- a/js/CLAUDE.md +++ b/js/CLAUDE.md @@ -1,19 +1,17 @@ # JavaScript SDK +Run commands from the `js/` directory unless noted otherwise. + ## Running Tests ```bash -make test # All tests -make test-core # Core tests only -make test-openai # OpenAI wrapper -make test-anthropic # Anthropic wrapper -make clean # Remove build artifacts +make test # Full JS test suite (core + wrappers) ``` **Run a single test:** ```bash -pnpm test -- -t "test name" +pnpm test -- -t "test name" # Filters within core vitest suite ``` **Build:** @@ -24,7 +22,7 @@ pnpm build ## Linting & Formatting -From the sdk root: +From the repository root: ```bash pnpm run lint # Check formatting + eslint @@ -45,20 +43,10 @@ pnpm run fix:prettier # Format all files ## Test Framework -Uses Vitest. Config in `vitest.config.js`. Tests make real API calls. +Uses Vitest. Most tests are local/mocked, while some wrapper tests require real API keys. ```bash # Required env vars for wrapper tests export OPENAI_API_KEY="sk-..." export ANTHROPIC_API_KEY="sk-ant-..." ``` - -```typescript -import { describe, it, expect } from "vitest"; - -describe("module", () => { - it("should do something", () => { - expect(value).toBe(expected); - }); -}); -``` diff --git a/js/README.md b/js/README.md index b07ae0253..7a1b21afc 100644 --- a/js/README.md +++ b/js/README.md @@ -1,39 +1,29 @@ -An isomorphic JS library for logging data to Braintrust. +# Braintrust JavaScript SDK -## Version information +[![npm version](https://img.shields.io/npm/v/braintrust.svg)](https://www.npmjs.com/package/braintrust) -**2.x** is the current stable release. [Zod](https://zod.dev/) is now a peer dependency instead of a bundled dependency. This gives you control over the Zod version in your project and reduces bundle size if you’re already using Zod. +An isomorphic JavaScript/TypeScript SDK for logging, tracing, and evaluating AI applications with [Braintrust](https://www.braintrust.dev/). For more details, see the [Braintrust docs](https://www.braintrust.dev/docs) -The SDK requires Zod v3.25.34 or later. +## Installation -### Upgrading from 1.x - -See the [Migrate from v1.x to v2.x guide](https://www.braintrust.dev/docs/reference/sdks/typescript/migrations/v1-to-v2) for instructions. - -### Upgrading from 0.x - -First follow the [Migrate from v0.x to v1.x guide](https://www.braintrust.dev/docs/reference/sdks/typescript/migrations/v0-to-v1), then proceed to the [Migrate from v1.x to v2.x guide](https://www.braintrust.dev/docs/reference/sdks/typescript/migrations/v1-to-v2). - -**Note:** If you do not have OpenTelemetry you can upgrade directly from v0.x to v2.x. - -### Quickstart - -Install the library with npm (or yarn). +Install the SDK: ```bash -npm install braintrust zod +npm install braintrust ``` -Then, run a simple experiment with the following code (replace `YOUR_API_KEY` with -your Braintrust API key): +## Quickstart + +Run a simple experiment (replace `YOUR_API_KEY` with your Braintrust API key): -```javascript +```typescript 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", @@ -45,53 +35,32 @@ async function main() { id: 1, }, }); + console.log(await experiment.summarize()); } main().catch(console.error); ``` -### Browser Support - -**For browser-only applications, use the dedicated browser package:** - -```bash -npm install @braintrust/browser -``` - -The `@braintrust/browser` package is optimized for browser environments and includes the `als-browser` polyfill for AsyncLocalStorage support. It's a standalone package with no peer dependencies. - -**When to use each package:** - -- **`braintrust`** (this package) - For Node.js applications, full-stack frameworks (Next.js, etc.), and edge runtimes with native AsyncLocalStorage (Cloudflare Workers, Vercel Edge) -- **`@braintrust/browser`** - For browser-only applications that need AsyncLocalStorage support in standard browsers - -See the [@braintrust/browser README](../integrations/browser-js/README.md) for more details. - -**Breaking change in v3.0.0:** The `braintrust/browser` subpath export has been deprecated. Browser users should migrate to the `@braintrust/browser` package. - -### Auto-Instrumentation +## Auto-Instrumentation -Braintrust provides automatic instrumentation for popular AI SDKs, eliminating the need for manual wrapping. This feature automatically logs all AI SDK calls (OpenAI, Anthropic, Vercel AI SDK, etc.) to Braintrust without any code changes. +Braintrust can automatically instrument popular AI SDKs (OpenAI, Anthropic, Vercel AI SDK, and others) to log calls without manual wrapper code. -#### Node.js Applications +### Node.js -For Node.js applications, use the `--import` flag to load the instrumentation hook: +Use the runtime import hook: ```bash node --import braintrust/hook.mjs app.js ``` -This works with both ESM and CommonJS modules automatically. +### Bundled Apps -#### Browser/Bundled Applications +Use a bundler plugin: -For browser applications or bundled Node.js applications, use the appropriate bundler plugin: +Vite: -**Vite:** - -```typescript -// vite.config.ts +```ts import { vitePlugin } from "braintrust/vite"; export default { @@ -99,10 +68,9 @@ export default { }; ``` -**Webpack:** +Webpack: -```javascript -// webpack.config.js +```js const { webpackPlugin } = require("braintrust/webpack"); module.exports = { @@ -110,9 +78,9 @@ module.exports = { }; ``` -**esbuild:** +esbuild: -```typescript +```ts import { esbuildPlugin } from "braintrust/esbuild"; await esbuild.build({ @@ -120,9 +88,9 @@ await esbuild.build({ }); ``` -**Rollup:** +Rollup: -```typescript +```ts import { rollupPlugin } from "braintrust/rollup"; export default { @@ -130,15 +98,32 @@ export default { }; ``` -**Important:** If you're using TypeScript or other transpilation plugins, place the Braintrust plugin **after** them in the plugin array to ensure it instruments the transformed code: +If you use TypeScript or other transpilation plugins, place the Braintrust plugin after them so transformed output is instrumented. -```typescript -export default { - plugins: [ - typescript(), // or other transpilation plugins - vitePlugin(), // Braintrust plugin should come after - ], -}; +For deeper details, see the [auto-instrumentation architecture docs](src/auto-instrumentations/README.md). + +## Browser Support + +For browser-only applications, use the dedicated browser package: + +```bash +npm install @braintrust/browser braintrust ``` -For more information on auto-instrumentation, see the [internal architecture docs](src/auto-instrumentations/README.md). +See the [`@braintrust/browser` README](../integrations/browser-js/README.md) for details and current limitations. + +## Migration Guides + +### Upgrading from 2.x to 3.x + +See the [Migrate from v2.x to v3.x guide](https://www.braintrust.dev/docs/reference/sdks/typescript/migrations/v2-to-v3). + +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](https://www.braintrust.dev/docs/reference/sdks/typescript/migrations/v1-to-v2). + +### Upgrading from 0.x to 1.x + +See the [Migrate from v1.x to v2.x guide](https://www.braintrust.dev/docs/reference/sdks/typescript/migrations/v0-to-v1).