agent-checkpoint-framework 0.1.0__py3-none-any.whl

agent_checkpoint/__init__.py

@@ -0,0 +1,24 @@
+from .codec import ParseResult, emit, emit_json, parse
+from .factory import new_checkpoint, resume_from
+from .manager import CheckpointManager
+from .models import Checkpoint, CheckpointStatus, RetryStrategy
+from .storage import InMemoryStorage, Storage
+from .validator import ValidationError
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Checkpoint",
+    "CheckpointStatus",
+    "RetryStrategy",
+    "ValidationError",
+    "ParseResult",
+    "parse",
+    "emit",
+    "emit_json",
+    "new_checkpoint",
+    "resume_from",
+    "CheckpointManager",
+    "Storage",
+    "InMemoryStorage",
+]

agent_checkpoint/codec.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Union
+
+from .models import Checkpoint, CheckpointStatus, RetryStrategy
+from .validator import ValidationError, validate
+
+
+@dataclass
+class ParseResult:
+    """The result of a parse operation."""
+
+    ok: bool
+    checkpoint: Optional[Checkpoint]
+    errors: List[ValidationError]
+
+
+def parse(data: Union[str, Dict[str, Any]]) -> ParseResult:
+    """
+    Parses a JSON string or dictionary into a Checkpoint object.
+    Performs validation and returns a ParseResult.
+    """
+    if isinstance(data, str):
+        try:
+            raw_dict = json.loads(data)
+        except json.JSONDecodeError as e:
+            return ParseResult(
+                ok=False,
+                checkpoint=None,
+                errors=[ValidationError("json", f"Invalid JSON: {str(e)}")],
+            )
+    else:
+        raw_dict = data
+
+    # 1. Validate the dictionary
+    errors = validate(raw_dict)
+    if errors:
+        return ParseResult(ok=False, checkpoint=None, errors=errors)
+
+    # 2. Build Checkpoint from dict
+    try:
+        # Convert enum strings to actual enum members for the constructor
+        status = CheckpointStatus(raw_dict["status"])
+
+        retry_strategy = None
+        if raw_dict.get("retry_strategy"):
+            retry_strategy = RetryStrategy(raw_dict["retry_strategy"])
+
+        checkpoint = Checkpoint(
+            # Required fields
+            ac_version=raw_dict["ac_version"],
+            checkpoint_id=raw_dict["checkpoint_id"],
+            task_id=raw_dict["task_id"],
+            agent_id=raw_dict["agent_id"],
+            emitted_at=raw_dict["emitted_at"],
+            status=status,
+            task_summary=raw_dict["task_summary"],
+            # Optional fields
+            completed_steps=raw_dict.get("completed_steps", []),
+            remaining_steps=raw_dict.get("remaining_steps", []),
+            partial_output=raw_dict.get("partial_output"),
+            failure_reason=raw_dict.get("failure_reason"),
+            confidence=raw_dict.get("confidence"),
+            retry_strategy=retry_strategy,
+            executor_hint=raw_dict.get("executor_hint"),
+            context_snapshot=raw_dict.get("context_snapshot"),
+            parent_checkpoint_id=raw_dict.get("parent_checkpoint_id"),
+        )
+        return ParseResult(ok=True, checkpoint=checkpoint, errors=[])
+    except (KeyError, ValueError, TypeError) as e:
+        # This catch-all handles unexpected type mismatches not caught by validate()
+        return ParseResult(
+            ok=False,
+            checkpoint=None,
+            errors=[ValidationError("internal", f"Failed to instantiate Checkpoint: {str(e)}")],
+        )
+
+
+def emit(checkpoint: Checkpoint) -> Dict[str, Any]:
+    """
+    Converts a Checkpoint to a dictionary for serialization.
+    Omits fields with None values entirely.
+    """
+    # Use __dict__ to avoid complex serialization of nested objects if any,
+    # but since Checkpoint is simple dataclass, this works well.
+    raw = checkpoint.__dict__.copy()
+
+    # Clean up enums and omit None values
+    clean: Dict[str, Any] = {}
+    for k, v in raw.items():
+        if v is None:
+            continue
+
+        # Handle enums
+        if isinstance(v, (CheckpointStatus, RetryStrategy)):
+            clean[k] = v.value
+        else:
+            clean[k] = v
+
+    return clean
+
+
+def emit_json(checkpoint: Checkpoint, indent: int = 2) -> str:
+    """
+    Converts a Checkpoint to a JSON string.
+    """
+    return json.dumps(emit(checkpoint), indent=indent, default=str)

