Skip to content

armgit / letta

Public Imported from GitHub
0

Platform for stateful agents: AI with advanced memory that can learn and self-improve over time.

feat: Write functionality for undoing block checkpoints (#1490)

Matthew Zhou78ec7a54f783
diff --git a/letta/services/block_manager.py b/letta/services/block_manager.py
index 3bf6996de..178859b07 100644
--- a/letta/services/block_manager.py
+++ b/letta/services/block_manager.py
@@ -162,7 +162,6 @@ class BlockManager:
Note: We only have a single commit at the end, to avoid weird intermediate states.
e.g. created a BlockHistory, but the block update failed
"""
- """If `use_preloaded_block` is given, skip re-reading from DB."""
with self.session_maker() as session:
# 1) Load the block via the ORM
if use_preloaded_block is not None:
@@ -194,8 +193,71 @@ class BlockManager:
# 5) Now just flush; SQLAlchemy will:
block = block.update(db_session=session, actor=actor, no_commit=True)
-
session.commit()
# Return the block’s new state
return block.to_pydantic()
+
+ @enforce_types
+ def undo_checkpoint_block(self, block_id: str, actor: PydanticUser, use_preloaded_block: Optional[BlockModel] = None) -> PydanticBlock:
+ """
+ Move the block to the previous checkpoint by copying fields
+ from the immediately previous BlockHistory entry (sequence_number - 1).
+
+ 1) Load the current block (either by merging a preloaded block or reading from DB).
+ 2) Identify its current history entry. If none, there's nothing to undo.
+ 3) Determine the previous checkpoint's sequence_number. If seq=1, we can't go earlier.
+ 4) Copy state from that previous checkpoint into the block.
+ 5) Commit transaction (optimistic lock check).
+ 6) Return the updated block as Pydantic.
+
+ Raises:
+ ValueError: If no previous checkpoint exists or if we can't find the matching row.
+ NoResultFound: If the block or block history row do not exist.
+ StaleDataError: If another transaction updated the block concurrently (optimistic locking).
+ """
+ with self.session_maker() as session:
+ # 1) Load the block
+ if use_preloaded_block is not None:
+ block = session.merge(use_preloaded_block)
+ else:
+ block = BlockModel.read(db_session=session, identifier=block_id, actor=actor)
+
+ if not block.current_history_entry_id:
+ # There's no known history entry to revert from
+ raise ValueError(f"Block {block_id} has no history entry - cannot undo.")
+
+ # 2) Fetch the current history entry
+ current_entry = session.get(BlockHistory, block.current_history_entry_id)
+ if not current_entry:
+ raise NoResultFound(f"BlockHistory row not found for id={block.current_history_entry_id}")
+
+ current_seq = current_entry.sequence_number
+ if current_seq <= 1:
+ # This means there's no previous checkpoint
+ raise ValueError(f"Block {block_id} is at the first checkpoint (seq=1). Cannot undo further.")
+
+ # 3) The previous checkpoint is current_seq - 1
+ previous_seq = current_seq - 1
+ prev_entry = (
+ session.query(BlockHistory)
+ .filter(BlockHistory.block_id == block.id, BlockHistory.sequence_number == previous_seq)
+ .one_or_none()
+ )
+ if not prev_entry:
+ raise NoResultFound(f"No BlockHistory row for block_id={block.id} at sequence_number={previous_seq}")
+
+ # 4) Copy fields from the prev_entry back to the block
+ block.description = prev_entry.description
+ block.label = prev_entry.label
+ block.value = prev_entry.value
+ block.limit = prev_entry.limit
+ block.metadata_ = prev_entry.metadata_
+ block.current_history_entry_id = prev_entry.id
+
+ # 5) Commit with optimistic locking. We do a single commit at the end.
+ block = block.update(db_session=session, actor=actor, no_commit=True)
+ session.commit()
+
+ # 6) Return the block’s new state in Pydantic form
+ return block.to_pydantic()
diff --git a/tests/test_managers.py b/tests/test_managers.py
index 938be4c7f..109d6a16e 100644
--- a/tests/test_managers.py
+++ b/tests/test_managers.py
@@ -2581,7 +2581,7 @@ def test_get_agents_for_block(server: SyncServer, sarah_agent, charles_agent, de
# ======================================================================================================================
-# Block Manager Tests - History (Undo/Redo/Checkpoint)
+# Block Manager Tests - Checkpointing
# ======================================================================================================================
@@ -2727,6 +2727,158 @@ def test_checkpoint_concurrency_stale(server: SyncServer, default_user):
)
+# ======================================================================================================================
+# Block Manager Tests - Undo
+# ======================================================================================================================
+
+
+def test_undo_checkpoint_block(server: SyncServer, default_user):
+ """
+ Verifies that we can undo to the previous checkpoint:
+ 1) Create a block and checkpoint -> sequence_number=1
+ 2) Update block content and checkpoint -> sequence_number=2
+ 3) Undo -> should revert block to sequence_number=1's content
+ """
+ block_manager = BlockManager()
+
+ # 1) Create block
+ initial_value = "Version 1 content"
+ created_block = block_manager.create_or_update_block(PydanticBlock(label="undo_test", value=initial_value), actor=default_user)
+
+ # 2) First checkpoint => seq=1
+ block_manager.checkpoint_block(block_id=created_block.id, actor=default_user)
+
+ # 3) Update block content to "Version 2"
+ updated_data = PydanticBlock(**created_block.dict())
+ updated_data.value = "Version 2 content"
+ block_manager.create_or_update_block(updated_data, actor=default_user)
+
+ # 4) Second checkpoint => seq=2
+ block_manager.checkpoint_block(block_id=created_block.id, actor=default_user)
+
+ # 5) Undo => revert to seq=1
+ undone_block = block_manager.undo_checkpoint_block(block_id=created_block.id, actor=default_user)
+
+ # 6) Verify the block is now restored to "Version 1" content
+ assert undone_block.value == initial_value, "Block should revert to version 1 content"
+ assert undone_block.label == "undo_test", "Label should also revert if changed (or remain the same if unchanged)"
+
+
+def test_undo_no_history(server: SyncServer, default_user):
+ """
+ If a block has never been checkpointed (no current_history_entry_id),
+ undo_checkpoint_block should raise a ValueError.
+ """
+ block_manager = BlockManager()
+
+ # Create a block but don't checkpoint it
+ block = block_manager.create_or_update_block(PydanticBlock(label="no_history_test", value="initial"), actor=default_user)
+
+ # Attempt to undo
+ with pytest.raises(ValueError, match="has no history entry - cannot undo"):
+ block_manager.undo_checkpoint_block(block_id=block.id, actor=default_user)
+
+
+def test_undo_first_checkpoint(server: SyncServer, default_user):
+ """
+ If the block is at the first checkpoint (sequence_number=1),
+ undo should fail because there's no prior checkpoint.
+ """
+ block_manager = BlockManager()
+
+ # 1) Create the block
+ block_data = PydanticBlock(label="first_checkpoint", value="Version1")
+ block = block_manager.create_or_update_block(block_data, actor=default_user)
+
+ # 2) First checkpoint => seq=1
+ block_manager.checkpoint_block(block_id=block.id, actor=default_user)
+
+ # Attempt undo -> expect ValueError
+ with pytest.raises(ValueError, match="Cannot undo further"):
+ block_manager.undo_checkpoint_block(block_id=block.id, actor=default_user)
+
+
+def test_undo_multiple_checkpoints(server: SyncServer, default_user):
+ """
+ Tests multiple checkpoints in a row, then undo repeatedly
+ from seq=3 -> seq=2 -> seq=1, verifying each revert.
+ """
+ block_manager = BlockManager()
+
+ # Step 1: Create block
+ block_data = PydanticBlock(label="multi_checkpoint", value="v1")
+ block_v1 = block_manager.create_or_update_block(block_data, actor=default_user)
+ # checkpoint => seq=1
+ block_manager.checkpoint_block(block_id=block_v1.id, actor=default_user)
+
+ # Step 2: Update to v2, checkpoint => seq=2
+ block_data_v2 = PydanticBlock(**block_v1.dict())
+ block_data_v2.value = "v2"
+ block_manager.create_or_update_block(block_data_v2, actor=default_user)
+ block_manager.checkpoint_block(block_id=block_v1.id, actor=default_user)
+
+ # Step 3: Update to v3, checkpoint => seq=3
+ block_data_v3 = PydanticBlock(**block_v1.dict())
+ block_data_v3.value = "v3"
+ block_manager.create_or_update_block(block_data_v3, actor=default_user)
+ block_manager.checkpoint_block(block_id=block_v1.id, actor=default_user)
+
+ # Now we have 3 seq: v1, v2, v3
+ # Undo from seq=3 -> seq=2
+ undone_block = block_manager.undo_checkpoint_block(block_v1.id, actor=default_user)
+ assert undone_block.value == "v2"
+
+ # Undo from seq=2 -> seq=1
+ undone_block = block_manager.undo_checkpoint_block(block_v1.id, actor=default_user)
+ assert undone_block.value == "v1"
+
+ # Try once more -> fails because seq=1 is the earliest
+ with pytest.raises(ValueError, match="Cannot undo further"):
+ block_manager.undo_checkpoint_block(block_v1.id, actor=default_user)
+
+
+def test_undo_concurrency_stale(server: SyncServer, default_user):
+ """
+ Demonstrate concurrency: both sessions start with the block at seq=2,
+ one session undoes first -> block now seq=1, version increments,
+ the other session tries to undo with stale data -> StaleDataError.
+ """
+ block_manager = BlockManager()
+
+ # 1) create block
+ block_data = PydanticBlock(label="concurrency_undo", value="v1")
+ block_v1 = block_manager.create_or_update_block(block_data, actor=default_user)
+ # checkpoint => seq=1
+ block_manager.checkpoint_block(block_v1.id, actor=default_user)
+
+ # 2) update to v2
+ block_data_v2 = PydanticBlock(**block_v1.dict())
+ block_data_v2.value = "v2"
+ block_manager.create_or_update_block(block_data_v2, actor=default_user)
+ # checkpoint => seq=2
+ block_manager.checkpoint_block(block_v1.id, actor=default_user)
+
+ # Now block is at seq=2
+
+ # session1 preloads the block
+ with db_context() as s1:
+ block_s1 = s1.get(Block, block_v1.id) # version=? let's say 2 in memory
+
+ # session2 also preloads the block
+ with db_context() as s2:
+ block_s2 = s2.get(Block, block_v1.id) # also version=2
+
+ # Session1 -> undo to seq=1
+ block_manager.undo_checkpoint_block(
+ block_id=block_v1.id, actor=default_user, use_preloaded_block=block_s1 # stale object from session1
+ )
+ # This commits first => block now points to seq=1, version increments
+
+ # Session2 tries the same undo, but it's stale
+ with pytest.raises(StaleDataError):
+ block_manager.undo_checkpoint_block(block_id=block_v1.id, actor=default_user, use_preloaded_block=block_s2) # also seq=2 in memory
+
+
# ======================================================================================================================
# Identity Manager Tests
# ======================================================================================================================