Skip to content

Checkpointing APIs - #159

Open
sonleoracle wants to merge 10 commits into
mainfrom
checkpointing-support
Open

Checkpointing APIs#159
sonleoracle wants to merge 10 commits into
mainfrom
checkpointing-support

Conversation

@sonleoracle

@sonleoracle sonleoracle commented May 11, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Summary

This PR adds conversation checkpointing to WayFlowCore.

Checkpointing is integrated into normal conversation execution: conversations can be started with a Checkpointer, execution can save checkpoints at configured boundaries, and later runs can restore and resume from a saved checkpoint.

What Changed

  • Added the wayflowcore.checkpointing module with:

    • ConversationCheckpoint
    • CheckpointingInterval
    • Checkpointer
    • InMemoryCheckpointer
    • PostgresCheckpointer
    • OracleDatabaseCheckpointer

  • Added checkpoint-aware start_conversation(...) support for conversations, flows, agents, swarms, manager workers, A2A agents, and OpenAI Responses service flows.

  • Added a checkpoint execution listener that saves checkpoints after:

    • conversation turns
    • LLM turns
    • all internal turn boundaries

Example

from wayflowcore.checkpointing import InMemoryCheckpointer

checkpointer = InMemoryCheckpointer()

conversation = flow.start_conversation(
    messages="Plan a trip to Bern",
    checkpointer=checkpointer,
)

conversation.execute()

checkpoint = checkpointer.load_latest(conversation.conversation_id)

restored = flow.start_conversation(
    conversation_id=conversation.conversation_id,
    checkpoint_id=checkpoint.checkpoint_id,
    checkpointer=checkpointer,
)

restored.execute()

@oracle-contributor-agreement oracle-contributor-agreement Bot added the OCA Verified All contributors have signed the Oracle Contributor Agreement. label May 11, 2026
@sonleoracle
sonleoracle marked this pull request as ready for review May 11, 2026 14:16
@sonleoracle
sonleoracle requested a review from a team May 11, 2026 14:16
@dhilloulinoracle

dhilloulinoracle commented May 11, 2026

Copy link
Copy Markdown
Contributor

Internal regression failed: Build ID #857

@dhilloulinoracle

dhilloulinoracle commented May 11, 2026

Copy link
Copy Markdown
Contributor

Internal regression failed: Build ID #858

@sonleoracle
sonleoracle force-pushed the checkpointing-support branch from 58b840e to c9c4248 Compare May 12, 2026 09:39
@dhilloulinoracle

dhilloulinoracle commented May 12, 2026

Copy link
Copy Markdown
Contributor

Internal regression failed: Build ID #859

@dhilloulinoracle

dhilloulinoracle commented May 12, 2026

Copy link
Copy Markdown
Contributor

Internal regression failed: Build ID #860

@dhilloulinoracle

dhilloulinoracle commented May 12, 2026

Copy link
Copy Markdown
Contributor

Internal regression failed: Build ID #861

@dhilloulinoracle

dhilloulinoracle commented May 12, 2026

Copy link
Copy Markdown
Contributor

Internal regression failed: Build ID #862

@dhilloulinoracle

dhilloulinoracle commented May 12, 2026

Copy link
Copy Markdown
Contributor

Internal regression failed: Build ID #863

@dhilloulinoracle

dhilloulinoracle commented May 12, 2026

Copy link
Copy Markdown
Contributor

Internal regression succeeded 🍏: Build ID #864

@dhilloulinoracle

dhilloulinoracle commented May 12, 2026

Copy link
Copy Markdown
Contributor

Internal regression failed: Build ID #865

@dhilloulinoracle

dhilloulinoracle commented May 12, 2026

Copy link
Copy Markdown
Contributor

Internal regression failed: Build ID #867

@dhilloulinoracle

dhilloulinoracle commented May 12, 2026

Copy link
Copy Markdown
Contributor

Internal regression failed: Build ID #868

@dhilloulinoracle

dhilloulinoracle commented May 13, 2026

Copy link
Copy Markdown
Contributor

Internal regression succeeded 🍏: Build ID #871

@dhilloulinoracle

dhilloulinoracle commented May 13, 2026

