asap-protocol 0.1.0__py3-none-any.whl

asap/models/parts.py

@@ -0,0 +1,207 @@
+"""Part models for ASAP protocol content types.
+
+Parts are atomic content units used within messages and artifacts.
+They support different content types including text, structured data,
+files, MCP resources, and parameterized templates.
+"""
+
+import base64
+import re
+from typing import Annotated, Any, Literal, Union
+
+from pydantic import Discriminator, Field, TypeAdapter, field_validator
+
+from asap.models.base import ASAPBaseModel
+from asap.models.types import MIMEType
+
+
+class TextPart(ASAPBaseModel):
+    """Plain text content part.
+
+    TextPart represents simple text content, such as user messages,
+    agent responses, or any textual information.
+
+    Attributes:
+        type: Discriminator field, always "text"
+        content: The text content
+
+    Example:
+        >>> part = TextPart(
+        ...     type="text",
+        ...     content="Research Q3 market trends for AI infrastructure"
+        ... )
+    """
+
+    type: Literal["text"] = Field(..., description="Part type discriminator")
+    content: str = Field(..., description="Text content")
+
+
+class DataPart(ASAPBaseModel):
+    """Structured JSON data part.
+
+    DataPart represents structured data in JSON format, optionally
+    with a schema URI for validation.
+
+    Attributes:
+        type: Discriminator field, always "data"
+        data: Arbitrary JSON-serializable data
+        schema_uri: Optional URI to JSON Schema for validation
+
+    Example:
+        >>> part = DataPart(
+        ...     type="data",
+        ...     data={"query": "AI trends", "max_results": 10},
+        ...     schema_uri="https://example.com/schemas/search.json"
+        ... )
+    """
+
+    type: Literal["data"] = Field(..., description="Part type discriminator")
+    data: dict[str, Any] = Field(..., description="Structured data (JSON-serializable)")
+    schema_uri: str | None = Field(
+        default=None, description="Optional JSON Schema URI for validation"
+    )
+
+
+class FilePart(ASAPBaseModel):
+    """Binary or text file part.
+
+    FilePart represents file content, either by reference (URI) or
+    inline (base64-encoded data). Includes MIME type for proper handling.
+
+    Attributes:
+        type: Discriminator field, always "file"
+        uri: File URI (can be asap://, file://, https://, or data: URI)
+        mime_type: MIME type of the file (e.g., "application/pdf")
+        inline_data: Optional base64-encoded inline file data
+
+    Example:
+        >>> part = FilePart(
+        ...     type="file",
+        ...     uri="asap://artifacts/task_123/report.pdf",
+        ...     mime_type="application/pdf"
+        ... )
+        >>>
+        >>> # With inline data
+        >>> part_inline = FilePart(
+        ...     type="file",
+        ...     uri="data:text/plain;base64,SGVsbG8gV29ybGQ=",
+        ...     mime_type="text/plain",
+        ...     inline_data="SGVsbG8gV29ybGQ="
+        ... )
+    """
+
+    type: Literal["file"] = Field(..., description="Part type discriminator")
+    uri: str = Field(..., description="File URI (asap://, file://, https://, data:)")
+    mime_type: MIMEType = Field(..., description="MIME type (e.g., application/pdf)")
+    inline_data: str | None = Field(
+        default=None, description="Optional base64-encoded inline file data"
+    )
+
+    @field_validator("mime_type")
+    @classmethod
+    def validate_mime_type(cls, v: str) -> str:
+        """Validate MIME type format (type/subtype)."""
+        # Pattern: type/subtype where both parts can contain alphanumeric, dots, plus, and hyphens
+        if not re.match(r"^[a-z0-9-]+/[a-z0-9.+\-]+$", v.lower()):
+            raise ValueError(f"Invalid MIME type format: {v}")
+        return v
+
+    @field_validator("inline_data")
+    @classmethod
+    def validate_base64(cls, v: str | None) -> str | None:
+        """Validate that inline_data is valid base64 when provided.
+
+        Args:
+            v: Base64 string or None
+
+        Returns:
+            Base64 string after validation
+
+        Raises:
+            ValueError: If inline_data is not valid base64
+        """
+        if v is not None:
+            try:
+                base64.b64decode(v, validate=True)
+            except Exception as e:
+                raise ValueError(f"inline_data must be valid base64: {e}") from e
+        return v
+
+
+class ResourcePart(ASAPBaseModel):
+    """Reference to an MCP resource.
+
+    ResourcePart represents a reference to a resource provided by
+    an MCP (Model Context Protocol) server, enabling integration
+    with external tools and data sources.
+
+    Attributes:
+        type: Discriminator field, always "resource"
+        resource_uri: URI of the MCP resource
+
+    Example:
+        >>> part = ResourcePart(
+        ...     type="resource",
+        ...     resource_uri="mcp://tools.example.com/web/search_results"
+        ... )
+    """
+
+    type: Literal["resource"] = Field(..., description="Part type discriminator")
+    resource_uri: str = Field(..., description="MCP resource URI")
+
+
+class TemplatePart(ASAPBaseModel):
+    """Parameterized prompt template.
+
+    TemplatePart represents a template string with variable placeholders
+    (using {{variable}} syntax) and their corresponding values.
+
+    Attributes:
+        type: Discriminator field, always "template"
+        template: Template string with {{variable}} placeholders
+        variables: Dictionary mapping variable names to their values
+
+    Example:
+        >>> part = TemplatePart(
+        ...     type="template",
+        ...     template="Research {{topic}} for {{timeframe}}",
+        ...     variables={"topic": "AI trends", "timeframe": "Q3 2025"}
+        ... )
+    """
+
+    type: Literal["template"] = Field(..., description="Part type discriminator")
+    template: str = Field(..., description="Template string with {{variable}} syntax")
+    variables: dict[str, Any] = Field(..., description="Variable name to value mapping")
+
+
+# Discriminated union type for type hints
+PartType = Annotated[
+    Union[TextPart, DataPart, FilePart, ResourcePart, TemplatePart], Discriminator("type")
+]
+
+# TypeAdapter for validation and deserialization
+Part: TypeAdapter[PartType] = TypeAdapter(PartType)
+"""TypeAdapter for Part discriminated union.
+
+Part is a TypeAdapter that can validate and deserialize any of the five
+part types: TextPart, DataPart, FilePart, ResourcePart, or TemplatePart.
+
+The 'type' field is used as a discriminator to automatically deserialize
+JSON data into the correct Part subtype.
+
+Example:
+    >>> from asap.models.parts import Part
+    >>> 
+    >>> # Deserializes to TextPart
+    >>> text_part = Part.validate_python({"type": "text", "content": "Hello"})
+    >>> 
+    >>> # Deserializes to DataPart
+    >>> data_part = Part.validate_python({"type": "data", "data": {"key": "value"}})
+    >>> 
+    >>> # Deserializes to FilePart
+    >>> file_part = Part.validate_python({
+    ...     "type": "file",
+    ...     "uri": "file://test.pdf",
+    ...     "mime_type": "application/pdf"
+    ... })
+"""

