Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
feat: checkpoint list/info CLI commands
Greyson LaLondea5df7c798c0d
diff --git a/lib/crewai/src/crewai/cli/checkpoint_cli.py b/lib/crewai/src/crewai/cli/checkpoint_cli.pynew file mode 100644index 000000000..c61500b20--- /dev/null+++ b/lib/crewai/src/crewai/cli/checkpoint_cli.py@@ -0,0 +1,329 @@+"""CLI commands for inspecting checkpoint files."""++from __future__ import annotations++from datetime import datetime+import glob+import json+import os+import sqlite3+from typing import Any++import click+++_SQLITE_MAGIC = b"SQLite format 3\x00"++_SELECT_ALL = """+SELECT id, created_at, json(data)+FROM checkpoints+ORDER BY rowid DESC+"""++_SELECT_ONE = """+SELECT id, created_at, json(data)+FROM checkpoints+WHERE id = ?+"""++_SELECT_LATEST = """+SELECT id, created_at, json(data)+FROM checkpoints+ORDER BY rowid DESC+LIMIT 1+"""+++def _is_sqlite(path: str) -> bool:+ """Check if a file is a SQLite database by reading its magic bytes."""+ if not os.path.isfile(path):+ return False+ try:+ with open(path, "rb") as f:+ return f.read(16) == _SQLITE_MAGIC+ except OSError:+ return False+++def _parse_checkpoint_json(raw: str, source: str) -> dict[str, Any]:+ """Parse checkpoint JSON into metadata dict."""+ data = json.loads(raw)+ entities = data.get("entities", [])+ nodes = data.get("event_record", {}).get("nodes", {})+ event_count = len(nodes)++ trigger_event = None+ if nodes:+ last_node = max(+ nodes.values(),+ key=lambda n: n.get("event", {}).get("emission_sequence") or 0,+ )+ trigger_event = last_node.get("event", {}).get("type")++ parsed_entities: list[dict[str, Any]] = []+ for entity in entities:+ tasks = entity.get("tasks", [])+ completed = sum(1 for t in tasks if t.get("output") is not None)+ info: dict[str, Any] = {+ "type": entity.get("entity_type", "unknown"),+ "name": entity.get("name"),+ "id": entity.get("id"),+ }+ if tasks:+ info["tasks_completed"] = completed+ info["tasks_total"] = len(tasks)+ info["tasks"] = [+ {+ "description": t.get("description", ""),+ "completed": t.get("output") is not None,+ }+ for t in tasks+ ]+ parsed_entities.append(info)++ return {+ "source": source,+ "event_count": event_count,+ "trigger": trigger_event,+ "entities": parsed_entities,+ }+++def _format_size(size: int) -> str:+ if size < 1024:+ return f"{size}B"+ if size < 1024 * 1024:+ return f"{size / 1024:.1f}KB"+ return f"{size / 1024 / 1024:.1f}MB"+++def _ts_from_name(name: str) -> str | None:+ """Extract timestamp from checkpoint ID or filename."""+ stem = os.path.basename(name).split("_")[0].removesuffix(".json")+ try:+ dt = datetime.strptime(stem, "%Y%m%dT%H%M%S")+ except ValueError:+ return None+ return dt.strftime("%Y-%m-%d %H:%M:%S")+++def _entity_summary(entities: list[dict[str, Any]]) -> str:+ parts = []+ for ent in entities:+ etype = ent.get("type", "unknown")+ ename = ent.get("name", "")+ completed = ent.get("tasks_completed")+ total = ent.get("tasks_total")+ if completed is not None and total is not None:+ parts.append(f"{etype}:{ename} [{completed}/{total} tasks]")+ else:+ parts.append(f"{etype}:{ename}")+ return ", ".join(parts) if parts else "empty"+++# --- JSON directory ---+++def _list_json(location: str) -> list[dict[str, Any]]:+ pattern = os.path.join(location, "*.json")+ results = []+ for path in sorted(glob.glob(pattern), key=os.path.getmtime, reverse=True):+ name = os.path.basename(path)+ try:+ with open(path) as f:+ raw = f.read()+ meta = _parse_checkpoint_json(raw, source=name)+ meta["name"] = name+ meta["ts"] = _ts_from_name(name)+ meta["size"] = os.path.getsize(path)+ meta["path"] = path+ except Exception:+ meta = {"name": name, "ts": None, "size": 0, "entities": [], "source": name}+ results.append(meta)+ return results+++def _info_json_latest(location: str) -> dict[str, Any] | None:+ pattern = os.path.join(location, "*.json")+ files = sorted(glob.glob(pattern), key=os.path.getmtime, reverse=True)+ if not files:+ return None+ path = files[0]+ with open(path) as f:+ raw = f.read()+ meta = _parse_checkpoint_json(raw, source=os.path.basename(path))+ meta["name"] = os.path.basename(path)+ meta["ts"] = _ts_from_name(path)+ meta["size"] = os.path.getsize(path)+ meta["path"] = path+ return meta+++def _info_json_file(path: str) -> dict[str, Any]:+ with open(path) as f:+ raw = f.read()+ meta = _parse_checkpoint_json(raw, source=os.path.basename(path))+ meta["name"] = os.path.basename(path)+ meta["ts"] = _ts_from_name(path)+ meta["size"] = os.path.getsize(path)+ meta["path"] = path+ return meta+++# --- SQLite ---+++def _list_sqlite(db_path: str) -> list[dict[str, Any]]:+ results = []+ with sqlite3.connect(db_path) as conn:+ for row in conn.execute(_SELECT_ALL):+ checkpoint_id, created_at, raw = row+ try:+ meta = _parse_checkpoint_json(raw, source=checkpoint_id)+ meta["name"] = checkpoint_id+ meta["ts"] = _ts_from_name(checkpoint_id) or created_at+ except Exception:+ meta = {+ "name": checkpoint_id,+ "ts": created_at,+ "entities": [],+ "source": checkpoint_id,+ }+ results.append(meta)+ return results+++def _info_sqlite_latest(db_path: str) -> dict[str, Any] | None:+ with sqlite3.connect(db_path) as conn:+ row = conn.execute(_SELECT_LATEST).fetchone()+ if not row:+ return None+ checkpoint_id, created_at, raw = row+ meta = _parse_checkpoint_json(raw, source=checkpoint_id)+ meta["name"] = checkpoint_id+ meta["ts"] = _ts_from_name(checkpoint_id) or created_at+ meta["db"] = db_path+ return meta+++def _info_sqlite_id(db_path: str, checkpoint_id: str) -> dict[str, Any] | None:+ with sqlite3.connect(db_path) as conn:+ row = conn.execute(_SELECT_ONE, (checkpoint_id,)).fetchone()+ if not row:+ return None+ cid, created_at, raw = row+ meta = _parse_checkpoint_json(raw, source=cid)+ meta["name"] = cid+ meta["ts"] = _ts_from_name(cid) or created_at+ meta["db"] = db_path+ return meta+++# --- Public API ---+++def list_checkpoints(location: str) -> None:+ """List all checkpoints at a location."""+ if _is_sqlite(location):+ entries = _list_sqlite(location)+ label = f"SQLite: {location}"+ elif os.path.isdir(location):+ entries = _list_json(location)+ label = location+ else:+ click.echo(f"Not a directory or SQLite database: {location}")+ return++ if not entries:+ click.echo(f"No checkpoints found in {label}")+ return++ click.echo(f"Found {len(entries)} checkpoint(s) in {label}\n")++ for entry in entries:+ ts = entry.get("ts") or "unknown"+ name = entry.get("name", "")+ size = _format_size(entry["size"]) if "size" in entry else ""+ trigger = entry.get("trigger") or ""+ summary = _entity_summary(entry.get("entities", []))+ parts = [name, ts]+ if size:+ parts.append(size)+ if trigger:+ parts.append(trigger)+ parts.append(summary)+ click.echo(f" {' '.join(parts)}")+++def info_checkpoint(path: str) -> None:+ """Show details of a single checkpoint."""+ meta: dict[str, Any] | None = None++ # db_path#checkpoint_id format+ if "#" in path:+ db_path, checkpoint_id = path.rsplit("#", 1)+ if _is_sqlite(db_path):+ meta = _info_sqlite_id(db_path, checkpoint_id)+ if not meta:+ click.echo(f"Checkpoint not found: {checkpoint_id}")+ return++ # SQLite file — show latest+ if meta is None and _is_sqlite(path):+ meta = _info_sqlite_latest(path)+ if not meta:+ click.echo(f"No checkpoints in database: {path}")+ return+ click.echo(f"Latest checkpoint: {meta['name']}\n")++ # Directory — show latest JSON+ if meta is None and os.path.isdir(path):+ meta = _info_json_latest(path)+ if not meta:+ click.echo(f"No checkpoints found in {path}")+ return+ click.echo(f"Latest checkpoint: {meta['name']}\n")++ # Specific JSON file+ if meta is None and os.path.isfile(path):+ try:+ meta = _info_json_file(path)+ except Exception as exc:+ click.echo(f"Failed to read checkpoint: {exc}")+ return++ if meta is None:+ click.echo(f"Not found: {path}")+ return++ _print_info(meta)+++def _print_info(meta: dict[str, Any]) -> None:+ ts = meta.get("ts") or "unknown"+ source = meta.get("path") or meta.get("db") or meta.get("source", "")+ click.echo(f"Source: {source}")+ click.echo(f"Name: {meta.get('name', '')}")+ click.echo(f"Time: {ts}")+ if "size" in meta:+ click.echo(f"Size: {_format_size(meta['size'])}")+ click.echo(f"Events: {meta.get('event_count', 0)}")+ trigger = meta.get("trigger")+ if trigger:+ click.echo(f"Trigger: {trigger}")++ for ent in meta.get("entities", []):+ eid = str(ent.get("id", ""))[:8]+ click.echo(f"\n {ent['type']}: {ent.get('name', 'unnamed')} ({eid}...)")++ tasks = ent.get("tasks")+ if isinstance(tasks, list):+ click.echo(+ f" Tasks: {ent['tasks_completed']}/{ent['tasks_total']} completed"+ )+ for i, task in enumerate(tasks):+ status = "done" if task.get("completed") else "pending"+ desc = str(task.get("description", ""))+ if len(desc) > 70:+ desc = desc[:67] + "..."+ click.echo(f" {i + 1}. [{status}] {desc}")diff --git a/lib/crewai/src/crewai/cli/cli.py b/lib/crewai/src/crewai/cli/cli.pyindex c40fe656f..57ff4551a 100644--- a/lib/crewai/src/crewai/cli/cli.py+++ b/lib/crewai/src/crewai/cli/cli.py@@ -786,5 +786,28 @@ def traces_status() -> None:console.print(panel)+def checkpoint() -> None:+ """Inspect checkpoint files."""++[email protected]("list")[email protected]("location", default="./.checkpoints")+def checkpoint_list(location: str) -> None:+ """List checkpoints in a directory."""+ from crewai.cli.checkpoint_cli import list_checkpoints++ list_checkpoints(location)++[email protected]("info")[email protected]("path", default="./.checkpoints")+def checkpoint_info(path: str) -> None:+ """Show details of a checkpoint. Pass a file or directory for latest."""+ from crewai.cli.checkpoint_cli import info_checkpoint++ info_checkpoint(path)++if __name__ == "__main__":crewai()