@bitfab/sdk 0.38.10 → 0.40.0

package/dist/index.d.cts

@@ -540,7 +540,11 @@ declare class HttpClient {
     lookupFunction<T>(name: string): Promise<T>;
     getAutoTracePolicy<T>(traceFunctionKey: string, protocol: string): Promise<T>;
     getTraceSpan(traceId: string, lookup: SpanLookup): Promise<CapturedSpan | null>;
-    private get;
+    /**
+     * GET a JSON endpoint on the service with the client's API key. Throws a
+     * `BitfabError` carrying the status text for any non-2xx response.
+     */
+    get<T>(endpoint: string): Promise<T>;
     /**
      * Queue an internal trace (from local BAML execution via `call()`) onto this
      * client's batching transport. `functionId` moves into the payload because
@@ -1034,6 +1038,141 @@ declare class BitfabVercelAiHandler {
     get middleware(): BitfabLanguageModelMiddleware;
 }
 
+interface DatasetGraderRef {
+    id: string;
+    name: string | null;
+}
+interface Dataset {
+    id: string;
+    traceFunctionKey: string;
+    name: string;
+    description: string | null;
+    traceCount: number;
+    graders: DatasetGraderRef[];
+    createdAt: string;
+    updatedAt: string;
+}
+interface SaveDatasetParams {
+    traceFunctionKey: string;
+    name: string;
+    description?: string;
+}
+interface SaveDatasetResult {
+    dataset: Dataset;
+    created: boolean;
+}
+interface ListDatasetsParams {
+    traceFunctionKey?: string;
+}
+interface DatasetTraceIds {
+    datasetId: string;
+    traceIds: string[];
+}
+interface AddDatasetTracesResult {
+    dataset: Dataset;
+    addedTraceIds: string[];
+    alreadyPresentTraceIds: string[];
+    skippedTraceIds: string[];
+}
+interface RemoveDatasetTracesResult {
+    dataset: Dataset;
+    removedTraceIds: string[];
+    notPresentTraceIds: string[];
+}
+interface AddDatasetGradersResult {
+    dataset: Dataset;
+    addedGraderIds: string[];
+    alreadyAssignedGraderIds: string[];
+    skippedGraderIds: string[];
+}
+interface RemoveDatasetGradersResult {
+    dataset: Dataset;
+    removedGraderIds: string[];
+    notAssignedGraderIds: string[];
+}
+type GraderRerunStatus = "pending" | "running" | "completed" | "errored";
+interface GraderRerunProgress {
+    completedTraces: number;
+    totalTraces: number;
+    graderCount: number;
+}
+interface GraderRerunResult {
+    tracesGraded: number;
+    gradersRun: number;
+}
+interface GraderRerun {
+    id: string;
+    status: GraderRerunStatus;
+    graderIds: string[];
+    progress: GraderRerunProgress | null;
+    result: GraderRerunResult | null;
+    error: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface RerunGradersOptions {
+    graderIds?: string[];
+    wait?: boolean;
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+}
+interface RerunGradersResult {
+    run: GraderRerun;
+    joinedExisting: boolean;
+}
+/**
+ * Dataset operations for the authenticated organization, reached as
+ * `client.datasets`. A dataset is a named bucket of traces scoped to one trace
+ * function. Experiments replay against it and its graders score its members.
+ */
+declare class DatasetsClient {
+    private readonly httpClient;
+    constructor(httpClient: HttpClient);
+    /**
+     * Create a dataset, or update the one already named this way under the same
+     * trace function. `created` reports which happened. An omitted description
+     * leaves an existing one untouched.
+     */
+    save(params: SaveDatasetParams): Promise<SaveDatasetResult>;
+    /**
+     * List datasets, scoped to one trace function when `traceFunctionKey` is
+     * given and organization-wide otherwise.
+     */
+    list(params?: ListDatasetsParams): Promise<Dataset[]>;
+    /** Fetch one dataset by id. Rejects with a 404 `BitfabError` when it is not in this organization. */
+    get(datasetId: string): Promise<Dataset>;
+    /** The ids of every trace in the dataset, the same membership a replay with `datasetId` selects. */
+    listTraces(datasetId: string): Promise<DatasetTraceIds>;
+    /**
+     * Add traces to the dataset (1 to 100 ids per call). Traces outside the
+     * organization or under another trace function are reported in
+     * `skippedTraceIds` rather than failing the call.
+     */
+    addTraces(datasetId: string, traceIds: string[]): Promise<AddDatasetTracesResult>;
+    /** Remove traces from the dataset. The traces themselves are never deleted. */
+    removeTraces(datasetId: string, traceIds: string[]): Promise<RemoveDatasetTracesResult>;
+    /**
+     * Assign graders to the dataset (1 to 100 ids per call). Graders outside the
+     * organization or under another trace function are reported in
+     * `skippedGraderIds` rather than failing the call.
+     */
+    addGraders(datasetId: string, graderIds: string[]): Promise<AddDatasetGradersResult>;
+    /** Unassign graders from the dataset. */
+    removeGraders(datasetId: string, graderIds: string[]): Promise<RemoveDatasetGradersResult>;
+    /**
+     * Re-run graders over every trace in the dataset. Defaults to every assigned
+     * grader; an unassigned id is rejected. Waits for the run to finish (up to
+     * `timeoutMs`, default 90s) unless `wait` is `false`, and returns the last
+     * run state seen either way. A request matching an in-flight run joins it.
+     */
+    rerunGraders(datasetId: string, options?: RerunGradersOptions): Promise<RerunGradersResult>;
+    /**
+     * The dataset's active grader re-run, or the run named by `runId`. Returns
+     * `null` when nothing is active or the run does not belong to this dataset.
+     */
+    getGraderRerun(datasetId: string, runId?: string): Promise<GraderRerun | null>;
+}
+
 /**
  * LangGraph/LangChain callback handler for Bitfab tracing.
  *
@@ -1288,6 +1427,13 @@ declare class BitfabOpenAIAgentHandler {
  */
 
 type MockStrategy = "none" | "all" | "marked";
+/**
+ * How a source trace came to exist. A `seeded` trace was written from a case
+ * with {@link Bitfab.seedTrace} rather than executed, so it has no recorded
+ * child spans to mock from and no database state to restore, and its recorded
+ * output is the value the case expected rather than a previous run's result.
+ */
+type TraceIngestionType = "captured" | "seeded";
 /**
  * How the DB-snapshot branch each replay item runs against is sized and warmed.
  *
@@ -1418,6 +1564,15 @@ interface ReplayOptions {
      * Omit it to spread the recorded inputs unchanged.
      */
     adaptInputs?: (inputs: unknown[], ctx: AdaptContext) => unknown[];
+    /**
+     * Resolve every item's inputs and stop, without calling the function.
+     *
+     * Selection, span fetch, deserialization, and `adaptInputs` all run, so each
+     * item reports the exact arguments the function would have received. Nothing
+     * executes and no replay traces are produced, which is the cheap way to check
+     * that recorded inputs still fit the current signature.
+     */
+    dryRun?: boolean;
     /**
      * Called once per item as it finishes, in completion order (not input
      * order), with running totals for the whole run. Use it to render replay
@@ -1620,8 +1775,17 @@ interface ReplayItem<T> {
     input: unknown[];
     /** The result returned by the function during replay, or undefined on error. */
     result: T | undefined;
-    /** The original output from the historical trace. */
+    /**
+     * The original output from the historical trace. For a `seeded` source this
+     * is the value the case expected, not a previous run's result, so a
+     * difference means the code missed the expectation rather than drifted.
+     */
     originalOutput: unknown;
+    /**
+     * How the source trace came to exist. Absent on servers that predate the
+     * field, which only ever served captured traces.
+     */
+    ingestionType?: TraceIngestionType;
     /**
      * Backward-compatible message for either error kind. Prefer `traceError` and
      * `replayError` when callers need the original exception and its source.
@@ -2247,6 +2411,8 @@ declare class Bitfab {
     private readonly explicitlyEnabled;
     private readonly strict;
     private readonly httpClient;
+    /** Dataset operations for the authenticated organization. */
+    readonly datasets: DatasetsClient;
     private readonly bamlClient;
     private readonly dbSnapshot;
     private readonly autoTracePolicyRefreshes;
@@ -2716,6 +2882,45 @@ declare class Bitfab {
     registerMockOverride(traceFunctionKey: string, override: MockOverride | MockOverrideResolver): void;
     /** Remove all overrides registered via {@link registerMockOverride}. */
     clearMockOverrides(): void;
+    /**
+     * Write a replayable trace from a case, without running anything.
+     *
+     * Use this to turn a corpus you already hold (a Braintrust dataset, a
+     * spreadsheet, hand-written cases) into traces that {@link replay} can
+     * select. The recorded root span carries `input` as its input and `expected`
+     * as its output, so replay reports each item against the value you expected
+     * rather than against a previous run.
+     *
+     * A seeded trace has no child spans and no database pin, so replay mocking
+     * has nothing recorded to substitute and `dbBranch` refuses it. Pass
+     * `mockOverride` at replay time for calls that must not run.
+     *
+     * @returns The trace ID, usable with `replay({ traceIds: [...] })`.
+     */
+    seedTrace(traceFunctionKey: string, options: {
+        /** Arguments spread into the function at replay, as `fn(...input)`. */
+        input: unknown[];
+        /**
+         * The output this case should produce. Optional, but without it the
+         * replay has nothing to be judged against.
+         */
+        expected?: unknown;
+        /**
+         * The function these inputs will replay through. When given, the call is
+         * checked against its arity here, so a case that cannot supply the
+         * function's required arguments fails now instead of at replay. Omit it
+         * when the seeding script cannot import the function.
+         */
+        fn?: (...args: any[]) => unknown;
+        /**
+         * Recorded on the trace. Put the source row's id here so a seeded trace
+         * can be traced back to the case it came from.
+         */
+        metadata?: Record<string, unknown>;
+        sessionId?: string;
+        spanName?: string;
+        spanType?: SpanType;
+    }): string;
     replay<TReturn>(traceFunctionKey: string, fn: (...args: any[]) => TReturn | Promise<TReturn>, options?: ReplayOptions): Promise<ReplayResult<TReturn>>;
 }
 /**
@@ -2891,7 +3096,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.38.10";
+declare const __version__ = "0.40.0";
 
 /**
  * Constants for the Bitfab SDK.
@@ -2993,5 +3198,30 @@ type ReplayRegistry = Record<string, ReplayRegistration>;
  * SDK upgrade can add replay features without regenerating the project file.
  */
 declare function defineReplayRegistry<TRegistry extends ReplayRegistry>(registry: TRegistry): TRegistry;
+/** One case to seed, in the shape `--seed` reads from JSON or JSONL. */
+interface SeedCase {
+    /** Arguments spread into the registered function at replay. */
+    input: unknown[];
+    /** The output this case should produce. */
+    expected?: unknown;
+    /** Recorded on the trace, for tracing a seeded case back to its source row. */
+    metadata?: Record<string, unknown>;
+    sessionId?: string;
+}
+interface SeedResult {
+    pipeline: string;
+    traceFunctionKey: string;
+    traceIds: string[];
+}
+/**
+ * Seed cases through an already-registered pipeline.
+ *
+ * The registration is the whole point: it already holds the client, the exact
+ * function production calls, and the trace function key replay selects by, so
+ * a seeded case is guaranteed to line up with the replay that will read it.
+ * Passing the registered function to `seedTrace` also means a case that cannot
+ * supply its required arguments is rejected here rather than at replay.
+ */
+declare function seedFromRegistry(registry: ReplayRegistry, pipeline: string, cases: readonly SeedCase[]): Promise<SeedResult>;
 
-export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, BitfabLangGraphIntegration, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CaptureWhen, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbBranchOptions, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, HttpClient, type LangGraphIntegrationOptions, type MockOverride, type MockOverrideCtx, type MockOverrideInput, type MockOverrideResolver, type MockStrategy, type MockValue, NO_MOCK_OVERRIDE, type NodeMatcher, type NodeMethodDecorator, type NodeOptions, type ProviderDefinition, ReplayBranch, ReplayError, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayOptions, type ReplayOptionsFactory, type ReplayProgress, type ReplayProgressItem, type ReplayRegistration, type ReplayRegistry, type ReplayRegistryContext, type ReplayRegistryOptions, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, serializeReplayResult };
+export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AddDatasetGradersResult, type AddDatasetTracesResult, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, BitfabLangGraphIntegration, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CaptureWhen, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type Dataset, type DatasetGraderRef, type DatasetTraceIds, DatasetsClient, type DbBranchOptions, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type GraderRerun, type GraderRerunProgress, type GraderRerunResult, type GraderRerunStatus, HttpClient, type LangGraphIntegrationOptions, type ListDatasetsParams, type MockOverride, type MockOverrideCtx, type MockOverrideInput, type MockOverrideResolver, type MockStrategy, type MockValue, NO_MOCK_OVERRIDE, type NodeMatcher, type NodeMethodDecorator, type NodeOptions, type ProviderDefinition, type RemoveDatasetGradersResult, type RemoveDatasetTracesResult, ReplayBranch, ReplayError, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayOptions, type ReplayOptionsFactory, type ReplayProgress, type ReplayProgressItem, type ReplayRegistration, type ReplayRegistry, type ReplayRegistryContext, type ReplayRegistryOptions, type ReplayResult, type RerunGradersOptions, type RerunGradersResult, SUPPORTED_PROVIDERS, type SaveDatasetParams, type SaveDatasetResult, type SeedCase, type SeedResult, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceIngestionType, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, seedFromRegistry, serializeReplayResult };

