Tools API

This section provides detailed API documentation for the tool framework in Scoras.

Tool Classes

Tool

class Tool:
    def __init__(
        self,
        name: str,
        description: str,
        function: Callable,
        parameters: Dict[str, Any],
        complexity: str = "standard",
        metadata: Optional[Dict[str, Any]] = None
    ):
        """
        Initialize a Tool.

        Args:
            name: Name of the tool
            description: Description of what the tool does
            function: Function to execute when the tool is called
            parameters: Parameter schema for the tool
            complexity: Complexity level ("simple", "standard", "complex")
            metadata: Optional metadata for the tool
        """

    async def execute(self, **kwargs) -> Any:
        """
        Execute the tool asynchronously.

        Args:
            **kwargs: Arguments to pass to the tool function

        Returns:
            Result of the tool execution
        """

    def execute_sync(self, **kwargs) -> Any:
        """
        Execute the tool synchronously.

        Args:
            **kwargs: Arguments to pass to the tool function

        Returns:
            Result of the tool execution
        """

    def get_complexity_score(self) -> float:
        """
        Get the complexity score for the tool.

        Returns:
            Complexity score as a float
        """

ToolChain

class ToolChain:
    def __init__(
        self,
        tools: List[Tool],
        name: str,
        description: str,
        enable_scoring: bool = True
    ):
        """
        Initialize a ToolChain that combines multiple tools.

        Args:
            tools: List of tools in the chain
            name: Name of the tool chain
            description: Description of what the tool chain does
            enable_scoring: Whether to track complexity scoring
        """

    def add_tool(self, tool: Tool) -> None:
        """
        Add a tool to the chain.

        Args:
            tool: Tool to add
        """

    async def execute(self, tool_name: str, **kwargs) -> Any:
        """
        Execute a specific tool in the chain asynchronously.

        Args:
            tool_name: Name of the tool to execute
            **kwargs: Arguments to pass to the tool

        Returns:
            Result of the tool execution
        """

    def execute_sync(self, tool_name: str, **kwargs) -> Any:
        """
        Execute a specific tool in the chain synchronously.

        Args:
            tool_name: Name of the tool to execute
            **kwargs: Arguments to pass to the tool

        Returns:
            Result of the tool execution
        """

    def get_complexity_score(self) -> Dict[str, Any]:
        """
        Get the complexity score for the tool chain.

        Returns:
            Dictionary containing complexity score information
        """

ToolRouter

class ToolRouter:
    def __init__(
        self,
        tools: Dict[str, Tool],
        routing_strategy: str = "auto",
        enable_scoring: bool = True
    ):
        """
        Initialize a ToolRouter that routes requests to appropriate tools.

        Args:
            tools: Dictionary mapping tool names to Tool instances
            routing_strategy: Strategy for routing ("auto", "manual", "priority")
            enable_scoring: Whether to track complexity scoring
        """

    def add_tool(self, tool: Tool) -> None:
        """
        Add a tool to the router.

        Args:
            tool: Tool to add
        """

    async def route_and_execute(self, query: str, **kwargs) -> Any:
        """
        Route a query to the appropriate tool and execute it asynchronously.

        Args:
            query: Query to route
            **kwargs: Additional arguments to pass to the tool

        Returns:
            Result of the tool execution
        """

    def route_and_execute_sync(self, query: str, **kwargs) -> Any:
        """
        Route a query to the appropriate tool and execute it synchronously.

        Args:
            query: Query to route
            **kwargs: Additional arguments to pass to the tool

        Returns:
            Result of the tool execution
        """

    def get_complexity_score(self) -> Dict[str, Any]:
        """
        Get the complexity score for the tool router.

        Returns:
            Dictionary containing complexity score information
        """

HTTP Tools

HTTPTool

