solace-agent-mesh 1.6.2__py3-none-any.whl → 1.7.0__py3-none-any.whl

solace_agent_mesh/agent/tools/builtin_artifact_tools.py

@@ -32,6 +32,7 @@ from ...common.utils.embeds import (
     EMBED_REGEX,
     EMBED_CHAIN_DELIMITER,
 )
+from ...common.utils.embeds.types import ResolutionMode
 from ...agent.utils.context_helpers import get_original_session_id
 from ...agent.adk.models.lite_llm import LiteLlm
 from google.adk.models import LlmRequest
@@ -43,6 +44,7 @@ log = logging.getLogger(__name__)
 CATEGORY_NAME = "Artifact Management"
 CATEGORY_DESCRIPTION = "List, read, create, update, and delete artifacts."
 
+
 async def _internal_create_artifact(
     filename: str,
     content: str,
@@ -371,7 +373,7 @@ async def load_artifact(
 
     Args:
         filename: The name of the artifact to load. May contain embeds.
-        version: The specific version number to load. Must be explicitly provided.
+        version: The specific version number to load. Must be explicitly provided. Versions are 0-indexed.
         load_metadata_only (bool): If True, load only the metadata JSON. Default False.
         max_content_length (Optional[int]): Maximum character length for text content.
                                            If None, uses app configuration. Range: 100-100,000.
@@ -451,121 +453,6 @@ async def load_artifact(
         }
 
 
-async def signal_artifact_for_return(
-    filename: str,
-    version: int,
-    tool_context: ToolContext = None,
-) -> Dict[str, Any]:
-    """
-    Signals that a specific version of an artifact should be returned to the
-    original caller as part of the final task result.
-
-    Args:
-        filename: The name of the artifact to return. May contain embeds.
-        version: The specific version number to return. Must be explicitly provided.
-    """
-    if not tool_context:
-        return {
-            "status": "error",
-            "filename": filename,
-            "version": version,
-            "message": "ToolContext is missing.",
-        }
-
-    log_identifier = (
-        f"[BuiltinArtifactTool:signal_artifact_for_return:{filename}:{version}]"
-    )
-    log.debug("%s Processing request after potential embed resolution.", log_identifier)
-
-    if version is None:
-        return {
-            "status": "error",
-            "filename": filename,
-            "version": None,
-            "message": "Version parameter is required. Use list_artifacts() to find available versions.",
-        }
-
-    try:
-        inv_context = tool_context._invocation_context
-        artifact_service = inv_context.artifact_service
-        host_component = getattr(inv_context.agent, "host_component", None)
-
-        if not artifact_service:
-            raise ValueError("ArtifactService is not available in the context.")
-        if not host_component:
-            raise ValueError("Host component is not available.")
-
-        app_name = inv_context.app_name
-        user_id = inv_context.user_id
-        session_id = get_original_session_id(inv_context)
-
-        versions = await artifact_service.list_versions(
-            app_name=app_name,
-            user_id=user_id,
-            session_id=session_id,
-            filename=filename,
-        )
-        if version not in versions:
-            raise FileNotFoundError(
-                f"Artifact '{filename}' version {version} not found."
-            )
-
-        a2a_context = tool_context.state.get("a2a_context", {})
-        logical_task_id = a2a_context.get("logical_task_id")
-        if not logical_task_id:
-            raise ValueError("Could not determine logical_task_id for signaling.")
-
-        with host_component.active_tasks_lock:
-            task_execution_context = host_component.active_tasks.get(logical_task_id)
-
-        if not task_execution_context:
-            raise ValueError(
-                f"TaskExecutionContext not found for task {logical_task_id}."
-            )
-
-        signal_data = {"filename": filename, "version": version}
-        task_execution_context.add_artifact_signal(signal_data)
-
-        log.info(
-            "%s Added artifact signal to TaskExecutionContext for task %s.",
-            log_identifier,
-            logical_task_id,
-        )
-
-        # Also add a placeholder to state_delta. This acts as a trigger
-        # for the host component to check the cache at the end of the turn.
-        # The key is unique to avoid collisions, but the content is just a placeholder.
-        trigger_key = f"temp:a2a_return_artifact:{uuid.uuid4().hex}"
-        tool_context.actions.state_delta[trigger_key] = {"triggered": True}
-        log.debug(
-            "%s Set state_delta trigger key '%s' to ensure signal processing.",
-            log_identifier,
-            trigger_key,
-        )
-
-        return {
-            "status": "success",
-            "message": f"Artifact '{filename}' (version {version}) has been signaled for return.",
-        }
-
-    except FileNotFoundError as fnf_err:
-        log.warning("%s Artifact not found: %s", log_identifier, fnf_err)
-        return {
-            "status": "error",
-            "filename": filename,
-            "version": version,
-            "message": str(fnf_err),
-        }
-    except Exception as e:
-        log.exception("%s Error signaling artifact for return: %s", log_identifier, e)
-        return {
-            "status": "error",
-            "filename": filename,
-            "version": version,
-            "message": f"Failed to signal artifact for return: {e}",
-        }
-
-
 async def apply_embed_and_create_artifact(
     output_filename: str,
     embed_directive: str,
@@ -659,6 +546,7 @@ async def apply_embed_and_create_artifact(
         format_spec=format_spec,
         context=gateway_context,
         log_identifier=log_identifier,
+        resolution_mode=ResolutionMode.TOOL_PARAMETER,
         config=embed_config,
     )
 
@@ -976,7 +864,7 @@ async def extract_content_from_artifact(
         mime_type=normalized_source_mime_type,
         content_bytes=source_artifact_content_bytes,
     )
-            
+
     if is_text_based:
         try:
             artifact_text_content = source_artifact_content_bytes.decode("utf-8")
@@ -1648,17 +1536,20 @@ async def _notify_artifact_save(
     tool_context: ToolContext = None,  # Keep tool_context for signature consistency
 ) -> Dict[str, Any]:
     """
-    An internal tool used by the system to confirm that a fenced artifact block
-    has been successfully saved. It performs no actions and simply returns its
-    arguments to get the result into the ADK history.
+    CRITICAL: _notify_artifact_save is automatically invoked by the system as a side-effect when you create artifacts. You should NEVER call this tool yourself. The system will call it for you and provide the results in your next turn. If you manually invoke it, you are making an error."
     """
-    return {"filename": filename, "version": version, "status": status}
+    return {
+        "filename": filename,
+        "version": version,
+        "status": status,
+        "message": "Artifact has been created and provided to the requester",
+    }
 
 
 _notify_artifact_save_tool_def = BuiltinTool(
     name="_notify_artifact_save",
     implementation=_notify_artifact_save,
-    description="INTERNAL TOOL. This tool is used by the system to confirm that a fenced artifact block has been saved. You MUST NOT call this tool directly.",
+    description="CRITICAL: _notify_artifact_save is automatically invoked by the system as a side-effect when you create artifacts. You should NEVER call this tool yourself. The system will call it for you and provide the results in your next turn. If you manually invoke it, you are making an error.",
     category="internal",
     required_scopes=[],  # No scopes needed for an internal notification tool
     parameters=adk_types.Schema(
@@ -1762,31 +1653,6 @@ load_artifact_tool_def = BuiltinTool(
     examples=[],
 )
 
-signal_artifact_for_return_tool_def = BuiltinTool(
-    name="signal_artifact_for_return",
-    implementation=signal_artifact_for_return,
-    description="Signals the host component to return a specific artifact version to the original caller of the task. This tool does not load the artifact content itself; it just flags it for return.",
-    category="artifact_management",
-    category_name=CATEGORY_NAME,
-    category_description=CATEGORY_DESCRIPTION,
-    required_scopes=["tool:artifact:signal_return"],
-    parameters=adk_types.Schema(
-        type=adk_types.Type.OBJECT,
-        properties={
-            "filename": adk_types.Schema(
-                type=adk_types.Type.STRING,
-                description="The name of the artifact to return. May contain embeds.",
-            ),
-            "version": adk_types.Schema(
-                type=adk_types.Type.INTEGER,
-                description="The specific version number to return. Use list_artifacts() first to find available versions.",
-            ),
-        },
-        required=["filename", "version"],
-    ),
-    examples=[],
-)
-
 apply_embed_and_create_artifact_tool_def = BuiltinTool(
     name="apply_embed_and_create_artifact",
     implementation=apply_embed_and_create_artifact,
@@ -1857,7 +1723,6 @@ tool_registry.register(_notify_artifact_save_tool_def)
 tool_registry.register(append_to_artifact_tool_def)
 tool_registry.register(list_artifacts_tool_def)
 tool_registry.register(load_artifact_tool_def)
-tool_registry.register(signal_artifact_for_return_tool_def)
 tool_registry.register(apply_embed_and_create_artifact_tool_def)
 tool_registry.register(extract_content_from_artifact_tool_def)
 

solace_agent_mesh/agent/tools/dynamic_tool.py

@@ -34,6 +34,7 @@ from ...common.utils.embeds import (
     LATE_EMBED_TYPES,
     EMBED_DELIMITER_OPEN,
 )
+from ...common.utils.embeds.types import ResolutionMode
 
 log = logging.getLogger(__name__)
 
@@ -182,6 +183,7 @@ class DynamicTool(BaseTool, ABC):
                     context=resolution_context,
                     resolver_func=evaluate_embed,
                     types_to_resolve=types_to_resolve,
+                    resolution_mode=ResolutionMode.TOOL_PARAMETER,
                     log_identifier=log_identifier,
                     config=self.tool_config,
                 )

solace_agent_mesh/agent/tools/tools_llm.txt

@@ -1,19 +1,19 @@
-# DEVELOPER GUIDE: tools
+# DEVELOPER GUIDE for tools
 
 ## Quick Summary
-The `tools` directory contains the complete tool system for the Solace Agent Mesh, providing built-in tools for artifact management, data analysis, audio/image processing, web interactions, and dynamic tool creation. It includes a registry system for tool discovery and management, with support for declarative YAML-based configurations and multiple tool types including built-in, custom Python, and MCP tools.
+The `tools` directory contains the complete tool system for the Solace Agent Mesh, providing built-in tools for artifact management, data analysis, audio processing, image generation, web scraping, and dynamic tool creation. It includes a registry system for tool discovery and management, with support for declarative YAML-based configurations and multiple tool types including built-in, custom Python, and MCP tools.
 
 ## Files Overview
-- `__init__.py` - Ensures all built-in tool modules are imported for declarative registration
-- `audio_tools.py` - Audio processing tools including TTS, transcription, and audio manipulation
-- `builtin_artifact_tools.py` - Core artifact management tools for CRUD operations and content processing
-- `builtin_data_analysis_tools.py` - Data analysis tools for creating charts from Plotly configurations
-- `dynamic_tool.py` - Base classes for creating dynamic, programmatically-defined tools
-- `general_agent_tools.py` - General-purpose tools for file conversion and diagram generation
-- `image_tools.py` - Image generation, editing, and multimodal content analysis tools
-- `peer_agent_tool.py` - Tool for delegating tasks to peer agents over Solace messaging
+- `__init__.py` - Imports all tool modules to trigger registration
+- `audio_tools.py` - Text-to-speech, transcription, and audio manipulation tools
+- `builtin_artifact_tools.py` - Core artifact management (CRUD operations, metadata handling)
+- `builtin_data_analysis_tools.py` - Data visualization and chart generation tools
+- `dynamic_tool.py` - Base classes for creating custom dynamic tools
+- `general_agent_tools.py` - General purpose tools (file conversion, diagram generation)
+- `image_tools.py` - Image generation, editing, and multimodal analysis tools
+- `peer_agent_tool.py` - Tool for delegating tasks to other agents
 - `registry.py` - Singleton registry for tool discovery and management
-- `test_tools.py` - Testing utilities for timeouts and error handling
+- `test_tools.py` - Testing and debugging utilities for timeouts and error handling
 - `tool_config_types.py` - Pydantic models for YAML-based tool configurations
 - `tool_definition.py` - Base tool definition classes and structures
 - `web_tools.py` - Web scraping and content extraction tools
@@ -21,60 +21,61 @@ The `tools` directory contains the complete tool system for the Solace Agent Mes
 ## Developer API Reference
 
 ### __init__.py
-**Purpose:** Triggers tool registration by importing all tool modules
+**Purpose:** Ensures all tool modules are imported to trigger registration
 **Import:** `from solace_agent_mesh.agent.tools import *`
 
-No public classes or functions - this is an initialization module.
-
 ### audio_tools.py
-**Purpose:** Provides comprehensive audio processing capabilities
+**Purpose:** Audio processing, text-to-speech, and transcription capabilities
 **Import:** `from solace_agent_mesh.agent.tools.audio_tools import select_voice, text_to_speech, multi_speaker_text_to_speech, concatenate_audio, transcribe_audio`
 
 **Functions:**
-- `select_voice(gender: Optional[str] = None, tone: Optional[str] = None, exclude_voices: Optional[List[str]] = None, tool_context: ToolContext = None, tool_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]` - Selects a suitable voice based on gender and tone criteria
-- `text_to_speech(text: str, output_filename: Optional[str] = None, voice_name: Optional[str] = None, gender: Optional[str] = None, tone: Optional[str] = None, language: Optional[str] = None, tool_context: ToolContext = None, tool_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]` - Converts text to speech using Gemini TTS API
-- `multi_speaker_text_to_speech(conversation_text: str, output_filename: Optional[str] = None, speaker_configs: Optional[List[Dict[str, str]]] = None, language: Optional[str] = None, tool_context: ToolContext = None, tool_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]` - Creates multi-speaker audio from conversation text
-- `concatenate_audio(clips_to_join: List[Dict[str, Any]], output_filename: Optional[str] = None, tool_context: ToolContext = None, tool_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]` - Combines multiple audio clips with custom pause durations
-- `transcribe_audio(audio_filename: str, tool_context: ToolContext = None, tool_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]` - Transcribes audio using OpenAI-compatible API
+- `select_voice(gender: Optional[str] = None, tone: Optional[str] = None, exclude_voices: Optional[List[str]] = None, tool_context: ToolContext = None, tool_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]` - Selects a suitable voice based on criteria
+- `text_to_speech(text: str, output_filename: Optional[str] = None, voice_name: Optional[str] = None, gender: Optional[str] = None, tone: Optional[str] = None, language: Optional[str] = None, tool_context: ToolContext = None, tool_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]` - Converts text to speech using Gemini TTS
+- `multi_speaker_text_to_speech(conversation_text: str, output_filename: Optional[str] = None, speaker_configs: Optional[List[Dict[str, str]]] = None, language: Optional[str] = None, tool_context: ToolContext = None, tool_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]` - Multi-speaker TTS for conversations
+- `concatenate_audio(clips_to_join: List[Dict[str, Any]], output_filename: Optional[str] = None, tool_context: ToolContext = None, tool_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]` - Combines multiple audio clips
+- `transcribe_audio(audio_filename: str, output_filename: Optional[str] = None, description: Optional[str] = None, tool_context: ToolContext = None, tool_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]` - Transcribes audio to text
 
 **Constants/Variables:**
-- `VOICE_TONE_MAPPING: Dict[str, List[str]]` - Maps tone preferences to available voices
-- `GENDER_TO_VOICE_MAPPING: Dict[str, List[str]]` - Maps gender preferences to available voices
-- `ALL_AVAILABLE_VOICES: List[str]` - Complete list of available voice names
-- `SUPPORTED_LANGUAGES: Dict[str, str]` - Maps language names to BCP-47 codes
+- `ALL_AVAILABLE_VOICES: List[str]` - List of all available TTS voices
+- `SUPPORTED_LANGUAGES: Dict[str, str]` - Mapping of language names to BCP-47 codes
+- `VOICE_TONE_MAPPING: Dict[str, List[str]]` - Maps tones to voice names
+- `GENDER_TO_VOICE_MAPPING: Dict[str, List[str]]` - Maps genders to voice names
 
 **Usage Examples:**
 ```python
-# Basic text-to-speech
+# Select a voice
+result = await select_voice(gender="female", tone="friendly")
+voice_name = result["voice_name"]
+
+# Generate speech
 result = await text_to_speech(
-    text="Hello, world!",
-    voice_name="Kore",
+    text="Hello world",
+    voice_name=voice_name,
     tool_context=context
 )
 
 # Multi-speaker conversation
-conversation = "Speaker1: Hello there!\nSpeaker2: Hi, how are you?"
+conversation = "Speaker1: Hello\nSpeaker2: Hi there"
 result = await multi_speaker_text_to_speech(
     conversation_text=conversation,
     speaker_configs=[
         {"name": "Speaker1", "gender": "female", "tone": "friendly"},
-        {"name": "Speaker2", "gender": "male", "tone": "casual"}
+        {"name": "Speaker2", "gender": "male", "tone": "professional"}
     ],
     tool_context=context
 )
 ```
 
 ### builtin_artifact_tools.py
-**Purpose:** Core artifact management and content processing tools
-**Import:** `from solace_agent_mesh.agent.tools.builtin_artifact_tools import list_artifacts, load_artifact, signal_artifact_for_return, apply_embed_and_create_artifact, extract_content_from_artifact, append_to_artifact, delete_artifact`
+**Purpose:** Core artifact management operations (CRUD, metadata, embeds)
+**Import:** `from solace_agent_mesh.agent.tools.builtin_artifact_tools import list_artifacts, load_artifact, append_to_artifact, apply_embed_and_create_artifact, extract_content_from_artifact, delete_artifact`
 
 **Functions:**
-- `list_artifacts(tool_context: ToolContext = None) -> Dict[str, Any]` - Lists all available artifacts with metadata summaries
+- `list_artifacts(tool_context: ToolContext = None) -> Dict[str, Any]` - Lists all artifacts with metadata summaries
 - `load_artifact(filename: str, version: int, load_metadata_only: bool = False, max_content_length: Optional[int] = None, tool_context: ToolContext = None) -> Dict[str, Any]` - Loads artifact content or metadata
-- `signal_artifact_for_return(filename: str, version: int, tool_context: ToolContext = None) -> Dict[str, Any]` - Signals artifact to be returned to caller
-- `apply_embed_and_create_artifact(output_filename: str, embed_directive: str, output_metadata: Optional[Dict[str, Any]] = None, tool_context: ToolContext = None) -> Dict[str, Any]` - Resolves embed directives and creates new artifacts
+- `append_to_artifact(filename: str, content_chunk: str, mime_type: str, tool_context: ToolContext = None) -> Dict[str, Any]` - Appends content to existing artifact
+- `apply_embed_and_create_artifact(output_filename: str, embed_directive: str, output_metadata: Optional[Dict[str, Any]] = None, tool_context: ToolContext = None) -> Dict[str, Any]` - Resolves embed directives and creates artifacts
 - `extract_content_from_artifact(filename: str, extraction_goal: str, version: Optional[str] = "latest", output_filename_base: Optional[str] = None, tool_context: ToolContext = None) -> Dict[str, Any]` - Uses LLM to extract/transform artifact content
-- `append_to_artifact(filename: str, content_chunk: str, mime_type: str, tool_context: ToolContext = None) -> Dict[str, Any]` - Appends content to existing artifacts
 - `delete_artifact(filename: str, version: Optional[int] = None, tool_context: ToolContext = None) -> Dict[str, Any]` - Deletes artifact versions
 
 **Usage Examples:**
@@ -82,9 +83,9 @@ result = await multi_speaker_text_to_speech(
 # List all artifacts
 artifacts = await list_artifacts(tool_context=context)
 
-# Load specific artifact version
+# Load specific artifact
 content = await load_artifact(
-    filename="data.csv",
+    filename="data.json",
     version=1,
     tool_context=context
 )
@@ -98,16 +99,16 @@ result = await extract_content_from_artifact(
 ```
 
 ### builtin_data_analysis_tools.py
-**Purpose:** Data analysis and visualization tools
+**Purpose:** Data visualization and chart generation
 **Import:** `from solace_agent_mesh.agent.tools.builtin_data_analysis_tools import create_chart_from_plotly_config`
 
 **Functions:**
-- `create_chart_from_plotly_config(config_content: str, config_format: Literal["json", "yaml"], output_filename: str, output_format: Optional[str] = "png", tool_context: ToolContext = None) -> Dict[str, Any]` - Generates static chart images from Plotly configurations
+- `create_chart_from_plotly_config(config_content: str, config_format: Literal["json", "yaml"], output_filename: str, output_format: Optional[str] = "png", tool_context: ToolContext = None) -> Dict[str, Any]` - Creates charts from Plotly configurations
 
 **Usage Examples:**
 ```python
 # Create chart from JSON config
-plotly_config = '{"data": [{"x": [1,2,3], "y": [4,5,6], "type": "scatter"}]}'
+plotly_config = '{"data": [{"x": [1,2,3], "y": [4,5,6], "type": "scatter"}], "layout": {"title": "Sample Chart"}}'
 result = await create_chart_from_plotly_config(
     config_content=plotly_config,
     config_format="json",
@@ -117,23 +118,21 @@ result = await create_chart_from_plotly_config(
 ```
 
 ### dynamic_tool.py
-**Purpose:** Base classes for creating dynamic, programmatically-defined tools
+**Purpose:** Base classes for creating custom dynamic tools
 **Import:** `from solace_agent_mesh.agent.tools.dynamic_tool import DynamicTool, DynamicToolProvider`
 
 **Classes:**
-- `DynamicTool(tool_config: Optional[Union[dict, BaseModel]] = None)` - Base class for dynamic tools with programmatic definitions
-  - `tool_name: str` - Property returning the function name for LLM calls
+- `DynamicTool(tool_config: Optional[Union[dict, BaseModel]] = None)` - Base class for programmatic tools
+  - `tool_name: str` - Property returning the function name
   - `tool_description: str` - Property returning tool description
   - `parameters_schema: adk_types.Schema` - Property returning parameter schema
-  - `raw_string_args: List[str]` - Property listing args that skip embed resolution
-  - `resolution_type: Literal["early", "all"]` - Property determining embed resolution scope
-  - `run_async(*, args: Dict[str, Any], tool_context: ToolContext) -> Dict[str, Any]` - Executes the tool with embed resolution
-  - `_run_async_impl(args: dict, tool_context: ToolContext, credential: Optional[str] = None) -> dict` - Abstract method for tool implementation
+  - `raw_string_args: List[str]` - Property listing args to skip embed resolution
+  - `resolution_type: Literal["early", "all"]` - Property controlling embed resolution
+  - `_run_async_impl(args: dict, tool_context: ToolContext, credential: Optional[str] = None) -> dict` - Abstract method to implement tool logic
 
-- `DynamicToolProvider()` - Base class for tool providers that generate multiple tools
-  - `register_tool(func: Callable) -> Callable` - Class method decorator for registering functions as tools
-  - `create_tools(tool_config: Optional[Union[dict, BaseModel]] = None) -> List[DynamicTool]` - Abstract method for creating custom tools
-  - `get_all_tools_for_framework(tool_config: Optional[Union[dict, BaseModel]] = None) -> List[DynamicTool]` - Framework method combining decorated and custom tools
+- `DynamicToolProvider()` - Base class for tool providers
+  - `register_tool(func: Callable) -> Callable` - Class method decorator for registering tools
+  - `create_tools(tool_config: Optional[Union[dict, BaseModel]] = None) -> List[DynamicTool]` - Abstract method to create custom tools
 
 **Usage Examples:**
 ```python
@@ -160,24 +159,24 @@ class MyCustomTool(DynamicTool):
     async def _run_async_impl(self, args: dict, tool_context: ToolContext, credential: Optional[str] = None) -> dict:
         return {"result": f"Processed: {args['input']}"}
 
-# Create a tool provider with decorated methods
+# Create a tool provider
 class MyToolProvider(DynamicToolProvider):
     @DynamicToolProvider.register_tool
-    async def my_decorated_tool(self, param1: str, tool_context: ToolContext) -> dict:
-        """This tool does something useful."""
-        return {"status": "success", "input": param1}
+    async def my_decorated_tool(self, message: str, tool_context: ToolContext = None) -> dict:
+        """A tool created via decorator."""
+        return {"response": f"Hello {message}"}
     
     def create_tools(self, tool_config: Optional[Union[dict, BaseModel]] = None) -> List[DynamicTool]:
         return [MyCustomTool(tool_config)]
 ```
 
 ### general_agent_tools.py
-**Purpose:** General-purpose utility tools for file conversion and diagram generation
+**Purpose:** General purpose utility tools
 **Import:** `from solace_agent_mesh.agent.tools.general_agent_tools import convert_file_to_markdown, mermaid_diagram_generator`
 
 **Functions:**
-- `convert_file_to_markdown(input_filename: str, tool_context: ToolContext = None, tool_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]` - Converts files to Markdown using MarkItDown library
-- `mermaid_diagram_generator(mermaid_syntax: str, output_filename: Optional[str] = None, tool_context: ToolContext = None, tool_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]` - Generates PNG images from Mermaid diagram syntax
+- `convert_file_to_markdown(input_filename: str, tool_context: ToolContext = None, tool_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]` - Converts files to Markdown using MarkItDown
+- `mermaid_diagram_generator(mermaid_syntax: str, output_filename: Optional[str] = None, tool_context: ToolContext = None, tool_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]` - Generates PNG diagrams from Mermaid syntax
 
 **Usage Examples:**
 ```python
@@ -201,32 +200,32 @@ result = await mermaid_diagram_generator(
 ```
 
 ### image_tools.py
-**Purpose:** Image generation, editing, and multimodal content analysis
+**Purpose:** Image generation, editing, and multimodal analysis
 **Import:** `from solace_agent_mesh.agent.tools.image_tools import create_image_from_description, describe_image, describe_audio, edit_image_with_gemini`
 
 **Functions:**
 - `create_image_from_description(image_description: str, output_filename: Optional[str] = None, tool_context: ToolContext = None, tool_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]` - Generates images from text descriptions
-- `describe_image(image_filename: str, prompt: str = "What is in this image?", tool_context: ToolContext = None, tool_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]` - Describes images using vision APIs
-- `describe_audio(audio_filename: str, prompt: str = "What is in this recording?", tool_context: ToolContext = None, tool_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]` - Describes audio using multimodal APIs
-- `edit_image_with_gemini(image_filename: str, edit_prompt: str, output_filename: Optional[str] = None, tool_context: ToolContext = None, tool_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]` - Edits images using Gemini 2.0 Flash
+- `describe_image(image_filename: str, prompt: str = "What is in this image?", tool_context: ToolContext = None, tool_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]` - Describes images using vision API
+- `describe_audio(audio_filename: str, prompt: str = "What is in this recording?", tool_context: ToolContext = None, tool_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]` - Describes audio using multimodal API
+- `edit_image_with_gemini(image_filename: str, edit_prompt: str, output_filename: Optional[str] = None, tool_context: ToolContext = None, tool_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]` - Edits images using Gemini
 
 **Usage Examples:**
 ```python
-# Generate image from description
+# Generate image
 result = await create_image_from_description(
-    image_description="A sunset over mountains with a lake in the foreground",
+    image_description="A sunset over mountains",
     output_filename="sunset.png",
     tool_context=context
 )
 
-# Describe an existing image
+# Describe image
 result = await describe_image(
     image_filename="photo.jpg",
-    prompt="What objects are visible in this image?",
+    prompt="What objects are in this image?",
     tool_context=context
 )
 
-# Edit an image
+# Edit image
 result = await edit_image_with_gemini(
     image_filename="original.jpg",
     edit_prompt="Add a rainbow in the sky",
@@ -235,29 +234,43 @@ result = await edit_image_with_gemini(
 ```
 
 ### peer_agent_tool.py
-**Purpose:** Enables task delegation to peer agents over Solace messaging
+**Purpose:** Tool for delegating tasks to other agents in the mesh
 **Import:** `from solace_agent_mesh.agent.tools.peer_agent_tool import PeerAgentTool`
 
 **Classes:**
-- `PeerAgentTool(target_agent_name: str, host_component)` - Tool for delegating tasks to peer agents
-  - `target_agent_name: str` - Name of the peer agent
-  - `host_component` - Reference to the SamAgentComponent
-  - `is_long_running: bool` - Always True for async delegation
+- `PeerAgentTool(target_agent_name: str, host_component)` - Tool for peer agent communication
+  - `target_agent_name: str` - Name of the target agent
+  - `host_component` - Reference to the host component
   - `run_async(*, args: Dict[str, Any], tool_context: ToolContext) -> Any` - Delegates task to peer agent
 
 **Usage Examples:**
 ```python
-# Create peer agent tool (typically done by framework)
+# Create peer tool (typically done automatically)
 peer_tool = PeerAgentTool("data_analyst_agent", host_component)
 
-# Tool is called by LLM with these parameters:
-# {
-#     "task_description": "Analyze the sales data and create a summary report",
-#     "user_query": "What were our top performing products last quarter?",
-#     "artifacts": [{"filename": "sales_data.csv", "version": "latest"}]
-# }
+# Use via ADK (the tool is registered automatically)
+# The LLM would call: peer_data_analyst_agent(task_description="Analyze sales data", artifacts=[{"filename": "sales.csv"}])
 ```
 
 ### registry.py
+**Purpose:** Singleton registry for tool discovery and management
+**Import:** `from solace_agent_mesh.agent.tools.registry import tool_registry`
+
+**Classes:**
+- `_ToolRegistry()` - Singleton registry for tools
+  - `register(tool: BuiltinTool)` - Registers a tool
+  - `get_tool_by_name(name: str) -> Optional[BuiltinTool]` - Gets tool by name
+  - `get_tools_by_category(category_name: str) -> List[BuiltinTool]` - Gets tools by category
+  - `get_all_tools() -> List[BuiltinTool]` - Gets all registered tools
+  - `clear()` - Clears registry (testing only)
+
+**Constants/Variables:**
+- `tool_registry: _ToolRegistry` - Global singleton instance
+
+**Usage Examples:**
+```python
+from solace_agent_mesh.agent.tools.registry import tool_registry
+
+# Register a tool
 
-# content_hash: 20fa34bab0871d388e46728669b40fe53f763aeff295c72c42aba81729cabab4
+# content_hash: b3f2b9ed392ce5771853db0564d776f20e30b7e0706d9126611eca5697e6a05e

solace_agent_mesh/agent/tools/tools_llm_detail.txt

@@ -76,17 +76,18 @@ result = await multi_speaker_text_to_speech(
 
 ### builtin_artifact_tools.py
 **Purpose:** Core artifact management and content processing tools
-**Import:** `from solace_agent_mesh.agent.tools.builtin_artifact_tools import list_artifacts, load_artifact, signal_artifact_for_return, apply_embed_and_create_artifact, extract_content_from_artifact, append_to_artifact, delete_artifact`
+**Import:** `from solace_agent_mesh.agent.tools.builtin_artifact_tools import list_artifacts, load_artifact, apply_embed_and_create_artifact, extract_content_from_artifact, append_to_artifact, delete_artifact`
 
 **Functions:**
 - `list_artifacts(tool_context: ToolContext = None) -> Dict[str, Any]` - Lists all available artifacts with metadata summaries
 - `load_artifact(filename: str, version: int, load_metadata_only: bool = False, max_content_length: Optional[int] = None, tool_context: ToolContext = None) -> Dict[str, Any]` - Loads artifact content or metadata
-- `signal_artifact_for_return(filename: str, version: int, tool_context: ToolContext = None) -> Dict[str, Any]` - Signals artifact to be returned to caller
 - `apply_embed_and_create_artifact(output_filename: str, embed_directive: str, output_metadata: Optional[Dict[str, Any]] = None, tool_context: ToolContext = None) -> Dict[str, Any]` - Resolves embed directives and creates new artifacts
 - `extract_content_from_artifact(filename: str, extraction_goal: str, version: Optional[str] = "latest", output_filename_base: Optional[str] = None, tool_context: ToolContext = None) -> Dict[str, Any]` - Uses LLM to extract/transform artifact content
 - `append_to_artifact(filename: str, content_chunk: str, mime_type: str, tool_context: ToolContext = None) -> Dict[str, Any]` - Appends content to existing artifacts
 - `delete_artifact(filename: str, version: Optional[int] = None, tool_context: ToolContext = None) -> Dict[str, Any]` - Deletes artifact versions
 
+**Note:** To return artifacts to users, use the `«artifact_return:filename[:version]»` embed in your response text instead of a tool call. This is more efficient and provides a better user experience.
+
 **Usage Examples:**
 ```python
 # List all artifacts

solace_agent_mesh/agent/utils/artifact_helpers.py

@@ -882,6 +882,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 +895,7 @@ async def get_artifact_info_list(
                         description=description,
                         version=loaded_version_num,
                         version_count=version_count,
+                        source=source,
                     )
                 )
                 log.debug(

solace_agent_mesh/agent/utils/utils_llm.txt

@@ -25,6 +25,7 @@ The `utils` directory provides a collection of helper modules designed to suppor
 - `format_metadata_for_llm(metadata: Dict[str, Any]) -> str` - Formats metadata into LLM-friendly text
 - `decode_and_get_bytes(content_str: str, mime_type: str, log_identifier: str) -> Tuple[bytes, str]` - Decodes content based on MIME type (base64 for binary, UTF-8 for text)
 - `generate_artifact_metadata_summary(component: "SamAgentComponent", artifact_identifiers: List[Dict[str, Any]], user_id: str, session_id: str, app_name: str, header_text: Optional[str] = None) -> str` - Generates YAML summary of multiple artifacts' metadata
+- `process_artifact_upload(artifact_service: BaseArtifactService, component: Any, user_id: str, session_id: str, filename: str, content_bytes: bytes, mime_type: str, metadata_json: Optional[str] = None, log_prefix: str = "[ArtifactUpload]") -> Dict[str, Any]` - Common logic for processing artifact uploads with validation and storage
 
 **Constants/Variables:**
 - `METADATA_SUFFIX: str` - Suffix for metadata files (".metadata.json")
@@ -40,7 +41,8 @@ from solace_agent_mesh.agent.utils.artifact_helpers import (
     get_artifact_info_list,
     ensure_correct_extension,
     format_artifact_uri,
-    parse_artifact_uri
+    parse_artifact_uri,
+    process_artifact_upload
 )
 
 async def artifact_example():
@@ -61,6 +63,18 @@ async def artifact_example():
         timestamp=datetime.now(timezone.utc)
     )
     
+    # Process artifact upload (higher-level function)
+    upload_result = await process_artifact_upload(
+        artifact_service=service,
+        component=component,
+        user_id="user123",
+        session_id="session456",
+        filename="data.csv",
+        content_bytes=csv_data,
+        mime_type="text/csv",
+        metadata_json='{"description": "Uploaded data"}'
+    )
+    
     # Load artifact content
     loaded = await load_artifact_content_or_metadata(
         artifact_service=service,
@@ -135,4 +149,4 @@ def my_tool(callback_context):
     # "session123:tool456" -> "session123"
 ```
 
-# content_hash: a47bd4722e780a6a8146c6913cb0cbb053515a6f17dac92171ba79aef00d61b0
+# content_hash: b9691e1ea5f36ef138caa844b72f38b76652ea8cf79d1814e7a5f7362b922ffa