braintrust 0.0.166 → 0.0.168

package/dist/browser.js

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/browser.ts
 var browser_exports = {};
 __export(browser_exports, {
+  Attachment: () => Attachment,
   BraintrustState: () => BraintrustState,
   BraintrustStream: () => BraintrustStream,
   Dataset: () => Dataset,
@@ -43,6 +44,7 @@ __export(browser_exports, {
   ReadonlyExperiment: () => ReadonlyExperiment,
   SpanImpl: () => SpanImpl,
   X_CACHED_HEADER: () => X_CACHED_HEADER,
+  _exportsForTestingOnly: () => _exportsForTestingOnly,
   _internalGetGlobalState: () => _internalGetGlobalState,
   _internalSetInitialState: () => _internalSetInitialState,
   braintrustStreamChunkSchema: () => braintrustStreamChunkSchema,
@@ -446,6 +448,9 @@ var NoopSpan = class {
   async export() {
     return "";
   }
+  async permalink() {
+    return "";
+  }
   async flush() {
   }
   close(args) {
@@ -587,11 +592,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) {
@@ -680,15 +685,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 {
@@ -724,12 +729,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,
@@ -739,13 +746,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((0, import_core._urljoin)(this.base_url, path), {
+      await this_fetch((0, import_core._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,
@@ -778,6 +788,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 (error) {
+        if (error instanceof import_zod2.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,
@@ -802,7 +973,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))
   );
@@ -851,10 +1022,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()
@@ -1055,7 +1228,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) {
@@ -1078,7 +1251,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 ?? {};
@@ -1112,7 +1285,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;
@@ -1152,7 +1325,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;
@@ -1168,7 +1341,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({
@@ -1208,6 +1383,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;
@@ -1271,6 +1447,7 @@ var BackgroundLogger = class _BackgroundLogger {
         await this.flush();
       });
     }
+    this.onFlushError = opts.onFlushError;
   }
   log(items) {
     const [addedItems, droppedItems] = (() => {
@@ -1302,14 +1479,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;
     }
@@ -1341,6 +1520,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);
     }
@@ -1348,8 +1544,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;
@@ -1357,7 +1555,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);
@@ -1365,10 +1566,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();
@@ -1384,16 +1582,14 @@ var BackgroundLogger = class _BackgroundLogger {
       let error = 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) {
-          error = e2;
+        } catch (e) {
+          error = e;
         }
       }
       if (error === void 0) {
@@ -1417,7 +1613,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);
@@ -1426,10 +1625,6 @@ Error: ${errorText}`;
         }
       }
     }
-    console.warn(
-      `log request failed after ${this.numTries} retries. Dropping batch`
-    );
-    return;
   }
   registerDroppedItemCount(numItems) {
     if (numItems <= 0) {
@@ -1457,15 +1652,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);
@@ -1504,6 +1701,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;
@@ -1546,7 +1750,7 @@ function init(projectOrOptions, optionalOptions) {
     apiKey,
     orgName,
     forceLogin,
-    fetch,
+    fetch: fetch2,
     metadata,
     gitMetadataSettings,
     projectId,
@@ -1564,7 +1768,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,
@@ -1735,7 +1939,7 @@ function initDataset(projectOrOptions, optionalOptions) {
     appUrl,
     apiKey,
     orgName,
-    fetch,
+    fetch: fetch2,
     forceLogin,
     projectId,
     metadata,
@@ -1749,7 +1953,7 @@ function initDataset(projectOrOptions, optionalOptions) {
         orgName,
         apiKey,
         appUrl,
-        fetch,
+        fetch: fetch2,
         forceLogin
       });
       const args = {
@@ -1831,7 +2035,7 @@ function initLogger(options = {}) {
     apiKey,
     orgName,
     forceLogin,
-    fetch,
+    fetch: fetch2,
     state: stateArg
   } = options || {};
   const computeMetadataArgs = {
@@ -1846,7 +2050,7 @@ function initLogger(options = {}) {
         apiKey,
         appUrl,
         forceLogin,
-        fetch
+        fetch: fetch2
       });
       return computeLoggerMetadata(state, computeMetadataArgs);
     }
@@ -1870,7 +2074,7 @@ async function loadPrompt({
   appUrl,
   apiKey,
   orgName,
-  fetch,
+  fetch: fetch2,
   forceLogin,
   state: stateArg
 }) {
@@ -1885,7 +2089,7 @@ async function loadPrompt({
     orgName,
     apiKey,
     appUrl,
-    fetch,
+    fetch: fetch2,
     forceLogin
   });
   const args = {
@@ -1936,7 +2140,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);
@@ -1946,7 +2150,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",
@@ -2114,8 +2318,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;
@@ -2243,6 +2447,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(
@@ -2373,10 +2618,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) {
@@ -2392,7 +2636,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 ?? {};
@@ -2418,7 +2662,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;
@@ -2530,7 +2774,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;
@@ -2546,7 +2790,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({
@@ -2561,7 +2807,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(
@@ -2703,27 +2949,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;
     }
@@ -2809,6 +3042,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();
   }
@@ -2958,15 +3196,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;
   }
@@ -2991,14 +3231,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;
   }
@@ -3053,7 +3295,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(
@@ -3217,6 +3459,7 @@ var Prompt = class {
     return this.parsedPromptData;
   }
 };
+var _exportsForTestingOnly = { extractAttachments, deepCopyEvent };
 
 // src/browser-config.ts
 var browserConfigured = false;
@@ -3243,6 +3486,7 @@ function configureBrowser() {
 // src/exports-browser.ts
 var exports_browser_exports = {};
 __export(exports_browser_exports, {
+  Attachment: () => Attachment,
   BraintrustState: () => BraintrustState,
   BraintrustStream: () => BraintrustStream,
   Dataset: () => Dataset,
@@ -3256,6 +3500,7 @@ __export(exports_browser_exports, {
   ReadonlyExperiment: () => ReadonlyExperiment,
   SpanImpl: () => SpanImpl,
   X_CACHED_HEADER: () => X_CACHED_HEADER,
+  _exportsForTestingOnly: () => _exportsForTestingOnly,
   _internalGetGlobalState: () => _internalGetGlobalState,
   _internalSetInitialState: () => _internalSetInitialState,
   braintrustStreamChunkSchema: () => braintrustStreamChunkSchema,
@@ -3304,7 +3549,7 @@ async function invoke(args) {
     apiKey,
     appUrl,
     forceLogin,
-    fetch,
+    fetch: fetch2,
     input,
     messages,
     parent: parentArg,
@@ -3320,7 +3565,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({
@@ -3748,6 +3993,7 @@ configureBrowser();
 var browser_default = exports_browser_exports;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  Attachment,
   BraintrustState,
   BraintrustStream,
   Dataset,
@@ -3761,6 +4007,7 @@ var browser_default = exports_browser_exports;
   ReadonlyExperiment,
   SpanImpl,
   X_CACHED_HEADER,
+  _exportsForTestingOnly,
   _internalGetGlobalState,
   _internalSetInitialState,
   braintrustStreamChunkSchema,