Documentation

Toolhouse 🛠️🏠

Toolhouse is the first complete infrastructure for tool use. With Toolhouse, you can equip your LLM with tools like Code Interpreter, Web Search, and Email tools, among others. This equips your LLMs with the ability to search the web, send the emails they write, or run the code they generate, without the need for your to code or prompt these tools. These tools can be used across any LLM supported by Groq.

Python Quick Start (3 minutes to hello world)

1. Install Required Libraries

pip install toolhouse groq

2. Configure your API keys:

Note: You can get your free Toolhouse API key here!

export GROQ_API_KEY="your-groq-api-key"
export TOOLHOUSE_API_KEY="your-toolhouse-api-key"

3. Initialize the Groq and Toolhouse clients:

import os
from toolhouse import Toolhouse
from groq import Groq

client = Groq(api_key=os.environ.get('GROQ_API_KEY'))
th = Toolhouse(api_key=os.environ.get('TOOLHOUSE_API_KEY'))

4. Define and register a custom, local tool to perform arithmetic operations:

  • @th.register_local_tool: Registers a local function as a tool accessible via Toolhouse.
  • The calculate function takes an operation (add, subtract, multiply, or divide) and two numbers (x and y) as input and performs the operation.
@th.register_local_tool("calculate")
@th.register_local_tool("calculate")
def calculate(operation: str, x: float, y: float) -> str:
    operations = {
        "add": lambda: x + y,
        "subtract": lambda: x - y,
        "multiply": lambda: x * y,
        "divide": lambda: x / y if y != 0 else "Error: Cannot divide by zero"
    }
    if operation not in operations:
        return f"Error: Invalid operation. Please use add, subtract, multiply, or divide."
    result = operations[operation]()
    return f"The result of {x} {operation} {y} is {result}"

5. Clearly specify our tool definition for our LLM to be able understand what parameters are required along with their expected types to be able to use correctly when needed:

my_local_tools = [{
    "type": "function",
    "function": {
        "name": "calculate",
        "description": "This tool can be used to perform basic arithmetic operations on two numbers",
        "parameters": {
            "type": "object",
            "properties": {
                "operation": {
                    "type": "string",
                    "description": "The arithmetic operation to perform (add, subtract, multiply, or divide)",
                    "enum": ["add", "subtract", "multiply", "divide"]
                },
                "x": {
                    "type": "number",
                    "description": "The first number"
                },
                "y": {
                    "type": "number",
                    "description": "The second number"
                }
            },
            "required": ["operation", "x", "y"]
        }
    }
}]

Challenge: Update the code to add other custom, local tools and tools from Toolhouse!

6. Set up our conversation using multiple tool calls:

role specifies the speaker (system, user, or assistant) and content provides our query. Here, we first send our query to Groq API and retrieve any required tool calls. The first call identifies tool usage based on the user query and th.run_tools(response) executes the tools selected by the LLM. The second Groq API call incorporates the tool’s output to refine the response before printing the end result!

messages = [
    {
        "role": "user",
        "content": "perform 1024 + 1024. Then using the scraper, scrape https://console.groq.com/docs/changelog and tell me which is the latest model added"
    }
]

# First call - Get the tool function call
response = client.chat.completions.create(
    model="llama-3.3-70b-versatile",
    messages=messages,
    tools=th.get_tools() + my_local_tools  # Combine local and cloud tools
)

print("\n****** Tools Used in Response ******")
if hasattr(response.choices[0].message, 'tool_calls') and response.choices[0].message.tool_calls:
    idx = 1
    for tool_call in response.choices[0].message.tool_calls:
        print(f"DEBUG MSG {idx}: {response.choices[0]}")
        print(f"Tool {idx} used: {tool_call.function.name}")
        print(f"Arguments {idx}: {tool_call.function.arguments}\n")

        # Execute the tool
        tool_run = th.run_tools(response)
        messages.extend(tool_run)

        # Second call - Get the final response
        response = client.chat.completions.create(
            model="llama-3.3-70b-versatile",
            messages=messages,
            tools=th.get_tools() + my_local_tools
        )
        print(f"DEBUG RESPONSE {idx}: {response.choices[0].message.content}")
        idx += 1
else:
    print("No tools were used in this response")
print("FINAL RESPONSE", response.choices[0].message.content)

Additional Resources

For more robust documentation and further resources, including using Toolhouse with Groq building agentic workflows, see the following: