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

solace_agent_mesh/agent/tools/web_tools.py

@@ -2,6 +2,7 @@
 Collection of Python tools for web-related tasks, such as making HTTP requests.
 """
 
+import asyncio
 import logging
 import json
 import uuid
@@ -32,6 +33,10 @@ log = logging.getLogger(__name__)
 CATEGORY_NAME = "Web Access"
 CATEGORY_DESCRIPTION = "Access the web to find information to complete user requests."
 
+# Response size limits (in bytes)
+DEFAULT_MAX_RESPONSE_SIZE = 10 * 1024 * 1024  # 10 MB default
+ABSOLUTE_MAX_RESPONSE_SIZE = 50 * 1024 * 1024  # 50 MB hard cap (cannot be exceeded even via config)
+
 def _is_safe_url(url: str) -> bool:
     """
     Checks if a URL is safe to request by resolving its hostname and checking
@@ -70,9 +75,10 @@ async def web_request(
     output_artifact_filename: Optional[str] = None,
     tool_context: ToolContext = None,
     tool_config: Optional[Dict[str, Any]] = None,
+    max_retries: int = 2,
 ) -> Dict[str, Any]:
     """
-    Makes an HTTP request to the specified URL, processes the content (e.g., HTML to Markdown),
+    Makes an HTTP request to the specified URL with retry logic, processes the content (e.g., HTML to Markdown),
     and saves the result as an artifact.
 
     Args:
@@ -82,7 +88,10 @@ async def web_request(
         body: Optional request body string for methods like POST/PUT. If sending JSON, this should be a valid JSON string.
         output_artifact_filename: Optional. Desired filename for the output artifact.
         tool_context: The context provided by the ADK framework.
-        tool_config: Optional. Configuration passed by the ADK, generally not used by this simplified tool.
+        tool_config: Optional. Configuration passed by the ADK. Supports:
+            - allow_loopback: bool - Allow requests to loopback addresses (for testing)
+            - max_response_size_bytes: int - Maximum response size in bytes (default: 10MB, max: 50MB)
+        max_retries: Maximum number of retry attempts for failed requests. Defaults to 2.
 
     Returns:
         A dictionary with status, message, and artifact details if successful.
@@ -94,8 +103,15 @@ async def web_request(
 
     # Check if loopback URLs are allowed (for testing)
     allow_loopback = False
+    max_response_size = DEFAULT_MAX_RESPONSE_SIZE
+    
     if tool_config:
         allow_loopback = tool_config.get("allow_loopback", False)
+        # Get max response size from config, but enforce hard cap
+        configured_size = tool_config.get("max_response_size_bytes")
+        if configured_size is not None:
+            max_response_size = min(int(configured_size), ABSOLUTE_MAX_RESPONSE_SIZE)
+            log.debug(f"{log_identifier} Using configured max_response_size: {max_response_size} bytes")
     
     if not allow_loopback and not _is_safe_url(url):
         log.error(f"{log_identifier} URL is not safe to request: {url}")
@@ -140,19 +156,108 @@ async def web_request(
         if body:
             request_body_bytes = body.encode("utf-8")
 
-        async with httpx.AsyncClient(timeout=30.0) as client:
-            log.debug(
-                f"{log_identifier} Making {method} request to {url} with headers: {headers}"
-            )
-            response = await client.request(
-                method=method.upper(),
-                url=url,
-                headers=headers,
-                content=request_body_bytes,
-            )
-            log.debug(
-                f"{log_identifier} Received response with status code: {response.status_code}"
-            )
+        # Retry logic with exponential backoff
+        last_error = None
+        response = None
+        for attempt in range(1, max_retries + 1):
+            try:
+                async with httpx.AsyncClient(timeout=30.0, follow_redirects=True) as client:
+                    log.info(
+                        f"{log_identifier} Attempt {attempt}/{max_retries}: Making {method} request to {url}"
+                    )
+                    
+                    # Use streaming to check Content-Length and limit response size
+                    async with client.stream(
+                        method=method.upper(),
+                        url=url,
+                        headers=headers,
+                        content=request_body_bytes,
+                    ) as stream_response:
+                        # Check Content-Length header if available
+                        content_length = stream_response.headers.get("content-length")
+                        if content_length:
+                            content_length_int = int(content_length)
+                            if content_length_int > max_response_size:
+                                log.warning(
+                                    f"{log_identifier} Response Content-Length ({content_length_int} bytes) exceeds "
+                                    f"max_response_size ({max_response_size} bytes). Rejecting request."
+                                )
+                                return {
+                                    "status": "error",
+                                    "message": f"Response too large: {content_length_int} bytes exceeds limit of {max_response_size} bytes ({max_response_size // (1024*1024)} MB). "
+                                               f"Consider using a more specific URL or a different approach."
+                                }
+                        
+                        # Read response with size limit using streaming
+                        chunks = []
+                        total_size = 0
+                        async for chunk in stream_response.aiter_bytes():
+                            total_size += len(chunk)
+                            if total_size > max_response_size:
+                                log.warning(
+                                    f"{log_identifier} Response size ({total_size} bytes) exceeded "
+                                    f"max_response_size ({max_response_size} bytes) during streaming. Truncating."
+                                )
+                                # Keep what we have so far but stop reading
+                                break
+                            chunks.append(chunk)
+                        
+                        # Create a response-like object with the data we need
+                        class StreamedResponse:
+                            def __init__(self, stream_resp, content_bytes):
+                                self.status_code = stream_resp.status_code
+                                self.headers = stream_resp.headers
+                                self.content = content_bytes
+                        
+                        response = StreamedResponse(stream_response, b"".join(chunks))
+                        
+                        log.info(
+                            f"{log_identifier} Received response with status code: {response.status_code}, "
+                            f"size: {len(response.content)} bytes"
+                        )
+                    
+                    # Success - break out of retry loop
+                    break
+                    
+            except (httpx.ReadTimeout, httpx.ConnectTimeout) as timeout_error:
+                last_error = timeout_error
+                log.warning(
+                    f"{log_identifier} Attempt {attempt}/{max_retries} timed out: {timeout_error}"
+                )
+                
+                if attempt < max_retries:
+                    # Exponential backoff with jitter
+                    import random
+                    base_delay = 3.0 * (2 ** (attempt - 1))  # 3s, 6s, 12s...
+                    jitter = random.uniform(0, 1.0)
+                    delay = base_delay + jitter
+                    log.info(f"{log_identifier} Waiting {delay:.1f}s before retry {attempt + 1}/{max_retries}")
+                    await asyncio.sleep(delay)
+                else:
+                    # Final attempt failed
+                    error_message = f"Request timed out after {max_retries} attempts (30s timeout per attempt)"
+                    log.error(f"{log_identifier} {error_message}")
+                    return {
+                        "status": "error",
+                        "message": f"{error_message}. The website may be slow or blocking automated requests."
+                    }
+                    
+            except httpx.RequestError as req_error:
+                last_error = req_error
+                log.warning(
+                    f"{log_identifier} Attempt {attempt}/{max_retries} failed with request error: {req_error}"
+                )
+                
+                if attempt < max_retries:
+                    import random
+                    base_delay = 3.0 * (2 ** (attempt - 1))
+                    jitter = random.uniform(0, 1.0)
+                    delay = base_delay + jitter
+                    log.info(f"{log_identifier} Waiting {delay:.1f}s before retry {attempt + 1}/{max_retries}")
+                    await asyncio.sleep(delay)
+                else:
+                    # Will be handled by the outer exception handler
+                    raise
 
         response_content_bytes = response.content
         response_status_code = response.status_code
@@ -335,9 +440,12 @@ async def web_request(
             return {"status": "error", "message": error_message}
 
     except httpx.RequestError as re:
-        error_message = f"Request error while fetching {url}: {re}"
+        error_message = f"Request error while fetching {url} after {max_retries} attempts: {re}"
         log.error(f"{log_identifier} {error_message}", exc_info=True)
-        return {"status": "error", "message": error_message}
+        return {
+            "status": "error",
+            "message": f"{error_message}. The website may be unreachable or blocking requests."
+        }
     except ValueError as ve:
         log.error(f"{log_identifier} Value error: {ve}", exc_info=True)
         return {"status": "error", "message": str(ve)}

solace_agent_mesh/agent/utils/artifact_helpers.py

@@ -33,6 +33,7 @@ log = logging.getLogger(__name__)
 
 METADATA_SUFFIX = ".metadata.json"
 DEFAULT_SCHEMA_MAX_KEYS = 20
+DEFAULT_SCHEMA_INFERENCE_DEPTH = 4
 
 
 def is_filename_safe(filename: str) -> bool:
@@ -67,6 +68,67 @@ def is_filename_safe(filename: str) -> bool:
     return True
 
 
+def sanitize_to_filename(
+    text: str,
+    max_length: int = 50,
+    suffix: str = "",
+    replacement_char: str = "_"
+) -> str:
+    """
+    Sanitizes arbitrary text into a safe filename.
+    
+    Converts text (like a research question or title) into a filesystem-safe
+    filename by:
+    1. Converting to lowercase
+    2. Removing non-word characters (except spaces and hyphens)
+    3. Replacing spaces and hyphens with the replacement character
+    4. Limiting length to max_length
+    5. Optionally appending a suffix
+    
+    Args:
+        text: The text to convert into a filename (e.g., research question, title)
+        max_length: Maximum length of the base filename (before suffix). Default: 50
+        suffix: Optional suffix to append (e.g., "_report.md"). Default: ""
+        replacement_char: Character to replace spaces/hyphens with. Default: "_"
+    
+    Returns:
+        A sanitized filename string safe for filesystem use.
+    
+    Examples:
+        >>> sanitize_to_filename("What is AI?")
+        'what_is_ai'
+        >>> sanitize_to_filename("Research: Deep Learning!", suffix="_report.md")
+        'research_deep_learning_report.md'
+        >>> sanitize_to_filename("A very long research question about many topics", max_length=20)
+        'a_very_long_research'
+    """
+    import re
+    
+    if not text:
+        return f"unnamed{suffix}"
+    
+    # Convert to lowercase and remove non-word characters except spaces and hyphens
+    safe_name = re.sub(r'[^\w\s-]', '', text.lower())
+    
+    # Replace spaces and hyphens with the replacement character
+    safe_name = re.sub(r'[-\s]+', replacement_char, safe_name)
+    
+    # Strip leading/trailing replacement chars
+    safe_name = safe_name.strip(replacement_char)
+    
+    # Limit length
+    if max_length > 0:
+        safe_name = safe_name[:max_length]
+        # Strip trailing replacement char if we cut in the middle
+        safe_name = safe_name.rstrip(replacement_char)
+    
+    # Handle empty result
+    if not safe_name:
+        safe_name = "unnamed"
+    
+    return f"{safe_name}{suffix}"
+
+
 def ensure_correct_extension(filename_from_llm: str, desired_extension: str) -> str:
     """
     Ensures a filename has the correct extension, handling cases where the LLM
