Toolkit

In Synthora, Tools are fundamental units of functionality exposed to agents. These tools can be synchronous or asynchronous and are designed to provide well-defined actions or computations as part of the agent framework. Tools facilitate structured and extensible interactions by following a standardized schema.

Key Concepts of Tools in Synthora:

1. Purpose of Tools:

   • Tools encapsulate specific functionalities, enabling agents to interact with them in a modular way.

   • They support callback mechanisms, allowing event-driven execution and result tracking.

2. Initialization:

   • Tools are created using the @tool decorator. This decorator wraps a function or method and ensures it adheres to the framework’s structure, handling both synchronous (SyncFunction) and asynchronous (AsyncFunction) execution patterns.

---

Tool Definition Using the @tool Decorator

The @tool decorator marks a function or method as a tool within the Synthora framework. It is the entry point for defining tools and ensures that functions are correctly wrapped for synchronous or asynchronous execution.

How It Works:

• Signature Inspection: The decorator inspects the function’s signature to determine if it is a method (i.e., part of a class) by checking for the self parameter.

• Flagging for Methods: If the function is a method, it is marked for later association with its class instance.

• Tool Wrapping: The function is passed to BaseFunction.wrap() for further processing, which creates either a SyncFunction or AsyncFunction object based on the function’s nature (synchronous or asynchronous).

Example:

# Synchronous tool definition
@tool
def add_numbers(a: int, b: int) -> int:
    """Adds two numbers and returns the result."""
    return a + b

# Asynchronous tool definition in a class
class MathTools:
    @tool
    async def multiply_numbers(self, a: int, b: int) -> int:
        """Multiplies two numbers asynchronously."""
        return a * b

---

BaseFunction: Abstract Base for Tool Wrappers

The BaseFunction class is an abstract base class used to wrap tools. It provides the foundation for both SyncFunction and AsyncFunction implementations.

Responsibilities:

1. Schema Integration:

   • Extracts schema metadata for tools (name, description, and parameters) to ensure compatibility with OpenAI tool standards.

2. Callback Management:

   • Integrates with callback handlers for events like TOOL_START, TOOL_ERROR, and TOOL_END.

3. Execution Interfaces:

   • Provides abstract methods for execution (__call__, run, and async_run) that are implemented in the concrete subclasses.

Example Usage:

# Accessing tool metadata and executing
tool_instance = SyncFunction(None, add_numbers)
print(tool_instance.name)  # Prints the tool's name from its schema
result = tool_instance.run(3, 5)  # Executes the tool and handles callbacks

---

Subclasses: SyncFunction and AsyncFunction

SyncFunction:

• Handles execution of synchronous functions.

• Supports callback handling during execution (run method).

• Raises NotImplementedError if asynchronous execution (async_run) is attempted.

AsyncFunction:

• Handles execution of asynchronous functions.

• Allows callbacks during asynchronous execution (async_run method).

• Raises NotImplementedError if synchronous execution (run) is attempted.

---

Managing Tools with BaseToolkit

The BaseToolkit class is an abstract base class for managing collections of tools within the framework.

Features:

1. Automatic Tool Collection:

   • Scans class definitions for methods wrapped with @tool.

   • Collects and categorizes them as synchronous or asynchronous tools.

2. Categorization:

   • sync_tools: List of all synchronous tools.

   • async_tools: List of all asynchronous tools.

Example:

class MathToolkit(BaseToolkit):
    @tool
    def add(self, a: int, b: int) -> int:
        return a + b

    @tool
    async def subtract(self, a: int, b: int) -> int:
        return a - b

# Usage
toolkit = MathToolkit()
sync_tools = toolkit.sync_tools  # List of synchronous tools
async_tools = toolkit.async_tools  # List of asynchronous tools

---

Properties Provided by BaseFunction

The BaseFunction class includes several key properties that provide metadata and functionality for tools. These properties ensure compatibility with schemas (e.g., OpenAI tools) and facilitate interaction with wrapped functions.

1. name

• Description: Retrieves the name of the wrapped function.

• Source: Extracted from the tool’s schema.

• Use Case: Helpful for identifying the tool in toolkits, logs, or callbacks.

Example:

print(my_tool.name)  # Outputs the tool's name from the schema

---

2. description

• Description: Returns the tool’s description, providing details about its purpose or functionality.

• Source: Pulled from the schema’s description field.

• Use Case: Useful for documentation or dynamically presenting tool details to agents.

Example:

print(my_tool.description)  # Outputs the tool's description

---

3. parameters

• Description: Retrieves a dictionary of parameter definitions from the tool’s schema.

• Source: Defined in the schema under parameters.properties.

• Use Case: Used for validation, introspection, or dynamically generating UI for tool invocation.

Example:

print(my_tool.parameters)
# Outputs a dictionary of parameters, e.g., {"a": {"type": "integer"}, "b": {"type": "integer"}}

---

Summary of Properties

Property	Description	Use Case
name	Name of the tool, extracted from the schema.	Identification in logs, debugging, or UI.
description	Description of the tool’s purpose/functionality.	Documentation or agent interaction.
parameters	Dictionary of parameter definitions for the tool.	Validation, dynamic UI generation.

These properties make BaseFunction a powerful abstraction for managing tools, ensuring they are self-descriptive, schema-compliant, and easy to integrate into the Synthora framework.

---

Toolkits Provided by Synthora

Toolkit Name	Description	Tools/Methods
BasicMathToolkit	Provides methods for basic math operations.	add, subtract, multiply, divide
FileToolkit	Handles file operations.	read_file, write_file, delete_file, copy_file, move_file, search_file, list_directory
SlidesToolkit	A toolkit for creating slides.	Custom slide creation tools (not detailed in the code)
SearchToolkit	Enables various search functionalities.	search_wikipedia, search_google, search_arxiv, search_youtube, search_duckduckgo
WeatherToolkit	Fetches weather data.	Tools for weather fetching (not detailed in the code)
TrafilaturaWebpageReader	Extracts main content from webpages using Trafilatura.	General webpage reading tools based on Trafilatura
get_webpage	A function to retrieve webpage text content using BeautifulSoup.	Accepts a URL and extracts the text content of the webpage.

This table highlights the modular structure of Synthora’s toolkits, which provide specialized functionalities for different use cases, such as mathematical calculations, file operations, and content extraction.

---

Summary of Key Properties and Methods

• @tool: Marks a function or method as a tool, initializing it as SyncFunction or AsyncFunction.

• BaseFunction.wrap(): Determines whether a function is sync or async and creates the appropriate wrapper.

• Execution:

  • run: Synchronous execution with callbacks.

  • async_run: Asynchronous execution with callbacks.

• Toolkit Management:

  • BaseToolkit: Automatically collects and organizes tools.

This structure ensures that tools in Synthora are well-integrated, extensible, and capable of handling complex workflows seamlessly.