o !ib@sjdZddlmZddlZddlZddlZddlZddlZddlZddl m Z ddl m Z ddl mZddlmZddlmZdd lmZmZmZmZmZerO ed Zd Zd Zd ZeGdddZeGdddZGddde Z Gddde Z!Gddde Z"e!Z#e"Z$eeedd+d!d"Z%eeedd+d#d$Z&d,d%d&Z'Gd'd(d(e!Z(Gd)d*d*e"Z)dS)-zPrompt caching module for LangSmith SDK. This module provides thread-safe LRU caches with background refresh for prompt caching. Includes both sync and async implementations. ) annotationsN)ABC) OrderedDict) Awaitable) dataclass)Path) TYPE_CHECKINGAnyCallableOptionalUnionzlangsmith.cachei,d<c@s8eZdZUdZded<ded<dZded<dd dZdS) CacheEntryz4A single cache entry with metadata for TTL tracking.r valuefloat created_atNzOptional[Callable[[], Any]] refresh_func ttl_secondsOptional[float]returnboolcCs|durdSt|j|kS)z/Check if entry is past its TTL (needs refresh).NF)timer)selfrr[/var/www/html/crm_dreinet/venv_linux/lib/python3.10/site-packages/langsmith/prompt_cache.pyis_stale)szCacheEntry.is_stale)rrrr)__name__ __module__ __qualname____doc____annotations__rrrrrrr!s  rc@s^eZdZUdZdZded<dZded<dZded<dZded<e dd d Z e dd d Z dS) CacheMetricszCache performance metrics.rinthitsmisses refreshesrefresh_errorsrcCs |j|jS)z%Total cache requests (hits + misses).)r$r%rrrrtotal_requests9s zCacheMetrics.total_requestsrcCs|j}|dkr |j|SdS)zCache hit rate (0.0 to 1.0).rg)r)r$)rtotalrrrhit_rate>szCacheMetrics.hit_rateN)rr#)rr) rrrr r$r!r%r&r'propertyr)r+rrrrr"0s      r"c@seZdZdZgdZeeefd-d d Ze d.ddZ d/ddZ d0ddZ d1ddZ d2ddZd/dd Zd3d"d#Zd4d&d'Zd5d(d)Zd-d*d+Zd,S)6_BasePromptCachezBase class for prompt caches with shared LRU logic. Provides thread-safe in-memory LRU cache operations. Subclasses implement the background refresh mechanism. )_cache_lock _max_size _ttl_seconds_refresh_interval_metricsmax_sizer#rrrefresh_interval_secondsrrNonecCs.t|_t|_t|_|j|||ddS)agInitialize the base cache. Args: max_size: Maximum entries in cache (LRU eviction when exceeded). ttl_seconds: Time before entry is considered stale. Set to None for infinite TTL (entries never expire, no background refresh). refresh_interval_seconds: How often to check for stale entries. r4rr5N)rr. threadingRLockr/r"r3 _configurerr4rr5rrr__init__Us  z_BasePromptCache.__init__r"cCs|jS)zGet cache performance metrics.)r3r(rrrmetricslsz_BasePromptCache.metricscCs t|_dS)zReset all metrics to zero.N)r"r3r(rrr reset_metricsqs z_BasePromptCache.reset_metricskeystrrCallable[[], Any] Optional[Any]cCs|jdkrdS|j7||jvr!|jjd7_ WddS|j|}||_|j||jjd7_|jWdS1sDwYdS)a]Get a value from cache. Args: key: The cache key (prompt identifier like "owner/name:hash"). refresh_func: Function to refresh this cache entry when stale. Returns: The cached value or None if not found. Stale entries are still returned (background refresh handles updates). rN) r0r/r.r3r%r move_to_endr$r)rr?rentryrrrgetus    $z_BasePromptCache.getrr cCs|jdkrdS|jAt}t|||d}||jvr8t|j|jkr8tt|j}|j|t d|||j|<|j |WddS1sNwYdS)Set a value in the cache. Args: key: The cache key (prompt identifier). value: The value to cache. refresh_func: Function to refresh this cache entry when stale. rN)rrrzEvicted oldest cache entry: ) r0r/rrr.lennextiterpoploggerdebugrD)rr?rrnowrE oldest_keyrrr_sets   "z_BasePromptCache._setcCs:|j|j|dWddS1swYdS)ziRemove a specific entry from cache. Args: key: The cache key to invalidate. N)r/r.rK)rr?rrr invalidates"z_BasePromptCache.invalidatecCs6|j|jWddS1swYdS)z$Clear all cache entries from memory.N)r/r.clearr(rrrrRs "z_BasePromptCache.clearlist[tuple[str, CacheEntry]]csBjfddjDWdS1swYdS)z.Get list of stale cache entries (thread-safe).cs$g|]\}}|jr||fqSr)rr1).0r?rEr(rr s  z7_BasePromptCache._get_stale_entries..N)r/r.itemsr(rr(r_get_stale_entriess  $z#_BasePromptCache._get_stale_entriespathUnion[str, Path]c CsJddlm}t|}|jjddd|j:i}|jD]&\}}t|j |j rrFrPrQrRrWrnr{r:rrrrr-Es$         *7r-cseZdZdZddgZeeedd#fd dZd$ddZ d%ddZ d%ddZ d%ddZ d%ddZ d%dd Zeeedd#d!d"ZZS)& PromptCacheaThread-safe LRU cache with background thread refresh. For use with the synchronous Client. Features: - In-memory LRU cache with configurable max size - Background thread for refreshing stale entries - Stale-while-revalidate: returns stale data while refresh happens - Thread-safe for concurrent access Example: >>> def fetch_prompt(key: str) -> PromptCommit: ... return client._fetch_prompt_from_api(key) >>> cache = PromptCache( ... max_size=100, ... ttl_seconds=3600, ... fetch_func=fetch_prompt, ... ) >>> cache.set("my-prompt:latest", prompt_commit) >>> cached = cache.get("my-prompt:latest") >>> cache.shutdown() _shutdown_event_refresh_threadr7r4r#rrr5rrr6cs&tj|||dt|_d|_dS)aInitialize the sync prompt cache. Args: max_size: Maximum entries in cache (LRU eviction when exceeded). ttl_seconds: Time before entry is considered stale. Set to None for infinite TTL (offline mode - entries never expire). Default: 300 (5 minutes). refresh_interval_seconds: How often to check for stale entries. r7N)superr<r8Eventrrr; __class__rrr<Ks  zPromptCache.__init__r?r@rr rrAcCs$|jdur |||||dS)rGN)r_start_refresh_threadrPrr?rrrrrsetes zPromptCache.setcCs |dS)gStop background refresh thread. Should be called when the client is being cleaned up. N)shutdownr(rrrstoprs zPromptCache.stopcCs:|jdur |j|jdur|jjddd|_dSdS)rNg@)timeout)rrrjoinr(rrrrys    zPromptCache.shutdowncCsD|jdur |jtj|jddd|_|jt ddSdS)z5Start background thread for refreshing stale entries.NTzPromptCache-refresh)targetdaemonnamezStarted cache refresh thread) r1rrRr8Thread _refresh_looprstartrLrMr(rrrrs   z!PromptCache._start_refresh_threadc Csf|j|js1z|Wnty'}ztd|WYd}~nd}~ww|j|jrdSdS)z)Background loop to refresh stale entries.z(Unexpected error in cache refresh loop: N)rwaitr2_refresh_stale_entriesrprL exceptionrrxrrrrs zPromptCache._refresh_loopc Cs|}|sdStdt|d|D]U\}}|jr!dS|jdurjz|}||||j|jj d7_ td|Wqt yi}z|jj d7_ t d|d|WYd}~qd}~wwqdS)z)Check for stale entries and refresh them.Nz Refreshing  stale cache entriesrCzRefreshed cache entry: zFailed to refresh cache entry ry) rWrLrMrHris_setrrr3r&rpr'r~r stale_entriesr?rE new_valuerxrrrrs(   "z"PromptCache._refresh_stale_entriescCs||j|||ddS)Reconfigure the cache parameters. Args: max_size: Maximum entries in cache (LRU eviction when exceeded). ttl_seconds: Time before entry is considered stale. refresh_interval_seconds: How often to check for stale entries. r7Nrr:r;rrr configures  zPromptCache.configurerrr)rrrr rrrrr<rrrrrrr __classcell__rrrrr1s"   rcseZdZdZdgZeeedd"fd d Zd#ddZ d$ddZ d$ddZ d$ddZ d$ddZ d$ddZeeedd"d d!ZZS)%AsyncPromptCacheaThread-safe LRU cache with asyncio task refresh. For use with the asynchronous AsyncClient. Features: - In-memory LRU cache with configurable max size - Asyncio task for refreshing stale entries - Stale-while-revalidate: returns stale data while refresh happens - Thread-safe for concurrent access Example: >>> async def fetch_prompt(key: str) -> PromptCommit: ... return await client._afetch_prompt_from_api(key) >>> cache = AsyncPromptCache( ... max_size=100, ... ttl_seconds=3600, ... fetch_func=fetch_prompt, ... ) >>> await cache.start() >>> cache.set("my-prompt:latest", prompt_commit) >>> cached = cache.get("my-prompt:latest") >>> await cache.stop() _refresh_taskr7r4r#rrr5rrr6cstj|||dd|_dS)agInitialize the async prompt cache. Args: max_size: Maximum entries in cache (LRU eviction when exceeded). ttl_seconds: Time before entry is considered stale. Set to None for infinite TTL (offline mode - entries never expire). refresh_interval_seconds: How often to check for stale entries. r7N)rr<rr;rrrr<s  zAsyncPromptCache.__init__r?r@rr rCallable[[], Awaitable[Any]]cs,|jdur |IdH||||dS)zSet a value in the cache. Args: key: The cache key (prompt identifier). value: The value to cache. refresh_func: Async function to refresh this cache entry when stale. N)rrrPrrrrasets zAsyncPromptCache.asetcs@|jdurdS|jdurdStj|dd|_tddS)zStart async background refresh loop. Must be called from an async context. Creates an asyncio task that periodically checks for stale entries and refreshes them. Does nothing if ttl_seconds is None (infinite TTL mode). NzAsyncPromptCache-refresh)rz Started async cache refresh task)r1rasyncio create_taskrrLrMr(rrrrs  zAsyncPromptCache.startcCs"|jdur|jd|_dSdS)zStop background refresh task. Synchronous wrapper that cancels the refresh task. For proper cleanup in async context, use stop() instead. N)rcancelr(rrrrs   zAsyncPromptCache.shutdowncsT|jdurdS|jz|jIdHWn tjyYnwd|_tddS)zlStop async background refresh loop. Cancels the refresh task and waits for it to complete. Nz Stopped async cache refresh task)rrrCancelledErrorrLrMr(rrrr$s  zAsyncPromptCache.stopc sp zt|jIdH|IdHWn"tjyty6}ztd|WYd}~nd}~wwq)z/Async background loop to refresh stale entries.TNz.Unexpected error in async cache refresh loop: )rsleepr2rrrprLrrrrrr4szAsyncPromptCache._refresh_loopc s|}|s dStdt|d|D]S\}}|jduriz$|IdH}||||jIdH|jjd7_td|Wqtyh}z|jj d7_ t d|d|WYd}~qd}~wwqdS)z8Check for stale entries and refresh them asynchronously.NzAsync refreshing rrCzAsync refreshed cache entry: z$Failed to async refresh cache entry ry) rWrLrMrHrrr3r&rpr'r~rrrrr@s&  "z'AsyncPromptCache._refresh_stale_entriescs"|IdH||||dS)rNrr;rrrrUszAsyncPromptCache.configurer)r?r@rr rrrr6r)rrrr rrrrr<rrrrrrrrrrrrrs"     rr7r4r#rrr5rrr6cCstj|||ddSaConfigure the global prompt cache. This should be called before any cache instances are created or used. Args: max_size: Maximum entries in cache (LRU eviction when exceeded). ttl_seconds: Time before entry is considered stale. refresh_interval_seconds: How often to check for stale entries. Example: >>> from langsmith import configure_global_prompt_cache >>> configure_global_prompt_cache(max_size=200, ttl_seconds=7200) r7N)prompt_cache_singletonrr7rrrconfigure_global_prompt_cachels  rcstj|||dIdHdSr)async_prompt_cache_singletonrr7rrr#configure_global_async_prompt_caches rcCstjdtdddS)NzcThe 'Cache' class is deprecated and will be removed in a future version. Use 'PromptCache' instead.) stacklevel)warningswarnDeprecationWarningrrrr_deprecated_cache_class_warnings  rc,eZdZdZeeedd fd d ZZS)Cachez:Deprecated alias for PromptCache. Use PromptCache instead.r7r4r#rrr5rrr6cttj|||ddS)aInitialize the deprecated Cache class. Args: max_size: Maximum entries in cache (LRU eviction when exceeded). ttl_seconds: Time before entry is considered stale. refresh_interval_seconds: How often to check for stale entries. r7Nrrr<r;rrrr<  zCache.__init__r rrrr rrrr<rrrrrr rcr) AsyncCachezDDeprecated alias for AsyncPromptCache. Use AsyncPromptCache instead.r7r4r#rrr5rrr6cr)aInitialize the deprecated AsyncCache class. Args: max_size: Maximum entries in cache (LRU eviction when exceeded). ttl_seconds: Time before entry is considered stale. refresh_interval_seconds: How often to check for stale entries. r7Nrr;rrrr<rzAsyncCache.__init__rrrrrrrrrrr)*r __future__rrr_loggingr8rrabcr collectionsrcollections.abcr dataclassesrpathlibrtypingrr r r r getLoggerrLrrrrr"r-rrrrrrrrrrrrrsV       m#