asap-protocol 0.1.0__py3-none-any.whl

asap/__init__.py

@@ -0,0 +1,7 @@
+"""ASAP: Async Simple Agent Protocol.
+
+A streamlined, scalable, asynchronous protocol for agent-to-agent communication
+and task coordination.
+"""
+
+__version__ = "0.1.0"

asap/cli.py

@@ -0,0 +1,220 @@
+"""Command-line interface for ASAP Protocol utilities.
+
+This module provides CLI commands for schema export, inspection, and validation.
+
+Example:
+    >>> # From terminal:
+    >>> # asap --version
+    >>> # asap export-schemas --output-dir ./schemas
+    >>> # asap list-schemas
+    >>> # asap show-schema agent
+    >>> # asap validate-schema message.json --schema-type envelope
+"""
+
+import json
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+from pydantic import ValidationError
+
+from asap import __version__
+from asap.schemas import SCHEMA_REGISTRY, export_all_schemas, get_schema_json, list_schema_entries
+
+app = typer.Typer(help="ASAP Protocol CLI.")
+
+# Default directory for schema operations
+DEFAULT_SCHEMAS_DIR = Path("schemas")
+
+# Global verbose flag
+_verbose: bool = False
+
+
+def _version_callback(value: bool) -> None:
+    """Print the version and exit when requested."""
+    if value:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+VERSION_OPTION = typer.Option(
+    False,
+    "--version",
+    help="Show ASAP Protocol version and exit.",
+    callback=_version_callback,
+    is_eager=True,
+)
+
+# Module-level singleton options to avoid B008 linting errors
+OUTPUT_DIR_EXPORT_OPTION = typer.Option(
+    DEFAULT_SCHEMAS_DIR,
+    "--output-dir",
+    help="Directory where JSON schemas will be written.",
+)
+OUTPUT_DIR_LIST_OPTION = typer.Option(
+    DEFAULT_SCHEMAS_DIR,
+    "--output-dir",
+    help="Directory where JSON schemas are written.",
+)
+
+
+@app.callback()
+def cli(
+    version: bool = VERSION_OPTION,
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Enable verbose output."),
+) -> None:
+    """ASAP Protocol CLI entrypoint."""
+    global _verbose
+    _verbose = verbose
+
+
+@app.command("export-schemas")
+def export_schemas(
+    output_dir: Path = OUTPUT_DIR_EXPORT_OPTION,
+) -> None:
+    """Export all ASAP JSON schemas to the output directory."""
+    try:
+        written_paths = export_all_schemas(output_dir)
+        typer.echo(f"Exported {len(written_paths)} schemas to {output_dir}")
+        if _verbose:
+            for path in sorted(written_paths):
+                typer.echo(f"  - {path.relative_to(output_dir)}")
+    except PermissionError as exc:
+        raise typer.BadParameter(f"Cannot write to directory: {output_dir}") from exc
+    except OSError as exc:
+        raise typer.BadParameter(f"Failed to export schemas: {exc}") from exc
+
+
+@app.command("list-schemas")
+def list_schemas(
+    output_dir: Path = OUTPUT_DIR_LIST_OPTION,
+) -> None:
+    """List available schema names and output paths."""
+    entries = list_schema_entries(output_dir)
+    for name, path in entries:
+        typer.echo(f"{name}\t{path.relative_to(output_dir)}")
+
+
+@app.command("show-schema")
+def show_schema(schema_name: str) -> None:
+    """Print the JSON schema for a named model."""
+    try:
+        schema = get_schema_json(schema_name)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+    typer.echo(json.dumps(schema, indent=2))
+
+
+def _detect_schema_type(data: dict[str, object]) -> str | None:
+    """Attempt to auto-detect schema type from JSON data.
+
+    Auto-detects envelope type if payload_type field is present.
+
+    Args:
+        data: Parsed JSON data.
+
+    Returns:
+        Detected schema type name or None if not detectable.
+    """
+    # Envelope detection: has payload_type field
+    if "payload_type" in data and "asap_version" in data:
+        return "envelope"
+    return None
+
+
+def _validate_against_schema(data: dict[str, object], schema_type: str) -> list[str]:
+    """Validate JSON data against a registered schema.
+
+    Args:
+        data: Parsed JSON data to validate.
+        schema_type: Schema type name from SCHEMA_REGISTRY.
+
+    Returns:
+        List of validation error messages (empty if valid).
+
+    Raises:
+        ValueError: If schema_type is not registered.
+    """
+    if schema_type not in SCHEMA_REGISTRY:
+        raise ValueError(f"Unknown schema type: {schema_type}")
+
+    model_class = SCHEMA_REGISTRY[schema_type]
+    try:
+        model_class.model_validate(data)
+        return []
+    except ValidationError as exc:
+        errors: list[str] = []
+        for error in exc.errors():
+            loc = ".".join(str(part) for part in error["loc"])
+            msg = error["msg"]
+            errors.append(f"  - {loc}: {msg}")
+        return errors
+
+
+@app.command("validate-schema")
+def validate_schema(
+    file: Annotated[Path, typer.Argument(help="Path to JSON file to validate.")],
+    schema_type: Annotated[
+        Optional[str],
+        typer.Option(
+            "--schema-type",
+            help="Schema type to validate against (e.g., agent, envelope, task_request).",
+        ),
+    ] = None,
+) -> None:
+    """Validate a JSON file against an ASAP schema.
+
+    The schema type can be auto-detected for envelope files (those containing
+    payload_type and asap_version fields). For other schema types, use the
+    --schema-type option.
+
+    Available schema types: agent, manifest, conversation, task, message,
+    artifact, state_snapshot, text_part, data_part, file_part, resource_part,
+    template_part, task_request, task_response, task_update, task_cancel,
+    message_send, state_query, state_restore, artifact_notify, mcp_tool_call,
+    mcp_tool_result, mcp_resource_fetch, mcp_resource_data, envelope.
+    """
+    # Check file exists
+    if not file.exists():
+        raise typer.BadParameter(f"File not found: {file}")
+
+    # Parse JSON
+    try:
+        content = file.read_text(encoding="utf-8")
+        data = json.loads(content)
+    except json.JSONDecodeError as exc:
+        raise typer.BadParameter(f"Invalid JSON: {exc}") from exc
+
+    if not isinstance(data, dict):
+        raise typer.BadParameter("JSON root must be an object")
+
+    # Determine schema type
+    effective_schema_type = schema_type
+    if effective_schema_type is None:
+        effective_schema_type = _detect_schema_type(data)
+        if effective_schema_type is None:
+            raise typer.BadParameter(
+                "Cannot auto-detect schema type. Use --schema-type to specify."
+            )
+
+    # Validate
+    try:
+        errors = _validate_against_schema(data, effective_schema_type)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+    if errors:
+        error_details = "\n".join(errors)
+        raise typer.BadParameter(f"Validation error:\n{error_details}")
+
+    typer.echo(f"Valid {effective_schema_type} schema: {file}")
+
+
+def main() -> None:
+    """Run the ASAP Protocol CLI."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

asap/errors.py

@@ -0,0 +1,150 @@
+"""ASAP Protocol Error Taxonomy.
+
+This module defines the error hierarchy for the ASAP protocol,
+providing structured error handling with specific error codes
+and context information.
+"""
+
+from typing import Any
+
+
+class ASAPError(Exception):
+    """Base exception for all ASAP protocol errors.
+
+    This is the root exception class that all ASAP-specific errors
+    should inherit from. It provides a standardized way to handle
+    protocol-level errors with error codes and additional context.
+
+    Attributes:
+        code: Error code following the asap:error/... pattern
+        message: Human-readable error message
+        details: Optional additional error context
+    """
+
+    def __init__(self, code: str, message: str, details: dict[str, Any] | None = None) -> None:
+        """Initialize ASAP error.
+
+        Args:
+            code: Error code (e.g., 'asap:protocol/invalid_state')
+            message: Human-readable error description
+            details: Optional dictionary with additional error context
+        """
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.details = details or {}
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert error to dictionary for JSON serialization.
+
+        Returns:
+            Dictionary containing code, message, and details
+        """
+        return {
+            "code": self.code,
+            "message": self.message,
+            "details": self.details,
+        }
+
+
+class InvalidTransitionError(ASAPError):
+    """Raised when attempting an invalid task state transition.
+
+    This error occurs when trying to change a task from one status
+    to another status that is not allowed by the state machine rules.
+
+    Attributes:
+        from_state: The current task status
+        to_state: The attempted target status
+    """
+
+    def __init__(
+        self, from_state: str, to_state: str, details: dict[str, Any] | None = None
+    ) -> None:
+        """Initialize invalid transition error.
+
+        Args:
+            from_state: Current task status
+            to_state: Attempted target status
+            details: Optional additional context
+        """
+        message = f"Invalid transition from '{from_state}' to '{to_state}'"
+        super().__init__(
+            code="asap:protocol/invalid_state",
+            message=message,
+            details={"from_state": from_state, "to_state": to_state, **(details or {})},
+        )
+        self.from_state = from_state
+        self.to_state = to_state
+
+
+class MalformedEnvelopeError(ASAPError):
+    """Raised when receiving a malformed or invalid envelope.
+
+    This error occurs when the envelope structure is invalid,
+    missing required fields, or contains malformed data that
+    cannot be processed by the protocol.
+    """
+
+    def __init__(self, reason: str, details: dict[str, Any] | None = None) -> None:
+        """Initialize malformed envelope error.
+
+        Args:
+            reason: Description of what's malformed
+            details: Optional additional context (e.g., validation errors)
+        """
+        message = f"Malformed envelope: {reason}"
+        super().__init__(
+            code="asap:protocol/malformed_envelope", message=message, details=details or {}
+        )
+        self.reason = reason
+
+
+class TaskNotFoundError(ASAPError):
+    """Raised when a requested task cannot be found.
+
+    This error occurs when attempting to access or modify a task
+    that doesn't exist in the system.
+    """
+
+    def __init__(self, task_id: str, details: dict[str, Any] | None = None) -> None:
+        """Initialize task not found error.
+
+        Args:
+            task_id: The ID of the task that was not found
+            details: Optional additional context
+        """
+        message = f"Task not found: {task_id}"
+        super().__init__(
+            code="asap:task/not_found",
+            message=message,
+            details={"task_id": task_id, **(details or {})},
+        )
+        self.task_id = task_id
+
+
+class TaskAlreadyCompletedError(ASAPError):
+    """Raised when attempting to modify a task that is already completed.
+
+    This error occurs when trying to perform operations on a task
+    that has reached a terminal state and cannot be modified further.
+    """
+
+    def __init__(
+        self, task_id: str, current_status: str, details: dict[str, Any] | None = None
+    ) -> None:
+        """Initialize task already completed error.
+
+        Args:
+            task_id: The ID of the completed task
+            current_status: The current terminal status
+            details: Optional additional context
+        """
+        message = f"Task already completed: {task_id} (status: {current_status})"
+        super().__init__(
+            code="asap:task/already_completed",
+            message=message,
+            details={"task_id": task_id, "current_status": current_status, **(details or {})},
+        )
+        self.task_id = task_id
+        self.current_status = current_status

