> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Function and Tool Calling

> Enable models to invoke defined functions during conversations using function and tool calling capabilities.

Function calling allows models to invoke defined functions during conversations, enabling them to perform specific actions or retrieve information from external sources.

## Basic Usage

Define functions that the model can call:

```python lines theme={"dark"}
from openai import OpenAI
import json

client = OpenAI(
    api_key="your_truefoundry_api_key",
    base_url="{GATEWAY_BASE_URL}"
)

# Define a function
tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"]
                }
            },
            "required": ["location"]
        }
    }
}]

# Make the request
response = client.chat.completions.create(
    model="openai-main/gpt-4o-mini",
    messages=[{"role": "user", "content": "What's the weather in New York?"}],
    tools=tools
)

# Check if the model wants to call a function
if response.choices[0].message.tool_calls:
    tool_call = response.choices[0].message.tool_calls[0]
    function_name = tool_call.function.name
    function_args = json.loads(tool_call.function.arguments)

    print(f"Function called: {function_name}")
    print(f"Arguments: {function_args}")
```

## Function Definition Schema

<Accordion title="Basic Structure">
  When defining functions, you need to provide:

  * **name**: The function name
  * **description**: What the function does
  * **parameters**: JSON Schema object describing the parameters

  ```python lines theme={"dark"}
  function_schema = {
      "name": "get_weather",
      "description": "Get current weather information",
      "parameters": {
          "type": "object",
          "properties": {
              "location": {
                  "type": "string",
                  "description": "City name"
              }
          },
          "required": ["location"]
      }
  }
  ```
</Accordion>

<Accordion title="Parameter Types">
  Functions support various parameter types:

  ```python lines theme={"dark"}
  function_schema = {
      "name": "process_data",
      "description": "Process data with various parameters",
      "parameters": {
          "type": "object",
          "properties": {
              "text": {
                  "type": "string",
                  "description": "Text to process"
              },
              "count": {
                  "type": "integer",
                  "description": "Number of items"
              },
              "confidence": {
                  "type": "number",
                  "description": "Threshold (0.0 to 1.0)"
              },
              "enabled": {
                  "type": "boolean",
                  "description": "Whether processing is enabled"
              },
              "categories": {
                  "type": "array",
                  "items": {"type": "string"},
                  "description": "List of categories"
              }
          },
          "required": ["text"]
      }
  }
  ```
</Accordion>

## Complete Workflow

<Accordion title="Multiple Functions">
  Define multiple functions for the model to choose from:

  ```python lines theme={"dark"}
  tools = [
      {
          "type": "function",
          "function": {
              "name": "get_weather",
              "description": "Get current weather information",
              "parameters": {
                  "type": "object",
                  "properties": {
                      "location": {"type": "string"},
                      "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
                  },
                  "required": ["location"]
              }
          }
      },
      {
          "type": "function",
          "function": {
              "name": "search_web",
              "description": "Search the web for information",
              "parameters": {
                  "type": "object",
                  "properties": {
                      "query": {"type": "string"},
                      "max_results": {"type": "integer", "default": 5}
                  },
                  "required": ["query"]
              }
          }
      }
  ]
  ```
</Accordion>

<Accordion title="Handling Function Calls">
  Process function calls and continue the conversation:

  ```python lines theme={"dark"}
  # Initial request
  messages = [{"role": "user", "content": "What's the weather in Tokyo?"}]
  response = client.chat.completions.create(
      model="openai-main/gpt-4o-mini",
      messages=messages,
      tools=tools
  )

  # Handle function call
  if response.choices[0].message.tool_calls:
      messages.append(response.choices[0].message)

      for tool_call in response.choices[0].message.tool_calls:
          function_name = tool_call.function.name
          function_args = json.loads(tool_call.function.arguments)

          # Execute your function (simulated here)
          if function_name == "get_weather":
              result = f"The weather in {function_args['location']} is 22°C and sunny"

          # Add the function result to the conversation
          messages.append({
              "role": "tool",
              "tool_call_id": tool_call.id,
              "content": result
          })

      # Continue the conversation
      final_response = client.chat.completions.create(
          model="openai-main/gpt-4o-mini",
          messages=messages
      )

      print(final_response.choices[0].message.content)
  ```
</Accordion>

<Accordion title="Controlling Function Calls">
  Control when and how functions are called:

  ```python lines theme={"dark"}
  # Force a specific function call
  response = client.chat.completions.create(
      model="openai-main/gpt-4o-mini",
      messages=[{"role": "user", "content": "What's the weather?"}],
      tools=tools,
      tool_choice={"type": "function", "function": {"name": "get_weather"}}
  )

  # Allow automatic function calling (default)
  response = client.chat.completions.create(
      model="openai-main/gpt-4o-mini",
      messages=[{"role": "user", "content": "What's the weather?"}],
      tools=tools,
      tool_choice="auto"
  )

  # Prevent function calling
  response = client.chat.completions.create(
      model="openai-main/gpt-4o-mini",
      messages=[{"role": "user", "content": "What's the weather?"}],
      tools=tools,
      tool_choice="none"
  )

  # Force any function call
  response = client.chat.completions.create(
      model="openai-main/gpt-4o-mini",
      messages=[{"role": "user", "content": "What's the weather?"}],
      tools=tools,
      tool_choice="required"
  )
  ```
</Accordion>