braintrust 0.0.113 → 0.0.115

package/dist/logger.d.ts

@@ -1,5 +1,5 @@
 /// <reference lib="dom" />
-import { TRANSACTION_ID_FIELD, GitMetadataSettings, RepoInfo, TransactionId, ParentExperimentIds, ParentProjectLogIds, IdField, ExperimentLogPartialArgs, ExperimentLogFullArgs, LogFeedbackFullArgs, ExperimentEvent, BackgroundLogEvent, DEFAULT_IS_LEGACY_DATASET, DatasetRecord } from "@braintrust/core";
+import { TRANSACTION_ID_FIELD, GitMetadataSettings, RepoInfo, TransactionId, IdField, ExperimentLogPartialArgs, ExperimentLogFullArgs, LogFeedbackFullArgs, ExperimentEvent, BackgroundLogEvent, DEFAULT_IS_LEGACY_DATASET, DatasetRecord, SpanType, SpanParentObjectType } from "@braintrust/core";
 import { AnyModelParam, Message, PromptData, Tools, Prompt as PromptRow } from "@braintrust/core/typespecs";
 import { IsoAsyncLocalStorage } from "./isomorph";
 import { LazyValue } from "./util";
@@ -9,8 +9,10 @@ export type SetCurrentArg = {
 type StartSpanEventArgs = ExperimentLogPartialArgs & Partial<IdField>;
 export type StartSpanArgs = {
     name?: string;
+    type?: SpanType;
     spanAttributes?: Record<any, any>;
     startTime?: number;
+    parent?: string;
     parentId?: string;
     event?: StartSpanEventArgs;
 };
@@ -48,10 +50,12 @@ export interface Span {
      *
      * @param callback The function to be run under the span context.
      * @param args.name Optional name of the span. If not provided, a name will be inferred from the call stack.
+     * @param args.type Optional type of the span. If not provided, the type will be unset.
      * @param args.span_attributes Optional additional attributes to attach to the span, such as a type name.
      * @param args.start_time Optional start time of the span, as a timestamp in seconds.
      * @param args.setCurrent If true (the default), the span will be marked as the currently-active span for the duration of the callback.
-     * @param args.parentId Optional id of the parent span. If not provided, the current span will be used (depending on context). This is useful for adding spans to an existing trace.
+     * @param args.parent Optional parent info string for the span. The string can be generated from `[Span,Experiment,Logger].export`. If not provided, the current span will be used (depending on context). This is useful for adding spans to an existing trace.
+     * @param parentId This option is deprecated and will be removed in a future version of Braintrust. Prefer to use `parent` instead.
      * @param args.event Data to be logged. See `Experiment.log` for full details.
      * @Returns The result of running `callback`.
      */
@@ -79,6 +83,10 @@ export interface Span {
      * Alias for `end`.
      */
     close(args?: EndSpanArgs): number;
+    /**
+     * Flush any pending rows to the server.
+     */
+    flush(): Promise<void>;
     kind: "span";
 }
 /**
@@ -89,11 +97,12 @@ export declare class NoopSpan implements Span {
     kind: "span";
     constructor();
     log(_: ExperimentLogPartialArgs): void;
-    logFeedback(event: Omit<LogFeedbackFullArgs, "id">): void;
+    logFeedback(_event: Omit<LogFeedbackFullArgs, "id">): void;
     traced<R>(callback: (span: Span) => R, _1?: StartSpanArgs & SetCurrentArg): R;
     startSpan(_1?: StartSpanArgs): this;
     end(args?: EndSpanArgs): number;
     close(args?: EndSpanArgs): number;
+    flush(): Promise<void>;
 }
 export declare const NOOP_SPAN: NoopSpan;
 declare global {
@@ -104,7 +113,9 @@ declare class BraintrustState {
     currentExperiment: Experiment | undefined;
     currentLogger: Logger<false> | undefined;
     currentSpan: IsoAsyncLocalStorage<Span>;
+    private _globalBgLogger;
     appUrl: string | null;
+    appPublicUrl: string | null;
     loginToken: string | null;
     orgId: string | null;
     orgName: string | null;
@@ -113,10 +124,12 @@ declare class BraintrustState {
     gitMetadataSettings?: GitMetadataSettings;
     private _apiConn;
     private _logConn;
+    private _globalBgLoggerDirty;
     constructor();
     resetLoginInfo(): void;
     apiConn(): HTTPConnection;
     logConn(): HTTPConnection;
+    globalBgLogger(): BackgroundLogger;
 }
 export declare function _internalSetInitialState(): void;
 export declare const _internalGetGlobalState: () => BraintrustState;
@@ -161,10 +174,14 @@ export declare class Logger<IsAsyncFlush extends boolean> {
     private logOptions;
     private bgLogger;
     private lastStartTime;
+    private lazyId;
+    private calledStartSpan;
     kind: "logger";
     constructor(lazyMetadata: LazyValue<OrgProjectMetadata>, logOptions?: LogOptions<IsAsyncFlush>);
     get org_id(): Promise<string>;
     get project(): Promise<ObjectMetadata>;
+    get id(): Promise<string>;
+    private spanParentObjectType;
     private getState;
     /**
      * Log a single event. The event will be batched and uploaded behind the scenes if `logOptions.asyncFlush` is true.
@@ -178,11 +195,11 @@ export declare class Logger<IsAsyncFlush extends boolean> {
      * @param event.metrics: (Optional) a dictionary of metrics to log. The following keys are populated automatically: "start", "end".
      * @param event.id: (Optional) a unique identifier for the event. If you don't provide one, BrainTrust will generate one for you.
      * @param options Additional logging options
-     * @param options.allowLogConcurrentWithActiveSpan in rare cases where you need to log at the top level separately from an active span on the logger, set this to true.
+     * @param options.allowConcurrentWithSpans in rare cases where you need to log at the top level separately from spans on the logger elsewhere, set this to true.
      * :returns: The `id` of the logged event.
      */
     log(event: Readonly<StartSpanEventArgs>, options?: {
-        allowLogConcurrentWithActiveSpan?: boolean;
+        allowConcurrentWithSpans?: boolean;
     }): PromiseUnless<IsAsyncFlush, string>;
     /**
      * Create a new toplevel span underneath the logger. The name defaults to "root".
@@ -190,7 +207,6 @@ export declare class Logger<IsAsyncFlush extends boolean> {
      * See `Span.traced` for full details.
      */
     traced<R>(callback: (span: Span) => R, args?: StartSpanArgs & SetCurrentArg): PromiseUnless<IsAsyncFlush, R>;
-    private lazyParentIds;
     /**
      * Lower-level alternative to `traced`. This allows you to start a span yourself, and can be useful in situations
      * where you cannot use callbacks. However, spans started with `startSpan` will not be marked as the "current span",
@@ -199,6 +215,7 @@ export declare class Logger<IsAsyncFlush extends boolean> {
      * See `traced` for full details.
      */
     startSpan(args?: StartSpanArgs): Span;
+    private startSpanImpl;
     /**
      * Log feedback to an event. Feedback is used to save feedback scores, set an expected value, or add a comment.
      *
@@ -211,6 +228,10 @@ export declare class Logger<IsAsyncFlush extends boolean> {
      * @param event.source (Optional) the source of the feedback. Must be one of "external" (default), "app", or "api".
      */
     logFeedback(event: LogFeedbackFullArgs): void;
+    /**
+     * Return a serialized representation of the logger that can be used to start subspans in other places. See `Span.start_span` for more details.
+     */
+    export(): Promise<string>;
     flush(): Promise<void>;
     get asyncFlush(): IsAsyncFlush | undefined;
 }
@@ -466,7 +487,7 @@ export declare function getSpanParentObject<IsAsyncFlush extends boolean>(option
  *  * Currently-active experiment
  *  * Currently-active logger
  *
- * and creates a span under the first one that is active. If none of these are active, it returns a no-op span object.
+ * and creates a span under the first one that is active. Alternatively, if `parent` is specified, it creates a span under the specified parent row. If none of these are active, it returns a no-op span object.
  *
  * See `Span.traced` for full details.
  */
@@ -523,11 +544,14 @@ export declare class Experiment extends ObjectFetcher<ExperimentEvent> {
     readonly dataset?: AnyDataset;
     bgLogger: BackgroundLogger;
     private lastStartTime;
+    private lazyId;
+    private calledStartSpan;
     kind: "experiment";
     constructor(lazyMetadata: LazyValue<ProjectExperimentMetadata>, dataset?: AnyDataset);
     get id(): Promise<string>;
     get name(): Promise<string>;
     get project(): Promise<ObjectMetadata>;
+    private spanParentObjectType;
     protected getState(): Promise<BraintrustState>;
     /**
      * Log a single event to the experiment. The event will be batched and uploaded behind the scenes.
@@ -543,11 +567,11 @@ export declare class Experiment extends ObjectFetcher<ExperimentEvent> {
      * @param event.dataset_record_id: (Optional) the id of the dataset record that this event is associated with. This field is required if and only if the experiment is associated with a dataset.
      * @param event.inputs: (Deprecated) the same as `input` (will be removed in a future version).
      * @param options Additional logging options
-     * @param options.allowLogConcurrentWithActiveSpan in rare cases where you need to log at the top level separately from an active span on the experiment, set this to true.
+     * @param options.allowConcurrentWithSpans in rare cases where you need to log at the top level separately from spans on the experiment elsewhere, set this to true.
      * :returns: The `id` of the logged event.
      */
     log(event: Readonly<ExperimentLogFullArgs>, options?: {
-        allowLogConcurrentWithActiveSpan?: boolean;
+        allowConcurrentWithSpans?: boolean;
     }): string;
     /**
      * Create a new toplevel span underneath the experiment. The name defaults to "root".
@@ -555,7 +579,6 @@ export declare class Experiment extends ObjectFetcher<ExperimentEvent> {
      * See `Span.traced` for full details.
      */
     traced<R>(callback: (span: Span) => R, args?: StartSpanArgs & SetCurrentArg): R;
-    private lazyParentIds;
     /**
      * Lower-level alternative to `traced`. This allows you to start a span yourself, and can be useful in situations
      * where you cannot use callbacks. However, spans started with `startSpan` will not be marked as the "current span",
@@ -564,6 +587,7 @@ export declare class Experiment extends ObjectFetcher<ExperimentEvent> {
      * See `traced` for full details.
      */
     startSpan(args?: StartSpanArgs): Span;
+    private startSpanImpl;
     fetchBaseExperiment(): Promise<{
         id: any;
         name: any;
@@ -592,6 +616,10 @@ export declare class Experiment extends ObjectFetcher<ExperimentEvent> {
      * @param event.source (Optional) the source of the feedback. Must be one of "external" (default), "app", or "api".
      */
     logFeedback(event: LogFeedbackFullArgs): void;
+    /**
+     * Return a serialized representation of the experiment that can be used to start subspans in other places. See `Span.start_span` for more details.
+     */
+    export(): Promise<string>;
     /**
      * Flush any pending rows to the server.
      */
@@ -612,10 +640,6 @@ export declare class ReadonlyExperiment extends ObjectFetcher<ExperimentEvent> {
     protected getState(): Promise<BraintrustState>;
     asDataset<Input, Expected>(): AsyncGenerator<EvalCase<Input, Expected, void>>;
 }
-type ParentSpanInfo = {
-    span_id: string;
-    root_span_id: string;
-};
 /**
  * Primary implementation of the `Span` interface. See the `Span` interface for full details on each method.
  *
@@ -626,26 +650,30 @@ export declare class SpanImpl implements Span {
     private internalData;
     private isMerge;
     private loggedEndTime;
-    parentObject: Experiment | Logger<any>;
-    private parentIds;
-    private readonly rowIds;
+    private parentObjectType;
+    private parentObjectId;
+    private parentRowId;
+    private _id;
     kind: "span";
     constructor(args: {
-        parentObject: Experiment | Logger<any>;
-        parentIds: LazyValue<ParentExperimentIds | ParentProjectLogIds>;
+        parentObjectType: SpanParentObjectType;
+        parentObjectId: LazyValue<string>;
+        parentRowId: string;
         bgLogger: BackgroundLogger;
-    } & Omit<StartSpanArgs, "parentId"> & ({
-        parentSpanInfo?: ParentSpanInfo;
-    } | {
-        parentId?: string;
-    }));
+        defaultRootType?: SpanType;
+    } & Omit<StartSpanArgs, "parent" & "parentId">);
     get id(): string;
     log(event: ExperimentLogPartialArgs): void;
     logFeedback(event: Omit<LogFeedbackFullArgs, "id">): void;
     traced<R>(callback: (span: Span) => R, args?: StartSpanArgs & SetCurrentArg): R;
     startSpan(args?: StartSpanArgs): Span;
     end(args?: EndSpanArgs): number;
+    /**
+     * Return a serialized representation of the span that can be used to start subspans in other places. See `Span.start_span` for more details.
+     */
+    export(): Promise<string>;
     close(args?: EndSpanArgs): number;
+    flush(): Promise<void>;
 }
 /**
  * A dataset is a collection of records, such as model inputs and expected outputs, which represent
@@ -654,7 +682,7 @@ export declare class SpanImpl implements Span {
  *
  * You should not create `Dataset` objects directly. Instead, use the `braintrust.initDataset()` method.
  */
-declare class Dataset<IsLegacyDataset extends boolean = typeof DEFAULT_IS_LEGACY_DATASET> extends ObjectFetcher<DatasetRecord<IsLegacyDataset>> {
+export declare class Dataset<IsLegacyDataset extends boolean = typeof DEFAULT_IS_LEGACY_DATASET> extends ObjectFetcher<DatasetRecord<IsLegacyDataset>> {
     private readonly lazyMetadata;
     private bgLogger;
     constructor(lazyMetadata: LazyValue<ProjectDatasetMetadata>, pinnedVersion?: string, legacy?: IsLegacyDataset);
@@ -764,9 +792,9 @@ export type AnyDataset = Dataset<boolean>;
 export interface ScoreSummary {
     name: string;
     score: number;
-    diff: number;
-    improvements: number;
-    regressions: number;
+    diff?: number;
+    improvements?: number;
+    regressions?: number;
 }
 /**
  * Summary of a metric's performance.
@@ -797,11 +825,11 @@ export interface MetricSummary {
 export interface ExperimentSummary {
     projectName: string;
     experimentName: string;
-    projectUrl: string;
-    experimentUrl: string;
-    comparisonExperimentName: string | undefined;
-    scores: Record<string, ScoreSummary> | undefined;
-    metrics: Record<string, MetricSummary> | undefined;
+    projectUrl?: string;
+    experimentUrl?: string;
+    comparisonExperimentName?: string;
+    scores: Record<string, ScoreSummary>;
+    metrics?: Record<string, MetricSummary>;
 }
 /**
  * Summary of a dataset's data.