asap-protocol 0.1.0__py3-none-any.whl

asap/examples/run_demo.py

@@ -0,0 +1,120 @@
+"""Run the ASAP two-agent demo.
+
+This script starts the echo agent as a subprocess, then demonstrates
+communication by sending a task request from the coordinator logic.
+"""
+
+import asyncio
+import signal
+import subprocess
+import sys
+import time
+from typing import Sequence
+
+import httpx
+
+from asap.examples.coordinator import dispatch_task
+from asap.observability import get_logger
+
+ECHO_MANIFEST_URL = "http://127.0.0.1:8001/.well-known/asap/manifest.json"
+ECHO_BASE_URL = "http://127.0.0.1:8001"
+READY_TIMEOUT_SECONDS = 10.0
+READY_POLL_INTERVAL_SECONDS = 0.5
+
+ECHO_AGENT_MODULE = "asap.examples.echo_agent"
+
+logger = get_logger(__name__)
+
+
+def start_process(command: Sequence[str]) -> subprocess.Popen[str]:
+    """Start a subprocess and return its handle.
+
+    Args:
+        command: Command to execute as a sequence.
+
+    Returns:
+        Started subprocess handle.
+    """
+    return subprocess.Popen(command, text=True)
+
+
+def wait_for_ready(url: str, timeout_seconds: float) -> None:
+    """Wait for the given URL to respond with HTTP 200.
+
+    Args:
+        url: The URL to poll for readiness.
+        timeout_seconds: Maximum time to wait before failing.
+
+    Raises:
+        RuntimeError: If the service does not become ready in time.
+    """
+    deadline = time.monotonic() + timeout_seconds
+    while time.monotonic() < deadline:
+        try:
+            response = httpx.get(url, timeout=1.0)
+            if response.status_code == 200:
+                return
+        except httpx.HTTPError:
+            pass
+        time.sleep(READY_POLL_INTERVAL_SECONDS)
+    raise RuntimeError(f"Service not ready after {timeout_seconds:.1f}s: {url}")
+
+
+def _terminate_process(process: subprocess.Popen[str] | None) -> None:
+    """Terminate a subprocess if it is still running."""
+    if process is None or process.poll() is not None:
+        return
+    process.terminate()
+    try:
+        process.wait(timeout=3)
+    except subprocess.TimeoutExpired:
+        process.kill()
+        process.wait(timeout=3)
+
+
+def main() -> None:
+    """Start echo agent and demonstrate communication via coordinator logic."""
+    echo_command = [sys.executable, "-m", ECHO_AGENT_MODULE]
+    echo_process = None
+
+    def handle_signal(signum: int, _frame: object) -> None:
+        """Handle shutdown signals by terminating child processes."""
+        signal_name = signal.Signals(signum).name
+        raise RuntimeError(f"Shutdown requested ({signal_name})")
+
+    signal.signal(signal.SIGINT, handle_signal)
+    signal.signal(signal.SIGTERM, handle_signal)
+
+    try:
+        # Start echo agent server
+        echo_process = start_process(echo_command)
+        wait_for_ready(ECHO_MANIFEST_URL, READY_TIMEOUT_SECONDS)
+        logger.info("asap.demo.echo_ready", url=ECHO_MANIFEST_URL)
+
+        # Demonstrate communication using coordinator dispatch logic
+        logger.info("asap.demo.starting_communication")
+        try:
+            response = asyncio.run(
+                dispatch_task(
+                    payload={"message": "Hello from demo runner!"},
+                    echo_base_url=ECHO_BASE_URL,
+                )
+            )
+            logger.info(
+                "asap.demo.communication_success",
+                request_id=response.correlation_id,
+                response_id=response.id,
+                payload_type=response.payload_type,
+            )
+            print(f"\n✅ Demo successful! Response: {response.payload}\n")
+        except Exception as e:
+            logger.exception("asap.demo.communication_failed", error=str(e))
+            print(f"\n❌ Demo failed: {e}\n")
+            raise
+
+    finally:
+        _terminate_process(echo_process)
+
+
+if __name__ == "__main__":
+    main()

asap/models/__init__.py

