asap-protocol 0.1.0__py3-none-any.whl

asap/schemas.py

@@ -0,0 +1,203 @@
+"""Schema export helpers for ASAP models.
+
+This module provides utilities for exporting JSON schemas from ASAP
+Pydantic models, enabling schema validation and tooling integration.
+
+Example:
+    >>> from asap.schemas import get_schema_json, list_schema_entries
+    >>> schema = get_schema_json("agent")
+    >>> schema["title"]
+    'Agent'
+"""
+
+import json
+from pathlib import Path
+
+from asap.models import (
+    Agent,
+    Artifact,
+    ArtifactNotify,
+    Conversation,
+    DataPart,
+    Envelope,
+    FilePart,
+    Manifest,
+    McpResourceData,
+    McpResourceFetch,
+    McpToolCall,
+    McpToolResult,
+    Message,
+    MessageSend,
+    ResourcePart,
+    StateQuery,
+    StateRestore,
+    StateSnapshot,
+    Task,
+    TaskCancel,
+    TaskRequest,
+    TaskResponse,
+    TaskUpdate,
+    TemplatePart,
+    TextPart,
+)
+from asap.models.base import ASAPBaseModel
+
+# Schema registry mapping names to model classes
+SCHEMA_REGISTRY: dict[str, type[ASAPBaseModel]] = {
+    "agent": Agent,
+    "manifest": Manifest,
+    "conversation": Conversation,
+    "task": Task,
+    "message": Message,
+    "artifact": Artifact,
+    "state_snapshot": StateSnapshot,
+    "text_part": TextPart,
+    "data_part": DataPart,
+    "file_part": FilePart,
+    "resource_part": ResourcePart,
+    "template_part": TemplatePart,
+    "task_request": TaskRequest,
+    "task_response": TaskResponse,
+    "task_update": TaskUpdate,
+    "task_cancel": TaskCancel,
+    "message_send": MessageSend,
+    "state_query": StateQuery,
+    "state_restore": StateRestore,
+    "artifact_notify": ArtifactNotify,
+    "mcp_tool_call": McpToolCall,
+    "mcp_tool_result": McpToolResult,
+    "mcp_resource_fetch": McpResourceFetch,
+    "mcp_resource_data": McpResourceData,
+    "envelope": Envelope,
+}
+
+# Total number of schemas in the registry
+TOTAL_SCHEMA_COUNT = len(SCHEMA_REGISTRY)
+
+# Schema output path mapping for directory organization
+_SCHEMA_PATHS: dict[str, str] = {
+    # Entities
+    "agent": "entities/agent.schema.json",
+    "manifest": "entities/manifest.schema.json",
+    "conversation": "entities/conversation.schema.json",
+    "task": "entities/task.schema.json",
+    "message": "entities/message.schema.json",
+    "artifact": "entities/artifact.schema.json",
+    "state_snapshot": "entities/state_snapshot.schema.json",
+    # Parts
+    "text_part": "parts/text_part.schema.json",
+    "data_part": "parts/data_part.schema.json",
+    "file_part": "parts/file_part.schema.json",
+    "resource_part": "parts/resource_part.schema.json",
+    "template_part": "parts/template_part.schema.json",
+    # Payloads
+    "task_request": "payloads/task_request.schema.json",
+    "task_response": "payloads/task_response.schema.json",
+    "task_update": "payloads/task_update.schema.json",
+    "task_cancel": "payloads/task_cancel.schema.json",
+    "message_send": "payloads/message_send.schema.json",
+    "state_query": "payloads/state_query.schema.json",
+    "state_restore": "payloads/state_restore.schema.json",
+    "artifact_notify": "payloads/artifact_notify.schema.json",
+    "mcp_tool_call": "payloads/mcp_tool_call.schema.json",
+    "mcp_tool_result": "payloads/mcp_tool_result.schema.json",
+    "mcp_resource_fetch": "payloads/mcp_resource_fetch.schema.json",
+    "mcp_resource_data": "payloads/mcp_resource_data.schema.json",
+    # Envelope (root level)
+    "envelope": "envelope.schema.json",
+}
+
+
+def list_schema_entries(output_dir: Path) -> list[tuple[str, Path]]:
+    """List all available schema names and their output paths.
+
+    Args:
+        output_dir: Base directory where schemas are written.
+
+    Returns:
+        List of (schema_name, output_path) tuples.
+
+    Example:
+        >>> from pathlib import Path
+        >>> entries = list_schema_entries(Path("schemas"))
+        >>> any(name == "agent" for name, _ in entries)
+        True
+    """
+    return [(name, output_dir / rel_path) for name, rel_path in _SCHEMA_PATHS.items()]
+
+
+def get_schema_json(schema_name: str) -> dict[str, object]:
+    """Return the JSON schema for a named model.
+
+    Args:
+        schema_name: Schema identifier (e.g., "agent", "task_request").
+
+    Returns:
+        JSON schema dictionary for the model.
+
+    Raises:
+        ValueError: If the schema name is not recognized.
+
+    Example:
+        >>> schema = get_schema_json("agent")
+        >>> schema["title"]
+        'Agent'
+        >>> "properties" in schema
+        True
+    """
+    if schema_name not in SCHEMA_REGISTRY:
+        raise ValueError(f"Unknown schema name: {schema_name}")
+    return SCHEMA_REGISTRY[schema_name].model_json_schema()
+
+
+def export_schema(model_class: type[ASAPBaseModel], output_path: Path) -> Path:
+    """Export JSON Schema for a model to a file.
+
+    Creates parent directories if they don't exist. Overwrites existing files.
+
+    Args:
+        model_class: Pydantic model class to export.
+        output_path: Path to write the schema file.
+
+    Returns:
+        The path that was written.
+
+    Example:
+        >>> from pathlib import Path
+        >>> from asap.models import Agent
+        >>> path = export_schema(Agent, Path("/tmp/agent.schema.json"))
+        >>> path.exists()
+        True
+    """
+    schema = model_class.model_json_schema()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(json.dumps(schema, indent=2), encoding="utf-8")
+    return output_path
+
+
+def export_all_schemas(output_dir: Path) -> list[Path]:
+    """Export all ASAP model schemas to the given directory.
+
+    Creates the directory structure (entities/, parts/, payloads/) and
+    writes all schema files.
+
+    Args:
+        output_dir: Base directory to write schemas into.
+
+    Returns:
+        List of schema file paths that were written.
+
+    Example:
+        >>> from pathlib import Path
+        >>> paths = export_all_schemas(Path("/tmp/schemas"))
+        >>> len(paths) == 24
+        True
+    """
+    written_paths: list[Path] = []
+
+    for name, rel_path in _SCHEMA_PATHS.items():
+        model_class = SCHEMA_REGISTRY[name]
+        output_path = output_dir / rel_path
+        written_paths.append(export_schema(model_class, output_path))
+
+    return written_paths

