solace-agent-mesh 1.6.1__py3-none-any.whl → 1.13.2__py3-none-any.whl

solace_agent_mesh/common/data_parts.py

@@ -71,10 +71,53 @@ class ArtifactCreationProgressData(BaseModel):
         description="The constant type for this data part.",
     )
     filename: str = Field(..., description="The name of the artifact being created.")
-    bytes_saved: int = Field(..., description="The number of bytes saved so far.")
-    artifact_chunk: str = Field(
-        ...,
-        description="The chunk of artifact data that was saved in this progress update.",
+    status: Literal["in-progress", "completed", "failed"] = Field(
+        ..., description="The status of the artifact creation."
+    )
+    bytes_transferred: int = Field(
+        ..., description="The number of bytes transferred so far."
+    )
+    description: Optional[str] = Field(
+        None, description="An optional description of the artifact being created."
+    )
+    artifact_chunk: Optional[str] = Field(
+        None,
+        description="The chunk of artifact data that was transferred in this progress update. Only present for 'in-progress' status.",
+    )
+    mime_type: Optional[str] = Field(
+        None,
+        description="The MIME type of the artifact. Only present for 'completed' status.",
+    )
+    version: Optional[int] = Field(
+        None,
+        description="The version number of the artifact being created or updated.",
+    )
+    function_call_id: Optional[str] = Field(
+        None, description="The function call ID if artifact was created by a tool."
+    )
+
+
+class ArtifactSavedData(BaseModel):
+    """
+    Data model for an artifact saved notification signal.
+    This is sent when an artifact has been successfully saved to storage.
+    Unlike ArtifactCreationProgressData, this is a single notification event
+    and does not follow the start->updates->end protocol.
+    """
+
+    type: Literal["artifact_saved"] = Field(
+        "artifact_saved",
+        description="The constant type for this data part.",
+    )
+    filename: str = Field(..., description="The name of the saved artifact.")
+    version: int = Field(..., description="The version number of the saved artifact.")
+    mime_type: str = Field(..., description="The MIME type of the artifact.")
+    size_bytes: int = Field(..., description="The size of the artifact in bytes.")
+    description: Optional[str] = Field(
+        None, description="An optional description of the artifact."
+    )
+    function_call_id: Optional[str] = Field(
+        None, description="The function call ID if artifact was created by a tool."
     )
 
 
@@ -98,10 +141,107 @@ class ToolResultData(BaseModel):
     )
 
 
+class TemplateBlockData(BaseModel):
+    """
+    Data model for a buffered inline template block ready for resolution.
+    Corresponds to template_block.json schema.
+    """
+
+    type: Literal["template_block"] = Field(
+        "template_block", description="The constant type for this data part."
+    )
+    template_id: str = Field(
+        ..., description="UUID for tracking this specific template instance."
+    )
+    data_artifact: str = Field(
+        ..., description="Data artifact filename or filename:version."
+    )
+    jsonpath: Optional[str] = Field(
+        None, description="Optional JSONPath expression to filter data."
+    )
+    limit: Optional[int] = Field(
+        None, description="Optional limit on number of items/rows to pass to template."
+    )
+    template_content: str = Field(
+        ..., description="The full Liquid template content."
+    )
+
+
+class DeepResearchProgressData(BaseModel):
+    """
+    Data model for deep research progress updates with structured information.
+    Provides detailed progress for UI visualization during iterative research.
+    """
+
+    type: Literal["deep_research_progress"] = Field(
+        "deep_research_progress", description="The constant type for this data part."
+    )
+    phase: str = Field(..., description="Current phase: planning, searching, analyzing, writing")
+    status_text: str = Field(..., description="Human-readable status message")
+    progress_percentage: int = Field(..., description="Overall progress percentage (0-100)")
+    current_iteration: int = Field(..., description="Current iteration number")
+    total_iterations: int = Field(..., description="Total planned iterations")
+    sources_found: int = Field(..., description="Total sources found so far")
+    current_query: str = Field(default="", description="Current search query being executed")
+    fetching_urls: list[Dict[str, str]] = Field(
+        default_factory=list,
+        description="List of sources being analyzed (with title, favicon/icon, and source_type)"
+    )
+    elapsed_seconds: int = Field(..., description="Elapsed time in seconds")
+    max_runtime_seconds: int = Field(default=0, description="Maximum runtime limit (0 = no limit)")
+
+
+class RAGInfoUpdateData(BaseModel):
+    """
+    Data model for RAG info panel updates during deep research.
+    Sends title and sources to the UI early so the RAG info panel can display them
+    while research is still in progress.
+    """
+
+    type: Literal["rag_info_update"] = Field(
+        "rag_info_update", description="The constant type for this data part."
+    )
+    title: str = Field(..., description="Human-readable title for the research (generated by LLM)")
+    query: str = Field(..., description="The original research question/query")
+    search_type: str = Field(default="deep_research", description="Type of search (deep_research, web_search, etc.)")
+    sources: list[Dict[str, Any]] = Field(
+        default_factory=list,
+        description="List of sources found so far (in camelCase format for frontend)"
+    )
+    is_complete: bool = Field(default=False, description="Whether the research is complete")
+    timestamp: str = Field(..., description="ISO timestamp of this update")
+
+
+class DeepResearchReportData(BaseModel):
+    """
+    Data model for a deep research report completion signal.
+    This is sent when a deep research report artifact has been created and saved.
+    The frontend will use this to render the DeepResearchReportBubble component
+    instead of displaying the report content inline.
+    
+    This signal bypasses the LLM response entirely, ensuring the report is displayed
+    via the artifact viewer without duplication.
+    """
+
+    type: Literal["deep_research_report"] = Field(
+        "deep_research_report", description="The constant type for this data part."
+    )
+    filename: str = Field(..., description="The filename of the research report artifact.")
+    version: int = Field(..., description="The version number of the artifact.")
+    uri: str = Field(..., description="The artifact URI for fetching the report content.")
+    title: Optional[str] = Field(None, description="Human-readable title for the research.")
+    sources_count: int = Field(default=0, description="Number of sources analyzed.")
+
+
 SignalData = Union[
     ToolInvocationStartData,
     LlmInvocationData,
     AgentProgressUpdateData,
     ArtifactCreationProgressData,
+    ArtifactSavedData,
     ToolResultData,
+    TemplateBlockData,
+    DeepResearchProgressData,
+    RAGInfoUpdateData,
+    DeepResearchReportData,
 ]

