jibdZddlmZddlZddlmcmZddl Z ddl Z ddl Z ddl Z ddl Z ddlZddlmZddlmZddlmZddlmZddlmZdd lmZmZmZmZmZer e j>d Z d Z!d Z"d Z#eGddZ$eGddZ%GddeZ&Gdde&Z'Gdde&Z(e'Z)e(Z*e"e!e#d d dZ+e"e!e#d d dZ,d!dZ-Gdde'Z.Gdde(Z/y)"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<eZdZUdZded<ded<dZded<d d Zy) CacheEntryz4A single cache entry with metadata for TTL tracking.r valuefloat created_atNzOptional[Callable[[], Any]] refresh_funccP|ytj|jz |kDS)z/Check if entry is past its TTL (needs refresh).F)timer)self ttl_secondss ^/home/jang/Projects/ai-researcher/.venv/lib/python3.12/site-packages/langsmith/prompt_cache.pyis_stalezCacheEntry.is_stale)s%   doo-<<)rOptional[float]returnbool)__name__ __module__ __qualname____doc____annotations__rrrrrr!s > J04L-4=rrcneZdZUdZdZded<dZded<dZded<dZded<e d dZ e d d Z y ) CacheMetricszCache performance metrics.rinthitsmisses refreshesrefresh_errorsc4|j|jzS)z%Total cache requests (hits + misses).)r)r*rs rtotal_requestszCacheMetrics.total_requests9syy4;;&&rcF|j}|dkDr|j|z SdS)zCache hit rate (0.0 to 1.0).rg)r/r))rtotals rhit_ratezCacheMetrics.hit_rate>s)##$)AItyy5 636rN)rr()rr) r r!r"r#r)r$r*r+r,propertyr/r2r%rrr'r'0sQ$D#MFCOIsNC ''77rr'ceZdZdZgdZeeef ddZe ddZ ddZ ddZ ddZ ddZdd Zdd Zdd Zdd Z dd Zy)_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_metricsct|_tj|_t |_|j|||y)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. max_sizerrefresh_interval_secondsN)rr6 threadingRLockr7r'r; _configurerr>rr?s r__init__z_BasePromptCache.__init__Us?5@M __& $  #%=  rc|jS)zGet cache performance metrics.)r;r.s rmetricsz_BasePromptCache.metricsls}}rc"t|_y)zReset all metrics to zero.N)r'r;r.s r reset_metricsz_BasePromptCache.reset_metricsqs $ rc|jdk(ry|j5||jvr)|jxjdz c_ dddy|j|}||_|jj ||jxjdz c_|jcdddS#1swYyxYw)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) r8r7r6r;r*r move_to_endr)r)rkeyrentrys rgetz_BasePromptCache.getus >>Q  ZZ $++% $$)$   KK$E".E  KK # #C ( MM  ! # ;;   s/B:AB::Cc|jdk(ry|j5tj}t|||}||jvrst |j|jk\rQt t|j}|jj|tjd|||j|<|jj|dddy#1swYyxYw)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: ) r8r7rrr6lennextiterpoploggerdebugrK)rrLrrnowrM oldest_keys r_setz_BasePromptCache._sets >>Q   ZZ )))+CUsVE$++%#dkk*:dnn*L!$t{{"34   + ;J<HI$DKK  KK # #C ( ) ) )s CC44C=c~|j5|jj|ddddy#1swYyxYw)ziRemove a specific entry from cache. Args: key: The cache key to invalidate. N)r7r6rT)rrLs r invalidatez_BasePromptCache.invalidates2 ZZ ' KKOOC & ' ' 's3<cz|j5|jjdddy#1swYyxYw)z$Clear all cache entries from memory.N)r7r6clearr.s rr]z_BasePromptCache.clears. ZZ KK      s1:c|j5|jjDcgc]$\}}|j|jr||f&c}}cdddScc}}w#1swYyxYw)z.Get list of stale cache entries (thread-safe).N)r7r6itemsrr9)rrLrMs r_get_stale_entriesz#_BasePromptCache._get_stale_entriessg ZZ #'++"3"3"5C>>$"3"34e     sA')A!A'!A''A0cVddlm}t|}|jj dd|j 5i}|j jD]\}}t|j|jrNt|jdr|jjd}n'|jj}n |j}|||<d|i}d d d |jd } t|d 5} t!j"| d d d d |j%|t&j)dt+d|y #1swY~xYw#1swYKxYw#t,$r'} |j/r|j1| d } ~ wwxYw)z{Dump cache contents to a JSON file for offline use. Args: path: Path to the output JSON file. rschemasT)parentsexist_ok model_dumpjson)modeentriesNz.tmpw)indentzDumped z cache entries to ) langsmithrcrparentmkdirr7r6r_ isinstancer PromptCommithasattrrfdict with_suffixopenrgdumpreplacerUrVrQ Exceptionexistsunlink) rpath ls_schemasrirLrM value_datadata temp_pathfes rrvz_BasePromptCache.dumpsu 4Dz $6 ZZ (G"kk//1 * Uekk:+B+BCu{{L9%*[[%;%;%;%H %*[[%5%5%7 "'J)  *w'D! (&$$V,  i% - $!, -   d # LL73w<.0B4&I J1 ( (* - - !  "G  s<B(E = E8 E,"=E8 E),E51E88 F("F##F(c ddlm}t|}|jstj d|y t |5}tj|}dddjdi}d}tj}|j5|jD]\} } t!|j"|j$k\rtj d|nq t'|j(d r|j(j+| } n|j(j-| } t/| | } | |j"| <|d z }dddtj d |d||S#1swY'xYw#tjtf$r%}tjd|d|Yd}~yd}~wwxYw#t0$r&}tjd | d|Yd}~Pd}~wwxYw#1swYxYw)a%Load cache contents from a JSON file. Args: path: Path to the JSON file to load. Returns: Number of entries loaded. Loaded entries get a fresh TTL starting from load time. If the file doesn't exist or is corrupted, returns 0. rrbzCache file not found: NzFailed to load cache file : riz)Reached max cache size, stopping load at model_validate)rrrJzFailed to load cache entry zLoaded z cache entries from )rmrcrryrUrVrurgloadJSONDecodeErrorOSErrorwarningrNrr7r_rQr6r8rrrqr parse_objrrx) rr{r|rr~rriloadedrWrLr}rrMs rrz_BasePromptCache.loads 4Dz{{} LL1$8 9 d $qyy| $ ((9b)iik ZZ #*==? Zt{{#t~~5LL#LVH!UV z668HI * 7 7 F Fz R * 7 7 A A* M'UsCE',DKK$aKF  *  wvh&:4&AB A $ $$$g.  NN7vRsC D 2!NN%@Rs#KL#  sg FFFAH-A.GHF FG (GG  G?G:4H:G??HH c.||_||_||_y)N)r8r9r:rCs rrBz_BasePromptCache._configure&s "'!9rNr>r(rrr?rrNone)rr'rr)rLstrrCallable[[], Any]rz Optional[Any]rLrrr rrrr)rLrrr)rzlist[tuple[str, CacheEntry]])r{Union[str, Path]rr)r{rrr()r r!r"r# __slots__DEFAULT_PROMPT_CACHE_MAX_SIZE DEFAULT_PROMPT_CACHE_TTL_SECONDS-DEFAULT_PROMPT_CACHE_REFRESH_INTERVAL_SECONDSrDr3rFrHrNrYr[r]r`rvrrBr%rrr5r5Es I6'G*W   % #(    .'>)4' (T5n::%:#( :  :rr5ceZdZdZddgZeeed d fdZddZ ddZ ddZ dd Z dd Z dd Zeeed d d ZxZS) 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_threadr=cjt||||tj|_d|_y)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. r=N)superrDr@Eventrrrr>rr? __class__s rrDzPromptCache.__init__Ks9 #%=  )0;?rcb|j|j|j|||y)rPN)r_start_refresh_threadrYrrLrrs rsetzPromptCache.setes,    '  & & ( #ul+rc$|jy)gStop background refresh thread. Should be called when the client is being cleaned up. N)shutdownr.s rstopzPromptCache.stoprs rc|j|jj|j$|jjdd|_yy)rNg@)timeout)rrrjoinr.s rrzPromptCache.shutdownysR    +  $ $ &    +  % %c % 2#'D  ,rc|jq|jjtj|j dd|_|j jtjdyy)z5Start background thread for refreshing stale entries.NTzPromptCache-refresh)targetdaemonnamezStarted cache refresh thread) r9rr]r@Thread _refresh_looprstartrUrVr.s rrz!PromptCache._start_refresh_threadsh    (  & & (#,#3#3))*$D  & & ( LL7 8 )rc|jj|js8 |j|jj|js7yy#t$r"}t j d|Yd}~Nd}~wwxYw)z)Background loop to refresh stale entries.z(Unexpected error in cache refresh loop: N)rwaitr:_refresh_stale_entriesrxrU exceptionrrs rrzPromptCache._refresh_loopsw&&++D,B,BC Q++-&&++D,B,BC Q  #KA3!OPP QsA B (BB c>|j}|sytjdt|d|D]\}}|jj ry|j / |j }|j|||j |jxjdz c_ tjd|y#t$rD}|jxjdz c_ tjd|d|Yd}~d}~wwxYw)z)Check for stale entries and refresh them.Nz Refreshing  stale cache entriesrJzRefreshed cache entry: zFailed to refresh cache entry r) r`rUrVrQris_setrrr;r+rxr,rr stale_entriesrLrM new_valuers rrz"PromptCache._refresh_stale_entriess//1   {3}#5"66JKL' PJC##**,!!-P % 2 2 4IHHS)U-?-?@MM++q0+LL#:3%!@A P!PMM00A50NN%CC51##NOOPs(A$C D:DDcL|j|j|||y)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. r=NrrBrCs r configurezPromptCache.configures'  #%=  rrrr)r r!r"r#rrrrrDrrrrrrr __classcell__rs@rrr1s.#$56I 6'G*W @@% @ #( @  @4 , ( 9QP46'G*W   %  #(    rrceZdZdZdgZeeed d fdZ d dZ ddZ ddZ ddZ dd Z dd Zeeed d d ZxZS)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_taskr=c8t||||d|_y)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. r=N)rrDrrs rrDzAsyncPromptCache.__init__s+ #%=  <@rc~K|j|jd{|j|||y7w)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)rrrYrs rasetzAsyncPromptCache.asets8    %**,   #ul+ s =;=cK|jy|jytj|j d|_t j dyw)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)r9rasyncio create_taskrrUrVr.s rrzAsyncPromptCache.startsW    $     ) $00    +   78sAAc`|j"|jjd|_yy)zStop background refresh task. Synchronous wrapper that cancels the refresh task. For proper cleanup in async context, use stop() instead. N)rcancelr.s rrzAsyncPromptCache.shutdowns/    )    % % '!%D  *rcK|jy|jj |jd{d|_tj dy7!#tj$rY4wxYww)zlStop async background refresh loop. Cancels the refresh task and waits for it to complete. Nz Stopped async cache refresh task)rrrCancelledErrorrUrVr.s rrzAsyncPromptCache.stop$sp    %  !!# $$ $ $" 78 %%%   s7(A7AAAA7AA41A73A44A7cK tj|jd{|jd{A77#tj$rt $r"}t jd|Yd}~>d}~wwxYww)z/Async background loop to refresh stale entries.Nz.Unexpected error in async cache refresh loop: )rsleepr:rrrxrUrrs rrzAsyncPromptCache._refresh_loop4s WmmD$:$:;;;11333;3))  W  #QRSQT!UVV WsOB "A AA AA B A A B%B=B BB c6K|j}|sytjdt|d|D]\}}|j |j d{}|j |||jd{|j xjdz c_tjd|y7c7@#t$rD}|j xjdz c_ tjd|d|Yd}~d}~wwxYww)z8Check for stale entries and refresh them asynchronously.NzAsync refreshing rrJzAsync refreshed cache entry: z$Failed to async refresh cache entry r) r`rUrVrQrrr;r+rxr,rrs rrz'AsyncPromptCache._refresh_stale_entries@s//1   (]);(<>> from langsmith import configure_global_prompt_cache >>> configure_global_prompt_cache(max_size=200, ttl_seconds=7200) r=N)prompt_cache_singletonrr=s rconfigure_global_prompt_cacherls &$$!9%rcPKtj|||d{y7wr)async_prompt_cache_singletonrr=s r#configure_global_async_prompt_cachers.& ' 0 0!9 1 s &$&c<tjdtdy)NzcThe 'Cache' class is deprecated and will be removed in a future version. Use 'PromptCache' instead.) stacklevel)warningswarnDeprecationWarningr%rr_deprecated_cache_class_warningrs MM % rc<eZdZdZeeed dfdZxZS)Cachez:Deprecated alias for PromptCache. Use PromptCache instead.r=c>tt| |||y)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. r=NrrrDrs rrDzCache.__init__& () #%=  rr r r!r"r#rrrrDrrs@rrrsCD 6'G*W   %  #(     rrc<eZdZdZeeed dfdZxZS) AsyncCachezDDeprecated alias for AsyncPromptCache. Use AsyncPromptCache instead.r=c>tt| |||y)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. r=Nrrs rrDzAsyncCache.__init__rrrrrs@rrrsCN 6'G*W   %  #(     rrrr)0r# __future__rbuiltins @py_builtins_pytest.assertion.rewrite assertionrewrite @pytest_arrrgloggingr@rrabcr collectionsrcollections.abcr dataclassesrpathlibrtypingr r r r r getLoggerrUrrrrr'r5rrrrrrrrrr%rrrsg #  #%!@@   , -$* #02-  = =  = 77 7(i:si:XR "R j^I'^ID%/1 2#C&S !$   82#C&S !$   : K 2 ! r