tjwPddlmZddlZddlZddlmZmZmZmZm Z ddl m Z m Z m Z mZmZmZddlmZddlmZddlmZddlmZmZdd lmZdd lmZdd lmZm Z m!Z!m"Z"m#Z#ed e$e%e&Z'e(e&e&e fZ)ej*e+Z,Gd dedZ-e.e&e&e$ze%zfZ/GddeZ0d8dZ1GddeZ2GddeZ3Gdde e'Z4d9d Z5Gd!d"e6Z7d:d&Z8d;d(Z9d;d)Z: ed*e"d+e d,e!d-iZ;hd.Zdd1d=d7Z?dS)>) annotationsN) AsyncIterator CollectionIteratorMappingSequence)AnyGenericLiteral NamedTuple TypedDictTypeVar)RunnableConfig) NotRequired)uuid6)SerializerProtocolmaybe_add_typed_methods)EncryptedSerializer)JsonPlusSerializer)ERROR INTERRUPTRESUME SCHEDULEDChannelProtocolVcNeZdZUdZded< ded< ded< ded < d ed <d S) CheckpointMetadataz&Metadata associated with a checkpoint.z*Literal['input', 'loop', 'update', 'fork']sourceintstepzdict[str, str]parentsstrrun_idzdict[str, tuple[int, int]]counters_since_delta_snapshotN__name__ __module__ __qualname____doc____annotations__`/var/www/html/CA-Chatbot/venv/lib/python3.11/site-packages/langgraph/checkpoint/base/__init__.pyrr&sj006666III KKK9====r,rF)totalcfeZdZUdZded< ded< ded< ded< d ed < d ed < d ed<dS) Checkpointz(State snapshot at a given point in time.rvr"idtszdict[str, Any]channel_valuesChannelVersionschannel_versionszdict[str, ChannelVersions] versions_seenzlist[str] | Noneupdated_channelsNr%r+r,r-r0r0\s22 FFF> GGG' GGG=""""&%%% .--- '&&&r,r0 checkpointreturnc lt|d|d|d|d|dd|dD|dg|d d S) Nr1r3r2r4r6c>i|]\}}||Sr+)copy.0kr1s r- z#copy_checkpoint..s&SSStq!q!&&((SSSr,r7 pending_sendsr8r1r3r2r4r6r7rBr8)r0r=itemsget)r9s r-copy_checkpointrF~s  S/ d  d !"2388::#$67<<>>SSz//J/P/P/R/RSSS nn_b99>>@@#(:DAA    r,cNeZdZUdZded<ded<ded<dZd ed <dZd ed <dS) CheckpointTuplez8A tuple containing a checkpoint and its associated data.rconfigr0r9rmetadataNRunnableConfig | None parent_configzlist[PendingWrite] | Nonepending_writes)r&r'r(r)r*rLrMr+r,r-rHrHs^BB    +/M////04N444444r,rHc(eZdZUdZded<ded<dS)DeltaChannelHistoryuPer-channel result entry from `BaseCheckpointSaver.get_delta_channel_history`. !!! warning "Beta" Part of the `DeltaChannel` support surface; in beta. Field names and semantics may change. Storage-level view of what one channel contributed across the ancestor chain of a target checkpoint: * `writes` — on-path deltas oldest→newest as `PendingWrite` tuples. Always present; possibly empty. Already filtered to one channel. Writes stored at the target checkpoint itself are pending for the next super-step and are excluded. * `seed` — the stored value at the nearest ancestor whose `channel_values[ch]` is populated. Omitted if the walk reached the root without finding any stored value (consumer treats absence as "start empty"). Typically a `_DeltaSnapshot` for delta channels with finite snapshot frequency, or a plain value for threads migrated from a pre-delta channel type. zlist[PendingWrite]writeszNotRequired[Any]seedNr%r+r,r-rOrOs6,r,rOc0eZdZUdZeZded<dddMd ZedNd Z dOdZ dPdZ dddddQdZ dRd!Z dSdTd(ZdUd*ZdVd-ZdWd0Zd1d2dXd5ZdOd6ZdPd7ZdddddYd9ZdRd:Z dSdTd;ZdUd<ZdVd=ZdWd>Zd1d2dXd?ZdZdBZdZdCZd[dHZd\dLZdS)]BaseCheckpointSavera|Base class for creating a graph checkpointer. Checkpointers allow LangGraph agents to persist their state within and across multiple interactions. When a checkpointer is configured, you should pass a `thread_id` in the config when invoking the graph: ```python config = {"configurable": {"thread_id": "my-thread"}} graph.invoke(inputs, config) ``` The `thread_id` is the primary key used to store and retrieve checkpoints. Without it, the checkpointer cannot save state, resume from interrupts, or enable time-travel debugging. How you choose ``thread_id`` depends on your use case: - **Single-shot workflows**: Use a unique ID (e.g., uuid4) for each run when executions are independent. - **Conversational memory**: Reuse the same `thread_id` across invocations to accumulate state (e.g., chat history) within a conversation. Attributes: serde (SerializerProtocol): Serializer for encoding/decoding checkpoints. Note: When creating a custom checkpoint saver, consider implementing async versions to avoid blocking the main thread. rserdeN)rTSerializerProtocol | Noner:Nonec<t|p|j|_dS)N)rrT)selfrTs r-__init__zBaseCheckpointSaver.__init__s -U-@djAA r,listcgS)zDefine the configuration options for the checkpoint saver. Returns: list: List of configuration field specs. r+)rXs r- config_specsz BaseCheckpointSaver.config_specss  r,rIrCheckpoint | NonecB||x}r|jSdS)zFetch a checkpoint using the given configuration. Args: config: Configuration specifying which checkpoint to retrieve. Returns: The requested checkpoint, or `None` if not found. N) get_tupler9rXrIvalues r-rEzBaseCheckpointSaver.gets0NN6** *5 $# # $ $r,CheckpointTuple | Nonect)aYFetch a checkpoint tuple using the given configuration. Args: config: Configuration specifying which checkpoint to retrieve. Returns: The requested checkpoint tuple, or `None` if not found. Raises: NotImplementedError: Implement this method in your custom checkpoint saver. NotImplementedErrorrXrIs r-r_zBaseCheckpointSaver.get_tuples "!r,)filterbeforelimitrKrgdict[str, Any] | Nonerhri int | NoneIterator[CheckpointTuple]ct)aList checkpoints that match the given criteria. Args: config: Base configuration for filtering checkpoints. filter: Additional filtering criteria. before: List checkpoints created before this configuration. limit: Maximum number of checkpoints to return. Returns: Iterator of matching checkpoint tuples. Raises: NotImplementedError: Implement this method in your custom checkpoint saver. rdrXrIrgrhris r-rZzBaseCheckpointSaver.list ,"!r,r9r0rJr new_versionsr5ct)aStore a checkpoint with its configuration and metadata. Args: config: Configuration for the checkpoint. checkpoint: The checkpoint to store. metadata: Additional metadata for the checkpoint. new_versions: New channel versions as of this write. Returns: RunnableConfig: Updated configuration after storing the checkpoint. Raises: NotImplementedError: Implement this method in your custom checkpoint saver. rdrXrIr9rJrps r-putzBaseCheckpointSaver.puts *"!r,rPSequence[tuple[str, Any]]task_idr" task_pathct)aStore intermediate writes linked to a checkpoint. Args: config: Configuration of the related checkpoint. writes: List of writes to store. task_id: Identifier for the task creating the writes. task_path: Path of the task creating the writes. Raises: NotImplementedError: Implement this method in your custom checkpoint saver. rdrXrIrPrvrws r- put_writeszBaseCheckpointSaver.put_writes,s $"!r, thread_idctzDelete all checkpoints and writes associated with a specific thread ID. Args: thread_id: The thread ID whose checkpoints should be deleted. rdrXr{s r- delete_threadz!BaseCheckpointSaver.delete_thread@s "!r,run_ids Sequence[str]ct)uDelete all checkpoints and writes associated with the given run IDs. Args: run_ids: The run IDs whose checkpoints should be deleted. !!! warning "DeltaChannel" Deleting a run that produced ancestor `checkpoint_writes` — or the only `_DeltaSnapshot` blob — for a still-live thread will break reconstruction of any `DeltaChannel` whose history depended on those rows. See the `DeltaChannel` note on `prune` for safe-recovery strategies. rdrXrs r-delete_for_runsz#BaseCheckpointSaver.delete_for_runsKs ""!r,source_thread_idtarget_thread_idct)u;Copy all checkpoints and writes from one thread to another. Args: source_thread_id: The thread ID to copy from. target_thread_id: The thread ID to copy to. !!! warning "DeltaChannel" Implementations must copy the **complete** parent chain (all ancestor checkpoints and their `checkpoint_writes`) — copying only the head checkpoint will leave the target thread with `DeltaChannel` state that cannot be reconstructed (no path back to a `_DeltaSnapshot` ancestor). Equivalently, the copy must include enough ancestors that every `DeltaChannel`-backed key has either a `_DeltaSnapshot` in `channel_values` somewhere in the chain, or a complete write history back to the chain root. rdrXrrs r- copy_threadzBaseCheckpointSaver.copy_thread^ror, keep_latest)strategy thread_idsrct)uTPrune checkpoints for the given threads. Args: thread_ids: The thread IDs to prune. strategy: The pruning strategy. `"keep_latest"` retains only the most recent checkpoint per namespace. `"delete"` removes all checkpoints. !!! warning "DeltaChannel" Custom implementations must be `DeltaChannel`-aware. `DeltaChannel` stores only a sentinel in `channel_values` for non-snapshot steps; reconstruction walks the parent chain via `get_delta_channel_history`, accumulating rows from `checkpoint_writes` until it reaches an ancestor whose `channel_values` contains a `_DeltaSnapshot` blob (written every `snapshot_frequency` updates). A naive `"keep_latest"` that drops intermediate checkpoints and their writes can sever that chain: the surviving "latest" checkpoint is rarely a snapshot point itself, so its delta channels would silently reconstruct as empty (no error raised — `get_delta_channel_history` simply returns no `seed`). Safe options when the graph uses `DeltaChannel`: * Walk back from each kept checkpoint and preserve every ancestor (plus its `checkpoint_writes`) up to the nearest one whose `channel_values` already contains a `_DeltaSnapshot` for every `DeltaChannel`-backed key. * Force a fresh snapshot on the kept checkpoint before deleting ancestors — rewrite `channel_values[k] = _DeltaSnapshot(value)` for each delta channel `k` (resolving `value` via the existing ancestor walk first), then prune. * Skip pruning threads whose graph uses `DeltaChannel` until one of the above is implemented. rdrXrrs r-prunezBaseCheckpointSaver.prunevs R"!r,cRK||d{Vx}r|jSdS)zAsynchronously fetch a checkpoint using the given configuration. Args: config: Configuration specifying which checkpoint to retrieve. Returns: The requested checkpoint, or `None` if not found. N) aget_tupler9r`s r-agetzBaseCheckpointSaver.agetsF//&11111111 15 $# # $ $r,cKt)ahAsynchronously fetch a checkpoint tuple using the given configuration. Args: config: Configuration specifying which checkpoint to retrieve. Returns: The requested checkpoint tuple, or `None` if not found. Raises: NotImplementedError: Implement this method in your custom checkpoint saver. rdrfs r-rzBaseCheckpointSaver.aget_tuples"!r,AsyncIterator[CheckpointTuple]cKt)aAsynchronously list checkpoints that match the given criteria. Args: config: Base configuration for filtering checkpoints. filter: Additional filtering criteria for metadata. before: List checkpoints created before this configuration. limit: Maximum number of checkpoints to return. Returns: Async iterator of matching checkpoint tuples. Raises: NotImplementedError: Implement this method in your custom checkpoint saver. rdrns r-alistzBaseCheckpointSaver.alists,"!r,cKt)aAsynchronously store a checkpoint with its configuration and metadata. Args: config: Configuration for the checkpoint. checkpoint: The checkpoint to store. metadata: Additional metadata for the checkpoint. new_versions: New channel versions as of this write. Returns: RunnableConfig: Updated configuration after storing the checkpoint. Raises: NotImplementedError: Implement this method in your custom checkpoint saver. rdrrs r-aputzBaseCheckpointSaver.aputs*"!r,cKt)aAsynchronously store intermediate writes linked to a checkpoint. Args: config: Configuration of the related checkpoint. writes: List of writes to store. task_id: Identifier for the task creating the writes. task_path: Path of the task creating the writes. Raises: NotImplementedError: Implement this method in your custom checkpoint saver. rdrys r- aput_writeszBaseCheckpointSaver.aput_writes$"!r,cKtr}rdr~s r-adelete_threadz"BaseCheckpointSaver.adelete_threads"!r,cKt)uAsynchronously delete all checkpoints and writes for the given run IDs. Args: run_ids: The run IDs whose checkpoints should be deleted. !!! warning "DeltaChannel" See `delete_for_runs` — deleting rows a still-live thread's `DeltaChannel` reconstruction depends on (writes between the head and its nearest `_DeltaSnapshot` ancestor) will silently corrupt that channel's state. rdrs r-adelete_for_runsz$BaseCheckpointSaver.adelete_for_runs s "!r,cKt)uAsynchronously copy all checkpoints and writes from one thread to another. Args: source_thread_id: The thread ID to copy from. target_thread_id: The thread ID to copy to. !!! warning "DeltaChannel" See `copy_thread` — the copy must carry the complete parent chain (or at least back to a `_DeltaSnapshot` ancestor for every `DeltaChannel`) so the target thread can reconstruct delta state. rdrs r- acopy_threadz BaseCheckpointSaver.acopy_threadrr,cKt)axAsynchronously prune checkpoints for the given threads. Args: thread_ids: The thread IDs to prune. strategy: The pruning strategy. `"keep_latest"` retains only the most recent checkpoint per namespace. `"delete"` removes all checkpoints. !!! warning "DeltaChannel" See `prune` for the full `DeltaChannel` caveat. In short: `"keep_latest"` must not drop ancestor checkpoints / writes that sit between the kept checkpoint and the nearest `_DeltaSnapshot` ancestor, or delta channels will silently reconstruct as empty. rdrs r-aprunezBaseCheckpointSaver.aprune0s("!r,channels!Mapping[str, DeltaChannelHistory]cv|siSd|D}i}t|}||}|r|jnd}||r||}|n|jr>t |jD])} | d} | |vr|| | *t |D]<} | |jdvr+|jd| || <|| =|j}||i} |D]:} dt t || i} | |vr || | d<| | | <;| S)uWalk the parent chain returning per-channel writes + seed. !!! warning "Beta" This method is part of the `DeltaChannel` support surface and is in beta. The signature, return shape (`DeltaChannelHistory`), and interaction with `_DeltaSnapshot` blobs may change. Override at your own risk; the default implementation will continue to work against the public `BaseCheckpointSaver` contract. For each requested channel, walks ancestors of the checkpoint identified by `config` (following `parent_config`) and accumulates `pending_writes` for that channel. The walk terminates per-channel at the nearest ancestor whose `channel_values[ch]` is populated; that value is returned as `seed`. If the walk reaches the root without finding a stored value, `seed` is omitted from that channel's entry — the consumer treats the absence as "start empty." Walks the **parent chain** (not `list(before=...)`): for forked threads, only on-path ancestors contribute. The default implementation walks `get_tuple` + `parent_config` once for all channels — each ancestor visited once, not once per channel. Savers with direct storage access (`InMemorySaver`, `PostgresSaver`) override for performance; the return contract is fixed here. Args: config: Configuration identifying the target checkpoint. channels: Channel names to walk for. Empty → empty mapping. Returns: Per-channel `DeltaChannelHistory` for every name in `channels`. ci|]}|gSr+r+r?cs r-rAzABaseCheckpointSaver.get_delta_channel_history..n9R9R9RA!R9R9R9Rr,Nr4rPrQ) setr_rLrMreversedappendrZr9discard rXrIrcollected_by_ch seed_by_ch remaining target_tuple cursor_configtupwritechresultentrys r-get_delta_channel_historyz-BaseCheckpointSaver.get_delta_channel_historyFsL I9R9R9R9R9R%' !(mm ~~f-- *6 @L & &D 'I'..//C{! :%c&899::EqBY'+2259999oo * *(8999%(^4D%Eb%IJrN%%b)))-M'I'24  B*2D/RTBU9V9V4W4W)XEZ *2f F2JJ r,cK|siSd|D}i}t|}||d{V}|r|jnd}||r||d{V}|n|jr>t |jD])} | d} | |vr|| | *t |D]<} | |jdvr+|jd| || <|| =|j}||i} |D]:} dt t || i} | |vr || | d<| | | <;| S)zAsync version of `get_delta_channel_history`. !!! warning "Beta" This method is part of the `DeltaChannel` support surface and is in beta. See `get_delta_channel_history` for caveats. ci|]}|gSr+r+rs r-rAzBBaseCheckpointSaver.aget_delta_channel_history..rr,Nrr4rPrQ) rrrLrMrrrZr9rrs r-aget_delta_channel_historyz.BaseCheckpointSaver.aget_delta_channel_historys I9R9R9R9R9R%' !(mm !__V44444444 *6 @L & &D 'I' 66666666C{! :%c&899::EqBY'+2259999oo * *(8999%(^4D%Eb%IJrN%%b)))-M'I'24  B*2D/RTBU9V9V4W4W)XEZ *2f F2JJ r,currentV | NonechannelrcLt|trt|dS|dzS)aGenerate the next version ID for a channel. Default is to use integer versions, incrementing by `1`. If you override, you can use `str`/`int`/`float` versions, as long as they are monotonically increasing. Args: current: The current version identifier (`int`, `float`, or `str`). channel: Deprecated argument, kept for backwards compatibility. Returns: V: The next version identifier, which must be increasing. Nr) isinstancer"re)rXrrs r-get_next_versionz$BaseCheckpointSaver.get_next_versions0 gs # # % % _1Q; r,extra_allowlistCollection[tuple[str, ...]]BaseCheckpointSaver[V]ct|j|}||jur|Stj|}t||_|S)z8Return a shallow clone with a derived msgpack allowlist.)_with_msgpack_allowlistrTr=r)rXrrTclones r-with_allowlistz"BaseCheckpointSaver.with_allowlistsH( ODD DJ  K $-e44  r,)rTrUr:rV)r:rZ)rIrr:r])rIrr:rb) rIrKrgrjrhrKrirkr:rl) rIrr9r0rJrrpr5r:r)rt) rIrrPrurvr"rwr"r:rV)r{r"r:rV)rrr:rV)rr"rr"r:rV)rrrr"r:rV) rIrKrgrjrhrKrirkr:r)rIrrrr:r)rrrrVr:r)rrr:r) r&r'r(r)rrTr*rYpropertyr\rEr_rZrsrzrrrrrrrrrrrrrrrrrr+r,r-rSrSs@!3 2 4 4E4444 ,0BBBBBBX $ $ $ $ " " " "$)-(, """"""0""""8 """""( " " " """""&""""8& )")")")")")"V $ $ $ $ " " " "$)-(, 2""""8 """""( " " " """""$""""0& """""",CCCCJ''''R*      r,rSrTrrrcvt|tr||St|trL|j}t|tr0||}||ur|St|j|St dt|j |S)NzfSerializer %s does not support msgpack allowlist. Strict msgpack deserialization will not be enforced.) rrwith_msgpack_allowlistrrTcipherloggerwarningtyper&)rTrinner updated_inners r-rrs%+,,=++O<<<%,--D  e/ 0 0 D!88IIM%% &u|]CC C NN ? U  Lr,ceZdZdZdS)EmptyChannelErrorziRaised when attempting to get the value of a channel that hasn't been updated for the first time yet.N)r&r'r(r)r+r,r-rrs Dr,rrIr str | Nonec8|ddS)zGet checkpoint ID. configurable checkpoint_id)rE)rIs r-get_checkpoint_idrs . ! % %o 6 66r,rJcd|D}|d|dfD]}|s|D]~\}}||vs|tvs|dr(t |t r|dd||<Wt |tttfr|||<|S)9Get checkpoint metadata in a backwards-compatible manner.cpi|]3\}}|t|tr|ddn|4S)rt)rr"replacer>s r-rAz+get_checkpoint_metadata..sP Aq jC&8&8 ?199Xr " " "ar,rJr__rrt) rDrEEXCLUDED_METADATA_KEYS startswithrr"rrboolfloat)rIrJobjkeyr1s r-get_checkpoint_metadatarsNN$$H :&& >(B(BC " "  iikk " "FCh#)?"?"?3>>RVCWCW"?As## " ! (B 7 7 AT5122 " !  " Or,cXt||}d|vr|d|S)rrP)rpop)rIrJcheckpoint_metadatas r-$get_serializable_checkpoint_metadatar s:2&(CC&&&))) r,> r{r checkpoint_nscheckpoint_maplanggraph_nodelanggraph_pathlanggraph_steplanggraph_triggerslanggraph_checkpoint_nsc ddlm}m}ttt t d||jiiigdS)Nrdatetimetimezoner clock_seq)r1r2r3r4r6r7rBr8) rrr0LATEST_VERSIONr"rnowutc isoformatrs r-empty_checkpointr.sv++++++++   ur""" # # << % % / / 1 1    r,)r2r$Mapping[str, ChannelProtocol] | Noner rr2c ddlm}m}||j}| |d}nOi}|D]8\}} ||dvr | ||<)#t$rY5wxYwtt||ptt|||d|d| dgd S) z+Create a checkpoint for the given channels.rrNr4r6rr7rBrC) rrrrrrDr9rr0rr"rrE) r9rr r2rrr3valuesr@r1s r-create_checkpointr=s,+++++++ hl # # - - / /B,-NN$$  DAq #5666 LLNNq $       +UT***++#$67 1 nn_b99    s'A?? B  B )r9r0r:r0)rTrrrr:r)rIrr:r)rIrrJrr:r)r:r0) r9r0rrr rr2rr:r0)@ __future__rr=loggingcollections.abcrrrrrtypingr r r r r rlangchain_core.runnablesrtyping_extensionsrlanggraph.checkpoint.base.idrlanggraph.checkpoint.serde.baserr$langgraph.checkpoint.serde.encryptedr#langgraph.checkpoint.serde.jsonplusr langgraph.checkpoint.serde.typesrrrrrrrr"rtuple PendingWrite getLoggerr&rrdictr5r0rFrHrOrSr ExceptionrrrrWRITES_IDX_MAPrrrrr+r,r-rs"""""" RRRRRRRRRRRRRR433333))))))......WWWWWWWWDDDDDDBBBBBB GCeS!!S#s]#   8 $ $00000%0000fsC#I--.D    55555j555)6bbbbb'!*bbbJ(        7777 *YIr62F       ( r,