braintrust 3.19.0 → 3.21.0

package/dist/instrumentation/index.d.mts

@@ -2891,18 +2891,21 @@ declare const PromptData: z.ZodObject<{
         choice_scores: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
         choice: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         allow_no_match: z.ZodOptional<z.ZodBoolean>;
+        allow_skip: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
         type: "llm_classifier";
         use_cot: boolean;
         choice_scores?: Record<string, number> | undefined;
         choice?: string[] | undefined;
         allow_no_match?: boolean | undefined;
+        allow_skip?: boolean | undefined;
     }, {
         type: "llm_classifier";
         use_cot: boolean;
         choice_scores?: Record<string, number> | undefined;
         choice?: string[] | undefined;
         allow_no_match?: boolean | undefined;
+        allow_skip?: boolean | undefined;
     }>, z.ZodNull]>>;
     tool_functions: z.ZodOptional<z.ZodUnion<[z.ZodArray<z.ZodUnion<[z.ZodObject<{
         type: z.ZodLiteral<"function">;
@@ -3202,6 +3205,7 @@ declare const PromptData: z.ZodObject<{
         choice_scores?: Record<string, number> | undefined;
         choice?: string[] | undefined;
         allow_no_match?: boolean | undefined;
+        allow_skip?: boolean | undefined;
     } | null | undefined;
     tool_functions?: ({
         type: "function";
@@ -3452,6 +3456,7 @@ declare const PromptData: z.ZodObject<{
         choice_scores?: Record<string, number> | undefined;
         choice?: string[] | undefined;
         allow_no_match?: boolean | undefined;
+        allow_skip?: boolean | undefined;
     } | null | undefined;
     tool_functions?: ({
         type: "function";
@@ -4726,18 +4731,21 @@ declare const Prompt$1: z.ZodObject<{
             choice_scores: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
             choice: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
             allow_no_match: z.ZodOptional<z.ZodBoolean>;
+            allow_skip: z.ZodOptional<z.ZodBoolean>;
         }, "strip", z.ZodTypeAny, {
             type: "llm_classifier";
             use_cot: boolean;
             choice_scores?: Record<string, number> | undefined;
             choice?: string[] | undefined;
             allow_no_match?: boolean | undefined;
+            allow_skip?: boolean | undefined;
         }, {
             type: "llm_classifier";
             use_cot: boolean;
             choice_scores?: Record<string, number> | undefined;
             choice?: string[] | undefined;
             allow_no_match?: boolean | undefined;
+            allow_skip?: boolean | undefined;
         }>, z.ZodNull]>>;
         tool_functions: z.ZodOptional<z.ZodUnion<[z.ZodArray<z.ZodUnion<[z.ZodObject<{
             type: z.ZodLiteral<"function">;
@@ -5037,6 +5045,7 @@ declare const Prompt$1: z.ZodObject<{
             choice_scores?: Record<string, number> | undefined;
             choice?: string[] | undefined;
             allow_no_match?: boolean | undefined;
+            allow_skip?: boolean | undefined;
         } | null | undefined;
         tool_functions?: ({
             type: "function";
@@ -5287,6 +5296,7 @@ declare const Prompt$1: z.ZodObject<{
             choice_scores?: Record<string, number> | undefined;
             choice?: string[] | undefined;
             allow_no_match?: boolean | undefined;
+            allow_skip?: boolean | undefined;
         } | null | undefined;
         tool_functions?: ({
             type: "function";
@@ -5315,15 +5325,15 @@ declare const Prompt$1: z.ZodObject<{
     function_type: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["llm", "scorer", "task", "tool", "custom_view", "preprocessor", "facet", "classifier", "tag", "parameters", "sandbox"]>, z.ZodNull]>>;
 }, "strip", z.ZodTypeAny, {
     id: string;
-    org_id: string;
-    name: string;
     project_id: string;
-    _xact_id: string;
+    name: string;
     slug: string;
+    org_id: string;
+    _xact_id: string;
     log_id: "p";
     created?: string | null | undefined;
-    metadata?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | null | undefined;
     description?: string | null | undefined;
+    metadata?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | null | undefined;
     function_type?: "llm" | "scorer" | "task" | "tool" | "custom_view" | "preprocessor" | "facet" | "classifier" | "tag" | "parameters" | "sandbox" | null | undefined;
     tags?: string[] | null | undefined;
     prompt_data?: {
@@ -5554,6 +5564,7 @@ declare const Prompt$1: z.ZodObject<{
             choice_scores?: Record<string, number> | undefined;
             choice?: string[] | undefined;
             allow_no_match?: boolean | undefined;
+            allow_skip?: boolean | undefined;
         } | null | undefined;
         tool_functions?: ({
             type: "function";
@@ -5579,15 +5590,15 @@ declare const Prompt$1: z.ZodObject<{
     } | null | undefined;
 }, {
     id: string;
-    org_id: string;
-    name: string;
     project_id: string;
-    _xact_id: string;
+    name: string;
     slug: string;
+    org_id: string;
+    _xact_id: string;
     log_id: "p";
     created?: string | null | undefined;
-    metadata?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | null | undefined;
     description?: string | null | undefined;
+    metadata?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | null | undefined;
     function_type?: "llm" | "scorer" | "task" | "tool" | "custom_view" | "preprocessor" | "facet" | "classifier" | "tag" | "parameters" | "sandbox" | null | undefined;
     tags?: string[] | null | undefined;
     prompt_data?: {
@@ -5818,6 +5829,7 @@ declare const Prompt$1: z.ZodObject<{
             choice_scores?: Record<string, number> | undefined;
             choice?: string[] | undefined;
             allow_no_match?: boolean | undefined;
+            allow_skip?: boolean | undefined;
         } | null | undefined;
         tool_functions?: ({
             type: "function";
@@ -6233,6 +6245,31 @@ declare abstract class IDGenerator {
     abstract shareRootSpanId(): boolean;
 }
 
+type TraceContextHeaderValue = string | number | readonly string[] | null | undefined;
+/**
+ * Minimal structural interface for outbound HTTP header carriers.
+ *
+ * Supports plain objects, Web/Fetch-compatible `Headers`, Node/Fastify-style
+ * response carriers, and mutable `HeadersInit` tuple arrays.
+ */
+type TraceContextCarrier = {
+    [name: string]: TraceContextHeaderValue;
+} | {
+    get(name: string): TraceContextHeaderValue;
+    set(name: string, value: string): void;
+    delete?(name: string): void;
+} | {
+    getHeader(name: string): TraceContextHeaderValue;
+    setHeader(name: string, value: string): void;
+    removeHeader?(name: string): void;
+} | {
+    get?(name: string): TraceContextHeaderValue;
+    getHeader?(name: string): TraceContextHeaderValue;
+    header(name: string, value: string): void;
+    delete?(name: string): void;
+    removeHeader?(name: string): void;
+} | [string, string][];
+
 declare const TRANSACTION_ID_FIELD = "_xact_id";
 declare const IS_MERGE_FIELD = "_is_merge";
 declare const MERGE_PATHS_FIELD = "_merge_paths";
@@ -6323,13 +6360,13 @@ declare const AsyncScoringControl: z.ZodUnion<[z.ZodObject<{
     function_ids: z.ZodArray<z.ZodUnknown, "many">;
     triggered_xact_id: z.ZodString;
 }, "strip", z.ZodTypeAny, {
+    kind: "complete_triggered_functions";
     triggered_xact_id: string;
     function_ids: unknown[];
-    kind: "complete_triggered_functions";
 }, {
+    kind: "complete_triggered_functions";
     triggered_xact_id: string;
     function_ids: unknown[];
-    kind: "complete_triggered_functions";
 }>]>;
 type AsyncScoringControlType = z.infer<typeof AsyncScoringControl>;
 declare const ObjectReference: z.ZodObject<{
@@ -6406,6 +6443,7 @@ type ExperimentEvent = Partial<InputField> & Partial<OtherExperimentLogFields> &
     span_parents: string[];
     span_attributes: Record<string, unknown>;
     context: Record<string, unknown>;
+    is_root: boolean | null;
     [AUDIT_SOURCE_FIELD]: Source;
     [AUDIT_METADATA_FIELD]?: Record<string, unknown>;
 }>;
@@ -6919,6 +6957,8 @@ declare class SpanCache {
     dispose(): void;
 }
 
+/// <reference lib="dom" />
+
 declare const RESET_CONTEXT_MANAGER_STATE: unique symbol;
 declare const datasetRestorePreviewResultSchema: z.ZodObject<{
     rows_to_restore: z.ZodNumber;
@@ -6969,32 +7009,32 @@ declare const parametersRowSchema: z.ZodObject<{
     metadata: z.ZodOptional<z.ZodUnion<[z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>, z.ZodNull]>>;
 }, "strip", z.ZodTypeAny, {
     id: string;
+    project_id: string;
     name: string;
+    slug: string;
     function_type: "parameters";
-    project_id: string;
     _xact_id: string;
-    slug: string;
     function_data: {
         type: "parameters";
         __schema: Record<string, unknown>;
         data?: Record<string, unknown> | undefined;
     };
-    metadata?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | null | undefined;
     description?: string | null | undefined;
+    metadata?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | null | undefined;
 }, {
     id: string;
+    project_id: string;
     name: string;
+    slug: string;
     function_type: "parameters";
-    project_id: string;
     _xact_id: string;
-    slug: string;
     function_data: {
         type: "parameters";
         __schema: Record<string, unknown>;
         data?: Record<string, unknown> | undefined;
     };
-    metadata?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | null | undefined;
     description?: string | null | undefined;
+    metadata?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | null | undefined;
 }>;
 type ParametersRow = z.infer<typeof parametersRowSchema>;
 
@@ -7011,7 +7051,12 @@ type StartSpanArgs = {
     type?: SpanType;
     spanAttributes?: Record<any, any>;
     startTime?: number;
-    parent?: string;
+    /**
+     * The parent to start this span under. May be an exported span slug string
+     * (from `span.export()`) or an opaque W3C trace-context (from
+     * {@link extractTraceContextFromHeaders}).
+     */
+    parent?: string | PropagationContext;
     event?: StartSpanEventArgs;
     propagatedEvent?: StartSpanEventArgs;
     spanId?: string;
@@ -7113,6 +7158,24 @@ interface Span extends Exportable {
      * @returns Serialized representation of this span's identifiers.
      */
     export(): Promise<string>;
+    /**
+     * Inject W3C trace-context headers (`traceparent` and `baggage`) for this span
+     * into a carrier, for distributed tracing across service boundaries.
+     *
+     * Adds `traceparent` (trace identity) and, when this span's Braintrust parent
+     * is known, a `baggage` entry `braintrust.parent=<parent>` (merged with any
+     * pre-existing baggage). Propagation is best-effort and never throws; if the
+     * span's ids are not W3C-shaped hex (e.g. legacy UUID mode), `traceparent` is
+     * omitted.
+     *
+     * @param carrier Optional existing carrier (e.g. outbound HTTP headers) to
+     *   mutate and return. Supports plain objects, Web `Headers`, Node-style
+     *   `setHeader` carriers, framework `header` carriers, and mutable
+     *   `HeadersInit` tuple arrays. A new object is created if not provided.
+     * @returns The carrier with propagation headers injected.
+     */
+    inject(): Record<string, string>;
+    inject<T extends TraceContextCarrier>(carrier: T): T;
     /**
      * Format a permalink to the Braintrust application for viewing this span.
      *
@@ -7234,7 +7297,7 @@ declare class BraintrustState {
     id: string;
     currentExperiment: Experiment | undefined;
     currentLogger: Logger<false> | undefined;
-    currentParent: IsoAsyncLocalStorage<string>;
+    currentParent: IsoAsyncLocalStorage<string | PropagationContext>;
     currentSpan: IsoAsyncLocalStorage<Span>;
     private _bgLogger;
     private _overrideBgLogger;
@@ -7352,6 +7415,15 @@ type DatasetPipelineDeferredJSONAttachmentHook = (data: unknown, options?: {
 declare global {
     var __BT_DATASET_PIPELINE_DEFER_JSON_ATTACHMENT__: DatasetPipelineDeferredJSONAttachmentHook | undefined;
 }
+/**
+ * An opaque W3C trace-context, as returned by
+ * {@link extractTraceContextFromHeaders}.
+ *
+ * Carries the relevant W3C headers (`traceparent`, `baggage`, `tracestate`).
+ * Callers MUST treat it as opaque and pass it straight to
+ * `startSpan({ parent })`.
+ */
+type PropagationContext = Record<string, string>;
 interface ParentSpanIds {
     spanId: string;
     rootSpanId: string;
@@ -7443,6 +7515,12 @@ declare class Logger<IsAsyncFlush extends boolean> implements Exportable {
      * Resolution order: state -> linkArgs -> env var
      */
     _getLinkBaseUrl(): string | null;
+    /**
+     * Return this logger's Braintrust parent string (`project_id:<id>` or
+     * `project_name:<name>`) for the `braintrust.parent` baggage entry, or
+     * undefined when it cannot be determined synchronously.
+     */
+    _getOtelParent(): string | undefined;
 }
 interface BackgroundLoggerOpts {
     noExitFlush?: boolean;
@@ -7512,6 +7590,9 @@ type DatasetPinState = {
     pinnedEnvironment?: string;
     pinnedSnapshotName?: string;
 };
+declare global {
+    var __bt_eval_internal_btql: Record<string, unknown> | undefined;
+}
 /**
  * Options for logging in to Braintrust.
  */
@@ -7571,8 +7652,9 @@ declare class ObjectFetcher<RecordType> implements AsyncIterable<WithTransaction
     private pinnedVersion;
     private mutateRecord?;
     private _internal_btql?;
+    private _internalBrainstoreRealtime;
     private _fetchedData;
-    constructor(objectType: "dataset" | "experiment" | "project_logs" | "playground_logs", pinnedVersion: string | undefined, mutateRecord?: ((r: any) => WithTransactionId<RecordType>) | undefined, _internal_btql?: Record<string, unknown> | undefined);
+    constructor(objectType: "dataset" | "experiment" | "project_logs" | "playground_logs", pinnedVersion: string | undefined, mutateRecord?: ((r: any) => WithTransactionId<RecordType>) | undefined, _internal_btql?: Record<string, unknown> | undefined, _internalBrainstoreRealtime?: boolean);
     get id(): Promise<string>;
     protected getState(): Promise<BraintrustState>;
     protected getPinnedVersion(): string | undefined;
@@ -7708,6 +7790,12 @@ declare class Experiment extends ObjectFetcher<ExperimentEvent> implements Expor
      * See {@link Span.startSpan} for more details.
      */
     export(): Promise<string>;
+    /**
+     * Return this experiment's Braintrust parent string (`experiment_id:<id>`) for
+     * the `braintrust.parent` baggage entry, or undefined when it cannot be
+     * determined synchronously.
+     */
+    _getOtelParent(): string | undefined;
     /**
      * Flush any pending rows to the server.
      */
@@ -8184,7 +8272,6 @@ type FlueOperationKind = "prompt" | "skill" | "task" | "compact";
 interface FlueContext {
     readonly id?: string;
     readonly runId?: string;
-    [key: string | symbol]: unknown;
 }
 type FlueExecutionOperation = {
     type: "workflow";
@@ -8236,6 +8323,17 @@ interface FlueInstrumentation {
 
 type FlueObserver = (event: unknown, ctx?: unknown) => void;
 type BraintrustFlueObserver = FlueObserver & FlueInstrumentation;
+/**
+ * Manual instrumentation for flue.
+ *
+ * This should be passed to flue's `instrument()` API if not using auto-instrumentation: `instrument(braintrustFlueInstrumentation())`
+ */
+declare function braintrustFlueInstrumentation(): FlueInstrumentation;
+/**
+ * Observer for flue pre version 1.0.0.
+ *
+ * This observer should be passed to flue's `observe()` API if not using auto-instrumentation.
+ */
 declare const braintrustFlueObserver: BraintrustFlueObserver;
 
 /**
@@ -8274,4 +8372,4 @@ declare const braintrustFlueObserver: BraintrustFlueObserver;
  */
 declare function configureInstrumentation(config: InstrumentationConfig): void;
 
-export { type AsyncEndEvent, type AsyncStartEvent, type BaseContext, BasePlugin, BraintrustPlugin, type BraintrustPluginConfig, type ChannelHandlers, type EndEvent, type ErrorEvent, type InstrumentationConfig, OpenAIAgentsTraceProcessor, type OpenAIAgentsTraceProcessorOptions, type StartEvent, braintrustFlueObserver, configureInstrumentation, createChannelName, isValidChannelName, parseChannelName };
+export { type AsyncEndEvent, type AsyncStartEvent, type BaseContext, BasePlugin, BraintrustPlugin, type BraintrustPluginConfig, type ChannelHandlers, type EndEvent, type ErrorEvent, type InstrumentationConfig, OpenAIAgentsTraceProcessor, type OpenAIAgentsTraceProcessorOptions, type StartEvent, braintrustFlueInstrumentation, braintrustFlueObserver, configureInstrumentation, createChannelName, isValidChannelName, parseChannelName };