class HTTPTool(Tool):
    def __init__(
        self,
        name: str,
        description: str,
        url: str,
        method: str = "GET",
        headers: Optional[Dict[str, str]] = None,
        auth: Optional[Dict[str, str]] = None,
        complexity: str = "standard",
        metadata: Optional[Dict[str, Any]] = None
    ):
        """
        Initialize an HTTP Tool for making API requests.

        Args:
            name: Name of the tool
            description: Description of what the tool does
            url: URL to make requests to
            method: HTTP method ("GET", "POST", "PUT", "DELETE", etc.)
            headers: Optional HTTP headers
            auth: Optional authentication credentials
            complexity: Complexity level ("simple", "standard", "complex")
            metadata: Optional metadata for the tool
        """

APITool

class APITool(HTTPTool):
    def __init__(
        self,
        name: str,
        description: str,
        api_url: str,
        api_key: str,
        method: str = "GET",
        headers: Optional[Dict[str, str]] = None,
        complexity: str = "standard",
        metadata: Optional[Dict[str, Any]] = None
    ):
        """
        Initialize an API Tool for making authenticated API requests.

        Args:
            name: Name of the tool
            description: Description of what the tool does
            api_url: URL of the API
            api_key: API key for authentication
            method: HTTP method ("GET", "POST", "PUT", "DELETE", etc.)
            headers: Optional additional HTTP headers
            complexity: Complexity level ("simple", "standard", "complex")
            metadata: Optional metadata for the tool
        """

Tool Factories

create_tool

def create_tool(
    name: str,
    description: str,
    function: Callable,
    complexity: str = "standard",
    **kwargs
) -> Tool:
    """
    Factory function to create a tool.

    Args:
        name: Name of the tool
        description: Description of what the tool does
        function: Function to execute when the tool is called
        complexity: Complexity level ("simple", "standard", "complex")
        **kwargs: Additional arguments for the tool

    Returns:
        Instantiated Tool
    """

create_http_tool

def create_http_tool(
    name: str,
    description: str,
    url: str,
    method: str = "GET",
    complexity: str = "standard",
    **kwargs
) -> HTTPTool:
    """
    Factory function to create an HTTP tool.

    Args:
        name: Name of the tool
        description: Description of what the tool does
        url: URL to make requests to
        method: HTTP method ("GET", "POST", "PUT", "DELETE", etc.)
        complexity: Complexity level ("simple", "standard", "complex")
        **kwargs: Additional arguments for the HTTP tool

    Returns:
        Instantiated HTTPTool
    """

create_api_tool

def create_api_tool(
    name: str,
    description: str,
    api_url: str,
    api_key: str,
    method: str = "GET",
    complexity: str = "standard",
    **kwargs
) -> APITool:
    """
    Factory function to create an API tool.

    Args:
        name: Name of the tool
        description: Description of what the tool does
        api_url: URL of the API
        api_key: API key for authentication
        method: HTTP method ("GET", "POST", "PUT", "DELETE", etc.)
        complexity: Complexity level ("simple", "standard", "complex")
        **kwargs: Additional arguments for the API tool

    Returns:
        Instantiated APITool
    """

Tool Builder

class ToolBuilder:
    def __init__(self):
        """Initialize a ToolBuilder for creating tools programmatically."""

    def set_name(self, name: str) -> "ToolBuilder":
        """
        Set the name of the tool.

        Args:
            name: Name of the tool

        Returns:
            Self for method chaining
        """

    def set_description(self, description: str) -> "ToolBuilder":
        """
        Set the description of the tool.

        Args:
            description: Description of what the tool does

        Returns:
            Self for method chaining
        """

    def set_function(self, function: Callable) -> "ToolBuilder":
        """
        Set the function of the tool.

        Args:
            function: Function to execute when the tool is called

        Returns:
            Self for method chaining
        """

    def set_complexity(self, complexity: str) -> "ToolBuilder":
        """
        Set the complexity level of the tool.

        Args:
            complexity: Complexity level ("simple", "standard", "complex")

        Returns:
            Self for method chaining
        """

    def add_parameter(self, name: str, type_: Type, description: str, required: bool = True) -> "ToolBuilder":
        """
        Add a parameter to the tool.

        Args:
            name: Name of the parameter
            type_: Type of the parameter
            description: Description of the parameter
            required: Whether the parameter is required

        Returns:
            Self for method chaining
        """

    def build(self) -> Tool:
        """
        Build the tool.

        Returns:
            Instantiated Tool
        """