solace-agent-mesh 1.11.2__py3-none-any.whl

solace_agent_mesh/gateway/adapter/__init__.py

@@ -0,0 +1 @@
+"""Abstract base classes and types for the Generic Gateway Adapter Framework."""

solace_agent_mesh/gateway/adapter/base.py

@@ -0,0 +1,143 @@
+"""
+Defines the abstract base class for Generic Gateway Adapters.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Generic, Optional, Type, TypeVar
+
+from pydantic import BaseModel
+
+from .types import (
+    AuthClaims,
+    GatewayContext,
+    ResponseContext,
+    SamDataPart,
+    SamError,
+    SamFilePart,
+    SamTask,
+    SamTextPart,
+    SamUpdate,
+)
+
+T_ExternalInput = TypeVar("T_ExternalInput", bound=Any)
+T_PlatformContext = TypeVar("T_PlatformContext", bound=Dict[str, Any])
+T_AdapterConfig = TypeVar("T_AdapterConfig", bound=BaseModel)
+
+
+class GatewayAdapter(
+    ABC, Generic[T_ExternalInput, T_PlatformContext, T_AdapterConfig]
+):
+    """
+    Abstract base class for gateway adapter plugins.
+
+    Gateway adapters handle platform-specific communication while the
+    GenericGatewayComponent manages A2A protocol complexity.
+    """
+
+    ConfigModel: Optional[Type[BaseModel]] = None
+
+    # --- Lifecycle ---
+    async def init(self, context: GatewayContext) -> None:
+        """
+        Initialize the gateway adapter.
+
+        This is where you should:
+        - Start platform listeners (WebSocket, HTTP server, stdin reader, etc.)
+        - Connect to external services and store the context for later use.
+        """
+        pass
+
+    async def cleanup(self) -> None:
+        """
+        Clean up resources on shutdown.
+
+        This is where you should:
+        - Stop platform listeners, close connections, and release resources.
+        """
+        pass
+
+    # --- Authentication ---
+    async def extract_auth_claims(
+        self,
+        external_input: T_ExternalInput,
+        endpoint_context: Optional[Dict[str, Any]] = None,
+    ) -> Optional[AuthClaims]:
+        """
+        Extract authentication claims from platform input.
+
+        Return AuthClaims with user info/tokens, or None to use config-based auth.
+        """
+        return None
+
+    # --- Inbound: Platform -> A2A ---
+    @abstractmethod
+    async def prepare_task(
+        self,
+        external_input: T_ExternalInput,
+        endpoint_context: Optional[Dict[str, Any]] = None,
+    ) -> SamTask:
+        """
+        Prepare a task from platform input.
+
+        This method is called after authentication succeeds. Convert your
+        platform's event format into a SamTask with parts.
+        """
+        pass
+
+    # --- Outbound: A2A -> Platform ---
+    async def handle_update(self, update: SamUpdate, context: ResponseContext) -> None:
+        """
+        Handle an update from the agent (batch handler).
+
+        By default, this method dispatches to individual part handlers.
+        Override for custom batch processing.
+        """
+        for part in update.parts:
+            if isinstance(part, SamTextPart):
+                await self.handle_text_chunk(part.text, context)
+            elif isinstance(part, SamFilePart):
+                await self.handle_file(part, context)
+            elif isinstance(part, SamDataPart):
+                # Check for special data part types that have their own handlers
+                if part.data.get("type") == "agent_progress_update":
+                    status_text = part.data.get("status_text")
+                    if status_text:
+                        await self.handle_status_update(status_text, context)
+                else:
+                    # Fallback to the generic data part handler
+                    await self.handle_data_part(part, context)
+
+    async def handle_text_chunk(self, text: str, context: ResponseContext) -> None:
+        """
+        Handle streaming text chunk from the agent.
+
+        This is called by the default `handle_update` implementation.
+        An adapter can override this method to process text parts individually.
+        """
+        pass
+
+    async def handle_file(
+        self, file_part: SamFilePart, context: ResponseContext
+    ) -> None:
+        """Handle file/artifact from the agent."""
+        pass
+
+    async def handle_data_part(
+        self, data_part: SamDataPart, context: ResponseContext
+    ) -> None:
+        """Handle structured data part from the agent."""
+        pass
+
+    async def handle_status_update(
+        self, status_text: str, context: ResponseContext
+    ) -> None:
+        """Handle agent status update (progress indicator)."""
+        pass
+
+    async def handle_task_complete(self, context: ResponseContext) -> None:
+        """Handle task completion notification."""
+        pass
+
+    async def handle_error(self, error: SamError, context: ResponseContext) -> None:
+        """Handle error from the agent or gateway."""
+        pass

solace_agent_mesh/gateway/adapter/types.py

@@ -0,0 +1,221 @@
+"""
+Defines the Pydantic models for the Generic Gateway Adapter framework.
+
+These types create a stable abstraction layer, decoupling gateway adapters from the
+underlying A2A protocol specifics.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable, Dict, List, Literal, Optional, Union
+
+from pydantic import BaseModel, Field, model_validator
+
+if TYPE_CHECKING:
+    from google.adk.artifacts import BaseArtifactService
+    from ...common.a2a.types import ArtifactInfo
+
+
+# --- Content Part Models ---
+
+
+class SamTextPart(BaseModel):
+    """Text content in a SAM task."""
+
+    type: Literal["text"] = "text"
+    text: str
+
+
+class SamFilePart(BaseModel):
+    """File content in a SAM task, with either inline bytes or a URI."""
+
+    type: Literal["file"] = "file"
+    name: str
+    content_bytes: Optional[bytes] = None
+    uri: Optional[str] = None
+    mime_type: Optional[str] = None
+
+    @model_validator(mode="after")
+    def validate_content_or_uri(self) -> "SamFilePart":
+        """Ensures that either content_bytes or uri is set, but not both."""
+        if not self.content_bytes and not self.uri:
+            raise ValueError("SamFilePart must have either 'content_bytes' or 'uri'.")
+        if self.content_bytes and self.uri:
+            raise ValueError("SamFilePart cannot have both 'content_bytes' and 'uri'.")
+        return self
+
+
+class SamDataPart(BaseModel):
+    """Structured data in a SAM task."""
+
+    type: Literal["data"] = "data"
+    data: Dict[str, Any]
+    metadata: Optional[Dict[str, Any]] = None
+
+
+SamContentPart = Union[SamTextPart, SamFilePart, SamDataPart]
+
+
+# --- Task and Update Models ---
+
+
+class SamTask(BaseModel):
+    """A task prepared for submission to the SAM agent mesh."""
+
+    parts: List[SamContentPart]
+    session_id: Optional[str] = None
+    target_agent: str = Field(..., description="Target agent name (required).")
+    is_streaming: bool = Field(default=True, description="Enable streaming responses.")
+    platform_context: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Platform-specific data for response routing.",
+    )
+
+
+class SamUpdate(BaseModel):
+    """An update event from the agent containing one or more parts."""
+
+    parts: List[SamContentPart] = Field(default_factory=list)
+    is_final: bool = Field(
+        default=False,
+        description="True if this is the final update before task completion.",
+    )
+
+
+# --- Auth and Error Models ---
+
+
+class AuthClaims(BaseModel):
+    """Authentication claims extracted from a platform event."""
+
+    id: Optional[str] = Field(
+        default=None,
+        description="Primary user identifier. If None, generic gateway uses auth_config default.",
+    )
+    email: Optional[str] = None
+    token: Optional[str] = Field(
+        default=None, description="Bearer token or API key for token-based auth flows."
+    )
+    token_type: Optional[Literal["bearer", "api_key"]] = None
+    source: str = Field(default="platform", description="Authentication source.")
+    raw_context: Dict[str, Any] = Field(
+        default_factory=dict, description="Platform-specific auth context."
+    )
+
+
+class SamError(BaseModel):
+    """A structured error object for outbound error handling."""
+
+    message: str
+    code: int
+    category: Literal[
+        "FAILED", "CANCELED", "TIMED_OUT", "PROTOCOL_ERROR", "GATEWAY_ERROR"
+    ]
+
+
+class SamFeedback(BaseModel):
+    """A structured model for submitting user feedback."""
+
+    task_id: str
+    session_id: str
+    rating: Literal["up", "down"]
+    comment: Optional[str] = None
+    user_id: str
+
+
+# --- Context Models ---
+
+
+class ResponseContext(BaseModel):
+    """Context provided with each outbound response callback."""
+
+    task_id: str
+    session_id: Optional[str]
+    user_id: str
+    platform_context: Dict[str, Any]
+
+
+class GatewayContext:
+    """
+    Context provided to gateway adapter during initialization.
+
+    Provides access to gateway services and helper methods.
+    This is an abstract class definition; the concrete implementation is the
+    GenericGatewayComponent.
+    """
+
+    gateway_id: str
+    namespace: str
+    config: Dict[str, Any]
+    adapter_config: Any  # Can be a Pydantic model or a dict
+    artifact_service: "BaseArtifactService"
+
+    async def handle_external_input(
+        self, external_input: Any, endpoint_context: Optional[Dict[str, Any]] = None
+    ) -> str:
+        raise NotImplementedError
+
+    async def cancel_task(self, task_id: str) -> None:
+        raise NotImplementedError
+
+    async def submit_feedback(self, feedback: "SamFeedback") -> None:
+        """Submits user feedback related to a task."""
+        raise NotImplementedError
+
+    async def load_artifact_content(
+        self, context: "ResponseContext", filename: str, version: Union[int, str] = "latest"
+    ) -> Optional[bytes]:
+        """Loads the raw byte content of an artifact."""
+        raise NotImplementedError
+
+    async def list_artifacts(
+        self, context: "ResponseContext"
+    ) -> List["ArtifactInfo"]:
+        """Lists all artifacts available in the user's context."""
+        raise NotImplementedError
+
+    def add_timer(
+        self, delay_ms: int, callback: "Callable", interval_ms: Optional[int] = None
+    ) -> str:
+        raise NotImplementedError
+
+    def cancel_timer(self, timer_id: str) -> None:
+        raise NotImplementedError
+
+    def get_task_state(self, task_id: str, key: str, default: Any = None) -> Any:
+        raise NotImplementedError
+
+    def set_task_state(self, task_id: str, key: str, value: Any) -> None:
+        raise NotImplementedError
+
+    def get_session_state(self, session_id: str, key: str, default: Any = None) -> Any:
+        raise NotImplementedError
+
+    def set_session_state(self, session_id: str, key: str, value: Any) -> None:
+        raise NotImplementedError
+
+    def create_text_part(self, text: str) -> SamTextPart:
+        return SamTextPart(text=text)
+
+    def create_file_part_from_bytes(
+        self, name: str, content_bytes: bytes, mime_type: str
+    ) -> SamFilePart:
+        return SamFilePart(name=name, content_bytes=content_bytes, mime_type=mime_type)
+
+    def create_file_part_from_uri(
+        self, uri: str, name: str, mime_type: Optional[str] = None
+    ) -> SamFilePart:
+        return SamFilePart(name=name, uri=uri, mime_type=mime_type)
+
+    def create_data_part(self, data: Dict[str, Any]) -> SamDataPart:
+        return SamDataPart(data=data)
+
+    def process_sac_template(
+        self,
+        template: str,
+        payload: Any = None,
+        headers: Optional[Dict[str, str]] = None,
+        query_params: Optional[Dict[str, str]] = None,
+        user_data: Optional[Dict[str, Any]] = None,
+    ) -> str:
+        raise NotImplementedError

solace_agent_mesh/gateway/base/__init__.py

@@ -0,0 +1 @@
+"""Base classes and utilities for the Gateway Development Kit (GDK)."""