asap/state/__init__.py

@@ -0,0 +1,22 @@
+"""ASAP State Management Module.
+
+This module provides state machine functionality for managing
+task lifecycles and state transitions in the ASAP protocol.
+
+Example:
+    >>> from asap.models.enums import TaskStatus
+    >>> can_transition(TaskStatus.SUBMITTED, TaskStatus.WORKING)
+    True
+"""
+
+from .machine import can_transition, transition
+from .snapshot import InMemorySnapshotStore, SnapshotStore
+from asap.models.enums import TaskStatus
+
+__all__ = [
+    "TaskStatus",
+    "can_transition",
+    "transition",
+    "SnapshotStore",
+    "InMemorySnapshotStore",
+]

asap/state/machine.py

@@ -0,0 +1,86 @@
+"""ASAP Task State Machine.
+
+This module implements the task state machine for the ASAP protocol,
+managing valid state transitions and providing transition validation.
+
+Example:
+    >>> from asap.models.enums import TaskStatus
+    >>> can_transition(TaskStatus.SUBMITTED, TaskStatus.WORKING)
+    True
+"""
+
+from datetime import datetime, timezone
+
+from asap.errors import InvalidTransitionError
+from asap.models.entities import Task
+from asap.models.enums import TaskStatus
+
+
+# Valid state transitions mapping
+VALID_TRANSITIONS: dict[TaskStatus, set[TaskStatus]] = {
+    TaskStatus.SUBMITTED: {TaskStatus.WORKING, TaskStatus.CANCELLED},
+    TaskStatus.WORKING: {
+        TaskStatus.COMPLETED,
+        TaskStatus.FAILED,
+        TaskStatus.CANCELLED,
+        TaskStatus.INPUT_REQUIRED,
+    },
+    TaskStatus.INPUT_REQUIRED: {TaskStatus.WORKING, TaskStatus.CANCELLED},
+    TaskStatus.COMPLETED: set(),  # Terminal state
+    TaskStatus.FAILED: set(),  # Terminal state
+    TaskStatus.CANCELLED: set(),  # Terminal state
+}
+
+
+def can_transition(from_status: TaskStatus, to_status: TaskStatus) -> bool:
+    """Check if a transition from one status to another is valid.
+
+    Args:
+        from_status: Current task status
+        to_status: Target task status
+
+    Returns:
+        True if the transition is valid, False otherwise
+
+    Example:
+        >>> can_transition(TaskStatus.SUBMITTED, TaskStatus.WORKING)
+        True
+        >>> can_transition(TaskStatus.COMPLETED, TaskStatus.WORKING)
+        False
+    """
+    valid_targets = VALID_TRANSITIONS.get(from_status, set())
+    return to_status in valid_targets
+
+
+def transition(task: Task, new_status: TaskStatus) -> Task:
+    """Transition a task to a new status with validation.
+
+    Args:
+        task: The task to transition
+        new_status: The target status
+
+    Returns:
+        New task instance with updated status and updated_at timestamp
+
+    Raises:
+        InvalidTransitionError: If the transition is not valid
+
+    Example:
+        >>> task = Task(
+        ...     id="task_01HX5K4N...",
+        ...     conversation_id="conv_01HX5K3M...",
+        ...     status=TaskStatus.SUBMITTED,
+        ...     created_at=datetime.now(timezone.utc),
+        ...     updated_at=datetime.now(timezone.utc),
+        ... )
+        >>> updated = transition(task, TaskStatus.WORKING)
+        >>> updated.status
+        <TaskStatus.WORKING: 'working'>
+    """
+    if not can_transition(task.status, new_status):
+        raise InvalidTransitionError(
+            from_state=task.status.value, to_state=new_status.value, details={"task_id": task.id}
+        )
+
+    # Create new task instance with updated status and timestamp (immutable approach)
+    return task.model_copy(update={"status": new_status, "updated_at": datetime.now(timezone.utc)})

