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

# Function Calling

## 1. Use Cases

The Function Calling feature enables models to invoke external tools, thereby enhancing their capabilities.

This feature allows models to act as a "brain" that utilizes external tools (e.g., searching for external knowledge, checking itineraries, or accessing specialized domain tools) to effectively address issues such as hallucinations and knowledge recency.

## 2. How to Use

### 2.1 Add tools as a request parameter via REST API

Include the following in the request body:

```shell theme={null}
"tools": [
    {
        'type': 'function',
        'function': {
            'name': 'function_name',
            'description': 'function description',
            'parameters': {
                '_comments': 'function parameters'
            },
        }
    },
    {
        '_comments': 'other function descriptions'
    }
]
```

for example, payload:

```shell theme={null}
payload = {
    "model": "deepseek-ai/DeepSeek-V2.5",
    "messages": [
        {
            "role": "user",
            "content": "How is the weather in Tokyo?"
        }
    ],
    "tools": [
    {
        'type': 'function',
        'function': {
            'name': 'function name',
            'description': 'function description',
            'parameters': {
                '_comments': 'function parameters'
            },
        }
    },
    {
        '_comments': 'other function descriptions'
    }
    ]
    '_comments': 'other function descriptions'
}
```

### 2.2 Requesting via the OpenAI Library

This feature is compatible with OpenAI. When using the OpenAI library, add the parameter `tools=[corresponding tools]` in the request.
For example:

```python theme={null}
response = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-V2.5",
    messages = messages,
    tools=[
        {
            'type': 'function',
            'function': {
                'name': 'function name',
                'description': 'function description',
                'parameters': {
                    // function parameters
                },
            }
        },
        {
            // other function descriptions
        }
    ]
    // chat.completions other parameters
)
```

## 3. Supported Models

The currently supported models are:

* Deepseek Series:
  * deepseek-ai/DeepSeek-V2.5

* Qwen Series：
  * Qwen/Qwen2.5-72B-Instruct
  * Qwen/Qwen2.5-7B-Instruct

## 4. Examples

### 4.1. Example 1: Extending numerical computation capabilities

This code demonstrates the use of four functions: addition, subtraction, comparison of values, and counting repeated letters in a string.
The example illustrates how function calling can address execution challenges in areas where large language models are less proficient, such as numerical operations within token predictions.

```python theme={null}

from openai import OpenAI

client = OpenAI(
    api_key="Your API KEY", # get from https://dash.horay.ai/account/ak
    base_url="https://api.horay.ai/v1"
)

def add(a: float, b: float):
    return a + b

def mul(a: float, b: float):
    return a * b

def compare(a: float, b: float):
    if a > b:
        return f'{a} is greater than {b}'
    elif a < b:
        return f'{b} is greater than {a}'
    else:
        return f'{a} is equal to {b}'

def count_letter_in_string(a: str, b: str):
    string = a.lower()
    letter = b.lower()
    
    count = string.count(letter)
    return(f"The letter '{letter}' appears {count} times in the string.")


tools = [
{
    'type': 'function',
    'function': {
        'name': 'add',
        'description': 'Compute the sum of two numbers',
        'parameters': {
            'type': 'object',
            'properties': {
                'a': {
                    'type': 'int',
                    'description': 'A number',
                },
                'b': {
                    'type': 'int',
                    'description': 'A number',
                },
            },
            'required': ['a', 'b'],
        },
    }
}, 
{
    'type': 'function',
    'function': {
        'name': 'mul',
        'description': 'Calculate the product of two numbers',
        'parameters': {
            'type': 'object',
            'properties': {
                'a': {
                    'type': 'int',
                    'description': 'A number',
                },
                'b': {
                    'type': 'int',
                    'description': 'A number',
                },
            },
            'required': ['a', 'b'],
        },
    }
},
{
    'type': 'function',
    'function': {
        'name': 'count_letter_in_string',
        'description': 'Count letter number in a string',
        'parameters': {
            'type': 'object',
            'properties': {
                'a': {
                    'type': 'str',
                    'description': 'source string',
                },
                'b': {
                    'type': 'str',
                    'description': 'letter',
                },
            },
            'required': ['a', 'b'],
        },
    }
},
{
    'type': 'function',
    'function': {
        'name': 'compare',
        'description': 'Compare two number, which one is bigger',
        'parameters': {
            'type': 'object',
            'properties': {
                'a': {
                    'type': 'float',
                    'description': 'A number',
                },
                'b': {
                    'type': 'float',
                    'description': 'A number',
                },
            },
            'required': ['a', 'b'],
        },
    }
}
]

def function_call_playground(prompt):
    messages = [{'role': 'user', 'content': prompt}]
    response = client.chat.completions.create(
        model="deepseek-ai/DeepSeek-V2.5",
        messages = messages,
        temperature=0.01,
        top_p=0.95,
        stream=False,
        tools=tools)

    # print(response)
    func1_name = response.choices[0].message.tool_calls[0].function.name
    func1_args = response.choices[0].message.tool_calls[0].function.arguments
    func1_out = eval(f'{func1_name}(**{func1_args})')
    # print(func1_out)

    messages.append(response.choices[0].message)
    messages.append({
        'role': 'tool',
        'content': f'{func1_out}',
        'tool_call_id': response.choices[0].message.tool_calls[0].id
    })
    # print(messages)
    response = client.chat.completions.create(
        model="deepseek-ai/DeepSeek-V2.5",
        messages=messages,
        temperature=0.01,
        top_p=0.95,
        stream=False,
        tools=tools)
    return response.choices[0].message.content
  
prompts = [
    "How many “r”s are in “strawberry”?", 
    "Which is smaller, 9.11 or 9.9?"
]

for prompt in prompts:
    print(function_call_playground(prompt))
```