Copy link
Copy Markdown
Contributor

Internal regression succeeded 🍏: Build ID #872

@dhilloulinoracle

dhilloulinoracle commented May 13, 2026

Copy link
Copy Markdown
Contributor

Internal regression succeeded 🍏: Build ID #873

@dhilloulinoracle

dhilloulinoracle commented May 13, 2026

Copy link
Copy Markdown
Contributor

Internal regression failed: Build ID #875

@dhilloulinoracle

dhilloulinoracle commented May 13, 2026

Copy link
Copy Markdown
Contributor

Internal regression succeeded 🍏: Build ID #877

@dhilloulinoracle

dhilloulinoracle commented May 15, 2026

Copy link
Copy Markdown
Contributor

Internal regression failed: Build ID #884

@dhilloulinoracle

dhilloulinoracle commented May 15, 2026

Copy link
Copy Markdown
Contributor

Internal regression failed: Build ID #886

@sonleoracle
sonleoracle force-pushed the checkpointing-support branch from ce95f95 to c2f878e Compare May 16, 2026 09:02
@dhilloulinoracle

dhilloulinoracle commented May 16, 2026

Copy link
Copy Markdown
Contributor

Internal regression failed: Build ID #889

@dhilloulinoracle

dhilloulinoracle commented May 16, 2026

Copy link
Copy Markdown
Contributor

Internal regression failed: Build ID #890

@sonleoracle
sonleoracle force-pushed the checkpointing-support branch from c2f878e to 8d2d5cc Compare June 12, 2026 14:49
@dhilloulinoracle

dhilloulinoracle commented Jun 12, 2026

Copy link
Copy Markdown
Contributor

Internal regression failed: Build ID #923

