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

solace_agent_mesh/agent/tools/tool_config_types.py

@@ -0,0 +1,93 @@
+"""
+Pydantic models for agent tool configurations defined in YAML.
+"""
+from typing import Any, Dict, List, Literal, Optional, Union
+from pydantic import Field, model_validator
+from ...common.utils.pydantic_utils import SamConfigBase
+
+
+class BaseToolConfig(SamConfigBase):
+    """Base model for common tool configuration fields."""
+
+    required_scopes: List[str] = Field(default_factory=list)
+    tool_config: Dict[str, Any] = Field(default_factory=dict)
+
+
+class BuiltinToolConfig(BaseToolConfig):
+    """Configuration for a single built-in tool."""
+    tool_type: Literal["builtin"]
+    tool_name: str
+
+class BuiltinGroupToolConfig(BaseToolConfig):
+    """Configuration for a group of built-in tools by category."""
+    tool_type: Literal["builtin-group"]
+    group_name: str
+
+class PythonToolConfig(BaseToolConfig):
+    """Configuration for a custom Python tool (function or DynamicTool)."""
+    tool_type: Literal["python"]
+    component_module: str
+    component_base_path: Optional[str] = None
+    function_name: Optional[str] = None
+    tool_name: Optional[str] = None
+    tool_description: Optional[str] = None
+    class_name: Optional[str] = None
+    init_function: Optional[str] = Field(
+        default=None,
+        description="Name of the lifecycle init function in the same component_module.",
+    )
+    cleanup_function: Optional[str] = Field(
+        default=None,
+        description="Name of the lifecycle cleanup function in the same component_module.",
+    )
+    raw_string_args: List[str] = Field(default_factory=list)
+
+
+class McpToolConfig(BaseToolConfig):
+    """Configuration for an MCP tool or toolset."""
+    tool_type: Literal["mcp"]
+    connection_params: Dict[str, Any]
+    tool_name: Optional[str] = None # Optional filter
+    environment_variables: Optional[Dict[str, Any]] = None
+    auth: dict[str, Any] | None = None
+    manifest: list[dict[str, Any]] | None = None
+
+
+class OpenApiToolConfig(BaseToolConfig):
+    """Configuration for OpenAPI-based tools."""
+    tool_type: Literal["openapi"]
+
+    # Specification input (mutually exclusive - only one should be provided)
+    specification_file: Optional[str] = None  # Path to OpenAPI spec file
+    specification: Optional[str] = None       # Inline OpenAPI spec (JSON/YAML)
+    specification_url: Optional[str] = None   # URL to fetch OpenAPI spec from
+    specification_format: Optional[Literal["json", "yaml"]] = None  # Optional format hint
+
+    # Server URL override
+    base_url: Optional[str] = None  # Base URL to override/complete the server URL in the spec
+
+    # Tool filtering (mutually exclusive - only one should be provided)
+    allow_list: Optional[List[str]] = None  # Include only these specific operations/endpoints
+    deny_list: Optional[List[str]] = None   # Exclude these specific operations/endpoints
+
+    # Authentication
+    auth: Optional[Dict[str, Any]] = None
+
+    @model_validator(mode='after')
+    def validate_tool_filtering(self):
+        """Ensure allow_list and deny_list are mutually exclusive."""
+        if self.allow_list is not None and self.deny_list is not None:
+            raise ValueError(
+                "OpenAPI tool configuration error: Cannot specify both 'allow_list' and 'deny_list'. "
+                "Please use only one."
+            )
+        return self
+
+
+AnyToolConfig = Union[
+    BuiltinToolConfig,
+    BuiltinGroupToolConfig,
+    PythonToolConfig,
+    McpToolConfig,
+    OpenApiToolConfig,
+]

solace_agent_mesh/agent/tools/tool_definition.py