asap/models/payloads.py

@@ -0,0 +1,423 @@
+"""Payload models for ASAP protocol messages.
+
+Payloads define the content of protocol messages for different operations
+like task requests, responses, updates, state management, and MCP integration.
+"""
+
+from typing import Any, Union
+
+from pydantic import Field, field_validator, model_validator
+
+from asap.models.base import ASAPBaseModel
+from asap.models.enums import MessageRole, TaskStatus, UpdateType
+from asap.models.types import (
+    AgentURN,
+    ArtifactID,
+    ConversationID,
+    MessageID,
+    PartID,
+    SnapshotID,
+    TaskID,
+)
+
+
+class TaskRequest(ASAPBaseModel):
+    """Request to execute a task on an agent.
+
+    TaskRequest initiates task execution, specifying the skill to invoke,
+    input data, and optional configuration parameters.
+
+    Attributes:
+        conversation_id: ID of the conversation this task belongs to
+        parent_task_id: Optional ID of parent task (for subtasks)
+        skill_id: Identifier of the skill to execute
+        input: Input data for the skill (JSON-serializable)
+        config: Optional configuration (timeout, priority, streaming, etc.)
+
+    Example:
+        >>> request = TaskRequest(
+        ...     conversation_id="conv_01HX5K3MQVN8",
+        ...     skill_id="web_research",
+        ...     input={"query": "AI infrastructure market trends Q3 2025"},
+        ...     config={"timeout_seconds": 600, "streaming": True}
+        ... )
+    """
+
+    conversation_id: ConversationID = Field(..., description="Parent conversation ID")
+    parent_task_id: TaskID | None = Field(default=None, description="Parent task ID for subtasks")
+    skill_id: str = Field(..., description="Skill identifier to execute")
+    input: dict[str, Any] = Field(..., description="Input data for the skill")
+    config: dict[str, Any] | None = Field(
+        default=None, description="Optional configuration (timeout, priority, streaming, etc.)"
+    )
+
+
+class TaskResponse(ASAPBaseModel):
+    """Response to a task execution request.
+
+    TaskResponse provides the final result of task execution, including
+    status, result data, final state snapshot, and execution metrics.
+
+    Attributes:
+        task_id: ID of the completed task
+        status: Final task status (completed, failed, cancelled, etc.)
+        result: Optional result data (summary, artifacts, etc.)
+        final_state: Optional final state snapshot
+        metrics: Optional execution metrics (duration, tokens used, etc.)
+
+    Example:
+        >>> response = TaskResponse(
+        ...     task_id="task_01HX5K4N",
+        ...     status="completed",
+        ...     result={"summary": "Analysis complete", "artifacts": ["art_123"]},
+        ...     metrics={"duration_ms": 45000, "tokens_used": 12500}
+        ... )
+    """
+
+    task_id: TaskID = Field(..., description="Task identifier")
+    status: TaskStatus = Field(..., description="Final task status")
+    result: dict[str, Any] | None = Field(
+        default=None, description="Result data (summary, artifacts, etc.)"
+    )
+    final_state: dict[str, Any] | None = Field(default=None, description="Final state snapshot")
+    metrics: dict[str, Any] | None = Field(
+        default=None, description="Execution metrics (duration, tokens, etc.)"
+    )
+
+
+class TaskUpdate(ASAPBaseModel):
+    """Update on task execution progress or status.
+
+    TaskUpdate provides real-time updates during task execution, including
+    progress information or requests for additional input.
+
+    Attributes:
+        task_id: ID of the task being updated
+        update_type: Type of update (progress, input_required, etc.)
+        status: Current task status
+        progress: Optional progress information (percent, message, ETA)
+        input_request: Optional request for additional input from user
+
+    Example:
+        >>> # Progress update
+        >>> update = TaskUpdate(
+        ...     task_id="task_123",
+        ...     update_type="progress",
+        ...     status="working",
+        ...     progress={"percent": 65, "message": "Synthesizing findings..."}
+        ... )
+        >>>
+        >>> # Input required update
+        >>> update = TaskUpdate(
+        ...     task_id="task_123",
+        ...     update_type="input_required",
+        ...     status="input_required",
+        ...     input_request={"prompt": "Please clarify:", "options": [...]}
+        ... )
+    """
+
+    task_id: TaskID = Field(..., description="Task identifier")
+    update_type: UpdateType = Field(..., description="Update type (progress, input_required)")
+    status: TaskStatus = Field(..., description="Current task status")
+    progress: dict[str, Any] | None = Field(
+        default=None, description="Progress info (percent, message, ETA)"
+    )
+    input_request: dict[str, Any] | None = Field(
+        default=None, description="Request for additional input"
+    )
+
+    @field_validator("progress")
+    @classmethod
+    def validate_progress_percent(cls, v: dict[str, Any] | None) -> dict[str, Any] | None:
+        """Validate that progress percent is between 0 and 100 if provided.
+
+        Args:
+            v: Progress dictionary or None
+
+        Returns:
+            Progress dictionary after validation
+
+        Raises:
+            ValueError: If percent is not between 0 and 100
+        """
+        if v and "percent" in v:
+            percent = v["percent"]
+            if not isinstance(percent, (int, float)):
+                raise ValueError("progress.percent must be a number")
+            if not (0 <= percent <= 100):
+                raise ValueError("progress.percent must be between 0 and 100")
+        return v
+
+
+class TaskCancel(ASAPBaseModel):
+    """Request to cancel a running task.
+
+    TaskCancel requests cancellation of a task that is currently executing.
+    The agent should attempt graceful cancellation and cleanup.
+
+    Attributes:
+        task_id: ID of the task to cancel
+        reason: Optional reason for cancellation
+
+    Example:
+        >>> cancel = TaskCancel(
+        ...     task_id="task_123",
+        ...     reason="User requested cancellation"
+        ... )
+    """
+
+    task_id: TaskID = Field(..., description="Task identifier to cancel")
+    reason: str | None = Field(default=None, description="Optional cancellation reason")
+
+
+class MessageSend(ASAPBaseModel):
+    """Send a message within a task conversation.
+
+    MessageSend exchanges conversation turns between agents during
+    task execution, containing message content as parts.
+
+    Attributes:
+        task_id: ID of the task this message belongs to
+        message_id: Unique identifier for this message
+        sender: Agent URN of the message sender
+        role: Message role (user, assistant, system)
+        parts: List of part IDs that make up this message
+
+    Example:
+        >>> message = MessageSend(
+        ...     task_id="task_123",
+        ...     message_id="msg_456",
+        ...     sender="urn:asap:agent:coordinator",
+        ...     role="user",
+        ...     parts=["part_789"]
+        ... )
+    """
+
+    task_id: TaskID = Field(..., description="Parent task ID")
+    message_id: MessageID = Field(..., description="Unique message identifier")
+    sender: AgentURN = Field(..., description="Sender agent URN")
+    role: MessageRole = Field(..., description="Message role (user, assistant, system)")
+    parts: list[PartID] = Field(..., description="Part IDs making up this message")
+
+
+class StateQuery(ASAPBaseModel):
+    """Request a state snapshot for a task.
+
+    StateQuery requests the current or a specific version of a task's
+    state snapshot for inspection or restoration.
+
+    Attributes:
+        task_id: ID of the task to query state for
+        version: Optional specific version number to retrieve
+
+    Example:
+        >>> # Query latest state
+        >>> query = StateQuery(task_id="task_123")
+        >>>
+        >>> # Query specific version
+        >>> query = StateQuery(task_id="task_123", version=5)
+    """
+
+    task_id: TaskID = Field(..., description="Task identifier")
+    version: int | None = Field(default=None, description="Optional specific version to retrieve")
+
+
+class StateRestore(ASAPBaseModel):
+    """Restore a task to a previous state snapshot.
+
+    StateRestore requests restoration of a task to a previously saved
+    state snapshot, enabling rollback and recovery scenarios.
+
+    Attributes:
+        task_id: ID of the task to restore
+        snapshot_id: ID of the snapshot to restore from
+
+    Example:
+        >>> restore = StateRestore(
+        ...     task_id="task_123",
+        ...     snapshot_id="snap_456"
+        ... )
+    """
+
+    task_id: TaskID = Field(..., description="Task identifier")
+    snapshot_id: SnapshotID = Field(..., description="Snapshot ID to restore from")
+
+
+class ArtifactNotify(ASAPBaseModel):
+    """Notify about artifact creation or availability.
+
+    ArtifactNotify informs agents when a new artifact has been created
+    or is available for retrieval.
+
+    Attributes:
+        artifact_id: ID of the artifact
+        task_id: ID of the task that produced the artifact
+        name: Optional human-readable artifact name
+
+    Example:
+        >>> notify = ArtifactNotify(
+        ...     artifact_id="art_123",
+        ...     task_id="task_456",
+        ...     name="Q3 Market Analysis Report"
+        ... )
+    """
+
+    artifact_id: ArtifactID = Field(..., description="Artifact identifier")
+    task_id: TaskID = Field(..., description="Parent task ID")
+    name: str | None = Field(default=None, description="Optional human-readable artifact name")
+
+
+class McpToolCall(ASAPBaseModel):
+    """Call an MCP tool.
+
+    McpToolCall invokes a tool provided by an MCP server, enabling
+    agents to leverage external capabilities and integrations.
+
+    Attributes:
+        request_id: Unique identifier for this tool call request
+        tool_name: Name of the MCP tool to invoke
+        arguments: Arguments to pass to the tool (JSON-serializable)
+        mcp_context: Optional MCP-specific context (server, session, etc.)
+
+    Example:
+        >>> tool_call = McpToolCall(
+        ...     request_id="req_123",
+        ...     tool_name="web_search",
+        ...     arguments={"query": "AI trends", "max_results": 10},
+        ...     mcp_context={"server": "mcp://tools.example.com"}
+        ... )
+    """
+
+    request_id: str = Field(..., description="Unique request identifier")
+    tool_name: str = Field(..., description="MCP tool name to invoke")
+    arguments: dict[str, Any] = Field(..., description="Tool arguments (JSON-serializable)")
+    mcp_context: dict[str, Any] | None = Field(
+        default=None, description="Optional MCP context (server, session, etc.)"
+    )
+
+
+class McpToolResult(ASAPBaseModel):
+    """Result of an MCP tool call.
+
+    McpToolResult provides the outcome of an MCP tool invocation,
+    including success status, result data, or error information.
+
+    Attributes:
+        request_id: ID of the original tool call request
+        success: Whether the tool call succeeded
+        result: Optional result data (if successful)
+        error: Optional error message (if failed)
+
+    Example:
+        >>> # Successful result
+        >>> result = McpToolResult(
+        ...     request_id="req_123",
+        ...     success=True,
+        ...     result={"findings": ["finding1", "finding2"]}
+        ... )
+        >>>
+        >>> # Failed result
+        >>> result = McpToolResult(
+        ...     request_id="req_123",
+        ...     success=False,
+        ...     error="Tool execution failed: timeout"
+        ... )
+    """
+
+    request_id: str = Field(..., description="Original request identifier")
+    success: bool = Field(..., description="Whether tool call succeeded")
+    result: dict[str, Any] | None = Field(default=None, description="Result data (if successful)")
+    error: str | None = Field(default=None, description="Error message (if failed)")
+
+    @model_validator(mode="after")
+    def validate_result_error_exclusivity(self) -> "McpToolResult":
+        """Validate that result and error are mutually exclusive based on success.
+
+        When success=True, result must be provided and error must be None.
+        When success=False, error must be provided and result must be None.
+
+        Returns:
+            Self after validation
+
+        Raises:
+            ValueError: If result/error are not mutually exclusive based on success
+        """
+        if self.success:
+            if self.result is None:
+                raise ValueError("result must be provided when success=True")
+            if self.error is not None:
+                raise ValueError("error must be None when success=True")
+        else:
+            if self.error is None:
+                raise ValueError("error must be provided when success=False")
+            if self.result is not None:
+                raise ValueError("result must be None when success=False")
+        return self
+
+
+class McpResourceFetch(ASAPBaseModel):
+    """Request to fetch an MCP resource.
+
+    McpResourceFetch requests retrieval of a resource from an MCP server,
+    such as documentation, data, or other content.
+
+    Attributes:
+        resource_uri: URI of the MCP resource to fetch
+
+    Example:
+        >>> fetch = McpResourceFetch(
+        ...     resource_uri="mcp://server/resources/data_123"
+        ... )
+    """
+
+    resource_uri: str = Field(..., description="MCP resource URI to fetch")
+
+
+class McpResourceData(ASAPBaseModel):
+    """Data from an MCP resource.
+
+    McpResourceData provides the content of a fetched MCP resource.
+
+    Attributes:
+        resource_uri: URI of the resource
+        content: Resource content (JSON-serializable)
+
+    Example:
+        >>> data = McpResourceData(
+        ...     resource_uri="mcp://server/resources/data_123",
+        ...     content={"data": [1, 2, 3], "metadata": {"source": "api"}}
+        ... )
+    """
+
+    resource_uri: str = Field(..., description="MCP resource URI")
+    content: dict[str, Any] = Field(..., description="Resource content (JSON-serializable)")
+
+
+# Union type for all payload types
+# Note: The discriminator (payload_type) will be in the Envelope, not in individual payloads
+PayloadType = Union[
+    TaskRequest,
+    TaskResponse,
+    TaskUpdate,
+    TaskCancel,
+    MessageSend,
+    StateQuery,
+    StateRestore,
+    ArtifactNotify,
+    McpToolCall,
+    McpToolResult,
+    McpResourceFetch,
+    McpResourceData,
+]
+"""Union type of all ASAP payload types.
+
+PayloadType represents any of the 12 payload types used in ASAP protocol messages.
+The actual payload type discrimination is done via the 'payload_type' field in the
+Envelope that wraps these payloads.
+
+Payload types:
+- Task operations: TaskRequest, TaskResponse, TaskUpdate, TaskCancel
+- Messaging: MessageSend
+- State management: StateQuery, StateRestore, ArtifactNotify
+- MCP integration: McpToolCall, McpToolResult, McpResourceFetch, McpResourceData
+"""

asap/models/types.py

@@ -0,0 +1,39 @@
+"""Type aliases for ASAP protocol.
+
+This module defines type aliases to improve code readability and
+document the semantic meaning of string types.
+"""
+
+from typing import TypeAlias
+
+# Entity identifiers
+AgentURN: TypeAlias = str
+"""Agent identifier in URN format: urn:asap:agent:{name}"""
+
+ConversationID: TypeAlias = str
+"""Unique conversation identifier (ULID format)"""
+
+TaskID: TypeAlias = str
+"""Unique task identifier (ULID format)"""
+
+MessageID: TypeAlias = str
+"""Unique message identifier (ULID format)"""
+
+ArtifactID: TypeAlias = str
+"""Unique artifact identifier (ULID format)"""
+
+SnapshotID: TypeAlias = str
+"""Unique state snapshot identifier (ULID format)"""
+
+PartID: TypeAlias = str
+"""Unique part identifier (ULID format)"""
+
+# Other semantic types
+URI: TypeAlias = str
+"""Uniform Resource Identifier"""
+
+MIMEType: TypeAlias = str
+"""MIME type string (e.g., 'application/json')"""
+
+SemanticVersion: TypeAlias = str
+"""Semantic version string (e.g., '1.0.0')"""