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

macp_sdk/__init__.py

@@ -0,0 +1,207 @@
+from ._logging import configure_logging
+from .auth import AuthConfig
+from .base_projection import BaseProjection
+from .base_session import BaseSession
+from .client import MacpClient, MacpStream
+from .constants import (
+    DEFAULT_CONFIGURATION_VERSION,
+    DEFAULT_MODE_VERSION,
+    DEFAULT_POLICY_VERSION,
+    MACP_VERSION,
+    MODE_DECISION,
+    MODE_HANDOFF,
+    MODE_MULTI_ROUND,
+    MODE_PROPOSAL,
+    MODE_QUORUM,
+    MODE_TASK,
+    STANDARD_MODES,
+)
+from .decision import DecisionSession
+from .envelope import (
+    build_commitment_payload,
+    build_envelope,
+    build_progress_payload,
+    build_root,
+    build_session_start_payload,
+    build_signal_payload,
+    infer_outcome_positive,
+    new_commitment_id,
+    new_message_id,
+    new_session_id,
+    serialize_message,
+)
+from .errors import (
+    DUPLICATE_MESSAGE,
+    FORBIDDEN,
+    INTERNAL_ERROR,
+    INVALID_ENVELOPE,
+    INVALID_POLICY_DEFINITION,
+    INVALID_SESSION_ID,
+    MODE_NOT_SUPPORTED,
+    PAYLOAD_TOO_LARGE,
+    POLICY_DENIED,
+    RATE_LIMITED,
+    SESSION_ALREADY_EXISTS,
+    SESSION_NOT_FOUND,
+    SESSION_NOT_OPEN,
+    UNAUTHENTICATED,
+    UNKNOWN_POLICY_VERSION,
+    UNSUPPORTED_PROTOCOL_VERSION,
+    AckFailure,
+    MacpAckError,
+    MacpIdentityMismatchError,
+    MacpRetryError,
+    MacpSdkError,
+    MacpSessionError,
+    MacpTimeoutError,
+    MacpTransportError,
+)
+from .handoff import HandoffProjection, HandoffRecord, HandoffSession
+from .policy import (
+    AbstentionRules,
+    CommitmentRules,
+    CounterProposalRules,
+    EvaluationRules,
+    HandoffAcceptanceRules,
+    ObjectionHandlingRules,
+    ProposalAcceptanceRules,
+    QuorumThreshold,
+    RejectionRules,
+    TaskAssignmentRules,
+    TaskCompletionRules,
+    VotingRules,
+    build_decision_policy,
+    build_handoff_policy,
+    build_proposal_policy,
+    build_quorum_policy,
+    build_task_policy,
+)
+from .projections import DecisionProjection
+from .proposal import ProposalProjection, ProposalSession, RejectRecord
+from .proto_registry import ProtoRegistry
+from .quorum import QuorumProjection, QuorumSession
+from .retry import RetryPolicy, retry_send
+from .task import TaskProjection, TaskSession
+from .validation import (
+    validate_confidence,
+    validate_participant_count,
+    validate_participants,
+    validate_recommendation,
+    validate_required_field,
+    validate_session_id,
+    validate_session_start,
+    validate_severity,
+    validate_signal_type,
+    validate_ttl_ms,
+    validate_vote,
+)
+from .watchers import (
+    ModeRegistryWatcher,
+    PolicyChange,
+    PolicyWatcher,
+    RootsWatcher,
+    SignalWatcher,
+)
+
+__all__ = [
+    "DEFAULT_CONFIGURATION_VERSION",
+    "DEFAULT_MODE_VERSION",
+    "DEFAULT_POLICY_VERSION",
+    "DUPLICATE_MESSAGE",
+    "FORBIDDEN",
+    "INTERNAL_ERROR",
+    "INVALID_ENVELOPE",
+    "INVALID_POLICY_DEFINITION",
+    "INVALID_SESSION_ID",
+    "MACP_VERSION",
+    "MODE_DECISION",
+    "MODE_HANDOFF",
+    "MODE_MULTI_ROUND",
+    "MODE_NOT_SUPPORTED",
+    "MODE_PROPOSAL",
+    "MODE_QUORUM",
+    "MODE_TASK",
+    "PAYLOAD_TOO_LARGE",
+    "POLICY_DENIED",
+    "RATE_LIMITED",
+    "SESSION_ALREADY_EXISTS",
+    "SESSION_NOT_FOUND",
+    "SESSION_NOT_OPEN",
+    "STANDARD_MODES",
+    "UNAUTHENTICATED",
+    "UNKNOWN_POLICY_VERSION",
+    "UNSUPPORTED_PROTOCOL_VERSION",
+    "AbstentionRules",
+    "AckFailure",
+    "AuthConfig",
+    "BaseProjection",
+    "BaseSession",
+    "CommitmentRules",
+    "CounterProposalRules",
+    "DecisionProjection",
+    "DecisionSession",
+    "EvaluationRules",
+    "HandoffAcceptanceRules",
+    "HandoffProjection",
+    "HandoffRecord",
+    "HandoffSession",
+    "MacpAckError",
+    "MacpClient",
+    "MacpIdentityMismatchError",
+    "MacpRetryError",
+    "MacpSdkError",
+    "MacpSessionError",
+    "MacpStream",
+    "MacpTimeoutError",
+    "MacpTransportError",
+    "ModeRegistryWatcher",
+    "ObjectionHandlingRules",
+    "PolicyChange",
+    "PolicyWatcher",
+    "ProposalAcceptanceRules",
+    "ProposalProjection",
+    "ProposalSession",
+    "ProtoRegistry",
+    "QuorumProjection",
+    "QuorumSession",
+    "QuorumThreshold",
+    "RejectRecord",
+    "RejectionRules",
+    "RetryPolicy",
+    "RootsWatcher",
+    "SignalWatcher",
+    "TaskAssignmentRules",
+    "TaskCompletionRules",
+    "TaskProjection",
+    "TaskSession",
+    "VotingRules",
+    "build_commitment_payload",
+    "build_decision_policy",
+    "build_envelope",
+    "build_handoff_policy",
+    "build_progress_payload",
+    "build_proposal_policy",
+    "build_quorum_policy",
+    "build_root",
+    "build_session_start_payload",
+    "build_signal_payload",
+    "build_task_policy",
+    "configure_logging",
+    "infer_outcome_positive",
+    "new_commitment_id",
+    "new_message_id",
+    "new_session_id",
+    "retry_send",
+    "serialize_message",
+    "validate_confidence",
+    "validate_participant_count",
+    "validate_participants",
+    "validate_recommendation",
+    "validate_required_field",
+    "validate_session_id",
+    "validate_session_start",
+    "validate_severity",
+    "validate_signal_type",
+    "validate_ttl_ms",
+    "validate_vote",
+]