@@ -0,0 +1,146 @@
+"""ASAP Protocol Models.
+
+This module provides all the Pydantic models for the ASAP protocol,
+including entities, parts, payloads, and the envelope wrapper.
+"""
+
+# Base models
+from asap.models.base import ASAPBaseModel
+
+# Constants
+from asap.models.constants import (
+    AGENT_URN_PATTERN,
+    ASAP_PROTOCOL_VERSION,
+    DEFAULT_TIMEOUT_SECONDS,
+    MAX_TASK_DEPTH,
+)
+
+# Enums
+from asap.models.enums import MessageRole, TaskStatus, UpdateType
+
+# Type aliases
+from asap.models.types import (
+    AgentURN,
+    ArtifactID,
+    ConversationID,
+    MessageID,
+    MIMEType,
+    PartID,
+    SemanticVersion,
+    SnapshotID,
+    TaskID,
+    URI,
+)
+
+# ID utilities
+from asap.models.ids import extract_timestamp, generate_id
+
+# Entities
+from asap.models.entities import (
+    Agent,
+    Artifact,
+    AuthScheme,
+    Capability,
+    Conversation,
+    Endpoint,
+    Manifest,
+    Message,
+    Skill,
+    StateSnapshot,
+    Task,
+)
+
+# Parts
+from asap.models.parts import (
+    DataPart,
+    FilePart,
+    Part,
+    PartType,
+    ResourcePart,
+    TemplatePart,
+    TextPart,
+)
+
+# Payloads
+from asap.models.payloads import (
+    ArtifactNotify,
+    McpResourceData,
+    McpResourceFetch,
+    McpToolCall,
+    McpToolResult,
+    MessageSend,
+    PayloadType,
+    StateQuery,
+    StateRestore,
+    TaskCancel,
+    TaskRequest,
+    TaskResponse,
+    TaskUpdate,
+)
+
+# Envelope
+from asap.models.envelope import Envelope
+
+__all__ = [
+    # Base
+    "ASAPBaseModel",
+    # Constants
+    "AGENT_URN_PATTERN",
+    "ASAP_PROTOCOL_VERSION",
+    "DEFAULT_TIMEOUT_SECONDS",
+    "MAX_TASK_DEPTH",
+    # Enums
+    "MessageRole",
+    "TaskStatus",
+    "UpdateType",
+    # Type aliases
+    "AgentURN",
+    "ArtifactID",
+    "ConversationID",
+    "MessageID",
+    "MIMEType",
+    "PartID",
+    "SemanticVersion",
+    "SnapshotID",
+    "TaskID",
+    "URI",
+    # IDs
+    "generate_id",
+    "extract_timestamp",
+    # Entities
+    "Agent",
+    "Artifact",
+    "AuthScheme",
+    "Capability",
+    "Conversation",
+    "Endpoint",
+    "Manifest",
+    "Message",
+    "Skill",
+    "StateSnapshot",
+    "Task",
+    # Parts
+    "DataPart",
+    "FilePart",
+    "Part",
+    "PartType",
+    "ResourcePart",
+    "TemplatePart",
+    "TextPart",
+    # Payloads
+    "ArtifactNotify",
+    "McpResourceData",
+    "McpResourceFetch",
+    "McpToolCall",
+    "McpToolResult",
+    "MessageSend",
+    "PayloadType",
+    "StateQuery",
+    "StateRestore",
+    "TaskCancel",
+    "TaskRequest",
+    "TaskResponse",
+    "TaskUpdate",
+    # Envelope
+    "Envelope",
+]

asap/models/base.py

@@ -0,0 +1,55 @@
+"""Base Pydantic model configuration for ASAP protocol models.
+
+All ASAP models inherit from ASAPBaseModel to ensure consistent behavior:
+- Immutability (frozen=True) for thread-safety and predictability
+- Strict validation (extra="forbid") to catch typos and invalid fields
+- Flexible field naming (populate_by_name=True) for alias support
+- JSON Schema generation with proper metadata
+"""
+
+from pydantic import BaseModel, ConfigDict
+
+
+class ASAPBaseModel(BaseModel):
+    """Base model for all ASAP protocol entities.
+
+    This base class provides:
+    - **Immutability**: Models are frozen after creation (thread-safe)
+    - **Strict validation**: Extra fields are forbidden (catches errors early)
+    - **Flexible naming**: Fields can be populated by name or alias
+    - **JSON Schema**: Proper schema generation for interoperability
+
+    Example:
+        >>> from pydantic import Field
+        >>> class MyModel(ASAPBaseModel):
+        ...     name: str
+        ...     count: int = Field(default=0, ge=0)
+        >>>
+        >>> obj = MyModel(name="test", count=5)
+        >>> obj.name
+        'test'
+        >>> obj.count = 10  # Raises ValidationError (frozen)
+        Traceback (most recent call last):
+        ...
+        pydantic_core._pydantic_core.ValidationError: ...
+    """
+
+    model_config = ConfigDict(
+        # Immutability: prevents accidental mutations after creation
+        frozen=True,
+        # Strict validation: reject unknown fields to catch typos
+        extra="forbid",
+        # Allow populating fields by both name and alias
+        populate_by_name=True,
+        # JSON Schema configuration
+        # Use enum values (not names) in schema
+        use_enum_values=False,
+        # Validate default values
+        validate_default=True,
+        # Validate assignments (only relevant if frozen=False)
+        validate_assignment=True,
+        # JSON Schema extras for better documentation
+        json_schema_extra={
+            "additionalProperties": False,
+        },
+    )

asap/models/constants.py

@@ -0,0 +1,14 @@
+"""Constants for ASAP protocol.
+
+This module defines protocol-wide constants used across the codebase.
+"""
+
+# Protocol version
+ASAP_PROTOCOL_VERSION = "0.1"
+
+# Default configuration values
+DEFAULT_TIMEOUT_SECONDS = 600
+MAX_TASK_DEPTH = 10  # Maximum nesting level for subtasks
+
+# URN patterns
+AGENT_URN_PATTERN = r"^urn:asap:agent:[a-z0-9-]+(?::[a-z0-9-]+)?$"