@@ -0,0 +1,53 @@
+"""
+Defines the Pydantic model for a self-contained BuiltinTool definition.
+"""
+
+from typing import Callable, List, Dict, Any, Optional
+from pydantic import BaseModel, Field
+from google.genai import types as adk_types
+
+
+class BuiltinTool(BaseModel):
+    """A self-contained, declarative definition for a built-in agent tool."""
+
+    name: str = Field(..., description="The function name the LLM will call.")
+    implementation: Callable = Field(
+        ..., description="The async Python function that implements the tool."
+    )
+    description: str = Field(
+        ...,
+        description="High-level description for the LLM to understand the tool's purpose.",
+    )
+    parameters: adk_types.Schema = Field(
+        ..., description="The OpenAPI-like schema for the tool's parameters."
+    )
+    examples: List[Dict[str, Any]] = Field(
+        default_factory=list, description="Few-shot examples for the LLM."
+    )
+    required_scopes: List[str] = Field(
+        default_factory=list,
+        description="A list of scopes required to execute this tool.",
+    )
+    category: str = Field(
+        default="General",
+        description="A category for grouping tools, e.g., 'Artifact', 'Data Analysis'. Used for configuration toggles.",
+    )
+    category_name: Optional[str] = Field(
+        default=None,
+        description="A human-readable name for the tool's category.",
+    )
+    category_description: Optional[str] = Field(
+        default=None,
+        description="A description for the tool's category. Will be the same for all tools in a category.",
+    )
+    initializer: Optional[Callable[[Any, Dict[str, Any]], None]] = Field(
+        default=None,
+        description="An optional function to initialize the tool or its dependencies.",
+    )
+    raw_string_args: List[str] = Field(
+        default_factory=list,
+        description="A list of argument names that should be passed as raw strings without embed pre-resolution.",
+    )
+
+    class Config:
+        arbitrary_types_allowed = True

solace_agent_mesh/agent/tools/tools_llm.txt

@@ -0,0 +1,276 @@
+# 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 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` - 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 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
+
+## Developer API Reference
+
+### __init__.py
+**Purpose:** Ensures all tool modules are imported to trigger registration
+**Import:** `from solace_agent_mesh.agent.tools import *`
+
+### audio_tools.py
+**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 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:**
+- `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
+# 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=voice_name,
+    tool_context=context
+)
+
+# Multi-speaker conversation
+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": "professional"}
+    ],
+    tool_context=context
+)
+```
+
+### builtin_artifact_tools.py
+**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 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
+- `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
+- `delete_artifact(filename: str, version: Optional[int] = None, tool_context: ToolContext = None) -> Dict[str, Any]` - Deletes artifact versions
+
+**Usage Examples:**
+```python
+# List all artifacts
+artifacts = await list_artifacts(tool_context=context)
+
+# Load specific artifact
+content = await load_artifact(
+    filename="data.json",
+    version=1,
+    tool_context=context
+)
+
+# Extract content using LLM
+result = await extract_content_from_artifact(
+    filename="report.pdf",
+    extraction_goal="Extract all financial figures and create a summary table",
+    tool_context=context
+)
+```
+
+### builtin_data_analysis_tools.py
+**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]` - 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"}], "layout": {"title": "Sample Chart"}}'
+result = await create_chart_from_plotly_config(
+    config_content=plotly_config,
+    config_format="json",
+    output_filename="my_chart.png",
+    tool_context=context
+)
+```
+
+### dynamic_tool.py
+**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 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 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
+  - `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
+# Create a custom dynamic tool
+class MyCustomTool(DynamicTool):
+    @property
+    def tool_name(self) -> str:
+        return "my_custom_tool"
+    
+    @property
+    def tool_description(self) -> str:
+        return "Does something custom"
+    
+    @property
+    def parameters_schema(self) -> adk_types.Schema:
+        return adk_types.Schema(
+            type=adk_types.Type.OBJECT,
+            properties={
+                "input": adk_types.Schema(type=adk_types.Type.STRING)
+            },
+            required=["input"]
+        )
+    
+    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
+class MyToolProvider(DynamicToolProvider):
+    @DynamicToolProvider.register_tool
+    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
+**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
+- `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
+# Convert PDF to Markdown
+result = await convert_file_to_markdown(
+    input_filename="document.pdf",
+    tool_context=context
+)
+
+# Generate Mermaid diagram
+mermaid_code = """
+graph TD
+    A[Start] --> B[Process]
+    B --> C[End]
+"""
+result = await mermaid_diagram_generator(
+    mermaid_syntax=mermaid_code,
+    output_filename="flowchart.png",
+    tool_context=context
+)
+```
+
+### image_tools.py
+**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 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
+result = await create_image_from_description(
+    image_description="A sunset over mountains",
+    output_filename="sunset.png",
+    tool_context=context
+)
+
+# Describe image
+result = await describe_image(
+    image_filename="photo.jpg",
+    prompt="What objects are in this image?",
+    tool_context=context
+)
+
+# Edit image
+result = await edit_image_with_gemini(
+    image_filename="original.jpg",
+    edit_prompt="Add a rainbow in the sky",
+    tool_context=context
+)
+```
+
+### peer_agent_tool.py
+**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 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 tool (typically done automatically)
+peer_tool = PeerAgentTool("data_analyst_agent", host_component)
+
+# 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: b3f2b9ed392ce5771853db0564d776f20e30b7e0706d9126611eca5697e6a05e