langsmith 0.5.6 → 0.5.7

package/dist/client.cjs

@@ -47,6 +47,7 @@ const warn_js_1 = require("./utils/warn.cjs");
 const prompts_js_1 = require("./utils/prompts.cjs");
 const error_js_1 = require("./utils/error.cjs");
 const index_js_2 = require("./utils/prompt_cache/index.cjs");
+const fsUtils = __importStar(require("./utils/fs.cjs"));
 const fetch_js_1 = require("./singletons/fetch.cjs");
 const index_js_3 = require("./utils/fast-safe-stringify/index.cjs");
 function mergeRuntimeEnvIntoRun(run, cachedEnvVars, omitTracedRuntimeInfo) {
@@ -435,6 +436,18 @@ class Client {
             writable: true,
             value: (0, env_js_1.getLangSmithEnvironmentVariable)("DISABLE_RUN_COMPRESSION") === "true"
         });
+        Object.defineProperty(this, "failedTracesDir", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "failedTracesMaxBytes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 100 * 1024 * 1024
+        });
         Object.defineProperty(this, "debug", {
             enumerable: true,
             configurable: true,
@@ -466,6 +479,16 @@ class Client {
         }
         this.debug = config.debug ?? this.debug;
         this.fetchImplementation = config.fetchImplementation;
+        // Failed trace dump configuration
+        this.failedTracesDir =
+            (0, env_js_1.getLangSmithEnvironmentVariable)("FAILED_TRACES_DIR") || undefined;
+        const failedTracesMb = (0, env_js_1.getLangSmithEnvironmentVariable)("FAILED_TRACES_MAX_MB");
+        if (failedTracesMb) {
+            const n = parseInt(failedTracesMb, 10);
+            if (Number.isFinite(n) && n > 0) {
+                this.failedTracesMaxBytes = n * 1024 * 1024;
+            }
+        }
         // Use maxIngestMemoryBytes for both queues
         const maxMemory = config.maxIngestMemoryBytes ?? exports.DEFAULT_MAX_SIZE_BYTES;
         this.batchIngestCaller = new async_caller_js_1.AsyncCaller({
@@ -806,6 +829,63 @@ class Client {
         }
         return Promise.all(promises);
     }
+    /**
+     * Persist a failed trace payload to a local fallback directory.
+     *
+     * Saves a self-contained JSON file containing the endpoint path, the HTTP
+     * headers required for replay, and the base64-encoded request body.
+     * Can be replayed later with a simple POST:
+     *
+     *   POST /<endpoint>
+     *   Content-Type: <value from saved headers>
+     *   [Content-Encoding: <value from saved headers>]
+     *   <decoded body>
+     */
+    static async _writeTraceToFallbackDir(directory, body, replayHeaders, endpoint, maxBytes) {
+        try {
+            const bodyBuffer = typeof body === "string"
+                ? Buffer.from(body, "utf8")
+                : Buffer.from(body);
+            const envelope = JSON.stringify({
+                version: 1,
+                endpoint,
+                headers: replayHeaders,
+                body_base64: bodyBuffer.toString("base64"),
+            });
+            const filename = `trace_${Date.now()}_${uuid.v4().slice(0, 8)}.json`;
+            const filepath = fsUtils.path.join(directory, filename);
+            if (!Client._fallbackDirsCreated.has(directory)) {
+                await fsUtils.mkdir(directory);
+                Client._fallbackDirsCreated.add(directory);
+            }
+            // Check budget before writing — drop new traces if over limit.
+            if (maxBytes !== undefined && maxBytes > 0) {
+                try {
+                    const entries = await fsUtils.readdir(directory);
+                    const traceFiles = entries.filter((f) => f.startsWith("trace_") && f.endsWith(".json"));
+                    let total = 0;
+                    for (const name of traceFiles) {
+                        const { size } = await fsUtils.stat(fsUtils.path.join(directory, name));
+                        total += size;
+                    }
+                    if (total >= maxBytes) {
+                        console.warn(`Could not write trace to fallback dir ${directory} as it's ` +
+                            `already over size limit (${total} bytes >= ${maxBytes} bytes). ` +
+                            `Increase LANGSMITH_FAILED_TRACES_MAX_MB if possible.`);
+                        return;
+                    }
+                }
+                catch {
+                    // budget check errors must never prevent writing
+                }
+            }
+            await fsUtils.writeFileAtomic(filepath, envelope);
+            console.warn(`LangSmith trace upload failed; data saved to ${filepath} for later replay.`);
+        }
+        catch (writeErr) {
+            console.error(`LangSmith tracing error: could not write trace to fallback dir ${directory}:`, writeErr);
+        }
+    }
     async _processBatch(batch, options) {
         if (!batch.length) {
             return;
@@ -1386,6 +1466,12 @@ class Client {
                 throw e;
             }
             console.warn(`${e.message.trim()}\n\nContext: ${context}`);
+            if (this.failedTracesDir) {
+                const bodyBuffer = await this._createNodeFetchBody(parts, boundary).catch(() => null);
+                if (bodyBuffer) {
+                    await Client._writeTraceToFallbackDir(this.failedTracesDir, bodyBuffer, { "Content-Type": `multipart/form-data; boundary=${boundary}` }, "runs/multipart", this.failedTracesMaxBytes);
+                }
+            }
         }
     }
     async updateRun(runId, run, options) {
@@ -1739,6 +1825,128 @@ class Client {
             }
         }
     }
+    async *readThread(props) {
+        const { threadId, projectId, projectName, isRoot = true, limit, filter: userFilter, order = "asc", } = props;
+        if (!projectId && !projectName) {
+            throw new Error("threadId requires projectId or projectName");
+        }
+        const threadFilter = `eq(thread_id, ${JSON.stringify(threadId)})`;
+        const combinedFilter = userFilter
+            ? `and(${threadFilter}, ${userFilter})`
+            : threadFilter;
+        yield* this.listRuns({
+            projectId: projectId ?? undefined,
+            projectName: projectName ?? undefined,
+            isRoot,
+            limit,
+            filter: combinedFilter,
+            order,
+        });
+    }
+    async listThreads(props) {
+        const { projectId, projectName, limit, offset = 0, filter, startTime, isRoot = true, } = props;
+        if (!projectId && !projectName) {
+            throw new Error("Either projectId or projectName must be provided");
+        }
+        if (projectId && projectName) {
+            throw new Error("Provide exactly one of projectId or projectName");
+        }
+        const sessionId = projectId ?? (await this.readProject({ projectName: projectName })).id;
+        const startTimeResolved = startTime ?? new Date(Date.now() - 1 * 24 * 60 * 60 * 1000);
+        const runSelect = [
+            "id",
+            "name",
+            "status",
+            "start_time",
+            "end_time",
+            "thread_id",
+            "trace_id",
+            "run_type",
+            "error",
+            "tags",
+            "session_id",
+            "parent_run_id",
+            "total_tokens",
+            "total_cost",
+            "dotted_order",
+            "reference_example_id",
+            "feedback_stats",
+            "app_path",
+            "completion_cost",
+            "completion_tokens",
+            "prompt_cost",
+            "prompt_tokens",
+            "first_token_time",
+        ];
+        const bodyQuery = {
+            session: [sessionId],
+            is_root: isRoot,
+            limit: 100,
+            order: "desc",
+            select: runSelect,
+            start_time: startTimeResolved.toISOString(),
+        };
+        if (filter != null) {
+            bodyQuery.filter = filter;
+        }
+        const threadsMap = new Map();
+        for await (const runs of this._getCursorPaginatedList("/runs/query", bodyQuery)) {
+            for (const run of runs) {
+                const tid = run.thread_id;
+                if (tid) {
+                    const list = threadsMap.get(tid) ?? [];
+                    list.push(run);
+                    threadsMap.set(tid, list);
+                }
+            }
+        }
+        const result = [];
+        for (const [threadId, runs] of threadsMap.entries()) {
+            runs.sort((a, b) => {
+                const aRun = a;
+                const bRun = b;
+                const aStart = aRun.start_time ?? "";
+                const bStart = bRun.start_time ?? "";
+                if (aStart !== bStart)
+                    return aStart.localeCompare(bStart);
+                const aOrder = aRun.dotted_order ?? "";
+                const bOrder = bRun.dotted_order ?? "";
+                return aOrder.localeCompare(bOrder);
+            });
+            const startTimes = runs
+                .map((r) => r.start_time)
+                .filter(Boolean);
+            const sortedTimes = [...startTimes].sort();
+            const minStart = sortedTimes.length ? sortedTimes[0] : "";
+            const maxStart = sortedTimes.length
+                ? sortedTimes[sortedTimes.length - 1]
+                : "";
+            result.push({
+                thread_id: threadId,
+                runs,
+                count: runs.length,
+                filter: "",
+                total_tokens: 0,
+                total_cost: null,
+                min_start_time: minStart,
+                max_start_time: maxStart,
+                latency_p50: 0,
+                latency_p99: 0,
+                feedback_stats: null,
+                first_inputs: "",
+                last_outputs: "",
+                last_error: null,
+            });
+        }
+        result.sort((a, b) => {
+            const aMax = a.max_start_time ?? "";
+            const bMax = b.max_start_time ?? "";
+            return bMax.localeCompare(aMax);
+        });
+        const withOffset = offset > 0 ? result.slice(offset) : result;
+        const withLimit = limit !== undefined ? withOffset.slice(0, limit) : withOffset;
+        return withLimit;
+    }
     async getRunStats({ id, trace, parentRun, runType, projectNames, projectIds, referenceExampleIds, startTime, endTime, error, query, filter, traceFilter, treeFilter, isRoot, dataSourceType, }) {
         let projectIds_ = projectIds || [];
         if (projectNames) {
@@ -3605,21 +3813,110 @@ class Client {
             }
         }
     }
+    /**
+     * Check if a prompt exists.
+     * @param promptIdentifier - The identifier of the prompt. Can be in the format:
+     *   - "promptName" (for private prompts, owner defaults to "-")
+     *   - "owner/promptName" (for prompts with explicit owner)
+     * @returns A Promise that resolves to true if the prompt exists, false otherwise
+     * @example
+     * ```typescript
+     * // Check if a prompt exists before creating a commit
+     * if (await client.promptExists("my-prompt")) {
+     *   await client.createCommit("my-prompt", template);
+     * } else {
+     *   await client.createPrompt("my-prompt");
+     * }
+     * ```
+     */
     async promptExists(promptIdentifier) {
         const prompt = await this.getPrompt(promptIdentifier);
         return !!prompt;
     }
+    /**
+     * Like a prompt.
+     * @param promptIdentifier - The identifier of the prompt. Can be in the format:
+     *   - "promptName" (for private prompts, owner defaults to "-")
+     *   - "owner/promptName" (for prompts with explicit owner)
+     * @returns A Promise that resolves to the like response containing the updated like count
+     * @example
+     * ```typescript
+     * // Like a prompt
+     * const response = await client.likePrompt("owner/useful-prompt");
+     * console.log(`Prompt now has ${response.likes} likes`);
+     * ```
+     */
     async likePrompt(promptIdentifier) {
         return this._likeOrUnlikePrompt(promptIdentifier, true);
     }
+    /**
+     * Unlike a prompt (remove a previously added like).
+     * @param promptIdentifier - The identifier of the prompt. Can be in the format:
+     *   - "promptName" (for private prompts, owner defaults to "-")
+     *   - "owner/promptName" (for prompts with explicit owner)
+     * @returns A Promise that resolves to the like response containing the updated like count
+     * @example
+     * ```typescript
+     * // Unlike a prompt
+     * const response = await client.unlikePrompt("owner/useful-prompt");
+     * console.log(`Prompt now has ${response.likes} likes`);
+     * ```
+     */
     async unlikePrompt(promptIdentifier) {
         return this._likeOrUnlikePrompt(promptIdentifier, false);
     }
-    async *listCommits(promptOwnerAndName) {
-        for await (const commits of this._getPaginated(`/commits/${promptOwnerAndName}/`, new URLSearchParams(), (res) => res.commits)) {
+    /**
+     * List all commits for a prompt.
+     * @param promptIdentifier - The identifier of the prompt. Can be in the format:
+     *   - "promptName" (for private prompts, owner defaults to "-")
+     *   - "owner/promptName" (for prompts with explicit owner)
+     *   - "promptName:commitHash" (commit hash is ignored, all commits are returned)
+     * @returns An async iterable iterator of PromptCommit objects
+     * @example
+     * ```typescript
+     * // List commits for a private prompt
+     * for await (const commit of client.listCommits("my-prompt")) {
+     *   console.log(commit);
+     * }
+     *
+     * // List commits for a prompt with explicit owner
+     * for await (const commit of client.listCommits("owner/my-prompt")) {
+     *   console.log(commit);
+     * }
+     * ```
+     */
+    async *listCommits(promptIdentifier) {
+        const [owner, promptName, _] = (0, prompts_js_1.parsePromptIdentifier)(promptIdentifier);
+        for await (const commits of this._getPaginated(`/commits/${owner}/${promptName}/`, new URLSearchParams(), (res) => res.commits)) {
             yield* commits;
         }
     }
+    /**
+     * List prompts by filter.
+     * @param options - Optional filters for listing prompts
+     * @param options.isPublic - Filter by public/private prompts. If undefined, returns all prompts.
+     * @param options.isArchived - Filter by archived status. Defaults to false (non-archived prompts only).
+     * @param options.sortField - Field to sort by. Defaults to "updated_at".
+     * @param options.query - Search query to filter prompts by name or description.
+     * @returns An async iterable iterator of Prompt objects
+     * @example
+     * ```typescript
+     * // List all prompts
+     * for await (const prompt of client.listPrompts()) {
+     *   console.log(prompt);
+     * }
+     *
+     * // List only public prompts
+     * for await (const prompt of client.listPrompts({ isPublic: true })) {
+     *   console.log(prompt);
+     * }
+     *
+     * // Search for prompts
+     * for await (const prompt of client.listPrompts({ query: "translation" })) {
+     *   console.log(prompt);
+     * }
+     * ```
+     */
     async *listPrompts(options) {
         const params = new URLSearchParams();
         params.append("sort_field", options?.sortField ?? "updated_at");
@@ -3635,6 +3932,22 @@ class Client {
             yield* prompts;
         }
     }
+    /**
+     * Get a prompt by its identifier.
+     * @param promptIdentifier - The identifier of the prompt. Can be in the format:
+     *   - "promptName" (for private prompts, owner defaults to "-")
+     *   - "owner/promptName" (for prompts with explicit owner)
+     *   - "promptName:commitHash" (commit hash is ignored, latest version is returned)
+     * @returns A Promise that resolves to the Prompt object, or null if not found
+     * @example
+     * ```typescript
+     * // Get a private prompt
+     * const prompt = await client.getPrompt("my-prompt");
+     *
+     * // Get a public prompt
+     * const publicPrompt = await client.getPrompt("owner/public-prompt");
+     * ```
+     */
     async getPrompt(promptIdentifier) {
         const [owner, promptName, _] = (0, prompts_js_1.parsePromptIdentifier)(promptIdentifier);
         const response = await this.caller.call(async () => {
@@ -3658,6 +3971,33 @@ class Client {
             return null;
         }
     }
+    /**
+     * Create a new prompt.
+     * @param promptIdentifier - The identifier for the new prompt. Can be in the format:
+     *   - "promptName" (creates a private prompt)
+     *   - "owner/promptName" (creates a prompt under a specific owner, must match your tenant)
+     * @param options - Optional configuration for the prompt
+     * @param options.description - A description of the prompt
+     * @param options.readme - Markdown content for the prompt's README
+     * @param options.tags - Array of tags to categorize the prompt
+     * @param options.isPublic - Whether the prompt should be public. Requires a LangChain Hub handle.
+     * @returns A Promise that resolves to the created Prompt object
+     * @throws {Error} If creating a public prompt without a LangChain Hub handle, or if owner doesn't match current tenant
+     * @example
+     * ```typescript
+     * // Create a private prompt
+     * const prompt = await client.createPrompt("my-new-prompt", {
+     *   description: "A prompt for translations",
+     *   tags: ["translation", "language"]
+     * });
+     *
+     * // Create a public prompt
+     * const publicPrompt = await client.createPrompt("my-public-prompt", {
+     *   description: "A public translation prompt",
+     *   isPublic: true
+     * });
+     * ```
+     */
     async createPrompt(promptIdentifier, options) {
         const settings = await this._getSettings();
         if (options?.isPublic && !settings.tenant_handle) {
@@ -3692,6 +4032,35 @@ class Client {
         const { repo } = await response.json();
         return repo;
     }
+    /**
+     * Create a new commit for an existing prompt.
+     * @param promptIdentifier - The identifier of the prompt. Can be in the format:
+     *   - "promptName" (for private prompts, owner defaults to "-")
+     *   - "owner/promptName" (for prompts with explicit owner)
+     * @param object - The prompt object/manifest to commit (e.g., ChatPromptTemplate, messages array, etc.)
+     * @param options - Optional configuration for the commit
+     * @param options.parentCommitHash - The parent commit hash. Defaults to "latest" (the most recent commit).
+     * @returns A Promise that resolves to the URL of the newly created commit
+     * @throws {Error} If the prompt does not exist
+     * @example
+     * ```typescript
+     * import { ChatPromptTemplate } from "@langchain/core/prompts";
+     *
+     * // Create a commit with a new version of the prompt
+     * const template = ChatPromptTemplate.fromMessages([
+     *   ["system", "You are a helpful assistant."],
+     *   ["human", "{input}"]
+     * ]);
+     *
+     * const commitUrl = await client.createCommit("my-prompt", template);
+     * console.log(`Commit created: ${commitUrl}`);
+     *
+     * // Create a commit based on a specific parent commit
+     * const commitUrl2 = await client.createCommit("my-prompt", template, {
+     *   parentCommitHash: "abc123def456"
+     * });
+     * ```
+     */
     async createCommit(promptIdentifier, object, options) {
         if (!(await this.promptExists(promptIdentifier))) {
             throw new Error("Prompt does not exist, you must create it first.");
@@ -4176,6 +4545,12 @@ class Client {
     }
 }
 exports.Client = Client;
+Object.defineProperty(Client, "_fallbackDirsCreated", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: new Set()
+});
 function isExampleCreate(input) {
     return "dataset_id" in input || "dataset_name" in input;
 }