braintrust 3.12.0 → 3.13.0

package/dist/index.mjs

@@ -24,7 +24,7 @@ import {
   openRouterChannels,
   patchTracingChannel,
   readDisabledInstrumentationEnvConfig
-} from "./chunk-MSLBGITU.mjs";
+} from "./chunk-75IQCUB2.mjs";
 
 // src/node/config.ts
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -36,6 +36,7 @@ import * as fsSync from "node:fs";
 import * as crypto from "node:crypto";
 import { promisify } from "node:util";
 import * as zlib from "node:zlib";
+import * as dotenv from "dotenv";
 
 // src/debug-logger.ts
 var PREFIX = "[braintrust]";
@@ -5580,6 +5581,19 @@ var JSONAttachment = class extends Attachment {
    */
   constructor(data, options) {
     const { filename = "data.json", pretty = false, state } = options ?? {};
+    const deferredJsonAttachment = globalThis.__BT_DATASET_PIPELINE_DEFER_JSON_ATTACHMENT__;
+    if (deferredJsonAttachment) {
+      super({
+        data: new Blob([]),
+        filename,
+        contentType: "application/json",
+        state
+      });
+      return deferredJsonAttachment(data, {
+        filename,
+        pretty
+      });
+    }
     const jsonString = pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data);
     const blob = new Blob([jsonString], { type: "application/json" });
     super({
@@ -7572,10 +7586,11 @@ async function login(options = {}) {
 async function loginToState(options = {}) {
   const {
     appUrl = isomorph_default.getEnv("BRAINTRUST_APP_URL") || "https://www.braintrust.dev",
-    apiKey = isomorph_default.getEnv("BRAINTRUST_API_KEY"),
+    apiKey: apiKeyArg,
     orgName = isomorph_default.getEnv("BRAINTRUST_ORG_NAME"),
     fetch: fetch2 = globalThis.fetch
   } = options || {};
+  const apiKey = apiKeyArg !== void 0 ? apiKeyArg : await isomorph_default.getBraintrustApiKey();
   const appPublicUrl = isomorph_default.getEnv("BRAINTRUST_APP_PUBLIC_URL") || appUrl;
   const state = new BraintrustState(options);
   state.resetLoginInfo();
@@ -8816,9 +8831,15 @@ var SpanImpl = class _SpanImpl {
       const cachedSpan = {
         input: partialRecord.input,
         output: partialRecord.output,
+        expected: partialRecord.expected,
+        error: partialRecord.error,
+        scores: partialRecord.scores,
+        metrics: partialRecord.metrics,
         metadata: partialRecord.metadata,
+        tags: partialRecord.tags,
         span_id: this._spanId,
         span_parents: this._spanParents,
+        is_root: this._spanId === this._rootSpanId,
         span_attributes: partialRecord.span_attributes
       };
       this._state.spanCache.queueWrite(
@@ -9154,6 +9175,7 @@ var Dataset2 = class extends ObjectFetcher {
     metadata,
     tags,
     output,
+    origin,
     isMerge
   }) {
     return new LazyValue(async () => {
@@ -9168,6 +9190,7 @@ var Dataset2 = class extends ObjectFetcher {
         created: !isMerge ? (/* @__PURE__ */ new Date()).toISOString() : void 0,
         //if we're merging/updating an event we will not add this ts
         metadata,
+        origin,
         ...!!isMerge ? {
           [IS_MERGE_FIELD]: true
         } : {}
@@ -9187,6 +9210,7 @@ var Dataset2 = class extends ObjectFetcher {
    * 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.
@@ -9197,7 +9221,8 @@ var Dataset2 = class extends ObjectFetcher {
     metadata,
     tags,
     id,
-    output
+    output,
+    origin
   }) {
     this.validateEvent({ metadata, expected, output, tags });
     const rowId = id || uuidv42();
@@ -9209,6 +9234,7 @@ var Dataset2 = class extends ObjectFetcher {
         metadata,
         tags,
         output,
+        origin,
         isMerge: false
       })
     );
@@ -25464,11 +25490,60 @@ function configureInstrumentation(config) {
 }
 
 // src/node/config.ts
+var BRAINTRUST_ENV_SEARCH_PARENT_LIMIT = 64;
 function configureNode() {
   isomorph_default.buildType = "node";
   isomorph_default.getRepoInfo = getRepoInfo;
   isomorph_default.getPastNAncestors = getPastNAncestors;
-  isomorph_default.getEnv = (name) => process.env[name];
+  isomorph_default.getEnv = (name) => {
+    const value = process.env[name];
+    return name === "BRAINTRUST_API_KEY" && !value?.trim() ? void 0 : value;
+  };
+  isomorph_default.getBraintrustApiKey = async () => {
+    const value = process.env.BRAINTRUST_API_KEY;
+    if (value?.trim()) {
+      return value;
+    }
+    const envPaths = [];
+    for (let dir2 = process.cwd(), depth = 0; depth <= BRAINTRUST_ENV_SEARCH_PARENT_LIMIT; dir2 = path.dirname(dir2), depth++) {
+      envPaths.push(path.join(dir2, ".env.braintrust"));
+      if (path.dirname(dir2) === dir2) {
+        break;
+      }
+    }
+    const pending = /* @__PURE__ */ new Map();
+    envPaths.forEach((envPath, index) => {
+      pending.set(
+        index,
+        fs.readFile(envPath, "utf8").then(
+          (contents) => ({ contents, envPath, index }),
+          (error) => ({ error, envPath, index })
+        )
+      );
+    });
+    const results = [];
+    let nearestUnresolvedIndex = 0;
+    while (pending.size > 0) {
+      const result = await Promise.race(pending.values());
+      pending.delete(result.index);
+      results[result.index] = result;
+      while (results[nearestUnresolvedIndex]) {
+        const nearestResult = results[nearestUnresolvedIndex];
+        if ("contents" in nearestResult) {
+          const parsed = dotenv.parse(nearestResult.contents);
+          const apiKey = parsed.BRAINTRUST_API_KEY;
+          return apiKey?.trim() ? apiKey : void 0;
+        }
+        const e = nearestResult.error;
+        if (typeof e === "object" && e !== null && "code" in e && e.code === "ENOENT") {
+          nearestUnresolvedIndex++;
+          continue;
+        }
+        return void 0;
+      }
+    }
+    return void 0;
+  };
   isomorph_default.getCallerLocation = getCallerLocation;
   isomorph_default.newAsyncLocalStorage = () => new AsyncLocalStorage();
   isomorph_default.newTracingChannel = (nameOrChannels) => diagnostics_channel.tracingChannel(nameOrChannels);
@@ -25522,6 +25597,7 @@ __export(exports_exports, {
   DEFAULT_FETCH_BATCH_SIZE: () => DEFAULT_FETCH_BATCH_SIZE,
   DEFAULT_MAX_REQUEST_SIZE: () => DEFAULT_MAX_REQUEST_SIZE,
   Dataset: () => Dataset2,
+  DatasetPipeline: () => DatasetPipeline,
   ERR_PERMALINK: () => ERR_PERMALINK,
   Eval: () => Eval,
   EvalResultWithSummary: () => EvalResultWithSummary,
@@ -28780,10 +28856,12 @@ function formatExperimentSummary(summary) {
 // src/wrappers/shared/flush.ts
 async function summarizeAndFlush(experiment, options) {
   const shouldDisplay = options.displaySummary ?? true;
-  const summary = await experiment.summarize();
-  if (shouldDisplay) {
-    console.log(formatExperimentSummary(summary));
+  if (!shouldDisplay) {
+    await experiment.flush();
+    return;
   }
+  const summary = await experiment.summarize();
+  console.log(formatExperimentSummary(summary));
 }
 
 // src/wrappers/vitest/flush-manager.ts
@@ -30647,8 +30725,12 @@ var waterfall$1 = awaitify(waterfall);
 
 // src/trace.ts
 var SpanFetcher = class _SpanFetcher extends ObjectFetcher {
-  constructor(objectType, _objectId, rootSpanId, _state, spanTypeFilter) {
-    const filterExpr = _SpanFetcher.buildFilter(rootSpanId, spanTypeFilter);
+  constructor(objectType, _objectId, rootSpanId, _state, spanTypeFilter, includeScorers = false) {
+    const filterExpr = _SpanFetcher.buildFilter(
+      rootSpanId,
+      spanTypeFilter,
+      includeScorers
+    );
     super(objectType, void 0, void 0, {
       filter: filterExpr
     });
@@ -30657,16 +30739,17 @@ var SpanFetcher = class _SpanFetcher extends ObjectFetcher {
     this._state = _state;
     this.spanTypeFilter = spanTypeFilter;
   }
-  static buildFilter(rootSpanId, spanTypeFilter) {
+  static buildFilter(rootSpanId, spanTypeFilter, includeScorers = false) {
     const children = [
       // Base filter: root_span_id = 'value'
       {
         op: "eq",
         left: { op: "ident", name: ["root_span_id"] },
         right: { op: "literal", value: rootSpanId }
-      },
-      // Exclude span_attributes.purpose = 'score'
-      {
+      }
+    ];
+    if (!includeScorers) {
+      children.push({
         op: "or",
         children: [
           {
@@ -30679,8 +30762,8 @@ var SpanFetcher = class _SpanFetcher extends ObjectFetcher {
             right: { op: "literal", value: "scorer" }
           }
         ]
-      }
-    ];
+      });
+    }
     if (spanTypeFilter && spanTypeFilter.length > 0) {
       children.push({
         op: "in",
@@ -30706,35 +30789,49 @@ var CachedSpanFetcher = class {
   fetchFn;
   constructor(objectTypeOrFetchFn, objectId, rootSpanId, getState) {
     if (typeof objectTypeOrFetchFn === "function") {
-      this.fetchFn = objectTypeOrFetchFn;
+      this.fetchFn = (spanType) => objectTypeOrFetchFn(spanType);
     } else {
       const objectType = objectTypeOrFetchFn;
-      this.fetchFn = async (spanType) => {
+      this.fetchFn = async (spanType, includeScorers) => {
         const state = await getState();
         const fetcher = new SpanFetcher(
           objectType,
           objectId,
           rootSpanId,
           state,
-          spanType
+          spanType,
+          includeScorers
         );
         const rows = await fetcher.fetchedData();
-        return rows.filter((row) => row.span_attributes?.purpose !== "scorer").map((row) => ({
+        return rows.map((row) => ({
           input: row.input,
           output: row.output,
+          expected: row.expected,
+          error: row.error,
+          scores: row.scores,
+          metrics: row.metrics,
           metadata: row.metadata,
           span_id: row.span_id,
           span_parents: row.span_parents,
+          is_root: row.is_root,
           span_attributes: row.span_attributes,
           id: row.id,
           _xact_id: row._xact_id,
           _pagination_key: row._pagination_key,
-          root_span_id: row.root_span_id
+          root_span_id: row.root_span_id,
+          created: row.created,
+          tags: row.tags
         }));
       };
     }
   }
-  async getSpans({ spanType } = {}) {
+  async getSpans({
+    spanType,
+    includeScorers = false
+  } = {}) {
+    if (includeScorers) {
+      return this.fetchFn(spanType, true);
+    }
     if (this.allFetched) {
       return this.getFromCache(spanType);
     }
@@ -30751,7 +30848,7 @@ var CachedSpanFetcher = class {
     return this.getFromCache(spanType);
   }
   async fetchSpans(spanType) {
-    const spans = await this.fetchFn(spanType);
+    const spans = await this.fetchFn(spanType, false);
     for (const span of spans) {
       const type = span.span_attributes?.type ?? "";
       const existing = this.spanCache.get(type) ?? [];
@@ -30829,10 +30926,13 @@ var LocalTrace = class {
    * First checks the local span cache for recently logged spans, then falls
    * back to CachedSpanFetcher which handles BTQL fetching and caching.
    */
-  async getSpans({ spanType } = {}) {
+  async getSpans({
+    spanType,
+    includeScorers = false
+  } = {}) {
     const cachedSpans = this.state.spanCache.getByRootSpanId(this.rootSpanId);
     if (cachedSpans && cachedSpans.length > 0) {
-      let spans = cachedSpans.filter(
+      let spans = includeScorers ? cachedSpans : cachedSpans.filter(
         (span) => span.span_attributes?.purpose !== "scorer"
       );
       if (spanType && spanType.length > 0) {
@@ -30843,13 +30943,19 @@ var LocalTrace = class {
       return spans.map((span) => ({
         input: span.input,
         output: span.output,
+        expected: span.expected,
+        error: span.error,
+        scores: span.scores,
+        metrics: span.metrics,
         metadata: span.metadata,
         span_id: span.span_id,
         span_parents: span.span_parents,
-        span_attributes: span.span_attributes
+        is_root: span.is_root,
+        span_attributes: span.span_attributes,
+        tags: span.tags
       }));
     }
-    return this.cachedFetcher.getSpans({ spanType });
+    return this.cachedFetcher.getSpans({ spanType, includeScorers });
   }
   /**
    * Get the thread (preprocessed messages) for this trace.
@@ -32038,6 +32144,34 @@ var defaultReporter = {
   }
 };
 
+// src/dataset-pipeline.ts
+function DatasetPipeline(definition) {
+  if (!globalThis.__braintrust_dataset_pipelines) {
+    globalThis.__braintrust_dataset_pipelines = [];
+  }
+  const storedDefinition = {
+    name: definition.name,
+    source: {
+      projectId: definition.source.projectId,
+      projectName: definition.source.projectName,
+      orgName: definition.source.orgName,
+      filter: definition.source.filter,
+      scope: definition.source.scope ?? "span"
+    },
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions, @typescript-eslint/no-explicit-any
+    transform: definition.transform,
+    target: {
+      projectId: definition.target.projectId,
+      projectName: definition.target.projectName,
+      orgName: definition.target.orgName,
+      datasetName: definition.target.datasetName,
+      description: definition.target.description,
+      metadata: definition.target.metadata
+    }
+  };
+  globalThis.__braintrust_dataset_pipelines.push(storedDefinition);
+}
+
 // src/framework2.ts
 import { z as z12 } from "zod/v3";
 var currentFilename = typeof __filename !== "undefined" ? __filename : "unknown";
@@ -32577,6 +32711,7 @@ export {
   DEFAULT_FETCH_BATCH_SIZE,
   DEFAULT_MAX_REQUEST_SIZE,
   Dataset2 as Dataset,
+  DatasetPipeline,
   ERR_PERMALINK,
   Eval,
   EvalResultWithSummary,

package/dist/instrumentation/index.d.mts

@@ -3487,6 +3487,26 @@ declare const GitMetadataSettings: z.ZodObject<{
     fields?: ("dirty" | "tag" | "commit" | "branch" | "author_name" | "author_email" | "commit_message" | "commit_time" | "git_diff")[] | undefined;
 }>;
 type GitMetadataSettingsType = z.infer<typeof GitMetadataSettings>;
+declare const ObjectReference$1: z.ZodObject<{
+    object_type: z.ZodEnum<["project_logs", "experiment", "dataset", "prompt", "function", "prompt_session"]>;
+    object_id: z.ZodString;
+    id: z.ZodString;
+    _xact_id: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNull]>>;
+    created: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNull]>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    object_type: "function" | "experiment" | "dataset" | "prompt" | "prompt_session" | "project_logs";
+    object_id: string;
+    created?: string | null | undefined;
+    _xact_id?: string | null | undefined;
+}, {
+    id: string;
+    object_type: "function" | "experiment" | "dataset" | "prompt" | "prompt_session" | "project_logs";
+    object_id: string;
+    created?: string | null | undefined;
+    _xact_id?: string | null | undefined;
+}>;
+type ObjectReferenceType$1 = z.infer<typeof ObjectReference$1>;
 declare const Prompt$1: z.ZodObject<{
     id: z.ZodString;
     _xact_id: z.ZodString;
@@ -6322,6 +6342,7 @@ declare const ObjectReference: z.ZodObject<{
     created?: string | null | undefined;
     _xact_id?: string | null | undefined;
 }>;
+type ObjectReferenceType = z.infer<typeof ObjectReference>;
 
 type IdField = {
     id: string;
@@ -6342,7 +6363,7 @@ type OtherExperimentLogFields = {
     metadata: Record<string, unknown>;
     metrics: Record<string, unknown>;
     datasetRecordId: string;
-    origin: z.infer<typeof ObjectReference>;
+    origin: ObjectReferenceType;
     span_attributes: Record<string, unknown>;
     [ASYNC_SCORING_CONTROL_FIELD]: AsyncScoringControlType;
     [MERGE_PATHS_FIELD]: string[][];
@@ -6384,6 +6405,7 @@ type DatasetEvent = {
     tags?: string[];
     metadata?: unknown;
     created?: string;
+    origin?: ObjectReferenceType;
     id: string;
     dataset_id: string;
 } & ({
@@ -6775,9 +6797,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;
@@ -7310,6 +7338,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;
@@ -7480,7 +7515,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;
     /**
@@ -7719,17 +7754,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$1;
     }): string;
     /**
      * Update fields of a single record in the dataset. The updated fields will be batched and uploaded behind the scenes.

package/dist/instrumentation/index.d.ts

@@ -3487,6 +3487,26 @@ declare const GitMetadataSettings: z.ZodObject<{
     fields?: ("dirty" | "tag" | "commit" | "branch" | "author_name" | "author_email" | "commit_message" | "commit_time" | "git_diff")[] | undefined;
 }>;
 type GitMetadataSettingsType = z.infer<typeof GitMetadataSettings>;
+declare const ObjectReference$1: z.ZodObject<{
+    object_type: z.ZodEnum<["project_logs", "experiment", "dataset", "prompt", "function", "prompt_session"]>;
+    object_id: z.ZodString;
+    id: z.ZodString;
+    _xact_id: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNull]>>;
+    created: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNull]>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    object_type: "function" | "experiment" | "dataset" | "prompt" | "prompt_session" | "project_logs";
+    object_id: string;
+    created?: string | null | undefined;
+    _xact_id?: string | null | undefined;
+}, {
+    id: string;
+    object_type: "function" | "experiment" | "dataset" | "prompt" | "prompt_session" | "project_logs";
+    object_id: string;
+    created?: string | null | undefined;
+    _xact_id?: string | null | undefined;
+}>;
+type ObjectReferenceType$1 = z.infer<typeof ObjectReference$1>;
 declare const Prompt$1: z.ZodObject<{
     id: z.ZodString;
     _xact_id: z.ZodString;
@@ -6322,6 +6342,7 @@ declare const ObjectReference: z.ZodObject<{
     created?: string | null | undefined;
     _xact_id?: string | null | undefined;
 }>;
+type ObjectReferenceType = z.infer<typeof ObjectReference>;
 
 type IdField = {
     id: string;
@@ -6342,7 +6363,7 @@ type OtherExperimentLogFields = {
     metadata: Record<string, unknown>;
     metrics: Record<string, unknown>;
     datasetRecordId: string;
-    origin: z.infer<typeof ObjectReference>;
+    origin: ObjectReferenceType;
     span_attributes: Record<string, unknown>;
     [ASYNC_SCORING_CONTROL_FIELD]: AsyncScoringControlType;
     [MERGE_PATHS_FIELD]: string[][];
@@ -6384,6 +6405,7 @@ type DatasetEvent = {
     tags?: string[];
     metadata?: unknown;
     created?: string;
+    origin?: ObjectReferenceType;
     id: string;
     dataset_id: string;
 } & ({
@@ -6775,9 +6797,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;
@@ -7310,6 +7338,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;
@@ -7480,7 +7515,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;
     /**
@@ -7719,17 +7754,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$1;
     }): string;
     /**
      * Update fields of a single record in the dataset. The updated fields will be batched and uploaded behind the scenes.

package/dist/instrumentation/index.js

@@ -125,6 +125,7 @@ var iso = {
   getRepoInfo: async (_settings) => void 0,
   getPastNAncestors: async () => [],
   getEnv: (_name) => void 0,
+  getBraintrustApiKey: async () => void 0,
   getCallerLocation: () => void 0,
   newAsyncLocalStorage: () => new DefaultAsyncLocalStorage(),
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -6548,10 +6549,11 @@ function initLogger(options = {}) {
 async function loginToState(options = {}) {
   const {
     appUrl = isomorph_default.getEnv("BRAINTRUST_APP_URL") || "https://www.braintrust.dev",
-    apiKey = isomorph_default.getEnv("BRAINTRUST_API_KEY"),
+    apiKey: apiKeyArg,
     orgName = isomorph_default.getEnv("BRAINTRUST_ORG_NAME"),
     fetch: fetch2 = globalThis.fetch
   } = options || {};
+  const apiKey = apiKeyArg !== void 0 ? apiKeyArg : await isomorph_default.getBraintrustApiKey();
   const appPublicUrl = isomorph_default.getEnv("BRAINTRUST_APP_PUBLIC_URL") || appUrl;
   const state = new BraintrustState(options);
   state.resetLoginInfo();
@@ -7482,9 +7484,15 @@ var SpanImpl = class _SpanImpl {
       const cachedSpan = {
         input: partialRecord.input,
         output: partialRecord.output,
+        expected: partialRecord.expected,
+        error: partialRecord.error,
+        scores: partialRecord.scores,
+        metrics: partialRecord.metrics,
         metadata: partialRecord.metadata,
+        tags: partialRecord.tags,
         span_id: this._spanId,
         span_parents: this._spanParents,
+        is_root: this._spanId === this._rootSpanId,
         span_attributes: partialRecord.span_attributes
       };
       this._state.spanCache.queueWrite(
@@ -7820,6 +7828,7 @@ var Dataset2 = class extends ObjectFetcher {
     metadata,
     tags,
     output,
+    origin,
     isMerge
   }) {
     return new LazyValue(async () => {
@@ -7834,6 +7843,7 @@ var Dataset2 = class extends ObjectFetcher {
         created: !isMerge ? (/* @__PURE__ */ new Date()).toISOString() : void 0,
         //if we're merging/updating an event we will not add this ts
         metadata,
+        origin,
         ...!!isMerge ? {
           [IS_MERGE_FIELD]: true
         } : {}
@@ -7853,6 +7863,7 @@ var Dataset2 = class extends ObjectFetcher {
    * 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.
@@ -7863,7 +7874,8 @@ var Dataset2 = class extends ObjectFetcher {
     metadata,
     tags,
     id,
-    output
+    output,
+    origin
   }) {
     this.validateEvent({ metadata, expected, output, tags });
     const rowId = id || (0, import_uuid2.v4)();
@@ -7875,6 +7887,7 @@ var Dataset2 = class extends ObjectFetcher {
         metadata,
         tags,
         output,
+        origin,
         isMerge: false
       })
     );