Debugging API Reference

This page documents the complete API for Clearstone's time-travel debugging system.

CheckpointManager

Creates, saves, and loads agent state checkpoints.

from clearstone.debugging import CheckpointManager

manager = CheckpointManager(checkpoint_dir=".checkpoints")

clearstone.debugging.checkpoint.CheckpointManager

Manages the creation, storage, and retrieval of checkpoints.

create_checkpoint(agent, trace, span_id)

Creates a checkpoint for a given agent at a specific span within a trace.

load_checkpoint(path)

Loads and deserializes a checkpoint from a file.

ReplayEngine

Restores agent state from checkpoints and enables interactive debugging.

from clearstone.debugging import ReplayEngine

checkpoint = manager.load_checkpoint("checkpoint.ckpt")
# Pass trace_store to access all spans in the trace
engine = ReplayEngine(checkpoint, trace_store=provider.trace_store)

clearstone.debugging.replay.ReplayEngine

Loads a checkpoint and rehydrates an agent to allow for interactive, time-travel debugging.

start_debugging_session(function_to_replay, mock_config, *args, **kwargs)

Starts an interactive debugging session using pdb.

Parameters:

Name	Type	Description	Default
function_to_replay	str	The name of the method on the agent to call.	required
mock_config	Dict[str, str]	A mapping from a span_type (e.g., "llm") to the import path of the function to mock (e.g., "my_app.utils.llm.invoke"). This tells the replay engine how to map trace data to your code.	required
*args		Positional arguments to pass to the replay method.	()
**kwargs		Keyword arguments to pass to the replay method.	{}

Example

mock_config = { "llm": "finops_autopilot.tools.llm.invoke", "tool": "finops_autopilot.tools.cloud_api.run_tool" } engine.start_debugging_session("run_analysis_step", mock_config=mock_config)

Checkpoint Models

Checkpoint

Complete snapshot of agent state at a specific execution point.

checkpoint = manager.create_checkpoint(agent, trace, span_id)

print(f"Agent: {checkpoint.agent_class_path}")
print(f"Timestamp: {checkpoint.timestamp_ns}")
print(f"State: {checkpoint.agent_state}")

clearstone.debugging.checkpoint.Checkpoint

Bases: BaseModel

A snapshot of an agent's state at a specific point in a trace, designed to be rehydrated by the ReplayEngine.

CheckpointSerializer

Handles serialization and deserialization of checkpoints.

clearstone.debugging.checkpoint.CheckpointSerializer

Handles the serialization and deserialization of Checkpoint objects.

deserialize(data) staticmethod

Deserializes bytes back into a Checkpoint object.

serialize(checkpoint) staticmethod

Serializes a checkpoint using a hybrid JSON/pickle approach. Metadata is JSON for readability, while the agent state is pickled for fidelity.

Replay Utilities

DeterministicExecutionContext

Provides deterministic execution context for reproducible debugging.

clearstone.debugging.replay.DeterministicExecutionContext

A context manager that mocks non-deterministic functions (like time and random) to ensure a replay is deterministic. It can also mock user-specified external calls.

This flexible approach allows users to specify exactly which functions to mock and what their recorded return values should be, avoiding hardcoded import paths.

__enter__()

Applies all the patches.

__exit__(exc_type, exc_val, exc_tb)

Stops all patches.

__init__(checkpoint, mock_targets)

Parameters:

Name	Type	Description	Default
checkpoint	Checkpoint	The checkpoint to use for context.	required
mock_targets	Dict[str, List[Any]]	A dictionary mapping the import path of a function to mock to a list of its recorded return values. Example: {"myapp.llm.invoke": [response1, response2]}	required