agent_checkpoint/factory.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+
+from .models import Checkpoint, CheckpointStatus
+
+
+def new_checkpoint(
+    task_id: str,
+    agent_id: str,
+    task_summary: str,
+    status: CheckpointStatus = CheckpointStatus.PARTIAL,
+) -> Checkpoint:
+    """
+    Creates a new Checkpoint for a fresh task.
+    """
+    return Checkpoint(
+        ac_version="0.1.0",
+        checkpoint_id=str(uuid.uuid4()),
+        task_id=task_id,
+        agent_id=agent_id,
+        emitted_at=datetime.now(timezone.utc).isoformat(),
+        status=status,
+        task_summary=task_summary,
+    )
+
+
+def resume_from(previous: Checkpoint, agent_id: str) -> Checkpoint:
+    """
+    Creates a new Checkpoint linked to a previous one, preserving task context.
+    """
+    return Checkpoint(
+        ac_version="0.1.0",
+        checkpoint_id=str(uuid.uuid4()),
+        task_id=previous.task_id,
+        agent_id=agent_id,
+        emitted_at=datetime.now(timezone.utc).isoformat(),
+        status=CheckpointStatus.PARTIAL,
+        task_summary=previous.task_summary,
+        completed_steps=list(previous.completed_steps),  # copy the list
+        parent_checkpoint_id=previous.checkpoint_id,
+    )

agent_checkpoint/manager.py

@@ -0,0 +1,55 @@
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+from .models import Checkpoint, CheckpointStatus, RetryStrategy
+from .storage import Storage
+
+
+class CheckpointManager:
+    """Coordinates checkpoint creation and retrieval based on SPEC.md."""
+
+    def __init__(self, storage: Storage):
+        self.storage = storage
+
+    def create_checkpoint(
+        self,
+        task_id: str,
+        agent_id: str,
+        task_summary: str,
+        status: CheckpointStatus = CheckpointStatus.PARTIAL,
+        completed_steps: Optional[List[str]] = None,
+        remaining_steps: Optional[List[str]] = None,
+        partial_output: Optional[Dict[str, Any]] = None,
+        failure_reason: Optional[str] = None,
+        confidence: Optional[float] = None,
+        retry_strategy: Optional[RetryStrategy] = None,
+        executor_hint: Optional[str] = None,
+        context_snapshot: Optional[Dict[str, Any]] = None,
+        parent_checkpoint_id: Optional[str] = None,
+    ) -> Checkpoint:
+        """Creates and saves a new checkpoint following the spec."""
+        checkpoint = Checkpoint(
+            ac_version="0.1.0",
+            checkpoint_id=str(uuid.uuid4()),
+            task_id=task_id,
+            agent_id=agent_id,
+            emitted_at=datetime.now(timezone.utc).isoformat(),
+            status=status,
+            task_summary=task_summary,
+            completed_steps=completed_steps or [],
+            remaining_steps=remaining_steps or [],
+            partial_output=partial_output or {},
+            failure_reason=failure_reason,
+            confidence=confidence,
+            retry_strategy=retry_strategy,
+            executor_hint=executor_hint,
+            context_snapshot=context_snapshot or {},
+            parent_checkpoint_id=parent_checkpoint_id,
+        )
+        self.storage.save(checkpoint)
+        return checkpoint
+
+    def get_checkpoint(self, checkpoint_id: str) -> Optional[Checkpoint]:
+        """Retrieves a checkpoint by ID."""
+        return self.storage.load(checkpoint_id)

agent_checkpoint/models.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Dict, List, Optional
+
+
+class CheckpointStatus(StrEnum):
+    """Status of the checkpoint as defined in SPEC.md."""
+
+    PARTIAL = "partial"
+    FAILED = "failed"
+    PAUSED = "paused"
+    COMPLETED = "completed"
+
+
+class RetryStrategy(StrEnum):
+    """Strategy for continuation as defined in SPEC.md."""
+
+    RESUME = "resume"
+    RESTART = "restart"
+    ESCALATE = "escalate"
+
+
+@dataclass(frozen=True)
+class Checkpoint:
+    """
+    Represents a single point in time for an agent's state, following SPEC.md.
+
+    Validation:
+    - confidence: None or between 0.0 and 1.0 (inclusive)
+    - executor_hint: None, 'same', 'any', or starts with 'capability:'
+    """
+
+    # Required fields (no defaults)
+    ac_version: str
+    checkpoint_id: str
+    task_id: str
+    agent_id: str
+    emitted_at: str
+    status: CheckpointStatus
+    task_summary: str
+
+    # Optional fields
+    completed_steps: List[str] = field(default_factory=list)
+    remaining_steps: List[str] = field(default_factory=list)
+    partial_output: Optional[Dict[str, object]] = None
+    failure_reason: Optional[str] = None
+    confidence: Optional[float] = None
+    retry_strategy: Optional[RetryStrategy] = None
+    executor_hint: Optional[str] = None
+    context_snapshot: Optional[Dict[str, object]] = None
+    parent_checkpoint_id: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        """Validate input constraints."""
+        if self.confidence is not None:
+            if not (0.0 <= self.confidence <= 1.0):
+                raise ValueError(f"Confidence must be between 0.0 and 1.0; got {self.confidence}")
+
+        if self.executor_hint is not None:
+            if not (
+                self.executor_hint in ("same", "any")
+                or self.executor_hint.startswith("capability:")
+            ):
+                raise ValueError(
+                    f"executor_hint must be 'same', 'any', or start with 'capability:'; "
+                    f"got {self.executor_hint}"
+                )
+
+
+__all__ = ["CheckpointStatus", "RetryStrategy", "Checkpoint"]