solace_agent_mesh/common/error_handlers.py

@@ -0,0 +1,83 @@
+"""Centralized error handlers for Solace Agent Mesh."""
+
+from typing import Tuple
+from litellm.exceptions import BadRequestError
+
+
+# User-facing error messages
+CONTEXT_LIMIT_ERROR_MESSAGE = (
+    "The conversation history has become too long for the AI model to process. "
+    "This can happen after extended conversations. "
+    "To continue, please start a new conversation."
+)
+
+DEFAULT_BAD_REQUEST_MESSAGE = (
+    "An unexpected error occurred during tool execution. "
+    "Please try your request again. If the problem persists, "
+    "contact an administrator."
+)
+
+
+def _is_context_limit_error(exception: Exception) -> bool:
+    """
+    Detects if an exception is a context/token limit error from LiteLLM.
+    
+    Args:
+        exception: The exception to check
+        
+    Returns:
+        True if the exception indicates a context limit error
+    """
+    if not isinstance(exception, BadRequestError):
+        return False
+    
+    error_str = str(exception).lower()
+    
+    # Context limit error patterns from various LLM providers
+    context_limit_patterns = [
+        "too many tokens",
+        "expected maxlength:",
+        "input is too long",
+        "prompt is too long",
+        "prompt: length: 1..",
+        "too many input tokens",
+    ]
+    
+    return any(pattern in error_str for pattern in context_limit_patterns)
+
+
+def _get_user_friendly_error_message(exception: Exception) -> str:
+    """
+    Returns a user-friendly error message for the given exception.
+    
+    Args:
+        exception: The exception to get a message for
+        
+    Returns:
+        User-friendly error message string
+    """
+    if _is_context_limit_error(exception):
+        return CONTEXT_LIMIT_ERROR_MESSAGE
+    
+    if isinstance(exception, BadRequestError):
+        return f"Bad request: {exception}"
+    
+    return DEFAULT_BAD_REQUEST_MESSAGE
+
+
+def get_error_message(
+    exception: BadRequestError,
+) -> Tuple[str, bool]:
+    """
+    Handles BadRequestError and returns error information.
+    
+    Args:
+        exception: The BadRequestError to handle
+        
+    Returns:
+        Tuple of (error_message, is_context_limit_error)
+    """
+    is_context_limit = _is_context_limit_error(exception)
+    error_message = _get_user_friendly_error_message(exception)
+    
+    return error_message, is_context_limit

solace_agent_mesh/common/exceptions.py

@@ -23,3 +23,27 @@ class MessageSizeExceededError(Exception):
             )
 
         super().__init__(message)
+
+
+class ComponentInitializationError(Exception):
+    """Raised when a SAM component fails to initialize."""
+
+    def __init__(self, component_identifier: str, original_error: Exception, message: str = None):
+        """Initialize the ComponentInitializationError.
+
+        Args:
+            component_identifier: The identifier of the component that failed to initialize.
+            original_error: The original exception that caused the failure.
+            message: Optional custom error message. If None, a default message
+                    will be generated.
+        """
+        self.component_identifier = component_identifier
+        self.original_error = original_error
+
+        if message is None:
+            message = (
+                f"Component {component_identifier} failed to initialize: "
+                f"{original_error}"
+            )
+
+        super().__init__(message)

solace_agent_mesh/common/oauth/__init__.py

@@ -0,0 +1,17 @@
+"""Common OAuth 2.0 components for Solace Agent Mesh.
+
+This module provides pure OAuth 2.0 protocol implementations that can be
+used across different components (LLM providers, A2A proxies, etc.) without
+domain-specific logic.
+"""
+
+from .oauth_client import OAuth2Client, OAuth2RetryClient
+from .utils import calculate_expires_at, is_token_expired, validate_https_url
+
+__all__ = [
+    "OAuth2Client",
+    "OAuth2RetryClient",
+    "calculate_expires_at",
+    "is_token_expired",
+    "validate_https_url",
+]