agent-consistency 0.1.0__py3-none-any.whl

agent_consistency/__init__.py

@@ -0,0 +1,40 @@
+from .diff import DiffItem, RunDiff, diff_runs
+from .errors import (
+    ConsistencyError,
+    DuplicateReceiptError,
+    HandoffValidationError,
+    OutcomeVerificationError,
+    StaleStateError,
+)
+from .handoff import HandoffPacket
+from .models import ConsistencyIssue, ConsistencyReceipt, OutcomeResult, StateDelta, StateSnapshot
+from .outcome import OutcomeVerifier, verify_outcome
+from .run import AgentStep, WorkflowRun
+from .store import InMemoryReceiptStore, JsonlReceiptStore, ReceiptStore, load_receipts
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AgentStep",
+    "ConsistencyError",
+    "ConsistencyIssue",
+    "ConsistencyReceipt",
+    "DiffItem",
+    "DuplicateReceiptError",
+    "HandoffPacket",
+    "HandoffValidationError",
+    "InMemoryReceiptStore",
+    "JsonlReceiptStore",
+    "OutcomeResult",
+    "OutcomeVerificationError",
+    "OutcomeVerifier",
+    "ReceiptStore",
+    "RunDiff",
+    "StaleStateError",
+    "StateDelta",
+    "StateSnapshot",
+    "WorkflowRun",
+    "diff_runs",
+    "load_receipts",
+    "verify_outcome",
+]

agent_consistency/_time.py

@@ -0,0 +1,5 @@
+from datetime import datetime, timezone
+
+
+def utc_now_iso() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat()

agent_consistency/adapters/__init__.py

@@ -0,0 +1,15 @@
+from .azure_durable import (
+    DurableConsistencyContext,
+    durable_instance_id,
+    durable_is_replaying,
+    replay_safe_log,
+    stable_activity_key,
+)
+
+__all__ = [
+    "DurableConsistencyContext",
+    "durable_instance_id",
+    "durable_is_replaying",
+    "replay_safe_log",
+    "stable_activity_key",
+]

agent_consistency/adapters/azure_durable.py

@@ -0,0 +1,103 @@
+from collections.abc import Mapping
+from typing import Any, Optional
+
+from ..models import ConsistencyReceipt
+from ..run import WorkflowRun
+from ..serialization import stable_digest, to_jsonable
+from ..store import ReceiptStore
+
+
+def _get_attr(context: Any, *names: str) -> Any:
+    for name in names:
+        if hasattr(context, name):
+            value = getattr(context, name)
+            return value() if callable(value) else value
+        if isinstance(context, Mapping) and name in context:
+            return context[name]
+    return None
+
+
+def durable_instance_id(context: Any) -> str:
+    value = _get_attr(context, "instance_id", "instanceId", "instanceID")
+    return str(value or "durable-instance-unknown")
+
+
+def durable_is_replaying(context: Any) -> bool:
+    value = _get_attr(context, "is_replaying", "isReplaying")
+    return bool(value)
+
+
+def replay_safe_log(
+    context: Any,
+    logger: Any,
+    level: str,
+    message: str,
+    *args: Any,
+    **kwargs: Any,
+) -> None:
+    if durable_is_replaying(context):
+        return
+    log_method = getattr(logger, level)
+    log_method(message, *args, **kwargs)
+
+
+def stable_activity_key(instance_id: str, activity_name: str, intent: Mapping[str, Any]) -> str:
+    digest = stable_digest(
+        {
+            "instance_id": instance_id,
+            "activity_name": activity_name,
+            "intent": to_jsonable(intent),
+        }
+    )
+    return f"{instance_id}:{activity_name}:{digest[:16]}"
+
+
+class DurableConsistencyContext:
+    def __init__(
+        self,
+        context: Any,
+        *,
+        store: Optional[ReceiptStore] = None,
+        on_violation: str = "raise",
+    ) -> None:
+        self.context = context
+        self.run = WorkflowRun(
+            durable_instance_id(context),
+            store=store,
+            on_violation=on_violation,
+        )
+
+    @property
+    def is_replaying(self) -> bool:
+        return durable_is_replaying(self.context)
+
+    @property
+    def instance_id(self) -> str:
+        return durable_instance_id(self.context)
+
+    def step(self, *args: Any, **kwargs: Any) -> Any:
+        return self.run.step(*args, **kwargs)
+
+    def activity_key(self, activity_name: str, intent: Mapping[str, Any]) -> str:
+        return stable_activity_key(self.instance_id, activity_name, intent)
+
+    def set_custom_status(self, receipt: Optional[ConsistencyReceipt] = None) -> None:
+        setter = getattr(self.context, "set_custom_status", None) or getattr(
+            self.context,
+            "setCustomStatus",
+            None,
+        )
+        if setter is None:
+            return
+        if receipt is None:
+            receipts = self.run.receipts()
+            payload = {
+                "consistency": {
+                    "run_id": self.run.run_id,
+                    "receipt_count": len(receipts),
+                    "last_status": receipts[-1].status if receipts else "empty",
+                }
+            }
+        else:
+            payload = {"consistency": receipt.to_dict()}
+        setter(payload)