package/dist/index.d.ts

@@ -540,7 +540,11 @@ declare class HttpClient {
     lookupFunction<T>(name: string): Promise<T>;
     getAutoTracePolicy<T>(traceFunctionKey: string, protocol: string): Promise<T>;
     getTraceSpan(traceId: string, lookup: SpanLookup): Promise<CapturedSpan | null>;
-    private get;
+    /**
+     * GET a JSON endpoint on the service with the client's API key. Throws a
+     * `BitfabError` carrying the status text for any non-2xx response.
+     */
+    get<T>(endpoint: string): Promise<T>;
     /**
      * Queue an internal trace (from local BAML execution via `call()`) onto this
      * client's batching transport. `functionId` moves into the payload because
@@ -1034,6 +1038,141 @@ declare class BitfabVercelAiHandler {
     get middleware(): BitfabLanguageModelMiddleware;
 }
 
+interface DatasetGraderRef {
+    id: string;
+    name: string | null;
+}
+interface Dataset {
+    id: string;
+    traceFunctionKey: string;
+    name: string;
+    description: string | null;
+    traceCount: number;
+    graders: DatasetGraderRef[];
+    createdAt: string;
+    updatedAt: string;
+}
+interface SaveDatasetParams {
+    traceFunctionKey: string;
+    name: string;
+    description?: string;
+}
+interface SaveDatasetResult {
+    dataset: Dataset;
+    created: boolean;
+}
+interface ListDatasetsParams {
+    traceFunctionKey?: string;
+}
+interface DatasetTraceIds {
+    datasetId: string;
+    traceIds: string[];
+}
+interface AddDatasetTracesResult {
+    dataset: Dataset;
+    addedTraceIds: string[];
+    alreadyPresentTraceIds: string[];
+    skippedTraceIds: string[];
+}
+interface RemoveDatasetTracesResult {
+    dataset: Dataset;
+    removedTraceIds: string[];
+    notPresentTraceIds: string[];
+}
+interface AddDatasetGradersResult {
+    dataset: Dataset;
+    addedGraderIds: string[];
+    alreadyAssignedGraderIds: string[];
+    skippedGraderIds: string[];
+}
+interface RemoveDatasetGradersResult {
+    dataset: Dataset;
+    removedGraderIds: string[];
+    notAssignedGraderIds: string[];
+}
+type GraderRerunStatus = "pending" | "running" | "completed" | "errored";
+interface GraderRerunProgress {
+    completedTraces: number;
+    totalTraces: number;
+    graderCount: number;
+}
+interface GraderRerunResult {
+    tracesGraded: number;
+    gradersRun: number;
+}
+interface GraderRerun {
+    id: string;
+    status: GraderRerunStatus;
+    graderIds: string[];
+    progress: GraderRerunProgress | null;
+    result: GraderRerunResult | null;
+    error: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface RerunGradersOptions {
+    graderIds?: string[];
+    wait?: boolean;
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+}
+interface RerunGradersResult {
+    run: GraderRerun;
+    joinedExisting: boolean;
+}
+/**
+ * Dataset operations for the authenticated organization, reached as
+ * `client.datasets`. A dataset is a named bucket of traces scoped to one trace
+ * function. Experiments replay against it and its graders score its members.
+ */
+declare class DatasetsClient {
+    private readonly httpClient;
+    constructor(httpClient: HttpClient);
+    /**
+     * Create a dataset, or update the one already named this way under the same
+     * trace function. `created` reports which happened. An omitted description
+     * leaves an existing one untouched.
+     */
+    save(params: SaveDatasetParams): Promise<SaveDatasetResult>;
+    /**
+     * List datasets, scoped to one trace function when `traceFunctionKey` is
+     * given and organization-wide otherwise.
+     */
+    list(params?: ListDatasetsParams): Promise<Dataset[]>;
+    /** Fetch one dataset by id. Rejects with a 404 `BitfabError` when it is not in this organization. */
+    get(datasetId: string): Promise<Dataset>;
+    /** The ids of every trace in the dataset, the same membership a replay with `datasetId` selects. */
+    listTraces(datasetId: string): Promise<DatasetTraceIds>;
+    /**
+     * Add traces to the dataset (1 to 100 ids per call). Traces outside the
+     * organization or under another trace function are reported in
+     * `skippedTraceIds` rather than failing the call.
+     */
+    addTraces(datasetId: string, traceIds: string[]): Promise<AddDatasetTracesResult>;
+    /** Remove traces from the dataset. The traces themselves are never deleted. */
+    removeTraces(datasetId: string, traceIds: string[]): Promise<RemoveDatasetTracesResult>;
+    /**
+     * Assign graders to the dataset (1 to 100 ids per call). Graders outside the
+     * organization or under another trace function are reported in
+     * `skippedGraderIds` rather than failing the call.
+     */
+    addGraders(datasetId: string, graderIds: string[]): Promise<AddDatasetGradersResult>;
+    /** Unassign graders from the dataset. */
+    removeGraders(datasetId: string, graderIds: string[]): Promise<RemoveDatasetGradersResult>;
+    /**
+     * Re-run graders over every trace in the dataset. Defaults to every assigned
+     * grader; an unassigned id is rejected. Waits for the run to finish (up to
+     * `timeoutMs`, default 90s) unless `wait` is `false`, and returns the last
+     * run state seen either way. A request matching an in-flight run joins it.
+     */
+    rerunGraders(datasetId: string, options?: RerunGradersOptions): Promise<RerunGradersResult>;
+    /**
+     * The dataset's active grader re-run, or the run named by `runId`. Returns
+     * `null` when nothing is active or the run does not belong to this dataset.
+     */
+    getGraderRerun(datasetId: string, runId?: string): Promise<GraderRerun | null>;
+}
+
 /**
  * LangGraph/LangChain callback handler for Bitfab tracing.
  *
@@ -1288,6 +1427,13 @@ declare class BitfabOpenAIAgentHandler {
  */
 
 type MockStrategy = "none" | "all" | "marked";
+/**
+ * How a source trace came to exist. A `seeded` trace was written from a case
+ * with {@link Bitfab.seedTrace} rather than executed, so it has no recorded
+ * child spans to mock from and no database state to restore, and its recorded
+ * output is the value the case expected rather than a previous run's result.
+ */
+type TraceIngestionType = "captured" | "seeded";
 /**
  * How the DB-snapshot branch each replay item runs against is sized and warmed.
  *
@@ -1418,6 +1564,15 @@ interface ReplayOptions {
      * Omit it to spread the recorded inputs unchanged.
      */
     adaptInputs?: (inputs: unknown[], ctx: AdaptContext) => unknown[];
+    /**
+     * Resolve every item's inputs and stop, without calling the function.
+     *
+     * Selection, span fetch, deserialization, and `adaptInputs` all run, so each
+     * item reports the exact arguments the function would have received. Nothing
+     * executes and no replay traces are produced, which is the cheap way to check
+     * that recorded inputs still fit the current signature.
+     */
+    dryRun?: boolean;
     /**
      * Called once per item as it finishes, in completion order (not input
      * order), with running totals for the whole run. Use it to render replay
@@ -1620,8 +1775,17 @@ interface ReplayItem<T> {
     input: unknown[];
     /** The result returned by the function during replay, or undefined on error. */
     result: T | undefined;
-    /** The original output from the historical trace. */
+    /**
+     * The original output from the historical trace. For a `seeded` source this
+     * is the value the case expected, not a previous run's result, so a
+     * difference means the code missed the expectation rather than drifted.
+     */
     originalOutput: unknown;
+    /**
+     * How the source trace came to exist. Absent on servers that predate the
+     * field, which only ever served captured traces.
+     */
+    ingestionType?: TraceIngestionType;
     /**
      * Backward-compatible message for either error kind. Prefer `traceError` and
      * `replayError` when callers need the original exception and its source.
@@ -2247,6 +2411,8 @@ declare class Bitfab {
     private readonly explicitlyEnabled;
     private readonly strict;
     private readonly httpClient;
+    /** Dataset operations for the authenticated organization. */
+    readonly datasets: DatasetsClient;
     private readonly bamlClient;
     private readonly dbSnapshot;
     private readonly autoTracePolicyRefreshes;
@@ -2716,6 +2882,45 @@ declare class Bitfab {
     registerMockOverride(traceFunctionKey: string, override: MockOverride | MockOverrideResolver): void;
     /** Remove all overrides registered via {@link registerMockOverride}. */
     clearMockOverrides(): void;
+    /**
+     * Write a replayable trace from a case, without running anything.
+     *
+     * Use this to turn a corpus you already hold (a Braintrust dataset, a
+     * spreadsheet, hand-written cases) into traces that {@link replay} can
+     * select. The recorded root span carries `input` as its input and `expected`
+     * as its output, so replay reports each item against the value you expected
+     * rather than against a previous run.
+     *
+     * A seeded trace has no child spans and no database pin, so replay mocking
+     * has nothing recorded to substitute and `dbBranch` refuses it. Pass
+     * `mockOverride` at replay time for calls that must not run.
+     *
+     * @returns The trace ID, usable with `replay({ traceIds: [...] })`.
+     */
+    seedTrace(traceFunctionKey: string, options: {
+        /** Arguments spread into the function at replay, as `fn(...input)`. */
+        input: unknown[];
+        /**
+         * The output this case should produce. Optional, but without it the
+         * replay has nothing to be judged against.
+         */
+        expected?: unknown;
+        /**
+         * The function these inputs will replay through. When given, the call is
+         * checked against its arity here, so a case that cannot supply the
+         * function's required arguments fails now instead of at replay. Omit it
+         * when the seeding script cannot import the function.
+         */
+        fn?: (...args: any[]) => unknown;
+        /**
+         * Recorded on the trace. Put the source row's id here so a seeded trace
+         * can be traced back to the case it came from.
+         */
+        metadata?: Record<string, unknown>;
+        sessionId?: string;
+        spanName?: string;
+        spanType?: SpanType;
+    }): string;
     replay<TReturn>(traceFunctionKey: string, fn: (...args: any[]) => TReturn | Promise<TReturn>, options?: ReplayOptions): Promise<ReplayResult<TReturn>>;
 }
 /**
@@ -2891,7 +3096,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.38.10";
+declare const __version__ = "0.40.0";
 
 /**
  * Constants for the Bitfab SDK.
@@ -2993,5 +3198,30 @@ type ReplayRegistry = Record<string, ReplayRegistration>;
  * SDK upgrade can add replay features without regenerating the project file.
  */
 declare function defineReplayRegistry<TRegistry extends ReplayRegistry>(registry: TRegistry): TRegistry;
+/** One case to seed, in the shape `--seed` reads from JSON or JSONL. */
+interface SeedCase {
+    /** Arguments spread into the registered function at replay. */
+    input: unknown[];
+    /** The output this case should produce. */
+    expected?: unknown;
+    /** Recorded on the trace, for tracing a seeded case back to its source row. */
+    metadata?: Record<string, unknown>;
+    sessionId?: string;
+}
+interface SeedResult {
+    pipeline: string;
+    traceFunctionKey: string;
+    traceIds: string[];
+}
+/**
+ * Seed cases through an already-registered pipeline.
+ *
+ * The registration is the whole point: it already holds the client, the exact
+ * function production calls, and the trace function key replay selects by, so
+ * a seeded case is guaranteed to line up with the replay that will read it.
+ * Passing the registered function to `seedTrace` also means a case that cannot
+ * supply its required arguments is rejected here rather than at replay.
+ */
+declare function seedFromRegistry(registry: ReplayRegistry, pipeline: string, cases: readonly SeedCase[]): Promise<SeedResult>;
 
-export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, BitfabLangGraphIntegration, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CaptureWhen, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbBranchOptions, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, HttpClient, type LangGraphIntegrationOptions, type MockOverride, type MockOverrideCtx, type MockOverrideInput, type MockOverrideResolver, type MockStrategy, type MockValue, NO_MOCK_OVERRIDE, type NodeMatcher, type NodeMethodDecorator, type NodeOptions, type ProviderDefinition, ReplayBranch, ReplayError, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayOptions, type ReplayOptionsFactory, type ReplayProgress, type ReplayProgressItem, type ReplayRegistration, type ReplayRegistry, type ReplayRegistryContext, type ReplayRegistryOptions, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, serializeReplayResult };
+export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AddDatasetGradersResult, type AddDatasetTracesResult, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, BitfabLangGraphIntegration, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CaptureWhen, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type Dataset, type DatasetGraderRef, type DatasetTraceIds, DatasetsClient, type DbBranchOptions, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type GraderRerun, type GraderRerunProgress, type GraderRerunResult, type GraderRerunStatus, HttpClient, type LangGraphIntegrationOptions, type ListDatasetsParams, type MockOverride, type MockOverrideCtx, type MockOverrideInput, type MockOverrideResolver, type MockStrategy, type MockValue, NO_MOCK_OVERRIDE, type NodeMatcher, type NodeMethodDecorator, type NodeOptions, type ProviderDefinition, type RemoveDatasetGradersResult, type RemoveDatasetTracesResult, ReplayBranch, ReplayError, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayOptions, type ReplayOptionsFactory, type ReplayProgress, type ReplayProgressItem, type ReplayRegistration, type ReplayRegistry, type ReplayRegistryContext, type ReplayRegistryOptions, type ReplayResult, type RerunGradersOptions, type RerunGradersResult, SUPPORTED_PROVIDERS, type SaveDatasetParams, type SaveDatasetResult, type SeedCase, type SeedResult, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceIngestionType, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, seedFromRegistry, serializeReplayResult };

