braintrust 0.0.166 → 0.0.168

package/dist/index.js

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  Attachment: () => Attachment,
   BaseExperiment: () => BaseExperiment,
   BraintrustState: () => BraintrustState,
   BraintrustStream: () => BraintrustStream,
@@ -52,6 +53,7 @@ __export(src_exports, {
   SpanImpl: () => SpanImpl,
   ToolBuilder: () => ToolBuilder,
   X_CACHED_HEADER: () => X_CACHED_HEADER,
+  _exportsForTestingOnly: () => _exportsForTestingOnly,
   _internalGetGlobalState: () => _internalGetGlobalState,
   _internalSetInitialState: () => _internalSetInitialState,
   braintrustStreamChunkSchema: () => braintrustStreamChunkSchema,
@@ -679,6 +681,9 @@ var NoopSpan = class {
   async export() {
     return "";
   }
+  async permalink() {
+    return "";
+  }
   async flush() {
   }
   close(args) {
@@ -820,11 +825,11 @@ var BraintrustState = class _BraintrustState {
     state.loginReplaceApiConn(state.apiConn());
     return state;
   }
-  setFetch(fetch) {
-    this.loginParams.fetch = fetch;
-    this.fetch = fetch;
-    this._apiConn?.setFetch(fetch);
-    this._appConn?.setFetch(fetch);
+  setFetch(fetch2) {
+    this.loginParams.fetch = fetch2;
+    this.fetch = fetch2;
+    this._apiConn?.setFetch(fetch2);
+    this._appConn?.setFetch(fetch2);
   }
   async login(loginParams) {
     if (this.apiUrl && !loginParams.forceLogin) {
@@ -913,15 +918,15 @@ var HTTPConnection = class _HTTPConnection {
   token;
   headers;
   fetch;
-  constructor(base_url, fetch) {
+  constructor(base_url, fetch2) {
     this.base_url = base_url;
     this.token = null;
     this.headers = {};
     this._reset();
-    this.fetch = fetch;
+    this.fetch = fetch2;
   }
-  setFetch(fetch) {
-    this.fetch = fetch;
+  setFetch(fetch2) {
+    this.fetch = fetch2;
   }
   async ping() {
     try {
@@ -957,12 +962,14 @@ var HTTPConnection = class _HTTPConnection {
         ([k, v]) => v !== void 0 ? typeof v === "string" ? [[k, v]] : v.map((x) => [k, x]) : []
       ) : []
     ).toString();
+    const this_fetch = this.fetch;
+    const this_headers = this.headers;
     return await checkResponse(
       // Using toString() here makes it work with isomorphic fetch
-      await this.fetch(url.toString(), {
+      await this_fetch(url.toString(), {
         headers: {
           Accept: "application/json",
-          ...this.headers,
+          ...this_headers,
           ...headers
         },
         keepalive: true,
@@ -972,13 +979,16 @@ var HTTPConnection = class _HTTPConnection {
   }
   async post(path3, params, config) {
     const { headers, ...rest } = config || {};
+    const this_fetch = this.fetch;
+    const this_base_url = this.base_url;
+    const this_headers = this.headers;
     return await checkResponse(
-      await this.fetch((0, import_core._urljoin)(this.base_url, path3), {
+      await this_fetch((0, import_core._urljoin)(this_base_url, path3), {
         method: "POST",
         headers: {
           Accept: "application/json",
           "Content-Type": "application/json",
-          ...this.headers,
+          ...this_headers,
           ...headers
         },
         body: typeof params === "string" ? params : params ? JSON.stringify(params) : void 0,
@@ -1011,6 +1021,167 @@ var HTTPConnection = class _HTTPConnection {
     return await resp.json();
   }
 };
+var Attachment = class {
+  /**
+   * The object that replaces this `Attachment` at upload time.
+   */
+  reference;
+  uploader;
+  data;
+  state;
+  // For debug logging only.
+  dataDebugString;
+  /**
+   * Construct an attachment.
+   *
+   * @param data A string representing the path of the file on disk, or a
+   * `Blob`/`ArrayBuffer` with the file's contents. The caller is responsible
+   * for ensuring the file/blob/buffer is not modified until upload is complete.
+   *
+   * @param filename The desired name of the file in Braintrust after uploading.
+   * This parameter is for visualization purposes only and has no effect on
+   * attachment storage.
+   *
+   * @param contentType The MIME type of the file.
+   *
+   * @param state (Optional) For internal use.
+   */
+  constructor({ data, filename, contentType, state }) {
+    this.reference = {
+      type: import_typespecs2.BRAINTRUST_ATTACHMENT,
+      filename,
+      content_type: contentType,
+      key: newId()
+    };
+    this.state = state;
+    this.dataDebugString = typeof data === "string" ? data : "<in-memory data>";
+    this.data = this.initData(data);
+    this.uploader = this.initUploader();
+  }
+  /**
+   * On first access, (1) reads the attachment from disk if needed, (2)
+   * authenticates with the data plane to request a signed URL, (3) uploads to
+   * object store, and (4) updates the attachment.
+   *
+   * @returns The attachment status.
+   */
+  async upload() {
+    return await this.uploader.get();
+  }
+  /**
+   * A human-readable description for logging and debugging.
+   *
+   * @returns The debug object. The return type is not stable and may change in
+   * a future release.
+   */
+  debugInfo() {
+    return {
+      inputData: this.dataDebugString,
+      reference: this.reference,
+      state: this.state
+    };
+  }
+  initUploader() {
+    const doUpload = async (conn, orgId) => {
+      const requestParams = {
+        key: this.reference.key,
+        filename: this.reference.filename,
+        content_type: this.reference.content_type,
+        org_id: orgId
+      };
+      const [metadataPromiseResult, dataPromiseResult] = await Promise.allSettled([
+        conn.post("/attachment", requestParams),
+        this.data.get()
+      ]);
+      if (metadataPromiseResult.status === "rejected") {
+        const errorStr = JSON.stringify(metadataPromiseResult.reason);
+        throw new Error(
+          `Failed to request signed URL from API server: ${errorStr}`
+        );
+      }
+      if (dataPromiseResult.status === "rejected") {
+        const errorStr = JSON.stringify(dataPromiseResult.reason);
+        throw new Error(`Failed to read file: ${errorStr}`);
+      }
+      const metadataResponse = metadataPromiseResult.value;
+      const data = dataPromiseResult.value;
+      let signedUrl;
+      let headers;
+      try {
+        ({ signedUrl, headers } = import_zod2.z.object({
+          signedUrl: import_zod2.z.string().url(),
+          headers: import_zod2.z.record(import_zod2.z.string())
+        }).parse(await metadataResponse.json()));
+      } catch (error2) {
+        if (error2 instanceof import_zod2.ZodError) {
+          const errorStr = JSON.stringify(error2.flatten());
+          throw new Error(`Invalid response from API server: ${errorStr}`);
+        }
+        throw error2;
+      }
+      let objectStoreResponse;
+      try {
+        objectStoreResponse = await checkResponse(
+          await fetch(signedUrl, {
+            method: "PUT",
+            headers,
+            body: data
+          })
+        );
+      } catch (error2) {
+        if (error2 instanceof FailedHTTPResponse) {
+          throw new Error(
+            `Failed to upload attachment to object store: ${error2.status} ${error2.text} ${error2.data}`
+          );
+        }
+        throw error2;
+      }
+      return { signedUrl, metadataResponse, objectStoreResponse };
+    };
+    const errorWrapper = async () => {
+      const status = { upload_status: "done" };
+      const state = this.state ?? _globalState;
+      await state.login({});
+      const conn = state.apiConn();
+      const orgId = state.orgId ?? "";
+      try {
+        await doUpload(conn, orgId);
+      } catch (error2) {
+        status.upload_status = "error";
+        status.error_message = error2 instanceof Error ? error2.message : JSON.stringify(error2);
+      }
+      const requestParams = {
+        key: this.reference.key,
+        org_id: orgId,
+        status
+      };
+      const statusResponse = await conn.post(
+        "/attachment/status",
+        requestParams
+      );
+      if (!statusResponse.ok) {
+        const errorStr = JSON.stringify(statusResponse);
+        throw new Error(`Couldn't log attachment status: ${errorStr}`);
+      }
+      return status;
+    };
+    return new LazyValue(errorWrapper);
+  }
+  initData(data) {
+    if (typeof data === "string") {
+      const readFile2 = isomorph_default.readFile;
+      if (!readFile2) {
+        throw new Error(
+          `This platform does not support reading the filesystem. Construct the Attachment
+with a Blob/ArrayBuffer, or run the program on Node.js.`
+        );
+      }
+      return new LazyValue(async () => new Blob([await readFile2(data)]));
+    } else {
+      return new LazyValue(async () => new Blob([data]));
+    }
+  }
+};
 function logFeedbackImpl(state, parentObjectType, parentObjectId, {
   id,
   expected,
@@ -1035,7 +1206,7 @@ function logFeedbackImpl(state, parentObjectType, parentObjectId, {
     expected,
     tags
   });
-  let { metadata, ...updateEvent } = validatedEvent;
+  let { metadata, ...updateEvent } = deepCopyEvent(validatedEvent);
   updateEvent = Object.fromEntries(
     Object.entries(updateEvent).filter(([_, v]) => !isEmpty(v))
   );
@@ -1084,10 +1255,12 @@ function updateSpanImpl({
   id,
   event
 }) {
-  const updateEvent = validateAndSanitizeExperimentLogPartialArgs({
-    id,
-    ...event
-  });
+  const updateEvent = deepCopyEvent(
+    validateAndSanitizeExperimentLogPartialArgs({
+      id,
+      ...event
+    })
+  );
   const parentIds = async () => new import_core.SpanComponentsV3({
     object_type: parentObjectType,
     object_id: await parentObjectId.get()
@@ -1288,7 +1461,7 @@ var Logger = class {
    * @param event.id: (Optional) a unique identifier for the event. If you don't provide one, BrainTrust will generate one for you.
    * @param options Additional logging options
    * @param options.allowConcurrentWithSpans in rare cases where you need to log at the top level separately from spans on the logger elsewhere, set this to true.
-   * :returns: The `id` of the logged event.
+   * @returns The `id` of the logged event.
    */
   log(event, options) {
     if (this.calledStartSpan && !options?.allowConcurrentWithSpans) {
@@ -1311,7 +1484,7 @@ var Logger = class {
   /**
    * Create a new toplevel span underneath the logger. The name defaults to "root".
    *
-   * See `Span.traced` for full details.
+   * See {@link Span.traced} for full details.
    */
   traced(callback, args) {
     const { setCurrent, ...argsRest } = args ?? {};
@@ -1345,7 +1518,7 @@ var Logger = class {
    * where you cannot use callbacks. However, spans started with `startSpan` will not be marked as the "current span",
    * so `currentSpan()` and `traced()` will be no-ops. If you want to mark a span as current, use `traced` instead.
    *
-   * See `traced` for full details.
+   * See {@link traced} for full details.
    */
   startSpan(args) {
     this.calledStartSpan = true;
@@ -1385,7 +1558,7 @@ var Logger = class {
    * Update a span in the experiment using its id. It is important that you only update a span once the original span has been fully written and flushed,
    * since otherwise updates to the span may conflict with the original span.
    *
-   * @param event The event data to update the span with. Must include `id`. See `Experiment.log` for a full list of valid fields.
+   * @param event The event data to update the span with. Must include `id`. See {@link Experiment.log} for a full list of valid fields.
    */
   updateSpan(event) {
     const { id, ...eventRest } = event;
@@ -1401,7 +1574,9 @@ var Logger = class {
     });
   }
   /**
-   * Return a serialized representation of the logger that can be used to start subspans in other places. See `Span.start_span` for more details.
+   * Return a serialized representation of the logger that can be used to start subspans in other places.
+   *
+   * See {@link Span.startSpan} for more details.
    */
   async export() {
     return new import_core.SpanComponentsV3({
@@ -1441,6 +1616,7 @@ var BackgroundLogger = class _BackgroundLogger {
   activeFlush = Promise.resolve();
   activeFlushResolved = true;
   activeFlushError = void 0;
+  onFlushError;
   syncFlush = false;
   // 6 MB for the AWS lambda gateway (from our own testing).
   maxRequestSize = 6 * 1024 * 1024;
@@ -1504,6 +1680,7 @@ var BackgroundLogger = class _BackgroundLogger {
         await this.flush();
       });
     }
+    this.onFlushError = opts.onFlushError;
   }
   log(items) {
     const [addedItems, droppedItems] = (() => {
@@ -1535,14 +1712,16 @@ var BackgroundLogger = class _BackgroundLogger {
     if (this.activeFlushError) {
       const err = this.activeFlushError;
       this.activeFlushError = void 0;
-      throw err;
+      if (this.syncFlush) {
+        throw err;
+      }
     }
   }
   async flushOnce(args) {
     const batchSize = args?.batchSize ?? this.defaultBatchSize;
     const wrappedItems = this.items;
     this.items = [];
-    const allItems = await this.unwrapLazyValues(wrappedItems);
+    const [allItems, attachments] = await this.unwrapLazyValues(wrappedItems);
     if (allItems.length === 0) {
       return;
     }
@@ -1574,6 +1753,23 @@ var BackgroundLogger = class _BackgroundLogger {
         );
       }
     }
+    const attachmentErrors = [];
+    for (const attachment of attachments) {
+      try {
+        const result = await attachment.upload();
+        if (result.upload_status === "error" && result.error_message) {
+          attachmentErrors.push(new Error(result.error_message));
+        }
+      } catch (error2) {
+        attachmentErrors.push(error2);
+      }
+    }
+    if (attachmentErrors.length > 0) {
+      throw new AggregateError(
+        attachmentErrors,
+        `Encountered the following errors while uploading attachments:`
+      );
+    }
     if (this.items.length > 0) {
       await this.flushOnce(args);
     }
@@ -1581,8 +1777,10 @@ var BackgroundLogger = class _BackgroundLogger {
   async unwrapLazyValues(wrappedItems) {
     for (let i = 0; i < this.numTries; ++i) {
       try {
-        const itemPromises = wrappedItems.map((x) => x.get());
-        return (0, import_core.mergeRowBatch)(await Promise.all(itemPromises));
+        const items = await Promise.all(wrappedItems.map((x) => x.get()));
+        const attachments = [];
+        items.forEach((item) => extractAttachments(item, attachments));
+        return [(0, import_core.mergeRowBatch)(items), attachments];
       } catch (e) {
         let errmsg = "Encountered error when constructing records to flush";
         const isRetrying = i + 1 < this.numTries;
@@ -1590,7 +1788,10 @@ var BackgroundLogger = class _BackgroundLogger {
           errmsg += ". Retrying";
         }
         console.warn(errmsg);
-        if (!isRetrying && this.syncFlush) {
+        if (!isRetrying) {
+          console.warn(
+            `Failed to construct log records to flush after ${this.numTries} attempts. Dropping batch`
+          );
           throw e;
         } else {
           console.warn(e);
@@ -1598,10 +1799,7 @@ var BackgroundLogger = class _BackgroundLogger {
         }
       }
     }
-    console.warn(
-      `Failed to construct log records to flush after ${this.numTries} attempts. Dropping batch`
-    );
-    return [];
+    throw new Error("Impossible");
   }
   async submitLogsRequest(items) {
     const conn = await this.apiConn.get();
@@ -1617,16 +1815,14 @@ var BackgroundLogger = class _BackgroundLogger {
       let error2 = void 0;
       try {
         await conn.post_json("logs3", dataStr);
-      } catch (e) {
+      } catch {
         try {
           const legacyDataS = (0, import_core.constructJsonArray)(
-            items.map(
-              (r) => JSON.stringify((0, import_core.makeLegacyEvent)(JSON.parse(r)))
-            )
+            items.map((r) => JSON.stringify((0, import_core.makeLegacyEvent)(JSON.parse(r))))
           );
           await conn.post_json("logs", legacyDataS);
-        } catch (e2) {
-          error2 = e2;
+        } catch (e) {
+          error2 = e;
         }
       }
       if (error2 === void 0) {
@@ -1650,7 +1846,10 @@ Error: ${errorText}`;
         });
         this.logFailedPayloadsDir();
       }
-      if (!isRetrying && this.syncFlush) {
+      if (!isRetrying) {
+        console.warn(
+          `log request failed after ${this.numTries} retries. Dropping batch`
+        );
         throw new Error(errMsg);
       } else {
         console.warn(errMsg);
@@ -1659,10 +1858,6 @@ Error: ${errorText}`;
         }
       }
     }
-    console.warn(
-      `log request failed after ${this.numTries} retries. Dropping batch`
-    );
-    return;
   }
   registerDroppedItemCount(numItems) {
     if (numItems <= 0) {
@@ -1690,15 +1885,17 @@ Error: ${errorText}`;
       return;
     }
     try {
-      const allItems = await this.unwrapLazyValues(wrappedItems);
+      const [allItems, allAttachments] = await this.unwrapLazyValues(wrappedItems);
       const dataStr = constructLogs3Data(
         allItems.map((x) => JSON.stringify(x))
       );
+      const attachmentStr = JSON.stringify(
+        allAttachments.map((a) => a.debugInfo())
+      );
+      const payload = `{"data": ${dataStr}, "attachments": ${attachmentStr}}
+`;
       for (const payloadDir of publishPayloadsDir) {
-        await _BackgroundLogger.writePayloadToDir({
-          payloadDir,
-          payload: dataStr
-        });
+        await _BackgroundLogger.writePayloadToDir({ payloadDir, payload });
       }
     } catch (e) {
       console.error(e);
@@ -1737,6 +1934,13 @@ Error: ${errorText}`;
         try {
           await this.flushOnce();
         } catch (err) {
+          if (err instanceof AggregateError) {
+            for (const e of err.errors) {
+              this.onFlushError?.(e);
+            }
+          } else {
+            this.onFlushError?.(err);
+          }
           this.activeFlushError = err;
         } finally {
           this.activeFlushResolved = true;
@@ -1779,7 +1983,7 @@ function init(projectOrOptions, optionalOptions) {
     apiKey,
     orgName,
     forceLogin,
-    fetch,
+    fetch: fetch2,
     metadata,
     gitMetadataSettings,
     projectId,
@@ -1797,7 +2001,7 @@ function init(projectOrOptions, optionalOptions) {
     }
     const lazyMetadata2 = new LazyValue(
       async () => {
-        await state.login({ apiKey, appUrl, orgName, fetch, forceLogin });
+        await state.login({ apiKey, appUrl, orgName, fetch: fetch2, forceLogin });
         const args = {
           project_name: project,
           project_id: projectId,
@@ -1968,7 +2172,7 @@ function initDataset(projectOrOptions, optionalOptions) {
     appUrl,
     apiKey,
     orgName,
-    fetch,
+    fetch: fetch2,
     forceLogin,
     projectId,
     metadata,
@@ -1982,7 +2186,7 @@ function initDataset(projectOrOptions, optionalOptions) {
         orgName,
         apiKey,
         appUrl,
-        fetch,
+        fetch: fetch2,
         forceLogin
       });
       const args = {
@@ -2064,7 +2268,7 @@ function initLogger(options = {}) {
     apiKey,
     orgName,
     forceLogin,
-    fetch,
+    fetch: fetch2,
     state: stateArg
   } = options || {};
   const computeMetadataArgs = {
@@ -2079,7 +2283,7 @@ function initLogger(options = {}) {
         apiKey,
         appUrl,
         forceLogin,
-        fetch
+        fetch: fetch2
       });
       return computeLoggerMetadata(state, computeMetadataArgs);
     }
@@ -2103,7 +2307,7 @@ async function loadPrompt({
   appUrl,
   apiKey,
   orgName,
-  fetch,
+  fetch: fetch2,
   forceLogin,
   state: stateArg
 }) {
@@ -2118,7 +2322,7 @@ async function loadPrompt({
     orgName,
     apiKey,
     appUrl,
-    fetch,
+    fetch: fetch2,
     forceLogin
   });
   const args = {
@@ -2169,7 +2373,7 @@ async function loginToState(options = {}) {
     appUrl = isomorph_default.getEnv("BRAINTRUST_APP_URL") || "https://www.braintrust.dev",
     apiKey = isomorph_default.getEnv("BRAINTRUST_API_KEY"),
     orgName = isomorph_default.getEnv("BRAINTRUST_ORG_NAME"),
-    fetch = globalThis.fetch
+    fetch: fetch2 = globalThis.fetch
   } = options || {};
   const appPublicUrl = isomorph_default.getEnv("BRAINTRUST_APP_PUBLIC_URL") || appUrl;
   const state = new BraintrustState(options);
@@ -2179,7 +2383,7 @@ async function loginToState(options = {}) {
   let conn = null;
   if (apiKey !== void 0) {
     const resp = await checkResponse(
-      await fetch((0, import_core._urljoin)(state.appUrl, `/api/apikey/login`), {
+      await fetch2((0, import_core._urljoin)(state.appUrl, `/api/apikey/login`), {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
@@ -2347,8 +2551,8 @@ async function flush(options) {
   const state = options?.state ?? _globalState;
   return await state.bgLogger().flush();
 }
-function setFetch(fetch) {
-  _globalState.setFetch(fetch);
+function setFetch(fetch2) {
+  _globalState.setFetch(fetch2);
 }
 function startSpanAndIsLogger(args) {
   const state = args?.state ?? _globalState;
@@ -2476,6 +2680,47 @@ function validateAndSanitizeExperimentLogPartialArgs(event) {
     return { ...event };
   }
 }
+function deepCopyEvent(event) {
+  const attachments = [];
+  const IDENTIFIER = "_bt_internal_saved_attachment";
+  const savedAttachmentSchema = import_zod2.z.strictObject({ [IDENTIFIER]: import_zod2.z.number() });
+  const serialized = JSON.stringify(event, (_k, v) => {
+    if (v instanceof SpanImpl || v instanceof NoopSpan) {
+      return `<span>`;
+    } else if (v instanceof Experiment) {
+      return `<experiment>`;
+    } else if (v instanceof Dataset) {
+      return `<dataset>`;
+    } else if (v instanceof Logger) {
+      return `<logger>`;
+    } else if (v instanceof Attachment) {
+      const idx = attachments.push(v);
+      return { [IDENTIFIER]: idx - 1 };
+    }
+    return v;
+  });
+  const x = JSON.parse(serialized, (_k, v) => {
+    const parsedAttachment = savedAttachmentSchema.safeParse(v);
+    if (parsedAttachment.success) {
+      return attachments[parsedAttachment.data[IDENTIFIER]];
+    }
+    return v;
+  });
+  return x;
+}
+function extractAttachments(event, attachments) {
+  for (const [key, value] of Object.entries(event)) {
+    if (value instanceof Attachment) {
+      attachments.push(value);
+      event[key] = value.reference;
+      continue;
+    }
+    if (!(value instanceof Object)) {
+      continue;
+    }
+    extractAttachments(value, attachments);
+  }
+}
 function validateAndSanitizeExperimentLogFullArgs(event, hasDataset) {
   if ("input" in event && !isEmpty(event.input) && "inputs" in event && !isEmpty(event.inputs) || !("input" in event) && !("inputs" in event)) {
     throw new Error(
@@ -2606,10 +2851,9 @@ var Experiment = class extends ObjectFetcher {
    * @param event.metrics: (Optional) a dictionary of metrics to log. The following keys are populated automatically: "start", "end".
    * @param event.id: (Optional) a unique identifier for the event. If you don't provide one, BrainTrust will generate one for you.
    * @param event.dataset_record_id: (Optional) the id of the dataset record that this event is associated with. This field is required if and only if the experiment is associated with a dataset.
-   * @param event.inputs: (Deprecated) the same as `input` (will be removed in a future version).
    * @param options Additional logging options
    * @param options.allowConcurrentWithSpans in rare cases where you need to log at the top level separately from spans on the experiment elsewhere, set this to true.
-   * :returns: The `id` of the logged event.
+   * @returns The `id` of the logged event.
    */
   log(event, options) {
     if (this.calledStartSpan && !options?.allowConcurrentWithSpans) {
@@ -2625,7 +2869,7 @@ var Experiment = class extends ObjectFetcher {
   /**
    * Create a new toplevel span underneath the experiment. The name defaults to "root".
    *
-   * See `Span.traced` for full details.
+   * See {@link Span.traced} for full details.
    */
   traced(callback, args) {
     const { setCurrent, ...argsRest } = args ?? {};
@@ -2651,7 +2895,7 @@ var Experiment = class extends ObjectFetcher {
    * where you cannot use callbacks. However, spans started with `startSpan` will not be marked as the "current span",
    * so `currentSpan()` and `traced()` will be no-ops. If you want to mark a span as current, use `traced` instead.
    *
-   * See `traced` for full details.
+   * See {@link traced} for full details.
    */
   startSpan(args) {
     this.calledStartSpan = true;
@@ -2763,7 +3007,7 @@ var Experiment = class extends ObjectFetcher {
    * Update a span in the experiment using its id. It is important that you only update a span once the original span has been fully written and flushed,
    * since otherwise updates to the span may conflict with the original span.
    *
-   * @param event The event data to update the span with. Must include `id`. See `Experiment.log` for a full list of valid fields.
+   * @param event The event data to update the span with. Must include `id`. See {@link Experiment.log} for a full list of valid fields.
    */
   updateSpan(event) {
     const { id, ...eventRest } = event;
@@ -2779,7 +3023,9 @@ var Experiment = class extends ObjectFetcher {
     });
   }
   /**
-   * Return a serialized representation of the experiment that can be used to start subspans in other places. See `Span.start_span` for more details.
+   * Return a serialized representation of the experiment that can be used to start subspans in other places.
+   *
+   * See {@link Span.startSpan} for more details.
    */
   async export() {
     return new import_core.SpanComponentsV3({
@@ -2794,7 +3040,7 @@ var Experiment = class extends ObjectFetcher {
     return await this.state.bgLogger().flush();
   }
   /**
-   * This function is deprecated. You can simply remove it from your code.
+   * @deprecated This function is deprecated. You can simply remove it from your code.
    */
   async close() {
     console.warn(
@@ -2936,27 +3182,14 @@ var SpanImpl = class _SpanImpl {
       event,
       internalData
     });
-    let partialRecord = {
+    const partialRecord = deepCopyEvent({
       id: this.id,
       span_id: this.spanId,
       root_span_id: this.rootSpanId,
       span_parents: this.spanParents,
       ...serializableInternalData,
       [import_core.IS_MERGE_FIELD]: this.isMerge
-    };
-    const serializedPartialRecord = JSON.stringify(partialRecord, (_k, v) => {
-      if (v instanceof _SpanImpl) {
-        return `<span>`;
-      } else if (v instanceof Experiment) {
-        return `<experiment>`;
-      } else if (v instanceof Dataset) {
-        return `<dataset>`;
-      } else if (v instanceof Logger) {
-        return `<logger>`;
-      }
-      return v;
     });
-    partialRecord = JSON.parse(serializedPartialRecord);
     if (partialRecord.metrics?.end) {
       this.loggedEndTime = partialRecord.metrics?.end;
     }
@@ -3042,6 +3275,11 @@ var SpanImpl = class _SpanImpl {
       propagated_event: this.propagatedEvent
     }).toStr();
   }
+  async permalink() {
+    return await permalink(await this.export(), {
+      state: this.state
+    });
+  }
   async flush() {
     return await this.state.bgLogger().flush();
   }
@@ -3191,15 +3429,17 @@ var Dataset = class extends ObjectFetcher {
   }) {
     this.validateEvent({ metadata, expected, output, tags });
     const rowId = id || (0, import_uuid.v4)();
-    const args = this.createArgs({
-      id: rowId,
-      input,
-      expected,
-      metadata,
-      tags,
-      output,
-      isMerge: false
-    });
+    const args = this.createArgs(
+      deepCopyEvent({
+        id: rowId,
+        input,
+        expected,
+        metadata,
+        tags,
+        output,
+        isMerge: false
+      })
+    );
     this.state.bgLogger().log([args]);
     return rowId;
   }
@@ -3224,14 +3464,16 @@ var Dataset = class extends ObjectFetcher {
     id
   }) {
     this.validateEvent({ metadata, expected, tags });
-    const args = this.createArgs({
-      id,
-      input,
-      expected,
-      metadata,
-      tags,
-      isMerge: true
-    });
+    const args = this.createArgs(
+      deepCopyEvent({
+        id,
+        input,
+        expected,
+        metadata,
+        tags,
+        isMerge: true
+      })
+    );
     this.state.bgLogger().log([args]);
     return id;
   }
@@ -3286,7 +3528,7 @@ var Dataset = class extends ObjectFetcher {
     return await this.state.bgLogger().flush();
   }
   /**
-   * This function is deprecated. You can simply remove it from your code.
+   * @deprecated This function is deprecated. You can simply remove it from your code.
    */
   async close() {
     console.warn(
@@ -3450,6 +3692,7 @@ var Prompt = class {
     return this.parsedPromptData;
   }
 };
+var _exportsForTestingOnly = { extractAttachments, deepCopyEvent };
 
 // src/node.ts
 function configureNode() {
@@ -3465,12 +3708,14 @@ function configureNode() {
   isomorph_default.pathDirname = path.dirname;
   isomorph_default.mkdir = fs.mkdir;
   isomorph_default.writeFile = fs.writeFile;
+  isomorph_default.readFile = fs.readFile;
   _internalSetInitialState();
 }
 
 // src/exports-node.ts
 var exports_node_exports = {};
 __export(exports_node_exports, {
+  Attachment: () => Attachment,
   BaseExperiment: () => BaseExperiment,
   BraintrustState: () => BraintrustState,
   BraintrustStream: () => BraintrustStream,
@@ -3493,6 +3738,7 @@ __export(exports_node_exports, {
   SpanImpl: () => SpanImpl,
   ToolBuilder: () => ToolBuilder,
   X_CACHED_HEADER: () => X_CACHED_HEADER,
+  _exportsForTestingOnly: () => _exportsForTestingOnly,
   _internalGetGlobalState: () => _internalGetGlobalState,
   _internalSetInitialState: () => _internalSetInitialState,
   braintrustStreamChunkSchema: () => braintrustStreamChunkSchema,
@@ -3546,7 +3792,7 @@ async function invoke(args) {
     apiKey,
     appUrl,
     forceLogin,
-    fetch,
+    fetch: fetch2,
     input,
     messages,
     parent: parentArg,
@@ -3562,7 +3808,7 @@ async function invoke(args) {
     apiKey,
     appUrl,
     forceLogin,
-    fetch
+    fetch: fetch2
   });
   const parent = parentArg ? typeof parentArg === "string" ? parentArg : await parentArg.export() : await getSpanParentObject().export();
   const functionId = import_typespecs3.functionIdSchema.safeParse({
@@ -4813,6 +5059,7 @@ async function Eval(name, evaluator, reporterOrOpts) {
   }
   if (globalThis._lazy_load) {
     globalThis._evals.evaluators[evalName] = {
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
       evaluator: {
         evalName,
         projectName: name,
@@ -4851,7 +5098,8 @@ async function Eval(name, evaluator, reporterOrOpts) {
       baseExperiment: evaluator.baseExperimentName ?? defaultBaseExperiment,
       baseExperimentId: evaluator.baseExperimentId,
       gitMetadataSettings: evaluator.gitMetadataSettings,
-      repoInfo: evaluator.repoInfo
+      repoInfo: evaluator.repoInfo,
+      dataset: data instanceof Dataset ? data : void 0
     });
     if (options.onStart) {
       experiment.summarize({ summarizeScores: false }).then(options.onStart);
@@ -4897,7 +5145,10 @@ function serializeJSONWithPlainString(v) {
 function evaluateFilter(object, filter2) {
   const { path: path3, pattern } = filter2;
   const key = path3.reduce(
-    (acc, p) => typeof acc === "object" && acc !== null ? acc[p] : void 0,
+    (acc, p) => typeof acc === "object" && acc !== null ? (
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+      acc[p]
+    ) : void 0,
     object
   );
   if (key === void 0) {
@@ -5004,7 +5255,12 @@ async function runEvaluatorInternal(experiment, evaluator, progressReporter, fil
             }
           );
           rootSpan.log({ output, metadata });
-          const scoringArgs = { ...datum, metadata, output };
+          const scoringArgs = {
+            input: datum.input,
+            expected: "expected" in datum ? datum.expected : void 0,
+            metadata,
+            output
+          };
           const scorerNames = evaluator.scores.map(scorerName);
           const scoreResults = await Promise.all(
             evaluator.scores.map(async (score, score_idx) => {
@@ -5131,7 +5387,13 @@ async function runEvaluatorInternal(experiment, evaluator, progressReporter, fil
           event: {
             input: datum.input,
             expected: "expected" in datum ? datum.expected : void 0,
-            tags: datum.tags
+            tags: datum.tags,
+            origin: experiment.dataset && datum.id && datum._xact_id ? {
+              object_type: "dataset",
+              object_id: await experiment.dataset.id,
+              id: datum.id,
+              _xact_id: datum._xact_id
+            } : void 0
           }
         });
       }
@@ -5994,6 +6256,7 @@ configureNode();
 var src_default = exports_node_exports;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  Attachment,
   BaseExperiment,
   BraintrustState,
   BraintrustStream,
@@ -6016,6 +6279,7 @@ var src_default = exports_node_exports;
   SpanImpl,
   ToolBuilder,
   X_CACHED_HEADER,
+  _exportsForTestingOnly,
   _internalGetGlobalState,
   _internalSetInitialState,
   braintrustStreamChunkSchema,