braintrust 3.3.0 → 3.4.0

package/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).

package/dev/dist/index.d.mts

@@ -8382,6 +8382,14 @@ declare const ToolFunctionDefinition: z.ZodObject<{
 type ToolFunctionDefinitionType = z.infer<typeof ToolFunctionDefinition>;
 
 type GenericFunction<Input, Output> = ((input: Input) => Output) | ((input: Input) => Promise<Output>);
+interface BaseFnOpts {
+    name: string;
+    slug: string;
+    description: string;
+    ifExists: IfExistsType;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+}
 
 interface IsoAsyncLocalStorage<T> {
     enterWith(store: T): void;
@@ -8389,6 +8397,9 @@ interface IsoAsyncLocalStorage<T> {
     getStore(): T | undefined;
 }
 
+type DebugLogLevel = "error" | "warn" | "info" | "debug";
+type DebugLogLevelOption = DebugLogLevel | false | undefined;
+
 /**
  * Abstract base class for ID generators
  */
@@ -10424,11 +10435,25 @@ declare const evalParametersSchema: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodOb
             type: "function";
         }[] | undefined;
     }) | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"model">;
+    default: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "model";
+    description?: string | undefined;
+    default?: string | undefined;
+}, {
+    type: "model";
+    description?: string | undefined;
+    default?: string | undefined;
 }>, z.ZodType<z.ZodType<unknown, z.ZodTypeDef, unknown>, z.ZodTypeDef, z.ZodType<unknown, z.ZodTypeDef, unknown>>]>>;
 type EvalParameters = z.infer<typeof evalParametersSchema>;
 type InferParameterValue<T> = T extends {
     type: "prompt";
-} ? Prompt : T extends z.ZodType ? z.infer<T> : never;
+} ? Prompt : T extends {
+    type: "model";
+} ? string : T extends z.ZodType ? z.infer<T> : never;
 type InferParameters<T extends EvalParameters> = {
     [K in keyof T]: InferParameterValue<T[K]>;
 };
@@ -10706,6 +10731,8 @@ declare const loginSchema: z.ZodObject<{
         collect: "some" | "none" | "all";
         fields?: ("dirty" | "tag" | "commit" | "branch" | "author_name" | "author_email" | "commit_message" | "commit_time" | "git_diff")[] | undefined;
     }>>>;
