langsmith 0.8.8 → 0.8.10

package/dist/client.cjs

@@ -46,6 +46,7 @@ const index_js_1 = require("./index.cjs");
 const index_js_2 = require("./_openapi_client/index.cjs");
 const _uuid_js_1 = require("./utils/_uuid.cjs");
 const warn_js_1 = require("./utils/warn.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");
 const index_js_3 = require("./utils/prompt_cache/index.cjs");
@@ -192,6 +193,72 @@ exports.DEFAULT_MAX_SIZE_BYTES = 1024 * 1024 * 1024; // 1GB
 const SERVER_INFO_REQUEST_TIMEOUT_MS = 10000;
 /** Maximum number of operations to batch in a single request. */
 const DEFAULT_BATCH_SIZE_LIMIT = 100;
+/**
+ * Reject header names or values that could alter a request's framing.
+ *
+ * `Headers` does this for us, and does it the same way `fetch` will.
+ */
+function assertValidHeader(name, value) {
+    new Headers({ [name]: value });
+}
+/** Reject a malformed header up front, before it can reach a request. */
+function assertValidHeaders(headers) {
+    for (const [name, value] of Object.entries(headers ?? {})) {
+        assertValidHeader(name, value);
+    }
+}
+/**
+ * Fold a `HeadersInit` into a plain object so it can be spread.
+ *
+ * Names are matched case-insensitively with the last value winning, keeping the
+ * first spelling seen. A plain object would instead keep both spellings, which
+ * `Headers` later joins into a `"first, second"` list rather than an override.
+ * Every name and value is validated on the way through.
+ */
+function normalizeHeaders(headers) {
+    if (!headers)
+        return {};
+    const entries = headers instanceof Headers
+        ? [...headers.entries()]
+        : Array.isArray(headers)
+            ? headers.map(([name, value]) => [name, value])
+            : Object.entries(headers);
+    const normalized = {};
+    const nameByLower = new Map();
+    for (const [name, value] of entries) {
+        assertValidHeader(name, value);
+        const lowerName = name.toLowerCase();
+        const existingName = nameByLower.get(lowerName);
+        if (existingName === undefined) {
+            nameByLower.set(lowerName, name);
+            normalized[name] = value;
+        }
+        else {
+            normalized[existingName] = value;
+        }
+    }
+    return normalized;
+}
+/**
+ * Merge the caller's two header channels, then drop the `reserved` names.
+ *
+ * `overrides` wins, matched case-insensitively so a header supplied through both
+ * channels is overridden rather than turned into a `"first, second"` list.
+ */
+function mergeCallerHeaders(base, overrides, reserved) {
+    const merged = { ...base };
+    const nameByLower = new Map(Object.keys(merged).map((name) => [name.toLowerCase(), name]));
+    for (const [name, value] of Object.entries(overrides)) {
+        const lowerName = name.toLowerCase();
+        merged[nameByLower.get(lowerName) ?? name] = value;
+    }
+    for (const name of Object.keys(merged)) {
+        if (reserved.has(name.toLowerCase())) {
+            delete merged[name];
+        }
+    }
+    return merged;
+}
 class AutoBatchQueue {
     constructor(maxSizeBytes) {
         Object.defineProperty(this, "items", {
@@ -611,13 +678,26 @@ class Client {
             writable: true,
             value: void 0
         });
+        /** `config.fetchOptions` without its `headers`, which are merged separately. */
         Object.defineProperty(this, "fetchOptions", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
-        Object.defineProperty(this, "openAPIClient", {
+        Object.defineProperty(this, "_fetchOptionsHeaders", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: {}
+        });
+        Object.defineProperty(this, "_openAPIClient", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_openAPIClientSignature", {
             enumerable: true,
             configurable: true,
             writable: true,
@@ -813,7 +893,8 @@ class Client {
             config.hideInputs ?? config.anonymizer ?? defaultConfig.hideInputs;
         this.hideOutputs =
             config.hideOutputs ?? config.anonymizer ?? defaultConfig.hideOutputs;
-        this.hideMetadata = config.hideMetadata ?? defaultConfig.hideMetadata;
+        this.hideMetadata =
+            config.hideMetadata ?? config.anonymizer ?? defaultConfig.hideMetadata;
         this.anonymizer = config.anonymizer;
         this.omitTracedRuntimeInfo = config.omitTracedRuntimeInfo ?? false;
         this.autoBatchTracing = config.autoBatchTracing ?? this.autoBatchTracing;
@@ -822,8 +903,15 @@ class Client {
             config.blockOnRootRunFinalization ?? this.blockOnRootRunFinalization;
         this.batchSizeBytesLimit = config.batchSizeBytesLimit;
         this.batchSizeLimit = config.batchSizeLimit;
-        this.fetchOptions = config.fetchOptions || {};
-        this.openAPIClient = this._newOpenAPIClient();
+        const { headers: fetchOptionsHeaders, ...fetchOptions } = config.fetchOptions || {};
+        this.fetchOptions = fetchOptions;
+        // Kept apart from `fetchOptions` so they can be merged *under* the required
+        // headers instead of replacing the whole set at each call site.
+        this._fetchOptionsHeaders = normalizeHeaders(fetchOptionsHeaders);
+        // Validated eagerly so malformed input fails at construction, but stored
+        // as given: `get headers` hands this object back to the caller.
+        assertValidHeaders(config.headers);
+        this._customHeaders = config.headers ?? {};
         this.manualFlushMode = config.manualFlushMode ?? this.manualFlushMode;
         this._tracingMode = (0, env_js_1.resolveTracingMode)(config.tracingMode);
         if (this._tracingMode === "otel") {
@@ -858,8 +946,6 @@ class Client {
             // Use the global singleton instance
             this._promptCache = index_js_3.promptCacheSingleton;
         }
-        // Initialize custom headers
-        this._customHeaders = config.headers ?? {};
     }
     static getDefaultClientConfig() {
         const profileConfig = (0, profiles_js_1.loadProfileClientConfig)();
@@ -931,11 +1017,46 @@ class Client {
             return this.webUrl;
         }
     }
+    /**
+     * The headers this client sets from its own config, which a caller-supplied
+     * header must not replace.
+     *
+     * Only what the client *actually* supplies: passing an explicit `Authorization`
+     * or `x-api-key` header with no configured credential is a supported way to
+     * authenticate (see `hasExplicitAuthHeader`), so those must survive.
+     */
+    get _sdkControlledHeaders() {
+        const names = new Set();
+        if (this.apiKey !== undefined) {
+            names.add("x-api-key");
+        }
+        else {
+            const profileAuthHeader = this.profileAuth?.currentAuthHeader();
+            if (profileAuthHeader) {
+                names.add(profileAuthHeader.name.toLowerCase());
+            }
+        }
+        if (this.workspaceId) {
+            names.add("x-tenant-id");
+        }
+        return names;
+    }
+    /**
+     * Headers supplied by the caller, through either `config.headers` or
+     * `config.fetchOptions.headers`, with the ones this SDK sets removed.
+     *
+     * `_customHeaders` is normalized here rather than at assignment because it is
+     * public and mutable: `get headers` hands back the caller's own object, so its
+     * contents can change (and can become malformed) at any point.
+     */
+    get _callerHeaders() {
+        return mergeCallerHeaders(normalizeHeaders(this._customHeaders), this._fetchOptionsHeaders, this._sdkControlledHeaders);
+    }
     get _mergedHeaders() {
-        // Start with custom headers so they don't override required headers
+        // Start with caller-supplied headers so they don't override required headers
         const headers = {
             "User-Agent": `langsmith-js/${index_js_1.__version__}`,
-            ...this._customHeaders,
+            ...this._callerHeaders,
         };
         // Required headers that should not be overridden
         if (this.apiKey !== undefined) {
@@ -952,6 +1073,35 @@ class Client {
         }
         return headers;
     }
+    /**
+     * The auth options and caller headers to build the generated client with.
+     *
+     * The generated client applies `defaultHeaders` *after* its own auth headers,
+     * so the ones this SDK sets are already dropped from `_callerHeaders` to keep
+     * the precedence of `_mergedHeaders`, where required headers win.
+     */
+    get _openAPIAuth() {
+        const headers = { ...this._callerHeaders };
+        // A caller may authenticate by supplying `x-api-key` themselves. The
+        // generated client rejects that as a header (its `validateHeaders` requires
+        // its own `apiKey` to be set), so hand it over as the `apiKey` option and
+        // drop the header to avoid sending the same value twice.
+        const callerApiKeyName = Object.keys(headers).find((name) => name.toLowerCase() === "x-api-key");
+        let apiKey = this.apiKey;
+        if (apiKey === undefined && callerApiKeyName !== undefined) {
+            apiKey = headers[callerApiKeyName] ?? undefined;
+            delete headers[callerApiKeyName];
+        }
+        if (apiKey === undefined && this.workspaceId === undefined) {
+            // Let the wrapped `fetch` supply auth (profile auth, an explicit
+            // `Authorization` header, or none at all).
+            headers["X-API-Key"] = null;
+        }
+        return {
+            apiKey,
+            defaultHeaders: Object.keys(headers).length > 0 ? headers : undefined,
+        };
+    }
     /**
      * Get or set custom headers for the client.
      * Custom headers are merged with default headers (User-Agent, x-api-key, x-tenant-id).
@@ -961,6 +1111,7 @@ class Client {
         return this._customHeaders;
     }
     set headers(value) {
+        assertValidHeaders(value);
         this._customHeaders = value ?? {};
     }
     _getOpenAPIBaseUrl() {
@@ -971,19 +1122,36 @@ class Client {
         }
         return url;
     }
-    _newOpenAPIClient() {
-        const defaultHeaders = this.apiKey === undefined && this.workspaceId === undefined
-            ? { "X-API-Key": null }
-            : undefined;
-        const { method: _method, headers: _headers, body: _body, signal: _signal, ...openAPIFetchOptions } = this.fetchOptions;
+    /**
+     * The generated OpenAPI client, rebuilt whenever its auth or headers change.
+     *
+     * The generated client captures `defaultHeaders` and `apiKey` when it is
+     * built, while the handwritten paths recompute `_mergedHeaders` per request.
+     * Rebuilding on change keeps the two halves from diverging when the inputs
+     * move underneath us — a caller mutating the object returned by
+     * `get headers`, or a profile whose auth header only becomes available after
+     * its token is refreshed.
+     */
+    get openAPIClient() {
+        const auth = this._openAPIAuth;
+        const signature = JSON.stringify([auth.apiKey, auth.defaultHeaders]);
+        if (this._openAPIClient === undefined ||
+            this._openAPIClientSignature !== signature) {
+            this._openAPIClientSignature = signature;
+            this._openAPIClient = this._newOpenAPIClient(auth);
+        }
+        return this._openAPIClient;
+    }
+    _newOpenAPIClient(auth = this._openAPIAuth) {
+        const { method: _method, body: _body, signal: _signal, ...openAPIFetchOptions } = this.fetchOptions;
         return new index_js_2.Langsmith({
-            apiKey: this.apiKey,
+            apiKey: auth.apiKey,
             tenantID: this.workspaceId,
             baseURL: this._getOpenAPIBaseUrl(),
             timeout: this.timeout_ms,
             fetch: this._fetch,
             fetchOptions: openAPIFetchOptions,
-            defaultHeaders,
+            defaultHeaders: auth.defaultHeaders,
         });
     }
     _getPlatformEndpointPath(path) {
@@ -1388,6 +1556,9 @@ class Client {
         const batchSizeBytes = batch.reduce((sum, item) => sum + (item.size ?? 0), 0);
         try {
             if (this.langSmithToOTELTranslator !== undefined) {
+                for (const item of batch) {
+                    item.item = await this._maskRunMetadata(item.item);
+                }
                 this._sendBatchToOTELTranslator(batch);
             }
             else {
@@ -1468,6 +1639,25 @@ class Client {
             this.langSmithToOTELTranslator.exportBatch(operations, otelContextMap);
         }
     }
+    async _maskRunMetadata(run) {
+        if (run.extra?.metadata == null) {
+            return run;
+        }
+        return {
+            ...run,
+            extra: {
+                ...run.extra,
+                metadata: await this.processMetadata(run.extra.metadata),
+            },
+        };
+    }
+    async _mergeRuntimeEnvAndMaskMetadata(run) {
+        const merged = mergeRuntimeEnvIntoRun(run, this.cachedLSEnvVarsForMetadata, this.omitTracedRuntimeInfo);
+        if (this.omitTracedRuntimeInfo) {
+            return merged;
+        }
+        return this._maskRunMetadata(merged);
+    }
     async processRunOperation(item) {
         clearTimeout(this.autoBatchTimeout);
         this.autoBatchTimeout = undefined;
@@ -1560,7 +1750,7 @@ class Client {
     async _checkFeedbackSessionId() {
         const docs = "https://docs.langchain.com/langsmith/smithdb-sdk-migration#feedback-create";
         const serverInfo = await this._ensureServerInfo();
-        if (serverInfo.instance_flags?.ch_query_enabled === false) {
+        if ((0, v2_migration_js_1.getQueryBackend)(serverInfo.instance_flags) === v2_migration_js_1.QueryBackend.SMITHDB_ONLY) {
             throw new Error(`sessionId must be provided when creating feedback for a run: this ` +
                 `deployment cannot locate the run without it. See ${docs}`);
         }
@@ -1624,7 +1814,7 @@ class Client {
             }).catch(console.error);
             return;
         }
-        const mergedRunCreateParam = mergeRuntimeEnvIntoRun(runCreate, this.cachedLSEnvVarsForMetadata, this.omitTracedRuntimeInfo);
+        const mergedRunCreateParam = await this._mergeRuntimeEnvAndMaskMetadata(runCreate);
         if (options?.apiKey !== undefined) {
             headers["x-api-key"] = options.apiKey;
         }
@@ -2085,7 +2275,22 @@ class Client {
             return res;
         });
     }
+    /** @deprecated Use `client.runs.retrieve()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#runs-retrieve for the migration guide. Will be removed after Jan 31, 2027. */
     async readRun(runId, { loadChildRuns } = { loadChildRuns: false }) {
+        (0, warn_js_1.warnOnce)("readRun() is deprecated and will be removed after Jan 31, 2027. " +
+            "Use client.runs.retrieve() instead. " +
+            "See https://docs.langchain.com/langsmith/smithdb-sdk-migration#runs-retrieve for the migration guide.", { type: "DeprecationWarning", code: "LANGSMITH_DEPRECATED_READ_RUN" });
+        return this._readRun(runId, { loadChildRuns });
+    }
+    /**
+     * Fetch a run without emitting the `readRun()` deprecation warning.
+     *
+     * Internal callers use this so that a supported method doesn't warn about a
+     * deprecated one the caller never invoked.
+     *
+     * @internal
+     */
+    async _readRun(runId, { loadChildRuns } = { loadChildRuns: false }) {
         (0, _uuid_js_1.assertUuid)(runId);
         let run = _normalizeRunTimestamps(await this._get(`/runs/${runId}`));
         if (loadChildRuns) {
@@ -2093,7 +2298,11 @@ class Client {
         }
         return run;
     }
+    /** @deprecated Use `client.runs.getURL()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#runs-get-url for the migration guide. Will be removed after Jan 31, 2027. */
     async getRunUrl({ runId, run, projectOpts, }) {
+        (0, warn_js_1.warnOnce)("getRunUrl() is deprecated and will be removed after Jan 31, 2027. " +
+            "Use client.runs.getURL() instead. " +
+            "See https://docs.langchain.com/langsmith/smithdb-sdk-migration#runs-get-url for the migration guide.", { type: "DeprecationWarning", code: "LANGSMITH_DEPRECATED_GET_RUN_URL" });
         if (run !== undefined) {
             let sessionId;
             if (run.session_id) {
@@ -2115,7 +2324,9 @@ class Client {
             return `${this.getHostUrl()}/o/${tenantId}/projects/p/${sessionId}/r/${run.id}?poll=true`;
         }
         else if (runId !== undefined) {
-            const run_ = await this.readRun(runId);
+            // Via _readRun() rather than readRun() so callers don't also get a
+            // readRun deprecation warning for a method they never called.
+            const run_ = await this._readRun(runId);
             if (!run_.app_path) {
                 throw new Error(`Run ${runId} has no app_path`);
             }
@@ -2127,7 +2338,7 @@ class Client {
         }
     }
     async _loadChildRuns(run) {
-        const childRuns = await toArray(this.listRuns({
+        const childRuns = await toArray(this._listRuns({
             isRoot: false,
             projectId: run.session_id,
             traceId: run.trace_id,
@@ -2160,6 +2371,7 @@ class Client {
     }
     /**
      * List runs from the LangSmith server.
+     * @deprecated Use `client.runs.query()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#runs-query for the migration guide. Will be removed after Jan 31, 2027.
      * @param projectId - The ID of the project to filter by.
      * @param projectName - The name of the project to filter by.
      * @param parentRunId - The ID of the parent run to filter by.
@@ -2241,6 +2453,20 @@ class Client {
      * });
      */
     async *listRuns(props) {
+        (0, warn_js_1.warnOnce)("listRuns() is deprecated and will be removed after Jan 31, 2027. " +
+            "Use client.runs.query() instead. " +
+            "See https://docs.langchain.com/langsmith/smithdb-sdk-migration#runs-query for the migration guide.", { type: "DeprecationWarning", code: "LANGSMITH_DEPRECATED_LIST_RUNS" });
+        yield* this._listRuns(props);
+    }
+    /**
+     * List runs without emitting the `listRuns()` deprecation warning.
+     *
+     * Internal callers use this so that a supported method doesn't warn about a
+     * deprecated one the caller never invoked.
+     *
+     * @internal
+     */
+    async *_listRuns(props) {
         const { projectId, projectName, parentRunId, traceId, referenceExampleId, startTime, executionOrder, isRoot, runType, error, id, query, filter, traceFilter, treeFilter, limit, select, order, } = props;
         let projectIds = [];
         if (projectId) {
@@ -2374,7 +2600,11 @@ class Client {
             }
         }
     }
+    /** @deprecated Use `client.threads.listTraces()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#threads-list-traces for the migration guide. Will be removed after Jan 31, 2027. */
     async *readThread(props) {
+        (0, warn_js_1.warnOnce)("readThread() is deprecated and will be removed after Jan 31, 2027. " +
+            "Use client.threads.listTraces() instead. " +
+            "See https://docs.langchain.com/langsmith/smithdb-sdk-migration#threads-list-traces for the migration guide.", { type: "DeprecationWarning", code: "LANGSMITH_DEPRECATED_READ_THREAD" });
         const { threadId, projectId, projectName, isRoot = true, limit, filter: userFilter, order = "asc", } = props;
         if (!projectId && !projectName) {
             throw new Error("threadId requires projectId or projectName");
@@ -2383,7 +2613,9 @@ class Client {
         const combinedFilter = userFilter
             ? `and(${threadFilter}, ${userFilter})`
             : threadFilter;
-        yield* this.listRuns({
+        // Via _listRuns() rather than listRuns(): readThread() already warned, and it
+        // points at threads.listTraces() rather than listRuns()'s runs.query().
+        yield* this._listRuns({
             projectId: projectId ?? undefined,
             projectName: projectName ?? undefined,
             isRoot,
@@ -2392,7 +2624,11 @@ class Client {
             order,
         });
     }
+    /** @deprecated Use `client.threads.query()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#threads-query for the migration guide. Will be removed after Jan 31, 2027. */
     async listThreads(props) {
+        (0, warn_js_1.warnOnce)("listThreads() is deprecated and will be removed after Jan 31, 2027. " +
+            "Use client.threads.query() instead. " +
+            "See https://docs.langchain.com/langsmith/smithdb-sdk-migration#threads-query for the migration guide.", { type: "DeprecationWarning", code: "LANGSMITH_DEPRECATED_LIST_THREADS" });
         const { projectId, projectName, limit, offset = 0, filter, startTime, isRoot = true, } = props;
         if (!projectId && !projectName) {
             throw new Error("Either projectId or projectName must be provided");
@@ -2542,7 +2778,11 @@ class Client {
         const result = await response.json();
         return result;
     }
+    /** @deprecated Use `client.runs.share.create()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#share-and-read-public-runs for the migration guide. Will be removed after Jan 31, 2027. */
     async shareRun(runId, { shareId } = {}) {
+        (0, warn_js_1.warnOnce)("shareRun() is deprecated and will be removed after Jan 31, 2027. " +
+            "Use client.runs.share.create() instead. " +
+            "See https://docs.langchain.com/langsmith/smithdb-sdk-migration#share-and-read-public-runs for the migration guide.", { type: "DeprecationWarning", code: "LANGSMITH_DEPRECATED_SHARE_RUN" });
         const data = {
             run_id: runId,
             share_token: shareId || uuid.v4(),
@@ -2566,7 +2806,11 @@ class Client {
         }
         return `${this.getHostUrl()}/public/${result["share_token"]}/r`;
     }
+    /** @deprecated Use `client.runs.share.delete()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#share-and-read-public-runs for the migration guide. Will be removed after Jan 31, 2027. */
     async unshareRun(runId) {
+        (0, warn_js_1.warnOnce)("unshareRun() is deprecated and will be removed after Jan 31, 2027. " +
+            "Use client.runs.share.delete() instead. " +
+            "See https://docs.langchain.com/langsmith/smithdb-sdk-migration#share-and-read-public-runs for the migration guide.", { type: "DeprecationWarning", code: "LANGSMITH_DEPRECATED_UNSHARE_RUN" });
         (0, _uuid_js_1.assertUuid)(runId);
         await this.caller.call(async () => {
             const res = await this._fetch(`${this.apiUrl}/runs/${runId}/share`, {
@@ -2579,7 +2823,14 @@ class Client {
             return res;
         });
     }
+    /** @deprecated Use `client.runs.retrieve({ selects: ["SHARE_URL"] })` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#share-and-read-public-runs for the migration guide. Will be removed after Jan 31, 2027. */
     async readRunSharedLink(runId) {
+        (0, warn_js_1.warnOnce)("readRunSharedLink() is deprecated and will be removed after Jan 31, 2027. " +
+            'Use client.runs.retrieve({ selects: ["SHARE_URL"] }) instead. ' +
+            "See https://docs.langchain.com/langsmith/smithdb-sdk-migration#share-and-read-public-runs for the migration guide.", {
+            type: "DeprecationWarning",
+            code: "LANGSMITH_DEPRECATED_READ_RUN_SHARED_LINK",
+        });
         (0, _uuid_js_1.assertUuid)(runId);
         const response = await this.caller.call(async () => {
             const res = await this._fetch(`${this.apiUrl}/runs/${runId}/share`, {
@@ -2597,7 +2848,14 @@ class Client {
         }
         return `${this.getHostUrl()}/public/${result["share_token"]}/r`;
     }
+    /** @deprecated Use `client.public.runs.query()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#share-and-read-public-runs for the migration guide. Will be removed after Jan 31, 2027. */
     async listSharedRuns(shareToken, { runIds, } = {}) {
+        (0, warn_js_1.warnOnce)("listSharedRuns() is deprecated and will be removed after Jan 31, 2027. " +
+            "Use client.public.runs.query() instead. " +
+            "See https://docs.langchain.com/langsmith/smithdb-sdk-migration#share-and-read-public-runs for the migration guide.", {
+            type: "DeprecationWarning",
+            code: "LANGSMITH_DEPRECATED_LIST_SHARED_RUNS",
+        });
         const queryParams = new URLSearchParams({
             share_token: shareToken,
         });
@@ -2745,7 +3003,7 @@ class Client {
             _hostUrl: this.getHostUrl(),
         }));
     }
-    async createProject({ projectName, description = null, metadata = null, upsert = false, projectExtra = null, referenceDatasetId = null, numExamples = null, numRepetitions = null, evaluatorKeys = null, }) {
+    async createProject({ projectName, description = null, metadata = null, upsert = false, projectExtra = null, referenceDatasetId = null, numExamples = null, numRepetitions = null, evaluatorKeys = null, tagValueIds = null, }) {
         const upsert_ = upsert ? `?upsert=true` : "";
         const endpoint = `${this.apiUrl}/sessions${upsert_}`;
         const extra = projectExtra || {};
@@ -2769,6 +3027,9 @@ class Client {
         if (evaluatorKeys != null && evaluatorKeys.length > 0) {
             body["evaluator_keys"] = evaluatorKeys;
         }
+        if (tagValueIds !== null) {
+            body["tag_value_ids"] = tagValueIds;
+        }
         const serializedBody = JSON.stringify(body);
         const response = await this.caller.call(async () => {
             const res = await this._fetch(endpoint, {
@@ -3012,7 +3273,7 @@ class Client {
         const result = await response.json();
         return result;
     }
-    async createDataset(name, { description, dataType, inputsSchema, outputsSchema, metadata, } = {}) {
+    async createDataset(name, { description, dataType, inputsSchema, outputsSchema, metadata, tagValueIds, } = {}) {
         const body = {
             name,
             description,
@@ -3027,6 +3288,9 @@ class Client {
         if (outputsSchema) {
             body.outputs_schema_definition = outputsSchema;
         }
+        if (tagValueIds !== undefined) {
+            body.tag_value_ids = tagValueIds;
+        }
         const serializedBody = JSON.stringify(body);
         const response = await this.caller.call(async () => {
             const res = await this._fetch(`${this.apiUrl}/datasets`, {
@@ -4186,8 +4450,9 @@ class Client {
      * - `RunKey[]` (preferred): each entry carries the run's full lookup key, so
      *   it can be located directly without a scan. Required for workspaces served
      *   by SmithDB; routes to `POST /runs/by-key`.
-     * - `string[]`: a plain list of run IDs. This path will be deprecated in a
-     *   future release; prefer the key form. Routes to `POST /runs`.
+     * - `string[]`: a plain list of run IDs. **Deprecated**: this path will be
+     *   removed after Jan 31, 2027; prefer the key form. Routes to `POST /runs`.
+     *   See https://docs.langchain.com/langsmith/smithdb-sdk-migration#annotation-queues-add-runs.
      *
      * If every element is a string (or the list is empty) it is treated as run
      * IDs; otherwise the list is treated as `RunKey` objects.
@@ -4218,6 +4483,12 @@ class Client {
             }));
         }
         else {
+            (0, warn_js_1.warnOnce)("Passing run IDs as strings to addRunsToAnnotationQueue() is deprecated and will be removed after Jan 31, 2027. " +
+                "Use RunKey[] instead. " +
+                "See https://docs.langchain.com/langsmith/smithdb-sdk-migration#annotation-queues-add-runs for the migration guide.", {
+                type: "DeprecationWarning",
+                code: "LANGSMITH_DEPRECATED_ADD_RUNS_STRING_IDS",
+            });
             url = base;
             body = JSON.stringify(runs.map((id, i) => (0, _uuid_js_1.assertUuid)(id, `runs[${i}]`).toString()));
         }