langsmith 0.4.4 → 0.4.6

package/dist/client.cjs

@@ -46,6 +46,7 @@ const _uuid_js_1 = require("./utils/_uuid.cjs");
 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 prompts_cache_js_1 = require("./utils/prompts_cache.cjs");
 const fetch_js_1 = require("./singletons/fetch.cjs");
 const index_js_2 = require("./utils/fast-safe-stringify/index.cjs");
 function mergeRuntimeEnvIntoRun(run, cachedEnvVars, omitTracedRuntimeInfo) {
@@ -410,6 +411,12 @@ class Client {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "_cache", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(this, "multipartStreamingDisabled", {
             enumerable: true,
             configurable: true,
@@ -481,6 +488,16 @@ class Client {
         }
         // Cache metadata env vars once during construction to avoid repeatedly scanning process.env
         this.cachedLSEnvVarsForMetadata = (0, env_js_1.getLangSmithEnvVarsMetadata)();
+        // Initialize cache
+        if (config.cache === true) {
+            this._cache = new prompts_cache_js_1.Cache();
+        }
+        else if (config.cache && typeof config.cache === "object") {
+            this._cache = config.cache;
+        }
+        else {
+            this._cache = undefined;
+        }
     }
     static getDefaultClientConfig() {
         const apiKey = (0, env_js_1.getLangSmithEnvironmentVariable)("API_KEY");
@@ -3784,7 +3801,18 @@ class Client {
         });
         return response.json();
     }
-    async pullPromptCommit(promptIdentifier, options) {
+    /**
+     * Generate a cache key for a prompt.
+     * Format: "{identifier}" or "{identifier}:with_model"
+     */
+    _getPromptCacheKey(promptIdentifier, includeModel) {
+        const suffix = includeModel ? ":with_model" : "";
+        return `${promptIdentifier}${suffix}`;
+    }
+    /**
+     * Fetch a prompt commit directly from the API (bypassing cache).
+     */
+    async _fetchPromptFromApi(promptIdentifier, options) {
         const [owner, promptName, commitHash] = (0, prompts_js_1.parsePromptIdentifier)(promptIdentifier);
         const response = await this.caller.call(async () => {
             const res = await this._fetch(`${this.apiUrl}/commits/${owner}/${promptName}/${commitHash}${options?.includeModel ? "?include_model=true" : ""}`, {
@@ -3805,6 +3833,22 @@ class Client {
             examples: result.examples,
         };
     }
+    async pullPromptCommit(promptIdentifier, options) {
+        // Check cache first if not skipped
+        if (!options?.skipCache && this._cache) {
+            const cacheKey = this._getPromptCacheKey(promptIdentifier, options?.includeModel);
+            const cached = this._cache.get(cacheKey);
+            if (cached) {
+                return cached;
+            }
+            // Cache miss - fetch from API and cache it
+            const result = await this._fetchPromptFromApi(promptIdentifier, options);
+            this._cache.set(cacheKey, result);
+            return result;
+        }
+        // No cache or skip cache - fetch directly
+        return this._fetchPromptFromApi(promptIdentifier, options);
+    }
     /**
      * This method should not be used directly, use `import { pull } from "langchain/hub"` instead.
      * Using this method directly returns the JSON string of the prompt rather than a LangChain object.
@@ -3813,6 +3857,7 @@ class Client {
     async _pullPrompt(promptIdentifier, options) {
         const promptObject = await this.pullPromptCommit(promptIdentifier, {
             includeModel: options?.includeModel,
+            skipCache: options?.skipCache,
         });
         const prompt = JSON.stringify(promptObject.manifest);
         return prompt;
@@ -3927,6 +3972,22 @@ class Client {
             throw new Error(`Invalid public ${kind} URL or token: ${urlOrToken}`);
         }
     }
+    /**
+     * Get the cache instance, if caching is enabled.
+     * Useful for accessing cache metrics or manually managing the cache.
+     */
+    get cache() {
+        return this._cache;
+    }
+    /**
+     * Cleanup resources held by the client.
+     * Stops the cache's background refresh timer.
+     */
+    cleanup() {
+        if (this._cache) {
+            this._cache.stop();
+        }
+    }
     /**
      * Awaits all pending trace batches. Useful for environments where
      * you need to be sure that all tracing requests finish before execution ends,

package/dist/client.d.ts

@@ -2,6 +2,7 @@ import type { OTELContext } from "./experimental/otel/types.js";
 import { AsyncCallerParams } from "./utils/async_caller.js";
 import { ComparativeExperiment, DataType, Dataset, DatasetDiffInfo, DatasetShareSchema, Example, ExampleCreate, ExampleUpdate, ExampleUpdateWithoutId, Feedback, FeedbackConfig, FeedbackIngestToken, KVMap, LangChainBaseMessage, LangSmithSettings, LikePromptResponse, Prompt, PromptCommit, PromptSortField, Run, RunCreate, RunUpdate, ScoreType, ExampleSearch, TimeDelta, TracerSession, TracerSessionResult, ValueType, AnnotationQueue, RunWithAnnotationQueueInfo, Attachments, UploadExamplesResponse, UpdateExamplesResponse, DatasetVersion, AnnotationQueueWithDetails } from "./schemas.js";
 import { EvaluationResult, EvaluationResults } from "./evaluation/evaluator.js";
+import { Cache } from "./utils/prompts_cache.js";
 export interface ClientConfig {
     apiUrl?: string;
     apiKey?: string;
@@ -49,6 +50,28 @@ export interface ClientConfig {
      * Custom fetch implementation. Useful for testing.
      */
     fetchImplementation?: typeof fetch;
+    /**
+     * Configuration for caching. Can be:
+     * - `true`: Enable caching with default settings
+     * - `Cache` instance: Use custom cache configuration
+     * - `undefined` or `false`: Disable caching (default)
+     *
+     * @example
+     * ```typescript
+     * import { Client, Cache } from "langsmith";
+     *
+     * // Enable with defaults
+     * const client1 = new Client({ cache: true });
+     *
+     * // Or use custom configuration
+     * const myCache = new Cache({
+     *   maxSize: 100,
+     *   ttlSeconds: 3600, // 1 hour, or null for infinite TTL
+     * });
+     * const client2 = new Client({ cache: myCache });
+     * ```
+     */
+    cache?: Cache | boolean;
 }
 /**
  * Represents the parameters for listing runs (spans) from the Langsmith server.
@@ -351,6 +374,7 @@ export declare class Client implements LangSmithTracingClientInterface {
     private langSmithToOTELTranslator?;
     private fetchImplementation?;
     private cachedLSEnvVarsForMetadata?;
+    private _cache?;
     private get _fetch();
     private multipartStreamingDisabled;
     private _multipartDisabled;
@@ -995,8 +1019,18 @@ export declare class Client implements LangSmithTracingClientInterface {
         isArchived?: boolean;
     }): Promise<Record<string, any>>;
     deletePrompt(promptIdentifier: string): Promise<void>;
+    /**
+     * Generate a cache key for a prompt.
+     * Format: "{identifier}" or "{identifier}:with_model"
+     */
+    private _getPromptCacheKey;
+    /**
+     * Fetch a prompt commit directly from the API (bypassing cache).
+     */
+    private _fetchPromptFromApi;
     pullPromptCommit(promptIdentifier: string, options?: {
         includeModel?: boolean;
+        skipCache?: boolean;
     }): Promise<PromptCommit>;
     /**
      * This method should not be used directly, use `import { pull } from "langchain/hub"` instead.
@@ -1005,6 +1039,7 @@ export declare class Client implements LangSmithTracingClientInterface {
      */
     _pullPrompt(promptIdentifier: string, options?: {
         includeModel?: boolean;
+        skipCache?: boolean;
     }): Promise<any>;
     pushPrompt(promptIdentifier: string, options?: {
         object?: any;
@@ -1030,6 +1065,16 @@ export declare class Client implements LangSmithTracingClientInterface {
         datasetName?: string;
     }): Promise<void>;
     private parseTokenOrUrl;
+    /**
+     * Get the cache instance, if caching is enabled.
+     * Useful for accessing cache metrics or manually managing the cache.
+     */
+    get cache(): Cache | undefined;
+    /**
+     * Cleanup resources held by the client.
+     * Stops the cache's background refresh timer.
+     */
+    cleanup(): void;
     /**
      * Awaits all pending trace batches. Useful for environments where
      * you need to be sure that all tracing requests finish before execution ends,

package/dist/client.js

@@ -9,6 +9,7 @@ import { assertUuid } from "./utils/_uuid.js";
 import { warnOnce } from "./utils/warn.js";
 import { parsePromptIdentifier } from "./utils/prompts.js";
 import { raiseForStatus, isLangSmithNotFoundError } from "./utils/error.js";
+import { Cache } from "./utils/prompts_cache.js";
 import { _globalFetchImplementationIsNodeFetch, _getFetchImplementation, } from "./singletons/fetch.js";
 import { serialize as serializePayloadForTracing } from "./utils/fast-safe-stringify/index.js";
 export function mergeRuntimeEnvIntoRun(run, cachedEnvVars, omitTracedRuntimeInfo) {
@@ -372,6 +373,12 @@ export class Client {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "_cache", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(this, "multipartStreamingDisabled", {
             enumerable: true,
             configurable: true,
@@ -443,6 +450,16 @@ export class Client {
         }
         // Cache metadata env vars once during construction to avoid repeatedly scanning process.env
         this.cachedLSEnvVarsForMetadata = getLangSmithEnvVarsMetadata();
+        // Initialize cache
+        if (config.cache === true) {
+            this._cache = new Cache();
+        }
+        else if (config.cache && typeof config.cache === "object") {
+            this._cache = config.cache;
+        }
+        else {
+            this._cache = undefined;
+        }
     }
     static getDefaultClientConfig() {
         const apiKey = getLangSmithEnvironmentVariable("API_KEY");
@@ -3746,7 +3763,18 @@ export class Client {
         });
         return response.json();
     }
-    async pullPromptCommit(promptIdentifier, options) {
+    /**
+     * Generate a cache key for a prompt.
+     * Format: "{identifier}" or "{identifier}:with_model"
+     */
+    _getPromptCacheKey(promptIdentifier, includeModel) {
+        const suffix = includeModel ? ":with_model" : "";
+        return `${promptIdentifier}${suffix}`;
+    }
+    /**
+     * Fetch a prompt commit directly from the API (bypassing cache).
+     */
+    async _fetchPromptFromApi(promptIdentifier, options) {
         const [owner, promptName, commitHash] = parsePromptIdentifier(promptIdentifier);
         const response = await this.caller.call(async () => {
             const res = await this._fetch(`${this.apiUrl}/commits/${owner}/${promptName}/${commitHash}${options?.includeModel ? "?include_model=true" : ""}`, {
@@ -3767,6 +3795,22 @@ export class Client {
             examples: result.examples,
         };
     }
+    async pullPromptCommit(promptIdentifier, options) {
+        // Check cache first if not skipped
+        if (!options?.skipCache && this._cache) {
+            const cacheKey = this._getPromptCacheKey(promptIdentifier, options?.includeModel);
+            const cached = this._cache.get(cacheKey);
+            if (cached) {
+                return cached;
+            }
+            // Cache miss - fetch from API and cache it
+            const result = await this._fetchPromptFromApi(promptIdentifier, options);
+            this._cache.set(cacheKey, result);
+            return result;
+        }
+        // No cache or skip cache - fetch directly
+        return this._fetchPromptFromApi(promptIdentifier, options);
+    }
     /**
      * This method should not be used directly, use `import { pull } from "langchain/hub"` instead.
      * Using this method directly returns the JSON string of the prompt rather than a LangChain object.
@@ -3775,6 +3819,7 @@ export class Client {
     async _pullPrompt(promptIdentifier, options) {
         const promptObject = await this.pullPromptCommit(promptIdentifier, {
             includeModel: options?.includeModel,
+            skipCache: options?.skipCache,
         });
         const prompt = JSON.stringify(promptObject.manifest);
         return prompt;
@@ -3889,6 +3934,22 @@ export class Client {
             throw new Error(`Invalid public ${kind} URL or token: ${urlOrToken}`);
         }
     }
+    /**
+     * Get the cache instance, if caching is enabled.
+     * Useful for accessing cache metrics or manually managing the cache.
+     */
+    get cache() {
+        return this._cache;
+    }
+    /**
+     * Cleanup resources held by the client.
+     * Stops the cache's background refresh timer.
+     */
+    cleanup() {
+        if (this._cache) {
+            this._cache.stop();
+        }
+    }
     /**
      * Awaits all pending trace batches. Useful for environments where
      * you need to be sure that all tracing requests finish before execution ends,

package/dist/index.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.__version__ = exports.uuid7FromTime = exports.uuid7 = exports.getDefaultProjectName = exports.overrideFetchImplementation = exports.RunTree = exports.Client = void 0;
+exports.__version__ = exports.Cache = exports.uuid7FromTime = exports.uuid7 = exports.getDefaultProjectName = exports.overrideFetchImplementation = exports.RunTree = exports.Client = void 0;
 var client_js_1 = require("./client.cjs");
 Object.defineProperty(exports, "Client", { enumerable: true, get: function () { return client_js_1.Client; } });
 var run_trees_js_1 = require("./run_trees.cjs");
@@ -12,5 +12,7 @@ Object.defineProperty(exports, "getDefaultProjectName", { enumerable: true, get:
 var uuid_js_1 = require("./uuid.cjs");
 Object.defineProperty(exports, "uuid7", { enumerable: true, get: function () { return uuid_js_1.uuid7; } });
 Object.defineProperty(exports, "uuid7FromTime", { enumerable: true, get: function () { return uuid_js_1.uuid7FromTime; } });
+var prompts_cache_js_1 = require("./utils/prompts_cache.cjs");
+Object.defineProperty(exports, "Cache", { enumerable: true, get: function () { return prompts_cache_js_1.Cache; } });
 // Update using yarn bump-version
-exports.__version__ = "0.4.4";
+exports.__version__ = "0.4.6";

package/dist/index.d.ts

@@ -4,4 +4,5 @@ export { RunTree, type RunTreeConfig } from "./run_trees.js";
 export { overrideFetchImplementation } from "./singletons/fetch.js";
 export { getDefaultProjectName } from "./utils/project.js";
 export { uuid7, uuid7FromTime } from "./uuid.js";
-export declare const __version__ = "0.4.4";
+export { Cache, type CacheConfig, type CacheMetrics, } from "./utils/prompts_cache.js";
+export declare const __version__ = "0.4.6";

package/dist/index.js

@@ -3,5 +3,6 @@ export { RunTree } from "./run_trees.js";
 export { overrideFetchImplementation } from "./singletons/fetch.js";
 export { getDefaultProjectName } from "./utils/project.js";
 export { uuid7, uuid7FromTime } from "./uuid.js";
+export { Cache, } from "./utils/prompts_cache.js";
 // Update using yarn bump-version
-export const __version__ = "0.4.4";
+export const __version__ = "0.4.6";

package/dist/run_trees.cjs

@@ -44,6 +44,20 @@ function convertToDottedOrderFormat(epoch, runId, executionOrder = 1) {
         microsecondPrecisionDatestring,
     };
 }
+const HEADER_SAFE_REPLICA_FIELDS = new Set([
+    "projectName",
+    "updates",
+    "reroot",
+]);
+function filterReplicaForHeaders(replica) {
+    const filtered = {};
+    for (const key of Object.keys(replica)) {
+        if (HEADER_SAFE_REPLICA_FIELDS.has(key)) {
+            filtered[key] = replica[key];
+        }
+    }
+    return filtered;
+}
 /**
  * Baggage header information
  */
@@ -97,7 +111,13 @@ class Baggage {
                 project_name = value;
             }
             else if (key === "langsmith-replicas") {
-                replicas = JSON.parse(value);
+                const parsed = JSON.parse(value);
+                replicas = parsed.map((replica) => {
+                    if (Array.isArray(replica)) {
+                        return replica;
+                    }
+                    return filterReplicaForHeaders(replica);
+                });
             }
         }
         return new Baggage(metadata, tags, project_name, replicas);

package/dist/run_trees.js

@@ -38,6 +38,20 @@ export function convertToDottedOrderFormat(epoch, runId, executionOrder = 1) {
         microsecondPrecisionDatestring,
     };
 }
+const HEADER_SAFE_REPLICA_FIELDS = new Set([
+    "projectName",
+    "updates",
+    "reroot",
+]);
+function filterReplicaForHeaders(replica) {
+    const filtered = {};
+    for (const key of Object.keys(replica)) {
+        if (HEADER_SAFE_REPLICA_FIELDS.has(key)) {
+            filtered[key] = replica[key];
+        }
+    }
+    return filtered;
+}
 /**
  * Baggage header information
  */
@@ -91,7 +105,13 @@ class Baggage {
                 project_name = value;
             }
             else if (key === "langsmith-replicas") {
-                replicas = JSON.parse(value);
+                const parsed = JSON.parse(value);
+                replicas = parsed.map((replica) => {
+                    if (Array.isArray(replica)) {
+                        return replica;
+                    }
+                    return filterReplicaForHeaders(replica);
+                });
             }
         }
         return new Baggage(metadata, tags, project_name, replicas);

package/dist/utils/prompts_cache.cjs

@@ -0,0 +1,292 @@
+"use strict";
+/**
+ * Prompt caching module for LangSmith SDK.
+ *
+ * Provides an LRU cache with background refresh for prompt caching.
+ * Uses stale-while-revalidate pattern for optimal performance.
+ *
+ * Works in all environments. File operations (dump/load) use helpers
+ * that are swapped for browser builds via package.json browser field.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Cache = void 0;
+const prompts_cache_fs_js_1 = require("./prompts_cache_fs.cjs");
+/**
+ * Check if a cache entry is stale based on TTL.
+ */
+function isStale(entry, ttlSeconds) {
+    if (ttlSeconds === null) {
+        return false; // Infinite TTL, never stale
+    }
+    const ageMs = Date.now() - entry.createdAt;
+    return ageMs > ttlSeconds * 1000;
+}
+/**
+ * LRU cache with background refresh for prompts.
+ *
+ * Features:
+ * - In-memory LRU cache with configurable max size
+ * - Background refresh using setInterval
+ * - Stale-while-revalidate: returns stale data while refresh happens
+ * - JSON dump/load for offline use
+ *
+ * @example
+ * ```typescript
+ * const cache = new Cache({
+ *   maxSize: 100,
+ *   ttlSeconds: 3600,
+ *   fetchFunc: async (key) => client.pullPromptCommit(key),
+ * });
+ *
+ * // Use the cache
+ * cache.set("my-prompt:latest", promptCommit);
+ * const cached = cache.get("my-prompt:latest");
+ *
+ * // Cleanup
+ * cache.stop();
+ * ```
+ */
+class Cache {
+    constructor(config = {}) {
+        Object.defineProperty(this, "cache", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "maxSize", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "ttlSeconds", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "refreshIntervalSeconds", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "fetchFunc", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "refreshTimer", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_metrics", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: {
+                hits: 0,
+                misses: 0,
+                refreshes: 0,
+                refreshErrors: 0,
+            }
+        });
+        this.maxSize = config.maxSize ?? 100;
+        this.ttlSeconds = config.ttlSeconds ?? 3600;
+        this.refreshIntervalSeconds = config.refreshIntervalSeconds ?? 60;
+        this.fetchFunc = config.fetchFunc;
+        // Start background refresh if fetch function provided and TTL is set
+        if (this.fetchFunc && this.ttlSeconds !== null) {
+            this.startRefreshLoop();
+        }
+    }
+    /**
+     * Get cache performance metrics.
+     */
+    get metrics() {
+        return { ...this._metrics };
+    }
+    /**
+     * Get total cache requests (hits + misses).
+     */
+    get totalRequests() {
+        return this._metrics.hits + this._metrics.misses;
+    }
+    /**
+     * Get cache hit rate (0.0 to 1.0).
+     */
+    get hitRate() {
+        const total = this.totalRequests;
+        return total > 0 ? this._metrics.hits / total : 0;
+    }
+    /**
+     * Reset all metrics to zero.
+     */
+    resetMetrics() {
+        this._metrics = {
+            hits: 0,
+            misses: 0,
+            refreshes: 0,
+            refreshErrors: 0,
+        };
+    }
+    /**
+     * Get a value from cache.
+     *
+     * Returns the cached value or undefined if not found.
+     * Stale entries are still returned (background refresh handles updates).
+     */
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            this._metrics.misses += 1;
+            return undefined;
+        }
+        // Move to end for LRU (delete and re-add)
+        this.cache.delete(key);
+        this.cache.set(key, entry);
+        this._metrics.hits += 1;
+        return entry.value;
+    }
+    /**
+     * Set a value in the cache.
+     */
+    set(key, value) {
+        // Check if we need to evict (and key is new)
+        if (!this.cache.has(key) && this.cache.size >= this.maxSize) {
+            // Evict oldest (first item in Map)
+            const oldestKey = this.cache.keys().next().value;
+            if (oldestKey !== undefined) {
+                this.cache.delete(oldestKey);
+            }
+        }
+        const entry = {
+            value,
+            createdAt: Date.now(),
+        };
+        // Delete first to ensure it's at the end
+        this.cache.delete(key);
+        this.cache.set(key, entry);
+    }
+    /**
+     * Remove a specific entry from cache.
+     */
+    invalidate(key) {
+        this.cache.delete(key);
+    }
+    /**
+     * Clear all cache entries.
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Get the number of entries in the cache.
+     */
+    get size() {
+        return this.cache.size;
+    }
+    /**
+     * Stop background refresh.
+     * Should be called when the client is being cleaned up.
+     */
+    stop() {
+        if (this.refreshTimer) {
+            clearInterval(this.refreshTimer);
+            this.refreshTimer = undefined;
+        }
+    }
+    /**
+     * Dump cache contents to a JSON file for offline use.
+     */
+    dump(filePath) {
+        const entries = {};
+        for (const [key, entry] of this.cache.entries()) {
+            entries[key] = entry.value;
+        }
+        (0, prompts_cache_fs_js_1.dumpCache)(filePath, entries);
+    }
+    /**
+     * Load cache contents from a JSON file.
+     *
+     * Loaded entries get a fresh TTL starting from load time.
+     *
+     * @returns Number of entries loaded.
+     */
+    load(filePath) {
+        const entries = (0, prompts_cache_fs_js_1.loadCache)(filePath);
+        if (!entries) {
+            return 0;
+        }
+        let loaded = 0;
+        const now = Date.now();
+        for (const [key, value] of Object.entries(entries)) {
+            if (this.cache.size >= this.maxSize) {
+                break;
+            }
+            const entry = {
+                value: value,
+                createdAt: now, // Fresh TTL from load time
+            };
+            this.cache.set(key, entry);
+            loaded += 1;
+        }
+        return loaded;
+    }
+    /**
+     * Start the background refresh loop.
+     */
+    startRefreshLoop() {
+        this.refreshTimer = setInterval(() => {
+            this.refreshStaleEntries().catch((e) => {
+                // Log but don't die - keep the refresh loop running
+                console.warn("Unexpected error in cache refresh loop:", e);
+            });
+        }, this.refreshIntervalSeconds * 1000);
+        // Don't block Node.js from exiting
+        if (this.refreshTimer.unref) {
+            this.refreshTimer.unref();
+        }
+    }
+    /**
+     * Get list of stale cache keys.
+     */
+    getStaleKeys() {
+        const staleKeys = [];
+        for (const [key, entry] of this.cache.entries()) {
+            if (isStale(entry, this.ttlSeconds)) {
+                staleKeys.push(key);
+            }
+        }
+        return staleKeys;
+    }
+    /**
+     * Check for stale entries and refresh them.
+     */
+    async refreshStaleEntries() {
+        if (!this.fetchFunc) {
+            return;
+        }
+        const staleKeys = this.getStaleKeys();
+        if (staleKeys.length === 0) {
+            return;
+        }
+        for (const key of staleKeys) {
+            try {
+                const newValue = await this.fetchFunc(key);
+                this.set(key, newValue);
+                this._metrics.refreshes += 1;
+            }
+            catch (e) {
+                // Keep stale data on refresh failure
+                this._metrics.refreshErrors += 1;
+                console.warn(`Failed to refresh cache entry ${key}:`, e);
+            }
+        }
+    }
+}
+exports.Cache = Cache;

package/dist/utils/prompts_cache.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Prompt caching module for LangSmith SDK.
+ *
+ * Provides an LRU cache with background refresh for prompt caching.
+ * Uses stale-while-revalidate pattern for optimal performance.
+ *
+ * Works in all environments. File operations (dump/load) use helpers
+ * that are swapped for browser builds via package.json browser field.
+ */
+import type { PromptCommit } from "../schemas.js";
+/**
+ * A single cache entry with metadata for TTL tracking.
+ */
+export interface CacheEntry<T = unknown> {
+    value: T;
+    createdAt: number;
+}
+/**
+ * Cache performance metrics.
+ */
+export interface CacheMetrics {
+    hits: number;
+    misses: number;
+    refreshes: number;
+    refreshErrors: number;
+}
+/**
+ * Configuration options for Cache.
+ */
+export interface CacheConfig {
+    /** Maximum entries in cache (LRU eviction when exceeded). Default: 100 */
+    maxSize?: number;
+    /** Time in seconds before entry is stale. null = infinite TTL. Default: 3600 */
+    ttlSeconds?: number | null;
+    /** How often to check for stale entries in seconds. Default: 60 */
+    refreshIntervalSeconds?: number;
+    /** Callback to fetch fresh data for a cache key */
+    fetchFunc?: (key: string) => Promise<PromptCommit>;
+}
+/**
+ * LRU cache with background refresh for prompts.
+ *
+ * Features:
+ * - In-memory LRU cache with configurable max size
+ * - Background refresh using setInterval
+ * - Stale-while-revalidate: returns stale data while refresh happens
+ * - JSON dump/load for offline use
+ *
+ * @example
+ * ```typescript
+ * const cache = new Cache({
+ *   maxSize: 100,
+ *   ttlSeconds: 3600,
+ *   fetchFunc: async (key) => client.pullPromptCommit(key),
+ * });
+ *
+ * // Use the cache
+ * cache.set("my-prompt:latest", promptCommit);
+ * const cached = cache.get("my-prompt:latest");
+ *
+ * // Cleanup
+ * cache.stop();
+ * ```
+ */
+export declare class Cache {
+    private cache;
+    private maxSize;
+    private ttlSeconds;
+    private refreshIntervalSeconds;
+    private fetchFunc?;
+    private refreshTimer?;
+    private _metrics;
+    constructor(config?: CacheConfig);
+    /**
+     * Get cache performance metrics.
+     */
+    get metrics(): Readonly<CacheMetrics>;
+    /**
+     * Get total cache requests (hits + misses).
+     */
+    get totalRequests(): number;
+    /**
+     * Get cache hit rate (0.0 to 1.0).
+     */
+    get hitRate(): number;
+    /**
+     * Reset all metrics to zero.
+     */
+    resetMetrics(): void;
+    /**
+     * Get a value from cache.
+     *
+     * Returns the cached value or undefined if not found.
+     * Stale entries are still returned (background refresh handles updates).
+     */
+    get(key: string): PromptCommit | undefined;
+    /**
+     * Set a value in the cache.
+     */
+    set(key: string, value: PromptCommit): void;
+    /**
+     * Remove a specific entry from cache.
+     */
+    invalidate(key: string): void;
+    /**
+     * Clear all cache entries.
+     */
+    clear(): void;
+    /**
+     * Get the number of entries in the cache.
+     */
+    get size(): number;
+    /**
+     * Stop background refresh.
+     * Should be called when the client is being cleaned up.
+     */
+    stop(): void;
+    /**
+     * Dump cache contents to a JSON file for offline use.
+     */
+    dump(filePath: string): void;
+    /**
+     * Load cache contents from a JSON file.
+     *
+     * Loaded entries get a fresh TTL starting from load time.
+     *
+     * @returns Number of entries loaded.
+     */
+    load(filePath: string): number;
+    /**
+     * Start the background refresh loop.
+     */
+    private startRefreshLoop;
+    /**
+     * Get list of stale cache keys.
+     */
+    private getStaleKeys;
+    /**
+     * Check for stale entries and refresh them.
+     */
+    private refreshStaleEntries;
+}

package/dist/utils/prompts_cache.js

@@ -0,0 +1,288 @@
+/**
+ * Prompt caching module for LangSmith SDK.
+ *
+ * Provides an LRU cache with background refresh for prompt caching.
+ * Uses stale-while-revalidate pattern for optimal performance.
+ *
+ * Works in all environments. File operations (dump/load) use helpers
+ * that are swapped for browser builds via package.json browser field.
+ */
+import { dumpCache, loadCache } from "./prompts_cache_fs.js";
+/**
+ * Check if a cache entry is stale based on TTL.
+ */
+function isStale(entry, ttlSeconds) {
+    if (ttlSeconds === null) {
+        return false; // Infinite TTL, never stale
+    }
+    const ageMs = Date.now() - entry.createdAt;
+    return ageMs > ttlSeconds * 1000;
+}
+/**
+ * LRU cache with background refresh for prompts.
+ *
+ * Features:
+ * - In-memory LRU cache with configurable max size
+ * - Background refresh using setInterval
+ * - Stale-while-revalidate: returns stale data while refresh happens
+ * - JSON dump/load for offline use
+ *
+ * @example
+ * ```typescript
+ * const cache = new Cache({
+ *   maxSize: 100,
+ *   ttlSeconds: 3600,
+ *   fetchFunc: async (key) => client.pullPromptCommit(key),
+ * });
+ *
+ * // Use the cache
+ * cache.set("my-prompt:latest", promptCommit);
+ * const cached = cache.get("my-prompt:latest");
+ *
+ * // Cleanup
+ * cache.stop();
+ * ```
+ */
+export class Cache {
+    constructor(config = {}) {
+        Object.defineProperty(this, "cache", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "maxSize", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "ttlSeconds", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "refreshIntervalSeconds", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "fetchFunc", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "refreshTimer", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_metrics", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: {
+                hits: 0,
+                misses: 0,
+                refreshes: 0,
+                refreshErrors: 0,
+            }
+        });
+        this.maxSize = config.maxSize ?? 100;
+        this.ttlSeconds = config.ttlSeconds ?? 3600;
+        this.refreshIntervalSeconds = config.refreshIntervalSeconds ?? 60;
+        this.fetchFunc = config.fetchFunc;
+        // Start background refresh if fetch function provided and TTL is set
+        if (this.fetchFunc && this.ttlSeconds !== null) {
+            this.startRefreshLoop();
+        }
+    }
+    /**
+     * Get cache performance metrics.
+     */
+    get metrics() {
+        return { ...this._metrics };
+    }
+    /**
+     * Get total cache requests (hits + misses).
+     */
+    get totalRequests() {
+        return this._metrics.hits + this._metrics.misses;
+    }
+    /**
+     * Get cache hit rate (0.0 to 1.0).
+     */
+    get hitRate() {
+        const total = this.totalRequests;
+        return total > 0 ? this._metrics.hits / total : 0;
+    }
+    /**
+     * Reset all metrics to zero.
+     */
+    resetMetrics() {
+        this._metrics = {
+            hits: 0,
+            misses: 0,
+            refreshes: 0,
+            refreshErrors: 0,
+        };
+    }
+    /**
+     * Get a value from cache.
+     *
+     * Returns the cached value or undefined if not found.
+     * Stale entries are still returned (background refresh handles updates).
+     */
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            this._metrics.misses += 1;
+            return undefined;
+        }
+        // Move to end for LRU (delete and re-add)
+        this.cache.delete(key);
+        this.cache.set(key, entry);
+        this._metrics.hits += 1;
+        return entry.value;
+    }
+    /**
+     * Set a value in the cache.
+     */
+    set(key, value) {
+        // Check if we need to evict (and key is new)
+        if (!this.cache.has(key) && this.cache.size >= this.maxSize) {
+            // Evict oldest (first item in Map)
+            const oldestKey = this.cache.keys().next().value;
+            if (oldestKey !== undefined) {
+                this.cache.delete(oldestKey);
+            }
+        }
+        const entry = {
+            value,
+            createdAt: Date.now(),
+        };
+        // Delete first to ensure it's at the end
+        this.cache.delete(key);
+        this.cache.set(key, entry);
+    }
+    /**
+     * Remove a specific entry from cache.
+     */
+    invalidate(key) {
+        this.cache.delete(key);
+    }
+    /**
+     * Clear all cache entries.
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Get the number of entries in the cache.
+     */
+    get size() {
+        return this.cache.size;
+    }
+    /**
+     * Stop background refresh.
+     * Should be called when the client is being cleaned up.
+     */
+    stop() {
+        if (this.refreshTimer) {
+            clearInterval(this.refreshTimer);
+            this.refreshTimer = undefined;
+        }
+    }
+    /**
+     * Dump cache contents to a JSON file for offline use.
+     */
+    dump(filePath) {
+        const entries = {};
+        for (const [key, entry] of this.cache.entries()) {
+            entries[key] = entry.value;
+        }
+        dumpCache(filePath, entries);
+    }
+    /**
+     * Load cache contents from a JSON file.
+     *
+     * Loaded entries get a fresh TTL starting from load time.
+     *
+     * @returns Number of entries loaded.
+     */
+    load(filePath) {
+        const entries = loadCache(filePath);
+        if (!entries) {
+            return 0;
+        }
+        let loaded = 0;
+        const now = Date.now();
+        for (const [key, value] of Object.entries(entries)) {
+            if (this.cache.size >= this.maxSize) {
+                break;
+            }
+            const entry = {
+                value: value,
+                createdAt: now, // Fresh TTL from load time
+            };
+            this.cache.set(key, entry);
+            loaded += 1;
+        }
+        return loaded;
+    }
+    /**
+     * Start the background refresh loop.
+     */
+    startRefreshLoop() {
+        this.refreshTimer = setInterval(() => {
+            this.refreshStaleEntries().catch((e) => {
+                // Log but don't die - keep the refresh loop running
+                console.warn("Unexpected error in cache refresh loop:", e);
+            });
+        }, this.refreshIntervalSeconds * 1000);
+        // Don't block Node.js from exiting
+        if (this.refreshTimer.unref) {
+            this.refreshTimer.unref();
+        }
+    }
+    /**
+     * Get list of stale cache keys.
+     */
+    getStaleKeys() {
+        const staleKeys = [];
+        for (const [key, entry] of this.cache.entries()) {
+            if (isStale(entry, this.ttlSeconds)) {
+                staleKeys.push(key);
+            }
+        }
+        return staleKeys;
+    }
+    /**
+     * Check for stale entries and refresh them.
+     */
+    async refreshStaleEntries() {
+        if (!this.fetchFunc) {
+            return;
+        }
+        const staleKeys = this.getStaleKeys();
+        if (staleKeys.length === 0) {
+            return;
+        }
+        for (const key of staleKeys) {
+            try {
+                const newValue = await this.fetchFunc(key);
+                this.set(key, newValue);
+                this._metrics.refreshes += 1;
+            }
+            catch (e) {
+                // Keep stale data on refresh failure
+                this._metrics.refreshErrors += 1;
+                console.warn(`Failed to refresh cache entry ${key}:`, e);
+            }
+        }
+    }
+}

