langsmith 0.10.4 → 0.10.6

package/dist/address.cjs

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnvAddressError = void 0;
+exports.normalizeAddress = normalizeAddress;
+exports.wireKeys = wireKeys;
+exports.envNames = envNames;
+exports.toWire = toWire;
+exports.fromWire = fromWire;
+exports.addressFromEnv = addressFromEnv;
+exports.seed = seed;
+exports.sameAddress = sameAddress;
+// Wire key per field; env var is `LANGSMITH_<WIRE KEY>`.
+const FIELDS = {
+    agentId: "agent_id",
+    agentEnvironment: "agent_environment",
+};
+// The server's agent id rule: a DNS label, so a hostname can carry the id.
+const AGENT_ID_PATTERN = /^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$/;
+// Not `utils/env`: it imports the package index, which imports this module.
+function getEnv(name) {
+    try {
+        // eslint-disable-next-line no-process-env
+        return typeof process !== "undefined" ? process.env?.[name] : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The `LANGSMITH_AGENT_*` / project env vars name half an address, or both. */
+class EnvAddressError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "EnvAddressError";
+    }
+}
+exports.EnvAddressError = EnvAddressError;
+/**
+ * @internal Validate `value` and return a frozen copy of its fields.
+ * @throws If it isn't an object with exactly the address fields, or a value is invalid.
+ */
+function normalizeAddress(value) {
+    if (value == null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("`address` must be an object: { agentId, agentEnvironment }.");
+    }
+    const fields = value;
+    const unknown = Object.keys(fields).filter((key) => !(key in FIELDS));
+    if (unknown.length > 0) {
+        throw new Error(`Unknown address fields: ${unknown.join(", ")}.`);
+    }
+    for (const name of Object.keys(FIELDS)) {
+        const field = fields[name];
+        if (typeof field !== "string" || field === "") {
+            throw new Error(`Address ${name} must be a non-empty string.`);
+        }
+    }
+    const { agentId, agentEnvironment } = fields;
+    if (!AGENT_ID_PATTERN.test(agentId)) {
+        throw new Error("Address agentId must be 1 to 63 lowercase ASCII letters, digits, or " +
+            "hyphens, start with a letter, and end with a letter or digit, got " +
+            `${JSON.stringify(agentId)}. Use an id such as "support-agent".`);
+    }
+    return Object.freeze({ agentId, agentEnvironment });
+}
+/** @internal */
+function wireKeys() {
+    return Object.values(FIELDS);
+}
+/** @internal */
+function envNames() {
+    return wireKeys().map((key) => `LANGSMITH_${key.toUpperCase()}`);
+}
+/** @internal */
+function toWire(address) {
+    return {
+        [FIELDS.agentId]: address.agentId,
+        [FIELDS.agentEnvironment]: address.agentEnvironment,
+    };
+}
+/** @internal `undefined` if no field is set; throws if only some are. */
+function fromWire(values) {
+    const fields = Object.fromEntries(Object.entries(FIELDS).map(([name, key]) => [
+        name,
+        values[key] ?? undefined,
+    ]));
+    const missing = Object.entries(FIELDS)
+        .filter(([name]) => fields[name] === undefined)
+        .map(([, key]) => key);
+    if (missing.length === Object.keys(FIELDS).length) {
+        return undefined;
+    }
+    if (missing.length > 0) {
+        throw new Error(`An address needs ${missing.join(" and ")} as well.`);
+    }
+    return normalizeAddress(fields);
+}
+/**
+ * @internal
+ * @throws {EnvAddressError} If only some `LANGSMITH_AGENT_*` vars are set, or one is invalid.
+ */
+function addressFromEnv() {
+    const values = Object.fromEntries(wireKeys().map((key, i) => [key, getEnv(envNames()[i]) || undefined]));
+    try {
+        return fromWire(values);
+    }
+    catch (e) {
+        throw new EnvAddressError(`The LANGSMITH_AGENT_* env vars can't address a run: ${e.message}`);
+    }
+}
+/** @internal Replica id derivation seed. */
+function seed(address) {
+    return ["agent", ...Object.values(toWire(address))].join("/");
+}
+/** @internal */
+function sameAddress(a, b) {
+    if (!a || !b) {
+        return a === b;
+    }
+    return a.agentId === b.agentId && a.agentEnvironment === b.agentEnvironment;
+}

package/dist/address.d.ts

