agent-checkpoint-framework 0.2.0__tar.gz → 0.3.0__tar.gz

{agent_checkpoint_framework-0.2.0 → agent_checkpoint_framework-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-checkpoint-framework
-Version: 0.2.0
+Version: 0.3.0
 Summary: Never lose work when an agent fails.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{agent_checkpoint_framework-0.2.0 → agent_checkpoint_framework-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-checkpoint-framework"
-version = "0.2.0"
+version = "0.3.0"
 description = "Never lose work when an agent fails."
 readme = "README.md"
 requires-python = ">=3.11"

{agent_checkpoint_framework-0.2.0 → agent_checkpoint_framework-0.3.0}/src/agent_checkpoint/__init__.py

@@ -1,6 +1,7 @@
 from .codec import ParseResult, emit, emit_json, parse
 from .factory import new_checkpoint, resume_from
 from .manager import CheckpointManager
+from .manifest import AgentManifest, emit_manifest, parse_manifest
 from .models import Checkpoint, CheckpointStatus, RetryStrategy, TrustedValue, TrustTier
 from .storage import InMemoryStorage, Storage
 from .validator import ValidationError
@@ -23,4 +24,7 @@ __all__ = [
     "CheckpointManager",
     "Storage",
     "InMemoryStorage",
+    "AgentManifest",
+    "parse_manifest",
+    "emit_manifest",
 ]

agent_checkpoint_framework-0.3.0/src/agent_checkpoint/manifest.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from typing import Any, Dict, List, Optional, Union
+
+
+@dataclass
+class ConfidenceRange:
+    """Range of confidence scores the agent operates within."""
+
+    min: float = 0.0
+    max: float = 1.0
+
+    def __post_init__(self) -> None:
+        if not (0.0 <= self.min <= 1.0):
+            raise ValueError(f"min must be between 0.0 and 1.0; got {self.min}")
+        if not (0.0 <= self.max <= 1.0):
+            raise ValueError(f"max must be between 0.0 and 1.0; got {self.max}")
+        if self.min > self.max:
+            raise ValueError(f"min ({self.min}) cannot be greater than max ({self.max})")
+
+
+@dataclass
+class AgentManifest:
+    """Manifest describing an agent's capabilities and constraints."""
+
+    ac_version: str
+    agent_id: str
+    capabilities: List[str]
+    refuses: List[str] = field(default_factory=list)
+    confidence_range: Optional[ConfidenceRange] = None
+    max_context_tokens: Optional[int] = None
+    contact: Optional[str] = None
+
+
+def parse_manifest(data: Union[str, Dict[str, Any]]) -> Optional[AgentManifest]:
+    """
+    Parses a JSON string or dictionary into an AgentManifest object.
+    Returns None on any error or if required fields are missing.
+    """
+    try:
+        if isinstance(data, str):
+            raw_dict = json.loads(data)
+        else:
+            raw_dict = data
+
+        if not isinstance(raw_dict, dict):
+            return None
+
+        # Check required fields
+        if (
+            "ac_version" not in raw_dict
+            or "agent_id" not in raw_dict
+            or "capabilities" not in raw_dict
+        ):
+            return None
+
+        conf_range = None
+        raw_conf = raw_dict.get("confidence_range")
+        if isinstance(raw_conf, dict):
+            try:
+                conf_range = ConfidenceRange(
+                    min=float(raw_conf.get("min", 0.0)),
+                    max=float(raw_conf.get("max", 1.0)),
+                )
+            except (ValueError, TypeError):
+                # If confidence range is invalid, we continue without it
+                pass
+
+        return AgentManifest(
+            ac_version=str(raw_dict["ac_version"]),
+            agent_id=str(raw_dict["agent_id"]),
+            capabilities=list(raw_dict["capabilities"]),
+            refuses=list(raw_dict.get("refuses", [])),
+            confidence_range=conf_range,
+            max_context_tokens=raw_dict.get("max_context_tokens"),
+            contact=raw_dict.get("contact"),
+        )
+    except Exception:
+        # Never raise, return None on any failure
+        return None
+
+
+def emit_manifest(manifest: AgentManifest) -> str:
+    """
+    Converts an AgentManifest to a JSON string.
+    Omits fields with None values.
+    """
+    raw = asdict(manifest)
+
+    def _remove_none(obj: Any) -> Any:
+        if isinstance(obj, dict):
+            return {k: _remove_none(v) for k, v in obj.items() if v is not None}
+        return obj
+
+    clean = _remove_none(raw)
+    return json.dumps(clean, indent=2)

{agent_checkpoint_framework-0.2.0 → agent_checkpoint_framework-0.3.0}/src/agent_checkpoint_framework.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-checkpoint-framework
-Version: 0.2.0
+Version: 0.3.0
 Summary: Never lose work when an agent fails.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{agent_checkpoint_framework-0.2.0 → agent_checkpoint_framework-0.3.0}/src/agent_checkpoint_framework.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ src/agent_checkpoint/__init__.py
 src/agent_checkpoint/codec.py
 src/agent_checkpoint/factory.py
 src/agent_checkpoint/manager.py
+src/agent_checkpoint/manifest.py
 src/agent_checkpoint/models.py
 src/agent_checkpoint/storage.py
 src/agent_checkpoint/validator.py
@@ -14,4 +15,5 @@ src/agent_checkpoint_framework.egg-info/requires.txt
 src/agent_checkpoint_framework.egg-info/top_level.txt
 tests/test_codec.py
 tests/test_factory.py
-tests/test_manager.py
+tests/test_manager.py
+tests/test_manifest.py

agent_checkpoint_framework-0.3.0/tests/test_manifest.py

@@ -0,0 +1,109 @@
+import json
+
+import pytest
+
+from agent_checkpoint import AgentManifest, emit_manifest, parse_manifest
+from agent_checkpoint.manifest import ConfidenceRange
+
+
+@pytest.fixture
+def valid_manifest_dict():
+    return {
+        "ac_version": "0.1.0",
+        "agent_id": "reviewer-gpt-4",
+        "capabilities": ["code-review", "unit-testing"],
+        "confidence_range": {"min": 0.6, "max": 0.9},
+        "contact": "support@example.com",
+    }
+
+
+def test_parse_manifest_valid_dict(valid_manifest_dict):
+    manifest = parse_manifest(valid_manifest_dict)
+    assert isinstance(manifest, AgentManifest)
+    assert manifest.agent_id == "reviewer-gpt-4"
+    assert manifest.capabilities == ["code-review", "unit-testing"]
+    assert manifest.confidence_range.min == 0.6
+
+
+def test_parse_manifest_valid_json_string(valid_manifest_dict):
+    json_str = json.dumps(valid_manifest_dict)
+    manifest = parse_manifest(json_str)
+    assert isinstance(manifest, AgentManifest)
+    assert manifest.agent_id == "reviewer-gpt-4"
+
+
+def test_parse_manifest_missing_agent_id(valid_manifest_dict):
+    data = valid_manifest_dict.copy()
+    del data["agent_id"]
+    # Should return None, never raise
+    manifest = parse_manifest(data)
+    assert manifest is None
+
+
+def test_parse_manifest_invalid_json():
+    manifest = parse_manifest("{invalid json")
+    assert manifest is None
+
+
+def test_emit_manifest_produces_valid_json(valid_manifest_dict):
+    manifest = parse_manifest(valid_manifest_dict)
+    json_str = emit_manifest(manifest)
+    data = json.loads(json_str)
+    assert data["agent_id"] == "reviewer-gpt-4"
+
+
+def test_emit_manifest_omits_none_fields(valid_manifest_dict):
+    data = valid_manifest_dict.copy()
+    if "contact" in data:
+        del data["contact"]
+    manifest = parse_manifest(data)
+    json_str = emit_manifest(manifest)
+    assert "contact" not in json_str
+
+
+def test_manifest_round_trip(valid_manifest_dict):
+    manifest = parse_manifest(valid_manifest_dict)
+    json_str = emit_manifest(manifest)
+    round_tripped = parse_manifest(json_str)
+    assert manifest == round_tripped
+
+
+def test_confidence_range_validation():
+    # Valid
+    ConfidenceRange(min=0.1, max=0.5)
+    # Invalid: min > max
+    with pytest.raises(ValueError, match="cannot be greater than max"):
+        ConfidenceRange(min=0.8, max=0.2)
+    # Invalid: out of bounds
+    with pytest.raises(ValueError, match="between 0.0 and 1.0"):
+        ConfidenceRange(min=-0.1, max=0.5)
+
+
+def test_agent_agnostic_usage():
+    """
+    Demonstrates that an agent doesn't need to know about manifests
+    to receive and use checkpoints.
+    """
+    # A checkpoint with a capability hint
+    checkpoint_data = {
+        "ac_version": "0.1.0",
+        "checkpoint_id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
+        "task_id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
+        "agent_id": "source-agent",
+        "emitted_at": "2026-06-16T14:30:00Z",
+        "status": "partial",
+        "task_summary": "Review code",
+        "executor_hint": "capability:code-review",
+    }
+
+    # An agent receives this. It doesn't call parse_manifest.
+    # It just looks at the hint.
+    hint = checkpoint_data.get("executor_hint")
+    assert hint == "capability:code-review"
+
+    # It can decide to handle it based on its own internal logic
+    # without ever seeing an agent-caps.json manifest.
+    if hint.startswith("capability:"):
+        capability = hint.split(":")[1]
+        assert capability == "code-review"
+        # Proceed to handle...