agent_checkpoint/storage.py

@@ -0,0 +1,39 @@
+from abc import ABC, abstractmethod
+from typing import Dict, List, Optional
+
+from .models import Checkpoint
+
+
+class Storage(ABC):
+    """Abstract base class for checkpoint storage."""
+
+    @abstractmethod
+    def save(self, checkpoint: Checkpoint) -> None:
+        """Persist a checkpoint."""
+        pass
+
+    @abstractmethod
+    def load(self, checkpoint_id: str) -> Optional[Checkpoint]:
+        """Retrieve a checkpoint by ID."""
+        pass
+
+    @abstractmethod
+    def list_all(self) -> List[Checkpoint]:
+        """List all stored checkpoints."""
+        pass
+
+
+class InMemoryStorage(Storage):
+    """Simple in-memory implementation of checkpoint storage."""
+
+    def __init__(self) -> None:
+        self._checkpoints: Dict[str, Checkpoint] = {}
+
+    def save(self, checkpoint: Checkpoint) -> None:
+        self._checkpoints[checkpoint.checkpoint_id] = checkpoint
+
+    def load(self, checkpoint_id: str) -> Optional[Checkpoint]:
+        return self._checkpoints.get(checkpoint_id)
+
+    def list_all(self) -> List[Checkpoint]:
+        return list(self._checkpoints.values())

agent_checkpoint/validator.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Dict, List
+
+from .models import CheckpointStatus, RetryStrategy
+
+
+@dataclass
+class ValidationError:
+    """Represents a single validation failure."""
+
+    field: str
+    message: str
+
+
+# UUID v4 pattern (simplified but strict enough for spec compliance)
+UUID_V4_PATTERN = re.compile(
+    r"^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", re.IGNORECASE
+)
+SEMVER_PATTERN = re.compile(r"^\d+\.\d+\.\d+$")
+
+
+def validate(data: Dict[str, Any]) -> List[ValidationError]:
+    """
+    Validates a dictionary against the agent-checkpoint specification.
+    Returns a list of ValidationError objects; an empty list indicates success.
+    """
+    errors: List[ValidationError] = []
+
+    # 1. Required fields presence and basic type check
+    required_fields = [
+        "ac_version",
+        "checkpoint_id",
+        "task_id",
+        "agent_id",
+        "emitted_at",
+        "status",
+        "task_summary",
+    ]
+
+    for field in required_fields:
+        if field not in data:
+            errors.append(ValidationError(field, "Field is missing"))
+        elif not isinstance(data[field], str) or not data[field].strip():
+            errors.append(ValidationError(field, "Field must be a non-empty string"))
+
+    # If basic requirements are missing, we still continue to check patterns for existing fields
+
+    # 2. Pattern and Logic Validations
+    if "ac_version" in data and isinstance(data["ac_version"], str):
+        if not SEMVER_PATTERN.match(data["ac_version"]):
+            errors.append(
+                ValidationError("ac_version", "Must match semver pattern \\d+\\.\\d+\\.\\d+")
+            )
+
+    # UUID checks
+    for uuid_field in ["checkpoint_id", "task_id", "parent_checkpoint_id"]:
+        if uuid_field in data and data[uuid_field] is not None:
+            if not isinstance(data[uuid_field], str):
+                errors.append(ValidationError(uuid_field, "Must be a string"))
+            elif not UUID_V4_PATTERN.match(data[uuid_field]):
+                errors.append(ValidationError(uuid_field, "Must be a valid UUID v4"))
+
+    # Timestamp check
+    if "emitted_at" in data and isinstance(data["emitted_at"], str):
+        try:
+            # Handle the 'Z' suffix which fromisoformat might not like in older 3.11 patches
+            ts = data["emitted_at"].replace("Z", "+00:00")
+            datetime.fromisoformat(ts)
+        except ValueError:
+            errors.append(ValidationError("emitted_at", "Must be a valid ISO 8601 timestamp"))
+
+    # Enum checks
+    if "status" in data and isinstance(data["status"], str):
+        if data["status"] not in [s.value for s in CheckpointStatus]:
+            errors.append(
+                ValidationError(
+                    "status", f"Must be one of: {', '.join(s.value for s in CheckpointStatus)}"
+                )
+            )
+
+    if "retry_strategy" in data and data["retry_strategy"] is not None:
+        if data["retry_strategy"] not in [r.value for r in RetryStrategy]:
+            errors.append(
+                ValidationError(
+                    "retry_strategy", f"Must be one of: {', '.join(r.value for r in RetryStrategy)}"
+                )
+            )
+
+    # Confidence check
+    if "confidence" in data and data["confidence"] is not None:
+        if not isinstance(data["confidence"], (int, float)):
+            errors.append(ValidationError("confidence", "Must be a number"))
+        elif not (0.0 <= float(data["confidence"]) <= 1.0):
+            errors.append(ValidationError("confidence", "Must be between 0.0 and 1.0"))
+
+    # Executor hint check
+    if "executor_hint" in data and data["executor_hint"] is not None:
+        val = data["executor_hint"]
+        if not isinstance(val, str):
+            errors.append(ValidationError("executor_hint", "Must be a string"))
+        elif not (val in ("same", "any") or val.startswith("capability:")):
+            errors.append(
+                ValidationError(
+                    "executor_hint", "Must be 'same', 'any', or start with 'capability:'"
+                )
+            )
+
+    return errors

