braintrust 0.0.166 → 0.0.168

package/dist/browser.mjs

@@ -55,7 +55,8 @@ import {
   promptDataSchema,
   promptSchema,
   toolsSchema,
-  gitMetadataSettingsSchema
+  gitMetadataSettingsSchema,
+  BRAINTRUST_ATTACHMENT
 } from "@braintrust/core/typespecs";
 
 // src/util.ts
@@ -106,7 +107,7 @@ var LazyValue = class {
 
 // src/logger.ts
 import Mustache from "mustache";
-import { z as z2 } from "zod";
+import { z as z2, ZodError } from "zod";
 
 // src/functions/stream.ts
 import {
@@ -396,6 +397,9 @@ var NoopSpan = class {
   async export() {
     return "";
   }
+  async permalink() {
+    return "";
+  }
   async flush() {
   }
   close(args) {
@@ -537,11 +541,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) {
@@ -630,15 +634,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 {
@@ -674,12 +678,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,
@@ -689,13 +695,16 @@ var HTTPConnection = class _HTTPConnection {
   }
   async post(path, 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(_urljoin(this.base_url, path), {
+      await this_fetch(_urljoin(this_base_url, path), {
         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,
@@ -728,6 +737,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: 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 } = z2.object({
+          signedUrl: z2.string().url(),
+          headers: z2.record(z2.string())
+        }).parse(await metadataResponse.json()));
+      } catch (error) {
+        if (error instanceof ZodError) {
+          const errorStr = JSON.stringify(error.flatten());
+          throw new Error(`Invalid response from API server: ${errorStr}`);
+        }
+        throw error;
+      }
+      let objectStoreResponse;
+      try {
+        objectStoreResponse = await checkResponse(
+          await fetch(signedUrl, {
+            method: "PUT",
+            headers,
+            body: data
+          })
+        );
+      } catch (error) {
+        if (error instanceof FailedHTTPResponse) {
+          throw new Error(
+            `Failed to upload attachment to object store: ${error.status} ${error.text} ${error.data}`
+          );
+        }
+        throw error;
+      }
+      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 (error) {
+        status.upload_status = "error";
+        status.error_message = error instanceof Error ? error.message : JSON.stringify(error);
+      }
+      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 readFile = isomorph_default.readFile;
+      if (!readFile) {
+        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 readFile(data)]));
+    } else {
+      return new LazyValue(async () => new Blob([data]));
+    }
+  }
+};
 function logFeedbackImpl(state, parentObjectType, parentObjectId, {
   id,
   expected,
@@ -752,7 +922,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))
   );
@@ -801,10 +971,12 @@ function updateSpanImpl({
   id,
   event
 }) {
-  const updateEvent = validateAndSanitizeExperimentLogPartialArgs({
-    id,
-    ...event
-  });
+  const updateEvent = deepCopyEvent(
+    validateAndSanitizeExperimentLogPartialArgs({
+      id,
+      ...event
+    })
+  );
   const parentIds = async () => new SpanComponentsV3({
     object_type: parentObjectType,
     object_id: await parentObjectId.get()
@@ -1005,7 +1177,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) {
@@ -1028,7 +1200,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 ?? {};
@@ -1062,7 +1234,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;
@@ -1102,7 +1274,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;
@@ -1118,7 +1290,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 SpanComponentsV3({
@@ -1158,6 +1332,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;
@@ -1221,6 +1396,7 @@ var BackgroundLogger = class _BackgroundLogger {
         await this.flush();
       });
     }
+    this.onFlushError = opts.onFlushError;
   }
   log(items) {
     const [addedItems, droppedItems] = (() => {
@@ -1252,14 +1428,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;
     }
@@ -1291,6 +1469,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 (error) {
+        attachmentErrors.push(error);
+      }
+    }
+    if (attachmentErrors.length > 0) {
+      throw new AggregateError(
+        attachmentErrors,
+        `Encountered the following errors while uploading attachments:`
+      );
+    }
     if (this.items.length > 0) {
       await this.flushOnce(args);
     }
@@ -1298,8 +1493,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 mergeRowBatch(await Promise.all(itemPromises));
+        const items = await Promise.all(wrappedItems.map((x) => x.get()));
+        const attachments = [];
+        items.forEach((item) => extractAttachments(item, attachments));
+        return [mergeRowBatch(items), attachments];
       } catch (e) {
         let errmsg = "Encountered error when constructing records to flush";
         const isRetrying = i + 1 < this.numTries;
@@ -1307,7 +1504,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);
@@ -1315,10 +1515,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();
@@ -1334,16 +1531,14 @@ var BackgroundLogger = class _BackgroundLogger {
       let error = void 0;
       try {
         await conn.post_json("logs3", dataStr);
-      } catch (e) {
+      } catch {
         try {
           const legacyDataS = constructJsonArray(
-            items.map(
-              (r) => JSON.stringify(makeLegacyEvent(JSON.parse(r)))
-            )
+            items.map((r) => JSON.stringify(makeLegacyEvent(JSON.parse(r))))
           );
           await conn.post_json("logs", legacyDataS);
-        } catch (e2) {
-          error = e2;
+        } catch (e) {
+          error = e;
         }
       }
       if (error === void 0) {
@@ -1367,7 +1562,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);
@@ -1376,10 +1574,6 @@ Error: ${errorText}`;
         }
       }
     }
-    console.warn(
-      `log request failed after ${this.numTries} retries. Dropping batch`
-    );
-    return;
   }
   registerDroppedItemCount(numItems) {
     if (numItems <= 0) {
@@ -1407,15 +1601,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);
@@ -1454,6 +1650,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;
@@ -1496,7 +1699,7 @@ function init(projectOrOptions, optionalOptions) {
     apiKey,
     orgName,
     forceLogin,
-    fetch,
+    fetch: fetch2,
     metadata,
     gitMetadataSettings,
     projectId,
@@ -1514,7 +1717,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,
@@ -1685,7 +1888,7 @@ function initDataset(projectOrOptions, optionalOptions) {
     appUrl,
     apiKey,
     orgName,
-    fetch,
+    fetch: fetch2,
     forceLogin,
     projectId,
     metadata,
@@ -1699,7 +1902,7 @@ function initDataset(projectOrOptions, optionalOptions) {
         orgName,
         apiKey,
         appUrl,
-        fetch,
+        fetch: fetch2,
         forceLogin
       });
       const args = {
@@ -1781,7 +1984,7 @@ function initLogger(options = {}) {
     apiKey,
     orgName,
     forceLogin,
-    fetch,
+    fetch: fetch2,
     state: stateArg
   } = options || {};
   const computeMetadataArgs = {
@@ -1796,7 +1999,7 @@ function initLogger(options = {}) {
         apiKey,
         appUrl,
         forceLogin,
-        fetch
+        fetch: fetch2
       });
       return computeLoggerMetadata(state, computeMetadataArgs);
     }
@@ -1820,7 +2023,7 @@ async function loadPrompt({
   appUrl,
   apiKey,
   orgName,
-  fetch,
+  fetch: fetch2,
   forceLogin,
   state: stateArg
 }) {
@@ -1835,7 +2038,7 @@ async function loadPrompt({
     orgName,
     apiKey,
     appUrl,
-    fetch,
+    fetch: fetch2,
     forceLogin
   });
   const args = {
@@ -1886,7 +2089,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);
@@ -1896,7 +2099,7 @@ async function loginToState(options = {}) {
   let conn = null;
   if (apiKey !== void 0) {
     const resp = await checkResponse(
-      await fetch(_urljoin(state.appUrl, `/api/apikey/login`), {
+      await fetch2(_urljoin(state.appUrl, `/api/apikey/login`), {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
@@ -2064,8 +2267,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;
@@ -2193,6 +2396,47 @@ function validateAndSanitizeExperimentLogPartialArgs(event) {
     return { ...event };
   }
 }
+function deepCopyEvent(event) {
+  const attachments = [];
+  const IDENTIFIER = "_bt_internal_saved_attachment";
+  const savedAttachmentSchema = z2.strictObject({ [IDENTIFIER]: z2.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(
@@ -2323,10 +2567,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) {
@@ -2342,7 +2585,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 ?? {};
@@ -2368,7 +2611,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;
@@ -2480,7 +2723,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;
@@ -2496,7 +2739,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 SpanComponentsV3({
@@ -2511,7 +2756,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(
@@ -2653,27 +2898,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,
       [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;
     }
@@ -2759,6 +2991,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();
   }
@@ -2908,15 +3145,17 @@ var Dataset = class extends ObjectFetcher {
   }) {
     this.validateEvent({ metadata, expected, output, tags });
     const rowId = id || uuidv4();
-    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;
   }
@@ -2941,14 +3180,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;
   }
@@ -3003,7 +3244,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(
@@ -3167,6 +3408,7 @@ var Prompt = class {
     return this.parsedPromptData;
   }
 };
+var _exportsForTestingOnly = { extractAttachments, deepCopyEvent };
 
 // src/browser-config.ts
 var browserConfigured = false;
@@ -3193,6 +3435,7 @@ function configureBrowser() {
 // src/exports-browser.ts
 var exports_browser_exports = {};
 __export(exports_browser_exports, {
+  Attachment: () => Attachment,
   BraintrustState: () => BraintrustState,
   BraintrustStream: () => BraintrustStream,
   Dataset: () => Dataset,
@@ -3206,6 +3449,7 @@ __export(exports_browser_exports, {
   ReadonlyExperiment: () => ReadonlyExperiment,
   SpanImpl: () => SpanImpl,
   X_CACHED_HEADER: () => X_CACHED_HEADER,
+  _exportsForTestingOnly: () => _exportsForTestingOnly,
   _internalGetGlobalState: () => _internalGetGlobalState,
   _internalSetInitialState: () => _internalSetInitialState,
   braintrustStreamChunkSchema: () => braintrustStreamChunkSchema,
@@ -3256,7 +3500,7 @@ async function invoke(args) {
     apiKey,
     appUrl,
     forceLogin,
-    fetch,
+    fetch: fetch2,
     input,
     messages,
     parent: parentArg,
@@ -3272,7 +3516,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 = functionIdSchema.safeParse({
@@ -3699,6 +3943,7 @@ var WrapperStream = class {
 configureBrowser();
 var browser_default = exports_browser_exports;
 export {
+  Attachment,
   BraintrustState,
   BraintrustStream,
   Dataset,
@@ -3712,6 +3957,7 @@ export {
   ReadonlyExperiment,
   SpanImpl,
   X_CACHED_HEADER,
+  _exportsForTestingOnly,
   _internalGetGlobalState,
   _internalSetInitialState,
   braintrustStreamChunkSchema,