braintrust 3.11.0 → 3.13.0

package/README.md

@@ -61,40 +61,40 @@ Use a bundler plugin:
 Vite:
 
 ```ts
-import { vitePlugin } from "braintrust/vite";
+import { braintrustVitePlugin } from "braintrust/vite";
 
 export default {
-  plugins: [vitePlugin()],
+  plugins: [braintrustVitePlugin()],
 };
 ```
 
 Webpack:
 
 ```js
-const { webpackPlugin } = require("braintrust/webpack");
+const { braintrustWebpackPlugin } = require("braintrust/webpack");
 
 module.exports = {
-  plugins: [webpackPlugin()],
+  plugins: [braintrustWebpackPlugin()],
 };
 ```
 
 esbuild:
 
 ```ts
-import { esbuildPlugin } from "braintrust/esbuild";
+import { braintrustEsbuildPlugin } from "braintrust/esbuild";
 
 await esbuild.build({
-  plugins: [esbuildPlugin()],
+  plugins: [braintrustEsbuildPlugin()],
 });
 ```
 
 Rollup:
 
 ```ts
-import { rollupPlugin } from "braintrust/rollup";
+import { braintrustRollupPlugin } from "braintrust/rollup";
 
 export default {
-  plugins: [rollupPlugin()],
+  plugins: [braintrustRollupPlugin()],
 };
 ```
 

package/dev/dist/index.d.mts

@@ -118,6 +118,7 @@ declare const ObjectReference$1: z.ZodObject<{
     created?: string | null | undefined;
     _xact_id?: string | null | undefined;
 }>;