Output  might look like:

```shell theme={null}
There are 3 “r”s in “strawberry.”
9.11 is smaller than 9.9.
```

### 4.2. Example： Extending a large language model’s understanding of the external environment

This code uses a single function to query external information via an external API.

```python theme={null}
import requests
from openai import OpenAI

client = OpenAI(
    api_key="Your API KEY", # get from https://dash.horay.ai/account/ak
    base_url="https://api.horay.ai/v1"
)

# Use the WeatherAPI’s API to fetch weather information.
def get_weather(city: str):
    api_key = "your WeatherAPI APIKEY"  # your WeatherAPI APIKEY
    base_url = "http://api.weatherapi.com/v1/current.json"
    params = {
        'key': api_key,
        'q': city,
        'aqi': 'no' 
    }
    
    response = requests.get(base_url, params=params)
    
    if response.status_code == 200:
        data = response.json()
        weather = data['current']['condition']['text']
        temperature = data['current']['temp_c']
        return f"The weather in {city} is {weather} with a temperature of {temperature}°C."
    else:
        return f"Could not retrieve weather information for {city}."

# Define function calling tools
tools = [
    {
        'type': 'function',
        'function': {
            'name': 'get_weather',
            'description': 'Get the current weather for a given city.',
            'parameters': {
                'type': 'object',
                'properties': {
                    'city': {
                        'type': 'string',
                        'description': 'The name of the city to query weather for.',
                    },
                },
                'required': ['city'],
            },
        }
    }
]

# send request and handle function calling
def function_call_playground(prompt):
    messages = [{'role': 'user', 'content': prompt}]
    
    response = client.chat.completions.create(
        model="deepseek-ai/DeepSeek-V2.5",
        messages=messages,
        temperature=0.01,
        top_p=0.95,
        stream=False,
        tools=tools
    )

    func1_name = response.choices[0].message.tool_calls[0].function.name
    func1_args = response.choices[0].message.tool_calls[0].function.arguments
    func1_out = eval(f'{func1_name}(**{func1_args})')

    messages.append(response.choices[0].message)
    messages.append({
        'role': 'tool',
        'content': f'{func1_out}',
        'tool_call_id': response.choices[0].message.tool_calls[0].id
    })
    
    response = client.chat.completions.create(
        model="deepseek-ai/DeepSeek-V2.5",
        messages=messages,
        temperature=0.01,
        top_p=0.95,
        stream=False,
        tools=tools
    )
    
    return response.choices[0].message.content

prompt = "how is the weather today in New York?"
print(function_call_playground(prompt))
```

Output might look like:

```shell theme={null}
The weather in New York today is sunny with a temperature of 21.4°C.
```