braintrust 0.0.190 → 0.0.192

package/dist/browser.d.mts

@@ -1,5 +1,5 @@
-import { LogFeedbackFullArgs, ExperimentEvent, BackgroundLogEvent, ExperimentLogFullArgs, ExperimentLogPartialArgs, IdField, SpanType, SpanComponentsV3, DEFAULT_IS_LEGACY_DATASET, TRANSACTION_ID_FIELD, TransactionId, SpanObjectTypeV3, DatasetRecord } from '@braintrust/core';
-import { GitMetadataSettings, AttachmentReference, AttachmentStatus, RepoInfo, PromptData, OpenAIMessage, Tools, AnyModelParam, Message, Prompt as Prompt$1, ModelParams, PromptSessionEvent, CallEventSchema, StreamingMode } from '@braintrust/core/typespecs';
+import { TRANSACTION_ID_FIELD, TransactionId, ExperimentEvent, DEFAULT_IS_LEGACY_DATASET, DatasetRecord, ExperimentLogFullArgs, ExperimentLogPartialArgs, LogFeedbackFullArgs, SpanType, IdField, BackgroundLogEvent, SpanComponentsV3, SpanObjectTypeV3 } from '@braintrust/core';
+import { GitMetadataSettings, Prompt as Prompt$1, PromptSessionEvent, PromptData, AnyModelParam, OpenAIMessage, Tools, Message, AttachmentReference, AttachmentStatus, BraintrustAttachmentReference, ExternalAttachmentReference, RepoInfo, ModelParams, CallEventSchema, StreamingMode } from '@braintrust/core/typespecs';
 import { z } from 'zod';
 
 interface IsoAsyncLocalStorage<T> {
@@ -477,6 +477,18 @@ interface AttachmentParams {
     contentType: string;
     state?: BraintrustState;
 }
+interface ExternalAttachmentParams {
+    url: string;
+    filename: string;
+    contentType: string;
+    state?: BraintrustState;
+}
+declare abstract class BaseAttachment {
+    readonly reference: AttachmentReference;
+    abstract upload(): Promise<AttachmentStatus>;
+    abstract data(): Promise<Blob>;
+    abstract debugInfo(): Record<string, unknown>;
+}
 /**
  * Represents an attachment to be uploaded and the associated metadata.
  * `Attachment` objects can be inserted anywhere in an event, allowing you to
@@ -484,11 +496,11 @@ interface AttachmentParams {
  * object storage and replace the `Attachment` object with an
  * `AttachmentReference`.
  */
-declare class Attachment {
+declare class Attachment extends BaseAttachment {
     /**
      * The object that replaces this `Attachment` at upload time.
      */
-    readonly reference: AttachmentReference;
+    readonly reference: BraintrustAttachmentReference;
     private readonly uploader;
     private readonly _data;
     private readonly state?;
@@ -536,6 +548,59 @@ declare class Attachment {
     private initUploader;
     private initData;
 }
+/**
+ * Represents an attachment that resides in an external object store and the associated metadata.
+ *
+ * `ExternalAttachment` objects can be inserted anywhere in an event, similar to
+ * `Attachment` objects, but they reference files that already exist in an external
+ * object store rather than requiring upload. The SDK will replace the `ExternalAttachment`
+ * object with an `AttachmentReference` during logging.
+ */
+declare class ExternalAttachment extends BaseAttachment {
+    /**
+     * The object that replaces this `ExternalAttachment` at upload time.
+     */
+    readonly reference: ExternalAttachmentReference;
+    private readonly _data;
+    private readonly state?;
+    /**
+     * Construct an external attachment.
+     *
+     * @param param A parameter object with:
+     *
+     * `url`: The fully qualified URL of the file in the external object store.
+     *
+     * `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.
+     *
+     * `contentType`: The MIME type of the file.
+     *
+     * `state`: (Optional) For internal use.
+     */
+    constructor({ url, filename, contentType, state }: ExternalAttachmentParams);
+    /**
+     * For ExternalAttachment, this is a no-op since the data already resides
+     * in the external object store. It marks the attachment as already uploaded.
+     *
+     * @returns The attachment status, which will always indicate success.
+     */
+    upload(): Promise<{
+        upload_status: "done";
+    }>;
+    /**
+     * The attachment contents. This is a lazy value that will read the attachment contents from the external object store on first access.
+     */
+    data(): Promise<Blob>;
+    /**
+     * 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 initData;
+}
 declare const attachmentMetadataSchema: z.ZodObject<{
     downloadUrl: z.ZodString;
     status: z.ZodObject<{
@@ -1076,17 +1141,19 @@ declare function withParent<R>(parent: string, callback: () => R, state?: Braint
 /**
  * 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.
+ * {@link Attachment} and {@link ExternalAttachment} 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.
+ * and `ExternalAttachment` objects 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;
+declare function extractAttachments(event: Record<string, any>, attachments: BaseAttachment[]): void;
 type WithTransactionId<R> = R & {
     [TRANSACTION_ID_FIELD]: TransactionId;
 };
@@ -1915,6 +1982,8 @@ type braintrust_Attachment = Attachment;
 declare const braintrust_Attachment: typeof Attachment;
 type braintrust_AttachmentParams = AttachmentParams;
 type braintrust_BackgroundLoggerOpts = BackgroundLoggerOpts;
+type braintrust_BaseAttachment = BaseAttachment;
+declare const braintrust_BaseAttachment: typeof BaseAttachment;
 type braintrust_BaseMetadata = BaseMetadata;
 type braintrust_BraintrustState = BraintrustState;
 declare const braintrust_BraintrustState: typeof BraintrustState;
@@ -1937,6 +2006,9 @@ type braintrust_Experiment = Experiment;
 declare const braintrust_Experiment: typeof Experiment;
 type braintrust_ExperimentSummary = ExperimentSummary;
 type braintrust_Exportable = Exportable;
+type braintrust_ExternalAttachment = ExternalAttachment;
+declare const braintrust_ExternalAttachment: typeof ExternalAttachment;
+type braintrust_ExternalAttachmentParams = ExternalAttachmentParams;
 type braintrust_FailedHTTPResponse = FailedHTTPResponse;
 declare const braintrust_FailedHTTPResponse: typeof FailedHTTPResponse;
 type braintrust_FullInitOptions<IsOpen extends boolean> = FullInitOptions<IsOpen>;
@@ -2015,7 +2087,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, braintrust_Attachment as Attachment, type braintrust_AttachmentParams as AttachmentParams, type braintrust_BackgroundLoggerOpts as BackgroundLoggerOpts, type braintrust_BaseMetadata as BaseMetadata, braintrust_BraintrustState as BraintrustState, braintrust_BraintrustStream as BraintrustStream, type braintrust_BraintrustStreamChunk as BraintrustStreamChunk, type braintrust_ChatPrompt as ChatPrompt, type braintrust_CompiledPrompt as CompiledPrompt, type braintrust_CompiledPromptParams as CompiledPromptParams, type braintrust_CompletionPrompt as CompletionPrompt, type braintrust_DataSummary as DataSummary, braintrust_Dataset as Dataset, type braintrust_DatasetSummary as DatasetSummary, type braintrust_DefaultMetadataType as DefaultMetadataType, type braintrust_DefaultPromptArgs as DefaultPromptArgs, type braintrust_EndSpanArgs as EndSpanArgs, type braintrust_EvalCase as EvalCase, braintrust_Experiment as Experiment, type braintrust_ExperimentSummary as ExperimentSummary, type braintrust_Exportable as Exportable, braintrust_FailedHTTPResponse as FailedHTTPResponse, type braintrust_FullInitOptions as FullInitOptions, type braintrust_FullLoginOptions as FullLoginOptions, type braintrust_InitOptions as InitOptions, type braintrust_InvokeFunctionArgs as InvokeFunctionArgs, type braintrust_InvokeReturn as InvokeReturn, braintrust_LEGACY_CACHED_HEADER as LEGACY_CACHED_HEADER, 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, type braintrust_PromiseUnless as PromiseUnless, braintrust_Prompt as Prompt, type braintrust_PromptRowWithId as PromptRowWithId, braintrust_ReadonlyAttachment as ReadonlyAttachment, braintrust_ReadonlyExperiment as ReadonlyExperiment, type braintrust_ScoreSummary as ScoreSummary, type braintrust_SerializedBraintrustState as SerializedBraintrustState, type braintrust_SetCurrentArg as SetCurrentArg, type braintrust_Span as Span, braintrust_SpanImpl as SpanImpl, type braintrust_StartSpanArgs as StartSpanArgs, 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_createFinalValuePassThroughStream as createFinalValuePassThroughStream, braintrust_currentExperiment as currentExperiment, braintrust_currentLogger as currentLogger, braintrust_currentSpan as currentSpan, braintrust_deserializePlainStringAsJSON as deserializePlainStringAsJSON, 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_initFunction as initFunction, 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_renderMessage as renderMessage, braintrust_renderPromptParams as renderPromptParams, braintrust_setFetch as setFetch, braintrust_spanComponentsToObjectId as spanComponentsToObjectId, braintrust_startSpan as startSpan, braintrust_summarize as summarize, 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_withParent as withParent, 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_BaseAttachment as BaseAttachment, type braintrust_BaseMetadata as BaseMetadata, braintrust_BraintrustState as BraintrustState, braintrust_BraintrustStream as BraintrustStream, type braintrust_BraintrustStreamChunk as BraintrustStreamChunk, type braintrust_ChatPrompt as ChatPrompt, type braintrust_CompiledPrompt as CompiledPrompt, type braintrust_CompiledPromptParams as CompiledPromptParams, type braintrust_CompletionPrompt as CompletionPrompt, type braintrust_DataSummary as DataSummary, braintrust_Dataset as Dataset, type braintrust_DatasetSummary as DatasetSummary, type braintrust_DefaultMetadataType as DefaultMetadataType, type braintrust_DefaultPromptArgs as DefaultPromptArgs, type braintrust_EndSpanArgs as EndSpanArgs, type braintrust_EvalCase as EvalCase, braintrust_Experiment as Experiment, type braintrust_ExperimentSummary as ExperimentSummary, type braintrust_Exportable as Exportable, braintrust_ExternalAttachment as ExternalAttachment, type braintrust_ExternalAttachmentParams as ExternalAttachmentParams, braintrust_FailedHTTPResponse as FailedHTTPResponse, type braintrust_FullInitOptions as FullInitOptions, type braintrust_FullLoginOptions as FullLoginOptions, type braintrust_InitOptions as InitOptions, type braintrust_InvokeFunctionArgs as InvokeFunctionArgs, type braintrust_InvokeReturn as InvokeReturn, braintrust_LEGACY_CACHED_HEADER as LEGACY_CACHED_HEADER, 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, type braintrust_PromiseUnless as PromiseUnless, braintrust_Prompt as Prompt, type braintrust_PromptRowWithId as PromptRowWithId, braintrust_ReadonlyAttachment as ReadonlyAttachment, braintrust_ReadonlyExperiment as ReadonlyExperiment, type braintrust_ScoreSummary as ScoreSummary, type braintrust_SerializedBraintrustState as SerializedBraintrustState, type braintrust_SetCurrentArg as SetCurrentArg, type braintrust_Span as Span, braintrust_SpanImpl as SpanImpl, type braintrust_StartSpanArgs as StartSpanArgs, 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_createFinalValuePassThroughStream as createFinalValuePassThroughStream, braintrust_currentExperiment as currentExperiment, braintrust_currentLogger as currentLogger, braintrust_currentSpan as currentSpan, braintrust_deserializePlainStringAsJSON as deserializePlainStringAsJSON, 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_initFunction as initFunction, 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_renderMessage as renderMessage, braintrust_renderPromptParams as renderPromptParams, braintrust_setFetch as setFetch, braintrust_spanComponentsToObjectId as spanComponentsToObjectId, braintrust_startSpan as startSpan, braintrust_summarize as summarize, 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_withParent as withParent, braintrust_wrapOpenAI as wrapOpenAI, braintrust_wrapOpenAIv4 as wrapOpenAIv4, braintrust_wrapTraced as wrapTraced };
 }
 
-export { type AnyDataset, Attachment, type AttachmentParams, type BackgroundLoggerOpts, type BaseMetadata, BraintrustState, BraintrustStream, type BraintrustStreamChunk, type ChatPrompt, type CompiledPrompt, type CompiledPromptParams, type CompletionPrompt, type DataSummary, Dataset, type DatasetSummary, type DefaultMetadataType, type DefaultPromptArgs, type EndSpanArgs, type EvalCase, Experiment, type ExperimentSummary, type Exportable, FailedHTTPResponse, type FullInitOptions, type FullLoginOptions, type InitOptions, type InvokeFunctionArgs, type InvokeReturn, LEGACY_CACHED_HEADER, type LogOptions, Logger, type LoginOptions, type MetricSummary, NOOP_SPAN, NoopSpan, type ObjectMetadata, type PromiseUnless, Prompt, type PromptRowWithId, ReadonlyAttachment, ReadonlyExperiment, type ScoreSummary, type SerializedBraintrustState, type SetCurrentArg, type Span, SpanImpl, type StartSpanArgs, type WithTransactionId, X_CACHED_HEADER, _exportsForTestingOnly, _internalGetGlobalState, _internalSetInitialState, braintrustStreamChunkSchema, createFinalValuePassThroughStream, currentExperiment, currentLogger, currentSpan, braintrust as default, deserializePlainStringAsJSON, devNullWritableStream, flush, getSpanParentObject, init, initDataset, initExperiment, initFunction, initLogger, invoke, loadPrompt, log, logError, login, loginToState, newId, parseCachedHeader, permalink, renderMessage, renderPromptParams, setFetch, spanComponentsToObjectId, startSpan, summarize, traceable, traced, updateSpan, withCurrent, withDataset, withExperiment, withLogger, withParent, wrapOpenAI, wrapOpenAIv4, wrapTraced };
+export { type AnyDataset, Attachment, type AttachmentParams, type BackgroundLoggerOpts, BaseAttachment, type BaseMetadata, BraintrustState, BraintrustStream, type BraintrustStreamChunk, type ChatPrompt, type CompiledPrompt, type CompiledPromptParams, type CompletionPrompt, type DataSummary, Dataset, type DatasetSummary, type DefaultMetadataType, type DefaultPromptArgs, type EndSpanArgs, type EvalCase, Experiment, type ExperimentSummary, type Exportable, ExternalAttachment, type ExternalAttachmentParams, FailedHTTPResponse, type FullInitOptions, type FullLoginOptions, type InitOptions, type InvokeFunctionArgs, type InvokeReturn, LEGACY_CACHED_HEADER, type LogOptions, Logger, type LoginOptions, type MetricSummary, NOOP_SPAN, NoopSpan, type ObjectMetadata, type PromiseUnless, Prompt, type PromptRowWithId, ReadonlyAttachment, ReadonlyExperiment, type ScoreSummary, type SerializedBraintrustState, type SetCurrentArg, type Span, SpanImpl, type StartSpanArgs, type WithTransactionId, X_CACHED_HEADER, _exportsForTestingOnly, _internalGetGlobalState, _internalSetInitialState, braintrustStreamChunkSchema, createFinalValuePassThroughStream, currentExperiment, currentLogger, currentSpan, braintrust as default, deserializePlainStringAsJSON, devNullWritableStream, flush, getSpanParentObject, init, initDataset, initExperiment, initFunction, initLogger, invoke, loadPrompt, log, logError, login, loginToState, newId, parseCachedHeader, permalink, renderMessage, renderPromptParams, setFetch, spanComponentsToObjectId, startSpan, summarize, traceable, traced, updateSpan, withCurrent, withDataset, withExperiment, withLogger, withParent, wrapOpenAI, wrapOpenAIv4, wrapTraced };

package/dist/browser.d.ts

@@ -1,5 +1,5 @@
-import { LogFeedbackFullArgs, ExperimentEvent, BackgroundLogEvent, ExperimentLogFullArgs, ExperimentLogPartialArgs, IdField, SpanType, SpanComponentsV3, DEFAULT_IS_LEGACY_DATASET, TRANSACTION_ID_FIELD, TransactionId, SpanObjectTypeV3, DatasetRecord } from '@braintrust/core';
-import { GitMetadataSettings, AttachmentReference, AttachmentStatus, RepoInfo, PromptData, OpenAIMessage, Tools, AnyModelParam, Message, Prompt as Prompt$1, ModelParams, PromptSessionEvent, CallEventSchema, StreamingMode } from '@braintrust/core/typespecs';
+import { TRANSACTION_ID_FIELD, TransactionId, ExperimentEvent, DEFAULT_IS_LEGACY_DATASET, DatasetRecord, ExperimentLogFullArgs, ExperimentLogPartialArgs, LogFeedbackFullArgs, SpanType, IdField, BackgroundLogEvent, SpanComponentsV3, SpanObjectTypeV3 } from '@braintrust/core';
+import { GitMetadataSettings, Prompt as Prompt$1, PromptSessionEvent, PromptData, AnyModelParam, OpenAIMessage, Tools, Message, AttachmentReference, AttachmentStatus, BraintrustAttachmentReference, ExternalAttachmentReference, RepoInfo, ModelParams, CallEventSchema, StreamingMode } from '@braintrust/core/typespecs';
 import { z } from 'zod';
 
 interface IsoAsyncLocalStorage<T> {
@@ -477,6 +477,18 @@ interface AttachmentParams {
     contentType: string;
     state?: BraintrustState;
 }
+interface ExternalAttachmentParams {
+    url: string;
+    filename: string;
+    contentType: string;
+    state?: BraintrustState;
+}
+declare abstract class BaseAttachment {
+    readonly reference: AttachmentReference;
+    abstract upload(): Promise<AttachmentStatus>;
+    abstract data(): Promise<Blob>;
+    abstract debugInfo(): Record<string, unknown>;
+}
 /**
  * Represents an attachment to be uploaded and the associated metadata.
  * `Attachment` objects can be inserted anywhere in an event, allowing you to
@@ -484,11 +496,11 @@ interface AttachmentParams {
  * object storage and replace the `Attachment` object with an
  * `AttachmentReference`.
  */
-declare class Attachment {
+declare class Attachment extends BaseAttachment {
     /**
      * The object that replaces this `Attachment` at upload time.
      */
-    readonly reference: AttachmentReference;
+    readonly reference: BraintrustAttachmentReference;
     private readonly uploader;
     private readonly _data;
     private readonly state?;
@@ -536,6 +548,59 @@ declare class Attachment {
     private initUploader;
     private initData;
 }
+/**
+ * Represents an attachment that resides in an external object store and the associated metadata.
+ *
+ * `ExternalAttachment` objects can be inserted anywhere in an event, similar to
+ * `Attachment` objects, but they reference files that already exist in an external
+ * object store rather than requiring upload. The SDK will replace the `ExternalAttachment`
+ * object with an `AttachmentReference` during logging.
+ */
+declare class ExternalAttachment extends BaseAttachment {
+    /**
+     * The object that replaces this `ExternalAttachment` at upload time.
+     */
+    readonly reference: ExternalAttachmentReference;
+    private readonly _data;
+    private readonly state?;
+    /**
+     * Construct an external attachment.
+     *
+     * @param param A parameter object with:
+     *
+     * `url`: The fully qualified URL of the file in the external object store.
+     *
+     * `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.
+     *
+     * `contentType`: The MIME type of the file.
+     *
+     * `state`: (Optional) For internal use.
+     */
+    constructor({ url, filename, contentType, state }: ExternalAttachmentParams);
+    /**
+     * For ExternalAttachment, this is a no-op since the data already resides
+     * in the external object store. It marks the attachment as already uploaded.
+     *
+     * @returns The attachment status, which will always indicate success.
+     */
+    upload(): Promise<{
+        upload_status: "done";
+    }>;
+    /**
+     * The attachment contents. This is a lazy value that will read the attachment contents from the external object store on first access.
+     */
+    data(): Promise<Blob>;
+    /**
+     * 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 initData;
+}
 declare const attachmentMetadataSchema: z.ZodObject<{
     downloadUrl: z.ZodString;
     status: z.ZodObject<{
@@ -1076,17 +1141,19 @@ declare function withParent<R>(parent: string, callback: () => R, state?: Braint
 /**
  * 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.
+ * {@link Attachment} and {@link ExternalAttachment} 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.
+ * and `ExternalAttachment` objects 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;
+declare function extractAttachments(event: Record<string, any>, attachments: BaseAttachment[]): void;
 type WithTransactionId<R> = R & {
     [TRANSACTION_ID_FIELD]: TransactionId;
 };
@@ -1915,6 +1982,8 @@ type braintrust_Attachment = Attachment;
 declare const braintrust_Attachment: typeof Attachment;
 type braintrust_AttachmentParams = AttachmentParams;
 type braintrust_BackgroundLoggerOpts = BackgroundLoggerOpts;
+type braintrust_BaseAttachment = BaseAttachment;
+declare const braintrust_BaseAttachment: typeof BaseAttachment;
 type braintrust_BaseMetadata = BaseMetadata;
 type braintrust_BraintrustState = BraintrustState;
 declare const braintrust_BraintrustState: typeof BraintrustState;
@@ -1937,6 +2006,9 @@ type braintrust_Experiment = Experiment;
 declare const braintrust_Experiment: typeof Experiment;
 type braintrust_ExperimentSummary = ExperimentSummary;
 type braintrust_Exportable = Exportable;
+type braintrust_ExternalAttachment = ExternalAttachment;
+declare const braintrust_ExternalAttachment: typeof ExternalAttachment;
+type braintrust_ExternalAttachmentParams = ExternalAttachmentParams;
 type braintrust_FailedHTTPResponse = FailedHTTPResponse;
 declare const braintrust_FailedHTTPResponse: typeof FailedHTTPResponse;
 type braintrust_FullInitOptions<IsOpen extends boolean> = FullInitOptions<IsOpen>;
@@ -2015,7 +2087,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, braintrust_Attachment as Attachment, type braintrust_AttachmentParams as AttachmentParams, type braintrust_BackgroundLoggerOpts as BackgroundLoggerOpts, type braintrust_BaseMetadata as BaseMetadata, braintrust_BraintrustState as BraintrustState, braintrust_BraintrustStream as BraintrustStream, type braintrust_BraintrustStreamChunk as BraintrustStreamChunk, type braintrust_ChatPrompt as ChatPrompt, type braintrust_CompiledPrompt as CompiledPrompt, type braintrust_CompiledPromptParams as CompiledPromptParams, type braintrust_CompletionPrompt as CompletionPrompt, type braintrust_DataSummary as DataSummary, braintrust_Dataset as Dataset, type braintrust_DatasetSummary as DatasetSummary, type braintrust_DefaultMetadataType as DefaultMetadataType, type braintrust_DefaultPromptArgs as DefaultPromptArgs, type braintrust_EndSpanArgs as EndSpanArgs, type braintrust_EvalCase as EvalCase, braintrust_Experiment as Experiment, type braintrust_ExperimentSummary as ExperimentSummary, type braintrust_Exportable as Exportable, braintrust_FailedHTTPResponse as FailedHTTPResponse, type braintrust_FullInitOptions as FullInitOptions, type braintrust_FullLoginOptions as FullLoginOptions, type braintrust_InitOptions as InitOptions, type braintrust_InvokeFunctionArgs as InvokeFunctionArgs, type braintrust_InvokeReturn as InvokeReturn, braintrust_LEGACY_CACHED_HEADER as LEGACY_CACHED_HEADER, 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, type braintrust_PromiseUnless as PromiseUnless, braintrust_Prompt as Prompt, type braintrust_PromptRowWithId as PromptRowWithId, braintrust_ReadonlyAttachment as ReadonlyAttachment, braintrust_ReadonlyExperiment as ReadonlyExperiment, type braintrust_ScoreSummary as ScoreSummary, type braintrust_SerializedBraintrustState as SerializedBraintrustState, type braintrust_SetCurrentArg as SetCurrentArg, type braintrust_Span as Span, braintrust_SpanImpl as SpanImpl, type braintrust_StartSpanArgs as StartSpanArgs, 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_createFinalValuePassThroughStream as createFinalValuePassThroughStream, braintrust_currentExperiment as currentExperiment, braintrust_currentLogger as currentLogger, braintrust_currentSpan as currentSpan, braintrust_deserializePlainStringAsJSON as deserializePlainStringAsJSON, 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_initFunction as initFunction, 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_renderMessage as renderMessage, braintrust_renderPromptParams as renderPromptParams, braintrust_setFetch as setFetch, braintrust_spanComponentsToObjectId as spanComponentsToObjectId, braintrust_startSpan as startSpan, braintrust_summarize as summarize, 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_withParent as withParent, 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_BaseAttachment as BaseAttachment, type braintrust_BaseMetadata as BaseMetadata, braintrust_BraintrustState as BraintrustState, braintrust_BraintrustStream as BraintrustStream, type braintrust_BraintrustStreamChunk as BraintrustStreamChunk, type braintrust_ChatPrompt as ChatPrompt, type braintrust_CompiledPrompt as CompiledPrompt, type braintrust_CompiledPromptParams as CompiledPromptParams, type braintrust_CompletionPrompt as CompletionPrompt, type braintrust_DataSummary as DataSummary, braintrust_Dataset as Dataset, type braintrust_DatasetSummary as DatasetSummary, type braintrust_DefaultMetadataType as DefaultMetadataType, type braintrust_DefaultPromptArgs as DefaultPromptArgs, type braintrust_EndSpanArgs as EndSpanArgs, type braintrust_EvalCase as EvalCase, braintrust_Experiment as Experiment, type braintrust_ExperimentSummary as ExperimentSummary, type braintrust_Exportable as Exportable, braintrust_ExternalAttachment as ExternalAttachment, type braintrust_ExternalAttachmentParams as ExternalAttachmentParams, braintrust_FailedHTTPResponse as FailedHTTPResponse, type braintrust_FullInitOptions as FullInitOptions, type braintrust_FullLoginOptions as FullLoginOptions, type braintrust_InitOptions as InitOptions, type braintrust_InvokeFunctionArgs as InvokeFunctionArgs, type braintrust_InvokeReturn as InvokeReturn, braintrust_LEGACY_CACHED_HEADER as LEGACY_CACHED_HEADER, 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, type braintrust_PromiseUnless as PromiseUnless, braintrust_Prompt as Prompt, type braintrust_PromptRowWithId as PromptRowWithId, braintrust_ReadonlyAttachment as ReadonlyAttachment, braintrust_ReadonlyExperiment as ReadonlyExperiment, type braintrust_ScoreSummary as ScoreSummary, type braintrust_SerializedBraintrustState as SerializedBraintrustState, type braintrust_SetCurrentArg as SetCurrentArg, type braintrust_Span as Span, braintrust_SpanImpl as SpanImpl, type braintrust_StartSpanArgs as StartSpanArgs, 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_createFinalValuePassThroughStream as createFinalValuePassThroughStream, braintrust_currentExperiment as currentExperiment, braintrust_currentLogger as currentLogger, braintrust_currentSpan as currentSpan, braintrust_deserializePlainStringAsJSON as deserializePlainStringAsJSON, 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_initFunction as initFunction, 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_renderMessage as renderMessage, braintrust_renderPromptParams as renderPromptParams, braintrust_setFetch as setFetch, braintrust_spanComponentsToObjectId as spanComponentsToObjectId, braintrust_startSpan as startSpan, braintrust_summarize as summarize, 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_withParent as withParent, braintrust_wrapOpenAI as wrapOpenAI, braintrust_wrapOpenAIv4 as wrapOpenAIv4, braintrust_wrapTraced as wrapTraced };
 }
 
-export { type AnyDataset, Attachment, type AttachmentParams, type BackgroundLoggerOpts, type BaseMetadata, BraintrustState, BraintrustStream, type BraintrustStreamChunk, type ChatPrompt, type CompiledPrompt, type CompiledPromptParams, type CompletionPrompt, type DataSummary, Dataset, type DatasetSummary, type DefaultMetadataType, type DefaultPromptArgs, type EndSpanArgs, type EvalCase, Experiment, type ExperimentSummary, type Exportable, FailedHTTPResponse, type FullInitOptions, type FullLoginOptions, type InitOptions, type InvokeFunctionArgs, type InvokeReturn, LEGACY_CACHED_HEADER, type LogOptions, Logger, type LoginOptions, type MetricSummary, NOOP_SPAN, NoopSpan, type ObjectMetadata, type PromiseUnless, Prompt, type PromptRowWithId, ReadonlyAttachment, ReadonlyExperiment, type ScoreSummary, type SerializedBraintrustState, type SetCurrentArg, type Span, SpanImpl, type StartSpanArgs, type WithTransactionId, X_CACHED_HEADER, _exportsForTestingOnly, _internalGetGlobalState, _internalSetInitialState, braintrustStreamChunkSchema, createFinalValuePassThroughStream, currentExperiment, currentLogger, currentSpan, braintrust as default, deserializePlainStringAsJSON, devNullWritableStream, flush, getSpanParentObject, init, initDataset, initExperiment, initFunction, initLogger, invoke, loadPrompt, log, logError, login, loginToState, newId, parseCachedHeader, permalink, renderMessage, renderPromptParams, setFetch, spanComponentsToObjectId, startSpan, summarize, traceable, traced, updateSpan, withCurrent, withDataset, withExperiment, withLogger, withParent, wrapOpenAI, wrapOpenAIv4, wrapTraced };
+export { type AnyDataset, Attachment, type AttachmentParams, type BackgroundLoggerOpts, BaseAttachment, type BaseMetadata, BraintrustState, BraintrustStream, type BraintrustStreamChunk, type ChatPrompt, type CompiledPrompt, type CompiledPromptParams, type CompletionPrompt, type DataSummary, Dataset, type DatasetSummary, type DefaultMetadataType, type DefaultPromptArgs, type EndSpanArgs, type EvalCase, Experiment, type ExperimentSummary, type Exportable, ExternalAttachment, type ExternalAttachmentParams, FailedHTTPResponse, type FullInitOptions, type FullLoginOptions, type InitOptions, type InvokeFunctionArgs, type InvokeReturn, LEGACY_CACHED_HEADER, type LogOptions, Logger, type LoginOptions, type MetricSummary, NOOP_SPAN, NoopSpan, type ObjectMetadata, type PromiseUnless, Prompt, type PromptRowWithId, ReadonlyAttachment, ReadonlyExperiment, type ScoreSummary, type SerializedBraintrustState, type SetCurrentArg, type Span, SpanImpl, type StartSpanArgs, type WithTransactionId, X_CACHED_HEADER, _exportsForTestingOnly, _internalGetGlobalState, _internalSetInitialState, braintrustStreamChunkSchema, createFinalValuePassThroughStream, currentExperiment, currentLogger, currentSpan, braintrust as default, deserializePlainStringAsJSON, devNullWritableStream, flush, getSpanParentObject, init, initDataset, initExperiment, initFunction, initLogger, invoke, loadPrompt, log, logError, login, loginToState, newId, parseCachedHeader, permalink, renderMessage, renderPromptParams, setFetch, spanComponentsToObjectId, startSpan, summarize, traceable, traced, updateSpan, withCurrent, withDataset, withExperiment, withLogger, withParent, wrapOpenAI, wrapOpenAIv4, wrapTraced };

package/dist/browser.js

@@ -31,10 +31,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var browser_exports = {};
 __export(browser_exports, {
   Attachment: () => Attachment,
+  BaseAttachment: () => BaseAttachment,
   BraintrustState: () => BraintrustState,
   BraintrustStream: () => BraintrustStream,
   Dataset: () => Dataset,
   Experiment: () => Experiment,
+  ExternalAttachment: () => ExternalAttachment,
   FailedHTTPResponse: () => FailedHTTPResponse,
   LEGACY_CACHED_HEADER: () => LEGACY_CACHED_HEADER,
   Logger: () => Logger,
@@ -1006,7 +1008,10 @@ var HTTPConnection = class _HTTPConnection {
     return await resp.json();
   }
 };
-var Attachment = class {
+var BaseAttachment = class {
+  reference;
+};
+var Attachment = class extends BaseAttachment {
   /**
    * The object that replaces this `Attachment` at upload time.
    */
@@ -1034,6 +1039,7 @@ var Attachment = class {
    * `state`: (Optional) For internal use.
    */
   constructor({ data, filename, contentType, state }) {
+    super();
     this.reference = {
       type: import_typespecs2.BRAINTRUST_ATTACHMENT,
       filename,
@@ -1176,6 +1182,73 @@ with a Blob/ArrayBuffer, or run the program on Node.js.`
     }
   }
 };
+var ExternalAttachment = class extends BaseAttachment {
+  /**
+   * The object that replaces this `ExternalAttachment` at upload time.
+   */
+  reference;
+  _data;
+  state;
+  /**
+   * Construct an external attachment.
+   *
+   * @param param A parameter object with:
+   *
+   * `url`: The fully qualified URL of the file in the external object store.
+   *
+   * `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.
+   *
+   * `contentType`: The MIME type of the file.
+   *
+   * `state`: (Optional) For internal use.
+   */
+  constructor({ url, filename, contentType, state }) {
+    super();
+    this.reference = {
+      type: import_typespecs2.EXTERNAL_ATTACHMENT,
+      filename,
+      content_type: contentType,
+      url
+    };
+    this._data = this.initData();
+  }
+  /**
+   * For ExternalAttachment, this is a no-op since the data already resides
+   * in the external object store. It marks the attachment as already uploaded.
+   *
+   * @returns The attachment status, which will always indicate success.
+   */
+  async upload() {
+    return { upload_status: "done" };
+  }
+  /**
+   * The attachment contents. This is a lazy value that will read the attachment contents from the external object store on first access.
+   */
+  async data() {
+    return this._data.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 {
+      url: this.reference.url,
+      reference: this.reference,
+      state: this.state
+    };
+  }
+  initData() {
+    return new LazyValue(async () => {
+      const readonly = new ReadonlyAttachment(this.reference, this.state);
+      return await readonly.data();
+    });
+  }
+};
 var attachmentMetadataSchema = import_zod2.z.object({
   downloadUrl: import_zod2.z.string(),
   status: import_typespecs2.attachmentStatusSchema
@@ -1214,12 +1287,17 @@ var ReadonlyAttachment = class {
   async metadata() {
     const state = this.state ?? _globalState;
     await state.login({});
-    const resp = await state.apiConn().get("/attachment", {
-      key: this.reference.key,
+    let params = {
       filename: this.reference.filename,
       content_type: this.reference.content_type,
       org_id: state.orgId || ""
-    });
+    };
+    if (this.reference.type === "braintrust_attachment") {
+      params.key = this.reference.key;
+    } else if (this.reference.type === "external_attachment") {
+      params.url = this.reference.url;
+    }
+    const resp = await state.apiConn().get("/attachment", params);
     if (!resp.ok) {
       const errorStr = JSON.stringify(resp);
       throw new Error(`Invalid response from API server: ${errorStr}`);
@@ -1668,8 +1746,7 @@ var Logger = class {
   }
 };
 function castLogger(logger, asyncFlush) {
-  if (logger === void 0)
-    return void 0;
+  if (logger === void 0) return void 0;
   if (asyncFlush !== void 0 && !!asyncFlush !== !!logger.asyncFlush) {
     throw new Error(
       `Asserted asyncFlush setting ${asyncFlush} does not match stored logger's setting ${logger.asyncFlush}`
@@ -2818,7 +2895,7 @@ function deepCopyEvent(event) {
       return `<dataset>`;
     } else if (v instanceof Logger) {
       return `<logger>`;
-    } else if (v instanceof Attachment) {
+    } else if (v instanceof BaseAttachment) {
       const idx = attachments.push(v);
       return { [IDENTIFIER]: idx - 1 };
     } else if (v instanceof ReadonlyAttachment) {
@@ -2837,7 +2914,7 @@ function deepCopyEvent(event) {
 }
 function extractAttachments(event, attachments) {
   for (const [key, value] of Object.entries(event)) {
-    if (value instanceof Attachment) {
+    if (value instanceof BaseAttachment) {
       attachments.push(value);
       event[key] = value.reference;
       continue;
@@ -3300,10 +3377,8 @@ var SpanImpl = class _SpanImpl {
     const { id: eventId, ...event } = rawEvent;
     const callerLocation = isomorph_default.getCallerLocation();
     const name = (() => {
-      if (args.name)
-        return args.name;
-      if (!args.parentSpanIds)
-        return "root";
+      if (args.name) return args.name;
+      if (!args.parentSpanIds) return "root";
       if (callerLocation) {
         const pathComponents = callerLocation.caller_filename.split("/");
         const filename = pathComponents[pathComponents.length - 1];
@@ -3992,10 +4067,12 @@ function configureBrowser() {
 var exports_browser_exports = {};
 __export(exports_browser_exports, {
   Attachment: () => Attachment,
+  BaseAttachment: () => BaseAttachment,
   BraintrustState: () => BraintrustState,
   BraintrustStream: () => BraintrustStream,
   Dataset: () => Dataset,
   Experiment: () => Experiment,
+  ExternalAttachment: () => ExternalAttachment,
   FailedHTTPResponse: () => FailedHTTPResponse,
   LEGACY_CACHED_HEADER: () => LEGACY_CACHED_HEADER,
   Logger: () => Logger,
@@ -4533,10 +4610,12 @@ var browser_default = exports_browser_exports;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Attachment,
+  BaseAttachment,
   BraintrustState,
   BraintrustStream,
   Dataset,
   Experiment,
+  ExternalAttachment,
   FailedHTTPResponse,
   LEGACY_CACHED_HEADER,
   Logger,