@@ -0,0 +1,13 @@
+/**
+ * (beta) An address that runs are sent to instead of a project.
+ * Enabled per workspace; a workspace without it rejects the runs.
+ */
+export interface Address {
+    /** 1 to 63 lowercase ASCII letters, digits or hyphens; starts with a letter. */
+    agentId: string;
+    agentEnvironment: string;
+}
+/** The `LANGSMITH_AGENT_*` / project env vars name half an address, or both. */
+export declare class EnvAddressError extends Error {
+    constructor(message: string);
+}

package/dist/address.js

@@ -0,0 +1,107 @@
+// Wire key per field; env var is `LANGSMITH_<WIRE KEY>`.
+const FIELDS = {
+    agentId: "agent_id",
+    agentEnvironment: "agent_environment",
+};
+// The server's agent id rule: a DNS label, so a hostname can carry the id.
+const AGENT_ID_PATTERN = /^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$/;
+// Not `utils/env`: it imports the package index, which imports this module.
+function getEnv(name) {
+    try {
+        // eslint-disable-next-line no-process-env
+        return typeof process !== "undefined" ? process.env?.[name] : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The `LANGSMITH_AGENT_*` / project env vars name half an address, or both. */
+export class EnvAddressError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "EnvAddressError";
+    }
+}
+/**
+ * @internal Validate `value` and return a frozen copy of its fields.
+ * @throws If it isn't an object with exactly the address fields, or a value is invalid.
+ */
+export function normalizeAddress(value) {
+    if (value == null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("`address` must be an object: { agentId, agentEnvironment }.");
+    }
+    const fields = value;
+    const unknown = Object.keys(fields).filter((key) => !(key in FIELDS));
+    if (unknown.length > 0) {
+        throw new Error(`Unknown address fields: ${unknown.join(", ")}.`);
+    }
+    for (const name of Object.keys(FIELDS)) {
+        const field = fields[name];
+        if (typeof field !== "string" || field === "") {
+            throw new Error(`Address ${name} must be a non-empty string.`);
+        }
+    }
+    const { agentId, agentEnvironment } = fields;
+    if (!AGENT_ID_PATTERN.test(agentId)) {
+        throw new Error("Address agentId must be 1 to 63 lowercase ASCII letters, digits, or " +
+            "hyphens, start with a letter, and end with a letter or digit, got " +
+            `${JSON.stringify(agentId)}. Use an id such as "support-agent".`);
+    }
+    return Object.freeze({ agentId, agentEnvironment });
+}
+/** @internal */
+export function wireKeys() {
+    return Object.values(FIELDS);
+}
+/** @internal */
+export function envNames() {
+    return wireKeys().map((key) => `LANGSMITH_${key.toUpperCase()}`);
+}
+/** @internal */
+export function toWire(address) {
+    return {
+        [FIELDS.agentId]: address.agentId,
+        [FIELDS.agentEnvironment]: address.agentEnvironment,
+    };
+}
+/** @internal `undefined` if no field is set; throws if only some are. */
+export function fromWire(values) {
+    const fields = Object.fromEntries(Object.entries(FIELDS).map(([name, key]) => [
+        name,
+        values[key] ?? undefined,
+    ]));
+    const missing = Object.entries(FIELDS)
+        .filter(([name]) => fields[name] === undefined)
+        .map(([, key]) => key);
+    if (missing.length === Object.keys(FIELDS).length) {
+        return undefined;
+    }
+    if (missing.length > 0) {
+        throw new Error(`An address needs ${missing.join(" and ")} as well.`);
+    }
+    return normalizeAddress(fields);
+}
+/**
+ * @internal
+ * @throws {EnvAddressError} If only some `LANGSMITH_AGENT_*` vars are set, or one is invalid.
+ */
+export function addressFromEnv() {
+    const values = Object.fromEntries(wireKeys().map((key, i) => [key, getEnv(envNames()[i]) || undefined]));
+    try {
+        return fromWire(values);
+    }
+    catch (e) {
+        throw new EnvAddressError(`The LANGSMITH_AGENT_* env vars can't address a run: ${e.message}`);
+    }
+}
+/** @internal Replica id derivation seed. */
+export function seed(address) {
+    return ["agent", ...Object.values(toWire(address))].join("/");
+}
+/** @internal */
+export function sameAddress(a, b) {
+    if (!a || !b) {
+        return a === b;
+    }
+    return a.agentId === b.agentId && a.agentEnvironment === b.agentEnvironment;
+}

