braintrust 0.0.166 → 0.0.168

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { LogFeedbackFullArgs, ExperimentEvent, BackgroundLogEvent, ExperimentLogFullArgs, ExperimentLogPartialArgs, IdField, SpanType, SpanComponentsV3, DEFAULT_IS_LEGACY_DATASET, TRANSACTION_ID_FIELD, TransactionId, SpanObjectTypeV3, DatasetRecord, Score, CommentEvent, InputField, InputsField, LogCommentFullArgs, OtherExperimentLogFields, ParentExperimentIds, ParentProjectLogIds } from '@braintrust/core';
-export { CommentEvent, DatasetRecord, ExperimentLogFullArgs, ExperimentLogPartialArgs, IdField, InputField, InputsField, LogCommentFullArgs, LogFeedbackFullArgs, OtherExperimentLogFields, ParentExperimentIds, ParentProjectLogIds } from '@braintrust/core';
-import { GitMetadataSettings, RepoInfo, PromptData, OpenAIMessage, Tools, AnyModelParam, Message, Prompt as Prompt$1, PromptSessionEvent, StreamingMode, FunctionType, IfExists, SavedFunctionId, ModelParams } from '@braintrust/core/typespecs';
+import { LogFeedbackFullArgs, ExperimentEvent, BackgroundLogEvent, ExperimentLogFullArgs, ExperimentLogPartialArgs, IdField, SpanType, SpanComponentsV3, DEFAULT_IS_LEGACY_DATASET, TRANSACTION_ID_FIELD, TransactionId, SpanObjectTypeV3, DatasetRecord, Score, CommentEvent, InputField, LogCommentFullArgs, OtherExperimentLogFields, ParentExperimentIds, ParentProjectLogIds } from '@braintrust/core';
+export { CommentEvent, DatasetRecord, ExperimentLogFullArgs, ExperimentLogPartialArgs, IdField, InputField, LogCommentFullArgs, LogFeedbackFullArgs, OtherExperimentLogFields, ParentExperimentIds, ParentProjectLogIds } from '@braintrust/core';
+import { GitMetadataSettings, AttachmentReference, RepoInfo, PromptData, OpenAIMessage, Tools, AnyModelParam, Message, Prompt as Prompt$1, PromptSessionEvent, StreamingMode, FunctionType, IfExists, SavedFunctionId, ModelParams } from '@braintrust/core/typespecs';
 import { z } from 'zod';
 
 interface IsoAsyncLocalStorage<T> {
@@ -35,16 +35,14 @@ type EndSpanArgs = {
 };
 interface Exportable {
     /**
-     * Return a serialized representation of the object that can be used to start subspans in other places. See `Span.traced` for more details.
+     * Return a serialized representation of the object that can be used to start subspans in other places. See {@link Span.traced} for more details.
      */
     export(): Promise<string>;
 }
 /**
  * A Span encapsulates logged data and metrics for a unit of work. This interface is shared by all span implementations.
  *
- * We suggest using one of the various `traced` methods, instead of creating Spans directly.
- *
- * See `Span.traced` for full details.
+ * We suggest using one of the various `traced` methods, instead of creating Spans directly. See {@link Span.traced} for full details.
  */
 interface Span extends Exportable {
     /**
@@ -54,13 +52,13 @@ interface Span extends Exportable {
     /**
      * Incrementally update the current span with new data. The event will be batched and uploaded behind the scenes.
      *
-     * @param event: Data to be logged. See `Experiment.log` for full details.
+     * @param event: Data to be logged. See {@link Experiment.log} for full details.
      */
     log(event: ExperimentLogPartialArgs): void;
     /**
      * Add feedback to the current span. Unlike `Experiment.logFeedback` and `Logger.logFeedback`, this method does not accept an id parameter, because it logs feedback to the current span.
      *
-     * @param event: Data to be logged. See `Experiment.logFeedback` for full details.
+     * @param event: Data to be logged. See {@link Experiment.logFeedback} for full details.
      */
     logFeedback(event: Omit<LogFeedbackFullArgs, "id">): void;
     /**
@@ -75,8 +73,8 @@ interface Span extends Exportable {
      * @param args.start_time Optional start time of the span, as a timestamp in seconds.
      * @param args.setCurrent If true (the default), the span will be marked as the currently-active span for the duration of the callback.
      * @param args.parent Optional parent info string for the span. The string can be generated from `[Span,Experiment,Logger].export`. If not provided, the current span will be used (depending on context). This is useful for adding spans to an existing trace.
-     * @param args.event Data to be logged. See `Experiment.log` for full details.
-     * @Returns The result of running `callback`.
+     * @param args.event Data to be logged. See {@link Experiment.log} for full details.
+     * @returns The result of running `callback`.
      */
     traced<R>(callback: (span: Span) => R, args?: StartSpanArgs & SetCurrentArg): R;
     /**
@@ -84,7 +82,7 @@ interface Span extends Exportable {
      * 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 Span.traced} for full details.
      *
      * @returns The newly-created `Span`
      */
@@ -98,6 +96,28 @@ interface Span extends Exportable {
      * @returns The end time logged to the span metrics.
      */
     end(args?: EndSpanArgs): number;
+    /**
+     * Serialize the identifiers of this span. The return value can be used to
+     * identify this span when starting a subspan elsewhere, such as another
+     * process or service, without needing to access this `Span` object. See the
+     * parameters of {@link Span.startSpan} for usage details.
+     *
+     * Callers should treat the return value as opaque. The serialization format
+     * may change from time to time. If parsing is needed, use
+     * `SpanComponentsV3.fromStr`.
+     *
+     * @returns Serialized representation of this span's identifiers.
+     */
+    export(): Promise<string>;
+    /**
+     * Format a permalink to the Braintrust application for viewing this span.
+     *
+     * Links can be generated at any time, but they will only become viewable
+     * after the span and its root have been flushed to the server and ingested.
+     *
+     * @returns A permalink to the span.
+     */
+    permalink(): Promise<string>;
     /**
      * Flush any pending rows to the server.
      */
@@ -125,6 +145,7 @@ declare class NoopSpan implements Span {
     startSpan(_1?: StartSpanArgs): this;
     end(args?: EndSpanArgs): number;
     export(): Promise<string>;
+    permalink(): Promise<string>;
     flush(): Promise<void>;
     close(args?: EndSpanArgs): number;
     setAttributes(_args: Omit<StartSpanArgs, "event">): void;
@@ -212,7 +233,15 @@ declare class BraintrustState {
     bgLogger(): BackgroundLogger;
     loginReplaceApiConn(apiConn: HTTPConnection): void;
 }
+/**
+ * This function should be invoked exactly once after configuring the `iso`
+ * object based on the platform. See js/src/node.ts for an example.
+ * @internal
+ */
 declare function _internalSetInitialState(): void;
+/**
+ * @internal
+ */
 declare const _internalGetGlobalState: () => BraintrustState;
 declare class FailedHTTPResponse extends Error {
     status: number;
@@ -259,13 +288,72 @@ interface LogOptions<IsAsyncFlush> {
     computeMetadataArgs?: Record<string, any>;
 }
 type PromiseUnless<B, R> = B extends true ? R : Promise<Awaited<R>>;
+interface AttachmentParams {
+    data: string | Blob | ArrayBuffer;
+    filename: string;
+    contentType: string;
+    state?: BraintrustState;
+}
+/**
+ * Represents an attachment to be uploaded and the associated metadata.
+ * `Attachment` objects can be inserted anywhere in an event, allowing you to
+ * log arbitrary file data. The SDK will asynchronously upload the file to
+ * object storage and replace the `Attachment` object with an
+ * `AttachmentReference`.
+ */
+declare class Attachment {
+    /**
+     * The object that replaces this `Attachment` at upload time.
+     */
+    readonly reference: AttachmentReference;
+    private readonly uploader;
+    private readonly data;
+    private readonly state?;
+    private readonly 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 }: AttachmentParams);
+    /**
+     * 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.
+     */
+    upload(): Promise<{
+        upload_status: "error" | "done" | "uploading";
+        error_message?: string | undefined;
+    }>;
+    /**
+     * 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(): Record<string, unknown>;
+    private initUploader;
+    private initData;
+}
 /**
  * Update a span using the output of `span.export()`. It is important that you only resume updating
  * to 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 exported The output of `span.export()`.
- * @param event The event data to update the span with. See `Experiment.log` for a full list of valid fields.
+ * @param event The event data to update the span with. See {@link Experiment.log} for a full list of valid fields.
  * @param state (optional) Login state to use. If not provided, the global state will be used.
  */
 declare function updateSpan({ exported, state, ...event }: {
@@ -279,6 +367,22 @@ declare function spanComponentsToObjectId({ components, state, }: {
     components: SpanComponentsV3;
     state?: BraintrustState;
 }): Promise<string>;
+/**
+ * Format a permalink to the Braintrust application for viewing the span
+ * represented by the provided `slug`.
+ *
+ * Links can be generated at any time, but they will only become viewable after
+ * the span and its root have been flushed to the server and ingested.
+ *
+ * If you have a `Span` object, use {@link Span.permalink} instead.
+ *
+ * @param slug The identifier generated from {@link Span.export}.
+ * @param opts Optional arguments.
+ * @param opts.state The login state to use. If not provided, the global state will be used.
+ * @param opts.orgName The org name to use. If not provided, the org name will be inferred from the state.
+ * @param opts.appUrl The app URL to use. If not provided, the app URL will be inferred from the state.
+ * @returns A permalink to the exported span.
+ */
 declare function permalink(slug: string, opts?: {
     state?: BraintrustState;
     orgName?: string;
@@ -312,7 +416,7 @@ declare class Logger<IsAsyncFlush extends boolean> implements Exportable {
      * @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: Readonly<StartSpanEventArgs>, options?: {
         allowConcurrentWithSpans?: boolean;
@@ -320,7 +424,7 @@ declare class Logger<IsAsyncFlush extends boolean> implements Exportable {
     /**
      * 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<R>(callback: (span: Span) => R, args?: StartSpanArgs & SetCurrentArg): PromiseUnless<IsAsyncFlush, R>;
     /**
@@ -328,7 +432,7 @@ declare class Logger<IsAsyncFlush extends boolean> implements Exportable {
      * 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?: StartSpanArgs): Span;
     private startSpanImpl;
@@ -348,11 +452,13 @@ declare class Logger<IsAsyncFlush extends boolean> implements Exportable {
      * 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: Omit<Partial<ExperimentEvent>, "id"> & Required<Pick<ExperimentEvent, "id">>): void;
     /**
-     * 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.
      */
     export(): Promise<string>;
     flush(): Promise<void>;
@@ -360,6 +466,7 @@ declare class Logger<IsAsyncFlush extends boolean> implements Exportable {
 }
 interface BackgroundLoggerOpts {
     noExitFlush?: boolean;
+    onFlushError?: (error: unknown) => void;
 }
 declare class BackgroundLogger {
     private apiConn;
@@ -367,6 +474,7 @@ declare class BackgroundLogger {
     private activeFlush;
     private activeFlushResolved;
     private activeFlushError;
+    private onFlushError?;
     syncFlush: boolean;
     maxRequestSize: number;
     defaultBatchSize: number;
@@ -449,11 +557,11 @@ declare function initExperiment<IsOpen extends boolean = false>(options: Readonl
  */
 declare function initExperiment<IsOpen extends boolean = false>(project: string, options?: Readonly<InitOptions<IsOpen>>): InitializedExperiment<IsOpen>;
 /**
- * This function is deprecated. Use `init` instead.
+ * @deprecated Use {@link init} instead.
  */
 declare function withExperiment<R>(project: string, callback: (experiment: Experiment) => R, options?: Readonly<InitOptions<false> & SetCurrentArg>): R;
 /**
- * This function is deprecated. Use `initLogger` instead.
+ * @deprecated Use {@link initLogger} instead.
  */
 declare function withLogger<IsAsyncFlush extends boolean = false, R = void>(callback: (logger: Logger<IsAsyncFlush>) => R, options?: Readonly<InitLoggerOptions<IsAsyncFlush> & SetCurrentArg>): R;
 type UseOutputOption<IsLegacyDataset extends boolean> = {
@@ -488,12 +596,13 @@ type FullInitDatasetOptions<IsLegacyDataset extends boolean> = {
 declare function initDataset<IsLegacyDataset extends boolean = typeof DEFAULT_IS_LEGACY_DATASET>(options: Readonly<FullInitDatasetOptions<IsLegacyDataset>>): Dataset<IsLegacyDataset>;
 /**
  * Legacy form of `initDataset` which accepts the project name as the first
- * parameter, separately from the remaining options. See
- * `initDataset(options)` for full details.
+ * parameter, separately from the remaining options.
+ *
+ * See `initDataset(options)` for full details.
  */
 declare function initDataset<IsLegacyDataset extends boolean = typeof DEFAULT_IS_LEGACY_DATASET>(project: string, options?: Readonly<InitDatasetOptions<IsLegacyDataset>>): Dataset<IsLegacyDataset>;
 /**
- * This function is deprecated. Use `initDataset` instead.
+ * @deprecated Use {@link initDataset} instead.
  */
 declare function withDataset<R, IsLegacyDataset extends boolean = typeof DEFAULT_IS_LEGACY_DATASET>(project: string, callback: (dataset: Dataset<IsLegacyDataset>) => R, options?: Readonly<InitDatasetOptions<IsLegacyDataset>>): R;
 type AsyncFlushArg<IsAsyncFlush> = {
@@ -584,6 +693,10 @@ interface LoginOptions {
      * If true, this event handler will _not_ be installed.
      */
     noExitFlush?: boolean;
+    /**
+     * Calls this function if there's an error in the background flusher.
+     */
+    onFlushError?: (error: unknown) => void;
 }
 type FullLoginOptions = LoginOptions & {
     forceLogin?: boolean;
@@ -606,7 +719,7 @@ declare function loginToState(options?: LoginOptions): Promise<BraintrustState>;
 /**
  * Log a single event to the current experiment. The event will be batched and uploaded behind the scenes.
  *
- * @param event The event to log. See `Experiment.log` for full details.
+ * @param event The event to log. See {@link Experiment.log} for full details.
  * @returns The `id` of the logged event.
  */
 declare function log(event: ExperimentLogFullArgs): string;
@@ -626,17 +739,17 @@ type OptionalStateArg = {
     state?: BraintrustState;
 };
 /**
- * Returns the currently-active experiment (set by `braintrust.init`). Returns undefined if no current experiment has been set.
+ * Returns the currently-active experiment (set by {@link init}). Returns undefined if no current experiment has been set.
  */
 declare function currentExperiment(options?: OptionalStateArg): Experiment | undefined;
 /**
- * Returns the currently-active logger (set by `braintrust.initLogger`). Returns undefined if no current logger has been set.
+ * Returns the currently-active logger (set by {@link initLogger}). Returns undefined if no current logger has been set.
  */
 declare function currentLogger<IsAsyncFlush extends boolean>(options?: AsyncFlushArg<IsAsyncFlush> & OptionalStateArg): Logger<IsAsyncFlush> | undefined;
 /**
  * Return the currently-active span for logging (set by one of the `traced` methods). If there is no active span, returns a no-op span object, which supports the same interface as spans but does no logging.
  *
- * See `Span` for full details.
+ * See {@link Span} for full details.
  */
 declare function currentSpan(options?: OptionalStateArg): Span;
 /**
@@ -652,7 +765,7 @@ declare function logError(span: Span, error: unknown): void;
  *
  * and creates a span under the first one that is active. Alternatively, if `parent` is specified, it creates a span under the specified parent row. If none of these are active, it returns a no-op span object.
  *
- * See `Span.traced` for full details.
+ * See {@link Span.traced} for full details.
  */
 declare function traced<IsAsyncFlush extends boolean = false, R = void>(callback: (span: Span) => R, args?: StartSpanArgs & SetCurrentArg & AsyncFlushArg<IsAsyncFlush> & OptionalStateArg): PromiseUnless<IsAsyncFlush, R>;
 /**
@@ -688,7 +801,7 @@ declare const traceable: typeof wrapTraced;
  * 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.
  */
 declare function startSpan<IsAsyncFlush extends boolean = false>(args?: StartSpanArgs & AsyncFlushArg<IsAsyncFlush> & OptionalStateArg): Span;
 /**
@@ -706,6 +819,20 @@ declare function setFetch(fetch: typeof globalThis.fetch): void;
  * Runs the provided callback with the span as the current span.
  */
 declare function withCurrent<R>(span: Span, callback: (span: Span) => R, state?: BraintrustState): R;
+/**
+ * Creates a deep copy of the given event. Replaces references to user objects
+ * with placeholder strings to ensure serializability, except for
+ * {@link Attachment} objects, which are preserved and not deep-copied.
+ */
+declare function deepCopyEvent<T extends Partial<BackgroundLogEvent>>(event: T): T;
+/**
+ * Helper function for uploading attachments. Recursively extracts `Attachment`
+ * values and replaces them with their associated `AttachmentReference` objects.
+ *
+ * @param event The event to filter. Will be modified in-place.
+ * @param attachments Flat array of extracted attachments (output parameter).
+ */
+declare function extractAttachments(event: Record<string, any>, attachments: Attachment[]): void;
 type WithTransactionId<R> = R & {
     [TRANSACTION_ID_FIELD]: TransactionId;
 };
@@ -728,9 +855,11 @@ type DefaultMetadataType = void;
 type EvalCase<Input, Expected, Metadata> = {
     input: Input;
     tags?: string[];
-} & (Expected extends void ? {} : {
+    id?: string;
+    _xact_id?: TransactionId;
+} & (Expected extends void ? object : {
     expected: Expected;
-}) & (Metadata extends void ? {} : {
+}) & (Metadata extends void ? object : {
     metadata: Metadata;
 });
 /**
@@ -772,10 +901,9 @@ declare class Experiment extends ObjectFetcher<ExperimentEvent> implements Expor
      * @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: Readonly<ExperimentLogFullArgs>, options?: {
         allowConcurrentWithSpans?: boolean;
@@ -783,7 +911,7 @@ declare class Experiment extends ObjectFetcher<ExperimentEvent> implements Expor
     /**
      * 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<R>(callback: (span: Span) => R, args?: StartSpanArgs & SetCurrentArg): R;
     /**
@@ -791,7 +919,7 @@ declare class Experiment extends ObjectFetcher<ExperimentEvent> implements Expor
      * 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?: StartSpanArgs): Span;
     private startSpanImpl;
@@ -827,11 +955,13 @@ declare class Experiment extends ObjectFetcher<ExperimentEvent> implements Expor
      * 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: Omit<Partial<ExperimentEvent>, "id"> & Required<Pick<ExperimentEvent, "id">>): void;
     /**
-     * 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.
      */
     export(): Promise<string>;
     /**
@@ -839,7 +969,7 @@ declare class Experiment extends ObjectFetcher<ExperimentEvent> implements Expor
      */
     flush(): Promise<void>;
     /**
-     * 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.
      */
     close(): Promise<string>;
 }
@@ -857,9 +987,9 @@ declare class ReadonlyExperiment extends ObjectFetcher<ExperimentEvent> {
 }
 declare function newId(): string;
 /**
- * Primary implementation of the `Span` interface. See the `Span` interface for full details on each method.
+ * Primary implementation of the `Span` interface. See {@link Span} for full details on each method.
  *
- * We suggest using one of the various `traced` methods, instead of creating Spans directly. See `Span.startSpan` for full details.
+ * We suggest using one of the various `traced` methods, instead of creating Spans directly. See {@link Span.startSpan} for full details.
  */
 declare class SpanImpl implements Span {
     private state;
@@ -891,6 +1021,7 @@ declare class SpanImpl implements Span {
     startSpan(args?: StartSpanArgs): Span;
     end(args?: EndSpanArgs): number;
     export(): Promise<string>;
+    permalink(): Promise<string>;
     flush(): Promise<void>;
     close(args?: EndSpanArgs): number;
 }
@@ -970,7 +1101,7 @@ declare class Dataset<IsLegacyDataset extends boolean = typeof DEFAULT_IS_LEGACY
      */
     flush(): Promise<void>;
     /**
-     * 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.
      */
     close(): Promise<string>;
 }
@@ -1109,6 +1240,14 @@ interface DatasetSummary {
     datasetUrl: string;
     dataSummary: DataSummary;
 }
+/**
+ * Allows accessing helper functions for testing.
+ * @internal
+ */
+declare const _exportsForTestingOnly: {
+    extractAttachments: typeof extractAttachments;
+    deepCopyEvent: typeof deepCopyEvent;
+};
 
 declare const braintrustStreamChunkSchema: z.ZodUnion<[z.ZodObject<{
     type: z.ZodLiteral<"text_delta">;
@@ -1731,6 +1870,9 @@ declare function parseCachedHeader(value: string | null | undefined): number | u
 declare function wrapAISDKModel<T extends object>(model: T): T;
 
 type braintrust_AnyDataset = AnyDataset;
+type braintrust_Attachment = Attachment;
+declare const braintrust_Attachment: typeof Attachment;
+type braintrust_AttachmentParams = AttachmentParams;
 type braintrust_BackgroundLoggerOpts = BackgroundLoggerOpts;
 declare const braintrust_BaseExperiment: typeof BaseExperiment;
 type braintrust_BaseMetadata = BaseMetadata;
@@ -1779,7 +1921,6 @@ type braintrust_FullLoginOptions = FullLoginOptions;
 declare const braintrust_IdField: typeof IdField;
 type braintrust_InitOptions<IsOpen extends boolean> = InitOptions<IsOpen>;
 declare const braintrust_InputField: typeof InputField;
-declare const braintrust_InputsField: typeof InputsField;
 type braintrust_InvokeFunctionArgs<Input, Output, Stream extends boolean = false> = InvokeFunctionArgs<Input, Output, Stream>;
 type braintrust_InvokeReturn<Stream extends boolean, Output> = InvokeReturn<Stream, Output>;
 declare const braintrust_LEGACY_CACHED_HEADER: typeof LEGACY_CACHED_HEADER;
@@ -1826,6 +1967,7 @@ type braintrust_ToolFunctionDefinition = ToolFunctionDefinition;
 type braintrust_ToolOpts<Params, Returns, Fn extends GenericFunction<Params, Returns>> = ToolOpts<Params, Returns, Fn>;
 type braintrust_WithTransactionId<R> = WithTransactionId<R>;
 declare const braintrust_X_CACHED_HEADER: typeof X_CACHED_HEADER;
+declare const braintrust__exportsForTestingOnly: typeof _exportsForTestingOnly;
 declare const braintrust__internalGetGlobalState: typeof _internalGetGlobalState;
 declare const braintrust__internalSetInitialState: typeof _internalSetInitialState;
 declare const braintrust_braintrustStreamChunkSchema: typeof braintrustStreamChunkSchema;
@@ -1870,7 +2012,7 @@ declare const braintrust_wrapOpenAI: typeof wrapOpenAI;
 declare const braintrust_wrapOpenAIv4: typeof wrapOpenAIv4;
 declare const braintrust_wrapTraced: typeof wrapTraced;
 declare namespace braintrust {
-  export { type braintrust_AnyDataset as AnyDataset, type braintrust_BackgroundLoggerOpts as BackgroundLoggerOpts, braintrust_BaseExperiment as BaseExperiment, type braintrust_BaseMetadata as BaseMetadata, braintrust_BraintrustState as BraintrustState, braintrust_BraintrustStream as BraintrustStream, type braintrust_BraintrustStreamChunk as BraintrustStreamChunk, type braintrust_ChatPrompt as ChatPrompt, braintrust_CodeFunction as CodeFunction, braintrust_CodePrompt as CodePrompt, braintrust_CommentEvent as CommentEvent, type braintrust_CompiledPrompt as CompiledPrompt, type braintrust_CompiledPromptParams as CompiledPromptParams, type braintrust_CompletionPrompt as CompletionPrompt, type braintrust_CreateProjectOpts as CreateProjectOpts, type braintrust_DataSummary as DataSummary, braintrust_Dataset as Dataset, braintrust_DatasetRecord as DatasetRecord, type braintrust_DatasetSummary as DatasetSummary, type braintrust_DefaultMetadataType as DefaultMetadataType, type braintrust_DefaultPromptArgs as DefaultPromptArgs, type braintrust_EndSpanArgs as EndSpanArgs, braintrust_Eval as Eval, type braintrust_EvalCase as EvalCase, type braintrust_EvalResult as EvalResult, type braintrust_EvalScorer as EvalScorer, type braintrust_EvalScorerArgs as EvalScorerArgs, type braintrust_EvalTask as EvalTask, type braintrust_Evaluator as Evaluator, type braintrust_EvaluatorDef as EvaluatorDef, type braintrust_EvaluatorFile as EvaluatorFile, braintrust_Experiment as Experiment, braintrust_ExperimentLogFullArgs as ExperimentLogFullArgs, braintrust_ExperimentLogPartialArgs as ExperimentLogPartialArgs, type braintrust_ExperimentSummary as ExperimentSummary, type braintrust_Exportable as Exportable, braintrust_FailedHTTPResponse as FailedHTTPResponse, type braintrust_FullInitOptions as FullInitOptions, type braintrust_FullLoginOptions as FullLoginOptions, braintrust_IdField as IdField, type braintrust_InitOptions as InitOptions, braintrust_InputField as InputField, braintrust_InputsField as InputsField, type braintrust_InvokeFunctionArgs as InvokeFunctionArgs, type braintrust_InvokeReturn as InvokeReturn, braintrust_LEGACY_CACHED_HEADER as LEGACY_CACHED_HEADER, braintrust_LazyValue as LazyValue, braintrust_LogCommentFullArgs as LogCommentFullArgs, braintrust_LogFeedbackFullArgs as LogFeedbackFullArgs, type braintrust_LogOptions as LogOptions, braintrust_Logger as Logger, type braintrust_LoginOptions as LoginOptions, type braintrust_MetricSummary as MetricSummary, braintrust_NOOP_SPAN as NOOP_SPAN, braintrust_NoopSpan as NoopSpan, type braintrust_ObjectMetadata as ObjectMetadata, braintrust_OtherExperimentLogFields as OtherExperimentLogFields, braintrust_ParentExperimentIds as ParentExperimentIds, braintrust_ParentProjectLogIds as ParentProjectLogIds, braintrust_Project as Project, type braintrust_PromiseUnless as PromiseUnless, braintrust_Prompt as Prompt, braintrust_PromptBuilder as PromptBuilder, type braintrust_PromptOpts as PromptOpts, type braintrust_PromptRowWithId as PromptRowWithId, braintrust_ReadonlyExperiment as ReadonlyExperiment, braintrust_Reporter as Reporter, type braintrust_ReporterBody as ReporterBody, type braintrust_ScoreSummary as ScoreSummary, type braintrust_SerializedBraintrustState as SerializedBraintrustState, type braintrust_SetCurrentArg as SetCurrentArg, type braintrust_Span as Span, type braintrust_SpanContext as SpanContext, braintrust_SpanImpl as SpanImpl, type braintrust_StartSpanArgs as StartSpanArgs, braintrust_ToolBuilder as ToolBuilder, type braintrust_ToolFunctionDefinition as ToolFunctionDefinition, type braintrust_ToolOpts as ToolOpts, type braintrust_WithTransactionId as WithTransactionId, braintrust_X_CACHED_HEADER as X_CACHED_HEADER, braintrust__internalGetGlobalState as _internalGetGlobalState, braintrust__internalSetInitialState as _internalSetInitialState, braintrust_braintrustStreamChunkSchema as braintrustStreamChunkSchema, braintrust_buildLocalSummary as buildLocalSummary, braintrust_createFinalValuePassThroughStream as createFinalValuePassThroughStream, braintrust_currentExperiment as currentExperiment, braintrust_currentLogger as currentLogger, braintrust_currentSpan as currentSpan, braintrust_devNullWritableStream as devNullWritableStream, braintrust_flush as flush, braintrust_getSpanParentObject as getSpanParentObject, braintrust_init as init, braintrust_initDataset as initDataset, braintrust_initExperiment as initExperiment, braintrust_initLogger as initLogger, braintrust_invoke as invoke, braintrust_loadPrompt as loadPrompt, braintrust_log as log, braintrust_logError as logError, braintrust_login as login, braintrust_loginToState as loginToState, braintrust_newId as newId, braintrust_parseCachedHeader as parseCachedHeader, braintrust_permalink as permalink, braintrust_projects as projects, braintrust_renderMessage as renderMessage, braintrust_reportFailures as reportFailures, braintrust_setFetch as setFetch, braintrust_spanComponentsToObjectId as spanComponentsToObjectId, braintrust_startSpan as startSpan, braintrust_summarize as summarize, braintrust_toolFunctionDefinitionSchema as toolFunctionDefinitionSchema, braintrust_traceable as traceable, braintrust_traced as traced, braintrust_updateSpan as updateSpan, braintrust_withCurrent as withCurrent, braintrust_withDataset as withDataset, braintrust_withExperiment as withExperiment, braintrust_withLogger as withLogger, braintrust_wrapAISDKModel as wrapAISDKModel, braintrust_wrapOpenAI as wrapOpenAI, braintrust_wrapOpenAIv4 as wrapOpenAIv4, braintrust_wrapTraced as wrapTraced };
+  export { type braintrust_AnyDataset as AnyDataset, braintrust_Attachment as Attachment, type braintrust_AttachmentParams as AttachmentParams, type braintrust_BackgroundLoggerOpts as BackgroundLoggerOpts, braintrust_BaseExperiment as BaseExperiment, type braintrust_BaseMetadata as BaseMetadata, braintrust_BraintrustState as BraintrustState, braintrust_BraintrustStream as BraintrustStream, type braintrust_BraintrustStreamChunk as BraintrustStreamChunk, type braintrust_ChatPrompt as ChatPrompt, braintrust_CodeFunction as CodeFunction, braintrust_CodePrompt as CodePrompt, braintrust_CommentEvent as CommentEvent, type braintrust_CompiledPrompt as CompiledPrompt, type braintrust_CompiledPromptParams as CompiledPromptParams, type braintrust_CompletionPrompt as CompletionPrompt, type braintrust_CreateProjectOpts as CreateProjectOpts, type braintrust_DataSummary as DataSummary, braintrust_Dataset as Dataset, braintrust_DatasetRecord as DatasetRecord, type braintrust_DatasetSummary as DatasetSummary, type braintrust_DefaultMetadataType as DefaultMetadataType, type braintrust_DefaultPromptArgs as DefaultPromptArgs, type braintrust_EndSpanArgs as EndSpanArgs, braintrust_Eval as Eval, type braintrust_EvalCase as EvalCase, type braintrust_EvalResult as EvalResult, type braintrust_EvalScorer as EvalScorer, type braintrust_EvalScorerArgs as EvalScorerArgs, type braintrust_EvalTask as EvalTask, type braintrust_Evaluator as Evaluator, type braintrust_EvaluatorDef as EvaluatorDef, type braintrust_EvaluatorFile as EvaluatorFile, braintrust_Experiment as Experiment, braintrust_ExperimentLogFullArgs as ExperimentLogFullArgs, braintrust_ExperimentLogPartialArgs as ExperimentLogPartialArgs, type braintrust_ExperimentSummary as ExperimentSummary, type braintrust_Exportable as Exportable, braintrust_FailedHTTPResponse as FailedHTTPResponse, type braintrust_FullInitOptions as FullInitOptions, type braintrust_FullLoginOptions as FullLoginOptions, braintrust_IdField as IdField, type braintrust_InitOptions as InitOptions, braintrust_InputField as InputField, type braintrust_InvokeFunctionArgs as InvokeFunctionArgs, type braintrust_InvokeReturn as InvokeReturn, braintrust_LEGACY_CACHED_HEADER as LEGACY_CACHED_HEADER, braintrust_LazyValue as LazyValue, braintrust_LogCommentFullArgs as LogCommentFullArgs, braintrust_LogFeedbackFullArgs as LogFeedbackFullArgs, type braintrust_LogOptions as LogOptions, braintrust_Logger as Logger, type braintrust_LoginOptions as LoginOptions, type braintrust_MetricSummary as MetricSummary, braintrust_NOOP_SPAN as NOOP_SPAN, braintrust_NoopSpan as NoopSpan, type braintrust_ObjectMetadata as ObjectMetadata, braintrust_OtherExperimentLogFields as OtherExperimentLogFields, braintrust_ParentExperimentIds as ParentExperimentIds, braintrust_ParentProjectLogIds as ParentProjectLogIds, braintrust_Project as Project, type braintrust_PromiseUnless as PromiseUnless, braintrust_Prompt as Prompt, braintrust_PromptBuilder as PromptBuilder, type braintrust_PromptOpts as PromptOpts, type braintrust_PromptRowWithId as PromptRowWithId, braintrust_ReadonlyExperiment as ReadonlyExperiment, braintrust_Reporter as Reporter, type braintrust_ReporterBody as ReporterBody, type braintrust_ScoreSummary as ScoreSummary, type braintrust_SerializedBraintrustState as SerializedBraintrustState, type braintrust_SetCurrentArg as SetCurrentArg, type braintrust_Span as Span, type braintrust_SpanContext as SpanContext, braintrust_SpanImpl as SpanImpl, type braintrust_StartSpanArgs as StartSpanArgs, braintrust_ToolBuilder as ToolBuilder, type braintrust_ToolFunctionDefinition as ToolFunctionDefinition, type braintrust_ToolOpts as ToolOpts, type braintrust_WithTransactionId as WithTransactionId, braintrust_X_CACHED_HEADER as X_CACHED_HEADER, braintrust__exportsForTestingOnly as _exportsForTestingOnly, braintrust__internalGetGlobalState as _internalGetGlobalState, braintrust__internalSetInitialState as _internalSetInitialState, braintrust_braintrustStreamChunkSchema as braintrustStreamChunkSchema, braintrust_buildLocalSummary as buildLocalSummary, braintrust_createFinalValuePassThroughStream as createFinalValuePassThroughStream, braintrust_currentExperiment as currentExperiment, braintrust_currentLogger as currentLogger, braintrust_currentSpan as currentSpan, braintrust_devNullWritableStream as devNullWritableStream, braintrust_flush as flush, braintrust_getSpanParentObject as getSpanParentObject, braintrust_init as init, braintrust_initDataset as initDataset, braintrust_initExperiment as initExperiment, braintrust_initLogger as initLogger, braintrust_invoke as invoke, braintrust_loadPrompt as loadPrompt, braintrust_log as log, braintrust_logError as logError, braintrust_login as login, braintrust_loginToState as loginToState, braintrust_newId as newId, braintrust_parseCachedHeader as parseCachedHeader, braintrust_permalink as permalink, braintrust_projects as projects, braintrust_renderMessage as renderMessage, braintrust_reportFailures as reportFailures, braintrust_setFetch as setFetch, braintrust_spanComponentsToObjectId as spanComponentsToObjectId, braintrust_startSpan as startSpan, braintrust_summarize as summarize, braintrust_toolFunctionDefinitionSchema as toolFunctionDefinitionSchema, braintrust_traceable as traceable, braintrust_traced as traced, braintrust_updateSpan as updateSpan, braintrust_withCurrent as withCurrent, braintrust_withDataset as withDataset, braintrust_withExperiment as withExperiment, braintrust_withLogger as withLogger, braintrust_wrapAISDKModel as wrapAISDKModel, braintrust_wrapOpenAI as wrapOpenAI, braintrust_wrapOpenAIv4 as wrapOpenAIv4, braintrust_wrapTraced as wrapTraced };
 }
 
 /**
@@ -1926,4 +2068,4 @@ declare namespace braintrust {
  * @module braintrust
  */
 
-export { type AnyDataset, type BackgroundLoggerOpts, BaseExperiment, type BaseMetadata, BraintrustState, BraintrustStream, type BraintrustStreamChunk, type ChatPrompt, CodeFunction, CodePrompt, type CompiledPrompt, type CompiledPromptParams, type CompletionPrompt, type CreateProjectOpts, type DataSummary, Dataset, type DatasetSummary, type DefaultMetadataType, type DefaultPromptArgs, type EndSpanArgs, Eval, type EvalCase, type EvalResult, type EvalScorer, type EvalScorerArgs, type EvalTask, type Evaluator, type EvaluatorDef, type EvaluatorFile, Experiment, type ExperimentSummary, type Exportable, FailedHTTPResponse, type FullInitOptions, type FullLoginOptions, type InitOptions, type InvokeFunctionArgs, type InvokeReturn, LEGACY_CACHED_HEADER, LazyValue, type LogOptions, Logger, type LoginOptions, type MetricSummary, NOOP_SPAN, NoopSpan, type ObjectMetadata, Project, type PromiseUnless, Prompt, PromptBuilder, type PromptOpts, type PromptRowWithId, ReadonlyExperiment, Reporter, type ReporterBody, type ScoreSummary, type SerializedBraintrustState, type SetCurrentArg, type Span, type SpanContext, SpanImpl, type StartSpanArgs, ToolBuilder, type ToolFunctionDefinition, type ToolOpts, type WithTransactionId, X_CACHED_HEADER, _internalGetGlobalState, _internalSetInitialState, braintrustStreamChunkSchema, buildLocalSummary, createFinalValuePassThroughStream, currentExperiment, currentLogger, currentSpan, braintrust as default, devNullWritableStream, flush, getSpanParentObject, init, initDataset, initExperiment, initLogger, invoke, loadPrompt, log, logError, login, loginToState, newId, parseCachedHeader, permalink, projects, renderMessage, reportFailures, setFetch, spanComponentsToObjectId, startSpan, summarize, toolFunctionDefinitionSchema, traceable, traced, updateSpan, withCurrent, withDataset, withExperiment, withLogger, wrapAISDKModel, wrapOpenAI, wrapOpenAIv4, wrapTraced };
+export { type AnyDataset, Attachment, type AttachmentParams, type BackgroundLoggerOpts, BaseExperiment, type BaseMetadata, BraintrustState, BraintrustStream, type BraintrustStreamChunk, type ChatPrompt, CodeFunction, CodePrompt, type CompiledPrompt, type CompiledPromptParams, type CompletionPrompt, type CreateProjectOpts, type DataSummary, Dataset, type DatasetSummary, type DefaultMetadataType, type DefaultPromptArgs, type EndSpanArgs, Eval, type EvalCase, type EvalResult, type EvalScorer, type EvalScorerArgs, type EvalTask, type Evaluator, type EvaluatorDef, type EvaluatorFile, Experiment, type ExperimentSummary, type Exportable, FailedHTTPResponse, type FullInitOptions, type FullLoginOptions, type InitOptions, type InvokeFunctionArgs, type InvokeReturn, LEGACY_CACHED_HEADER, LazyValue, type LogOptions, Logger, type LoginOptions, type MetricSummary, NOOP_SPAN, NoopSpan, type ObjectMetadata, Project, type PromiseUnless, Prompt, PromptBuilder, type PromptOpts, type PromptRowWithId, ReadonlyExperiment, Reporter, type ReporterBody, type ScoreSummary, type SerializedBraintrustState, type SetCurrentArg, type Span, type SpanContext, SpanImpl, type StartSpanArgs, ToolBuilder, type ToolFunctionDefinition, type ToolOpts, type WithTransactionId, X_CACHED_HEADER, _exportsForTestingOnly, _internalGetGlobalState, _internalSetInitialState, braintrustStreamChunkSchema, buildLocalSummary, createFinalValuePassThroughStream, currentExperiment, currentLogger, currentSpan, braintrust as default, devNullWritableStream, flush, getSpanParentObject, init, initDataset, initExperiment, initLogger, invoke, loadPrompt, log, logError, login, loginToState, newId, parseCachedHeader, permalink, projects, renderMessage, reportFailures, setFetch, spanComponentsToObjectId, startSpan, summarize, toolFunctionDefinitionSchema, traceable, traced, updateSpan, withCurrent, withDataset, withExperiment, withLogger, wrapAISDKModel, wrapOpenAI, wrapOpenAIv4, wrapTraced };