macp_sdk/_logging.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger("macp_sdk")
+
+
+def configure_logging(
+    level: int = logging.INFO,
+    fmt: str = "%(asctime)s %(name)s %(levelname)s %(message)s",
+) -> None:
+    """Configure the macp_sdk logger with a stream handler."""
+    handler = logging.StreamHandler()
+    handler.setFormatter(logging.Formatter(fmt))
+    logger.addHandler(handler)
+    logger.setLevel(level)

macp_sdk/agent/__init__.py

@@ -0,0 +1,64 @@
+from .dispatcher import Dispatcher
+from .participant import Participant, ParticipantActions
+from .runner import from_bootstrap
+from .strategies import (
+    CommitmentDecision,
+    CommitmentStrategy,
+    EvaluationResult,
+    EvaluationStrategy,
+    VoteDecision,
+    VotingStrategy,
+    commitment_handler,
+    evaluation_handler,
+    function_committer,
+    function_evaluator,
+    function_voter,
+    majority_committer,
+    majority_voter,
+    voting_handler,
+)
+from .transports import (
+    GrpcTransportAdapter,
+    HttpTransportAdapter,
+    TransportAdapter,
+)
+from .types import (
+    HandlerContext,
+    IncomingMessage,
+    MessageHandler,
+    PhaseChangeHandler,
+    SessionInfo,
+    TerminalHandler,
+    TerminalResult,
+)
+
+__all__ = [
+    "CommitmentDecision",
+    "CommitmentStrategy",
+    "Dispatcher",
+    "EvaluationResult",
+    "EvaluationStrategy",
+    "GrpcTransportAdapter",
+    "HandlerContext",
+    "HttpTransportAdapter",
+    "IncomingMessage",
+    "MessageHandler",
+    "Participant",
+    "ParticipantActions",
+    "PhaseChangeHandler",
+    "SessionInfo",
+    "TerminalHandler",
+    "TerminalResult",
+    "TransportAdapter",
+    "VoteDecision",
+    "VotingStrategy",
+    "commitment_handler",
+    "evaluation_handler",
+    "from_bootstrap",
+    "function_committer",
+    "function_evaluator",
+    "function_voter",
+    "majority_committer",
+    "majority_voter",
+    "voting_handler",
+]