@@ -129,6 +191,34 @@ def parse_artifact_uri(uri: str) -> Dict[str, Any]:
     }
 
 
+def _clean_metadata_for_output(metadata: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Remove null, False, and empty values from metadata to reduce token usage.
+    Recursively cleans nested dictionaries.
+
+    Args:
+        metadata: The metadata dictionary to clean
+
+    Returns:
+        A cleaned dictionary with unnecessary fields removed
+    """
+    cleaned = {}
+    for key, value in metadata.items():
+        # Skip None, False, and empty collections
+        if value is None or value is False or value == {} or value == []:
+            continue
+
+        # Recursively clean nested dictionaries
+        if isinstance(value, dict):
+            cleaned_nested = _clean_metadata_for_output(value)
+            if cleaned_nested:  # Only include if not empty after cleaning
+                cleaned[key] = cleaned_nested
+        else:
+            cleaned[key] = value
+
+    return cleaned
+
+
 def _inspect_structure(
     data: Any, max_depth: int, max_keys: int, current_depth: int = 0
 ) -> Any:
@@ -234,15 +324,40 @@ async def save_artifact_with_metadata(
     metadata_dict: Dict[str, Any],
     timestamp: datetime,
     explicit_schema: Optional[Dict] = None,
-    schema_inference_depth: int = 2,
+    schema_inference_depth: Optional[int] = None,
     schema_max_keys: int = DEFAULT_SCHEMA_MAX_KEYS,
     tool_context: Optional["ToolContext"] = None,
+    suppress_visualization_signal: bool = False,
 ) -> Dict[str, Any]:
     """
     Saves a data artifact and its corresponding metadata artifact using BaseArtifactService.
     """
     log_identifier = f"[ArtifactHelper:save:{filename}]"
     log.debug("%s Saving artifact and metadata (async)...", log_identifier)
+
+    # Resolve schema_inference_depth from artifact service wrapper if not provided
+    if schema_inference_depth is None:
+        # Use duck typing to check for ScopedArtifactServiceWrapper capability
+        # (avoids dynamic class loading issues with isinstance)
+        if hasattr(artifact_service, "component") and hasattr(
+            artifact_service.component, "get_config"
+        ):
+            schema_inference_depth = artifact_service.component.get_config(
+                "schema_inference_depth", DEFAULT_SCHEMA_INFERENCE_DEPTH
+            )
+            log.debug(
+                "%s Resolved schema_inference_depth from agent config: %d",
+                log_identifier,
+                schema_inference_depth,
+            )
+        else:
+            schema_inference_depth = DEFAULT_SCHEMA_INFERENCE_DEPTH
+            log.debug(
+                "%s Using default schema_inference_depth: %d",
+                log_identifier,
+                schema_inference_depth,
+            )
+
     data_version = None
     metadata_version = None
     metadata_filename = f"{filename}{METADATA_SUFFIX}"
@@ -306,6 +421,59 @@ async def save_artifact_with_metadata(
                 data_version,
             )
 
+        # Always attempt to publish artifact saved notification for workflow visualization
+        # This works independently of artifact_delta and should succeed if we have
+        # the necessary context (host_component and a2a_context)
+        # Skip if suppress_visualization_signal is True (e.g., when called from fenced block callback)
+        if not suppress_visualization_signal:
+            try:
+                # Try to get context from tool_context if available
+                host_component = None
+                a2a_context = None
+                function_call_id = None
+
+                if tool_context:
+                    try:
+                        inv_context = tool_context._invocation_context
+                        agent = getattr(inv_context, "agent", None)
+                        host_component = getattr(agent, "host_component", None)
+                        a2a_context = tool_context.state.get("a2a_context")
+                        # Get function_call_id if this was created by a tool
+                        # Try state first (legacy), then the ADK attribute
+                        function_call_id = tool_context.state.get("function_call_id") or getattr(tool_context, "function_call_id", None)
+                    except Exception as ctx_err:
+                        log.info(
+                            "%s Could not extract context from tool_context: %s",
+                            log_identifier,
+                            ctx_err,
+                        )
+
+                # Only proceed if we have both required components
+                if host_component and a2a_context:
+                    # Create ArtifactInfo object
+                    artifact_info = ArtifactInfo(
+                        filename=filename,
+                        version=data_version,
+                        mime_type=mime_type,
+                        size=len(content_bytes),
+                        description=metadata_dict.get("description") if metadata_dict else None,
+                        version_count=None,  # Count not available in save context
+                    )
+
+                    # Publish artifact saved notification via component method
+                    await host_component.notify_artifact_saved(
+                        artifact_info=artifact_info,
+                        a2a_context=a2a_context,
+                        function_call_id=function_call_id,
+                    )
+            except Exception as signal_err:
+                # Don't fail artifact save if notification publishing fails
+                log.warning(
+                    "%s Failed to publish artifact saved notification (non-critical): %s",
+                    log_identifier,
+                    signal_err,
+                )
+
         final_metadata = {
             "filename": filename,
             "mime_type": mime_type,
@@ -636,12 +804,15 @@ async def generate_artifact_metadata_summary(
                 metadata.pop("filename", None)
                 metadata.pop("version", None)
 
+                # Clean metadata to remove null/false/empty values for token efficiency
+                cleaned_metadata = _clean_metadata_for_output(metadata)
+
                 TRUNCATION_LIMIT_BYTES = 1024
                 TRUNCATION_MESSAGE = "\n... [truncated] ..."
 
                 try:
                     formatted_metadata_str = yaml.safe_dump(
-                        metadata,
+                        cleaned_metadata,
                         default_flow_style=False,
                         sort_keys=False,
                         allow_unicode=True,
@@ -796,6 +967,51 @@ async def get_latest_artifact_version(
         return None
 
 
+async def get_artifact_counts_batch(
+    artifact_service: BaseArtifactService,
+    app_name: str,
+    user_id: str,
+    session_ids: List[str],
+) -> Dict[str, int]:
+    """
+    Get artifact counts for multiple sessions in a batch operation.
+    
+    Args:
+        artifact_service: The artifact service instance.
+        app_name: The application name.
+        user_id: The user ID.
+        session_ids: List of session IDs to get counts for.
+    
+    Returns:
+        Dict mapping session_id to artifact_count (excluding metadata files)
+    """
+    log_prefix = f"[ArtifactHelper:get_counts_batch] App={app_name}, User={user_id} -"
+    counts: Dict[str, int] = {}
+    
+    try:
+        list_keys_method = getattr(artifact_service, "list_artifact_keys")
+        
+        for session_id in session_ids:
+            try:
+                keys = await list_keys_method(
+                    app_name=app_name, user_id=user_id, session_id=session_id
+                )
+                # Count only non-metadata files
+                count = sum(1 for key in keys if not key.endswith(METADATA_SUFFIX))
+                counts[session_id] = count
+                log.debug("%s Session %s has %d artifacts", log_prefix, session_id, count)
+            except Exception as e:
+                log.warning("%s Failed to get count for session %s: %s", log_prefix, session_id, e)
+                counts[session_id] = 0
+                
+    except Exception as e:
+        log.exception("%s Error in batch count operation: %s", log_prefix, e)
+        # Return 0 for all sessions on error
+        return {session_id: 0 for session_id in session_ids}
+    
+    return counts
+
+
 async def get_artifact_info_list(
     artifact_service: BaseArtifactService,
     app_name: str,
@@ -822,7 +1038,7 @@ async def get_artifact_info_list(
         keys = await list_keys_method(
             app_name=app_name, user_id=user_id, session_id=session_id
         )
-        log.info(
+        log.debug(
             "%s Found %d artifact keys. Fetching details...", log_prefix, len(keys)
         )
 
@@ -882,6 +1098,9 @@ async def get_artifact_info_list(
                     else None
                 )
 
+                # Extract source from metadata
+                source = metadata.get("source")
+                
                 artifact_info_list.append(
                     ArtifactInfo(
                         filename=filename,
@@ -892,6 +1111,7 @@ async def get_artifact_info_list(
                         description=description,
                         version=loaded_version_num,
                         version_count=version_count,
+                        source=source,
                     )
                 )
                 log.debug(
@@ -939,6 +1159,7 @@ async def load_artifact_content_or_metadata(
     load_metadata_only: bool = False,
     return_raw_bytes: bool = False,
     max_content_length: Optional[int] = None,
+    include_line_numbers: bool = False,
     component: Optional[Any] = None,
     log_identifier_prefix: str = "[ArtifactHelper:load]",
     encoding: str = "utf-8",
@@ -1125,28 +1346,49 @@ async def load_artifact_content_or_metadata(
                 if is_text:
                     try:
                         content_str = data_bytes.decode(encoding, errors=error_handling)
+                        original_content_str = content_str  # Save for line count calculation
+
+                        # Add line numbers if requested (before truncation)
+                        if include_line_numbers:
+                            lines = content_str.split('\n')
+                            numbered_lines = [f"{i+1}\t{line}" for i, line in enumerate(lines)]
+                            content_str = '\n'.join(numbered_lines)
+                            log.debug(
+                                "%s Added line numbers to %d lines.",
+                                log_identifier,
+                                len(lines)
+                            )
+
                         message_to_llm = ""
                         if len(content_str) > max_content_length:
                             truncated_content = content_str[:max_content_length] + "..."
 
+                            # Calculate line range if line numbers are included
+                            line_range_msg = ""
+                            if include_line_numbers:
+                                visible_line_count = truncated_content.count('\n') + 1
+                                total_line_count = original_content_str.count('\n') + 1
+                                line_range_msg = f" Lines 1-{visible_line_count} of {total_line_count} total."
+
                             if (
                                 max_content_length
                                 < TEXT_ARTIFACT_CONTEXT_MAX_LENGTH_CAPACITY
                             ):
-                                message_to_llm = f"""This artifact content has been truncated to {max_content_length} characters. 
+                                message_to_llm = f"""This artifact content has been truncated to {max_content_length} characters.{line_range_msg}
                                                 The artifact is larger ({len(content_str)} characters).
                                                 Please request again with larger max size up to {TEXT_ARTIFACT_CONTEXT_MAX_LENGTH_CAPACITY} for the full artifact."""
                             else:
-                                message_to_llm = f"""This artifact content has been truncated to {max_content_length} characters. 
+                                message_to_llm = f"""This artifact content has been truncated to {max_content_length} characters.{line_range_msg}
                                                 The artifact content met the maximum allowed size of {TEXT_ARTIFACT_CONTEXT_MAX_LENGTH_CAPACITY} characters.
                                                 Please continue with this truncated content as the full artifact cannot be provided."""
                             log.info(
-                                "%s Loaded and decoded text artifact '%s' v%d. Returning truncated content (%d chars, limit: %d).",
+                                "%s Loaded and decoded text artifact '%s' v%d. Returning truncated content (%d chars, limit: %d).%s",
                                 log_identifier,
                                 filename,
                                 version_to_load,
                                 len(truncated_content),
                                 max_content_length,
+                                line_range_msg,
                             )
                         else:
                             truncated_content = content_str

solace_agent_mesh/agent/utils/context_helpers.py

@@ -58,3 +58,20 @@ def get_original_session_id(invocation_context: Any) -> str:
     else:
         raw_session_id = invocation_context.session.id
     return raw_session_id.split(":", 1)[0] if ":" in raw_session_id else raw_session_id
+
+
+def get_user_timezone(invocation_context: Any) -> str:
+    """
+    Extract the user's timezone from an invocation context.
+
+    Args:
+        invocation_context: The invocation context object from tool_context.
+                            Typically accessed via `tool_context._invocation_context`.
+
+    Returns:
+        str: The user's timezone (e.g., "America/Toronto").
+             Returns "UTC" if timezone is not available in the context.
+    """
+    if hasattr(invocation_context, "user_timezone"):
+        return invocation_context.user_timezone or "UTC"
+    return "UTC"