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

macp_sdk/policy.py

@@ -0,0 +1,292 @@
+"""Typed policy builders for all MACP governance modes.
+
+Each builder produces a :class:`PolicyDescriptor` with JSON-encoded rules
+that match the normative rule schemas defined in RFC-MACP-0012 and the
+Rust runtime's ``src/policy/rules.rs``.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+
+from macp.v1 import policy_pb2
+
+# ── Shared commitment rules (all modes) ─────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class CommitmentRules:
+    """Commitment authority configuration shared by all mode policies."""
+
+    authority: str = "initiator_only"
+    designated_roles: list[str] = field(default_factory=list)
+    require_vote_quorum: bool = False
+
+
+def _commitment_dict(c: CommitmentRules) -> dict[str, object]:
+    return {
+        "authority": c.authority,
+        "designated_roles": c.designated_roles,
+        "require_vote_quorum": c.require_vote_quorum,
+    }
+
+
+# ── Decision mode ────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class VotingRules:
+    """Voting configuration for a decision policy."""
+
+    algorithm: str = "none"
+    threshold: float = 0.5
+    quorum_type: str | None = None
+    quorum_value: float | None = None
+    weights: dict[str, float] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ObjectionHandlingRules:
+    """Objection handling configuration for a decision policy."""
+
+    critical_severity_vetoes: bool = False
+    veto_threshold: int = 1
+
+
+@dataclass(frozen=True, slots=True)
+class EvaluationRules:
+    """Evaluation configuration for a decision policy."""
+
+    minimum_confidence: float = 0.0
+    required_before_voting: bool = False
+
+
+def build_decision_policy(
+    policy_id: str,
+    description: str,
+    *,
+    voting: VotingRules | None = None,
+    objection_handling: ObjectionHandlingRules | None = None,
+    evaluation: EvaluationRules | None = None,
+    commitment: CommitmentRules | None = None,
+) -> policy_pb2.PolicyDescriptor:
+    """Build a PolicyDescriptor for Decision mode governance."""
+    v = voting or VotingRules()
+    o = objection_handling or ObjectionHandlingRules()
+    e = evaluation or EvaluationRules()
+    c = commitment or CommitmentRules()
+
+    voting_section: dict[str, object] = {
+        "algorithm": v.algorithm,
+        "threshold": v.threshold,
+        "quorum": {"type": v.quorum_type or "count", "value": v.quorum_value or 0},
+    }
+    if v.weights is not None:
+        voting_section["weights"] = v.weights
+
+    rules: dict[str, object] = {
+        "voting": voting_section,
+        "objection_handling": {
+            "critical_severity_vetoes": o.critical_severity_vetoes,
+            "veto_threshold": o.veto_threshold,
+        },
+        "evaluation": {
+            "minimum_confidence": e.minimum_confidence,
+            "required_before_voting": e.required_before_voting,
+        },
+        "commitment": _commitment_dict(c),
+    }
+
+    return policy_pb2.PolicyDescriptor(
+        policy_id=policy_id,
+        mode="macp.mode.decision.v1",
+        description=description,
+        rules=json.dumps(rules).encode(),
+        schema_version=1,
+    )
+
+
+# ── Quorum mode ──────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class QuorumThreshold:
+    """Quorum threshold configuration (RFC: ``threshold`` object)."""
+
+    type: str = "n_of_m"
+    value: float = 0
+
+
+@dataclass(frozen=True, slots=True)
+class AbstentionRules:
+    """Abstention handling configuration (RFC: ``abstention`` object)."""
+
+    counts_toward_quorum: bool = False
+    interpretation: str = "neutral"
+
+
+def build_quorum_policy(
+    policy_id: str,
+    description: str,
+    *,
+    threshold: QuorumThreshold | None = None,
+    abstention: AbstentionRules | None = None,
+    commitment: CommitmentRules | None = None,
+) -> policy_pb2.PolicyDescriptor:
+    """Build a PolicyDescriptor for Quorum mode governance."""
+    t = threshold or QuorumThreshold()
+    a = abstention or AbstentionRules()
+    c = commitment or CommitmentRules()
+
+    rules: dict[str, object] = {
+        "threshold": {"type": t.type, "value": t.value},
+        "abstention": {
+            "counts_toward_quorum": a.counts_toward_quorum,
+            "interpretation": a.interpretation,
+        },
+        "commitment": _commitment_dict(c),
+    }
+
+    return policy_pb2.PolicyDescriptor(
+        policy_id=policy_id,
+        mode="macp.mode.quorum.v1",
+        description=description,
+        rules=json.dumps(rules).encode(),
+        schema_version=1,
+    )
+
+
+# ── Proposal mode ────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class ProposalAcceptanceRules:
+    """Acceptance criterion for proposal policies."""
+
+    criterion: str = "all_parties"
+
+
+@dataclass(frozen=True, slots=True)
+class CounterProposalRules:
+    """Counter-proposal limits for proposal policies."""
+
+    max_rounds: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class RejectionRules:
+    """Rejection handling for proposal policies."""
+
+    terminal_on_any_reject: bool = False
+
+
+def build_proposal_policy(
+    policy_id: str,
+    description: str,
+    *,
+    acceptance: ProposalAcceptanceRules | None = None,
+    counter_proposal: CounterProposalRules | None = None,
+    rejection: RejectionRules | None = None,
+    commitment: CommitmentRules | None = None,
+) -> policy_pb2.PolicyDescriptor:
+    """Build a PolicyDescriptor for Proposal mode governance."""
+    acc = acceptance or ProposalAcceptanceRules()
+    cp = counter_proposal or CounterProposalRules()
+    rej = rejection or RejectionRules()
+    c = commitment or CommitmentRules()
+
+    rules: dict[str, object] = {
+        "acceptance": {"criterion": acc.criterion},
+        "counter_proposal": {"max_rounds": cp.max_rounds},
+        "rejection": {"terminal_on_any_reject": rej.terminal_on_any_reject},
+        "commitment": _commitment_dict(c),
+    }
+
+    return policy_pb2.PolicyDescriptor(
+        policy_id=policy_id,
+        mode="macp.mode.proposal.v1",
+        description=description,
+        rules=json.dumps(rules).encode(),
+        schema_version=1,
+    )
+
+
+# ── Task mode ────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class TaskAssignmentRules:
+    """Task assignment configuration."""
+
+    allow_reassignment_on_reject: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class TaskCompletionRules:
+    """Task completion configuration."""
+
+    require_output: bool = False
+
+
+def build_task_policy(
+    policy_id: str,
+    description: str,
+    *,
+    assignment: TaskAssignmentRules | None = None,
+    completion: TaskCompletionRules | None = None,
+    commitment: CommitmentRules | None = None,
+) -> policy_pb2.PolicyDescriptor:
+    """Build a PolicyDescriptor for Task mode governance."""
+    a = assignment or TaskAssignmentRules()
+    comp = completion or TaskCompletionRules()
+    c = commitment or CommitmentRules()
+
+    rules: dict[str, object] = {
+        "assignment": {"allow_reassignment_on_reject": a.allow_reassignment_on_reject},
+        "completion": {"require_output": comp.require_output},
+        "commitment": _commitment_dict(c),
+    }
+
+    return policy_pb2.PolicyDescriptor(
+        policy_id=policy_id,
+        mode="macp.mode.task.v1",
+        description=description,
+        rules=json.dumps(rules).encode(),
+        schema_version=1,
+    )
+
+
+# ── Handoff mode ─────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class HandoffAcceptanceRules:
+    """Handoff acceptance configuration."""
+
+    implicit_accept_timeout_ms: int = 0
+
+
+def build_handoff_policy(
+    policy_id: str,
+    description: str,
+    *,
+    acceptance: HandoffAcceptanceRules | None = None,
+    commitment: CommitmentRules | None = None,
+) -> policy_pb2.PolicyDescriptor:
+    """Build a PolicyDescriptor for Handoff mode governance."""
+    acc = acceptance or HandoffAcceptanceRules()
+    c = commitment or CommitmentRules()
+
+    rules: dict[str, object] = {
+        "acceptance": {"implicit_accept_timeout_ms": acc.implicit_accept_timeout_ms},
+        "commitment": _commitment_dict(c),
+    }
+
+    return policy_pb2.PolicyDescriptor(
+        policy_id=policy_id,
+        mode="macp.mode.handoff.v1",
+        description=description,
+        rules=json.dumps(rules).encode(),
+        schema_version=1,
+    )

macp_sdk/projections.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from macp.modes.decision.v1 import decision_pb2
+from macp.v1 import envelope_pb2
+
+from .base_projection import BaseProjection
+from .constants import MODE_DECISION
+
+
+@dataclass(slots=True)
+class DecisionProposalRecord:
+    proposal_id: str
+    option: str
+    rationale: str
+    sender: str
+
+
+@dataclass(slots=True)
+class DecisionEvaluationRecord:
+    proposal_id: str
+    recommendation: str
+    confidence: float
+    reason: str
+    sender: str
+
+
+@dataclass(slots=True)
+class DecisionObjectionRecord:
+    proposal_id: str
+    reason: str
+    severity: str
+    sender: str
+
+
+@dataclass(slots=True)
+class DecisionVoteRecord:
+    proposal_id: str
+    vote: str
+    reason: str
+    sender: str
+
+
+class DecisionProjection(BaseProjection):
+    """In-process state tracking for Decision mode sessions."""
+
+    MODE = MODE_DECISION
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.phase = "Proposal"
+        self.proposals: dict[str, DecisionProposalRecord] = {}
+        self.evaluations: list[DecisionEvaluationRecord] = []
+        self.objections: list[DecisionObjectionRecord] = []
+        self.votes: dict[str, dict[str, DecisionVoteRecord]] = {}
+
+    def _apply_mode_message(self, envelope: envelope_pb2.Envelope) -> None:
+        message_type = envelope.message_type
+
+        if message_type == "Proposal":
+            payload = decision_pb2.ProposalPayload()
+            payload.ParseFromString(envelope.payload)
+            self.proposals[payload.proposal_id] = DecisionProposalRecord(
+                proposal_id=payload.proposal_id,
+                option=payload.option,
+                rationale=payload.rationale,
+                sender=envelope.sender,
+            )
+            return
+
+        if message_type == "Evaluation":
+            payload = decision_pb2.EvaluationPayload()
+            payload.ParseFromString(envelope.payload)
+            self.evaluations.append(
+                DecisionEvaluationRecord(
+                    proposal_id=payload.proposal_id,
+                    recommendation=payload.recommendation,
+                    confidence=payload.confidence,
+                    reason=payload.reason,
+                    sender=envelope.sender,
+                )
+            )
+            self.phase = "Evaluation"
+            return
+
+        if message_type == "Objection":
+            payload = decision_pb2.ObjectionPayload()
+            payload.ParseFromString(envelope.payload)
+            self.objections.append(
+                DecisionObjectionRecord(
+                    proposal_id=payload.proposal_id,
+                    reason=payload.reason,
+                    severity=payload.severity or "medium",
+                    sender=envelope.sender,
+                )
+            )
+            return
+
+        if message_type == "Vote":
+            payload = decision_pb2.VotePayload()
+            payload.ParseFromString(envelope.payload)
+            self.votes.setdefault(payload.proposal_id, {})[envelope.sender] = DecisionVoteRecord(
+                proposal_id=payload.proposal_id,
+                vote=payload.vote,
+                reason=payload.reason,
+                sender=envelope.sender,
+            )
+            self.phase = "Voting"
+
+    # -- State query helpers (no policy enforcement) --
+
+    def vote_totals(self) -> dict[str, int]:
+        """Count votes per proposal, keyed by proposal_id.
+
+        ABSTAIN votes are tracked but excluded from the totals returned
+        here (which counts only APPROVE votes).
+        """
+        totals: dict[str, int] = {}
+        for proposal_id, sender_votes in self.votes.items():
+            totals[proposal_id] = sum(
+                1 for vote in sender_votes.values() if _is_positive_vote(vote.vote)
+            )
+        return totals
+
+    def majority_winner(self) -> str | None:
+        """Return the proposal_id with a majority of non-abstain votes, or None.
+
+        ABSTAIN votes are excluded from the denominator per RFC-MACP-0004.
+        """
+        totals = self.vote_totals()
+        if not totals:
+            return None
+        # Count total non-abstain votes across all proposals
+        non_abstain = 0
+        for sender_votes in self.votes.values():
+            for vote in sender_votes.values():
+                if vote.vote.upper() != "ABSTAIN":
+                    non_abstain += 1
+        if non_abstain == 0:
+            return None
+        for proposal_id, count in totals.items():
+            if count / non_abstain > 0.5:
+                return proposal_id
+        return None
+
+    def has_blocking_objection(self, proposal_id: str | None = None) -> bool:
+        """Check if any objection with ``critical`` severity exists.
+
+        Only ``critical`` severity triggers a veto per the updated runtime.
+        """
+        return any(
+            objection.severity.lower() == "critical"
+            and (proposal_id is None or objection.proposal_id == proposal_id)
+            for objection in self.objections
+        )
+
+    def review_evaluations(self) -> list[DecisionEvaluationRecord]:
+        """Return evaluations with REVIEW recommendation (informational only)."""
+        return [e for e in self.evaluations if e.recommendation.upper() == "REVIEW"]
+
+    def qualifying_evaluations(self) -> list[DecisionEvaluationRecord]:
+        """Return evaluations that are *not* REVIEW (i.e., they affect decisions)."""
+        return [e for e in self.evaluations if e.recommendation.upper() != "REVIEW"]
+
+    def vote_ratio(self, proposal_id: str) -> float:
+        """Return the APPROVE vote ratio for *proposal_id*.
+
+        ABSTAIN votes are excluded from the denominator.
+        """
+        sender_votes = self.votes.get(proposal_id)
+        if not sender_votes:
+            return 0.0
+        votes = list(sender_votes.values())
+        non_abstain = [v for v in votes if v.vote.upper() != "ABSTAIN"]
+        if not non_abstain:
+            return 0.0
+        approvals = sum(1 for v in non_abstain if _is_positive_vote(v.vote))
+        return approvals / len(non_abstain)
+
+
+def _is_positive_vote(vote: str) -> bool:
+    return vote.strip().upper() in {"APPROVE", "APPROVED", "YES", "ACCEPT", "ACCEPTED"}