package/dist/utils/prompts_cache_fs.browser.cjs

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * File system operations for prompt cache (Browser version).
+ *
+ * This stub is used in browser builds via the package.json browser field.
+ * File operations are not supported in browser environments.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dumpCache = dumpCache;
+exports.loadCache = loadCache;
+/**
+ * Dump cache entries to a JSON file.
+ * @throws Error - Always throws in browser environments.
+ */
+function dumpCache(_filePath, _entries) {
+    throw new Error("dump() is not supported in browser environments.");
+}
+/**
+ * Load cache entries from a JSON file.
+ * @throws Error - Always throws in browser environments.
+ */
+function loadCache(_filePath) {
+    throw new Error("load() is not supported in browser environments.");
+}

package/dist/utils/prompts_cache_fs.browser.d.ts

@@ -0,0 +1,16 @@
+/**
+ * File system operations for prompt cache (Browser version).
+ *
+ * This stub is used in browser builds via the package.json browser field.
+ * File operations are not supported in browser environments.
+ */
+/**
+ * Dump cache entries to a JSON file.
+ * @throws Error - Always throws in browser environments.
+ */
+export declare function dumpCache(_filePath: string, _entries: Record<string, unknown>): void;
+/**
+ * Load cache entries from a JSON file.
+ * @throws Error - Always throws in browser environments.
+ */
+export declare function loadCache(_filePath: string): Record<string, unknown> | null;