asap/state/snapshot.py

@@ -0,0 +1,265 @@
+"""ASAP Snapshot Store for task state persistence.
+
+This module provides interfaces and implementations for storing and retrieving
+task state snapshots, enabling state persistence across agent restarts.
+
+Example:
+    >>> store = InMemorySnapshotStore()
+    >>> store.list_versions("task_01HX5K4N...")
+    []
+"""
+
+import threading
+from typing import Protocol, runtime_checkable
+
+from asap.models.entities import StateSnapshot
+from asap.models.types import TaskID
+
+
+@runtime_checkable
+class SnapshotStore(Protocol):
+    """Protocol for snapshot storage implementations.
+
+    Provides the interface for storing and retrieving task state snapshots.
+    Implementations can use various backends (memory, database, file system, etc.).
+    This uses Protocol for duck typing, allowing any class that implements
+    these methods to be used as a SnapshotStore.
+
+    Example:
+        >>> class CustomStore:
+        ...     def save(self, snapshot: StateSnapshot) -> None:
+        ...         pass
+        ...     def get(self, task_id: TaskID, version: int | None = None) -> StateSnapshot | None:
+        ...         return None
+        ...     def list_versions(self, task_id: TaskID) -> list[int]:
+        ...         return []
+        ...     def delete(self, task_id: TaskID, version: int | None = None) -> bool:
+        ...         return False
+        >>> isinstance(CustomStore(), SnapshotStore)
+        True
+    """
+
+    def save(self, snapshot: StateSnapshot) -> None:
+        """Save a snapshot to the store.
+
+        Args:
+            snapshot: The snapshot to save
+
+        Example:
+            >>> from datetime import datetime, timezone
+            >>> store = InMemorySnapshotStore()
+            >>> snapshot = StateSnapshot(
+            ...     id="snap_01HX5K7R...",
+            ...     task_id="task_01HX5K4N...",
+            ...     version=1,
+            ...     data={"status": "submitted"},
+            ...     created_at=datetime.now(timezone.utc),
+            ... )
+            >>> store.save(snapshot)
+        """
+        ...
+
+    def get(self, task_id: TaskID, version: int | None = None) -> StateSnapshot | None:
+        """Retrieve a snapshot for the given task.
+
+        Args:
+            task_id: The task ID to retrieve snapshots for
+            version: Optional specific version to retrieve. If None, returns latest.
+
+        Returns:
+            The snapshot if found, None otherwise
+
+        Example:
+            >>> store = InMemorySnapshotStore()
+            >>> store.get("task_01HX5K4N...")
+            None
+        """
+        ...
+
+    def list_versions(self, task_id: TaskID) -> list[int]:
+        """List all available versions for a task.
+
+        Args:
+            task_id: The task ID to list versions for
+
+        Returns:
+            List of version numbers in ascending order
+
+        Example:
+            >>> store = InMemorySnapshotStore()
+            >>> store.list_versions("task_01HX5K4N...")
+            []
+        """
+        ...
+
+    def delete(self, task_id: TaskID, version: int | None = None) -> bool:
+        """Delete snapshot(s) for a task.
+
+        Args:
+            task_id: The task ID
+            version: If provided, delete only this version. Otherwise delete all.
+
+        Returns:
+            True if any snapshots were deleted, False otherwise
+
+        Example:
+            >>> store = InMemorySnapshotStore()
+            >>> store.delete("task_01HX5K4N...")
+            False
+        """
+        ...
+
+
+class InMemorySnapshotStore:
+    """In-memory implementation of SnapshotStore.
+
+    Stores snapshots in memory using dictionaries. Useful for testing
+    and simple applications that don't require persistence across restarts.
+
+    This implementation is thread-safe using RLock for concurrent access.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the in-memory snapshot store.
+
+        Example:
+            >>> store = InMemorySnapshotStore()
+            >>> isinstance(store, InMemorySnapshotStore)
+            True
+        """
+        self._lock = threading.RLock()
+        # task_id -> version -> snapshot
+        self._snapshots: dict[TaskID, dict[int, StateSnapshot]] = {}
+        # task_id -> latest version
+        self._latest_versions: dict[TaskID, int] = {}
+
+    def save(self, snapshot: StateSnapshot) -> None:
+        """Save a snapshot to the in-memory store.
+
+        Args:
+            snapshot: The snapshot to save
+
+        Example:
+            >>> from datetime import datetime, timezone
+            >>> store = InMemorySnapshotStore()
+            >>> snapshot = StateSnapshot(
+            ...     id="snap_01HX5K7R...",
+            ...     task_id="task_01HX5K4N...",
+            ...     version=1,
+            ...     data={"status": "submitted"},
+            ...     created_at=datetime.now(timezone.utc),
+            ... )
+            >>> store.save(snapshot)
+        """
+        with self._lock:
+            task_id = snapshot.task_id
+
+            # Initialize storage for this task if needed
+            if task_id not in self._snapshots:
+                self._snapshots[task_id] = {}
+
+            # Store the snapshot
+            self._snapshots[task_id][snapshot.version] = snapshot
+
+            # Update latest version
+            self._latest_versions[task_id] = max(
+                self._latest_versions.get(task_id, 0), snapshot.version
+            )
+
+    def get(self, task_id: TaskID, version: int | None = None) -> StateSnapshot | None:
+        """Retrieve a snapshot from the in-memory store.
+
+        Args:
+            task_id: The task ID to retrieve snapshots for
+            version: Optional specific version to retrieve. If None, returns latest.
+
+        Returns:
+            The snapshot if found, None otherwise
+
+        Example:
+            >>> store = InMemorySnapshotStore()
+            >>> store.get("task_01HX5K4N...")
+            None
+        """
+        with self._lock:
+            if task_id not in self._snapshots:
+                return None
+
+            if version is None:
+                # Return latest version
+                latest_version = self._latest_versions.get(task_id)
+                if latest_version is None:
+                    return None
+                return self._snapshots[task_id].get(latest_version)
+
+            # Return specific version
+            return self._snapshots[task_id].get(version)
+
+    def list_versions(self, task_id: TaskID) -> list[int]:
+        """List all available versions for a task.
+
+        Args:
+            task_id: The task ID to list versions for
+
+        Returns:
+            List of version numbers in ascending order
+
+        Example:
+            >>> store = InMemorySnapshotStore()
+            >>> store.list_versions("task_01HX5K4N...")
+            []
+        """
+        with self._lock:
+            if task_id not in self._snapshots:
+                return []
+
+            return sorted(self._snapshots[task_id].keys())
+
+    def delete(self, task_id: TaskID, version: int | None = None) -> bool:
+        """Delete snapshot(s) for a task.
+
+        Args:
+            task_id: The task ID
+            version: If provided, delete only this version. Otherwise delete all.
+
+        Returns:
+            True if any snapshots were deleted, False otherwise
+
+        Example:
+            >>> store = InMemorySnapshotStore()
+            >>> store.delete("task_01HX5K4N...")
+            False
+        """
+        with self._lock:
+            if task_id not in self._snapshots:
+                return False
+
+            if version is None:
+                # Delete all versions for this task
+                if task_id in self._snapshots:
+                    del self._snapshots[task_id]
+                    if task_id in self._latest_versions:
+                        del self._latest_versions[task_id]
+                    return True
+                return False
+
+            # Delete specific version
+            if version in self._snapshots[task_id]:
+                del self._snapshots[task_id][version]
+
+                # Update latest version if needed
+                if self._latest_versions.get(task_id) == version:
+                    if self._snapshots[task_id]:
+                        self._latest_versions[task_id] = max(self._snapshots[task_id].keys())
+                    else:
+                        del self._latest_versions[task_id]
+
+                # Clean up empty task dict
+                if not self._snapshots[task_id]:
+                    del self._snapshots[task_id]
+                    if task_id in self._latest_versions:
+                        del self._latest_versions[task_id]
+
+                return True
+
+            return False