@sonleoracle
sonleoracle force-pushed the checkpointing-support branch 3 times, most recently from ee8de97 to 870abd5 Compare June 15, 2026 15:27
cesarebernardis
cesarebernardis reviewed Jul 10, 2026
View reviewed changes
Comment thread wayflowcore/src/wayflowcore/conversation.py
Comment thread wayflowcore/src/wayflowcore/agent.py Outdated
Comment thread wayflowcore/src/wayflowcore/conversationalcomponent.py Outdated
Comment thread wayflowcore/src/wayflowcore/agentserver/_storagehelpers.py Outdated
Comment thread wayflowcore/src/wayflowcore/agentserver/serverstorageconfig.py
Comment thread wayflowcore/tests/integration/test_checkpointing.py Outdated
Comment thread wayflowcore/tests/integration/test_checkpointing.py Outdated
Comment thread wayflowcore/tests/integration/test_checkpointing.py Outdated
Comment thread wayflowcore/tests/integration/test_checkpointing.py Outdated
Comment thread wayflowcore/tests/integration/test_checkpointing.py Outdated
cesarebernardis
cesarebernardis reviewed Jul 10, 2026
View reviewed changes
Comment thread wayflowcore/src/wayflowcore/checkpointing/checkpoint_state.py Outdated
Comment thread wayflowcore/src/wayflowcore/checkpointing/checkpoint_state.py Outdated
Comment thread wayflowcore/src/wayflowcore/checkpointing/checkpoint_state.py Outdated
Comment thread wayflowcore/src/wayflowcore/checkpointing/checkpoint_state.py Outdated
Comment thread wayflowcore/src/wayflowcore/steps/parallelflowexecutionstep.py Outdated
Comment thread wayflowcore/src/wayflowcore/executors/_agentconversation.py Outdated
Comment thread wayflowcore/src/wayflowcore/checkpointing/checkpointeventlistener.py Outdated
Comment thread wayflowcore/src/wayflowcore/checkpointing/checkpointeventlistener.py
Comment thread wayflowcore/src/wayflowcore/checkpointing/datastorecheckpointer.py
Comment thread wayflowcore/src/wayflowcore/checkpointing/datastorecheckpointer.py Outdated
@sonleoracle
sonleoracle force-pushed the checkpointing-support branch 4 times, most recently from de213d7 to ae5e838 Compare July 23, 2026 15:15
sonleoracle
sonleoracle commented Jul 23, 2026
View reviewed changes
Comment thread docs/wayflowcore/source/core/code_examples/howto_checkpointing.py
previous_checkpoint = checkpoints[-2]
rewound_conversation = agent.start_conversation(
conversation_id=conversation_id,
checkpoint_id=previous_checkpoint.checkpoint_id,

@sonleoracle sonleoracle Jul 23, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it be better for start_conversation to take a checkpoint object rather than a checkpoint_id ?

Comment thread wayflowcore/src/wayflowcore/agentserver/_storagehelpers.py Outdated
@sonleoracle
sonleoracle force-pushed the checkpointing-support branch 2 times, most recently from 934f6d6 to e355c9c Compare July 23, 2026 15:47
@dhilloulinoracle

dhilloulinoracle commented Jul 23, 2026

Copy link
Copy Markdown
Contributor

Internal regression failed: Build ID #972

@sonleoracle
sonleoracle force-pushed the checkpointing-support branch from e355c9c to 5f7f208 Compare July 24, 2026 09:06
jschweiz and others added 9 commits July 24, 2026 11:06
@jschweiz @sonleoracle
[feat]: add checkpointing APIs
831f783
@jschweiz @sonleoracle
[fix]: fix tests
fbd9d1e
@jschweiz @sonleoracle
[fix]: fix import
684eaab
@sonleoracle
refactor
2f9929c
@sonleoracle
revert back to id-based identity instead of names; refactor in MW/Swa…
3310980 
…rm to use agent ids instead of names for routing/keying subagents, etc
@sonleoracle
remove runtime_conversation_id and use conversation_id or conversatio…
c97d6e6 
…n.id only
@sonleoracle
address comments
3ac600a
@sonleoracle
Refactor checkpoint snapshot and restoration handling
74b6028 
  - Move live conversation checkpoint creation into Checkpointer.save().
  - Support saving either live conversations or materialized checkpoints,
    including custom checkpoint IDs, component IDs, and metadata.
  - Move checkpoint restoration and compatibility validation into
    ConversationalComponent.
  - Add explicit checkpoint support detection across conversational components,
    while marking OCI agents as unsupported.
  - Preserve root component references during serialization and deserialization
    for nested graph restoration.
  - Rename nested flow conversation startup to clarify state preservation.
  - Update checkpoint listeners and OpenAI Responses persistence to use the
    unified Checkpointer API.
  - Remove the legacy checkpoint_state module.
  - Add unit coverage for saving live conversations with custom metadata.
@sonleoracle
refactor tests
e829e44
@sonleoracle
sonleoracle force-pushed the checkpointing-support branch from 5f7f208 to e829e44 Compare July 24, 2026 09:33
@dhilloulinoracle

dhilloulinoracle commented Jul 24, 2026

Copy link
Copy Markdown
Contributor

Internal regression failed: Build ID #973

@dhilloulinoracle

dhilloulinoracle commented Jul 24, 2026

Copy link
Copy Markdown
Contributor

Internal regression failed: Build ID #974

@sonleoracle
sonleoracle force-pushed the checkpointing-support branch from 11f33b1 to 9b6f872 Compare July 24, 2026 14:21
@dhilloulinoracle

dhilloulinoracle commented Jul 24, 2026

Copy link
Copy Markdown
Contributor

Internal regression succeeded 🍏: Build ID #975

@dhilloulinoracle

dhilloulinoracle commented Aug 5, 2026

Copy link
Copy Markdown
Contributor

Internal regression succeeded 🍏: Build ID #981

@dhilloulinoracle

dhilloulinoracle commented Aug 5, 2026

Copy link
Copy Markdown
Contributor

Internal regression failed: Build ID #982

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@cesarebernardis cesarebernardis cesarebernardis left review comments
@paul-cayet paul-cayet Awaiting requested review from paul-cayet
@dhilloulinoracle dhilloulinoracle Awaiting requested review from dhilloulinoracle

At least 3 approving reviews are required to merge this pull request.

Assignees

No one assigned

Labels

OCA Verified All contributors have signed the Oracle Contributor Agreement.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@sonleoracle @dhilloulinoracle @cesarebernardis @jschweiz