langsmith 0.8.3 → 0.8.5

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,
@@ -989,9 +1001,23 @@ function _getWriteReplicasFromEnv() {
                         `expected string, got ${typeof item.api_key}`);
                     continue;
                 }
+                if (item.project_name !== undefined &&
+                    item.project_name !== null &&
+                    typeof item.project_name !== "string") {
+                    console.warn(`Invalid project_name type in LANGSMITH_RUNS_ENDPOINTS: ` +
+                        `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;
@@ -1031,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],
@@ -1041,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,
@@ -982,9 +994,23 @@ function _getWriteReplicasFromEnv() {
                         `expected string, got ${typeof item.api_key}`);
                     continue;
                 }
+                if (item.project_name !== undefined &&
+                    item.project_name !== null &&
+                    typeof item.project_name !== "string") {
+                    console.warn(`Invalid project_name type in LANGSMITH_RUNS_ENDPOINTS: ` +
+                        `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;
@@ -1024,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],
@@ -1034,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/constants.cjs

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports._MIN_BACKEND_VERSION = void 0;
-exports._MIN_BACKEND_VERSION = "0.16.13rc1";
+exports._MIN_BACKEND_VERSION = "0.16.14rc1";

package/dist/utils/constants.d.ts

@@ -1 +1 @@
-export declare const _MIN_BACKEND_VERSION = "0.16.13rc1";
+export declare const _MIN_BACKEND_VERSION = "0.16.14rc1";

package/dist/utils/constants.js

@@ -1 +1 @@
-export const _MIN_BACKEND_VERSION = "0.16.13rc1";
+export const _MIN_BACKEND_VERSION = "0.16.14rc1";

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/dist/wrappers/openai.cjs

@@ -244,7 +244,13 @@ const getChatModelInvocationParamsFn = (provider, prepopulatedInvocationParams,
         if (useResponsesApi) {
             ls_invocation_params.use_responses_api = true;
         }
+        const requestMetadata = typeof params.metadata === "object" &&
+            params.metadata !== null &&
+            !Array.isArray(params.metadata)
+            ? params.metadata
+            : {};
         return {
+            ...requestMetadata,
             ls_provider: provider,
             ls_model_type: "chat",
             ls_model_name: params.model,

package/dist/wrappers/openai.js

@@ -241,7 +241,13 @@ const getChatModelInvocationParamsFn = (provider, prepopulatedInvocationParams,
         if (useResponsesApi) {
             ls_invocation_params.use_responses_api = true;
         }
+        const requestMetadata = typeof params.metadata === "object" &&
+            params.metadata !== null &&
+            !Array.isArray(params.metadata)
+            ? params.metadata
+            : {};
         return {
+            ...requestMetadata,
             ls_provider: provider,
             ls_model_type: "chat",
             ls_model_name: params.model,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "langsmith",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "description": "Client library to connect to the LangSmith Observability and Evaluation Platform.",
   "packageManager": "pnpm@10.33.0",
   "files": [
@@ -478,7 +478,11 @@
       "js-yaml": "^4.1.1",
       "vite": "^7.3.2",
       "form-data": "4.0.6",
-      "langsmith": "0.6.0"
+      "langsmith": "0.6.0",
+      "@babel/core": "^7.29.7",
+      "esbuild": "^0.28.1",
+      "markdown-it": "^14.3.0",
+      "uuid": "^11.1.1"
     }
   },
   "browser": {