g3fi XdZddlmZddlmZmZddlmZddlmZddl m Z m Z m Z m Z mZddlmZddlmZdd lmZmZmZmZmZGd d ZeZGd d ZGddeZGdde ZGdde Zee e dzdfZ! e dZ" Gdde Z#Gdde Z$Gdde Z%eeze%ze$zZ&ee'eze'eze'ee dfzdzZ(Gdde)Z*Gd d!e d"#Z+Gd$d%e d"#Z,Gd&d'eZ-d,d(Z. d- d.d)Z/ef d/d*Z0gd+Z1y)0aBase classes and types for persistent key-value stores. Stores provide long-term memory that persists across threads and conversations. Supports hierarchical namespaces, key-value storage, and optional vector search. Core types: - `BaseStore`: Store interface with sync/async operations - `Item`: Stored key-value pairs with metadata - `Op`: Get/Put/Search/List operations ) annotations)ABCabstractmethod)Iterable)datetime)AnyLiteral NamedTuple TypedDictcast) Embeddings)override)AEmbeddingsFuncEmbeddingsFuncensure_embeddingsget_text_at_path tokenize_pathc*eZdZdZddZeddZy) NotProvidedzSentinel singleton.cyNFselfs [/var/www/auto_recruiter/arenv/lib/python3.12/site-packages/langgraph/store/base/__init__.py__bool__zNotProvided.__bool__(scy)N NOT_GIVENrrs r__repr__zNotProvided.__repr__+srN)returnzLiteral[False]r!str)__name__ __module__ __qualname____doc__rrr rrrrr%srrcPeZdZdZdZ d dZd dZd dZd dZd dZ y)ItemaRepresents a stored item with metadata. Args: value: The stored data as a dictionary. Keys are filterable. key: Unique identifier within the namespace. namespace: Hierarchical path defining the collection in which this document resides. Represented as a tuple of strings, allowing for nested categorization. For example: `("documents", 'user123')` created_at: Timestamp of item creation. updated_at: Timestamp of last update. valuekey namespace created_at updated_atc4||_||_t||_t |t r#t jtt |n||_ t |t r)t jtt ||_ y||_ yN) r+r,tupler- isinstancer#r fromisoformatr r.r/)rr+r,r-r.r/s r__init__z Item.__init__Bs y)*c*  " "4Z#8 9 *c*  " "4Z#8 9  rc.t|tsy|j|jk(xrj|j|jk(xrO|j|jk(xr4|j |j k(xr|j |j k(Sr)r3r)r+r,r-r.r/)rothers r__eq__z Item.__eq__[s%& JJ%++ % 4EII% 4%//1 45#3#33 45#3#33  rcDt|j|jfSr1)hashr-r,rs r__hash__z Item.__hash__fsT^^TXX.//rct|j|j|j|jj |j j dS)N)r-r,r+r.r/)listr-r,r+r. isoformatr/rs rdictz Item.dictisFdnn-88ZZ//335//335   rcrddjd|jjDdS)NzItem(z, c30K|]\}}|d|yw)=Nr).0kvs r z Item.__repr__..ss N$!QA3au Ns))joinr?itemsrs rr z Item.__repr__rs0tyy N$))+:K:K:M NNOqQQrN) r+dict[str, Any]r,r#r-tuple[str, ...]r.rr/r)r7objectr!bool)r!intr!r?r") r$r%r&r' __slots__r5r8r;r?r rrrr)r)3s[ JI    #     2  0 Rrr)cReZdZdZdZ d dfd Zdfd ZxZS) SearchItemzMRepresents an item returned from a search operation with additional metadata.)scorec<t||||||||_y)aInitialize a result item. Args: namespace: Hierarchical path to the item. key: Unique identifier within the namespace. value: The stored value. created_at: When the item was first created. updated_at: When the item was last updated. score: Relevance/similarity score if from a ranked operation. r*N)superr5rS)rr-r,r+r.r/rS __class__s rr5zSearchItem.__init__{s/& !!   rcBt|}|j|d<|S)NrS)rUr?rS)rresultrVs rr?zSearchItem.dicts **w rr1)r-rKr,r#r+rJr.rr/rrS float | Noner!NonerO)r$r%r&r'rPr5r? __classcell__)rVs@rrRrRvscWI#"      8rrRc8eZdZUdZded< ded< dZded<y ) GetOpaOperation to retrieve a specific item by its namespace and key. This operation allows precise retrieval of stored items using their full path (namespace) and unique identifier (key) combination. ???+ example "Examples" Basic item retrieval: ```python GetOp(namespace=("users", "profiles"), key="user123") GetOp(namespace=("cache", "embeddings"), key="doc456") ``` rKr-r#r,TrM refresh_ttlN)r$r%r&r'__annotations__r^rrrr]r]s1  HKrr]cleZdZUdZded< dZded< dZded < d Zded < dZd ed < dZ ded<y)SearchOpaTOperation to search for items within a specified namespace hierarchy. This operation supports both structured filtering and natural language search within a given namespace prefix. It provides pagination through limit and offset parameters. !!! note Natural language search support depends on your store implementation. ???+ example "Examples" Search with filters and pagination: ```python SearchOp( namespace_prefix=("documents",), filter={"type": "report", "status": "active"}, limit=5, offset=10 ) ``` Natural language search: ```python SearchOp( namespace_prefix=("users", "content"), query="technical documentation about APIs", limit=20 ) ``` rKnamespace_prefixNdict[str, Any] | Nonefilter rNlimitroffset str | NonequeryTrMr^) r$r%r&r'r_rdrfrgrir^rrrrarasb D&% %)F !("HE3OBFCO:E:Krra*.)prefixsuffixc(eZdZUdZded< ded<y)MatchConditionaRepresents a pattern for matching namespaces in the store. This class combines a match type (prefix or suffix) with a namespace path pattern that can include wildcards to flexibly match different namespace hierarchies. ???+ example "Examples" Prefix matching: ```python MatchCondition(match_type="prefix", path=("users", "profiles")) ``` Suffix matching with wildcard: ```python MatchCondition(match_type="suffix", path=("cache", "*")) ``` Simple suffix matching: ```python MatchCondition(match_type="suffix", path=("v1",)) ``` NamespaceMatchType match_type NamespacePathpathNr$r%r&r'r_rrrrnrnMs6#"0 (!Iz  E31FCO6rrucTeZdZUdZded< ded< ded< dZd ed < dZd ed <y) PutOpzOperation to store, update, or delete an item in the store. This class represents a single operation to modify the store's contents, whether adding new items, updating existing ones, or removing them. rKr-r#r,rcr+N!Literal[False] | list[str] | NoneindexrYttl)r$r%r&r'r_r}r~rrrr{r{sQ 4 H !  04E ,3"FCrr{NceZdZdZy)InvalidNamespaceErrorzProvided namespace is invalid.N)r$r%r&r'rrrrrs(rrc4eZdZUdZded< ded< ded<y) TTLConfigz;Configuration for TTL (time-to-live) behavior in the store.rMrefresh_on_readrY default_ttlrwsweep_interval_minutesNrsrrrrr!s*E  '&rrF)totalc4eZdZUdZded< ded< ded<y) IndexConfigzConfiguration for indexing documents for semantic search in the store. If not provided to the store, the store will not support vector search. In that case, all `index` arguments to `put()` and `aput()` operations will be ignored. rNdimsz3Embeddings | EmbeddingsFunc | AEmbeddingsFunc | strembedzlist[str] | NonefieldsNrsrrrrr:s/ I  ?>EN "rrceZdZUdZdZded<dZded<dZedd Z edd Z dd  dd Z ddd ddd ddZ de d d dZd!dZdddddd d"dZdd  ddZddd ddd ddZ de d d dZd!dZdddddd d"dZy)# BaseStoreaOAbstract base class for persistent key-value stores. Stores enable persistence and memory that can be shared across threads, scoped to user IDs, assistant IDs, or other arbitrary namespaces. Some implementations may support semantic search capabilities through an optional `index` configuration. Note: Semantic search capabilities vary by implementation and are typically disabled by default. Stores that support this feature can be configured by providing an `index` configuration at creation time. Without this configuration, semantic search is disabled and any `index` arguments to storage operations will have no effect. Similarly, TTL (time-to-live) support is disabled by default. Subclasses must explicitly set `supports_ttl = True` to enable this feature. FrM supports_ttlNTTLConfig | None ttl_config) __weakref__cy)a@Execute multiple operations synchronously in a single batch. Args: ops: An iterable of operations to execute. Returns: A list of results, where each result corresponds to an operation in the input. The order of results matches the order of input operations. Nrropss rbatchzBaseStore.batchsrc Kyw)aAExecute multiple operations asynchronously in a single batch. Args: ops: An iterable of operations to execute. Returns: A list of results, where each result corresponds to an operation in the input. The order of results matches the order of input operations. Nrrs rabatchzBaseStore.abatchss)r^c ||jt|t|t|j|gdS)aRetrieve a single item. Args: namespace: Hierarchical path for the item. key: Unique identifier within the namespace. refresh_ttl: Whether to refresh TTLs for the returned item. If `None`, uses the store's default `refresh_ttl` setting. If no TTL is specified, this argument is ignored. Returns: The retrieved item or `None` if not found. r)rr]r#_ensure_refreshrrr-r,r^s rgetz BaseStore.gets;&zz 9c#h(U V W   rrer)rirdrfrgr^c p|jt|||||t|j|gdS)aQSearch for items within a namespace prefix. Args: namespace_prefix: Hierarchical path prefix to search within. query: Optional query for natural language search. filter: Key-value pairs to filter results. limit: Maximum number of items to return. offset: Number of items to skip before returning results. refresh_ttl: Whether to refresh TTLs for the returned items. If no TTL is specified, this argument is ignored. Returns: List of items matching the search criteria. ???+ example "Examples" Basic filtering: ```python # Search for documents with specific metadata results = store.search( ("docs",), filter={"type": "article", "status": "published"} ) ``` Natural language search (requires vector store implementation): ```python # Initialize store with embedding configuration store = YourStore( # e.g., InMemoryStore, AsyncPostgresStore index={ "dims": 1536, # embedding dimensions "embed": your_embedding_function, # function to create embeddings "fields": ["text"] # fields to embed. Defaults to ["$"] } ) # Search for semantically similar documents results = store.search( ("docs",), query="machine learning applications in healthcare", filter={"type": "research_paper"}, limit=5 ) ``` !!! note Natural language search support depends on your store implementation and requires proper embedding configuration. r)rrarrrrbrirdrfrgr^s rsearchzBaseStore.searchsJ@zz$#DOO[A       rr~c t||tdfvr/|js#td|jj d|j t|t|||t|j|gy)aP Store or update an item in the store. Args: namespace: Hierarchical path for the item, represented as a tuple of strings. Example: `("documents", "user123")` key: Unique identifier within the namespace. Together with namespace forms the complete path to the item. value: Dictionary containing the item's data. Must contain string keys and JSON-serializable values. index: Controls how the item's fields are indexed for search: - None (default): Use `fields` you configured when creating the store (if any) If you do not initialize the store with indexing capabilities, the `index` parameter will be ignored - False: Disable indexing for this item - `list[str]`: List of field paths to index, supporting: - Nested fields: `"metadata.title"` - Array access: `"chapters[*].content"` (each indexed separately) - Specific indices: `"authors[0].name"` ttl: Time to live in minutes. Support for this argument depends on your store adapter. If specified, the item will expire after this many minutes from when it was last accessed. None means no expiration. Expired runs will be deleted opportunistically. By default, the expiration timer refreshes on both read operations (get/search) and write operations (put/update), whenever the item is included in the operation. Note: Indexing support depends on your store implementation. If you do not initialize the store with indexing capabilities, the `index` parameter will be ignored. Similarly, TTL support depends on the specific store implementation. Some implementations may not support expiration of items. ???+ example "Examples" Store item. Indexing depends on how you configure the store: ```python store.put(("docs",), "report", {"memory": "Will likes ai"}) ``` Do not index item for semantic search. Still accessible through `get()` and `search()` operations but won't have a vector representation. ```python store.put(("docs",), "report", {"memory": "Will likes ai"}, index=False) ``` Index specific fields for search: ```python store.put(("docs",), "report", {"memory": "Will likes ai"}, index=["memory"]) ``` NTTL is not supported by ?. Use a store implementation that supports TTL or set ttl=None.r}r~) _validate_namespace NOT_PROVIDEDrNotImplementedErrorrVr$rr{r# _ensure_ttlrrr-r,r+r}r~s rputz BaseStore.putPs~ I& |T* *43D3D%*4>>+B+B*CDPQ  H#DOOS9   rcT|jt|t|ddgy)zDelete an item. Args: namespace: Hierarchical path for the item. key: Unique identifier within the namespace. Nr)rr{r#rr-r,s rdeletezBaseStore.deletes" E)SXt>?@rry)rkrlrxrfrgcg}|r|jtd||r|jtd|tt||||}|j |gdS)aList and filter namespaces in the store. Used to explore the organization of data, find specific collections, or navigate the namespace hierarchy. Args: prefix: Filter namespaces that start with this path. suffix: Filter namespaces that end with this path. max_depth: Return namespaces up to this depth in the hierarchy. Namespaces deeper than this level will be truncated. limit: Maximum number of namespaces to return. offset: Number of namespaces to skip for pagination. Returns: A list of namespace tuples that match the criteria. Each tuple represents a full namespace path up to `max_depth`. ???+ example "Examples": Setting `max_depth=3`. Given the namespaces: ```python # Example if you have the following namespaces: # ("a", "b", "c") # ("a", "b", "d", "e") # ("a", "b", "d", "i") # ("a", "b", "f") # ("a", "c", "f") store.list_namespaces(prefix=("a", "b"), max_depth=3) # [("a", "b", "c"), ("a", "b", "d"), ("a", "b", "f")] ``` rkrprrrlrvrxrfrgr)appendrnrur2rrrkrlrxrfrgrvops rlist_namespaceszBaseStore.list_namespacessoR   # #NhV$T U   # #NhV$T U "#34   zz2$""rc K|jt|t|t|j|gd{dS7w)zAsynchronously retrieve a single item. Args: namespace: Hierarchical path for the item. key: Unique identifier within the namespace. Returns: The retrieved item or `None` if not found. Nr)rr]r#rrrs ragetzBaseStore.agetsR"++!C'E     s>A AA c K|jt|||||t|j|gd{dS7w)aAsynchronously search for items within a namespace prefix. Args: namespace_prefix: Hierarchical path prefix to search within. query: Optional query for natural language search. filter: Key-value pairs to filter results. limit: Maximum number of items to return. offset: Number of items to skip before returning results. refresh_ttl: Whether to refresh TTLs for the returned items. If `None`, uses the store's `TTLConfig.refresh_default` setting. If `TTLConfig` is not provided or no TTL is specified, this argument is ignored. Returns: List of items matching the search criteria. ???+ example "Examples" Basic filtering: ```python # Search for documents with specific metadata results = await store.asearch( ("docs",), filter={"type": "article", "status": "published"} ) ``` Natural language search (requires vector store implementation): ```python # Initialize store with embedding configuration store = YourStore( # e.g., InMemoryStore, AsyncPostgresStore index={ "dims": 1536, # embedding dimensions "embed": your_embedding_function, # function to create embeddings "fields": ["text"] # fields to embed } ) # Search for semantically similar documents results = await store.asearch( ("docs",), query="machine learning applications in healthcare", filter={"type": "research_paper"}, limit=5 ) ``` !!! note Natural language search support depends on your store implementation and requires proper embedding configuration. Nr)rrarrrs rasearchzBaseStore.asearchsXD++('E        s8AAAc "Kt||tdfvr/|js#td|jj d|j t|t|||t|j|gd{y7w)al Asynchronously store or update an item in the store. Args: namespace: Hierarchical path for the item, represented as a tuple of strings. Example: `("documents", "user123")` key: Unique identifier within the namespace. Together with namespace forms the complete path to the item. value: Dictionary containing the item's data. Must contain string keys and JSON-serializable values. index: Controls how the item's fields are indexed for search: - None (default): Use `fields` you configured when creating the store (if any) If you do not initialize the store with indexing capabilities, the `index` parameter will be ignored - False: Disable indexing for this item - `list[str]`: List of field paths to index, supporting: - Nested fields: `"metadata.title"` - Array access: `"chapters[*].content"` (each indexed separately) - Specific indices: `"authors[0].name"` ttl: Time to live in minutes. Support for this argument depends on your store adapter. If specified, the item will expire after this many minutes from when it was last accessed. None means no expiration. Expired runs will be deleted opportunistically. By default, the expiration timer refreshes on both read operations (get/search) and write operations (put/update), whenever the item is included in the operation. Note: Indexing support depends on your store implementation. If you do not initialize the store with indexing capabilities, the `index` parameter will be ignored. Similarly, TTL support depends on the specific store implementation. Some implementations may not support expiration of items. ???+ example "Examples" Store item. Indexing depends on how you configure the store: ```python await store.aput(("docs",), "report", {"memory": "Will likes ai"}) ``` Do not index item for semantic search. Still accessible through `get()` and `search()` operations but won't have a vector representation. ```python await store.aput(("docs",), "report", {"memory": "Will likes ai"}, index=False) ``` Index specific fields for search (if store configured to index items): ```python await store.aput( ("docs",), "report", { "memory": "Will likes ai", "context": [{"content": "..."}, {"content": "..."}] }, index=["memory", "context[*].content"] ) ``` Nrrr) rrrrrVr$rr{r#rrrs raputzBaseStore.aputMsN I& |T* *43D3D%*4>>+B+B*CDPQ kkH#DOOS9    sBBB BclK|jt|t|dgd{y7w)zAsynchronously delete an item. Args: namespace: Hierarchical path for the item. key: Unique identifier within the namespace. N)rr{r#rs radeletezBaseStore.adeletes*kk5CHd;<===s *424cKg}|r|jtd||r|jtd|tt||||}|j |gd{dS7w)aList and filter namespaces in the store asynchronously. Used to explore the organization of data, find specific collections, or navigate the namespace hierarchy. Args: prefix: Filter namespaces that start with this path. suffix: Filter namespaces that end with this path. max_depth: Return namespaces up to this depth in the hierarchy. Namespaces deeper than this level will be truncated to this depth. limit: Maximum number of namespaces to return. offset: Number of namespaces to skip for pagination. Returns: A list of namespace tuples that match the criteria. Each tuple represents a full namespace path up to `max_depth`. ???+ example "Examples" Setting `max_depth=3` with existing namespaces: ```python # Given the following namespaces: # ("a", "b", "c") # ("a", "b", "d", "e") # ("a", "b", "d", "i") # ("a", "b", "f") # ("a", "c", "f") await store.alist_namespaces(prefix=("a", "b"), max_depth=3) # Returns: [("a", "b", "c"), ("a", "b", "d"), ("a", "b", "f")] ``` rkrrlrNr)rrnrur2rrs ralist_namespaceszBaseStore.alist_namespacessyR   # #NhV$T U   # #NhV$T U "#34   kk2$''++'sA,A8.A6/A8)rz Iterable[Op]r!z list[Result])r-rKr,r#r^ bool | Noner!z Item | None)rbrKrirhrdrcrfrNrgrNr^rr!zlist[SearchItem]r1) r-rKr,r#r+rJr}r|r~float | None | NotProvidedr!rZ)r-rKr,r#r!rZ) rkNamespacePath | NonerlrrxrwrfrNrgrNr!zlist[tuple[str, ...]])r$r%r&r'rr_rrPrrrrrrrrrrrrrrrrrrrs$L$#'J ' I        $(  "  !    8!(,#'K )K  K & K K K !K  K d48 O +7O "O O  O 1 O (O  O bA(,'+ $5#%5#% 5#  5#  5#5# 5#x$(  "  !    B!(,#'N )N  N & N N N !N  N j48 W +7W "W W  W 1 W (W  W r>(,'+ $5,%5,% 5,  5,  5,5, 5,rrc |s td|D]c}t|ts(td|d|dt|jdd|vrtd|d|d|rTtd|d||d d k(rtd |y) NzNamespace cannot be empty.zInvalid namespace label 'z ' found in z,. Namespace labels must be strings, but got .z0. Namespace labels cannot contain periods ('.').z.Namespace labels cannot be empty strings. Got z in r langgraphz5Root label for namespace cannot be "langgraph". Got: )rr3r#typer$)r-labels rrrs #$@AA %%'+E7+i[I--1%[-A-A,B!E  %<'+E7+i[Hxy '@tI;W  |{"#CI; O  #rc4||S||jddSy)NrT)r)rr^s rrrs+~~/66 rc>|tur|r|jdSy|S)Nr)rr)rr~s rrrs& l >>-0 0 Jr)rr)Opr{r]rarurnrqror rrr)r-rKr!rZr1)rrr^rr!rM)rrr~rr!rY)2r' __future__rabcrrcollections.abcrrtypingrr r r r langchain_core.embeddingsr typing_extensionsrlanggraph.store.base.embedrrrrrrrr)rRr]rar2r#rqrornrur{rr=Result ValueErrorrrrrrrr__all__rrrrs ##$1&} @R@RF$$N+J+\hzhXcGCL(#-.  /0 =Z =F<7z<7~gJgT X 00 T T*- -U38_0E E L)J) 2)5Dh,h,V 0>B /: '3  # r