Documentation Index
Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
Use this file to discover all available pages before exploring further.
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
| Parameter | Type | Description |
|---|
workspace_dir | str | Directory to track |
storage_dir | str | Where to store checkpoints |
Methods
| Method | Description |
|---|
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
| Attribute | Type | Description |
|---|
id | str | Unique checkpoint ID |
message | str | Checkpoint message |
timestamp | datetime | When checkpoint was created |
files_changed | list[str] | List of changed files |
metadata | dict | Additional 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
| Attribute | Type | Description |
|---|
from_id | str | Source checkpoint ID |
to_id | str | Target checkpoint ID |
added_files | list[str] | Files added |
modified_files | list[str] | Files modified |
deleted_files | list[str] | Files deleted |
diff_content | str | Full 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
| Attribute | Type | Default | Description |
|---|
auto_checkpoint | bool | True | Auto-checkpoint before changes |
max_checkpoints | int | 100 | Maximum checkpoints to keep |
exclude_patterns | list[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
- Initialize early - Initialize checkpoint service before agent starts
- Meaningful messages - Use descriptive checkpoint messages
- Exclude large files - Exclude logs, dependencies, build artifacts
- Limit checkpoints - Set max_checkpoints to prevent disk bloat
- Regular cleanup - Delete old checkpoints periodically
- Agent - Using checkpoints with agents
- Session - Session management
