braintrust 0.0.141-dev1 → 0.0.142

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,5 +1,5 @@
1
1
  import { GitMetadataSettings, LogFeedbackFullArgs, BackgroundLogEvent, ExperimentEvent, ExperimentLogFullArgs, ExperimentLogPartialArgs, IdField, SpanType, RepoInfo, DEFAULT_IS_LEGACY_DATASET, TRANSACTION_ID_FIELD, TransactionId, SpanObjectTypeV2, DatasetRecord } from '@braintrust/core';
2
- import { PromptData, OpenAIMessage, Tools, AnyModelParam, Prompt as Prompt$1, PromptSessionEvent, FunctionId } from '@braintrust/core/typespecs';
2
+ import { PromptData, OpenAIMessage, Tools, AnyModelParam, Prompt as Prompt$1, PromptSessionEvent } from '@braintrust/core/typespecs';
3
3
  import { z } from 'zod';
4
4
 
5
5
  interface IsoAsyncLocalStorage<T> {
@@ -137,7 +137,7 @@ declare const loginSchema: z.ZodObject<{
137
137
  appUrl: z.ZodString;
138
138
  appPublicUrl: z.ZodString;
139
139
  orgName: z.ZodString;
140
- logUrl: z.ZodString;
140
+ apiUrl: z.ZodString;
141
141
  proxyUrl: z.ZodString;
142
142
  loginToken: z.ZodString;
143
143
  orgId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -155,7 +155,7 @@ declare const loginSchema: z.ZodObject<{
155
155
  appUrl: string;
156
156
  appPublicUrl: string;
157
157
  orgName: string;
158
- logUrl: string;
158
+ apiUrl: string;
159
159
  proxyUrl: string;
160
160
  loginToken: string;
161
161
  orgId?: string | null | undefined;
@@ -167,7 +167,7 @@ declare const loginSchema: z.ZodObject<{
167
167
  appUrl: string;
168
168
  appPublicUrl: string;
169
169
  orgName: string;
170
- logUrl: string;
170
+ apiUrl: string;
171
171
  proxyUrl: string;
172
172
  loginToken: string;
173
173
  orgId?: string | null | undefined;
@@ -189,13 +189,13 @@ declare class BraintrustState {
189
189
  loginToken: string | null;
190
190
  orgId: string | null;
191
191
  orgName: string | null;
192
- logUrl: string | null;
192
+ apiUrl: string | null;
193
193
  proxyUrl: string | null;
194
194
  loggedIn: boolean;
195
195
  gitMetadataSettings?: GitMetadataSettings;
196
196
  fetch: typeof globalThis.fetch;
197
+ private _appConn;
197
198
  private _apiConn;
198
- private _logConn;
199
199
  private _proxyConn;
200
200
  constructor(loginParams: LoginOptions);
201
201
  resetLoginInfo(): void;
@@ -206,11 +206,11 @@ declare class BraintrustState {
206
206
  login(loginParams: LoginOptions & {
207
207
  forceLogin?: boolean;
208
208
  }): Promise<void>;
209
+ appConn(): HTTPConnection;
209
210
  apiConn(): HTTPConnection;
210
- logConn(): HTTPConnection;
211
211
  proxyConn(): HTTPConnection;
212
212
  bgLogger(): BackgroundLogger;
213
- loginReplaceLogConn(logConn: HTTPConnection): void;
213
+ loginReplaceApiConn(apiConn: HTTPConnection): void;
214
214
  }
215
215
  declare function _internalSetInitialState(): void;
216
216
  declare const _internalGetGlobalState: () => BraintrustState;
@@ -271,7 +271,6 @@ declare class Logger<IsAsyncFlush extends boolean> implements Exportable {
271
271
  get project(): Promise<ObjectMetadata>;
272
272
  get id(): Promise<string>;
273
273
  private parentObjectType;
274
- private triggerWaitUntilFlush;
275
274
  /**
276
275
  * Log a single event. The event will be batched and uploaded behind the scenes if `logOptions.asyncFlush` is true.
277
276
  *
@@ -325,7 +324,7 @@ declare class Logger<IsAsyncFlush extends boolean> implements Exportable {
325
324
  get asyncFlush(): IsAsyncFlush | undefined;
326
325
  }
327
326
  declare class BackgroundLogger {
328
- private logConn;
327
+ private apiConn;
329
328
  private items;
330
329
  private activeFlush;
331
330
  private activeFlushResolved;
@@ -339,7 +338,7 @@ declare class BackgroundLogger {
339
338
  failedPublishPayloadsDir: string | undefined;
340
339
  allPublishPayloadsDir: string | undefined;
341
340
  private queueDropLoggingState;
342
- constructor(logConn: LazyValue<HTTPConnection>);
341
+ constructor(apiConn: LazyValue<HTTPConnection>);
343
342
  log(items: LazyValue<BackgroundLogEvent>[]): void;
344
343
  flush(): Promise<void>;
345
344
  private flushOnce;
@@ -350,7 +349,7 @@ declare class BackgroundLogger {
350
349
  private static writePayloadToDir;
351
350
  private triggerActiveFlush;
352
351
  private logFailedPayloadsDir;
353
- internalReplaceLogConn(logConn: HTTPConnection): void;
352
+ internalReplaceApiConn(apiConn: HTTPConnection): void;
354
353
  }
355
354
  type InitOpenOption<IsOpen extends boolean> = {
356
355
  open?: IsOpen;
@@ -1024,33 +1023,155 @@ interface DatasetSummary {
1024
1023
  dataSummary: DataSummary;
1025
1024
  }
1026
1025
 
1027
- type BraintrustStreamChunk = {
1026
+ declare const braintrustStreamChunkSchema: z.ZodUnion<[z.ZodObject<{
1027
+ type: z.ZodLiteral<"text_delta">;
1028
+ data: z.ZodString;
1029
+ }, "strip", z.ZodTypeAny, {
1030
+ data: string;
1031
+ type: "text_delta";
1032
+ }, {
1033
+ data: string;
1028
1034
  type: "text_delta";
1035
+ }>, z.ZodObject<{
1036
+ type: z.ZodLiteral<"json_delta">;
1037
+ data: z.ZodString;
1038
+ }, "strip", z.ZodTypeAny, {
1029
1039
  data: string;
1030
- } | {
1031
1040
  type: "json_delta";
1041
+ }, {
1032
1042
  data: string;
1033
- };
1043
+ type: "json_delta";
1044
+ }>]>;
1045
+ /**
1046
+ * A chunk of data from a Braintrust stream. Each chunk type matches
1047
+ * an SSE event type.
1048
+ */
1049
+ type BraintrustStreamChunk = z.infer<typeof braintrustStreamChunkSchema>;
1050
+ /**
1051
+ * A Braintrust stream. This is a wrapper around a ReadableStream of `BraintrustStreamChunk`,
1052
+ * with some utility methods to make them easy to log and convert into various formats.
1053
+ */
1034
1054
  declare class BraintrustStream {
1035
1055
  private stream;
1056
+ private memoizedFinalValue;
1036
1057
  constructor(baseStream: ReadableStream<Uint8Array>);
1037
1058
  constructor(stream: ReadableStream<string>);
1038
1059
  constructor(stream: ReadableStream<BraintrustStreamChunk>);
1060
+ /**
1061
+ * Copy the stream. This returns a new stream that shares the same underlying
1062
+ * stream (via `tee`). Since streams are consumed in Javascript, use `copy()` if you
1063
+ * need to use the stream multiple times.
1064
+ *
1065
+ * @returns A new stream that you can independently consume.
1066
+ */
1039
1067
  copy(): BraintrustStream;
1068
+ /**
1069
+ * Get the underlying ReadableStream.
1070
+ *
1071
+ * @returns The underlying ReadableStream<BraintrustStreamChunk>.
1072
+ */
1040
1073
  toReadableStream(): ReadableStream<BraintrustStreamChunk>;
1074
+ /**
1075
+ * Get the final value of the stream. The final value is the concatenation of all
1076
+ * the chunks in the stream, deserialized into a string or JSON object, depending on
1077
+ * the value's type.
1078
+ *
1079
+ * This function returns a promise that resolves when the stream is closed, and
1080
+ * contains the final value. Multiple calls to `finalValue()` will return the same
1081
+ * promise, so it is safe to call this multiple times.
1082
+ *
1083
+ * This function consumes the stream, so if you need to use the stream multiple
1084
+ * times, you should call `copy()` first.
1085
+ *
1086
+ * @returns A promise that resolves with the final value of the stream or `undefined` if the stream is empty.
1087
+ */
1088
+ finalValue(): Promise<unknown>;
1041
1089
  }
1090
+ /**
1091
+ * Create a stream that passes through the final value of the stream. This is
1092
+ * used to implement `BraintrustStream.finalValue()`.
1093
+ *
1094
+ * @param onFinal A function to call with the final value of the stream.
1095
+ * @returns A new stream that passes through the final value of the stream.
1096
+ */
1042
1097
  declare function createFinalValuePassThroughStream<T extends BraintrustStreamChunk | string | Uint8Array>(onFinal: (result: unknown) => void): TransformStream<T, BraintrustStreamChunk>;
1043
1098
  declare function devNullWritableStream(): WritableStream;
1044
1099
 
1045
- type InvokeReturn<Stream extends boolean, Return> = Stream extends true ? BraintrustStream : Return;
1046
- type InvokeFunctionArgs<Arg, Return, Stream extends boolean = false> = FunctionId & FullLoginOptions & {
1047
- arg: Arg;
1100
+ /**
1101
+ * Arguments for the `invoke` function.
1102
+ */
1103
+ interface InvokeFunctionArgs<Input, Output, Stream extends boolean = false> {
1104
+ /**
1105
+ * The ID of the function to invoke.
1106
+ */
1107
+ function_id?: string;
1108
+ /**
1109
+ * The name of the project containing the function to invoke.
1110
+ */
1111
+ project_name?: string;
1112
+ /**
1113
+ * The slug of the function to invoke.
1114
+ */
1115
+ slug?: string;
1116
+ /**
1117
+ * The name of the global function to invoke.
1118
+ */
1119
+ global_function?: string;
1120
+ /**
1121
+ * The ID of the prompt session to invoke the function from.
1122
+ */
1123
+ prompt_session_id?: string;
1124
+ /**
1125
+ * The ID of the function in the prompt session to invoke.
1126
+ */
1127
+ prompt_session_function_id?: string;
1128
+ /**
1129
+ * The version of the function to invoke.
1130
+ */
1131
+ version?: string;
1132
+ /**
1133
+ * The input to the function. This will be logged as the `input` field in the span.
1134
+ */
1135
+ input: Input;
1136
+ /**
1137
+ * The parent of the function. This can be an existing span, logger, or experiment, or
1138
+ * the output of `.export()` if you are distributed tracing. If unspecified, will use
1139
+ * the same semantics as `traced()` to determine the parent and no-op if not in a tracing
1140
+ * context.
1141
+ */
1048
1142
  parent?: Exportable | string;
1049
- state?: BraintrustState;
1143
+ /**
1144
+ * Whether to stream the function's output. If true, the function will return a
1145
+ * `BraintrustStream`, otherwise it will return the output of the function as a JSON
1146
+ * object.
1147
+ */
1050
1148
  stream?: Stream;
1051
- schema?: z.ZodSchema<Return>;
1052
- };
1053
- declare function invoke<Arg, Return, Stream extends boolean = false>(args: InvokeFunctionArgs<Arg, Return, Stream>): Promise<InvokeReturn<Stream, Return>>;
1149
+ /**
1150
+ * A Zod schema to validate the output of the function and return a typed value. This
1151
+ * is only used if `stream` is false.
1152
+ */
1153
+ schema?: Stream extends true ? never : z.ZodSchema<Output>;
1154
+ /**
1155
+ * (Advanced) This parameter allows you to pass in a custom login state. This is useful
1156
+ * for multi-tenant environments where you are running functions from different Braintrust
1157
+ * organizations.
1158
+ */
1159
+ state?: BraintrustState;
1160
+ }
1161
+ /**
1162
+ * The return type of the `invoke` function. Conditionally returns a `BraintrustStream`
1163
+ * if `stream` is true, otherwise returns the output of the function using the Zod schema's
1164
+ * type if present.
1165
+ */
1166
+ type InvokeReturn<Stream extends boolean, Output> = Stream extends true ? BraintrustStream : Output;
1167
+ /**
1168
+ * Invoke a Braintrust function, returning a `BraintrustStream` or the value as a plain
1169
+ * Javascript object.
1170
+ *
1171
+ * @param args The arguments for the function (see {@link InvokeFunctionArgs} for more details).
1172
+ * @returns The output of the function.
1173
+ */
1174
+ declare function invoke<Input, Output, Stream extends boolean = false>(args: InvokeFunctionArgs<Input, Output, Stream> & FullLoginOptions): Promise<InvokeReturn<Stream, Output>>;
1054
1175
 
1055
1176
  interface BetaLike {
1056
1177
  chat: {
@@ -1086,4 +1207,4 @@ declare const LEGACY_CACHED_HEADER = "x-cached";
1086
1207
  declare const X_CACHED_HEADER = "x-bt-cached";
1087
1208
  declare function parseCachedHeader(value: string | null | undefined): number | undefined;
1088
1209
 
1089
- export { type AnyDataset, 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, 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, ReadonlyExperiment, type ScoreSummary, type SerializedBraintrustState, type SetCurrentArg, type Span, SpanImpl, type StartSpanArgs, type WithTransactionId, X_CACHED_HEADER, _internalGetGlobalState, _internalSetInitialState, createFinalValuePassThroughStream, currentExperiment, currentLogger, currentSpan, devNullWritableStream, flush, getSpanParentObject, init, initDataset, initExperiment, initLogger, invoke, loadPrompt, log, login, loginToState, newId, parseCachedHeader, setFetch, startSpan, summarize, traceable, traced, withDataset, withExperiment, withLogger, wrapOpenAI, wrapOpenAIv4, wrapTraced };
1210
+ export { type AnyDataset, 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, 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, ReadonlyExperiment, type ScoreSummary, type SerializedBraintrustState, type SetCurrentArg, type Span, SpanImpl, type StartSpanArgs, type WithTransactionId, X_CACHED_HEADER, _internalGetGlobalState, _internalSetInitialState, braintrustStreamChunkSchema, createFinalValuePassThroughStream, currentExperiment, currentLogger, currentSpan, devNullWritableStream, flush, getSpanParentObject, init, initDataset, initExperiment, initLogger, invoke, loadPrompt, log, login, loginToState, newId, parseCachedHeader, setFetch, startSpan, summarize, traceable, traced, withDataset, withExperiment, withLogger, wrapOpenAI, wrapOpenAIv4, wrapTraced };
package/dist/browser.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { GitMetadataSettings, LogFeedbackFullArgs, BackgroundLogEvent, ExperimentEvent, ExperimentLogFullArgs, ExperimentLogPartialArgs, IdField, SpanType, RepoInfo, DEFAULT_IS_LEGACY_DATASET, TRANSACTION_ID_FIELD, TransactionId, SpanObjectTypeV2, DatasetRecord } from '@braintrust/core';
2
- import { PromptData, OpenAIMessage, Tools, AnyModelParam, Prompt as Prompt$1, PromptSessionEvent, FunctionId } from '@braintrust/core/typespecs';
2
+ import { PromptData, OpenAIMessage, Tools, AnyModelParam, Prompt as Prompt$1, PromptSessionEvent } from '@braintrust/core/typespecs';
3
3
  import { z } from 'zod';
4
4
 
5
5
  interface IsoAsyncLocalStorage<T> {
@@ -137,7 +137,7 @@ declare const loginSchema: z.ZodObject<{
137
137
  appUrl: z.ZodString;
138
138
  appPublicUrl: z.ZodString;
139
139
  orgName: z.ZodString;
140
- logUrl: z.ZodString;
140
+ apiUrl: z.ZodString;
141
141
  proxyUrl: z.ZodString;
142
142
  loginToken: z.ZodString;
143
143
  orgId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -155,7 +155,7 @@ declare const loginSchema: z.ZodObject<{
155
155
  appUrl: string;
156
156
  appPublicUrl: string;
157
157
  orgName: string;
158
- logUrl: string;
158
+ apiUrl: string;
159
159
  proxyUrl: string;
160
160
  loginToken: string;
161
161
  orgId?: string | null | undefined;
@@ -167,7 +167,7 @@ declare const loginSchema: z.ZodObject<{
167
167
  appUrl: string;
168
168
  appPublicUrl: string;
169
169
  orgName: string;
170
- logUrl: string;
170
+ apiUrl: string;
171
171
  proxyUrl: string;
172
172
  loginToken: string;
173
173
  orgId?: string | null | undefined;
@@ -189,13 +189,13 @@ declare class BraintrustState {
189
189
  loginToken: string | null;
190
190
  orgId: string | null;
191
191
  orgName: string | null;
192
- logUrl: string | null;
192
+ apiUrl: string | null;
193
193
  proxyUrl: string | null;
194
194
  loggedIn: boolean;
195
195
  gitMetadataSettings?: GitMetadataSettings;
196
196
  fetch: typeof globalThis.fetch;
197
+ private _appConn;
197
198
  private _apiConn;
198
- private _logConn;
199
199
  private _proxyConn;
200
200
  constructor(loginParams: LoginOptions);
201
201
  resetLoginInfo(): void;
@@ -206,11 +206,11 @@ declare class BraintrustState {
206
206
  login(loginParams: LoginOptions & {
207
207
  forceLogin?: boolean;
208
208
  }): Promise<void>;
209
+ appConn(): HTTPConnection;
209
210
  apiConn(): HTTPConnection;
210
- logConn(): HTTPConnection;
211
211
  proxyConn(): HTTPConnection;
212
212
  bgLogger(): BackgroundLogger;
213
- loginReplaceLogConn(logConn: HTTPConnection): void;
213
+ loginReplaceApiConn(apiConn: HTTPConnection): void;
214
214
  }
215
215
  declare function _internalSetInitialState(): void;
216
216
  declare const _internalGetGlobalState: () => BraintrustState;
@@ -271,7 +271,6 @@ declare class Logger<IsAsyncFlush extends boolean> implements Exportable {
271
271
  get project(): Promise<ObjectMetadata>;
272
272
  get id(): Promise<string>;
273
273
  private parentObjectType;
274
- private triggerWaitUntilFlush;
275
274
  /**
276
275
  * Log a single event. The event will be batched and uploaded behind the scenes if `logOptions.asyncFlush` is true.
277
276
  *
@@ -325,7 +324,7 @@ declare class Logger<IsAsyncFlush extends boolean> implements Exportable {
325
324
  get asyncFlush(): IsAsyncFlush | undefined;
326
325
  }
327
326
  declare class BackgroundLogger {
328
- private logConn;
327
+ private apiConn;
329
328
  private items;
330
329
  private activeFlush;
331
330
  private activeFlushResolved;
@@ -339,7 +338,7 @@ declare class BackgroundLogger {
339
338
  failedPublishPayloadsDir: string | undefined;
340
339
  allPublishPayloadsDir: string | undefined;
341
340
  private queueDropLoggingState;
342
- constructor(logConn: LazyValue<HTTPConnection>);
341
+ constructor(apiConn: LazyValue<HTTPConnection>);
343
342
  log(items: LazyValue<BackgroundLogEvent>[]): void;
344
343
  flush(): Promise<void>;
345
344
  private flushOnce;
@@ -350,7 +349,7 @@ declare class BackgroundLogger {
350
349
  private static writePayloadToDir;
351
350
  private triggerActiveFlush;
352
351
  private logFailedPayloadsDir;
353
- internalReplaceLogConn(logConn: HTTPConnection): void;
352
+ internalReplaceApiConn(apiConn: HTTPConnection): void;
354
353
  }
355
354
  type InitOpenOption<IsOpen extends boolean> = {
356
355
  open?: IsOpen;
@@ -1024,33 +1023,155 @@ interface DatasetSummary {
1024
1023
  dataSummary: DataSummary;
1025
1024
  }
1026
1025
 
1027
- type BraintrustStreamChunk = {
1026
+ declare const braintrustStreamChunkSchema: z.ZodUnion<[z.ZodObject<{
1027
+ type: z.ZodLiteral<"text_delta">;
1028
+ data: z.ZodString;
1029
+ }, "strip", z.ZodTypeAny, {
1030
+ data: string;
1031
+ type: "text_delta";
1032
+ }, {
1033
+ data: string;
1028
1034
  type: "text_delta";
1035
+ }>, z.ZodObject<{
1036
+ type: z.ZodLiteral<"json_delta">;
1037
+ data: z.ZodString;
1038
+ }, "strip", z.ZodTypeAny, {
1029
1039
  data: string;
1030
- } | {
1031
1040
  type: "json_delta";
1041
+ }, {
1032
1042
  data: string;
1033
- };
1043
+ type: "json_delta";
1044
+ }>]>;
1045
+ /**
1046
+ * A chunk of data from a Braintrust stream. Each chunk type matches
1047
+ * an SSE event type.
1048
+ */
1049
+ type BraintrustStreamChunk = z.infer<typeof braintrustStreamChunkSchema>;
1050
+ /**
1051
+ * A Braintrust stream. This is a wrapper around a ReadableStream of `BraintrustStreamChunk`,
1052
+ * with some utility methods to make them easy to log and convert into various formats.
1053
+ */
1034
1054
  declare class BraintrustStream {
1035
1055
  private stream;
1056
+ private memoizedFinalValue;
1036
1057
  constructor(baseStream: ReadableStream<Uint8Array>);
1037
1058
  constructor(stream: ReadableStream<string>);
1038
1059
  constructor(stream: ReadableStream<BraintrustStreamChunk>);
1060
+ /**
1061
+ * Copy the stream. This returns a new stream that shares the same underlying
1062
+ * stream (via `tee`). Since streams are consumed in Javascript, use `copy()` if you
1063
+ * need to use the stream multiple times.
1064
+ *
1065
+ * @returns A new stream that you can independently consume.
1066
+ */
1039
1067
  copy(): BraintrustStream;
1068
+ /**
1069
+ * Get the underlying ReadableStream.
1070
+ *
1071
+ * @returns The underlying ReadableStream<BraintrustStreamChunk>.
1072
+ */
1040
1073
  toReadableStream(): ReadableStream<BraintrustStreamChunk>;
1074
+ /**
1075
+ * Get the final value of the stream. The final value is the concatenation of all
1076
+ * the chunks in the stream, deserialized into a string or JSON object, depending on
1077
+ * the value's type.
1078
+ *
1079
+ * This function returns a promise that resolves when the stream is closed, and
1080
+ * contains the final value. Multiple calls to `finalValue()` will return the same
1081
+ * promise, so it is safe to call this multiple times.
1082
+ *
1083
+ * This function consumes the stream, so if you need to use the stream multiple
1084
+ * times, you should call `copy()` first.
1085
+ *
1086
+ * @returns A promise that resolves with the final value of the stream or `undefined` if the stream is empty.
1087
+ */
1088
+ finalValue(): Promise<unknown>;
1041
1089
  }
1090
+ /**
1091
+ * Create a stream that passes through the final value of the stream. This is
1092
+ * used to implement `BraintrustStream.finalValue()`.
1093
+ *
1094
+ * @param onFinal A function to call with the final value of the stream.
1095
+ * @returns A new stream that passes through the final value of the stream.
1096
+ */
1042
1097
  declare function createFinalValuePassThroughStream<T extends BraintrustStreamChunk | string | Uint8Array>(onFinal: (result: unknown) => void): TransformStream<T, BraintrustStreamChunk>;
1043
1098
  declare function devNullWritableStream(): WritableStream;
1044
1099
 
1045
- type InvokeReturn<Stream extends boolean, Return> = Stream extends true ? BraintrustStream : Return;
1046
- type InvokeFunctionArgs<Arg, Return, Stream extends boolean = false> = FunctionId & FullLoginOptions & {
1047
- arg: Arg;
1100
+ /**
1101
+ * Arguments for the `invoke` function.
1102
+ */
1103
+ interface InvokeFunctionArgs<Input, Output, Stream extends boolean = false> {
1104
+ /**
1105
+ * The ID of the function to invoke.
1106
+ */
1107
+ function_id?: string;
1108
+ /**
1109
+ * The name of the project containing the function to invoke.
1110
+ */
1111
+ project_name?: string;
1112
+ /**
1113
+ * The slug of the function to invoke.
1114
+ */
1115
+ slug?: string;
1116
+ /**
1117
+ * The name of the global function to invoke.
1118
+ */
1119
+ global_function?: string;
1120
+ /**
1121
+ * The ID of the prompt session to invoke the function from.
1122
+ */
1123
+ prompt_session_id?: string;
1124
+ /**
1125
+ * The ID of the function in the prompt session to invoke.
1126
+ */
1127
+ prompt_session_function_id?: string;
1128
+ /**
1129
+ * The version of the function to invoke.
1130
+ */
1131
+ version?: string;
1132
+ /**
1133
+ * The input to the function. This will be logged as the `input` field in the span.
1134
+ */
1135
+ input: Input;
1136
+ /**
1137
+ * The parent of the function. This can be an existing span, logger, or experiment, or
1138
+ * the output of `.export()` if you are distributed tracing. If unspecified, will use
1139
+ * the same semantics as `traced()` to determine the parent and no-op if not in a tracing
1140
+ * context.
1141
+ */
1048
1142
  parent?: Exportable | string;
1049
- state?: BraintrustState;
1143
+ /**
1144
+ * Whether to stream the function's output. If true, the function will return a
1145
+ * `BraintrustStream`, otherwise it will return the output of the function as a JSON
1146
+ * object.
1147
+ */
1050
1148
  stream?: Stream;
1051
- schema?: z.ZodSchema<Return>;
1052
- };
1053
- declare function invoke<Arg, Return, Stream extends boolean = false>(args: InvokeFunctionArgs<Arg, Return, Stream>): Promise<InvokeReturn<Stream, Return>>;
1149
+ /**
1150
+ * A Zod schema to validate the output of the function and return a typed value. This
1151
+ * is only used if `stream` is false.
1152
+ */
1153
+ schema?: Stream extends true ? never : z.ZodSchema<Output>;
1154
+ /**
1155
+ * (Advanced) This parameter allows you to pass in a custom login state. This is useful
1156
+ * for multi-tenant environments where you are running functions from different Braintrust
1157
+ * organizations.
1158
+ */
1159
+ state?: BraintrustState;
1160
+ }
1161
+ /**
1162
+ * The return type of the `invoke` function. Conditionally returns a `BraintrustStream`
1163
+ * if `stream` is true, otherwise returns the output of the function using the Zod schema's
1164
+ * type if present.
1165
+ */
1166
+ type InvokeReturn<Stream extends boolean, Output> = Stream extends true ? BraintrustStream : Output;
1167
+ /**
1168
+ * Invoke a Braintrust function, returning a `BraintrustStream` or the value as a plain
1169
+ * Javascript object.
1170
+ *
1171
+ * @param args The arguments for the function (see {@link InvokeFunctionArgs} for more details).
1172
+ * @returns The output of the function.
1173
+ */
1174
+ declare function invoke<Input, Output, Stream extends boolean = false>(args: InvokeFunctionArgs<Input, Output, Stream> & FullLoginOptions): Promise<InvokeReturn<Stream, Output>>;
1054
1175
 
1055
1176
  interface BetaLike {
1056
1177
  chat: {
@@ -1086,4 +1207,4 @@ declare const LEGACY_CACHED_HEADER = "x-cached";
1086
1207
  declare const X_CACHED_HEADER = "x-bt-cached";
1087
1208
  declare function parseCachedHeader(value: string | null | undefined): number | undefined;
1088
1209
 
1089
- export { type AnyDataset, 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, 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, ReadonlyExperiment, type ScoreSummary, type SerializedBraintrustState, type SetCurrentArg, type Span, SpanImpl, type StartSpanArgs, type WithTransactionId, X_CACHED_HEADER, _internalGetGlobalState, _internalSetInitialState, createFinalValuePassThroughStream, currentExperiment, currentLogger, currentSpan, devNullWritableStream, flush, getSpanParentObject, init, initDataset, initExperiment, initLogger, invoke, loadPrompt, log, login, loginToState, newId, parseCachedHeader, setFetch, startSpan, summarize, traceable, traced, withDataset, withExperiment, withLogger, wrapOpenAI, wrapOpenAIv4, wrapTraced };
1210
+ export { type AnyDataset, 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, 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, ReadonlyExperiment, type ScoreSummary, type SerializedBraintrustState, type SetCurrentArg, type Span, SpanImpl, type StartSpanArgs, type WithTransactionId, X_CACHED_HEADER, _internalGetGlobalState, _internalSetInitialState, braintrustStreamChunkSchema, createFinalValuePassThroughStream, currentExperiment, currentLogger, currentSpan, devNullWritableStream, flush, getSpanParentObject, init, initDataset, initExperiment, initLogger, invoke, loadPrompt, log, login, loginToState, newId, parseCachedHeader, setFetch, startSpan, summarize, traceable, traced, withDataset, withExperiment, withLogger, wrapOpenAI, wrapOpenAIv4, wrapTraced };