macp-sdk-python 0.2.1__py3-none-any.whl

macp_sdk/quorum.py

@@ -0,0 +1,258 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from macp.modes.quorum.v1 import quorum_pb2
+from macp.v1 import envelope_pb2
+
+from .auth import AuthConfig
+from .base_projection import BaseProjection
+from .base_session import BaseSession
+from .constants import MODE_QUORUM
+from .envelope import build_envelope, serialize_message
+
+# ---------------------------------------------------------------------------
+# Projection records
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class ApprovalRequestRecord:
+    request_id: str
+    action: str
+    summary: str
+    required_approvals: int
+    requester: str
+
+
+@dataclass(slots=True)
+class BallotRecord:
+    request_id: str
+    vote: str  # "approve" | "reject" | "abstain"
+    reason: str
+    sender: str
+
+
+# ---------------------------------------------------------------------------
+# Projection
+# ---------------------------------------------------------------------------
+
+
+class QuorumProjection(BaseProjection):
+    """In-process state tracking for Quorum mode sessions.
+
+    Supports multiple concurrent approval requests within a single session.
+    Query methods accept a ``request_id`` parameter to target a specific
+    request.
+    """
+
+    MODE = MODE_QUORUM
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.phase = "Pending"
+        self.requests: dict[str, ApprovalRequestRecord] = {}
+        self.ballots: dict[str, dict[str, BallotRecord]] = {}  # request_id -> sender -> ballot
+
+    def _apply_mode_message(self, envelope: envelope_pb2.Envelope) -> None:
+        mt = envelope.message_type
+
+        if mt == "ApprovalRequest":
+            p = quorum_pb2.ApprovalRequestPayload()
+            p.ParseFromString(envelope.payload)
+            self.requests[p.request_id] = ApprovalRequestRecord(
+                request_id=p.request_id,
+                action=p.action,
+                summary=p.summary,
+                required_approvals=p.required_approvals,
+                requester=envelope.sender,
+            )
+            self.phase = "Voting"
+            return
+
+        if mt == "Approve":
+            p = quorum_pb2.ApprovePayload()
+            p.ParseFromString(envelope.payload)
+            self._set_ballot(p.request_id, envelope.sender, "approve", p.reason)
+            return
+
+        if mt == "Reject":
+            p = quorum_pb2.RejectPayload()
+            p.ParseFromString(envelope.payload)
+            self._set_ballot(p.request_id, envelope.sender, "reject", p.reason)
+            return
+
+        if mt == "Abstain":
+            p = quorum_pb2.AbstainPayload()
+            p.ParseFromString(envelope.payload)
+            self._set_ballot(p.request_id, envelope.sender, "abstain", p.reason)
+
+    def _set_ballot(self, request_id: str, sender: str, vote: str, reason: str) -> None:
+        sender_map = self.ballots.setdefault(request_id, {})
+        sender_map[sender] = BallotRecord(
+            request_id=request_id,
+            vote=vote,
+            reason=reason,
+            sender=sender,
+        )
+
+    def _count_votes(self, request_id: str, vote: str) -> int:
+        sender_map = self.ballots.get(request_id)
+        if not sender_map:
+            return 0
+        return sum(1 for b in sender_map.values() if b.vote == vote)
+
+    # -- State query helpers --
+
+    def approval_count(self, request_id: str) -> int:
+        return self._count_votes(request_id, "approve")
+
+    def rejection_count(self, request_id: str) -> int:
+        return self._count_votes(request_id, "reject")
+
+    def abstention_count(self, request_id: str) -> int:
+        return self._count_votes(request_id, "abstain")
+
+    def is_threshold_reached(self, request_id: str) -> bool:
+        req = self.requests.get(request_id)
+        if req is None:
+            return False
+        return self.approval_count(request_id) >= req.required_approvals
+
+    def is_threshold_unreachable(self, request_id: str, total_eligible: int) -> bool:
+        """True if remaining possible approvals cannot reach the threshold."""
+        req = self.requests.get(request_id)
+        if req is None:
+            return False
+        remaining = total_eligible - len(self.voted_senders(request_id))
+        return self.approval_count(request_id) + remaining < req.required_approvals
+
+    def commitment_ready(self, request_id: str) -> bool:
+        """True if the threshold is reached."""
+        return self.is_threshold_reached(request_id)
+
+    def threshold(self, request_id: str) -> int:
+        """Return the required approval count, or 0 if no request yet."""
+        req = self.requests.get(request_id)
+        return req.required_approvals if req else 0
+
+    def voted_senders(self, request_id: str) -> list[str]:
+        """Return list of senders who have cast a ballot for this request."""
+        sender_map = self.ballots.get(request_id)
+        return list(sender_map.keys()) if sender_map else []
+
+    def remaining_votes_needed(self, request_id: str) -> int:
+        """Return how many more approvals are needed to reach quorum."""
+        req = self.requests.get(request_id)
+        if req is None:
+            return 0
+        return max(0, req.required_approvals - self.approval_count(request_id))
+
+
+# ---------------------------------------------------------------------------
+# Session helper
+# ---------------------------------------------------------------------------
+
+
+class QuorumSession(BaseSession):
+    """High-level helper for Quorum mode sessions."""
+
+    MODE = MODE_QUORUM
+
+    def _create_projection(self) -> BaseProjection:
+        return QuorumProjection()
+
+    @property
+    def quorum_projection(self) -> QuorumProjection:
+        assert isinstance(self.projection, QuorumProjection)
+        return self.projection
+
+    def request_approval(
+        self,
+        request_id: str,
+        action: str,
+        *,
+        summary: str = "",
+        details: bytes = b"",
+        required_approvals: int,
+        sender: str | None = None,
+        auth: AuthConfig | None = None,
+    ) -> envelope_pb2.Ack:
+        payload = quorum_pb2.ApprovalRequestPayload(
+            request_id=request_id,
+            action=action,
+            summary=summary,
+            details=details,
+            required_approvals=required_approvals,
+        )
+        envelope = build_envelope(
+            mode=self.MODE,
+            message_type="ApprovalRequest",
+            session_id=self.session_id,
+            sender=self._sender_for(sender, auth=auth),
+            payload=serialize_message(payload),
+        )
+        return self._send_and_track(envelope, auth=auth)
+
+    def approve(
+        self,
+        request_id: str,
+        *,
+        reason: str = "",
+        sender: str | None = None,
+        auth: AuthConfig | None = None,
+    ) -> envelope_pb2.Ack:
+        payload = quorum_pb2.ApprovePayload(
+            request_id=request_id,
+            reason=reason,
+        )
+        envelope = build_envelope(
+            mode=self.MODE,
+            message_type="Approve",
+            session_id=self.session_id,
+            sender=self._sender_for(sender, auth=auth),
+            payload=serialize_message(payload),
+        )
+        return self._send_and_track(envelope, auth=auth)
+
+    def reject(
+        self,
+        request_id: str,
+        *,
+        reason: str = "",
+        sender: str | None = None,
+        auth: AuthConfig | None = None,
+    ) -> envelope_pb2.Ack:
+        payload = quorum_pb2.RejectPayload(
+            request_id=request_id,
+            reason=reason,
+        )
+        envelope = build_envelope(
+            mode=self.MODE,
+            message_type="Reject",
+            session_id=self.session_id,
+            sender=self._sender_for(sender, auth=auth),
+            payload=serialize_message(payload),
+        )
+        return self._send_and_track(envelope, auth=auth)
+
+    def abstain(
+        self,
+        request_id: str,
+        *,
+        reason: str = "",
+        sender: str | None = None,
+        auth: AuthConfig | None = None,
+    ) -> envelope_pb2.Ack:
+        payload = quorum_pb2.AbstainPayload(
+            request_id=request_id,
+            reason=reason,
+        )
+        envelope = build_envelope(
+            mode=self.MODE,
+            message_type="Abstain",
+            session_id=self.session_id,
+            sender=self._sender_for(sender, auth=auth),
+            payload=serialize_message(payload),
+        )
+        return self._send_and_track(envelope, auth=auth)