package/dist/utils/prompts_cache_fs.browser.js

@@ -0,0 +1,20 @@
+/**
+ * File system operations for prompt cache (Browser version).
+ *
+ * This stub is used in browser builds via the package.json browser field.
+ * File operations are not supported in browser environments.
+ */
+/**
+ * Dump cache entries to a JSON file.
+ * @throws Error - Always throws in browser environments.
+ */
+export function dumpCache(_filePath, _entries) {
+    throw new Error("dump() is not supported in browser environments.");
+}
+/**
+ * Load cache entries from a JSON file.
+ * @throws Error - Always throws in browser environments.
+ */
+export function loadCache(_filePath) {
+    throw new Error("load() is not supported in browser environments.");
+}

package/dist/utils/prompts_cache_fs.cjs

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * File system operations for prompt cache (Node.js version).
+ *
+ * This file is swapped with prompts_cache_fs.browser.ts for browser builds
+ * via the package.json browser field.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dumpCache = dumpCache;
+exports.loadCache = loadCache;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/**
+ * Dump cache entries to a JSON file.
+ */
+function dumpCache(filePath, entries) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    const data = { entries };
+    // Atomic write: write to temp file then rename
+    const tempPath = `${filePath}.tmp`;
+    try {
+        fs.writeFileSync(tempPath, JSON.stringify(data, null, 2));
+        fs.renameSync(tempPath, filePath);
+    }
+    catch (e) {
+        // Clean up temp file on failure
+        if (fs.existsSync(tempPath)) {
+            fs.unlinkSync(tempPath);
+        }
+        throw e;
+    }
+}
+/**
+ * Load cache entries from a JSON file.
+ *
+ * @returns The entries object, or null if file doesn't exist or is invalid.
+ */
+function loadCache(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const content = fs.readFileSync(filePath, "utf-8");
+        const data = JSON.parse(content);
+        return data.entries ?? null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/utils/prompts_cache_fs.d.ts

@@ -0,0 +1,16 @@
+/**
+ * File system operations for prompt cache (Node.js version).
+ *
+ * This file is swapped with prompts_cache_fs.browser.ts for browser builds
+ * via the package.json browser field.
+ */
+/**
+ * Dump cache entries to a JSON file.
+ */
+export declare function dumpCache(filePath: string, entries: Record<string, unknown>): void;
+/**
+ * Load cache entries from a JSON file.
+ *
+ * @returns The entries object, or null if file doesn't exist or is invalid.
+ */
+export declare function loadCache(filePath: string): Record<string, unknown> | null;

package/dist/utils/prompts_cache_fs.js

@@ -0,0 +1,49 @@
+/**
+ * File system operations for prompt cache (Node.js version).
+ *
+ * This file is swapped with prompts_cache_fs.browser.ts for browser builds
+ * via the package.json browser field.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+/**
+ * Dump cache entries to a JSON file.
+ */
+export function dumpCache(filePath, entries) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    const data = { entries };
+    // Atomic write: write to temp file then rename
+    const tempPath = `${filePath}.tmp`;
+    try {
+        fs.writeFileSync(tempPath, JSON.stringify(data, null, 2));
+        fs.renameSync(tempPath, filePath);
+    }
+    catch (e) {
+        // Clean up temp file on failure
+        if (fs.existsSync(tempPath)) {
+            fs.unlinkSync(tempPath);
+        }
+        throw e;
+    }
+}
+/**
+ * Load cache entries from a JSON file.
+ *
+ * @returns The entries object, or null if file doesn't exist or is invalid.
+ */
+export function loadCache(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const content = fs.readFileSync(filePath, "utf-8");
+        const data = JSON.parse(content);
+        return data.entries ?? null;
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "langsmith",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "Client library to connect to the LangSmith Observability and Evaluation Platform.",
   "packageManager": "yarn@1.22.19",
   "files": [
@@ -401,5 +401,8 @@
       "require": "./experimental/vercel.cjs"
     },
     "./package.json": "./package.json"
+  },
+  "browser": {
+    "./dist/utils/prompts_cache_fs.js": "./dist/utils/prompts_cache_fs.browser.js"
   }
 }