Skip to main content

​
Checkpoints Module

The checkpoints module provides file-level checkpointing using a shadow git repository to track and restore file changes made by agents.

​
Installation

pip install praisonaiagents

​
Features

  • Automatic checkpointing before file modifications
  • Rewind to any previous checkpoint
  • Diff between checkpoints
  • Restore files and conversation state together

​
Quick Start

from praisonaiagents.checkpoints import CheckpointService

# Create checkpoint service
service = CheckpointService(
    workspace_dir="/path/to/project",
    storage_dir="~/.praisonai/checkpoints"
)

# Initialize shadow git
await service.initialize()

# Save a checkpoint
checkpoint_id = await service.save("Before refactoring")

# Restore to a checkpoint
await service.restore(checkpoint_id)

​
Classes

​
CheckpointService

Main service for managing checkpoints. 
from praisonaiagents.checkpoints import CheckpointService

service = CheckpointService(
    workspace_dir="/path/to/project",
    storage_dir="~/.praisonai/checkpoints"
)

​
Constructor

ParameterTypeDescription
workspace_dirstrDirectory to track
storage_dirstrWhere to store checkpoints

​
Methods

MethodDescription
initialize()Initialize the shadow git repository
save(message)Save a checkpoint with a message
restore(checkpoint_id)Restore to a specific checkpoint
diff(from_id, to_id)Get diff between two checkpoints
list()List all checkpoints
get(checkpoint_id)Get checkpoint details
delete(checkpoint_id)Delete a checkpoint

​
Checkpoint

Represents a single checkpoint. 
from praisonaiagents.checkpoints import Checkpoint

checkpoint = Checkpoint(
    id="abc123",
    message="Before refactoring",
    timestamp=datetime.now(),
    files_changed=["src/main.py", "src/utils.py"]
)

​
Attributes

AttributeTypeDescription
idstrUnique checkpoint ID
messagestrCheckpoint message
timestampdatetimeWhen checkpoint was created
files_changedlist[str]List of changed files
metadatadictAdditional metadata

​
CheckpointDiff

Diff between two checkpoints. 
from praisonaiagents.checkpoints import CheckpointDiff

diff = await service.diff(from_id, to_id)
print(diff.added_files)
print(diff.modified_files)
print(diff.deleted_files)

​
Attributes

AttributeTypeDescription
from_idstrSource checkpoint ID
to_idstrTarget checkpoint ID
added_fileslist[str]Files added
modified_fileslist[str]Files modified
deleted_fileslist[str]Files deleted
diff_contentstrFull diff content

​
CheckpointConfig

Configuration for checkpoint service. 
from praisonaiagents.checkpoints import CheckpointConfig

config = CheckpointConfig(
    auto_checkpoint=True,
    max_checkpoints=100,
    exclude_patterns=["*.log", "node_modules/*"]
)

​
Attributes

AttributeTypeDefaultDescription
auto_checkpointboolTrueAuto-checkpoint before changes
max_checkpointsint100Maximum checkpoints to keep
exclude_patternslist[str][]Patterns to exclude

​
CheckpointEvent

Events emitted by the checkpoint service. 
from praisonaiagents.checkpoints import CheckpointEvent

# Available events
CheckpointEvent.CREATED    # Checkpoint created
CheckpointEvent.RESTORED   # Checkpoint restored
CheckpointEvent.DELETED    # Checkpoint deleted

​
Usage Examples

​
Basic Checkpointing

from praisonaiagents.checkpoints import CheckpointService

async def main():
    service = CheckpointService(workspace_dir="./my_project")
    await service.initialize()
    
    # Save checkpoint before making changes
    cp1 = await service.save("Initial state")
    
    # ... agent makes changes ...
    
    # Save another checkpoint
    cp2 = await service.save("After feature implementation")
    
    # View diff
    diff = await service.diff(cp1, cp2)
    print(f"Modified: {diff.modified_files}")
    
    # Restore if needed
    await service.restore(cp1)

​
With Agent

from praisonaiagents import Agent
from praisonaiagents.checkpoints import CheckpointService

service = CheckpointService(workspace_dir="./project")
await service.initialize()

agent = Agent(
    name="Developer",
    checkpoint_service=service  # Enable checkpointing
)

# Agent automatically creates checkpoints before file changes
result = agent.chat("Refactor the main.py file")

# List checkpoints
checkpoints = await service.list()
for cp in checkpoints:
    print(f"{cp.id}: {cp.message}")

​
Automatic Checkpointing

from praisonaiagents.checkpoints import CheckpointService, CheckpointConfig

config = CheckpointConfig(
    auto_checkpoint=True,
    max_checkpoints=50
)

service = CheckpointService(
    workspace_dir="./project",
    config=config
)

# Checkpoints are automatically created before file modifications

​
Excluding Files

from praisonaiagents.checkpoints import CheckpointService, CheckpointConfig

config = CheckpointConfig(
    exclude_patterns=[
        "*.log",
        "*.tmp",
        "node_modules/*",
        "__pycache__/*",
        ".git/*"
    ]
)

service = CheckpointService(
    workspace_dir="./project",
    config=config
)

​
Best Practices

  1. Initialize early - Initialize checkpoint service before agent starts
  2. Meaningful messages - Use descriptive checkpoint messages
  3. Exclude large files - Exclude logs, dependencies, build artifacts
  4. Limit checkpoints - Set max_checkpoints to prevent disk bloat
  5. Regular cleanup - Delete old checkpoints periodically
  • Agent - Using checkpoints with agents
  • Session - Session management