macp_sdk/retry.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+from ._logging import logger
+from .auth import AuthConfig
+from .errors import MacpRetryError, MacpTransportError
+
+# Re-export for convenience
+__all__ = ["RetryPolicy", "retry_send"]
+
+
+@dataclass(frozen=True)
+class RetryPolicy:
+    """Configuration for retry behaviour on transient failures."""
+
+    max_retries: int = 3
+    backoff_base: float = 0.1
+    backoff_max: float = 2.0
+    retryable_codes: frozenset[str] = field(
+        default_factory=lambda: frozenset({"RATE_LIMITED", "INTERNAL_ERROR"})
+    )
+
+
+def retry_send(
+    client: Any,
+    envelope: Any,
+    *,
+    policy: RetryPolicy | None = None,
+    auth: AuthConfig | None = None,
+) -> Any:
+    """Send an envelope with retries on transient failures.
+
+    Uses the client's ``send`` method. On ``MacpTransportError`` or retryable
+    NACK codes, backs off and retries up to ``policy.max_retries`` times.
+    """
+    from .errors import MacpAckError  # avoid circular
+
+    pol = policy or RetryPolicy()
+    last_error: Exception | None = None
+
+    for attempt in range(1 + pol.max_retries):
+        try:
+            return client.send(envelope, auth=auth)
+        except MacpTransportError as exc:
+            last_error = exc
+        except MacpAckError as exc:
+            if exc.failure.code not in pol.retryable_codes:
+                raise
+            last_error = exc
+
+        if attempt < pol.max_retries:
+            delay = min(pol.backoff_base * (2**attempt), pol.backoff_max)
+            logger.debug(
+                "retry attempt=%d delay=%.2fs error=%s",
+                attempt + 1,
+                delay,
+                last_error,
+            )
+            time.sleep(delay)
+
+    raise MacpRetryError(f"retries exhausted after {pol.max_retries} attempts") from last_error

