Q ifdZddlmZmZmZmZmZddlmZm Z ddl m Z ddl m Z ddlmZddlmZddlmZmZeeZd eeefd eeeffd Zd eeefd eeeffd ZGd de ZdS)zLangCache API-based LLM cache implementation for RedisVL. This module provides an LLM cache implementation that uses the LangCache managed service via the langcache Python SDK. )AnyDictListLiteralOptional)quoteunquote) BaseLLMCache)CacheHit)FilterExpression) get_logger)denorm_cosine_distancenorm_cosine_distance attributesreturnc|s|Sd}t|}|D]8\}}t|trt |d}||kr|||<d}9|r|n|S)zReturn a copy of *attributes* with string values safely encoded. Only top-level string values are encoded; non-string values are left unchanged. If no values require encoding, the original dict is returned unchanged. F)safeT)dictitems isinstancestrr)rchangedsafe_attributeskeyvalueencodeds C:\Users\Dell Inspiron 16\Desktop\tws\AgrotaPowerBi\back-agrota-powerbi\mcp-client-agrota\venv\Lib\site-packages\redisvl/extensions/cache/llm/langcache.py _encode_attributes_for_langcachers G&*:&6&6O &&(( U eS ! ! E+++G%'.$% 5??:5c|s|Sd}t|}|D]6\}}t|trt |}||kr|||<d}7|r|n|S)a+Return a copy of *attributes* with string values safely decoded. This is the inverse of :func:`_encode_attributes_for_langcache`. Only top-level string values are decoded; non-string values are left unchanged. If no values require decoding, the original dict is returned unchanged. FT)rrrrr )rrdecoded_attributesrrdecodeds r!_decode_attributes_from_langcacher$-s G)-j)9)9 &&(( U eS ! ! ennG%*1"3'!( 8  j8r ceZdZdZ d5ded ed ed ed eed edededffd Z dZ dee dee fdZ dedee dee eefde eeffdZdededee eeffdZde eefdefdZ d6deed eee ded!eeed"eedee dee eefdee eeffd#Z d6deed eee ded!eeed"eedee dee eefdee eeffd$Z d7deded eee d%ee eefd&ee eefd eedefd'Z d7deded eee d%ee eefd&ee eefd eedefd(Zd)eddfd*Zd)eddfd+Zd8d,Zd8d-Zd8d.Zd8d/Zd0eddfd1Zd0eddfd2Z de eefde eeffd3Z!de eefde eeffd4Z"xZ#S)9LangCacheSemanticCacheaXLLM Cache implementation using the LangCache managed service. This cache uses the LangCache API service for semantic caching of LLM responses. It requires a LangCache account and API key. Example: .. code-block:: python from redisvl.extensions.cache.llm import LangCacheSemanticCache cache = LangCacheSemanticCache( name="my_cache", server_url="https://api.langcache.com", cache_id="your-cache-id", api_key="your-api-key", ttl=3600 ) # Store a response cache.store( prompt="What is the capital of France?", response="Paris" ) # Check for cached responses results = cache.check(prompt="What is the capital of France?") langcache(https://aws-us-east-1.langcache.redis.iorNT normalizedname server_urlcache_idapi_keyttluse_exact_searchuse_semantic_searchdistance_scale)r)redisc  |dvrtd||_|std|stdtjd ||d| ||_||_||_g|_|r|jd|r|jd|jstd| |_ d S) uInitialize a LangCache semantic cache. Args: name (str): The name of the cache. Defaults to "langcache". server_url (str): The LangCache server URL. cache_id (str): The LangCache cache ID. api_key (str): The LangCache API key. ttl (Optional[int]): Time-to-live for cache entries in seconds. use_exact_search (bool): Whether to use exact matching. Defaults to True. use_semantic_search (bool): Whether to use semantic search. Defaults to True. distance_scale (str): Threshold scale for distance_threshold: - "normalized": 0–1 semantic distance (lower is better) - "redis": Redis COSINE distance 0–2 (lower is better) Raises: ImportError: If the langcache package is not installed. ValueError: If cache_id or api_key is not provided. >r2r)z.distance_scale must be 'normalized' or 'redis'z/cache_id is required for LangCacheSemanticCachez.api_key is required for LangCacheSemanticCache)r*r.exactsemanticzDAt least one of use_exact_search or use_semantic_search must be TrueN) ValueError_distance_scalesuper__init__ _server_url _cache_id_api_key_search_strategiesappend_create_client_client) selfr*r+r,r-r.r/r0r1kwargs __class__s rr:zLangCacheSemanticCache.__init__as< !8 8 8MNN N- PNOO O OMNN N6d66v666%! #%  4  # * *7 3 3 3  7  # * *: 6 6 6& V **,, r c ddlm}n"#t$r}td|d}~wwxYw||j|j|jS)z Initialize the LangCache client. Returns: LangCache: The LangCache client. Raises: ImportError: If the langcache package is not installed. r) LangCachezgThe langcache package is required to use LangCacheSemanticCache. Install it with: pip install langcacheN)r+r,r-)r'rF ImportErrorr;r<r=)rBrFes rr@z%LangCacheSemanticCache._create_clients  + + + + + + +   9   y'^M    s (#(distance_thresholdrcb|dS|jdkrt|Sdt|z S)uConvert a distance threshold to a similarity threshold based on scale. - If distance_scale == "redis": use norm_cosine_distance (0–2 -> 0–1) - Otherwise: use (1.0 - distance_threshold) for normalized 0–1 distances Nr2?)r8rfloat)rBrIs r_similarity_thresholdz,LangCacheSemanticCache._similarity_thresholds@  %4  7 * *'(:;; ;U-....r promptsimilarity_thresholdrcddlm}d|jvr|jndd|jvr|jndg}d|D}|||d}|rt ||d<|S)Nr)SearchStrategyr4r5cg|]}||S)Nr6).0ss r z?LangCacheSemanticCache._build_search_kwargs..sKKK1Q]Q]]]r )rNsearch_strategiesrOr)langcache.modelsrQr>EXACTSEMANTICr)rBrNrOrrQrVrCs r_build_search_kwargsz+LangCacheSemanticCache._build_search_kwargss 433333 %,t/F$F$FN D'1T5L'L'LN # #RV  LK(9KKK!2$8" "   P$DJ#O#OF<  r response num_resultsc6t|dr|jng}g}|d|D]r}t|dr|}nt|}||}||s|S)Ndata model_dump)hasattrr^r_r_convert_to_cache_hitr?to_dict)rBr[r\resultshitsresult result_dicthits r_hits_from_responsez*LangCacheSemanticCache._hits_from_responses$+8V#<#<D(--"%'l{l+ ' 'Fv|,, +$//11 "6ll ,,[99C KK & & & & r rec |dipi}|rt|}|dd}|jdkrt|}nd|z }t |dd|dd|d d||d d|d d|r|nd S)zConvert a LangCache result to a CacheHit object. Args: result (Dict[str, Any]): The result from LangCache. Returns: CacheHit: The converted cache hit. r similaritygr2rKidrrNr[ created_at updated_atN)entry_idrNr[vector_distance inserted_atrmmetadata)getr$r8rr )rBrerrjdistances rraz,LangCacheSemanticCache._convert_to_cache_hitsZZ b117R  G;:FFJZZ c22  7 * *-j99HHZ'HZZb))::h++ZZ B//$ <55zz,44#-7ZZ4    r vector return_fieldsfilter_expressionc(|std|td|tdd}|||}||||} |jjd i| } no#t$rb} ddlm } n#t$rwxYwt| | r5dt|  vr|rtd | d} ~ wwxYw|| |S) uSCheck the cache for semantically similar prompts. Args: prompt (Optional[str]): The text prompt to search for. vector (Optional[List[float]]): Not supported by LangCache API. num_results (int): Number of results to return. Defaults to 1. return_fields (Optional[List[str]]): Not used (for compatibility). filter_expression (Optional[FilterExpression]): Not supported. distance_threshold (Optional[float]): Maximum distance threshold. Converted to similarity_threshold according to distance_scale: - If "redis": uses norm_cosine_distance(distance_threshold) ([0,2] → [0,1]) - If "normalized": uses (1.0 - distance_threshold) ([0,1] → [0,1]) attributes (Optional[Dict[str, Any]]): LangCache attributes to filter by. Note: Attributes must be pre-configured in your LangCache instance. Returns: List[Dict[str, Any]]: List of matching cache entries. Raises: ValueError: If prompt is not provided. 'prompt is required for LangCache searchN1LangCache does not support vector search directly-LangCache does not support filter expressionsrNrOrrBadRequestErrorResponseContentno attributes are configuredzLangCache reported attributes are not configured for this cache, but attributes were provided to check(). Remove attributes or configure them on the cache.r6)r7loggerwarningrMrZrAsearch Exceptionlangcache.errorsr~rrlower RuntimeErrorrh rBrNrur\rvrwrIrrO search_kwargsr[rHr~s rcheckzLangCacheSemanticCache.check s> HFGG G   NNN O O O  ( NNJ K K K $  )#'#=#=>P#Q#Q 11!5!2   *t|*;;];;HH    KKKKKKK    1<== 2c!ffllnnDDE#q  $''+>>>s+<B C;B! C6! B--A C66C;c8K|std|td|tdd}|||}||||} |jjd i| d{V} no#t$rb} ddlm } n#t$rwxYwt| | r5dt|  vr|rtd | d} ~ wwxYw|| |S) adAsync check the cache for semantically similar prompts. Args: prompt (Optional[str]): The text prompt to search for. vector (Optional[List[float]]): Not supported by LangCache API. num_results (int): Number of results to return. Defaults to 1. return_fields (Optional[List[str]]): Not used (for compatibility). filter_expression (Optional[FilterExpression]): Not supported. distance_threshold (Optional[float]): Maximum distance threshold. Converted to similarity_threshold according to distance_scale: - If "redis": uses norm_cosine_distance(distance_threshold) ([0,2] -> [0,1]) - If "normalized": uses (1.0 - distance_threshold) ([0,1] -> [0,1]) attributes (Optional[Dict[str, Any]]): LangCache attributes to filter by. Note: Attributes must be pre-configured in your LangCache instance. Returns: List[Dict[str, Any]]: List of matching cache entries. Raises: ValueError: If prompt is not provided. ryNrzr{r|rr}rzLangCache reported attributes are not configured for this cache, but attributes were provided to acheck(). Remove attributes or configure them on the cache.r6)r7rrrMrZrA search_asyncrrr~rrrrrhrs racheckzLangCacheSemanticCache.acheckWs> HFGG G   NNN O O O  ( NNJ K K K $  )#'#=#=>P#Q#Q 11!5!2   6T\6GGGGGGGGGGHH    KKKKKKK    1<== 2c!ffllnnDDE#r  $''+>>>s+>B D"B)(C>) B55A C>>Drqfiltersc|std|std|td|td |t|dznd}|r.t |}|j||||} n|j|||} no#t$rb} d d lm } n#t$rwxYwt| | r5d t|  vr|rtd | d} ~ wwxYwt| d r| jndS)aeStore a prompt-response pair in the cache. Args: prompt (str): The user prompt to cache. response (str): The LLM response to cache. vector (Optional[List[float]]): Not supported by LangCache API. metadata (Optional[Dict[str, Any]]): Optional metadata (stored as attributes). filters (Optional[Dict[str, Any]]): Not supported. ttl (Optional[int]): Optional TTL override in seconds. Returns: str: The entry ID for the cached entry. Raises: ValueError: If prompt or response is empty. prompt is requiredresponse is requiredN)LangCache does not support custom vectors"LangCache does not support filtersrNr[r ttl_millisrNr[rrr}rzLangCache reported attributes are not configured for this cache, but metadata was provided to store(). Remove metadata or configure attributes on the cache.rnr)r7rrroundrrAsetrrr~rrrrr`rn rBrNr[rurqrr.r safe_metadatarerHr~s rstorezLangCacheSemanticCache.stores2 3122 2 5344 4   NNF G G G   NN? @ @ @ .1osTz***4J  @ J J ))!%,) *))!%)*     KKKKKKK    1<== 2c!ffllnnDDE#r  &#*&*"="=Ev2Es,A#C D, CD' CA D''D,cK|std|std|td|td |t|dznd}|r4t |}|j||||d{V} n#|j|||d{V} no#t$rb} d d lm } n#t$rwxYwt| | r5d t|  vr|rtd | d} ~ wwxYwt| d r| jndS)akAsync store a prompt-response pair in the cache. Args: prompt (str): The user prompt to cache. response (str): The LLM response to cache. vector (Optional[List[float]]): Not supported by LangCache API. metadata (Optional[Dict[str, Any]]): Optional metadata (stored as attributes). filters (Optional[Dict[str, Any]]): Not supported. ttl (Optional[int]): Optional TTL override in seconds. Returns: str: The entry ID for the cached entry. Raises: ValueError: If prompt or response is empty. rrNrrrrrrr}rzLangCache reported attributes are not configured for this cache, but metadata was provided to astore(). Remove metadata or configure attributes on the cache.rnr)r7rrrrrA set_asyncrrr~rrrrr`rnrs rastorezLangCacheSemanticCache.astores2 3122 2 5344 4   NNF G G G   NN? @ @ @ .1osTz***4J  @ J J #|55!%,) 6   $|55!%) 6       KKKKKKK    1<== 2c!ffllnnDDE#s  &#*&*"="=Ev2Es,A/C D:C D5 C,,A D55D:rc td)aUpdate specific fields within an existing cache entry. Note: LangCache API does not support updating individual entries. This method will raise NotImplementedError. Args: key (str): The key of the document to update. **kwargs: Field-value pairs to update. Raises: NotImplementedError: LangCache does not support entry updates. cLangCache API does not support updating individual entries. Delete and re-create the entry instead.NotImplementedErrorrBrrCs rupdatezLangCacheSemanticCache.update6s" 6   r c$Ktd)aAsync update specific fields within an existing cache entry. Note: LangCache API does not support updating individual entries. This method will raise NotImplementedError. Args: key (str): The key of the document to update. **kwargs: Field-value pairs to update. Raises: NotImplementedError: LangCache does not support entry updates. rrrs raupdatezLangCacheSemanticCache.aupdateHs" 6   r c8|jdS)zjDelete the entire cache. This deletes all entries in the cache by calling the flush API. N)rAflushrBs rdeletezLangCacheSemanticCache.deleteZs r cHK|jd{VdS)zpAsync delete the entire cache. This deletes all entries in the cache by calling the flush API. N)rA flush_asyncrs radeletezLangCacheSemanticCache.adeleteas4 l&&(((((((((((r c.|dS)zqClear the cache of all entries. This is an alias for delete() to match the BaseCache interface. N)rrs rclearzLangCacheSemanticCache.clearhs r c>K|d{VdS)zxAsync clear the cache of all entries. This is an alias for adelete() to match the BaseCache interface. N)rrs raclearzLangCacheSemanticCache.aclearos. llnnr rnc<|j|dS)zuDelete a single cache entry by ID. Args: entry_id (str): The ID of the entry to delete. rnN)rA delete_by_idrBrns rrz#LangCacheSemanticCache.delete_by_idvs# !!8!44444r cLK|j|d{VdS)z{Async delete a single cache entry by ID. Args: entry_id (str): The ID of the entry to delete. rN)rAdelete_by_id_asyncrs r adelete_by_idz$LangCacheSemanticCache.adelete_by_id~s9 l--x-@@@@@@@@@@@r c|stdt|}|j|}t |dr|niS)aVDelete cache entries matching the given attributes. Args: attributes (Dict[str, Any]): Attributes to match for deletion. Cannot be empty. Returns: Dict[str, Any]: Result of the deletion operation. Raises: ValueError: If attributes is an empty dictionary. @Cannot delete by attributes with an empty attributes dictionary.rr_)r7rrA delete_queryr`r_rBrrres rdelete_by_attributesz+LangCacheSemanticCache.delete_by_attributessn R ;:FF**o*FF&-fl&C&CKv  """Kr cK|stdt|}|j|d{V}t |dr|niS)a\Async delete cache entries matching the given attributes. Args: attributes (Dict[str, Any]): Attributes to match for deletion. Cannot be empty. Returns: Dict[str, Any]: Result of the deletion operation. Raises: ValueError: If attributes is an empty dictionary. rrNr_)r7rrAdelete_query_asyncr`r_rs radelete_by_attributesz,LangCacheSemanticCache.adelete_by_attributess R ;:FF|66/6RRRRRRRR&-fl&C&CKv  """Kr )r'r(rrNTTr))NNrtNNNN)NNNN)rN)$__name__ __module__ __qualname____doc__rrintboolrr:r@rLrMrrrZrrhr rar rrrrrrrrrrrrrr __classcell__)rDs@rr&r&Ds< D!!%$(9E9-9-9-9- 9-  9- c] 9-9-"9- 569-9-9-9-9-9-v   0 /"*5/ / % / / / /'uoT#s(^,  c3h 6  *-  d38n       DcN  x     H!%(,-18<.2/3H?H? H?e%H? H?  S * H? $$45 H?%UOH?T#s(^,H? d38n H?H?H?H?X!%(,-18<.2/3K?K? K?e%K? K?  S * K? $$45 K?%UOK?T#s(^,K? d38n K?K?K?K?b)--1,0!GFGFGFGFe% GF 4S>* GF $sCx.) GFc]GF GFGFGFGFZ)--1,0!GFGFGFGFe% GF 4S>* GF $sCx.) GFc]GF GFGFGFGFR # D    $  4    $))))5S5T5555ACADAAAALtCH~L$sCx.LLLL,Ld38nLcSVhLLLLLLLLr r&N)rtypingrrrrr urllib.parserr !redisvl.extensions.cache.llm.baser #redisvl.extensions.cache.llm.schemar redisvl.query.filterr redisvl.utils.logr redisvl.utils.utilsrrrrrrr$r&r6r rrsn 65555555555555''''''''::::::888888111111((((((LLLLLLLL H  6c3h6DcN666649$sCx.9T#s(^9999.l Ll Ll Ll Ll L\l Ll Ll Ll Ll Lr