asap/transport/__init__.py

@@ -0,0 +1,84 @@
+"""ASAP Protocol HTTP Transport Layer.
+
+This module provides HTTP-based transport for ASAP messages using:
+- JSON-RPC 2.0 for request/response wrapping
+- FastAPI for server implementation
+- httpx for async client implementation
+- Handler registry for payload dispatch
+
+Public exports:
+    JsonRpcRequest: JSON-RPC 2.0 request wrapper
+    JsonRpcResponse: JSON-RPC 2.0 response wrapper
+    JsonRpcError: JSON-RPC 2.0 error object
+    JsonRpcErrorResponse: JSON-RPC 2.0 error response wrapper
+    create_app: FastAPI application factory
+    HandlerRegistry: Registry for payload handlers
+    HandlerNotFoundError: Error for missing handlers
+    Handler: Type alias for handler functions
+    create_echo_handler: Factory for echo handler
+    create_default_registry: Factory for default registry
+    ASAPClient: Async HTTP client for agent communication
+    ASAPConnectionError: Connection error exception
+    ASAPTimeoutError: Timeout error exception
+    ASAPRemoteError: Remote error exception
+
+Example:
+    >>> from asap.transport import ASAPClient, create_app
+    >>> from asap.models.entities import Manifest, Capability, Endpoint, Skill
+    >>> manifest = Manifest(
+    ...     id="urn:asap:agent:demo",
+    ...     name="Demo Agent",
+    ...     version="1.0.0",
+    ...     description="Demo manifest",
+    ...     capabilities=Capability(
+    ...         asap_version="0.1",
+    ...         skills=[Skill(id="echo", description="Echo")],
+    ...         state_persistence=False,
+    ...     ),
+    ...     endpoints=Endpoint(asap="http://localhost:8000/asap"),
+    ... )
+    >>> app = create_app(manifest)
+"""
+
+from asap.transport.client import (
+    ASAPClient,
+    ASAPConnectionError,
+    ASAPRemoteError,
+    ASAPTimeoutError,
+)
+from asap.transport.handlers import (
+    Handler,
+    HandlerNotFoundError,
+    HandlerRegistry,
+    create_default_registry,
+    create_echo_handler,
+)
+from asap.transport.jsonrpc import (
+    JsonRpcError,
+    JsonRpcErrorResponse,
+    JsonRpcRequest,
+    JsonRpcResponse,
+)
+from asap.transport.server import ASAPRequestHandler, create_app
+
+__all__ = [
+    # JSON-RPC
+    "JsonRpcRequest",
+    "JsonRpcResponse",
+    "JsonRpcError",
+    "JsonRpcErrorResponse",
+    # Server
+    "create_app",
+    "ASAPRequestHandler",
+    # Handlers
+    "HandlerRegistry",
+    "HandlerNotFoundError",
+    "Handler",
+    "create_echo_handler",
+    "create_default_registry",
+    # Client
+    "ASAPClient",
+    "ASAPConnectionError",
+    "ASAPTimeoutError",
+    "ASAPRemoteError",
+]