Example: Simple Calculator

​

Overview of Step-by-Step Guide

1. Define Your Tool:
   • Create a class that inherits from Tool.
   • Use the @action decorator to define actions that the tool can perform.
     class Calculator(Tool):
         @action
         def add(self, a: int, b: int) -> int:
             return a + b
   
2. Initialize the Tool and Thread:
   • Instantiate your tool and a RoleThread for message management.
     self.tool = Calculator()
     self.thread = RoleThread()
   
3. Obtain the Tool Schema:
   • Retrieve the JSON schema of the tool to inform the LLM about available actions.
     schema = self.tool.json_schema()
   
4. Craft the System Prompt:
   • Create a system prompt that includes:
     • The role of the assistant.
     • The tool schema.
     • Instructions on how to format responses.
     system_prompt = f"""
     You are a helpful assistant...
     """
     self.thread.post("system", system_prompt)
   
5. Handle User Inputs:
   • Define a method to process user questions.
     def ask(self, question: str) -> str:
         ...
   
6. Implement Request Processing with Retries:
   • Use the @retry decorator to handle potential exceptions and retry the request.
   • Post the user’s question to the thread.
   • Get the LLM’s response.
   • Parse the response into the expected format.
   • Execute the action using the tool.
     @retry(...)
     def request(self, thread: RoleThread, question: str) -> str:
         ...
   
7. Parse and Execute LLM Responses:
   • Convert the LLM’s output into a V1ActionSelection object.
   • Find the corresponding action in the tool.
   • Execute the action with the provided parameters.
     action_selection = V1ActionSelection(...)
     action_object = self.tool.find_action(...)
     result = self.tool.use(action_object, ...)
   

​

Prerequisites

• Python installed on your system.
• Necessary Python packages installed:
  • toolfuse
  • rich
  • threadmem
  • litellm
  • skillpacks
  • tenacity
  • dotenv

​

Setup

1. Import required modules: Essential libraries for tool definition, threading, LLM completion, and logging.
2. Logging setup: Configures logging to display information-level logs.
3. Environment variables: Loads environment variables from a .env file for configurations.

​

Defining the Tool

class Calculator(Tool):
    def __init__(self):
        super().__init__()

    @action
    def add(self, a: int, b: int) -> int:
        return a + b

​

Calculator Tool

• Inherits from Tool class
• Defines an add action using the @action decorator

​

add Method

• Accepts two integers as parameters
• Returns their sum

​

Integrating with the LLM

​

Thinker Class

class Thinker():
    def __init__(self):
        self.tool = Calculator()
        self.thread = RoleThread()

        # Obtain the JSON schema of the tool
        schema = self.tool.json_schema()
        print(f"Tool schema:\n{schema}")

        # Define the system prompt for the LLM
        system_prompt = f"""
        You are a helpful assistant able to perform complex mathematical operations. 
        You have access to the following tools: {schema}. 
        For each task that I send to you, you have to return your thoughts and the specific tool to use to solve it.
        Please return your response in the following JSON format: {V1ActionSelection.model_json_schema()}
        Please only return the JSON object without any additional text or formatting.
        """
        self.thread.post("system", system_prompt)

• Manages the interaction between the LLM and the tool
• Initializes the Calculator tool and a RoleThread for message threading
• Retrieves the JSON schema of the tool, which outlines its available actions and parameters.
• Crafts a system prompt that instructs the LLM on how to utilize the tool and format responses

​

ask Method

def ask(self, question: str) -> str:
    thread_copy = self.thread.copy()
    thread_copy, result = self.request(thread_copy, question)
    self.thread = thread_copy
    return result

• Accepts a user question
• Copies the current thread state
• Processes the request

​

Processing Requests with Retries

@retry(
    stop=stop_after_attempt(5),
    before_sleep=before_sleep_log(logger, logging.INFO),            
)
def request(self, thread: RoleThread, question: str) -> str:
    thread.post("user", question)

    response = completion(model="gpt-4o", messages=thread.to_openai())
    print(f"Raw response:\n{response}")

    # Parse the response into the expected format
    action_selection = V1ActionSelection(**json.loads(response.choices[0].message.content))
    print(f"Suggested action:\n{action_selection}")

    # Find and execute the specified action
    action_object = self.tool.find_action(action_selection.action.name)
    print(f"Action object:\n{action_object}")

    result = self.tool.use(action_object, **action_selection.action.parameters)
    print(f"Action result:\n{result}")

    return thread, result

• @retry Decorator: Retries the request up to 5 times if exceptions occur (e.g., incorrect response formats).
• Posting the Question: Adds the user’s question to the thread.
• LLM Completion: Calls the LLM to get a response using the current thread messages.
• Parsing the Response: Expects the LLM to return a JSON-formatted action selection, which is parsed into a V1ActionSelection object.
• Executing the Action: Finds the corresponding action in the tool and executes it with the provided parameters.
• Result: Returns the updated thread and the result of the action.

​

Running the Script

1. Instantiate the Thinker class.
2. Call the ask method with questions. The tool can handle both numerical and word-based numbers.
3. Print or handle the results obtained from the LLM-assisted tool execution.

if __name__ == "__main__":
    thinker = Thinker()
    result_1 = thinker.ask("What is 1234 + 8765?")
    result_2 = thinker.ask("How much do I get if I add two and seven?")
    print(f"Result 1:\n{result_1}")
    print(f"Result 2:\n{result_2}")

• Extend LLM capabilities with custom tools
• Perform specific actions beyond text generation
• Utilize external functionalities seamlessly
• Enhance overall AI system performance

​

What’s next?

• Play around with this example at Jupyter notebook.
• Look at more realistic example of a SeleniumBrowser tool implementation.
• Dive into an elaborated implementation of the Desktop tool from the AgentDesk project, which adds the Tool sause on top of the Agentd-powered VMs.