agent_checkpoint_framework-0.1.0.dist-info/METADATA

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: agent-checkpoint-framework
+Version: 0.1.0
+Summary: Never lose work when an agent fails.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+
+# Agent Checkpoint
+
+Never lose work when an agent fails.
+
+## Features
+
+- **Industrialized OOP Structure**: Clean separation of concerns between models, storage, and management.
+- **Flexible Storage**: Abstract base class allows for multiple storage backends (In-Memory, File-system, Database).
+- **Type Safe**: Fully type-hinted and compatible with `mypy`.
+- **CI Ready**: Pre-configured with GitHub Actions, `ruff`, and `pytest`.
+
+## Architecture
+
+- `Checkpoint`: Immutable data model for agent states.
+- `Storage`: Interface for persisting and retrieving checkpoints.
+- `CheckpointManager`: Central API for creating and managing checkpoints.
+
+## Development
+
+```bash
+pip install -e .[dev]
+ruff check .
+mypy src
+pytest
+```

agent_checkpoint_framework-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+agent_checkpoint/__init__.py,sha256=vWeOPeehA9pgXrxPjKKJD1X5-35XhEcERFnRdGJ8vwM,581
+agent_checkpoint/codec.py,sha256=z6TmeRLyNGhhSeYAxlWcYIXtsn-g7USn6Le-T5_VajA,3615
+agent_checkpoint/factory.py,sha256=fBR1fxjoCAUfB3wESAwiRXNxy0wptqxK638T5NEG-9E,1219
+agent_checkpoint/manager.py,sha256=UC4gjC7DOdP9TWOTmJmKFgLJow2iDzIcZof0X-ApfH8,2057
+agent_checkpoint/models.py,sha256=dm96BVb9Ul7ZqBGo2hD0YScoi2_hcp4uvqgLdkL5u28,2165
+agent_checkpoint/storage.py,sha256=L0oDYv6CeLefAq07uEoMu8LvOFRREecL51pwu33wJaQ,1082
+agent_checkpoint/validator.py,sha256=XOFuMBEoCxyzEwgKEtZQxDb44lseypvj55Iz0rXvslM,4197
+agent_checkpoint_framework-0.1.0.dist-info/METADATA,sha256=SCqo3AFYLdqKGUeQKWYve5PSK64YqXwb0pyfpB3Zt50,1077
+agent_checkpoint_framework-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+agent_checkpoint_framework-0.1.0.dist-info/top_level.txt,sha256=PwvaVmUYakHhI7DYlzlDk2dZotS_olNFvb5xU02rvas,17
+agent_checkpoint_framework-0.1.0.dist-info/RECORD,,

agent_checkpoint_framework-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agent_checkpoint_framework-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agent_checkpoint