asap/examples/README.md

@@ -0,0 +1,25 @@
+## Overview
+
+The examples demonstrate a minimal end-to-end flow between two agents:
+an echo agent and a coordinator agent.
+
+## Running the demo
+
+Run the demo runner module from the repository root:
+
+- `uv run python -m asap.examples.run_demo`
+
+This starts the echo agent on port 8001 and the coordinator agent on port 8000.
+The coordinator sends a TaskRequest to the echo agent and logs the response.
+
+## Running agents individually
+
+You can run the agents separately if needed:
+
+- `uv run python -m asap.examples.echo_agent --host 127.0.0.1 --port 8001`
+- `uv run python -m asap.examples.coordinator`
+
+## Notes
+
+- The echo agent exposes `/.well-known/asap/manifest.json` for readiness checks.
+- Update ports in `asap.examples.run_demo` if you change the defaults.

asap/examples/__init__.py

@@ -0,0 +1 @@
+"""Example agents and demo runner for ASAP protocol."""

asap/examples/coordinator.py

@@ -0,0 +1,184 @@
+"""Coordinator agent example for ASAP protocol.
+
+This module defines a coordinator agent with a manifest and FastAPI app.
+The coordinator will dispatch tasks to other agents in later steps.
+"""
+
+import argparse
+import asyncio
+from typing import Any, Sequence
+
+from fastapi import FastAPI
+
+from asap.models.entities import Capability, Endpoint, Manifest, Skill
+from asap.models.envelope import Envelope
+from asap.models.ids import generate_id
+from asap.models.payloads import TaskRequest
+from asap.observability import get_logger
+from asap.observability.logging import bind_context, clear_context
+from asap.transport.client import ASAPClient
+from asap.transport.server import create_app
+
+DEFAULT_AGENT_ID = "urn:asap:agent:coordinator"
+DEFAULT_AGENT_NAME = "Coordinator Agent"
+DEFAULT_AGENT_VERSION = "0.1.0"
+DEFAULT_AGENT_DESCRIPTION = "Coordinates tasks across agents"
+DEFAULT_ASAP_ENDPOINT = "http://localhost:8000/asap"
+DEFAULT_ECHO_AGENT_ID = "urn:asap:agent:echo-agent"
+DEFAULT_ECHO_BASE_URL = "http://127.0.0.1:8001"
+
+logger = get_logger(__name__)
+
+
+def build_manifest(asap_endpoint: str = DEFAULT_ASAP_ENDPOINT) -> Manifest:
+    """Build the manifest for the coordinator agent.
+
+    Args:
+        asap_endpoint: URL where the agent receives ASAP messages.
+
+    Returns:
+        Manifest describing the coordinator agent's capabilities and endpoints.
+    """
+    return Manifest(
+        id=DEFAULT_AGENT_ID,
+        name=DEFAULT_AGENT_NAME,
+        version=DEFAULT_AGENT_VERSION,
+        description=DEFAULT_AGENT_DESCRIPTION,
+        capabilities=Capability(
+            asap_version="0.1",
+            skills=[Skill(id="coordinate", description="Dispatch tasks to agents")],
+            state_persistence=False,
+        ),
+        endpoints=Endpoint(asap=asap_endpoint),
+    )
+
+
+def create_coordinator_app(asap_endpoint: str = DEFAULT_ASAP_ENDPOINT) -> FastAPI:
+    """Create the FastAPI app for the coordinator agent.
+
+    Args:
+        asap_endpoint: URL where the agent receives ASAP messages.
+
+    Returns:
+        Configured FastAPI app.
+    """
+    manifest = build_manifest(asap_endpoint)
+    return create_app(manifest)
+
+
+app = create_coordinator_app()
+
+
+def build_task_request(payload: dict[str, Any]) -> TaskRequest:
+    """Build a TaskRequest payload for the echo agent.
+
+    Args:
+        payload: Input data to echo.
+
+    Returns:
+        TaskRequest payload ready for dispatch.
+    """
+    return TaskRequest(
+        conversation_id=generate_id(),
+        skill_id="echo",
+        input=payload,
+    )
+
+
+def build_task_envelope(payload: dict[str, Any]) -> Envelope:
+    """Build a TaskRequest envelope targeting the echo agent.
+
+    Args:
+        payload: Input data to echo.
+
+    Returns:
+        TaskRequest envelope for transmission.
+    """
+    task_request = build_task_request(payload)
+    return Envelope(
+        asap_version="0.1",
+        sender=DEFAULT_AGENT_ID,
+        recipient=DEFAULT_ECHO_AGENT_ID,
+        payload_type="task.request",
+        payload=task_request.model_dump(),
+        trace_id=generate_id(),
+    )
+
+
+async def dispatch_task(
+    payload: dict[str, Any],
+    echo_base_url: str = DEFAULT_ECHO_BASE_URL,
+) -> Envelope:
+    """Dispatch a task to the echo agent using ASAPClient.
+
+    Args:
+        payload: Input data to echo.
+        echo_base_url: Base URL for the echo agent (no trailing /asap).
+
+    Returns:
+        Response envelope from the echo agent.
+    """
+    envelope = build_task_envelope(payload)
+    bind_context(trace_id=envelope.trace_id, correlation_id=envelope.id)
+    try:
+        logger.info(
+            "asap.coordinator.request_sent",
+            request_id=envelope.id,
+            payload_type=envelope.payload_type,
+            payload=envelope.payload,
+        )
+    finally:
+        clear_context()
+    async with ASAPClient(echo_base_url) as client:
+        response = await client.send(envelope)
+
+    bind_context(
+        trace_id=envelope.trace_id,
+        correlation_id=response.correlation_id,
+    )
+    try:
+        logger.info(
+            "asap.coordinator.response_received",
+            request_id=envelope.id,
+            response_id=response.id,
+            payload_type=response.payload_type,
+            result=response.payload,
+        )
+    finally:
+        clear_context()
+    return response
+
+
+def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
+    """Parse command-line arguments for the coordinator agent.
+
+    Args:
+        argv: Optional list of CLI arguments for testing.
+
+    Returns:
+        Parsed argparse namespace.
+    """
+    parser = argparse.ArgumentParser(description="Run the ASAP coordinator agent.")
+    parser.add_argument(
+        "--echo-url",
+        default=DEFAULT_ECHO_BASE_URL,
+        help="Base URL for the echo agent (no trailing /asap).",
+    )
+    parser.add_argument(
+        "--message",
+        default="hello from coordinator",
+        help="Message to send to the echo agent.",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    """Run a sample dispatch to the echo agent."""
+    args = parse_args(argv)
+    payload: dict[str, Any] = {"message": args.message}
+    response = asyncio.run(dispatch_task(payload, echo_base_url=args.echo_url))
+    logger.info("asap.coordinator.demo_complete", response=response.payload)
+
+
+if __name__ == "__main__":
+    main()

asap/examples/echo_agent.py

@@ -0,0 +1,100 @@
+"""Echo agent example for ASAP protocol.
+
+This module defines a minimal echo agent with a manifest and FastAPI app.
+It uses the default handler registry to echo task input as output.
+"""
+
+import argparse
+from typing import Sequence
+
+from fastapi import FastAPI
+import uvicorn
+
+from asap.models.entities import Capability, Endpoint, Manifest, Skill
+from asap.transport.handlers import HandlerRegistry, create_echo_handler
+from asap.transport.server import create_app
+
+DEFAULT_AGENT_ID = "urn:asap:agent:echo-agent"
+DEFAULT_AGENT_NAME = "Echo Agent"
+DEFAULT_AGENT_VERSION = "0.1.0"
+DEFAULT_AGENT_DESCRIPTION = "Echoes task input as output"
+DEFAULT_ASAP_HOST = "127.0.0.1"
+DEFAULT_ASAP_PORT = 8001
+DEFAULT_ASAP_ENDPOINT = f"http://{DEFAULT_ASAP_HOST}:{DEFAULT_ASAP_PORT}/asap"
+
+
+def build_manifest(asap_endpoint: str = DEFAULT_ASAP_ENDPOINT) -> Manifest:
+    """Build the manifest for the echo agent.
+
+    Args:
+        asap_endpoint: URL where the agent receives ASAP messages.
+
+    Returns:
+        Manifest describing the echo agent's capabilities and endpoints.
+    """
+    return Manifest(
+        id=DEFAULT_AGENT_ID,
+        name=DEFAULT_AGENT_NAME,
+        version=DEFAULT_AGENT_VERSION,
+        description=DEFAULT_AGENT_DESCRIPTION,
+        capabilities=Capability(
+            asap_version="0.1",
+            skills=[Skill(id="echo", description="Echo back the input")],
+            state_persistence=False,
+        ),
+        endpoints=Endpoint(asap=asap_endpoint),
+    )
+
+
+def create_echo_app(asap_endpoint: str = DEFAULT_ASAP_ENDPOINT) -> FastAPI:
+    """Create the FastAPI app for the echo agent.
+
+    Args:
+        asap_endpoint: URL where the agent receives ASAP messages.
+
+    Returns:
+        Configured FastAPI app.
+    """
+    manifest = build_manifest(asap_endpoint)
+    registry = HandlerRegistry()
+    registry.register("task.request", create_echo_handler())
+    return create_app(manifest, registry)
+
+
+app = create_echo_app()
+
+
+def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
+    """Parse command-line arguments for the echo agent.
+
+    Args:
+        argv: Optional list of CLI arguments for testing.
+
+    Returns:
+        Parsed argparse namespace.
+    """
+    parser = argparse.ArgumentParser(description="Run the ASAP echo agent.")
+    parser.add_argument(
+        "--host",
+        default=DEFAULT_ASAP_HOST,
+        help="Host to bind the echo agent server.",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=DEFAULT_ASAP_PORT,
+        help="Port to bind the echo agent server.",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    """Run the echo agent with configurable host and port."""
+    args = parse_args(argv)
+    endpoint = f"http://{args.host}:{args.port}/asap"
+    agent_app = create_echo_app(endpoint)
+    uvicorn.run(agent_app, host=args.host, port=args.port)
+
+
+if __name__ == "__main__":
+    main()