agent_consistency/diff.py

@@ -0,0 +1,164 @@
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from typing import Any, Dict, List
+
+from .models import ConsistencyReceipt
+from .serialization import to_jsonable
+
+
+@dataclass(frozen=True)
+class DiffItem:
+    kind: str
+    message: str
+    step_id: str = ""
+    left: Any = None
+    right: Any = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "kind": self.kind,
+            "step_id": self.step_id,
+            "message": self.message,
+            "left": to_jsonable(self.left),
+            "right": to_jsonable(self.right),
+        }
+
+
+@dataclass(frozen=True)
+class RunDiff:
+    differences: List[DiffItem] = field(default_factory=list)
+
+    @property
+    def is_empty(self) -> bool:
+        return not self.differences
+
+    def summary(self) -> str:
+        if self.is_empty:
+            return "No consistency differences found."
+        return "\n".join(
+            f"- [{item.kind}] {item.step_id}: {item.message}" for item in self.differences
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"differences": [item.to_dict() for item in self.differences]}
+
+
+def diff_runs(left: Iterable[ConsistencyReceipt], right: Iterable[ConsistencyReceipt]) -> RunDiff:
+    left_by_step = {receipt.step_id: receipt for receipt in left}
+    right_by_step = {receipt.step_id: receipt for receipt in right}
+    differences: List[DiffItem] = []
+
+    for missing in sorted(set(left_by_step) - set(right_by_step)):
+        differences.append(
+            DiffItem("step_missing", f"step '{missing}' exists only in left run", step_id=missing)
+        )
+    for missing in sorted(set(right_by_step) - set(left_by_step)):
+        differences.append(
+            DiffItem("step_added", f"step '{missing}' exists only in right run", step_id=missing)
+        )
+
+    for step_id in sorted(set(left_by_step) & set(right_by_step)):
+        _compare_receipts(step_id, left_by_step[step_id], right_by_step[step_id], differences)
+
+    return RunDiff(differences=differences)
+
+
+def _compare_receipts(
+    step_id: str,
+    left: ConsistencyReceipt,
+    right: ConsistencyReceipt,
+    differences: List[DiffItem],
+) -> None:
+    if left.assumptions != right.assumptions:
+        differences.append(
+            DiffItem(
+                "assumptions",
+                "assumptions diverged",
+                step_id=step_id,
+                left=left.assumptions,
+                right=right.assumptions,
+            )
+        )
+    _compare_snapshot_list(
+        step_id,
+        "state_read",
+        "state read diverged",
+        [snapshot.to_dict() for snapshot in left.state_reads],
+        [snapshot.to_dict() for snapshot in right.state_reads],
+        differences,
+    )
+    _compare_snapshot_list(
+        step_id,
+        "state_delta",
+        "state delta diverged",
+        [delta.to_dict() for delta in left.state_deltas],
+        [delta.to_dict() for delta in right.state_deltas],
+        differences,
+    )
+    _compare_list(
+        step_id,
+        "handoff",
+        "handoff packet diverged",
+        [handoff.to_dict() for handoff in left.handoffs],
+        [handoff.to_dict() for handoff in right.handoffs],
+        differences,
+        ignore_fields={"created_at"},
+    )
+    _compare_list(
+        step_id,
+        "outcome",
+        "outcome diverged",
+        [outcome.to_dict() for outcome in left.outcomes],
+        [outcome.to_dict() for outcome in right.outcomes],
+        differences,
+        ignore_fields={"checked_at"},
+    )
+
+
+def _strip_fields(payload: Any, ignore_fields: set) -> Any:
+    if isinstance(payload, Mapping):
+        return {
+            key: _strip_fields(value, ignore_fields)
+            for key, value in payload.items()
+            if key not in ignore_fields
+        }
+    if isinstance(payload, list):
+        return [_strip_fields(item, ignore_fields) for item in payload]
+    return payload
+
+
+def _compare_snapshot_list(
+    step_id: str,
+    kind: str,
+    message: str,
+    left: List[Dict[str, Any]],
+    right: List[Dict[str, Any]],
+    differences: List[DiffItem],
+) -> None:
+    _compare_list(
+        step_id,
+        kind,
+        message,
+        left,
+        right,
+        differences,
+        ignore_fields={"captured_at"},
+    )
+
+
+def _compare_list(
+    step_id: str,
+    kind: str,
+    message: str,
+    left: List[Dict[str, Any]],
+    right: List[Dict[str, Any]],
+    differences: List[DiffItem],
+    *,
+    ignore_fields: set,
+) -> None:
+    left_clean = _strip_fields(left, ignore_fields)
+    right_clean = _strip_fields(right, ignore_fields)
+    if left_clean != right_clean:
+        differences.append(
+            DiffItem(kind, message, step_id=step_id, left=left_clean, right=right_clean)
+        )