+type ObjectReferenceType$1 = z.infer<typeof ObjectReference$1>;
 
 type IdField = {
     id: string;
@@ -138,7 +139,7 @@ type OtherExperimentLogFields = {
     metadata: Record<string, unknown>;
     metrics: Record<string, unknown>;
     datasetRecordId: string;
-    origin: z.infer<typeof ObjectReference$1>;
+    origin: ObjectReferenceType$1;
     span_attributes: Record<string, unknown>;
     [ASYNC_SCORING_CONTROL_FIELD]: AsyncScoringControlType;
     [MERGE_PATHS_FIELD]: string[][];
@@ -180,6 +181,7 @@ type DatasetEvent = {
     tags?: string[];
     metadata?: unknown;
     created?: string;
+    origin?: ObjectReferenceType$1;
     id: string;
     dataset_id: string;
 } & ({
@@ -8921,9 +8923,15 @@ declare class ParametersCache {
 interface CachedSpan {
     input?: unknown;
     output?: unknown;
+    expected?: unknown;
+    error?: unknown;
+    scores?: Record<string, unknown>;
+    metrics?: Record<string, unknown>;
     metadata?: Record<string, unknown>;
+    tags?: string[];
     span_id: string;
     span_parents?: string[];
+    is_root?: boolean | null;
     span_attributes?: {
         name?: string;
         type?: string;
@@ -11212,6 +11220,13 @@ interface LogOptions<IsAsyncFlush> {
     linkArgs?: LinkArgs;
 }
 type PromiseUnless<B, R> = B extends true ? R : Promise<Awaited<R>>;
+type DatasetPipelineDeferredJSONAttachmentHook = (data: unknown, options?: {
+    filename?: string;
+    pretty?: boolean;
+}) => object;
+declare global {
+    var __BT_DATASET_PIPELINE_DEFER_JSON_ATTACHMENT__: DatasetPipelineDeferredJSONAttachmentHook | undefined;
+}
 interface ParentSpanIds {
     spanId: string;
     rootSpanId: string;
@@ -11385,7 +11400,7 @@ interface LoginOptions {
      */
     appUrl?: string;
     /**
-     * The API key to use. If the parameter is not specified, will try to use the `BRAINTRUST_API_KEY` environment variable.
+     * The API key to use. If the parameter is not specified, will try to use the `BRAINTRUST_API_KEY` environment variable. In Node.js, if that is unset, will try the nearest `.env.braintrust` file in the current working directory or parent directories.
      */
     apiKey?: string;
     /**
@@ -11660,17 +11675,19 @@ declare class Dataset<IsLegacyDataset extends boolean = typeof DEFAULT_IS_LEGACY
      * about anything else that's relevant, that you can use to help find and analyze examples later. For example, you could log the
      * `prompt`, example's `id`, or anything else that would be useful to slice/dice later. The values in `metadata` can be any
      * JSON-serializable type, but its keys must be strings.
+     * @param event.origin (Optional) a reference to the source object this dataset record was derived from.
      * @param event.id (Optional) a unique identifier for the event. If you don't provide one, Braintrust will generate one for you.
      * @param event.output: (Deprecated) The output of your application. Use `expected` instead.
      * @returns The `id` of the logged record.
      */
-    insert({ input, expected, metadata, tags, id, output, }: {
+    insert({ input, expected, metadata, tags, id, output, origin, }: {
         readonly input?: unknown;
         readonly expected?: unknown;
         readonly tags?: string[];
         readonly metadata?: Record<string, unknown>;
         readonly id?: string;
         readonly output?: unknown;
+        readonly origin?: ObjectReferenceType;
     }): string;
     /**
      * Update fields of a single record in the dataset. The updated fields will be batched and uploaded behind the scenes.
@@ -11952,6 +11969,10 @@ interface GetThreadOptions {
      */
     preprocessor?: string;
 }
+interface GetSpansOptions {
+    spanType?: string[];
+    includeScorers?: boolean;
+}
 /**
  * Interface for trace objects that can be used by scorers.
  * Both the SDK's LocalTrace class and the API wrapper's WrapperTrace implement this.
@@ -11962,9 +11983,7 @@ interface Trace {
         object_id: string;
         root_span_id: string;
     };
-    getSpans(options?: {
-        spanType?: string[];
-    }): Promise<SpanData[]>;
+    getSpans(options?: GetSpansOptions): Promise<SpanData[]>;
     /**
      * Get the thread (preprocessed messages) for this trace.
      * Uses the project default preprocessor, falling back to the global "thread" preprocessor.
@@ -13557,7 +13576,7 @@ interface Evaluator<Input, Output, Expected, Metadata extends BaseMetadata = Def
      */
     baseExperimentId?: string;
     /**
-     * Optional settings for collecting git metadata. By default, will collect all git metadata fields allowed in org-level settings.
+     * Optional settings for collecting git metadata. By default, Braintrust collects the git metadata fields allowed by your organization's git metadata settings. If those settings are absent, git metadata is not collected unless this option is set.
      */
     gitMetadataSettings?: GitMetadataSettingsType;
     /**

package/dev/dist/index.d.ts

@@ -118,6 +118,7 @@ declare const ObjectReference$1: z.ZodObject<{
     created?: string | null | undefined;
     _xact_id?: string | null | undefined;
 }>;
+type ObjectReferenceType$1 = z.infer<typeof ObjectReference$1>;
 
 type IdField = {
     id: string;
@@ -138,7 +139,7 @@ type OtherExperimentLogFields = {
     metadata: Record<string, unknown>;
     metrics: Record<string, unknown>;
     datasetRecordId: string;
-    origin: z.infer<typeof ObjectReference$1>;
+    origin: ObjectReferenceType$1;
     span_attributes: Record<string, unknown>;
     [ASYNC_SCORING_CONTROL_FIELD]: AsyncScoringControlType;
     [MERGE_PATHS_FIELD]: string[][];
@@ -180,6 +181,7 @@ type DatasetEvent = {
     tags?: string[];
     metadata?: unknown;
     created?: string;
+    origin?: ObjectReferenceType$1;
     id: string;
     dataset_id: string;
 } & ({
@@ -8921,9 +8923,15 @@ declare class ParametersCache {
 interface CachedSpan {
     input?: unknown;
     output?: unknown;
+    expected?: unknown;
+    error?: unknown;
+    scores?: Record<string, unknown>;
+    metrics?: Record<string, unknown>;
     metadata?: Record<string, unknown>;
+    tags?: string[];
     span_id: string;
     span_parents?: string[];
+    is_root?: boolean | null;
     span_attributes?: {
         name?: string;
         type?: string;
@@ -11212,6 +11220,13 @@ interface LogOptions<IsAsyncFlush> {
     linkArgs?: LinkArgs;
 }
 type PromiseUnless<B, R> = B extends true ? R : Promise<Awaited<R>>;
+type DatasetPipelineDeferredJSONAttachmentHook = (data: unknown, options?: {
+    filename?: string;
+    pretty?: boolean;
+}) => object;
+declare global {
+    var __BT_DATASET_PIPELINE_DEFER_JSON_ATTACHMENT__: DatasetPipelineDeferredJSONAttachmentHook | undefined;
+}
 interface ParentSpanIds {
     spanId: string;
     rootSpanId: string;
@@ -11385,7 +11400,7 @@ interface LoginOptions {
      */
     appUrl?: string;
     /**
-     * The API key to use. If the parameter is not specified, will try to use the `BRAINTRUST_API_KEY` environment variable.
+     * The API key to use. If the parameter is not specified, will try to use the `BRAINTRUST_API_KEY` environment variable. In Node.js, if that is unset, will try the nearest `.env.braintrust` file in the current working directory or parent directories.
      */
     apiKey?: string;
     /**
@@ -11660,17 +11675,19 @@ declare class Dataset<IsLegacyDataset extends boolean = typeof DEFAULT_IS_LEGACY
      * about anything else that's relevant, that you can use to help find and analyze examples later. For example, you could log the
      * `prompt`, example's `id`, or anything else that would be useful to slice/dice later. The values in `metadata` can be any
      * JSON-serializable type, but its keys must be strings.
+     * @param event.origin (Optional) a reference to the source object this dataset record was derived from.
      * @param event.id (Optional) a unique identifier for the event. If you don't provide one, Braintrust will generate one for you.
      * @param event.output: (Deprecated) The output of your application. Use `expected` instead.
      * @returns The `id` of the logged record.
      */
-    insert({ input, expected, metadata, tags, id, output, }: {
+    insert({ input, expected, metadata, tags, id, output, origin, }: {
         readonly input?: unknown;
         readonly expected?: unknown;
         readonly tags?: string[];
         readonly metadata?: Record<string, unknown>;
         readonly id?: string;
         readonly output?: unknown;
+        readonly origin?: ObjectReferenceType;
     }): string;
     /**
      * Update fields of a single record in the dataset. The updated fields will be batched and uploaded behind the scenes.
@@ -11952,6 +11969,10 @@ interface GetThreadOptions {
      */
     preprocessor?: string;
 }
+interface GetSpansOptions {
+    spanType?: string[];
+    includeScorers?: boolean;
+}
 /**
  * Interface for trace objects that can be used by scorers.
  * Both the SDK's LocalTrace class and the API wrapper's WrapperTrace implement this.
@@ -11962,9 +11983,7 @@ interface Trace {
         object_id: string;
         root_span_id: string;
     };
-    getSpans(options?: {
-        spanType?: string[];
-    }): Promise<SpanData[]>;
+    getSpans(options?: GetSpansOptions): Promise<SpanData[]>;
     /**
      * Get the thread (preprocessed messages) for this trace.
      * Uses the project default preprocessor, falling back to the global "thread" preprocessor.
@@ -13557,7 +13576,7 @@ interface Evaluator<Input, Output, Expected, Metadata extends BaseMetadata = Def
      */
     baseExperimentId?: string;
     /**
-     * Optional settings for collecting git metadata. By default, will collect all git metadata fields allowed in org-level settings.
+     * Optional settings for collecting git metadata. By default, Braintrust collects the git metadata fields allowed by your organization's git metadata settings. If those settings are absent, git metadata is not collected unless this option is set.
      */
     gitMetadataSettings?: GitMetadataSettingsType;
     /**