langsmith 0.4.3 → 0.4.5

package/dist/client.cjs

@@ -411,7 +411,7 @@ class Client {
             writable: true,
             value: void 0
         });
-        Object.defineProperty(this, "_promptCache", {
+        Object.defineProperty(this, "_cache", {
             enumerable: true,
             configurable: true,
             writable: true,
@@ -488,26 +488,15 @@ 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);
-            }
+        // 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() {
@@ -3820,17 +3809,6 @@ class Client {
         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).
      */
@@ -3857,15 +3835,15 @@ class Client {
     }
     async pullPromptCommit(promptIdentifier, options) {
         // Check cache first if not skipped
-        if (!options?.skipCache && this._promptCache) {
+        if (!options?.skipCache && this._cache) {
             const cacheKey = this._getPromptCacheKey(promptIdentifier, options?.includeModel);
-            const cached = this._promptCache.get(cacheKey);
+            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._promptCache.set(cacheKey, result);
+            this._cache.set(cacheKey, result);
             return result;
         }
         // No cache or skip cache - fetch directly
@@ -3995,19 +3973,19 @@ class Client {
         }
     }
     /**
-     * Get the prompt cache instance, if caching is enabled.
+     * Get the cache instance, if caching is enabled.
      * Useful for accessing cache metrics or manually managing the cache.
      */
-    get promptCache() {
-        return this._promptCache;
+    get cache() {
+        return this._cache;
     }
     /**
      * Cleanup resources held by the client.
-     * Stops the prompt cache's background refresh timer.
+     * Stops the cache's background refresh timer.
      */
     cleanup() {
-        if (this._promptCache) {
-            this._promptCache.stop();
+        if (this._cache) {
+            this._cache.stop();
         }
     }
     /**

package/dist/client.d.ts

@@ -2,7 +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";
+import { Cache } from "./utils/prompts_cache.js";
 export interface ClientConfig {
     apiUrl?: string;
     apiKey?: string;
@@ -51,28 +51,27 @@ export interface ClientConfig {
      */
     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.
+     * 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 });
+     * ```
      */
-    promptCachePath?: string;
+    cache?: Cache | boolean;
 }
 /**
  * Represents the parameters for listing runs (spans) from the Langsmith server.
@@ -375,7 +374,7 @@ export declare class Client implements LangSmithTracingClientInterface {
     private langSmithToOTELTranslator?;
     private fetchImplementation?;
     private cachedLSEnvVarsForMetadata?;
-    private _promptCache?;
+    private _cache?;
     private get _fetch();
     private multipartStreamingDisabled;
     private _multipartDisabled;
@@ -1025,10 +1024,6 @@ export declare class Client implements LangSmithTracingClientInterface {
      * 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).
      */
@@ -1071,13 +1066,13 @@ export declare class Client implements LangSmithTracingClientInterface {
     }): Promise<void>;
     private parseTokenOrUrl;
     /**
-     * Get the prompt cache instance, if caching is enabled.
+     * Get the cache instance, if caching is enabled.
      * Useful for accessing cache metrics or manually managing the cache.
      */
-    get promptCache(): PromptCache | undefined;
+    get cache(): Cache | undefined;
     /**
      * Cleanup resources held by the client.
-     * Stops the prompt cache's background refresh timer.
+     * Stops the cache's background refresh timer.
      */
     cleanup(): void;
     /**

package/dist/client.js

@@ -9,7 +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 { 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) {
@@ -373,7 +373,7 @@ export class Client {
             writable: true,
             value: void 0
         });
-        Object.defineProperty(this, "_promptCache", {
+        Object.defineProperty(this, "_cache", {
             enumerable: true,
             configurable: true,
             writable: true,
@@ -450,26 +450,15 @@ 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);
-            }
+        // 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() {
@@ -3782,17 +3771,6 @@ export class Client {
         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).
      */
@@ -3819,15 +3797,15 @@ export class Client {
     }
     async pullPromptCommit(promptIdentifier, options) {
         // Check cache first if not skipped
-        if (!options?.skipCache && this._promptCache) {
+        if (!options?.skipCache && this._cache) {
             const cacheKey = this._getPromptCacheKey(promptIdentifier, options?.includeModel);
-            const cached = this._promptCache.get(cacheKey);
+            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._promptCache.set(cacheKey, result);
+            this._cache.set(cacheKey, result);
             return result;
         }
         // No cache or skip cache - fetch directly
@@ -3957,19 +3935,19 @@ export class Client {
         }
     }
     /**
-     * Get the prompt cache instance, if caching is enabled.
+     * Get the cache instance, if caching is enabled.
      * Useful for accessing cache metrics or manually managing the cache.
      */
-    get promptCache() {
-        return this._promptCache;
+    get cache() {
+        return this._cache;
     }
     /**
      * Cleanup resources held by the client.
-     * Stops the prompt cache's background refresh timer.
+     * Stops the cache's background refresh timer.
      */
     cleanup() {
-        if (this._promptCache) {
-            this._promptCache.stop();
+        if (this._cache) {
+            this._cache.stop();
         }
     }
     /**

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.3";
+exports.__version__ = "0.4.5";

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.3";
+export { Cache, type CacheConfig, type CacheMetrics, } from "./utils/prompts_cache.js";
+export declare const __version__ = "0.4.5";

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.3";
+export const __version__ = "0.4.5";

package/dist/run_trees.cjs

@@ -616,15 +616,14 @@ class RunTree {
                 }
             }
         }
-        // Remap IDs for the replica using uuid7Deterministic
-        // This ensures consistency across runs in the same replica while
-        // preserving UUID7 properties (time-ordering, monotonicity)
+        // Remap IDs for the replica using uuid5 (deterministic)
+        // This ensures consistency across runs in the same replica
         const oldId = baseRun.id;
-        const newId = (0, _uuid_js_1.uuid7Deterministic)(oldId, projectName);
+        const newId = (0, uuid_1.v5)(`${oldId}:${projectName}`, UUID_NAMESPACE_DNS);
         // Remap trace_id
         let newTraceId;
         if (baseRun.trace_id) {
-            newTraceId = (0, _uuid_js_1.uuid7Deterministic)(baseRun.trace_id, projectName);
+            newTraceId = (0, uuid_1.v5)(`${baseRun.trace_id}:${projectName}`, UUID_NAMESPACE_DNS);
         }
         else {
             newTraceId = newId;
@@ -632,7 +631,7 @@ class RunTree {
         // Remap parent_run_id
         let newParentId;
         if (baseRun.parent_run_id) {
-            newParentId = (0, _uuid_js_1.uuid7Deterministic)(baseRun.parent_run_id, projectName);
+            newParentId = (0, uuid_1.v5)(`${baseRun.parent_run_id}:${projectName}`, UUID_NAMESPACE_DNS);
         }
         // Remap dotted_order segments
         let newDottedOrder;
@@ -641,7 +640,7 @@ class RunTree {
             const remappedSegs = segs.map((seg) => {
                 // Extract the UUID from the segment (last TIMESTAMP_LENGTH characters)
                 const segId = seg.slice(-TIMESTAMP_LENGTH);
-                const remappedId = (0, _uuid_js_1.uuid7Deterministic)(segId, projectName);
+                const remappedId = (0, uuid_1.v5)(`${segId}:${projectName}`, UUID_NAMESPACE_DNS);
                 // Replace the UUID part while keeping the timestamp prefix
                 return seg.slice(0, -TIMESTAMP_LENGTH) + remappedId;
             });

package/dist/run_trees.js

@@ -7,7 +7,7 @@ import { getEnvironmentVariable, getRuntimeEnvironment, } from "./utils/env.js";
 import { getDefaultProjectName } from "./utils/project.js";
 import { getLangSmithEnvironmentVariable } from "./utils/env.js";
 import { warnOnce } from "./utils/warn.js";
-import { uuid7FromTime, uuid7Deterministic } from "./utils/_uuid.js";
+import { uuid7FromTime } from "./utils/_uuid.js";
 import { v5 as uuidv5 } from "uuid";
 const TIMESTAMP_LENGTH = 36;
 // DNS namespace for UUID v5 (same as Python's uuid.NAMESPACE_DNS)
@@ -610,15 +610,14 @@ export class RunTree {
                 }
             }
         }
-        // Remap IDs for the replica using uuid7Deterministic
-        // This ensures consistency across runs in the same replica while
-        // preserving UUID7 properties (time-ordering, monotonicity)
+        // Remap IDs for the replica using uuid5 (deterministic)
+        // This ensures consistency across runs in the same replica
         const oldId = baseRun.id;
-        const newId = uuid7Deterministic(oldId, projectName);
+        const newId = uuidv5(`${oldId}:${projectName}`, UUID_NAMESPACE_DNS);
         // Remap trace_id
         let newTraceId;
         if (baseRun.trace_id) {
-            newTraceId = uuid7Deterministic(baseRun.trace_id, projectName);
+            newTraceId = uuidv5(`${baseRun.trace_id}:${projectName}`, UUID_NAMESPACE_DNS);
         }
         else {
             newTraceId = newId;
@@ -626,7 +625,7 @@ export class RunTree {
         // Remap parent_run_id
         let newParentId;
         if (baseRun.parent_run_id) {
-            newParentId = uuid7Deterministic(baseRun.parent_run_id, projectName);
+            newParentId = uuidv5(`${baseRun.parent_run_id}:${projectName}`, UUID_NAMESPACE_DNS);
         }
         // Remap dotted_order segments
         let newDottedOrder;
@@ -635,7 +634,7 @@ export class RunTree {
             const remappedSegs = segs.map((seg) => {
                 // Extract the UUID from the segment (last TIMESTAMP_LENGTH characters)
                 const segId = seg.slice(-TIMESTAMP_LENGTH);
-                const remappedId = uuid7Deterministic(segId, projectName);
+                const remappedId = uuidv5(`${segId}:${projectName}`, UUID_NAMESPACE_DNS);
                 // Replace the UUID part while keeping the timestamp prefix
                 return seg.slice(0, -TIMESTAMP_LENGTH) + remappedId;
             });

package/dist/utils/_uuid.cjs

@@ -4,10 +4,8 @@ exports.assertUuid = assertUuid;
 exports.uuid7FromTime = uuid7FromTime;
 exports.getUuidVersion = getUuidVersion;
 exports.warnIfNotUuidV7 = warnIfNotUuidV7;
-exports.uuid7Deterministic = uuid7Deterministic;
 // Relaxed UUID validation regex (allows any valid UUID format including nil UUIDs)
 const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-const crypto_1 = require("crypto");
 const uuid_1 = require("uuid");
 const warn_js_1 = require("./warn.cjs");
 let UUID7_WARNING_EMITTED = false;
@@ -66,88 +64,3 @@ function warnIfNotUuidV7(uuidStr, _idType) {
             `Future versions will require UUID v7.`);
     }
 }
-/**
- * Convert a UUID string to its 16-byte representation.
- * @param uuidStr - The UUID string (with or without dashes)
- * @returns A Buffer containing the 16 bytes of the UUID
- */
-function uuidToBytes(uuidStr) {
-    const hex = uuidStr.replace(/-/g, "");
-    return Buffer.from(hex, "hex");
-}
-/**
- * Convert 16 bytes to a UUID string.
- * @param bytes - A Buffer containing 16 bytes
- * @returns A UUID string in standard format
- */
-function bytesToUuid(bytes) {
-    const hex = bytes.toString("hex");
-    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
-}
-/**
- * Generate a deterministic UUID v7 derived from an original UUID and a key.
- *
- * This function creates a new UUID that:
- * - Preserves the timestamp from the original UUID if it's UUID v7
- * - Uses current time if the original is not UUID v7
- * - Uses deterministic "random" bits derived from hashing the original + key
- * - Is valid UUID v7 format
- *
- * This is used for creating replica IDs that maintain time-ordering properties
- * while being deterministic across distributed systems.
- *
- * @param originalId - The source UUID string (ideally UUID v7 to preserve timestamp)
- * @param key - A string key used for deterministic derivation (e.g., project name)
- * @returns A new UUID v7 string with preserved timestamp (if original is v7) and
- *          deterministic random bits
- *
- * @example
- * ```typescript
- * const original = uuidv7();
- * const replicaId = uuid7Deterministic(original, "replica-project");
- * // Same inputs always produce same output
- * assert(uuid7Deterministic(original, "replica-project") === replicaId);
- * ```
- */
-function uuid7Deterministic(originalId, key) {
-    // Generate deterministic bytes from hash of original + key
-    const hashInput = `${originalId}:${key}`;
-    const h = (0, crypto_1.createHash)("sha256").update(hashInput).digest();
-    // Build new UUID7:
-    // UUID7 structure (RFC 9562):
-    // [0-5]  48 bits: unix_ts_ms (timestamp in milliseconds)
-    // [6]    4 bits: version (0111 = 7) + 4 bits rand_a
-    // [7]    8 bits: rand_a (continued)
-    // [8]    2 bits: variant (10) + 6 bits rand_b
-    // [9-15] 56 bits: rand_b (continued)
-    const b = Buffer.alloc(16);
-    // Check if original is UUID v7 - if so, preserve its timestamp
-    // If not, use current time to ensure the derived UUID has a valid timestamp
-    const version = getUuidVersion(originalId);
-    if (version === 7) {
-        // Preserve timestamp from original UUID7 (bytes 0-5)
-        const originalBytes = uuidToBytes(originalId);
-        originalBytes.copy(b, 0, 0, 6);
-    }
-    else {
-        // Generate fresh timestamp for non-UUID7 inputs
-        // This matches the uuid npm package's v7 implementation:
-        // https://github.com/uuidjs/uuid/blob/main/src/v7.ts
-        const msecs = Date.now();
-        b[0] = (msecs / 0x10000000000) & 0xff;
-        b[1] = (msecs / 0x100000000) & 0xff;
-        b[2] = (msecs / 0x1000000) & 0xff;
-        b[3] = (msecs / 0x10000) & 0xff;
-        b[4] = (msecs / 0x100) & 0xff;
-        b[5] = msecs & 0xff;
-    }
-    // Set version 7 (0111) in high nibble + 4 bits from hash
-    b[6] = 0x70 | (h[0] & 0x0f);
-    // rand_a continued (8 bits from hash)
-    b[7] = h[1];
-    // Set variant (10) in high 2 bits + 6 bits from hash
-    b[8] = 0x80 | (h[2] & 0x3f);
-    // rand_b (56 bits = 7 bytes from hash)
-    h.copy(b, 9, 3, 10);
-    return bytesToUuid(b);
-}

package/dist/utils/_uuid.d.ts

@@ -19,29 +19,3 @@ export declare function getUuidVersion(uuidStr: string): number | null;
  * @param idType - The type of ID (e.g., "run_id", "trace_id") for the warning message
  */
 export declare function warnIfNotUuidV7(uuidStr: string, _idType: string): void;
-/**
- * Generate a deterministic UUID v7 derived from an original UUID and a key.
- *
- * This function creates a new UUID that:
- * - Preserves the timestamp from the original UUID if it's UUID v7
- * - Uses current time if the original is not UUID v7
- * - Uses deterministic "random" bits derived from hashing the original + key
- * - Is valid UUID v7 format
- *
- * This is used for creating replica IDs that maintain time-ordering properties
- * while being deterministic across distributed systems.
- *
- * @param originalId - The source UUID string (ideally UUID v7 to preserve timestamp)
- * @param key - A string key used for deterministic derivation (e.g., project name)
- * @returns A new UUID v7 string with preserved timestamp (if original is v7) and
- *          deterministic random bits
- *
- * @example
- * ```typescript
- * const original = uuidv7();
- * const replicaId = uuid7Deterministic(original, "replica-project");
- * // Same inputs always produce same output
- * assert(uuid7Deterministic(original, "replica-project") === replicaId);
- * ```
- */
-export declare function uuid7Deterministic(originalId: string, key: string): string;

package/dist/utils/_uuid.js

@@ -1,6 +1,5 @@
 // Relaxed UUID validation regex (allows any valid UUID format including nil UUIDs)
 const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-import { createHash } from "crypto";
 import { v7 as uuidv7 } from "uuid";
 import { warnOnce } from "./warn.js";
 let UUID7_WARNING_EMITTED = false;
@@ -59,88 +58,3 @@ export function warnIfNotUuidV7(uuidStr, _idType) {
             `Future versions will require UUID v7.`);
     }
 }
-/**
- * Convert a UUID string to its 16-byte representation.
- * @param uuidStr - The UUID string (with or without dashes)
- * @returns A Buffer containing the 16 bytes of the UUID
- */
-function uuidToBytes(uuidStr) {
-    const hex = uuidStr.replace(/-/g, "");
-    return Buffer.from(hex, "hex");
-}
-/**
- * Convert 16 bytes to a UUID string.
- * @param bytes - A Buffer containing 16 bytes
- * @returns A UUID string in standard format
- */
-function bytesToUuid(bytes) {
-    const hex = bytes.toString("hex");
-    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
-}
-/**
- * Generate a deterministic UUID v7 derived from an original UUID and a key.
- *
- * This function creates a new UUID that:
- * - Preserves the timestamp from the original UUID if it's UUID v7
- * - Uses current time if the original is not UUID v7
- * - Uses deterministic "random" bits derived from hashing the original + key
- * - Is valid UUID v7 format
- *
- * This is used for creating replica IDs that maintain time-ordering properties
- * while being deterministic across distributed systems.
- *
- * @param originalId - The source UUID string (ideally UUID v7 to preserve timestamp)
- * @param key - A string key used for deterministic derivation (e.g., project name)
- * @returns A new UUID v7 string with preserved timestamp (if original is v7) and
- *          deterministic random bits
- *
- * @example
- * ```typescript
- * const original = uuidv7();
- * const replicaId = uuid7Deterministic(original, "replica-project");
- * // Same inputs always produce same output
- * assert(uuid7Deterministic(original, "replica-project") === replicaId);
- * ```
- */
-export function uuid7Deterministic(originalId, key) {
-    // Generate deterministic bytes from hash of original + key
-    const hashInput = `${originalId}:${key}`;
-    const h = createHash("sha256").update(hashInput).digest();
-    // Build new UUID7:
-    // UUID7 structure (RFC 9562):
-    // [0-5]  48 bits: unix_ts_ms (timestamp in milliseconds)
-    // [6]    4 bits: version (0111 = 7) + 4 bits rand_a
-    // [7]    8 bits: rand_a (continued)
-    // [8]    2 bits: variant (10) + 6 bits rand_b
-    // [9-15] 56 bits: rand_b (continued)
-    const b = Buffer.alloc(16);
-    // Check if original is UUID v7 - if so, preserve its timestamp
-    // If not, use current time to ensure the derived UUID has a valid timestamp
-    const version = getUuidVersion(originalId);
-    if (version === 7) {
-        // Preserve timestamp from original UUID7 (bytes 0-5)
-        const originalBytes = uuidToBytes(originalId);
-        originalBytes.copy(b, 0, 0, 6);
-    }
-    else {
-        // Generate fresh timestamp for non-UUID7 inputs
-        // This matches the uuid npm package's v7 implementation:
-        // https://github.com/uuidjs/uuid/blob/main/src/v7.ts
-        const msecs = Date.now();
-        b[0] = (msecs / 0x10000000000) & 0xff;
-        b[1] = (msecs / 0x100000000) & 0xff;
-        b[2] = (msecs / 0x1000000) & 0xff;
-        b[3] = (msecs / 0x10000) & 0xff;
-        b[4] = (msecs / 0x100) & 0xff;
-        b[5] = msecs & 0xff;
-    }
-    // Set version 7 (0111) in high nibble + 4 bits from hash
-    b[6] = 0x70 | (h[0] & 0x0f);
-    // rand_a continued (8 bits from hash)
-    b[7] = h[1];
-    // Set variant (10) in high 2 bits + 6 bits from hash
-    b[8] = 0x80 | (h[2] & 0x3f);
-    // rand_b (56 bits = 7 bytes from hash)
-    h.copy(b, 9, 3, 10);
-    return bytesToUuid(b);
-}

package/dist/utils/prompts_cache.cjs

@@ -4,44 +4,13 @@
  *
  * 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.
  */
-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.PromptCache = void 0;
-const fs = __importStar(require("node:fs"));
-const path = __importStar(require("node:path"));
+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.
  */
@@ -63,7 +32,7 @@ function isStale(entry, ttlSeconds) {
  *
  * @example
  * ```typescript
- * const cache = new PromptCache({
+ * const cache = new Cache({
  *   maxSize: 100,
  *   ttlSeconds: 3600,
  *   fetchFunc: async (key) => client.pullPromptCommit(key),
@@ -77,7 +46,7 @@ function isStale(entry, ttlSeconds) {
  * cache.stop();
  * ```
  */
-class PromptCache {
+class Cache {
     constructor(config = {}) {
         Object.defineProperty(this, "cache", {
             enumerable: true,
@@ -235,28 +204,11 @@ class PromptCache {
      * Dump cache contents to a JSON file for offline use.
      */
     dump(filePath) {
-        const dir = path.dirname(filePath);
-        if (!fs.existsSync(dir)) {
-            fs.mkdirSync(dir, { recursive: true });
-        }
         const entries = {};
         for (const [key, entry] of this.cache.entries()) {
             entries[key] = entry.value;
         }
-        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;
-        }
+        (0, prompts_cache_fs_js_1.dumpCache)(filePath, entries);
     }
     /**
      * Load cache contents from a JSON file.
@@ -266,18 +218,10 @@ class PromptCache {
      * @returns Number of entries loaded.
      */
     load(filePath) {
-        if (!fs.existsSync(filePath)) {
-            return 0;
-        }
-        let data;
-        try {
-            const content = fs.readFileSync(filePath, "utf-8");
-            data = JSON.parse(content);
-        }
-        catch {
+        const entries = (0, prompts_cache_fs_js_1.loadCache)(filePath);
+        if (!entries) {
             return 0;
         }
-        const entries = data.entries ?? {};
         let loaded = 0;
         const now = Date.now();
         for (const [key, value] of Object.entries(entries)) {
@@ -285,7 +229,7 @@ class PromptCache {
                 break;
             }
             const entry = {
-                value,
+                value: value,
                 createdAt: now, // Fresh TTL from load time
             };
             this.cache.set(key, entry);
@@ -345,4 +289,4 @@ class PromptCache {
         }
     }
 }
-exports.PromptCache = PromptCache;
+exports.Cache = Cache;

package/dist/utils/prompts_cache.d.ts

@@ -3,6 +3,9 @@
  *
  * 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";
 /**
@@ -22,9 +25,9 @@ export interface CacheMetrics {
     refreshErrors: number;
 }
 /**
- * Configuration options for PromptCache.
+ * Configuration options for Cache.
  */
-export interface PromptCacheConfig {
+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 */
@@ -45,7 +48,7 @@ export interface PromptCacheConfig {
  *
  * @example
  * ```typescript
- * const cache = new PromptCache({
+ * const cache = new Cache({
  *   maxSize: 100,
  *   ttlSeconds: 3600,
  *   fetchFunc: async (key) => client.pullPromptCommit(key),
@@ -59,7 +62,7 @@ export interface PromptCacheConfig {
  * cache.stop();
  * ```
  */
-export declare class PromptCache {
+export declare class Cache {
     private cache;
     private maxSize;
     private ttlSeconds;
@@ -67,7 +70,7 @@ export declare class PromptCache {
     private fetchFunc?;
     private refreshTimer?;
     private _metrics;
-    constructor(config?: PromptCacheConfig);
+    constructor(config?: CacheConfig);
     /**
      * Get cache performance metrics.
      */

package/dist/utils/prompts_cache.js

@@ -3,9 +3,11 @@
  *
  * 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 * as fs from "node:fs";
-import * as path from "node:path";
+import { dumpCache, loadCache } from "./prompts_cache_fs.js";
 /**
  * Check if a cache entry is stale based on TTL.
  */
@@ -27,7 +29,7 @@ function isStale(entry, ttlSeconds) {
  *
  * @example
  * ```typescript
- * const cache = new PromptCache({
+ * const cache = new Cache({
  *   maxSize: 100,
  *   ttlSeconds: 3600,
  *   fetchFunc: async (key) => client.pullPromptCommit(key),
@@ -41,7 +43,7 @@ function isStale(entry, ttlSeconds) {
  * cache.stop();
  * ```
  */
-export class PromptCache {
+export class Cache {
     constructor(config = {}) {
         Object.defineProperty(this, "cache", {
             enumerable: true,
@@ -199,28 +201,11 @@ export class PromptCache {
      * Dump cache contents to a JSON file for offline use.
      */
     dump(filePath) {
-        const dir = path.dirname(filePath);
-        if (!fs.existsSync(dir)) {
-            fs.mkdirSync(dir, { recursive: true });
-        }
         const entries = {};
         for (const [key, entry] of this.cache.entries()) {
             entries[key] = entry.value;
         }
-        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;
-        }
+        dumpCache(filePath, entries);
     }
     /**
      * Load cache contents from a JSON file.
@@ -230,18 +215,10 @@ export class PromptCache {
      * @returns Number of entries loaded.
      */
     load(filePath) {
-        if (!fs.existsSync(filePath)) {
-            return 0;
-        }
-        let data;
-        try {
-            const content = fs.readFileSync(filePath, "utf-8");
-            data = JSON.parse(content);
-        }
-        catch {
+        const entries = loadCache(filePath);
+        if (!entries) {
             return 0;
         }
-        const entries = data.entries ?? {};
         let loaded = 0;
         const now = Date.now();
         for (const [key, value] of Object.entries(entries)) {
@@ -249,7 +226,7 @@ export class PromptCache {
                 break;
             }
             const entry = {
-                value,
+                value: value,
                 createdAt: now, // Fresh TTL from load time
             };
             this.cache.set(key, entry);

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.3",
+  "version": "0.4.5",
   "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"
   }
 }