braintrust 3.12.0 → 3.14.0

package/dev/dist/index.d.mts

@@ -118,6 +118,7 @@ declare const ObjectReference$1: z.ZodObject<{
     created?: string | null | undefined;
     _xact_id?: string | null | undefined;
 }>;
+type ObjectReferenceType$1 = z.infer<typeof ObjectReference$1>;
 
 type IdField = {
     id: string;
@@ -138,7 +139,7 @@ type OtherExperimentLogFields = {
     metadata: Record<string, unknown>;
     metrics: Record<string, unknown>;
     datasetRecordId: string;
-    origin: z.infer<typeof ObjectReference$1>;
+    origin: ObjectReferenceType$1;
     span_attributes: Record<string, unknown>;
     [ASYNC_SCORING_CONTROL_FIELD]: AsyncScoringControlType;
     [MERGE_PATHS_FIELD]: string[][];
@@ -180,6 +181,7 @@ type DatasetEvent = {
     tags?: string[];
     metadata?: unknown;
     created?: string;
+    origin?: ObjectReferenceType$1;
     id: string;
     dataset_id: string;
 } & ({
@@ -8861,17 +8863,15 @@ interface PromptKey {
     id?: string;
 }
 /**
- * A two-layer cache for Braintrust prompts with both in-memory and filesystem storage.
+ * A configurable cache for Braintrust prompts with optional in-memory and filesystem storage.
  *
- * This cache implements either a one or two-layer caching strategy:
- * 1. A fast in-memory LRU cache for frequently accessed prompts.
- * 2. An optional persistent filesystem-based cache that serves as a backing store.
+ * This cache can use either layer independently, both layers together, or no layers.
  */
 declare class PromptCache {
-    private readonly memoryCache;
+    private readonly memoryCache?;
     private readonly diskCache?;
     constructor(options: {
-        memoryCache: LRUCache<string, Prompt>;
+        memoryCache?: LRUCache<string, Prompt>;
         diskCache?: DiskCache<Prompt>;
     });
     /**
@@ -8898,10 +8898,10 @@ interface ParametersKey {
     id?: string;
 }
 declare class ParametersCache {
-    private readonly memoryCache;
+    private readonly memoryCache?;
     private readonly diskCache?;
     constructor(options: {
-        memoryCache: LRUCache<string, RemoteEvalParameters>;
+        memoryCache?: LRUCache<string, RemoteEvalParameters>;
         diskCache?: DiskCache<RemoteEvalParameters>;
     });
     get(key: ParametersKey): Promise<RemoteEvalParameters | undefined>;
@@ -8921,9 +8921,15 @@ declare class ParametersCache {
 interface CachedSpan {
     input?: unknown;
     output?: unknown;
+    expected?: unknown;
+    error?: unknown;
+    scores?: Record<string, unknown>;
+    metrics?: Record<string, unknown>;
     metadata?: Record<string, unknown>;
+    tags?: string[];
     span_id: string;
     span_parents?: string[];
+    is_root?: boolean | null;
     span_attributes?: {
         name?: string;
         type?: string;
@@ -11212,6 +11218,13 @@ interface LogOptions<IsAsyncFlush> {
     linkArgs?: LinkArgs;
 }
 type PromiseUnless<B, R> = B extends true ? R : Promise<Awaited<R>>;
+type DatasetPipelineDeferredJSONAttachmentHook = (data: unknown, options?: {
+    filename?: string;
+    pretty?: boolean;
+}) => object;
+declare global {
+    var __BT_DATASET_PIPELINE_DEFER_JSON_ATTACHMENT__: DatasetPipelineDeferredJSONAttachmentHook | undefined;
+}
 interface ParentSpanIds {
     spanId: string;
     rootSpanId: string;
@@ -11385,7 +11398,7 @@ interface LoginOptions {
      */
     appUrl?: string;
     /**
-     * The API key to use. If the parameter is not specified, will try to use the `BRAINTRUST_API_KEY` environment variable.
+     * The API key to use. If the parameter is not specified, will try to use the `BRAINTRUST_API_KEY` environment variable. In Node.js, if that is unset, will try the nearest `.env.braintrust` file in the current working directory or parent directories.
      */
     apiKey?: string;
     /**
@@ -11660,17 +11673,19 @@ declare class Dataset<IsLegacyDataset extends boolean = typeof DEFAULT_IS_LEGACY
      * about anything else that's relevant, that you can use to help find and analyze examples later. For example, you could log the
      * `prompt`, example's `id`, or anything else that would be useful to slice/dice later. The values in `metadata` can be any
      * JSON-serializable type, but its keys must be strings.
+     * @param event.origin (Optional) a reference to the source object this dataset record was derived from.
      * @param event.id (Optional) a unique identifier for the event. If you don't provide one, Braintrust will generate one for you.
      * @param event.output: (Deprecated) The output of your application. Use `expected` instead.
      * @returns The `id` of the logged record.
      */
-    insert({ input, expected, metadata, tags, id, output, }: {
+    insert({ input, expected, metadata, tags, id, output, origin, }: {
         readonly input?: unknown;
         readonly expected?: unknown;
         readonly tags?: string[];
         readonly metadata?: Record<string, unknown>;
         readonly id?: string;
         readonly output?: unknown;
+        readonly origin?: ObjectReferenceType;
     }): string;
     /**
      * Update fields of a single record in the dataset. The updated fields will be batched and uploaded behind the scenes.
@@ -11952,6 +11967,10 @@ interface GetThreadOptions {
      */
     preprocessor?: string;
 }
+interface GetSpansOptions {
+    spanType?: string[];
+    includeScorers?: boolean;
+}
 /**
  * Interface for trace objects that can be used by scorers.
  * Both the SDK's LocalTrace class and the API wrapper's WrapperTrace implement this.
@@ -11962,9 +11981,7 @@ interface Trace {
         object_id: string;
         root_span_id: string;
     };
-    getSpans(options?: {
-        spanType?: string[];
-    }): Promise<SpanData[]>;
+    getSpans(options?: GetSpansOptions): Promise<SpanData[]>;
     /**
      * Get the thread (preprocessed messages) for this trace.
      * Uses the project default preprocessor, falling back to the global "thread" preprocessor.

package/dev/dist/index.d.ts

@@ -118,6 +118,7 @@ declare const ObjectReference$1: z.ZodObject<{
     created?: string | null | undefined;
     _xact_id?: string | null | undefined;
 }>;
+type ObjectReferenceType$1 = z.infer<typeof ObjectReference$1>;
 
 type IdField = {
     id: string;
@@ -138,7 +139,7 @@ type OtherExperimentLogFields = {
     metadata: Record<string, unknown>;
     metrics: Record<string, unknown>;
     datasetRecordId: string;
-    origin: z.infer<typeof ObjectReference$1>;
+    origin: ObjectReferenceType$1;
     span_attributes: Record<string, unknown>;
     [ASYNC_SCORING_CONTROL_FIELD]: AsyncScoringControlType;
     [MERGE_PATHS_FIELD]: string[][];
@@ -180,6 +181,7 @@ type DatasetEvent = {
     tags?: string[];
     metadata?: unknown;
     created?: string;
+    origin?: ObjectReferenceType$1;
     id: string;
     dataset_id: string;
 } & ({
@@ -8861,17 +8863,15 @@ interface PromptKey {
     id?: string;
 }
 /**
- * A two-layer cache for Braintrust prompts with both in-memory and filesystem storage.
+ * A configurable cache for Braintrust prompts with optional in-memory and filesystem storage.
  *
- * This cache implements either a one or two-layer caching strategy:
- * 1. A fast in-memory LRU cache for frequently accessed prompts.
- * 2. An optional persistent filesystem-based cache that serves as a backing store.
+ * This cache can use either layer independently, both layers together, or no layers.
  */
 declare class PromptCache {
-    private readonly memoryCache;
+    private readonly memoryCache?;
     private readonly diskCache?;
     constructor(options: {
-        memoryCache: LRUCache<string, Prompt>;
+        memoryCache?: LRUCache<string, Prompt>;
         diskCache?: DiskCache<Prompt>;
     });
     /**
@@ -8898,10 +8898,10 @@ interface ParametersKey {
     id?: string;
 }
 declare class ParametersCache {
-    private readonly memoryCache;
+    private readonly memoryCache?;
     private readonly diskCache?;
     constructor(options: {
-        memoryCache: LRUCache<string, RemoteEvalParameters>;
+        memoryCache?: LRUCache<string, RemoteEvalParameters>;
         diskCache?: DiskCache<RemoteEvalParameters>;
     });
     get(key: ParametersKey): Promise<RemoteEvalParameters | undefined>;
@@ -8921,9 +8921,15 @@ declare class ParametersCache {
 interface CachedSpan {
     input?: unknown;
     output?: unknown;
+    expected?: unknown;
+    error?: unknown;
+    scores?: Record<string, unknown>;
+    metrics?: Record<string, unknown>;
     metadata?: Record<string, unknown>;
+    tags?: string[];
     span_id: string;
     span_parents?: string[];
+    is_root?: boolean | null;
     span_attributes?: {
         name?: string;
         type?: string;
@@ -11212,6 +11218,13 @@ interface LogOptions<IsAsyncFlush> {
     linkArgs?: LinkArgs;
 }
 type PromiseUnless<B, R> = B extends true ? R : Promise<Awaited<R>>;
+type DatasetPipelineDeferredJSONAttachmentHook = (data: unknown, options?: {
+    filename?: string;
+    pretty?: boolean;
+}) => object;
+declare global {
+    var __BT_DATASET_PIPELINE_DEFER_JSON_ATTACHMENT__: DatasetPipelineDeferredJSONAttachmentHook | undefined;
+}
 interface ParentSpanIds {
     spanId: string;
     rootSpanId: string;
@@ -11385,7 +11398,7 @@ interface LoginOptions {
      */
     appUrl?: string;
     /**
-     * The API key to use. If the parameter is not specified, will try to use the `BRAINTRUST_API_KEY` environment variable.
+     * The API key to use. If the parameter is not specified, will try to use the `BRAINTRUST_API_KEY` environment variable. In Node.js, if that is unset, will try the nearest `.env.braintrust` file in the current working directory or parent directories.
      */
     apiKey?: string;
     /**
@@ -11660,17 +11673,19 @@ declare class Dataset<IsLegacyDataset extends boolean = typeof DEFAULT_IS_LEGACY
      * about anything else that's relevant, that you can use to help find and analyze examples later. For example, you could log the
      * `prompt`, example's `id`, or anything else that would be useful to slice/dice later. The values in `metadata` can be any
      * JSON-serializable type, but its keys must be strings.
+     * @param event.origin (Optional) a reference to the source object this dataset record was derived from.
      * @param event.id (Optional) a unique identifier for the event. If you don't provide one, Braintrust will generate one for you.
      * @param event.output: (Deprecated) The output of your application. Use `expected` instead.
      * @returns The `id` of the logged record.
      */
-    insert({ input, expected, metadata, tags, id, output, }: {
+    insert({ input, expected, metadata, tags, id, output, origin, }: {
         readonly input?: unknown;
         readonly expected?: unknown;
         readonly tags?: string[];
         readonly metadata?: Record<string, unknown>;
         readonly id?: string;
         readonly output?: unknown;
+        readonly origin?: ObjectReferenceType;
     }): string;
     /**
      * Update fields of a single record in the dataset. The updated fields will be batched and uploaded behind the scenes.
@@ -11952,6 +11967,10 @@ interface GetThreadOptions {
      */
     preprocessor?: string;
 }
+interface GetSpansOptions {
+    spanType?: string[];
+    includeScorers?: boolean;
+}
 /**
  * Interface for trace objects that can be used by scorers.
  * Both the SDK's LocalTrace class and the API wrapper's WrapperTrace implement this.
@@ -11962,9 +11981,7 @@ interface Trace {
         object_id: string;
         root_span_id: string;
     };
-    getSpans(options?: {
-        spanType?: string[];
-    }): Promise<SpanData[]>;
+    getSpans(options?: GetSpansOptions): Promise<SpanData[]>;
     /**
      * Get the thread (preprocessed messages) for this trace.
      * Uses the project default preprocessor, falling back to the global "thread" preprocessor.