macp_sdk/agent/dispatcher.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from collections import defaultdict
+
+from .._logging import logger
+from .types import (
+    HandlerContext,
+    IncomingMessage,
+    MessageHandler,
+    PhaseChangeHandler,
+    TerminalHandler,
+    TerminalResult,
+)
+
+
+class Dispatcher:
+    """Routes incoming MACP messages to registered handlers.
+
+    Supports per-message-type handlers, per-phase-change handlers,
+    wildcard ``'*'`` handlers (invoked for every event), and a single
+    terminal handler.
+    """
+
+    def __init__(self) -> None:
+        self._handlers: dict[str, list[MessageHandler]] = defaultdict(list)
+        self._wildcard_handlers: list[MessageHandler] = []
+        self._phase_handlers: dict[str, list[PhaseChangeHandler]] = defaultdict(list)
+        self._wildcard_phase_handlers: list[PhaseChangeHandler] = []
+        self._terminal_handler: TerminalHandler | None = None
+
+    def on(self, message_type: str, handler: MessageHandler) -> None:
+        """Register a handler for a specific message type.
+
+        Use ``'*'`` as the message_type to register a wildcard handler that
+        is invoked for every message after type-specific handlers.
+        """
+        if message_type == "*":
+            self._wildcard_handlers.append(handler)
+        else:
+            self._handlers[message_type].append(handler)
+
+    def on_phase_change(self, phase: str, handler: PhaseChangeHandler) -> None:
+        """Register a handler for a specific phase transition.
+
+        Use ``'*'`` as the phase to register a wildcard handler that is
+        invoked for every phase change after phase-specific handlers.
+        """
+        if phase == "*":
+            self._wildcard_phase_handlers.append(handler)
+        else:
+            self._phase_handlers[phase].append(handler)
+
+    def on_terminal(self, handler: TerminalHandler) -> None:
+        """Register the terminal state handler (only one is allowed)."""
+        self._terminal_handler = handler
+
+    def dispatch(self, message: IncomingMessage, ctx: HandlerContext) -> None:
+        """Dispatch a message to all matching handlers.
+
+        Type-specific handlers are invoked first (in registration order),
+        followed by wildcard ``'*'`` handlers.  If no handler matches at
+        all, a debug-level log is emitted.
+        """
+        handlers = self._handlers.get(message.message_type)
+        if not handlers and not self._wildcard_handlers:
+            logger.debug("no handler for message_type=%s", message.message_type)
+            return
+        for handler in handlers or []:
+            handler(message, ctx)
+        for handler in self._wildcard_handlers:
+            handler(message, ctx)
+
+    def dispatch_phase_change(self, phase: str, ctx: HandlerContext) -> None:
+        """Dispatch a phase change event to matching handlers.
+
+        Phase-specific handlers are invoked first, followed by wildcard
+        ``'*'`` phase handlers.
+        """
+        handlers = self._phase_handlers.get(phase)
+        for handler in handlers or []:
+            handler(phase, ctx)
+        for handler in self._wildcard_phase_handlers:
+            handler(phase, ctx)
+
+    def dispatch_terminal(self, result: TerminalResult) -> None:
+        """Invoke the terminal handler if registered."""
+        if self._terminal_handler is not None:
+            self._terminal_handler(result)
+        else:
+            logger.debug("terminal result with no handler: state=%s", result.state)
+
+    @property
+    def registered_message_types(self) -> list[str]:
+        """Return all message types that have at least one handler."""
+        return list(self._handlers.keys())
+
+    @property
+    def registered_phases(self) -> list[str]:
+        """Return all phases that have at least one handler."""
+        return list(self._phase_handlers.keys())
+
+    @property
+    def has_terminal_handler(self) -> bool:
+        """Return whether a terminal handler is registered."""
+        return self._terminal_handler is not None