package/dist/client.cjs

@@ -47,6 +47,8 @@ const index_js_2 = require("./_openapi_client/index.cjs");
 const _uuid_js_1 = require("./utils/_uuid.cjs");
 const sampling_js_1 = require("./utils/sampling.cjs");
 const warn_js_1 = require("./utils/warn.cjs");
+const address_js_1 = require("./address.cjs");
+const agent_addressing_js_1 = require("./utils/agent_addressing.cjs");
 const v2_migration_js_1 = require("./utils/v2_migration.cjs");
 const prompts_js_1 = require("./utils/prompts.cjs");
 const error_js_1 = require("./utils/error.cjs");
@@ -82,6 +84,26 @@ function _normalizeRunTimestamps(run) {
         end_time: _ensureUTCTimestamp(run.end_time),
     };
 }
+/** Index creates by id (last wins); warns when one id goes to two projects. */
+function indexRunCreatesById(creates) {
+    const byId = {};
+    for (const run of creates) {
+        if (!run.id) {
+            continue;
+        }
+        const previous = byId[run.id];
+        if (previous !== undefined && previous.session_name !== run.session_name) {
+            console.warn(`LangSmith run ${run.id} was queued for two projects with the same id ` +
+                `(${JSON.stringify(previous.session_name)} and ` +
+                `${JSON.stringify(run.session_name)}); only one of the projects will ` +
+                "keep the run. This usually means two write replicas both keep the " +
+                "original run ids, for example a replica marked `primary` plus one " +
+                "for the run's own project.");
+        }
+        byId[run.id] = run;
+    }
+    return byId;
+}
 function mergeRuntimeEnvIntoRun(run, cachedEnvVars, omitTracedRuntimeInfo, tracingSampleRate) {
     if (omitTracedRuntimeInfo) {
         return run;
@@ -866,6 +888,10 @@ class Client {
             throw new Error("Trace batch concurrency must be positive.");
         }
         this.debug = config.debug ?? this.debug;
+        if (this.debug) {
+            const source = config.apiUrl != null ? "apiUrl option" : defaultConfig.apiUrlSource;
+            console.log(`LangSmith API URL ${this.apiUrl} resolved from ${source}`);
+        }
         this.fetchImplementation = config.fetchImplementation;
         // Failed trace dump configuration
         this.failedTracesDir =
@@ -917,6 +943,7 @@ class Client {
         }
         // Cache metadata env vars once during construction to avoid repeatedly scanning process.env
         this.cachedLSEnvVarsForMetadata = (0, env_js_1.getLangSmithEnvVarsMetadata)();
+        (0, agent_addressing_js_1.warnOnEnv)();
         // Initialize prompt cache
         // Handle backwards compatibility for deprecated `cache` parameter
         if (config.cache !== undefined && config.disablePromptCache) {
@@ -952,12 +979,18 @@ class Client {
         const envWorkspaceId = (0, env_js_1.getLangSmithEnvironmentVariable)("WORKSPACE_ID");
         const envAuthSet = (0, profiles_js_1.hasValue)(envApiKey);
         const apiUrl = envApiUrl ?? profileConfig.apiUrl ?? profiles_js_1.DEFAULT_API_URL;
+        const apiUrlSource = envApiUrl != null
+            ? "LANGSMITH_ENDPOINT / LANGCHAIN_ENDPOINT environment variable"
+            : profileConfig.apiUrl != null
+                ? "profile config"
+                : "built-in default";
         const workspaceId = envWorkspaceId ?? profileConfig.workspaceId;
         const hideInputs = (0, env_js_1.getLangSmithEnvironmentVariable)("HIDE_INPUTS") === "true";
         const hideOutputs = (0, env_js_1.getLangSmithEnvironmentVariable)("HIDE_OUTPUTS") === "true";
         const hideMetadata = (0, env_js_1.getLangSmithEnvironmentVariable)("HIDE_METADATA") === "true";
         return {
             apiUrl: apiUrl,
+            apiUrlSource,
             apiKey: envApiKey,
             webUrl: undefined,
             hideInputs: hideInputs,
@@ -1278,8 +1311,9 @@ class Client {
             return event;
         });
     }
-    async prepareRunCreateOrUpdateInputs(run) {
+    async prepareRunCreateOrUpdateInputs(run, options) {
         const runParams = { ...run };
+        (0, agent_addressing_js_1.applyToPayload)(runParams, { update: options?.update ?? false });
         if (runParams.inputs !== undefined) {
             runParams.inputs = await this.processInputs(runParams.inputs);
         }
@@ -1761,8 +1795,24 @@ class Client {
             ...this._mergedHeaders,
             "Content-Type": "application/json",
         };
+        const address = (0, agent_addressing_js_1.checkAddress)(run.address);
+        // `RunTree.postRun` passes a built run body, carrying the wire `session_name`.
+        const bodySessionName = run.session_name;
+        (0, agent_addressing_js_1.rejectConflicting)(run.project_name ?? bodySessionName, address);
         const session_name = run.project_name;
         delete run.project_name;
+        if (!session_name && bodySessionName == null && !address) {
+            try {
+                run.address = (0, agent_addressing_js_1.resolveFromEnv)()[1];
+            }
+            catch (e) {
+                if (!(e instanceof address_js_1.EnvAddressError)) {
+                    throw e;
+                }
+                (0, agent_addressing_js_1.logUntraced)(e);
+                return;
+            }
+        }
         const runCreate = await this.prepareRunCreateOrUpdateInputs({
             session_name,
             ...run,
@@ -1811,15 +1861,10 @@ class Client {
             return;
         }
         let preparedCreateParams = await Promise.all(runCreates?.map((create) => this.prepareRunCreateOrUpdateInputs(create)) ?? []);
-        let preparedUpdateParams = await Promise.all(runUpdates?.map((update) => this.prepareRunCreateOrUpdateInputs(update)) ?? []);
+        let preparedUpdateParams = await Promise.all(runUpdates?.map((update) => this.prepareRunCreateOrUpdateInputs(update, { update: true })) ?? []);
+        // Index even without updates: the collision warning must see creates-only batches.
+        const createById = indexRunCreatesById(preparedCreateParams);
         if (preparedCreateParams.length > 0 && preparedUpdateParams.length > 0) {
-            const createById = preparedCreateParams.reduce((params, run) => {
-                if (!run.id) {
-                    return params;
-                }
-                params[run.id] = run;
-                return params;
-            }, {});
             const standaloneUpdates = [];
             for (const updateParam of preparedUpdateParams) {
                 if (updateParam.id !== undefined && createById[updateParam.id]) {
@@ -1910,7 +1955,7 @@ class Client {
         }
         let preparedUpdateParams = [];
         for (const update of runUpdates ?? []) {
-            preparedUpdateParams.push(await this.prepareRunCreateOrUpdateInputs(update));
+            preparedUpdateParams.push(await this.prepareRunCreateOrUpdateInputs(update, { update: true }));
         }
         // require trace_id and dotted_order
         const invalidRunCreate = preparedCreateParams.find((runCreate) => {
@@ -1926,14 +1971,8 @@ class Client {
             throw new Error(`Multipart ingest requires "trace_id" and "dotted_order" to be set when updating a run`);
         }
         // combine post and patch dicts where possible
+        const createById = indexRunCreatesById(preparedCreateParams);
         if (preparedCreateParams.length > 0 && preparedUpdateParams.length > 0) {
-            const createById = preparedCreateParams.reduce((params, run) => {
-                if (!run.id) {
-                    return params;
-                }
-                params[run.id] = run;
-                return params;
-            }, {});
             const standaloneUpdates = [];
             for (const updateParam of preparedUpdateParams) {
                 if (updateParam.id !== undefined && createById[updateParam.id]) {
@@ -2183,6 +2222,8 @@ class Client {
         if (run.events) {
             run.events = this._filterNewTokenEvents(run.events);
         }
+        // On `run` too: the direct path below serializes it.
+        (0, agent_addressing_js_1.applyToPayload)(run, { update: true });
         // TODO: Untangle types
         const data = { ...run, id: runId };
         if (!this._filterForSampling([data]).length) {
@@ -2274,6 +2315,9 @@ class Client {
             "Use client.runs.getURL() instead. " +
             "See https://docs.langchain.com/langsmith/smithdb-sdk-migration-runs#runs-get-url for the migration guide.", { type: "DeprecationWarning", code: "LANGSMITH_DEPRECATED_GET_RUN_URL" });
         if (run !== undefined) {
+            if (!run.session_id && run.address) {
+                throw new Error("Addressed runs have no URL until read back.");
+            }
             let sessionId;
             if (run.session_id) {
                 sessionId = run.session_id;
@@ -3603,7 +3647,7 @@ class Client {
         if (attachment_urls) {
             example.attachments = Object.entries(attachment_urls).reduce((acc, [key, value]) => {
                 acc[key.slice("attachment.".length)] = {
-                    presigned_url: value.presigned_url,
+                    presigned_url: new URL(value.presigned_url, this.apiUrl).href,
                     mime_type: value.mime_type,
                 };
                 return acc;
@@ -3671,7 +3715,7 @@ class Client {
                 if (attachment_urls) {
                     example.attachments = Object.entries(attachment_urls).reduce((acc, [key, value]) => {
                         acc[key.slice("attachment.".length)] = {
-                            presigned_url: value.presigned_url,
+                            presigned_url: new URL(value.presigned_url, this.apiUrl).href,
                             mime_type: value.mime_type || undefined,
                         };
                         return acc;
@@ -3896,16 +3940,18 @@ class Client {
         });
     }
     async createFeedback(runIdOrParams, keyArg, optionsArg) {
-        const { runId = null, key, score, value, correction, comment, sourceInfo, feedbackSourceType = "api", sourceRunId, feedbackId, feedbackConfig, projectId, traceId, comparativeExperimentId, sessionId, startTime, extendTraceRetention, } = typeof runIdOrParams === "object" && runIdOrParams !== null
+        const { runId = null, key, score, value, correction, comment, sourceInfo, feedbackSourceType = "api", sourceRunId, feedbackId, feedbackConfig, projectId, traceId, comparativeExperimentId, sessionId, startTime, extendTraceRetention, address: rawAddress, } = typeof runIdOrParams === "object" && runIdOrParams !== null
             ? runIdOrParams
             : { runId: runIdOrParams, key: keyArg, ...optionsArg };
+        const address = (0, agent_addressing_js_1.checkAddress)(rawAddress);
+        (0, agent_addressing_js_1.rejectConflicting)(sessionId ?? projectId, address);
         if (!runId && !projectId) {
             throw new Error("One of runId or projectId must be provided");
         }
         if (runId && projectId) {
             throw new Error("Only one of runId or projectId can be provided");
         }
-        if (runId && sessionId === undefined) {
+        if (runId && sessionId === undefined && !address) {
             await this._checkFeedbackSessionId();
         }
         const feedback_source = {
@@ -3941,7 +3987,7 @@ class Client {
         if (samplingId != null && !this._shouldSample(samplingId)) {
             return feedback;
         }
-        const body = JSON.stringify(feedback);
+        const body = JSON.stringify(address ? { ...feedback, ...(0, address_js_1.toWire)(address) } : feedback);
         const url = `${this.apiUrl}/feedback`;
         await this.caller.call(async () => {
             const res = await this._fetch(url, {

package/dist/client.d.ts

@@ -11,6 +11,7 @@ import { AnnotationQueues } from "./_openapi_client/resources/annotation-queues/
 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 { type Address } from "./address.js";
 import { PromptCache } from "./utils/prompt_cache/index.js";
 import { ProfileAuth } from "./utils/profiles.js";
 export interface ClientConfig {
@@ -300,6 +301,7 @@ interface UploadCSVParams {
 }
 type DefaultClientConfig = {
     apiUrl: string;
+    apiUrlSource: string;
     apiKey?: string;
     webUrl?: string;
     hideInputs?: boolean;
@@ -325,6 +327,8 @@ interface CreateRunParams {
     child_runs?: RunCreate[];
     parent_run_id?: string;
     project_name?: string;
+    /** (beta) Send the run to this address instead of a project. */
+    address?: Address;
     revision_id?: string;
     trace_id?: string;
     dotted_order?: string;
@@ -377,11 +381,20 @@ export type CreateFeedbackParams = CreateFeedbackOptions & ({
     /** The session (project) ID of the run. */
     sessionId: string;
     projectId?: never;
+    address?: never;
+} | {
+    /** The run to provide feedback on. */
+    runId: string;
+    /** (beta) The address the run was sent to, e.g. `runTree.address`. */
+    address: Address;
+    sessionId?: never;
+    projectId?: never;
 } | {
     runId?: null;
     /** The project (or experiment) to provide feedback on. */
     projectId: string;
     sessionId?: never;
+    address?: never;
 });
 export type CreateExampleOptions = {
     /** The ID of the dataset to create the example in. */