langsmith 0.8.4 → 0.8.5

package/dist/client.cjs

@@ -648,6 +648,12 @@ class Client {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "_stainlessVersionChecked", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
         Object.defineProperty(this, "manualFlushMode", {
             enumerable: true,
             configurable: true,
@@ -975,27 +981,37 @@ class Client {
         return needsV1Prefix ? `/v1/platform/${path}` : `/platform/${path}`;
     }
     get evaluators() {
+        this._checkStainlessVersion();
         return this.openAPIClient.onlineEvaluators;
     }
     get runs() {
+        this._checkStainlessVersion();
         return this.openAPIClient.runs;
     }
     /** Access the v2 sandboxes resource (registries, snapshots, boxes). */
     get sandboxes() {
+        this._checkStainlessVersion();
         return this.openAPIClient.sandboxes;
     }
     /** Access the v2 datasets resource (experimentRuns, etc.). */
     get datasets() {
+        this._checkStainlessVersion();
         return this.openAPIClient.datasets;
     }
     /** Access the threads resource (query, stats, listTraces). */
     get threads() {
+        this._checkStainlessVersion();
         return this.openAPIClient.threads;
     }
     /** Access the traces resource (query, listRuns). */
     get traces() {
+        this._checkStainlessVersion();
         return this.openAPIClient.traces;
     }
+    /** Access the public shared-run resource. */
+    get public() {
+        return this.openAPIClient.public;
+    }
     async processInputs(inputs) {
         if (this.hideInputs === false) {
             return inputs;
@@ -1482,15 +1498,26 @@ class Client {
         }
         return json;
     }
+    _checkStainlessVersion() {
+        if (this._stainlessVersionChecked)
+            return;
+        this._stainlessVersionChecked = true;
+        this._ensureServerInfo()
+            .then((serverInfo) => {
+            if (serverInfo?.version) {
+                _checkBackendVersion(serverInfo.version);
+            }
+        })
+            .catch(() => {
+            // _ensureServerInfo handles and logs its own errors
+        });
+    }
     async _ensureServerInfo() {
         if (this._getServerInfoPromise === undefined) {
             this._getServerInfoPromise = (async () => {
                 if (this._serverInfo === undefined) {
                     try {
                         this._serverInfo = await this._getServerInfo();
-                        if (this._serverInfo?.version) {
-                            _checkBackendVersion(this._serverInfo.version);
-                        }
                     }
                     catch (e) {
                         console.warn(`[LANGSMITH]: Failed to fetch info on supported operations. Falling back to batch operations and default limits. Info: ${e.status ?? "Unspecified status code"} ${e.message}`);
@@ -1506,6 +1533,10 @@ class Client {
             return serverInfo;
         });
     }
+    async _supportsSDBQuery() {
+        const serverInfo = await this._ensureServerInfo();
+        return serverInfo.instance_flags?.sdb_query_enabled === true;
+    }
     async _getSettings() {
         if (!this.settings) {
             this.settings = this._get("/settings");
@@ -2444,6 +2475,9 @@ class Client {
                 ...(await Promise.all(projectNames.map((name) => this.readProject({ projectName: name }).then((project) => project.id)))),
             ];
         }
+        if (projectIds_.length === 0) {
+            throw new Error("At least one of projectNames or projectIds must be provided.");
+        }
         const payload = {
             id,
             trace,
@@ -3827,7 +3861,7 @@ class Client {
         }
         return results_;
     }
-    async _logEvaluationFeedback(evaluatorResponse, run, sourceInfo) {
+    async _logEvaluationFeedback(evaluatorResponse, run, sourceInfo, sessionId) {
         const evalResults = this._selectEvalResults(evaluatorResponse);
         const feedbacks = [];
         for (const res of evalResults) {
@@ -3851,14 +3885,20 @@ class Client {
                 sourceRunId: res.sourceRunId,
                 feedbackConfig: res.feedbackConfig,
                 feedbackSourceType: "model",
-                sessionId: run?.session_id,
+                sessionId: run?.session_id ?? sessionId,
                 startTime: run?.start_time,
             }));
         }
         return [evalResults, feedbacks];
     }
-    async logEvaluationFeedback(evaluatorResponse, run, sourceInfo) {
-        const [results] = await this._logEvaluationFeedback(evaluatorResponse, run, sourceInfo);
+    async logEvaluationFeedback(evaluatorResponseOrParams, run, sourceInfo, sessionId) {
+        if (evaluatorResponseOrParams != null &&
+            typeof evaluatorResponseOrParams === "object" &&
+            "evaluatorResponse" in evaluatorResponseOrParams) {
+            const [results] = await this._logEvaluationFeedback(evaluatorResponseOrParams.evaluatorResponse, evaluatorResponseOrParams.run, evaluatorResponseOrParams.sourceInfo, evaluatorResponseOrParams.projectId);
+            return results;
+        }
+        const [results] = await this._logEvaluationFeedback(evaluatorResponseOrParams, run, sourceInfo, sessionId);
         return results;
     }
     /**

package/dist/client.d.ts

@@ -9,6 +9,7 @@ import { Sandboxes } from "./_openapi_client/resources/sandboxes/sandboxes.js";
 import { Datasets } from "./_openapi_client/resources/datasets/datasets.js";
 import { Threads } from "./_openapi_client/resources/threads.js";
 import { Traces } from "./_openapi_client/resources/traces.js";
+import { Public } from "./_openapi_client/resources/public/public.js";
 import { PromptCache } from "./utils/prompt_cache/index.js";
 import { ProfileAuth } from "./utils/profiles.js";
 export interface ClientConfig {
@@ -461,6 +462,7 @@ export declare class Client implements LangSmithTracingClientInterface {
     private traceBatchConcurrency;
     private _serverInfo;
     private _getServerInfoPromise?;
+    private _stainlessVersionChecked;
     private manualFlushMode;
     private _serializeWorker?;
     /**
@@ -528,6 +530,8 @@ export declare class Client implements LangSmithTracingClientInterface {
     get threads(): Threads;
     /** Access the traces resource (query, listRuns). */
     get traces(): Traces;
+    /** Access the public shared-run resource. */
+    get public(): Public;
     private processInputs;
     private processOutputs;
     private processMetadata;
@@ -580,7 +584,9 @@ export declare class Client implements LangSmithTracingClientInterface {
     private _sendBatchToOTELTranslator;
     private processRunOperation;
     protected _getServerInfo(): Promise<any>;
+    private _checkStainlessVersion;
     protected _ensureServerInfo(): Promise<Record<string, any>>;
+    _supportsSDBQuery(): Promise<boolean>;
     protected _getSettings(): Promise<LangSmithSettings>;
     /**
      * Flushes current queued traces.
@@ -1027,10 +1033,19 @@ export declare class Client implements LangSmithTracingClientInterface {
     _selectEvalResults(results: EvaluationResult | EvaluationResult[] | EvaluationResults): Array<EvaluationResult>;
     _logEvaluationFeedback(evaluatorResponse: EvaluationResult | EvaluationResult[] | EvaluationResults, run?: Run, sourceInfo?: {
         [key: string]: any;
-    }): Promise<[results: EvaluationResult[], feedbacks: Feedback[]]>;
+    }, sessionId?: string): Promise<[results: EvaluationResult[], feedbacks: Feedback[]]>;
+    logEvaluationFeedback(params: {
+        evaluatorResponse: EvaluationResult | EvaluationResult[] | EvaluationResults;
+        run: Run;
+        projectId: string;
+        sourceInfo?: {
+            [key: string]: any;
+        };
+    }): Promise<EvaluationResult[]>;
+    /** @deprecated Pass all params within an object and populate projectId. */
     logEvaluationFeedback(evaluatorResponse: EvaluationResult | EvaluationResult[] | EvaluationResults, run?: Run, sourceInfo?: {
         [key: string]: any;
-    }): Promise<EvaluationResult[]>;
+    }, sessionId?: string): Promise<EvaluationResult[]>;
     /**
      * API for managing feedback configs
      */

package/dist/client.js

@@ -609,6 +609,12 @@ export class Client {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "_stainlessVersionChecked", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
         Object.defineProperty(this, "manualFlushMode", {
             enumerable: true,
             configurable: true,
@@ -936,27 +942,37 @@ export class Client {
         return needsV1Prefix ? `/v1/platform/${path}` : `/platform/${path}`;
     }
     get evaluators() {
+        this._checkStainlessVersion();
         return this.openAPIClient.onlineEvaluators;
     }
     get runs() {
+        this._checkStainlessVersion();
         return this.openAPIClient.runs;
     }
     /** Access the v2 sandboxes resource (registries, snapshots, boxes). */
     get sandboxes() {
+        this._checkStainlessVersion();
         return this.openAPIClient.sandboxes;
     }
     /** Access the v2 datasets resource (experimentRuns, etc.). */
     get datasets() {
+        this._checkStainlessVersion();
         return this.openAPIClient.datasets;
     }
     /** Access the threads resource (query, stats, listTraces). */
     get threads() {
+        this._checkStainlessVersion();
         return this.openAPIClient.threads;
     }
     /** Access the traces resource (query, listRuns). */
     get traces() {
+        this._checkStainlessVersion();
         return this.openAPIClient.traces;
     }
+    /** Access the public shared-run resource. */
+    get public() {
+        return this.openAPIClient.public;
+    }
     async processInputs(inputs) {
         if (this.hideInputs === false) {
             return inputs;
@@ -1443,15 +1459,26 @@ export class Client {
         }
         return json;
     }
+    _checkStainlessVersion() {
+        if (this._stainlessVersionChecked)
+            return;
+        this._stainlessVersionChecked = true;
+        this._ensureServerInfo()
+            .then((serverInfo) => {
+            if (serverInfo?.version) {
+                _checkBackendVersion(serverInfo.version);
+            }
+        })
+            .catch(() => {
+            // _ensureServerInfo handles and logs its own errors
+        });
+    }
     async _ensureServerInfo() {
         if (this._getServerInfoPromise === undefined) {
             this._getServerInfoPromise = (async () => {
                 if (this._serverInfo === undefined) {
                     try {
                         this._serverInfo = await this._getServerInfo();
-                        if (this._serverInfo?.version) {
-                            _checkBackendVersion(this._serverInfo.version);
-                        }
                     }
                     catch (e) {
                         console.warn(`[LANGSMITH]: Failed to fetch info on supported operations. Falling back to batch operations and default limits. Info: ${e.status ?? "Unspecified status code"} ${e.message}`);
@@ -1467,6 +1494,10 @@ export class Client {
             return serverInfo;
         });
     }
+    async _supportsSDBQuery() {
+        const serverInfo = await this._ensureServerInfo();
+        return serverInfo.instance_flags?.sdb_query_enabled === true;
+    }
     async _getSettings() {
         if (!this.settings) {
             this.settings = this._get("/settings");
@@ -2405,6 +2436,9 @@ export class Client {
                 ...(await Promise.all(projectNames.map((name) => this.readProject({ projectName: name }).then((project) => project.id)))),
             ];
         }
+        if (projectIds_.length === 0) {
+            throw new Error("At least one of projectNames or projectIds must be provided.");
+        }
         const payload = {
             id,
             trace,
@@ -3788,7 +3822,7 @@ export class Client {
         }
         return results_;
     }
-    async _logEvaluationFeedback(evaluatorResponse, run, sourceInfo) {
+    async _logEvaluationFeedback(evaluatorResponse, run, sourceInfo, sessionId) {
         const evalResults = this._selectEvalResults(evaluatorResponse);
         const feedbacks = [];
         for (const res of evalResults) {
@@ -3812,14 +3846,20 @@ export class Client {
                 sourceRunId: res.sourceRunId,
                 feedbackConfig: res.feedbackConfig,
                 feedbackSourceType: "model",
-                sessionId: run?.session_id,
+                sessionId: run?.session_id ?? sessionId,
                 startTime: run?.start_time,
             }));
         }
         return [evalResults, feedbacks];
     }
-    async logEvaluationFeedback(evaluatorResponse, run, sourceInfo) {
-        const [results] = await this._logEvaluationFeedback(evaluatorResponse, run, sourceInfo);
+    async logEvaluationFeedback(evaluatorResponseOrParams, run, sourceInfo, sessionId) {
+        if (evaluatorResponseOrParams != null &&
+            typeof evaluatorResponseOrParams === "object" &&
+            "evaluatorResponse" in evaluatorResponseOrParams) {
+            const [results] = await this._logEvaluationFeedback(evaluatorResponseOrParams.evaluatorResponse, evaluatorResponseOrParams.run, evaluatorResponseOrParams.sourceInfo, evaluatorResponseOrParams.projectId);
+            return results;
+        }
+        const [results] = await this._logEvaluationFeedback(evaluatorResponseOrParams, run, sourceInfo, sessionId);
         return results;
     }
     /**

package/dist/evaluation/_runner.cjs

@@ -342,6 +342,8 @@ class _ExperimentManager {
             experiment: project,
             metadata: this._metadata,
             client: this.client,
+            runs: this._runs,
+            _runsArray: this._runsArray,
             evaluationResults: this._evaluationResults,
             summaryResults: this._summaryResults,
             numRepetitions: this._numRepetitions,
@@ -542,7 +544,11 @@ class _ExperimentManager {
                     tracingEnabled: true,
                 };
                 const evaluatorResponse = await evaluator.evaluateRun(run, example, options);
-                evaluationResults.results.push(...(await fields.client.logEvaluationFeedback(evaluatorResponse, run)));
+                evaluationResults.results.push(...(await fields.client.logEvaluationFeedback({
+                    evaluatorResponse,
+                    run,
+                    projectId: this._getExperiment().id,
+                })));
             }
             catch (e) {
                 console.error(`Error running evaluator ${evaluator.evaluateRun.name} on run ${run.id}: ${e}`);
@@ -1049,7 +1055,12 @@ async function _resolveExperiment(experiment, runs, client) {
         const firstRun = await runsCloneIterator
             .next()
             .then((result) => result.value);
-        const retrievedExperiment = await client.readProject(firstRun.sessionId);
+        if (firstRun?.session_id == null) {
+            throw new Error("Experiment ID not found for provided runs.");
+        }
+        const retrievedExperiment = await client.readProject({
+            projectId: firstRun.session_id,
+        });
         if (!retrievedExperiment.name) {
             throw new Error("Experiment name not found for provided runs.");
         }

package/dist/evaluation/_runner.js

@@ -334,6 +334,8 @@ export class _ExperimentManager {
             experiment: project,
             metadata: this._metadata,
             client: this.client,
+            runs: this._runs,
+            _runsArray: this._runsArray,
             evaluationResults: this._evaluationResults,
             summaryResults: this._summaryResults,
             numRepetitions: this._numRepetitions,
@@ -534,7 +536,11 @@ export class _ExperimentManager {
                     tracingEnabled: true,
                 };
                 const evaluatorResponse = await evaluator.evaluateRun(run, example, options);
-                evaluationResults.results.push(...(await fields.client.logEvaluationFeedback(evaluatorResponse, run)));
+                evaluationResults.results.push(...(await fields.client.logEvaluationFeedback({
+                    evaluatorResponse,
+                    run,
+                    projectId: this._getExperiment().id,
+                })));
             }
             catch (e) {
                 console.error(`Error running evaluator ${evaluator.evaluateRun.name} on run ${run.id}: ${e}`);
@@ -1040,7 +1046,12 @@ async function _resolveExperiment(experiment, runs, client) {
         const firstRun = await runsCloneIterator
             .next()
             .then((result) => result.value);
-        const retrievedExperiment = await client.readProject(firstRun.sessionId);
+        if (firstRun?.session_id == null) {
+            throw new Error("Experiment ID not found for provided runs.");
+        }
+        const retrievedExperiment = await client.readProject({
+            projectId: firstRun.session_id,
+        });
         if (!retrievedExperiment.name) {
             throw new Error("Experiment name not found for provided runs.");
         }

package/dist/evaluation/evaluate_comparative.cjs

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadTracesForExperiment = loadTracesForExperiment;
 exports.evaluateComparative = evaluateComparative;
 const index_js_1 = require("../utils/uuid/src/index.cjs");
 const index_js_2 = require("../index.cjs");
@@ -10,6 +11,7 @@ const shuffle_js_1 = require("../utils/shuffle.cjs");
 const async_caller_js_1 = require("../utils/async_caller.cjs");
 const index_js_3 = __importDefault(require("../utils/p-retry/index.cjs"));
 const traceable_js_1 = require("../traceable.cjs");
+const v2_migration_js_1 = require("../utils/v2_migration.cjs");
 function isExperimentResultsList(value) {
     return value.some((x) => typeof x !== "string");
 }
@@ -17,11 +19,15 @@ async function loadExperiment(client, experiment) {
     const value = typeof experiment === "string" ? experiment : experiment.experimentName;
     return client.readProject((0, index_js_1.validate)(value) ? { projectId: value } : { projectName: value });
 }
-async function loadTraces(client, experiment, options) {
-    const executionOrder = options.loadNested ? undefined : 1;
-    const runs = await client.listRuns((0, index_js_1.validate)(experiment)
-        ? { projectId: experiment, executionOrder }
-        : { projectName: experiment, executionOrder });
+async function loadTracesForExperiment(client, project, options) {
+    // v1 `/runs/query` returns 501 on SmithDB-only backends; use v2 when it's available.
+    const isRoot = options.loadNested ? undefined : true;
+    const runs = (await client._supportsSDBQuery())
+        ? await (0, v2_migration_js_1.loadTracesV2)(client, project, { isRoot })
+        : await client.listRuns({
+            projectId: project.id,
+            executionOrder: options.loadNested ? undefined : 1,
+        });
     const treeMap = {};
     const runIdMap = {};
     const results = [];
@@ -121,7 +127,9 @@ async function evaluateComparative(experiments, options) {
     if (viewUrl != null) {
         console.log(`View results at: ${viewUrl}`);
     }
-    const experimentRuns = await Promise.all(projects.map((p) => loadTraces(client, p.id, { loadNested: !!options.loadNested })));
+    const experimentRuns = await Promise.all(projects.map((project) => loadTracesForExperiment(client, project, {
+        loadNested: !!options.loadNested,
+    })));
     let exampleIdsIntersect;
     for (const runs of experimentRuns) {
         const exampleIdsSet = new Set(runs

package/dist/evaluation/evaluate_comparative.d.ts

@@ -1,7 +1,10 @@
 import { Client } from "../index.js";
-import { ComparativeExperiment, ComparisonEvaluationResult as ComparisonEvaluationResultRow, Example, Run } from "../schemas.js";
+import { ComparativeExperiment, ComparisonEvaluationResult as ComparisonEvaluationResultRow, Example, Run, TracerSession } from "../schemas.js";
 import { evaluate } from "./index.js";
 type ExperimentResults = Awaited<ReturnType<typeof evaluate>>;
+export declare function loadTracesForExperiment(client: Client, project: TracerSession, options: {
+    loadNested: boolean;
+}): Promise<Run[]>;
 /** @deprecated Use ComparativeEvaluatorNew instead: (args: { runs, example, inputs, outputs, referenceOutputs }) => ... */
 export type _ComparativeEvaluatorLegacy = (runs: Run[], example: Example) => ComparisonEvaluationResultRow | Promise<ComparisonEvaluationResultRow>;
 export type _ComparativeEvaluator = (args: {

package/dist/evaluation/evaluate_comparative.js

@@ -4,6 +4,7 @@ import { shuffle } from "../utils/shuffle.js";
 import { AsyncCaller } from "../utils/async_caller.js";
 import pRetry from "../utils/p-retry/index.js";
 import { getCurrentRunTree, traceable } from "../traceable.js";
+import { loadTracesV2 } from "../utils/v2_migration.js";
 function isExperimentResultsList(value) {
     return value.some((x) => typeof x !== "string");
 }
@@ -11,11 +12,15 @@ async function loadExperiment(client, experiment) {
     const value = typeof experiment === "string" ? experiment : experiment.experimentName;
     return client.readProject(validate(value) ? { projectId: value } : { projectName: value });
 }
-async function loadTraces(client, experiment, options) {
-    const executionOrder = options.loadNested ? undefined : 1;
-    const runs = await client.listRuns(validate(experiment)
-        ? { projectId: experiment, executionOrder }
-        : { projectName: experiment, executionOrder });
+export async function loadTracesForExperiment(client, project, options) {
+    // v1 `/runs/query` returns 501 on SmithDB-only backends; use v2 when it's available.
+    const isRoot = options.loadNested ? undefined : true;
+    const runs = (await client._supportsSDBQuery())
+        ? await loadTracesV2(client, project, { isRoot })
+        : await client.listRuns({
+            projectId: project.id,
+            executionOrder: options.loadNested ? undefined : 1,
+        });
     const treeMap = {};
     const runIdMap = {};
     const results = [];
@@ -115,7 +120,9 @@ export async function evaluateComparative(experiments, options) {
     if (viewUrl != null) {
         console.log(`View results at: ${viewUrl}`);
     }
-    const experimentRuns = await Promise.all(projects.map((p) => loadTraces(client, p.id, { loadNested: !!options.loadNested })));
+    const experimentRuns = await Promise.all(projects.map((project) => loadTracesForExperiment(client, project, {
+        loadNested: !!options.loadNested,
+    })));
     let exampleIdsIntersect;
     for (const runs of experimentRuns) {
         const exampleIdsSet = new Set(runs

package/dist/index.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LS_MESSAGE_VIEW_EXCLUDE = exports.__version__ = exports.InternalServerError = exports.RateLimitError = exports.UnprocessableEntityError = exports.ConflictError = exports.NotFoundError = exports.PermissionDeniedError = exports.AuthenticationError = exports.BadRequestError = exports.APIConnectionTimeoutError = exports.APIConnectionError = exports.APIUserAbortError = exports.APIError = exports.LangsmithError = exports.promptCacheSingleton = exports.configureGlobalPromptCache = exports.PromptCache = exports.Cache = exports.isTracingEnabled = exports.uuid7FromTime = exports.uuid7 = exports.getDefaultProjectName = exports.overrideFetchImplementation = exports.RunTree = exports.Client = void 0;
+exports.LS_MESSAGE_VIEW_EXCLUDE = exports.__version__ = exports.InternalServerError = exports.RateLimitError = exports.UnprocessableEntityError = exports.ConflictError = exports.NotFoundError = exports.PermissionDeniedError = exports.AuthenticationError = exports.BadRequestError = exports.APIConnectionTimeoutError = exports.APIConnectionError = exports.APIUserAbortError = exports.APIError = exports.LangsmithError = exports.promptCacheSingleton = exports.configureGlobalPromptCache = exports.PromptCache = exports.Cache = exports.isTracingEnabled = exports.uuid7FromTime = exports.uuid7 = exports.computeRunIdForSecondaryReplica = exports.getDefaultProjectName = exports.overrideFetchImplementation = exports.RunTree = exports.Client = void 0;
 var client_js_1 = require("./client.cjs");
 Object.defineProperty(exports, "Client", { enumerable: true, get: function () { return client_js_1.Client; } });
 var run_trees_js_1 = require("./run_trees.cjs");
@@ -10,6 +10,7 @@ Object.defineProperty(exports, "overrideFetchImplementation", { enumerable: true
 var project_js_1 = require("./utils/project.cjs");
 Object.defineProperty(exports, "getDefaultProjectName", { enumerable: true, get: function () { return project_js_1.getDefaultProjectName; } });
 var uuid_js_1 = require("./uuid.cjs");
+Object.defineProperty(exports, "computeRunIdForSecondaryReplica", { enumerable: true, get: function () { return uuid_js_1.computeRunIdForSecondaryReplica; } });
 Object.defineProperty(exports, "uuid7", { enumerable: true, get: function () { return uuid_js_1.uuid7; } });
 Object.defineProperty(exports, "uuid7FromTime", { enumerable: true, get: function () { return uuid_js_1.uuid7FromTime; } });
 var guard_js_1 = require("./utils/guard.cjs");
@@ -34,6 +35,6 @@ Object.defineProperty(exports, "UnprocessableEntityError", { enumerable: true, g
 Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return error_js_1.RateLimitError; } });
 Object.defineProperty(exports, "InternalServerError", { enumerable: true, get: function () { return error_js_1.InternalServerError; } });
 // Update using pnpm bump-version
-exports.__version__ = "0.8.4";
+exports.__version__ = "0.8.5";
 // Metadata key to hide a traced run from LangSmith's Messages View.
 exports.LS_MESSAGE_VIEW_EXCLUDE = "ls_message_view_exclude";

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 export { Client, type ClientConfig, type LangSmithTracingClientInterface, } from "./client.js";
 export type { Dataset, Example, TracerSession, Run, Feedback, FeedbackConfigSchema, RetrieverOutput, } from "./schemas.js";
-export { RunTree, type RunTreeConfig } from "./run_trees.js";
+export { RunTree, type RunTreeConfig, type WriteReplica } from "./run_trees.js";
 export { overrideFetchImplementation } from "./singletons/fetch.js";
 export { getDefaultProjectName } from "./utils/project.js";
-export { uuid7, uuid7FromTime } from "./uuid.js";
+export { computeRunIdForSecondaryReplica, uuid7, uuid7FromTime, } from "./uuid.js";
 export { isTracingEnabled } from "./utils/guard.js";
 export { Cache, PromptCache, type CacheConfig, type CacheMetrics, configureGlobalPromptCache, promptCacheSingleton, } from "./utils/prompt_cache/index.js";
 export { LangsmithError, APIError, APIUserAbortError, APIConnectionError, APIConnectionTimeoutError, BadRequestError, AuthenticationError, PermissionDeniedError, NotFoundError, ConflictError, UnprocessableEntityError, RateLimitError, InternalServerError, } from "./_openapi_client/core/error.js";
-export declare const __version__ = "0.8.4";
+export declare const __version__ = "0.8.5";
 export declare const LS_MESSAGE_VIEW_EXCLUDE: "ls_message_view_exclude";

package/dist/index.js

@@ -2,11 +2,11 @@ export { Client, } from "./client.js";
 export { RunTree } from "./run_trees.js";
 export { overrideFetchImplementation } from "./singletons/fetch.js";
 export { getDefaultProjectName } from "./utils/project.js";
-export { uuid7, uuid7FromTime } from "./uuid.js";
+export { computeRunIdForSecondaryReplica, uuid7, uuid7FromTime, } from "./uuid.js";
 export { isTracingEnabled } from "./utils/guard.js";
 export { Cache, PromptCache, configureGlobalPromptCache, promptCacheSingleton, } from "./utils/prompt_cache/index.js";
 export { LangsmithError, APIError, APIUserAbortError, APIConnectionError, APIConnectionTimeoutError, BadRequestError, AuthenticationError, PermissionDeniedError, NotFoundError, ConflictError, UnprocessableEntityError, RateLimitError, InternalServerError, } from "./_openapi_client/core/error.js";
 // Update using pnpm bump-version
-export const __version__ = "0.8.4";
+export const __version__ = "0.8.5";
 // Metadata key to hide a traced run from LangSmith's Messages View.
 export const LS_MESSAGE_VIEW_EXCLUDE = "ls_message_view_exclude";

package/dist/run_trees.cjs

@@ -46,12 +46,16 @@ function convertToDottedOrderFormat(epoch, runId, executionOrder = 1) {
 }
 const HEADER_SAFE_REPLICA_FIELDS = new Set([
     "projectName",
+    "primary",
     "updates",
     "reroot",
 ]);
 function filterReplicaForHeaders(replica) {
     const filtered = {};
     for (const key of Object.keys(replica)) {
+        if (key === "primary" && typeof replica[key] !== "boolean") {
+            continue;
+        }
         if (HEADER_SAFE_REPLICA_FIELDS.has(key)) {
             filtered[key] = replica[key];
         }
@@ -567,10 +571,10 @@ class RunTree {
         }
     }
     _remapForProject(params) {
-        const { projectName, runtimeEnv, excludeChildRuns = true, reroot = false, distributedParentId, apiUrl, apiKey, workspaceId, } = params;
+        const { projectName, primary, runtimeEnv, excludeChildRuns = true, reroot = false, distributedParentId, apiUrl, apiKey, workspaceId, } = params;
         const baseRun = this._convertToCreate(this, runtimeEnv, excludeChildRuns);
-        // Skip remapping if project name is the same
-        if (projectName === this.project_name) {
+        // Preserve legacy behavior when `primary` is omitted.
+        if (primary === undefined && projectName === this.project_name) {
             return {
                 ...baseRun,
                 session_name: projectName,
@@ -643,6 +647,12 @@ class RunTree {
                 }
             }
         }
+        if (primary) {
+            return {
+                ...baseRun,
+                session_name: projectName,
+            };
+        }
         // Remap IDs for the replica using nonCryptographicUuid7Deterministic
         // This ensures consistency across runs in the same replica while
         // preserving UUID7 properties (time-ordering, monotonicity)
@@ -691,9 +701,10 @@ class RunTree {
         try {
             const runtimeEnv = (0, env_js_2.getRuntimeEnvironment)();
             if (this.replicas && this.replicas.length > 0) {
-                for (const { projectName, apiKey, apiUrl, workspaceId, reroot, client: replicaClient, } of this.replicas) {
+                for (const { projectName, primary, apiKey, apiUrl, workspaceId, reroot, client: replicaClient, } of this.replicas) {
                     const runCreate = this._remapForProject({
                         projectName: projectName ?? this.project_name,
+                        primary,
                         runtimeEnv,
                         excludeChildRuns: true,
                         reroot,
@@ -728,9 +739,10 @@ class RunTree {
     }
     async patchRun(options) {
         if (this.replicas && this.replicas.length > 0) {
-            for (const { projectName, apiKey, apiUrl, workspaceId, updates, reroot, client: replicaClient, } of this.replicas) {
+            for (const { projectName, primary, apiKey, apiUrl, workspaceId, updates, reroot, client: replicaClient, } of this.replicas) {
                 const runData = this._remapForProject({
                     projectName: projectName ?? this.project_name,
+                    primary,
                     runtimeEnv: undefined,
                     excludeChildRuns: true,
                     reroot,
@@ -996,10 +1008,16 @@ function _getWriteReplicasFromEnv() {
                         `expected string, got ${typeof item.project_name}`);
                     continue;
                 }
+                if (item.primary !== undefined && typeof item.primary !== "boolean") {
+                    console.warn(`Invalid primary type in LANGSMITH_RUNS_ENDPOINTS: ` +
+                        `expected boolean, got ${typeof item.primary}`);
+                    continue;
+                }
                 replicas.push({
                     apiUrl: item.api_url.replace(/\/$/, ""),
                     apiKey: item.api_key,
                     projectName: item.project_name ?? undefined,
+                    primary: item.primary ?? undefined,
                 });
             }
             return replicas;
@@ -1039,9 +1057,8 @@ function _getWriteReplicasFromEnv() {
     }
 }
 function _ensureWriteReplicas(replicas) {
-    // If null -> fetch from env
-    if (replicas) {
-        return replicas.map((replica) => {
+    const ensured = replicas
+        ? replicas.map((replica) => {
             if (Array.isArray(replica)) {
                 return {
                     projectName: replica[0],
@@ -1049,9 +1066,12 @@ function _ensureWriteReplicas(replicas) {
                 };
             }
             return replica;
-        });
+        })
+        : _getWriteReplicasFromEnv();
+    if (ensured.filter((replica) => replica.primary === true).length > 1) {
+        throw new Error("Only one replica can be marked as primary.");
     }
-    return _getWriteReplicasFromEnv();
+    return ensured;
 }
 function _checkEndpointEnvUnset(parsed) {
     if (Object.keys(parsed).length > 0 &&

package/dist/run_trees.d.ts

@@ -55,11 +55,13 @@ interface HeadersLike {
     set(name: string, value: string): void;
 }
 type ProjectReplica = [string, KVMap | undefined];
-type WriteReplica = {
+export type WriteReplica = {
     apiUrl?: string;
     apiKey?: string;
     workspaceId?: string;
     projectName?: string;
+    /** Whether this replica keeps the original run IDs. */
+    primary?: boolean;
     updates?: KVMap | undefined;
     fromEnv?: boolean;
     reroot?: boolean;

package/dist/run_trees.js

@@ -40,12 +40,16 @@ export function convertToDottedOrderFormat(epoch, runId, executionOrder = 1) {
 }
 const HEADER_SAFE_REPLICA_FIELDS = new Set([
     "projectName",
+    "primary",
     "updates",
     "reroot",
 ]);
 function filterReplicaForHeaders(replica) {
     const filtered = {};
     for (const key of Object.keys(replica)) {
+        if (key === "primary" && typeof replica[key] !== "boolean") {
+            continue;
+        }
         if (HEADER_SAFE_REPLICA_FIELDS.has(key)) {
             filtered[key] = replica[key];
         }
@@ -561,10 +565,10 @@ export class RunTree {
         }
     }
     _remapForProject(params) {
-        const { projectName, runtimeEnv, excludeChildRuns = true, reroot = false, distributedParentId, apiUrl, apiKey, workspaceId, } = params;
+        const { projectName, primary, runtimeEnv, excludeChildRuns = true, reroot = false, distributedParentId, apiUrl, apiKey, workspaceId, } = params;
         const baseRun = this._convertToCreate(this, runtimeEnv, excludeChildRuns);
-        // Skip remapping if project name is the same
-        if (projectName === this.project_name) {
+        // Preserve legacy behavior when `primary` is omitted.
+        if (primary === undefined && projectName === this.project_name) {
             return {
                 ...baseRun,
                 session_name: projectName,
@@ -637,6 +641,12 @@ export class RunTree {
                 }
             }
         }
+        if (primary) {
+            return {
+                ...baseRun,
+                session_name: projectName,
+            };
+        }
         // Remap IDs for the replica using nonCryptographicUuid7Deterministic
         // This ensures consistency across runs in the same replica while
         // preserving UUID7 properties (time-ordering, monotonicity)
@@ -685,9 +695,10 @@ export class RunTree {
         try {
             const runtimeEnv = getRuntimeEnvironment();
             if (this.replicas && this.replicas.length > 0) {
-                for (const { projectName, apiKey, apiUrl, workspaceId, reroot, client: replicaClient, } of this.replicas) {
+                for (const { projectName, primary, apiKey, apiUrl, workspaceId, reroot, client: replicaClient, } of this.replicas) {
                     const runCreate = this._remapForProject({
                         projectName: projectName ?? this.project_name,
+                        primary,
                         runtimeEnv,
                         excludeChildRuns: true,
                         reroot,
@@ -722,9 +733,10 @@ export class RunTree {
     }
     async patchRun(options) {
         if (this.replicas && this.replicas.length > 0) {
-            for (const { projectName, apiKey, apiUrl, workspaceId, updates, reroot, client: replicaClient, } of this.replicas) {
+            for (const { projectName, primary, apiKey, apiUrl, workspaceId, updates, reroot, client: replicaClient, } of this.replicas) {
                 const runData = this._remapForProject({
                     projectName: projectName ?? this.project_name,
+                    primary,
                     runtimeEnv: undefined,
                     excludeChildRuns: true,
                     reroot,
@@ -989,10 +1001,16 @@ function _getWriteReplicasFromEnv() {
                         `expected string, got ${typeof item.project_name}`);
                     continue;
                 }
+                if (item.primary !== undefined && typeof item.primary !== "boolean") {
+                    console.warn(`Invalid primary type in LANGSMITH_RUNS_ENDPOINTS: ` +
+                        `expected boolean, got ${typeof item.primary}`);
+                    continue;
+                }
                 replicas.push({
                     apiUrl: item.api_url.replace(/\/$/, ""),
                     apiKey: item.api_key,
                     projectName: item.project_name ?? undefined,
+                    primary: item.primary ?? undefined,
                 });
             }
             return replicas;
@@ -1032,9 +1050,8 @@ function _getWriteReplicasFromEnv() {
     }
 }
 function _ensureWriteReplicas(replicas) {
-    // If null -> fetch from env
-    if (replicas) {
-        return replicas.map((replica) => {
+    const ensured = replicas
+        ? replicas.map((replica) => {
             if (Array.isArray(replica)) {
                 return {
                     projectName: replica[0],
@@ -1042,9 +1059,12 @@ function _ensureWriteReplicas(replicas) {
                 };
             }
             return replica;
-        });
+        })
+        : _getWriteReplicasFromEnv();
+    if (ensured.filter((replica) => replica.primary === true).length > 1) {
+        throw new Error("Only one replica can be marked as primary.");
     }
-    return _getWriteReplicasFromEnv();
+    return ensured;
 }
 function _checkEndpointEnvUnset(parsed) {
     if (Object.keys(parsed).length > 0 &&

package/dist/utils/jestlike/globals.cjs

@@ -30,10 +30,18 @@ function _logTestFeedback(params) {
             throw new Error("Could not log feedback to LangSmith: missing run information. Please contact us for help.");
         }
         exports.evaluatorLogFeedbackPromises.add((async () => {
+            if (context.project == null) {
+                throw new Error("Could not log feedback to LangSmith: missing project information. Please contact us for help.");
+            }
             await exports.syncExamplePromises.get(exampleId);
-            await client?.logEvaluationFeedback(feedback, runTree, sourceRunId !== undefined
-                ? { __run: { run_id: sourceRunId } }
-                : undefined);
+            await client?.logEvaluationFeedback({
+                evaluatorResponse: feedback,
+                run: runTree,
+                projectId: context.project.id,
+                sourceInfo: sourceRunId !== undefined
+                    ? { __run: { run_id: sourceRunId } }
+                    : undefined,
+            });
         })());
     }
     context.onFeedbackLogged?.(feedback);

package/dist/utils/jestlike/globals.js

@@ -25,10 +25,18 @@ export function _logTestFeedback(params) {
             throw new Error("Could not log feedback to LangSmith: missing run information. Please contact us for help.");
         }
         evaluatorLogFeedbackPromises.add((async () => {
+            if (context.project == null) {
+                throw new Error("Could not log feedback to LangSmith: missing project information. Please contact us for help.");
+            }
             await syncExamplePromises.get(exampleId);
-            await client?.logEvaluationFeedback(feedback, runTree, sourceRunId !== undefined
-                ? { __run: { run_id: sourceRunId } }
-                : undefined);
+            await client?.logEvaluationFeedback({
+                evaluatorResponse: feedback,
+                run: runTree,
+                projectId: context.project.id,
+                sourceInfo: sourceRunId !== undefined
+                    ? { __run: { run_id: sourceRunId } }
+                    : undefined,
+            });
         })());
     }
     context.onFeedbackLogged?.(feedback);

package/dist/utils/jestlike/index.cjs

@@ -573,6 +573,9 @@ function generateWrapperFromJestlikeMethods(methods, testRunnerName) {
                             const tracedFunction = (0, traceable_js_1.traceable)(async () => {
                                 return globals_js_1.testWrapperAsyncLocalStorageInstance.run({
                                     ...context,
+                                    dataset,
+                                    project,
+                                    client,
                                     currentExample: {
                                         inputs,
                                         outputs: referenceOutputs,

package/dist/utils/jestlike/index.js

@@ -526,6 +526,9 @@ export function generateWrapperFromJestlikeMethods(methods, testRunnerName) {
                             const tracedFunction = traceable(async () => {
                                 return testWrapperAsyncLocalStorageInstance.run({
                                     ...context,
+                                    dataset,
+                                    project,
+                                    client,
                                     currentExample: {
                                         inputs,
                                         outputs: referenceOutputs,

package/dist/utils/v2_migration.cjs

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.v2RunToRun = v2RunToRun;
+exports.loadTracesV2 = loadTracesV2;
+// Omitting selects from `/v2/runs/query` returns only the run ID.
+const V2_RUN_SELECTS = [
+    "ID",
+    "NAME",
+    "RUN_TYPE",
+    "STATUS",
+    "START_TIME",
+    "END_TIME",
+    "INPUTS",
+    "OUTPUTS",
+    "PARENT_RUN_IDS",
+    "PROJECT_ID",
+    "TRACE_ID",
+    "DOTTED_ORDER",
+    "REFERENCE_EXAMPLE_ID",
+    "ERROR",
+];
+function v2RunToRun(run) {
+    if (run.id == null || run.name == null || run.run_type == null) {
+        throw new Error("V2 run response is missing required fields.");
+    }
+    return {
+        id: run.id,
+        name: run.name,
+        run_type: run.run_type.toLowerCase(),
+        start_time: run.start_time,
+        end_time: run.end_time,
+        trace_id: run.trace_id,
+        session_id: run.project_id,
+        parent_run_id: run.parent_run_ids?.at(-1),
+        dotted_order: run.dotted_order,
+        reference_example_id: run.reference_example_id,
+        inputs: run.inputs ?? {},
+        outputs: run.outputs,
+        error: run.error ?? undefined,
+        status: run.status?.toLowerCase(),
+    };
+}
+async function loadTracesV2(client, project, options) {
+    const runs = [];
+    const pager = client.runs.queryV2({
+        project_ids: [project.id],
+        min_start_time: new Date(project.start_time).toISOString(),
+        max_start_time: new Date(project.end_time ?? Date.now()).toISOString(),
+        is_root: options.isRoot,
+        selects: V2_RUN_SELECTS,
+    });
+    for await (const run of pager) {
+        runs.push(v2RunToRun(run));
+    }
+    return runs;
+}

package/dist/utils/v2_migration.d.ts

@@ -0,0 +1,7 @@
+import type { Run as V2Run } from "../_openapi_client/resources/runs/runs.js";
+import type { Client } from "../client.js";
+import type { Run, TracerSession } from "../schemas.js";
+export declare function v2RunToRun(run: V2Run): Run;
+export declare function loadTracesV2(client: Client, project: TracerSession, options: {
+    isRoot?: boolean;
+}): Promise<Run[]>;

package/dist/utils/v2_migration.js

@@ -0,0 +1,52 @@
+// Omitting selects from `/v2/runs/query` returns only the run ID.
+const V2_RUN_SELECTS = [
+    "ID",
+    "NAME",
+    "RUN_TYPE",
+    "STATUS",
+    "START_TIME",
+    "END_TIME",
+    "INPUTS",
+    "OUTPUTS",
+    "PARENT_RUN_IDS",
+    "PROJECT_ID",
+    "TRACE_ID",
+    "DOTTED_ORDER",
+    "REFERENCE_EXAMPLE_ID",
+    "ERROR",
+];
+export function v2RunToRun(run) {
+    if (run.id == null || run.name == null || run.run_type == null) {
+        throw new Error("V2 run response is missing required fields.");
+    }
+    return {
+        id: run.id,
+        name: run.name,
+        run_type: run.run_type.toLowerCase(),
+        start_time: run.start_time,
+        end_time: run.end_time,
+        trace_id: run.trace_id,
+        session_id: run.project_id,
+        parent_run_id: run.parent_run_ids?.at(-1),
+        dotted_order: run.dotted_order,
+        reference_example_id: run.reference_example_id,
+        inputs: run.inputs ?? {},
+        outputs: run.outputs,
+        error: run.error ?? undefined,
+        status: run.status?.toLowerCase(),
+    };
+}
+export async function loadTracesV2(client, project, options) {
+    const runs = [];
+    const pager = client.runs.queryV2({
+        project_ids: [project.id],
+        min_start_time: new Date(project.start_time).toISOString(),
+        max_start_time: new Date(project.end_time ?? Date.now()).toISOString(),
+        is_root: options.isRoot,
+        selects: V2_RUN_SELECTS,
+    });
+    for await (const run of pager) {
+        runs.push(v2RunToRun(run));
+    }
+    return runs;
+}

package/dist/uuid.cjs

@@ -2,12 +2,32 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.uuid7FromTime = void 0;
 exports.uuid7 = uuid7;
+exports.computeRunIdForSecondaryReplica = computeRunIdForSecondaryReplica;
 const index_js_1 = require("./utils/uuid/src/index.cjs");
-var _uuid_js_1 = require("./utils/_uuid.cjs");
-Object.defineProperty(exports, "uuid7FromTime", { enumerable: true, get: function () { return _uuid_js_1.uuid7FromTime; } });
+const _uuid_js_1 = require("./utils/_uuid.cjs");
+var _uuid_js_2 = require("./utils/_uuid.cjs");
+Object.defineProperty(exports, "uuid7FromTime", { enumerable: true, get: function () { return _uuid_js_2.uuid7FromTime; } });
 /**
  * Generate a random UUID v7 string.
  */
 function uuid7() {
     return (0, index_js_1.v7)();
 }
+/**
+ * Compute the run ID used for a secondary tracing replica.
+ *
+ * @param runId - The original UUID v7 run ID.
+ * @param projectName - The secondary replica's destination project name.
+ * @returns The run ID used in the secondary replica destination.
+ */
+function computeRunIdForSecondaryReplica(runId, projectName) {
+    if (typeof projectName !== "string" || projectName.length === 0) {
+        throw new Error("projectName must be a non-empty string");
+    }
+    (0, _uuid_js_1.assertUuid)(runId, "runId");
+    const normalizedRunId = runId.toLowerCase();
+    if ((0, _uuid_js_1.getUuidVersion)(normalizedRunId) !== 7) {
+        throw new Error("runId must be a UUID v7");
+    }
+    return (0, _uuid_js_1.nonCryptographicUuid7Deterministic)(normalizedRunId, projectName);
+}

package/dist/uuid.d.ts

@@ -3,3 +3,11 @@ export { uuid7FromTime } from "./utils/_uuid.js";
  * Generate a random UUID v7 string.
  */
 export declare function uuid7(): string;
+/**
+ * Compute the run ID used for a secondary tracing replica.
+ *
+ * @param runId - The original UUID v7 run ID.
+ * @param projectName - The secondary replica's destination project name.
+ * @returns The run ID used in the secondary replica destination.
+ */
+export declare function computeRunIdForSecondaryReplica(runId: string, projectName: string): string;

package/dist/uuid.js

@@ -1,4 +1,5 @@
 import { v7 as uuidv7 } from "./utils/uuid/src/index.js";
+import { assertUuid, getUuidVersion, nonCryptographicUuid7Deterministic, } from "./utils/_uuid.js";
 export { uuid7FromTime } from "./utils/_uuid.js";
 /**
  * Generate a random UUID v7 string.
@@ -6,3 +7,21 @@ export { uuid7FromTime } from "./utils/_uuid.js";
 export function uuid7() {
     return uuidv7();
 }
+/**
+ * Compute the run ID used for a secondary tracing replica.
+ *
+ * @param runId - The original UUID v7 run ID.
+ * @param projectName - The secondary replica's destination project name.
+ * @returns The run ID used in the secondary replica destination.
+ */
+export function computeRunIdForSecondaryReplica(runId, projectName) {
+    if (typeof projectName !== "string" || projectName.length === 0) {
+        throw new Error("projectName must be a non-empty string");
+    }
+    assertUuid(runId, "runId");
+    const normalizedRunId = runId.toLowerCase();
+    if (getUuidVersion(normalizedRunId) !== 7) {
+        throw new Error("runId must be a UUID v7");
+    }
+    return nonCryptographicUuid7Deterministic(normalizedRunId, projectName);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "langsmith",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "description": "Client library to connect to the LangSmith Observability and Evaluation Platform.",
   "packageManager": "pnpm@10.33.0",
   "files": [