langsmith 0.4.2 → 0.4.3

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, "_promptCache", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(this, "multipartStreamingDisabled", {
             enumerable: true,
             configurable: true,
@@ -481,6 +488,27 @@ class Client {
         }
         // Cache metadata env vars once during construction to avoid repeatedly scanning process.env
         this.cachedLSEnvVarsForMetadata = (0, env_js_1.getLangSmithEnvVarsMetadata)();
+        // Initialize prompt cache
+        const cacheEnabled = config.promptCacheEnabled ??
+            (0, env_js_1.getLangSmithEnvironmentVariable)("PROMPT_CACHE_ENABLED") === "true";
+        if (cacheEnabled) {
+            this._promptCache = new prompts_cache_js_1.PromptCache({
+                maxSize: config.promptCacheMaxSize ??
+                    parseInt((0, env_js_1.getLangSmithEnvironmentVariable)("PROMPT_CACHE_MAX_SIZE") ?? "100", 10),
+                ttlSeconds: config.promptCacheTtlSeconds ??
+                    parseFloat((0, env_js_1.getLangSmithEnvironmentVariable)("PROMPT_CACHE_TTL_SECONDS") ??
+                        "3600"),
+                refreshIntervalSeconds: config.promptCacheRefreshIntervalSeconds ??
+                    parseFloat((0, env_js_1.getLangSmithEnvironmentVariable)("PROMPT_CACHE_REFRESH_INTERVAL_SECONDS") ?? "60"),
+                fetchFunc: this._makeFetchPromptFunc(),
+            });
+            // Load from file if path provided
+            const cachePath = config.promptCachePath ??
+                (0, env_js_1.getLangSmithEnvironmentVariable)("PROMPT_CACHE_PATH");
+            if (cachePath) {
+                this._promptCache.load(cachePath);
+            }
+        }
     }
     static getDefaultClientConfig() {
         const apiKey = (0, env_js_1.getLangSmithEnvironmentVariable)("API_KEY");
@@ -3784,7 +3812,29 @@ 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}`;
+    }
+    /**
+     * Create a fetch function for the prompt cache to use for background refresh.
+     */
+    _makeFetchPromptFunc() {
+        return async (key) => {
+            // Parse the cache key back to identifier and options
+            const includeModel = key.endsWith(":with_model");
+            const identifier = includeModel ? key.slice(0, -11) : key; // Remove ":with_model"
+            return this._fetchPromptFromApi(identifier, { includeModel });
+        };
+    }
+    /**
+     * 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 +3855,22 @@ class Client {
             examples: result.examples,
         };
     }
+    async pullPromptCommit(promptIdentifier, options) {
+        // Check cache first if not skipped
+        if (!options?.skipCache && this._promptCache) {
+            const cacheKey = this._getPromptCacheKey(promptIdentifier, options?.includeModel);
+            const cached = this._promptCache.get(cacheKey);
+            if (cached) {
+                return cached;
+            }
+            // Cache miss - fetch from API and cache it
+            const result = await this._fetchPromptFromApi(promptIdentifier, options);
+            this._promptCache.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 +3879,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 +3994,22 @@ class Client {
             throw new Error(`Invalid public ${kind} URL or token: ${urlOrToken}`);
         }
     }
+    /**
+     * Get the prompt cache instance, if caching is enabled.
+     * Useful for accessing cache metrics or manually managing the cache.
+     */
+    get promptCache() {
+        return this._promptCache;
+    }
+    /**
+     * Cleanup resources held by the client.
+     * Stops the prompt cache's background refresh timer.
+     */
+    cleanup() {
+        if (this._promptCache) {
+            this._promptCache.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 { PromptCache } from "./utils/prompts_cache.js";
 export interface ClientConfig {
     apiUrl?: string;
     apiKey?: string;
@@ -49,6 +50,29 @@ export interface ClientConfig {
      * Custom fetch implementation. Useful for testing.
      */
     fetchImplementation?: typeof fetch;
+    /**
+     * Whether to enable prompt caching. Defaults to false.
+     */
+    promptCacheEnabled?: boolean;
+    /**
+     * Maximum number of prompts to cache. Defaults to 100.
+     */
+    promptCacheMaxSize?: number;
+    /**
+     * Time-to-live for cached prompts in seconds. After this time, cached prompts
+     * are considered stale and will be refreshed in the background.
+     * Set to null for infinite TTL (offline mode). Defaults to 3600 (1 hour).
+     */
+    promptCacheTtlSeconds?: number | null;
+    /**
+     * How often to check for stale cache entries in seconds. Defaults to 60.
+     */
+    promptCacheRefreshIntervalSeconds?: number;
+    /**
+     * Path to a JSON file to load cached prompts from on initialization.
+     * Useful for offline mode.
+     */
+    promptCachePath?: string;
 }
 /**
  * Represents the parameters for listing runs (spans) from the Langsmith server.
@@ -351,6 +375,7 @@ export declare class Client implements LangSmithTracingClientInterface {
     private langSmithToOTELTranslator?;
     private fetchImplementation?;
     private cachedLSEnvVarsForMetadata?;
+    private _promptCache?;
     private get _fetch();
     private multipartStreamingDisabled;
     private _multipartDisabled;
@@ -995,8 +1020,22 @@ 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;
+    /**
+     * Create a fetch function for the prompt cache to use for background refresh.
+     */
+    private _makeFetchPromptFunc;
+    /**
+     * 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 +1044,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 +1070,16 @@ export declare class Client implements LangSmithTracingClientInterface {
         datasetName?: string;
     }): Promise<void>;
     private parseTokenOrUrl;
+    /**
+     * Get the prompt cache instance, if caching is enabled.
+     * Useful for accessing cache metrics or manually managing the cache.
+     */
+    get promptCache(): PromptCache | undefined;
+    /**
+     * Cleanup resources held by the client.
+     * Stops the prompt 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 { PromptCache } 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, "_promptCache", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(this, "multipartStreamingDisabled", {
             enumerable: true,
             configurable: true,
@@ -443,6 +450,27 @@ export class Client {
         }
         // Cache metadata env vars once during construction to avoid repeatedly scanning process.env
         this.cachedLSEnvVarsForMetadata = getLangSmithEnvVarsMetadata();
+        // Initialize prompt cache
+        const cacheEnabled = config.promptCacheEnabled ??
+            getLangSmithEnvironmentVariable("PROMPT_CACHE_ENABLED") === "true";
+        if (cacheEnabled) {
+            this._promptCache = new PromptCache({
+                maxSize: config.promptCacheMaxSize ??
+                    parseInt(getLangSmithEnvironmentVariable("PROMPT_CACHE_MAX_SIZE") ?? "100", 10),
+                ttlSeconds: config.promptCacheTtlSeconds ??
+                    parseFloat(getLangSmithEnvironmentVariable("PROMPT_CACHE_TTL_SECONDS") ??
+                        "3600"),
+                refreshIntervalSeconds: config.promptCacheRefreshIntervalSeconds ??
+                    parseFloat(getLangSmithEnvironmentVariable("PROMPT_CACHE_REFRESH_INTERVAL_SECONDS") ?? "60"),
+                fetchFunc: this._makeFetchPromptFunc(),
+            });
+            // Load from file if path provided
+            const cachePath = config.promptCachePath ??
+                getLangSmithEnvironmentVariable("PROMPT_CACHE_PATH");
+            if (cachePath) {
+                this._promptCache.load(cachePath);
+            }
+        }
     }
     static getDefaultClientConfig() {
         const apiKey = getLangSmithEnvironmentVariable("API_KEY");
@@ -3746,7 +3774,29 @@ 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}`;
+    }
+    /**
+     * Create a fetch function for the prompt cache to use for background refresh.
+     */
+    _makeFetchPromptFunc() {
+        return async (key) => {
+            // Parse the cache key back to identifier and options
+            const includeModel = key.endsWith(":with_model");
+            const identifier = includeModel ? key.slice(0, -11) : key; // Remove ":with_model"
+            return this._fetchPromptFromApi(identifier, { includeModel });
+        };
+    }
+    /**
+     * 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 +3817,22 @@ export class Client {
             examples: result.examples,
         };
     }
+    async pullPromptCommit(promptIdentifier, options) {
+        // Check cache first if not skipped
+        if (!options?.skipCache && this._promptCache) {
+            const cacheKey = this._getPromptCacheKey(promptIdentifier, options?.includeModel);
+            const cached = this._promptCache.get(cacheKey);
+            if (cached) {
+                return cached;
+            }
+            // Cache miss - fetch from API and cache it
+            const result = await this._fetchPromptFromApi(promptIdentifier, options);
+            this._promptCache.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 +3841,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 +3956,22 @@ export class Client {
             throw new Error(`Invalid public ${kind} URL or token: ${urlOrToken}`);
         }
     }
+    /**
+     * Get the prompt cache instance, if caching is enabled.
+     * Useful for accessing cache metrics or manually managing the cache.
+     */
+    get promptCache() {
+        return this._promptCache;
+    }
+    /**
+     * Cleanup resources held by the client.
+     * Stops the prompt cache's background refresh timer.
+     */
+    cleanup() {
+        if (this._promptCache) {
+            this._promptCache.stop();
+        }
+    }
     /**
      * Awaits all pending trace batches. Useful for environments where
      * you need to be sure that all tracing requests finish before execution ends,