package/dist/index.js

@@ -7,27 +7,31 @@ import {
   BitfabOpenAIAgentHandler,
   BitfabOpenAITracingProcessor,
   BitfabVercelAiHandler,
+  DatasetsClient,
   SUPPORTED_PROVIDERS,
   defineReplayRegistry,
   finalizers,
   getCurrentReplayBranch,
   getCurrentSpan,
-  getCurrentTrace
-} from "./chunk-UE4GGPM6.js";
+  getCurrentTrace,
+  seedFromRegistry
+} from "./chunk-5NT4YDCQ.js";
 import "./chunk-ZUD7OFYB.js";
 import {
   BITFAB_PROGRESS_PREFIX,
-  BitfabError,
-  DEFAULT_SERVICE_URL,
   DbBranchReplayError,
-  HttpClient,
   NO_MOCK_OVERRIDE,
   ReplayError,
-  __version__,
-  flushTraces,
   reportReplayProgress,
   serializeReplayResult
-} from "./chunk-BNOVHUQB.js";
+} from "./chunk-EXT5FK54.js";
+import {
+  BitfabError,
+  DEFAULT_SERVICE_URL,
+  HttpClient,
+  __version__,
+  flushTraces
+} from "./chunk-A22EYRSY.js";
 import "./chunk-H6LZRFMN.js";
 export {
   BITFAB_PROGRESS_PREFIX,
@@ -42,6 +46,7 @@ export {
   BitfabOpenAITracingProcessor,
   BitfabVercelAiHandler,
   DEFAULT_SERVICE_URL,
+  DatasetsClient,
   DbBranchReplayError,
   HttpClient,
   NO_MOCK_OVERRIDE,
@@ -55,6 +60,7 @@ export {
   getCurrentSpan,
   getCurrentTrace,
   reportReplayProgress,
+  seedFromRegistry,
   serializeReplayResult
 };
 //# sourceMappingURL=index.js.map