agent_consistency/errors.py

@@ -0,0 +1,36 @@
+from typing import Any, Dict, Optional
+
+
+class ConsistencyError(Exception):
+    """Base error for agent workflow consistency violations."""
+
+
+class StaleStateError(ConsistencyError):
+    def __init__(
+        self,
+        message: str,
+        *,
+        snapshot: Optional[Any] = None,
+        current: Optional[Any] = None,
+    ) -> None:
+        super().__init__(message)
+        self.snapshot = snapshot
+        self.current = current
+
+
+class HandoffValidationError(ConsistencyError):
+    def __init__(self, message: str, *, details: Optional[Dict[str, Any]] = None) -> None:
+        super().__init__(message)
+        self.details = details or {}
+
+
+class OutcomeVerificationError(ConsistencyError):
+    def __init__(self, message: str, *, result: Optional[Any] = None) -> None:
+        super().__init__(message)
+        self.result = result
+
+
+class DuplicateReceiptError(ConsistencyError):
+    def __init__(self, message: str, *, receipt_key: Optional[str] = None) -> None:
+        super().__init__(message)
+        self.receipt_key = receipt_key

agent_consistency/handoff.py

@@ -0,0 +1,109 @@
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from ._time import utc_now_iso
+from .serialization import to_jsonable
+
+
+def _get_path(payload: Mapping[str, Any], path: str) -> Any:
+    if path in payload:
+        return payload[path]
+    current: Any = payload
+    for part in path.split("."):
+        if not isinstance(current, Mapping) or part not in current:
+            return None
+        current = current[part]
+    return current
+
+
+def _is_blank(value: Any) -> bool:
+    return value is None or value == "" or value == [] or value == {}
+
+
+@dataclass(frozen=True)
+class HandoffPacket:
+    from_agent: str
+    to_agent: str
+    task: str
+    facts: Dict[str, Any] = field(default_factory=dict)
+    assumptions: List[str] = field(default_factory=list)
+    missing_info: List[str] = field(default_factory=list)
+    constraints: List[str] = field(default_factory=list)
+    evidence: Dict[str, Any] = field(default_factory=dict)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    created_at: str = field(default_factory=utc_now_iso)
+
+    def validate(
+        self,
+        *,
+        required_facts: Optional[Iterable[str]] = None,
+        required_assumptions: Optional[Iterable[str]] = None,
+        required_constraints: Optional[Iterable[str]] = None,
+        required_evidence: Optional[Iterable[str]] = None,
+    ) -> List[str]:
+        problems: List[str] = []
+        for fact in required_facts or []:
+            if _is_blank(_get_path(self.facts, fact)):
+                detail = "declared missing" if fact in self.missing_info else "missing"
+                problems.append(f"required fact '{fact}' is {detail}")
+        for assumption in required_assumptions or []:
+            if assumption not in self.assumptions:
+                problems.append(f"required assumption '{assumption}' is missing")
+        for constraint in required_constraints or []:
+            if constraint not in self.constraints:
+                problems.append(f"required constraint '{constraint}' is missing")
+        for evidence_key in required_evidence or []:
+            if _is_blank(_get_path(self.evidence, evidence_key)):
+                problems.append(f"required evidence '{evidence_key}' is missing")
+        return problems
+
+    def require_supported_claims(
+        self,
+        claims: Mapping[str, Any],
+        *,
+        by: Iterable[str],
+    ) -> List[str]:
+        support_keys = list(by)
+        missing_support = [
+            key
+            for key in support_keys
+            if _is_blank(_get_path(self.facts, key)) and _is_blank(_get_path(self.evidence, key))
+        ]
+        if not claims:
+            return ["claims cannot be empty when support is required"]
+        if missing_support:
+            return [
+                "unsupported claims "
+                f"{sorted(str(key) for key in claims)}; missing support keys {missing_support}"
+            ]
+        return []
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "from_agent": self.from_agent,
+            "to_agent": self.to_agent,
+            "task": self.task,
+            "facts": to_jsonable(self.facts),
+            "assumptions": list(self.assumptions),
+            "missing_info": list(self.missing_info),
+            "constraints": list(self.constraints),
+            "evidence": to_jsonable(self.evidence),
+            "metadata": to_jsonable(self.metadata),
+            "created_at": self.created_at,
+        }
+
+    @classmethod
+    def from_dict(cls, payload: Mapping[str, Any]) -> "HandoffPacket":
+        return cls(
+            from_agent=str(payload["from_agent"]),
+            to_agent=str(payload["to_agent"]),
+            task=str(payload["task"]),
+            facts=dict(payload.get("facts") or {}),
+            assumptions=list(payload.get("assumptions") or []),
+            missing_info=list(payload.get("missing_info") or []),
+            constraints=list(payload.get("constraints") or []),
+            evidence=dict(payload.get("evidence") or {}),
+            metadata=dict(payload.get("metadata") or {}),
+            created_at=str(payload.get("created_at") or utc_now_iso()),
+        )