> ## Documentation Index
> Fetch the complete documentation index at: https://liquidai-alay2shah-sync-notebook-snippets.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Function Calling

> Function calling allows the model to make requests to call some predefined functions provided by the app to interact with the environment.

<Warning>
  Not all models support function calling. Please check the model card before using the model for function calling.
</Warning>

<Info>
  Vision and audio-capable models require companion files. Bundles embed these references; GGUF
  checkpoints expect siblings such as `mmproj-*.gguf` (vision) and audio decoder/tokenizer files.
  When detected, you can attach `ChatMessageContent.image` and `ChatMessageContent.audio` parts to
  your messages and tool responses.
</Info>

## Register functions to conversations

To enable function calling, function definitions should be registered to the [`Conversation`](./conversation-generation#conversation) instance before content generation.
`Conversation.registerFunction` takes a `LeapFunction` instance as the input, which describes the name, parameters and ability of the function.

```swift theme={"theme":{"light":"github-light","dark":"github-dark"}}
conversation.registerFunction(
  LeapFunction(
    name: "get_weather",
    description: "Query the weather of a city",
    parameters: [
      LeapFunctionParameter(
        name: "city",
        type: LeapFunctionParameterType.string(StringType()),
        description: "The city to query weather for"
      ),
      LeapFunctionParameter(
        name: "unit",
        type: LeapFunctionParameterType.string(
          StringType(enumValues: ["celsius", "fahrenheit"])),
        description: "Temperature unit (celsius or fahrenheit)"
      ),
    ]
  )
)
```

Generally speaking, function names and parameter names should be normal identifiers that are recognized by most common programming languages (e.g. Python, JavaScript, etc.). We
recommend using descriptive names composed of letters, underscores, and digits (not starting with digits).

## Handle Function Calling Response

Function calling requests by the model will be presented as `functionCall` enum value of `MessageResponse`, which contains a list of function calls.

```swift theme={"theme":{"light":"github-light","dark":"github-dark"}}
public enum MessageResponse {
  case functionCall([LeapFunctionCall])
  // ...
}
```

Each `LeapFunctionCall` instance contains names and arguments of the function call request. The `arguments` field is a map from `String` to `Any?`.
The app needs to check whether the required parameters are filled by the models. It is possible (even though very unlikely to happen) that some
parameters are missing or the function name is invalid.

```swift theme={"theme":{"light":"github-light","dark":"github-dark"}}
public struct LeapFunctionCall {
  public let name: String
  public let arguments: [String: Any?]
}
```

In order to handle the function call response, you will need to add a new branch to match responses from the `generateResponse` flow:

```swift theme={"theme":{"light":"github-light","dark":"github-dark"}}
let userMessage = ChatMessage(role: .user, content: [.text("What's the weather in NYC?")])

for try await response in conversation.generateResponse(
  message: userMessage
) {
  switch response {
  case .functionCall(let calls):
    for call in calls {
      // process function call here
      print("Function call: \(call.name), \(call.arguments)")
    }
  case .audioSample:
    break // Optional: route audio output elsewhere
  default:
    // process other responses
    break
  }
}
```

## Function Definition

Functions for models to call are defined by `LeapFunction` instances. It has three fields:

```swift theme={"theme":{"light":"github-light","dark":"github-dark"}}
public struct LeapFunction: Equatable {
  public let name: String
  public let description: String
  public let parameters: [LeapFunctionParameter]
}
```

`name` is the function name. It is recommended to use only English letters, underscores, and digits (not starting with digits) to compose the
function names because this format is supported by most models. `description` tells the model what this function is doing. `parameters` is
the array to declare what arguments (parameters) this function accepts.

The items of `parameters` are instances of `LeapFunctionParameter`.

```swift theme={"theme":{"light":"github-light","dark":"github-dark"}}
public struct LeapFunctionParameter: Equatable {
  public let name: String
  public let type: LeapFunctionParameterType
  public let description: String
  public let optional: Bool
}
```

* `name` The name of the parameter.
* `type` Data type of the parameter.
* `description` Tells the model what this parameter is about.
* `optional` Whether the parameter is optional.

`LeapFunctionParameterType` describes the data types of the parameters. They will be translated into JSON Schema for the model to understand.
Following types are supported:

```swift theme={"theme":{"light":"github-light","dark":"github-dark"}}
public indirect enum LeapFunctionParameterType: Codable, Equatable {
  case string(StringType)
  case number(NumberType)
  case integer(IntegerType)
  case boolean(BooleanType)
  case array(ArrayType)
  case object(ObjectType)
  case null(NullType)
}
```

`StringType`, `NumberType` and `IntegerType` have a field of `enumValues` to restrict the legit values for this parameter.

`ArrayType` has a field of `itemType` to describe the type of array items.

`ObjectType` has a `properties` field, which is a map from the property names (`String`) to the property types (`LeapFunctionParameterType`).
It also has a `required` field, which is an array of names of required properties.

Each enum value includes a struct to describe the type. All type except `NullType` has an optional field of `description` to describe the purpose of this type.
It will be overridden if it is directly used as `LeapFunctionParameter.type`. It only plays a role if the type instance is used as `ArrayType.itemType` or the types
in object properties.

Here is a more comprehensive example on defining a function:

```swift theme={"theme":{"light":"github-light","dark":"github-dark"}}
LeapFunction(
  name: "get_weather",
  description: "Query the weather of cities",
  parameters: [
    LeapFunctionParameter(
      name: "cities",
      type: LeapFunctionParameterType.array(
        ArrayType(itemType: .string(StringType()))
      ),
      description: "Names of the cities to query weather for"
    ),
    LeapFunctionParameter(
      name: "unit",
      type: LeapFunctionParameterType.string(
        StringType(enumValues: ["celsius", "fahrenheit"])),
      description: "Temperature unit (celsius or fahrenheit)"
    ),
  ]
)
```

## Function Call Parser

Function call parsers translate the model's tool-call tokens into `LeapFunctionCall` values. Different models
emit tool calls in different formats, so pick the parser that matches your checkpoint.

By default, `LFMFunctionCallParser` is used. It supports Liquid Foundation Model (LFM2) Pythonic-style control tokens (`<|tool_call_start|> ... <|tool_call_end|>`).

For Qwen3 models and other models that are using [Hermes function calling format](https://github.com/NousResearch/Hermes-Function-Calling),
apply `HermesFunctionCallParser` by injecting a parser instance on the generation options:

```swift theme={"theme":{"light":"github-light","dark":"github-dark"}}
var options = GenerationOptions()
options.functionCallParser = HermesFunctionCallParser()
for try await response in conversation.generateResponse(
  message: userMessage,
  generationOptions: options
) {
  // process message response here
}
```