+    debugLogLevel: z.ZodOptional<z.ZodEnum<["error", "warn", "info", "debug"]>>;
+    debugLogLevelDisabled: z.ZodOptional<z.ZodBoolean>;
 }, "strict", z.ZodTypeAny, {
     appUrl: string;
     appPublicUrl: string;
@@ -10718,6 +10745,8 @@ declare const loginSchema: z.ZodObject<{
         collect: "some" | "none" | "all";
         fields?: ("dirty" | "tag" | "commit" | "branch" | "author_name" | "author_email" | "commit_message" | "commit_time" | "git_diff")[] | undefined;
     } | null | undefined;
+    debugLogLevel?: "error" | "warn" | "info" | "debug" | undefined;
+    debugLogLevelDisabled?: boolean | undefined;
 }, {
     appUrl: string;
     appPublicUrl: string;
@@ -10730,6 +10759,8 @@ declare const loginSchema: z.ZodObject<{
         collect: "some" | "none" | "all";
         fields?: ("dirty" | "tag" | "commit" | "branch" | "author_name" | "author_email" | "commit_message" | "commit_time" | "git_diff")[] | undefined;
     } | null | undefined;
+    debugLogLevel?: "error" | "warn" | "info" | "debug" | undefined;
+    debugLogLevelDisabled?: boolean | undefined;
 }>;
 type SerializedBraintrustState = z.infer<typeof loginSchema>;
 declare class BraintrustState {
@@ -10750,6 +10781,8 @@ declare class BraintrustState {
     proxyUrl: string | null;
     loggedIn: boolean;
     gitMetadataSettings?: GitMetadataSettingsType;
+    debugLogLevel?: DebugLogLevel;
+    private debugLogLevelConfigured;
     fetch: typeof globalThis.fetch;
     private _appConn;
     private _apiConn;
@@ -10780,6 +10813,9 @@ declare class BraintrustState {
     static deserialize(serialized: unknown, opts?: LoginOptions): BraintrustState;
     setFetch(fetch: typeof globalThis.fetch): void;
     setMaskingFunction(maskingFunction: ((value: unknown) => unknown) | null): void;
+    setDebugLogLevel(option: DebugLogLevelOption): void;
+    getDebugLogLevel(): DebugLogLevel | undefined;
+    hasDebugLogLevelOverride(): boolean;
     login(loginParams: LoginOptions & {
         forceLogin?: boolean;
     }): Promise<void>;
@@ -11028,6 +11064,19 @@ interface LoginOptions {
      * server. Defaults to false.
      */
     disableSpanCache?: boolean;
+    /**
+     * Controls internal Braintrust SDK troubleshooting output.
+     *
+     * Use `"error"`, `"warn"`, `"info"`, or `"debug"` to control how much
+     * internal SDK troubleshooting output is emitted. Use `false` to explicitly
+     * disable this output.
+     *
+     * When omitted, the SDK remains silent unless
+     * `BRAINTRUST_DEBUG_LOG_LEVEL` is set to `"error"`, `"warn"`, `"info"`, or
+     * `"debug"`. This option only affects local console output; it does not
+     * change what data is logged to Braintrust.
+     */
+    debugLogLevel?: DebugLogLevel | false;
 }
 type OptionalStateArg = {
     state?: BraintrustState;
@@ -12720,14 +12769,6 @@ declare const promptDefinitionSchema: z.ZodIntersection<z.ZodUnion<[z.ZodObject<
 }>>;
 type PromptDefinition = z.infer<typeof promptDefinitionSchema>;
 
-interface BaseFnOpts {
-    name: string;
-    slug: string;
-    description: string;
-    ifExists: IfExistsType;
-    metadata?: Record<string, unknown>;
-}
-
 type NameOrId = {
     name: string;
 } | {
@@ -12814,6 +12855,7 @@ declare class CodeFunction<Input, Output, Fn extends GenericFunction<Input, Outp
     readonly parameters?: z.ZodSchema<Input>;
     readonly returns?: z.ZodSchema<Output>;
     readonly ifExists?: IfExistsType;
+    readonly tags?: string[];
     readonly metadata?: Record<string, unknown>;
     constructor(project: Project, opts: Omit<CodeOpts<Input, Output, Fn>, "name" | "slug"> & {
         name: string;
@@ -12833,6 +12875,7 @@ declare class CodePrompt {
     readonly id?: string;
     readonly functionType?: FunctionTypeEnumType;
     readonly toolFunctions: (SavedFunctionIdType | GenericCodeFunction)[];
+    readonly tags?: string[];
     readonly metadata?: Record<string, unknown>;
     constructor(project: Project, prompt: PromptDataType, toolFunctions: (SavedFunctionIdType | GenericCodeFunction)[], opts: Omit<PromptOpts<false, false, false, false>, "name" | "slug"> & {
         name: string;
@@ -12900,6 +12943,7 @@ interface FunctionEvent {
     function_data: z.infer<typeof FunctionData>;
     function_type?: FunctionTypeEnumType;
     if_exists?: IfExistsType;
+    tags?: string[];
     metadata?: Record<string, unknown>;
 }
 declare class ProjectNameIdMap {

package/dev/dist/index.d.ts

@@ -8382,6 +8382,14 @@ declare const ToolFunctionDefinition: z.ZodObject<{
 type ToolFunctionDefinitionType = z.infer<typeof ToolFunctionDefinition>;
 
 type GenericFunction<Input, Output> = ((input: Input) => Output) | ((input: Input) => Promise<Output>);
+interface BaseFnOpts {
+    name: string;
+    slug: string;
+    description: string;
+    ifExists: IfExistsType;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+}
 
 interface IsoAsyncLocalStorage<T> {
     enterWith(store: T): void;
@@ -8389,6 +8397,9 @@ interface IsoAsyncLocalStorage<T> {
     getStore(): T | undefined;
 }
 
+type DebugLogLevel = "error" | "warn" | "info" | "debug";
+type DebugLogLevelOption = DebugLogLevel | false | undefined;
+
 /**
  * Abstract base class for ID generators
  */
@@ -10424,11 +10435,25 @@ declare const evalParametersSchema: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodOb
             type: "function";
         }[] | undefined;
     }) | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"model">;
+    default: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "model";
+    description?: string | undefined;
+    default?: string | undefined;
+}, {
+    type: "model";
+    description?: string | undefined;
+    default?: string | undefined;
 }>, z.ZodType<z.ZodType<unknown, z.ZodTypeDef, unknown>, z.ZodTypeDef, z.ZodType<unknown, z.ZodTypeDef, unknown>>]>>;
 type EvalParameters = z.infer<typeof evalParametersSchema>;
 type InferParameterValue<T> = T extends {
     type: "prompt";
-} ? Prompt : T extends z.ZodType ? z.infer<T> : never;
+} ? Prompt : T extends {
+    type: "model";
+} ? string : T extends z.ZodType ? z.infer<T> : never;
 type InferParameters<T extends EvalParameters> = {
     [K in keyof T]: InferParameterValue<T[K]>;
 };
@@ -10706,6 +10731,8 @@ declare const loginSchema: z.ZodObject<{
         collect: "some" | "none" | "all";
         fields?: ("dirty" | "tag" | "commit" | "branch" | "author_name" | "author_email" | "commit_message" | "commit_time" | "git_diff")[] | undefined;
     }>>>;
+    debugLogLevel: z.ZodOptional<z.ZodEnum<["error", "warn", "info", "debug"]>>;
+    debugLogLevelDisabled: z.ZodOptional<z.ZodBoolean>;
 }, "strict", z.ZodTypeAny, {
     appUrl: string;
     appPublicUrl: string;
@@ -10718,6 +10745,8 @@ declare const loginSchema: z.ZodObject<{
         collect: "some" | "none" | "all";
         fields?: ("dirty" | "tag" | "commit" | "branch" | "author_name" | "author_email" | "commit_message" | "commit_time" | "git_diff")[] | undefined;
     } | null | undefined;
+    debugLogLevel?: "error" | "warn" | "info" | "debug" | undefined;
+    debugLogLevelDisabled?: boolean | undefined;
 }, {
     appUrl: string;
     appPublicUrl: string;
@@ -10730,6 +10759,8 @@ declare const loginSchema: z.ZodObject<{
         collect: "some" | "none" | "all";
         fields?: ("dirty" | "tag" | "commit" | "branch" | "author_name" | "author_email" | "commit_message" | "commit_time" | "git_diff")[] | undefined;
     } | null | undefined;
+    debugLogLevel?: "error" | "warn" | "info" | "debug" | undefined;
+    debugLogLevelDisabled?: boolean | undefined;
 }>;
 type SerializedBraintrustState = z.infer<typeof loginSchema>;
 declare class BraintrustState {
@@ -10750,6 +10781,8 @@ declare class BraintrustState {
     proxyUrl: string | null;
     loggedIn: boolean;
     gitMetadataSettings?: GitMetadataSettingsType;
+    debugLogLevel?: DebugLogLevel;
+    private debugLogLevelConfigured;
     fetch: typeof globalThis.fetch;
     private _appConn;
     private _apiConn;
@@ -10780,6 +10813,9 @@ declare class BraintrustState {
     static deserialize(serialized: unknown, opts?: LoginOptions): BraintrustState;
     setFetch(fetch: typeof globalThis.fetch): void;
     setMaskingFunction(maskingFunction: ((value: unknown) => unknown) | null): void;
+    setDebugLogLevel(option: DebugLogLevelOption): void;
+    getDebugLogLevel(): DebugLogLevel | undefined;
+    hasDebugLogLevelOverride(): boolean;
     login(loginParams: LoginOptions & {
         forceLogin?: boolean;
     }): Promise<void>;
@@ -11028,6 +11064,19 @@ interface LoginOptions {
      * server. Defaults to false.
      */
     disableSpanCache?: boolean;
+    /**
+     * Controls internal Braintrust SDK troubleshooting output.
+     *
+     * Use `"error"`, `"warn"`, `"info"`, or `"debug"` to control how much
+     * internal SDK troubleshooting output is emitted. Use `false` to explicitly
+     * disable this output.
+     *
+     * When omitted, the SDK remains silent unless
+     * `BRAINTRUST_DEBUG_LOG_LEVEL` is set to `"error"`, `"warn"`, `"info"`, or
+     * `"debug"`. This option only affects local console output; it does not
+     * change what data is logged to Braintrust.
+     */
+    debugLogLevel?: DebugLogLevel | false;
 }
 type OptionalStateArg = {
     state?: BraintrustState;
@@ -12720,14 +12769,6 @@ declare const promptDefinitionSchema: z.ZodIntersection<z.ZodUnion<[z.ZodObject<
 }>>;
 type PromptDefinition = z.infer<typeof promptDefinitionSchema>;
 
-interface BaseFnOpts {
-    name: string;
-    slug: string;
-    description: string;
-    ifExists: IfExistsType;
-    metadata?: Record<string, unknown>;
-}
-
 type NameOrId = {
     name: string;
 } | {
@@ -12814,6 +12855,7 @@ declare class CodeFunction<Input, Output, Fn extends GenericFunction<Input, Outp
     readonly parameters?: z.ZodSchema<Input>;
     readonly returns?: z.ZodSchema<Output>;
     readonly ifExists?: IfExistsType;
+    readonly tags?: string[];
     readonly metadata?: Record<string, unknown>;
     constructor(project: Project, opts: Omit<CodeOpts<Input, Output, Fn>, "name" | "slug"> & {
         name: string;
@@ -12833,6 +12875,7 @@ declare class CodePrompt {
     readonly id?: string;
     readonly functionType?: FunctionTypeEnumType;
     readonly toolFunctions: (SavedFunctionIdType | GenericCodeFunction)[];
+    readonly tags?: string[];
     readonly metadata?: Record<string, unknown>;
     constructor(project: Project, prompt: PromptDataType, toolFunctions: (SavedFunctionIdType | GenericCodeFunction)[], opts: Omit<PromptOpts<false, false, false, false>, "name" | "slug"> & {
         name: string;
@@ -12900,6 +12943,7 @@ interface FunctionEvent {
     function_data: z.infer<typeof FunctionData>;
     function_type?: FunctionTypeEnumType;
     if_exists?: IfExistsType;
+    tags?: string[];
     metadata?: Record<string, unknown>;
 }
 declare class ProjectNameIdMap {