macp_sdk/task.py

@@ -0,0 +1,368 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from macp.modes.task.v1 import task_pb2
+from macp.v1 import envelope_pb2
+
+from .auth import AuthConfig
+from .base_projection import BaseProjection
+from .base_session import BaseSession
+from .constants import MODE_TASK
+from .envelope import build_envelope, serialize_message
+
+# ---------------------------------------------------------------------------
+# Projection records
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class TaskRequestRecord:
+    task_id: str
+    title: str
+    instructions: str
+    requested_assignee: str
+    requester: str
+
+
+@dataclass(slots=True)
+class TaskRejectRecord:
+    task_id: str
+    assignee: str
+    reason: str
+
+
+@dataclass(slots=True)
+class TaskUpdateRecord:
+    task_id: str
+    status: str
+    progress: float
+    message: str
+
+
+@dataclass(slots=True)
+class TaskCompleteRecord:
+    task_id: str
+    assignee: str
+    summary: str
+    output: bytes
+
+
+@dataclass(slots=True)
+class TaskFailRecord:
+    task_id: str
+    assignee: str
+    error_code: str
+    reason: str
+    retryable: bool
+
+
+# ---------------------------------------------------------------------------
+# Projection
+# ---------------------------------------------------------------------------
+
+
+class TaskProjection(BaseProjection):
+    """In-process state tracking for Task mode sessions.
+
+    Supports multiple tasks within a single session.  Each task is tracked
+    independently with its own status and progress.
+    """
+
+    MODE = MODE_TASK
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.phase = "Pending"
+        self.tasks: dict[str, TaskRequestRecord] = {}
+        self.updates: list[TaskUpdateRecord] = []
+        self.completions: list[TaskCompleteRecord] = []
+        self.failures: list[TaskFailRecord] = []
+        # Per-task mutable state
+        self._assignees: dict[str, str] = {}  # task_id -> assignee
+        self._statuses: dict[str, str] = {}  # task_id -> status
+        self._progress: dict[str, float] = {}  # task_id -> progress
+
+    def _apply_mode_message(self, envelope: envelope_pb2.Envelope) -> None:
+        mt = envelope.message_type
+
+        if mt == "TaskRequest":
+            p = task_pb2.TaskRequestPayload()
+            p.ParseFromString(envelope.payload)
+            self.tasks[p.task_id] = TaskRequestRecord(
+                task_id=p.task_id,
+                title=p.title,
+                instructions=p.instructions,
+                requested_assignee=p.requested_assignee,
+                requester=envelope.sender,
+            )
+            self._statuses[p.task_id] = "requested"
+            self._progress[p.task_id] = 0.0
+            self.phase = "Requested"
+            return
+
+        if mt == "TaskAccept":
+            p = task_pb2.TaskAcceptPayload()
+            p.ParseFromString(envelope.payload)
+            assignee = p.assignee or envelope.sender
+            self._assignees[p.task_id] = assignee
+            self._statuses[p.task_id] = "accepted"
+            self.phase = "InProgress"
+            return
+
+        if mt == "TaskReject":
+            p = task_pb2.TaskRejectPayload()
+            p.ParseFromString(envelope.payload)
+            self._statuses[p.task_id] = "rejected"
+            return
+
+        if mt == "TaskUpdate":
+            p = task_pb2.TaskUpdatePayload()
+            p.ParseFromString(envelope.payload)
+            self.updates.append(
+                TaskUpdateRecord(
+                    task_id=p.task_id,
+                    status=p.status,
+                    progress=p.progress,
+                    message=p.message,
+                )
+            )
+            self._statuses[p.task_id] = "in_progress"
+            self._progress[p.task_id] = p.progress
+            return
+
+        if mt == "TaskComplete":
+            p = task_pb2.TaskCompletePayload()
+            p.ParseFromString(envelope.payload)
+            self.completions.append(
+                TaskCompleteRecord(
+                    task_id=p.task_id,
+                    assignee=p.assignee or envelope.sender,
+                    summary=p.summary,
+                    output=p.output,
+                )
+            )
+            self._statuses[p.task_id] = "completed"
+            self._progress[p.task_id] = 1.0
+            self.phase = "Completed"
+            return
+
+        if mt == "TaskFail":
+            p = task_pb2.TaskFailPayload()
+            p.ParseFromString(envelope.payload)
+            self.failures.append(
+                TaskFailRecord(
+                    task_id=p.task_id,
+                    assignee=p.assignee or envelope.sender,
+                    error_code=p.error_code,
+                    reason=p.reason,
+                    retryable=p.retryable,
+                )
+            )
+            self._statuses[p.task_id] = "failed"
+            self.phase = "Failed"
+
+    # -- State query helpers --
+
+    def get_task(self, task_id: str) -> TaskRequestRecord | None:
+        """Return the task request record for *task_id*, or None."""
+        return self.tasks.get(task_id)
+
+    def is_accepted(self, task_id: str) -> bool:
+        status = self._statuses.get(task_id)
+        return status == "accepted" or status == "in_progress"
+
+    def is_completed(self, task_id: str) -> bool:
+        return self._statuses.get(task_id) == "completed"
+
+    def is_failed(self, task_id: str) -> bool:
+        return self._statuses.get(task_id) == "failed"
+
+    def is_retryable(self, task_id: str) -> bool:
+        """True if the task failed with ``retryable=True``."""
+        return any(f.task_id == task_id and f.retryable for f in self.failures)
+
+    def progress_of(self, task_id: str) -> float:
+        """Return the latest progress value for *task_id*, or 0 if unknown."""
+        return self._progress.get(task_id, 0.0)
+
+    def latest_progress(self) -> float | None:
+        return self.updates[-1].progress if self.updates else None
+
+    def active_tasks(self) -> list[TaskRequestRecord]:
+        """Return task records that are not in a terminal state."""
+        active_statuses = {"requested", "accepted", "in_progress"}
+        return [t for t in self.tasks.values() if self._statuses.get(t.task_id) in active_statuses]
+
+
+# ---------------------------------------------------------------------------
+# Session helper
+# ---------------------------------------------------------------------------
+
+
+class TaskSession(BaseSession):
+    """High-level helper for Task mode sessions."""
+
+    MODE = MODE_TASK
+
+    def _create_projection(self) -> BaseProjection:
+        return TaskProjection()
+
+    @property
+    def task_projection(self) -> TaskProjection:
+        assert isinstance(self.projection, TaskProjection)
+        return self.projection
+
+    def request(
+        self,
+        task_id: str,
+        title: str,
+        *,
+        instructions: str = "",
+        requested_assignee: str = "",
+        input_data: bytes = b"",
+        deadline_unix_ms: int = 0,
+        sender: str | None = None,
+        auth: AuthConfig | None = None,
+    ) -> envelope_pb2.Ack:
+        payload = task_pb2.TaskRequestPayload(
+            task_id=task_id,
+            title=title,
+            instructions=instructions,
+            requested_assignee=requested_assignee,
+            input=input_data,
+            deadline_unix_ms=deadline_unix_ms,
+        )
+        envelope = build_envelope(
+            mode=self.MODE,
+            message_type="TaskRequest",
+            session_id=self.session_id,
+            sender=self._sender_for(sender, auth=auth),
+            payload=serialize_message(payload),
+        )
+        return self._send_and_track(envelope, auth=auth)
+
+    def accept_task(
+        self,
+        task_id: str,
+        *,
+        assignee: str = "",
+        reason: str = "",
+        sender: str | None = None,
+        auth: AuthConfig | None = None,
+    ) -> envelope_pb2.Ack:
+        payload = task_pb2.TaskAcceptPayload(
+            task_id=task_id,
+            assignee=assignee or self._sender_for(sender, auth=auth),
+            reason=reason,
+        )
+        envelope = build_envelope(
+            mode=self.MODE,
+            message_type="TaskAccept",
+            session_id=self.session_id,
+            sender=self._sender_for(sender, auth=auth),
+            payload=serialize_message(payload),
+        )
+        return self._send_and_track(envelope, auth=auth)
+
+    def reject_task(
+        self,
+        task_id: str,
+        *,
+        assignee: str = "",
+        reason: str = "",
+        sender: str | None = None,
+        auth: AuthConfig | None = None,
+    ) -> envelope_pb2.Ack:
+        payload = task_pb2.TaskRejectPayload(
+            task_id=task_id,
+            assignee=assignee or self._sender_for(sender, auth=auth),
+            reason=reason,
+        )
+        envelope = build_envelope(
+            mode=self.MODE,
+            message_type="TaskReject",
+            session_id=self.session_id,
+            sender=self._sender_for(sender, auth=auth),
+            payload=serialize_message(payload),
+        )
+        return self._send_and_track(envelope, auth=auth)
+
+    def update(
+        self,
+        task_id: str,
+        *,
+        status: str = "",
+        progress: float = 0.0,
+        message: str = "",
+        partial_output: bytes = b"",
+        sender: str | None = None,
+        auth: AuthConfig | None = None,
+    ) -> envelope_pb2.Ack:
+        payload = task_pb2.TaskUpdatePayload(
+            task_id=task_id,
+            status=status,
+            progress=progress,
+            message=message,
+            partial_output=partial_output,
+        )
+        envelope = build_envelope(
+            mode=self.MODE,
+            message_type="TaskUpdate",
+            session_id=self.session_id,
+            sender=self._sender_for(sender, auth=auth),
+            payload=serialize_message(payload),
+        )
+        return self._send_and_track(envelope, auth=auth)
+
+    def complete(
+        self,
+        task_id: str,
+        *,
+        assignee: str = "",
+        output: bytes = b"",
+        summary: str = "",
+        sender: str | None = None,
+        auth: AuthConfig | None = None,
+    ) -> envelope_pb2.Ack:
+        payload = task_pb2.TaskCompletePayload(
+            task_id=task_id,
+            assignee=assignee or self._sender_for(sender, auth=auth),
+            output=output,
+            summary=summary,
+        )
+        envelope = build_envelope(
+            mode=self.MODE,
+            message_type="TaskComplete",
+            session_id=self.session_id,
+            sender=self._sender_for(sender, auth=auth),
+            payload=serialize_message(payload),
+        )
+        return self._send_and_track(envelope, auth=auth)
+
+    def fail(
+        self,
+        task_id: str,
+        *,
+        assignee: str = "",
+        error_code: str = "",
+        reason: str = "",
+        retryable: bool = False,
+        sender: str | None = None,
+        auth: AuthConfig | None = None,
+    ) -> envelope_pb2.Ack:
+        payload = task_pb2.TaskFailPayload(
+            task_id=task_id,
+            assignee=assignee or self._sender_for(sender, auth=auth),
+            error_code=error_code,
+            reason=reason,
+            retryable=retryable,
+        )
+        envelope = build_envelope(
+            mode=self.MODE,
+            message_type="TaskFail",
+            session_id=self.session_id,
+            sender=self._sender_for(sender, auth=auth),
+            payload=serialize_message(payload),
+        )
+        return self._send_and_track(envelope, auth=auth)