quickstarts/Function_calling.ipynb

{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "Tce3stUlHN0L"
      },
      "source": [
        "##### Copyright 2024 Google LLC."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 1,
      "metadata": {
        "cellView": "form",
        "id": "tuOe1ymfHZPu"
      },
      "outputs": [],
      "source": [
        "# @title Licensed under the Apache License, Version 2.0 (the \"License\");\n",
        "# you may not use this file except in compliance with the License.\n",
        "# You may obtain a copy of the License at\n",
        "#\n",
        "# https://www.apache.org/licenses/LICENSE-2.0\n",
        "#\n",
        "# Unless required by applicable law or agreed to in writing, software\n",
        "# distributed under the License is distributed on an \"AS IS\" BASIS,\n",
        "# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n",
        "# See the License for the specific language governing permissions and\n",
        "# limitations under the License."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "yeadDkMiISin"
      },
      "source": [
        "# Gemini API: Function calling with Python"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "lEXQ3OwKIa-O"
      },
      "source": [
        "<table align=\"left\">\n",
        "  <td>\n",
        "    <a target=\"_blank\" href=\"https://colab.research.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Function_calling.ipynb\"><img src=\"https://github.com/Giom-V/gemini-api-cookbook/blob/function_calling/images/colab_logo_32px.png?raw=1\" />Run in Google Colab</a>\n",
        "  </td>\n",
        "</table>\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "df1767a3d1cc"
      },
      "source": [
        "Function calling lets developers create a description of a function in their code, then pass that description to a language model in a request. The response from the model includes the name of a function that matches the description and the arguments to call it with. Function calling lets you use functions as tools in generative AI applications, and you can define more than one function within a single request.\n",
        "\n",
        "This notebook provides code examples to help you get started."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "d5027929de8f"
      },
      "source": [
        "### Install dependencies"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 2,
      "metadata": {
        "id": "9OEoeosRTv-5"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "\u001b[?25l   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m0.0/164.0 kB\u001b[0m \u001b[31m?\u001b[0m eta \u001b[36m-:--:--\u001b[0m\r\u001b[2K   \u001b[91m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m\u001b[91m╸\u001b[0m \u001b[32m163.8/164.0 kB\u001b[0m \u001b[31m9.3 MB/s\u001b[0m eta \u001b[36m0:00:01\u001b[0m\r\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m164.0/164.0 kB\u001b[0m \u001b[31m2.9 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25h\u001b[?25l   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m0.0/725.4 kB\u001b[0m \u001b[31m?\u001b[0m eta \u001b[36m-:--:--\u001b[0m\r\u001b[2K   \u001b[91m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m\u001b[91m╸\u001b[0m \u001b[32m716.8/725.4 kB\u001b[0m \u001b[31m37.4 MB/s\u001b[0m eta \u001b[36m0:00:01\u001b[0m\r\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m725.4/725.4 kB\u001b[0m \u001b[31m17.6 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25h"
          ]
        }
      ],
      "source": [
        "!pip install -U -q \"google-generativeai>=0.7.2\"  # Install the Python SDK"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 3,
      "metadata": {
        "id": "TS9l5igubpHO"
      },
      "outputs": [],
      "source": [
        "import google.generativeai as genai"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "x-hHZfLZ7FfH"
      },
      "source": [
        "### Set up your API key\n",
        "\n",
        "To run the following cell, your API key must be stored it in a Colab Secret named `GOOGLE_API_KEY`. If you don't already have an API key, or you're not sure how to create a Colab Secret, see the [Authentication](../quickstarts/Authentication.ipynb) quickstart for an example."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 4,
      "metadata": {
        "id": "ab9ASynfcIZn"
      },
      "outputs": [],
      "source": [
        "from google.colab import userdata\n",
        "\n",
        "GOOGLE_API_KEY = userdata.get(\"GOOGLE_API_KEY\")\n",
        "genai.configure(api_key=GOOGLE_API_KEY)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "3f383614ec30"
      },
      "source": [
        "## Function calling basics"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "b82c1aecb657"
      },
      "source": [
        "To use function calling, pass a list of functions to the `tools` parameter when creating a [`GenerativeModel`](https://ai.google.dev/api/python/google/generativeai/GenerativeModel). The model uses the function name, docstring, parameters, and parameter type annotations to decide if it needs the function to best answer a prompt.\n",
        "\n",
        "> Important: The SDK converts function parameter type annotations to a format the API understands (`genai.protos.FunctionDeclaration`). The API only supports a limited selection of parameter types, and the Python SDK's automatic conversion only supports a subset of that: `AllowedTypes = int | float | bool | str | list['AllowedTypes'] | dict`"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 5,
      "metadata": {
        "id": "42b27b02d2f5"
      },
      "outputs": [
        {
          "data": {
            "text/plain": [
              "genai.GenerativeModel(\n",
              "    model_name='models/gemini-1.5-flash',\n",
              "    generation_config={},\n",
              "    safety_settings={},\n",
              "    tools=<google.generativeai.types.content_types.FunctionLibrary object at 0x7c77c21a6230>,\n",
              "    system_instruction=None,\n",
              "    cached_content=None\n",
              ")"
            ]
          },
          "execution_count": 5,
          "metadata": {},
          "output_type": "execute_result"
        }
      ],
      "source": [
        "def add(a: float, b: float):\n",
        "    \"\"\"returns a + b.\"\"\"\n",
        "    return a + b\n",
        "\n",
        "\n",
        "def subtract(a: float, b: float):\n",
        "    \"\"\"returns a - b.\"\"\"\n",
        "    return a - b\n",
        "\n",
        "\n",
        "def multiply(a: float, b: float):\n",
        "    \"\"\"returns a * b.\"\"\"\n",
        "    return a * b\n",
        "\n",
        "\n",
        "def divide(a: float, b: float):\n",
        "    \"\"\"returns a / b.\"\"\"\n",
        "    return a / b\n",
        "\n",
        "\n",
        "model = genai.GenerativeModel(\n",
        "    model_name=\"gemini-1.5-flash\", tools=[add, subtract, multiply, divide]\n",
        ")\n",
        "\n",
        "model"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "UzUgtaY99BTg"
      },
      "source": [
        "## Automatic function calling"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "d5fd91032a1e"
      },
      "source": [
        "Function calls naturally fit in to [multi-turn chats](https://ai.google.dev/api/python/google/generativeai/GenerativeModel#multi-turn) as they capture a back and forth interaction between the user and model. The Python SDK's [`ChatSession`](https://ai.google.dev/api/python/google/generativeai/ChatSession) is a great interface for chats because handles the conversation history for you, and using the parameter `enable_automatic_function_calling` simplifies function calling even further:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 6,
      "metadata": {
        "id": "d3b91c855257"
      },
      "outputs": [],
      "source": [
        "chat = model.start_chat(enable_automatic_function_calling=True)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "1481a6159399"
      },
      "source": [
        "With automatic function calling enabled, `ChatSession.send_message` automatically calls your function if the model asks it to.\n",
        "\n",
        "In the following example, the result appears to simply be a text response containing the correct answer:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 7,
      "metadata": {
        "id": "81d8def3d865"
      },
      "outputs": [
        {
          "data": {
            "application/vnd.google.colaboratory.intrinsic+json": {
              "type": "string"
            },
            "text/plain": [
              "\"That's a total of 2508 mittens. \\n\""
            ]
          },
          "execution_count": 7,
          "metadata": {},
          "output_type": "execute_result"
        }
      ],
      "source": [
        "response = chat.send_message(\n",
        "    \"I have 57 cats, each owns 44 mittens, how many mittens is that in total?\"\n",
        ")\n",
        "response.text"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 8,
      "metadata": {
        "id": "951c0f83f72e"
      },
      "outputs": [
        {
          "data": {
            "text/plain": [
              "2508"
            ]
          },
          "execution_count": 8,
          "metadata": {},
          "output_type": "execute_result"
        }
      ],
      "source": [
        "57 * 44"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "7731e35f2383"
      },
      "source": [
        "However, by examining the chat history, you can see the flow of the conversation and how function calls are integrated within it.\n",
        "\n",
        "The `ChatSession.history` property stores a chronological record of the conversation between the user and the Gemini model. Each turn in the conversation is represented by a [`genai.protos.Content`](https://ai.google.dev/api/python/google/generativeai/protos/Content) object, which contains the following information:\n",
        "\n",
        "*   **Role**: Identifies whether the content originated from the \"user\" or the \"model\".\n",
        "*   **Parts**: A list of [`genai.protos.Part`](https://ai.google.dev/api/python/google/generativeai/protos/Part) objects that represent individual components of the message. With a text-only model, these parts can be:\n",
        "    *   **Text**: Plain text messages.\n",
        "    *   **Function Call** ([`genai.protos.FunctionCall`](https://ai.google.dev/api/python/google/generativeai/protos/FunctionCall)): A request from the model to execute a specific function with provided arguments.\n",
        "    *   **Function Response** ([`genai.protos.FunctionResponse`](https://ai.google.dev/api/python/google/generativeai/protos/FunctionResponse)): The result returned by the user after executing the requested function.\n",
        "\n",
        " In the previous example with the mittens calculation, the history shows the following sequence:\n",
        "\n",
        "1.  **User**: Asks the question about the total number of mittens.\n",
        "1.  **Model**: Determines that the multiply function is helpful and sends a FunctionCall request to the user.\n",
        "1.  **User**: The `ChatSession` automatically executes the function (due to `enable_automatic_function_calling` being set) and sends back a `FunctionResponse` with the calculated result.\n",
        "1.  **Model**: Uses the function's output to formulate the final answer and presents it as a text response."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 9,
      "metadata": {
        "id": "9f7eff1e8e60"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "user -> [{'text': 'I have 57 cats, each owns 44 mittens, how many mittens is that in total?'}]\n",
            "--------------------------------------------------------------------------------\n",
            "model -> [{'function_call': {'name': 'multiply', 'args': {'a': 57.0, 'b': 44.0}}}]\n",
            "--------------------------------------------------------------------------------\n",
            "user -> [{'function_response': {'name': 'multiply', 'response': {'result': 2508.0}}}]\n",
            "--------------------------------------------------------------------------------\n",
            "model -> [{'text': \"That's a total of 2508 mittens. \\n\"}]\n",
            "--------------------------------------------------------------------------------\n"
          ]
        }
      ],
      "source": [
        "for content in chat.history:\n",
        "    print(content.role, \"->\", [type(part).to_dict(part) for part in content.parts])\n",
        "    print(\"-\" * 80)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "2471fd72f05e"
      },
      "source": [
        "In general the state diagram is:\n",
        "\n",
        "<img src=\"https://codelabs.developers.google.com/static/codelabs/gemini-function-calling/img/gemini-function-calling-overview_1440.png\" alt=\"The model can always reply with text, or a FunctionCall. If the model sends a FunctionCall the user must reply with a FunctionResponse\" width=50%>\n",
        "\n",
        "The model can respond with multiple function calls before returning a text response, and function calls come before the text response."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "eea8e3a0b89f"
      },
      "source": [
        "## Manual function calling"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "9610f3465a69"
      },
      "source": [
        "For more control, you can process [`genai.protos.FunctionCall`](https://ai.google.dev/api/python/google/generativeai/protos/FunctionCall) requests from the model yourself. This would be the case if:\n",
        "\n",
        "- You use a `ChatSession` with the default `enable_automatic_function_calling=False`.\n",
        "- You use `GenerativeModel.generate_content` (and manage the chat history yourself)."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "34ffab0bf365"
      },
      "source": [
        "The following example is a rough equivalent of the [function calling single-turn curl sample](https://ai.google.dev/docs/function_calling#function-calling-single-turn-curl-sample) in Python. It uses functions that return (mock) movie playtime information, possibly from a hypothetical API:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 10,
      "metadata": {
        "id": "46ba0fa3d09a"
      },
      "outputs": [],
      "source": [
        "def find_movies(description: str, location: str = \"\"):\n",
        "    \"\"\"find movie titles currently playing in theaters based on any description, genre, title words, etc.\n",
        "\n",
        "    Args:\n",
        "        description: Any kind of description including category or genre, title words, attributes, etc.\n",
        "        location: The city and state, e.g. San Francisco, CA or a zip code e.g. 95616\n",
        "    \"\"\"\n",
        "    return [\"Barbie\", \"Oppenheimer\"]\n",
        "\n",
        "\n",
        "def find_theaters(location: str, movie: str = \"\"):\n",
        "    \"\"\"Find theaters based on location and optionally movie title which are is currently playing in theaters.\n",
        "\n",
        "    Args:\n",
        "        location: The city and state, e.g. San Francisco, CA or a zip code e.g. 95616\n",
        "        movie: Any movie title\n",
        "    \"\"\"\n",
        "    return [\"Googleplex 16\", \"Android Theatre\"]\n",
        "\n",
        "\n",
        "def get_showtimes(location: str, movie: str, theater: str, date: str):\n",
        "    \"\"\"\n",
        "    Find the start times for movies playing in a specific theater.\n",
        "\n",
        "    Args:\n",
        "      location: The city and state, e.g. San Francisco, CA or a zip code e.g. 95616\n",
        "      movie: Any movie title\n",
        "      thearer: Name of the theater\n",
        "      date: Date for requested showtime\n",
        "    \"\"\"\n",
        "    return [\"10:00\", \"11:00\"]"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "Ck-hdu5N8VlR"
      },
      "source": [
        "Use a dictionary to make looking up functions by name easier later on. You can also use it to pass the array of functions to the `tools` parameter of `GenerativeModel`."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 11,
      "metadata": {
        "id": "8i3SKdy18WHu"
      },
      "outputs": [],
      "source": [
        "functions = {\n",
        "    \"find_movies\": find_movies,\n",
        "    \"find_theaters\": find_theaters,\n",
        "    \"get_showtimes\": get_showtimes,\n",
        "}\n",
        "\n",
        "model = genai.GenerativeModel(model_name=\"gemini-1.5-flash\", tools=functions.values())"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "11631c6e2b10"
      },
      "source": [
        "After using `generate_content()` to ask a question, the model requests a `function_call`:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 12,
      "metadata": {
        "id": "5e3b9c84d883"
      },
      "outputs": [
        {
          "data": {
            "text/plain": [
              "[function_call {\n",
              "  name: \"find_theaters\"\n",
              "  args {\n",
              "    fields {\n",
              "      key: \"location\"\n",
              "      value {\n",
              "        string_value: \"Mountain View\"\n",
              "      }\n",
              "    }\n",
              "    fields {\n",
              "      key: \"movie\"\n",
              "      value {\n",
              "        string_value: \"Barbie\"\n",
              "      }\n",
              "    }\n",
              "  }\n",
              "}\n",
              "]"
            ]
          },
          "execution_count": 12,
          "metadata": {},
          "output_type": "execute_result"
        }
      ],
      "source": [
        "response = model.generate_content(\n",
        "    \"Which theaters in Mountain View show the Barbie movie?\"\n",
        ")\n",
        "response.candidates[0].content.parts"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "kuldoypuAC1i"
      },
      "source": [
        "Since this is not using a `ChatSession` with automatic function calling, you have to call the function yourself.\n",
        "\n",
        "A very simple way to do this would be with `if` statements:\n",
        "\n",
        "```python\n",
        "if function_call.name == 'find_theaters':\n",
        "  find_theaters(**function_call.args)\n",
        "elif ...\n",
        "```\n",
        "\n",
        "However, since you already made the `functions` dictionary, this can be simplified to:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 13,
      "metadata": {
        "id": "rjkZ8MA00Coc"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "['Googleplex 16', 'Android Theatre']\n"
          ]
        }
      ],
      "source": [
        "def call_function(function_call, functions):\n",
        "    function_name = function_call.name\n",
        "    function_args = function_call.args\n",
        "    return functions[function_name](**function_args)\n",
        "\n",
        "\n",
        "part = response.candidates[0].content.parts[0]\n",
        "\n",
        "# Check if it's a function call; in real use you'd need to also handle text\n",
        "# responses as you won't know what the model will respond with.\n",
        "if part.function_call:\n",
        "    result = call_function(part.function_call, functions)\n",
        "\n",
        "print(result)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "XLWrHOatBtRz"
      },
      "source": [
        "Finally, pass the response plus the message history to the next `generate_content()` call to get a final text response from the model."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 14,
      "metadata": {
        "id": "gdb62GstAD_3"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "The following theaters in Mountain View show the Barbie movie: Googleplex 16 and Android Theatre. \n",
            "\n"
          ]
        }
      ],
      "source": [
        "from google.protobuf.struct_pb2 import Struct\n",
        "\n",
        "# Put the result in a protobuf Struct\n",
        "s = Struct()\n",
        "s.update({\"result\": result})\n",
        "\n",
        "# Update this after https://github.com/google/generative-ai-python/issues/243\n",
        "function_response = genai.protos.Part(\n",
        "    function_response=genai.protos.FunctionResponse(name=\"find_theaters\", response=s)\n",
        ")\n",
        "\n",
        "# Build the message history\n",
        "messages = [\n",
        "    # fmt: off\n",
        "    {\"role\": \"user\",\n",
        "     \"parts\": [\"Which theaters in Mountain View show the Barbie movie?.\"]},\n",
        "    {\"role\": \"model\",\n",
        "     \"parts\": response.candidates[0].content.parts},\n",
        "    {\"role\": \"user\",\n",
        "     \"parts\": [function_response]},\n",
        "    # fmt: on\n",
        "]\n",
        "\n",
        "# Generate the next response\n",
        "response = model.generate_content(messages)\n",
        "print(response.text)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "94a52c498cb8"
      },
      "source": [
        "## Function calling chain\n",
        "\n",
        "The model is not limited to one function call, it can chain them until it finds the right answer."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 15,
      "metadata": {
        "id": "809deb79f194"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "user -> [{'text': 'Which comedy movies are shown tonight in Mountain view and at what time?'}]\n",
            "--------------------------------------------------------------------------------\n",
            "model -> [{'function_call': {'name': 'find_movies', 'args': {'location': 'Mountain View, CA', 'description': 'comedy'}}}]\n",
            "--------------------------------------------------------------------------------\n",
            "user -> [{'function_response': {'name': 'find_movies', 'response': {'result': ['Barbie', 'Oppenheimer']}}}]\n",
            "--------------------------------------------------------------------------------\n",
            "model -> [{'function_call': {'name': 'find_theaters', 'args': {'movie': 'Barbie', 'location': 'Mountain View, CA'}}}]\n",
            "--------------------------------------------------------------------------------\n",
            "user -> [{'function_response': {'name': 'find_theaters', 'response': {'result': ['Googleplex 16', 'Android Theatre']}}}]\n",
            "--------------------------------------------------------------------------------\n",
            "model -> [{'function_call': {'name': 'get_showtimes', 'args': {'date': 'tonight', 'location': 'Mountain View, CA', 'theater': 'Googleplex 16', 'movie': 'Barbie'}}}]\n",
            "--------------------------------------------------------------------------------\n",
            "user -> [{'function_response': {'name': 'get_showtimes', 'response': {'result': ['10:00', '11:00']}}}]\n",
            "--------------------------------------------------------------------------------\n",
            "model -> [{'text': 'The comedy movie \"Barbie\" is showing at Googleplex 16 at 10:00 and 11:00 tonight. \\n'}]\n",
            "--------------------------------------------------------------------------------\n"
          ]
        }
      ],
      "source": [
        "chat = model.start_chat(enable_automatic_function_calling=True)\n",
        "response = chat.send_message(\n",
        "    \"Which comedy movies are shown tonight in Mountain view and at what time?\"\n",
        ")\n",
        "for content in chat.history:\n",
        "    print(content.role, \"->\", [type(part).to_dict(part) for part in content.parts])\n",
        "    print(\"-\" * 80)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "eb364196a719"
      },
      "source": [
        "Here you can see that the model made three calls to answer your question and used the outputs of them in the subsequent calls and in the final answer."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "EuwKoNIhGBJN"
      },
      "source": [
        "## Parallel function calls\n",
        "\n",
        "The Gemini API can call multiple functions in a single turn. This caters for scenarios where there are multiple function calls that can take place independently to complete a task.\n",
        "\n",
        "First set the tools up. Unlike the movie example above, these functions do not require input from each other to be called so they should be good candidates for parallel calling."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 16,
      "metadata": {
        "id": "cJ-mSixWGqLv"
      },
      "outputs": [],
      "source": [
        "def power_disco_ball(power: bool) -> bool:\n",
        "    \"\"\"Powers the spinning disco ball.\"\"\"\n",
        "    print(f\"Disco ball is {'spinning!' if power else 'stopped.'}\")\n",
        "    return True\n",
        "\n",
        "\n",
        "def start_music(energetic: bool, loud: bool, bpm: int) -> str:\n",
        "    \"\"\"Play some music matching the specified parameters.\n",
        "\n",
        "    Args:\n",
        "      energetic: Whether the music is energetic or not.\n",
        "      loud: Whether the music is loud or not.\n",
        "      bpm: The beats per minute of the music.\n",
        "\n",
        "    Returns: The name of the song being played.\n",
        "    \"\"\"\n",
        "    print(f\"Starting music! {energetic=} {loud=}, {bpm=}\")\n",
        "    return \"Never gonna give you up.\"\n",
        "\n",
        "\n",
        "def dim_lights(brightness: float) -> bool:\n",
        "    \"\"\"Dim the lights.\n",
        "\n",
        "    Args:\n",
        "      brightness: The brightness of the lights, 0.0 is off, 1.0 is full.\n",
        "    \"\"\"\n",
        "    print(f\"Lights are now set to {brightness:.0%}\")\n",
        "    return True"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "zlrmXN7fxQi0"
      },
      "source": [
        "Now call the model with an instruction that could use all of the specified tools."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 17,
      "metadata": {
        "id": "21ecYHLgIsCl"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "power_disco_ball(power=True)\n",
            "start_music(energetic=True, bpm=120.0, loud=True)\n",
            "dim_lights(brightness=0.5)\n"
          ]
        }
      ],
      "source": [
        "# Set the model up with tools.\n",
        "house_fns = [power_disco_ball, start_music, dim_lights]\n",
        "# Try this out with Pro and Flash...\n",
        "model = genai.GenerativeModel(model_name=\"gemini-1.5-flash\", tools=house_fns)\n",
        "\n",
        "# Call the API.\n",
        "chat = model.start_chat()\n",
        "response = chat.send_message(\"Turn this place into a party!\")\n",
        "\n",
        "# Print out each of the function calls requested from this single call.\n",
        "for part in response.parts:\n",
        "    if fn := part.function_call:\n",
        "        args = \", \".join(f\"{key}={val}\" for key, val in fn.args.items())\n",
        "        print(f\"{fn.name}({args})\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "t6iYpty7yZct"
      },
      "source": [
        "Each of the printed results reflects a single function call that the model has requested. To send the results back, include the responses in the same order as they were requested."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 18,
      "metadata": {
        "id": "L7RxoiR3foBR"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "I've powered up the disco ball, started some energetic music at 120 BPM, and dimmed the lights.  Get ready to party! \n",
            "\n"
          ]
        }
      ],
      "source": [
        "# Simulate the responses from the specified tools.\n",
        "responses = {\n",
        "    \"power_disco_ball\": True,\n",
        "    \"start_music\": \"Never gonna give you up.\",\n",
        "    \"dim_lights\": True,\n",
        "}\n",
        "\n",
        "# Build the response parts.\n",
        "response_parts = [\n",
        "    genai.protos.Part(function_response=genai.protos.FunctionResponse(name=fn, response={\"result\": val}))\n",
        "    for fn, val in responses.items()\n",
        "]\n",
        "\n",
        "response = chat.send_message(response_parts)\n",
        "print(response.text)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "7c2f31504490"
      },
      "source": [
        "## Next Steps\n",
        "### Useful API references:\n",
        "\n",
        "- The [genai.GenerativeModel](https://github.com/google-gemini/generative-ai-python/blob/main/docs/api/google/generativeai/GenerativeModel.md) class\n",
        "  - Its [GenerativeModel.generate_content](https://github.com/google-gemini/generative-ai-python/blob/main/docs/api/google/generativeai/GenerativeModel.md#generate_content) method builds a [genai.protos.GenerateContentRequest](https://github.com/google-gemini/generative-ai-python/blob/main/docs/api/google/generativeai/protos/GenerateContentRequest.md) behind the scenes.\n",
        "    - The request's `.tools` field contains a list of 1 [genai.protos.Tool](https://github.com/google-gemini/generative-ai-python/blob/main/docs/api/google/generativeai/protos/Tool.md) object.\n",
        "    - The tool's `function_declarations` attribute contains a list of [FunctionDeclarations](https://github.com/google-gemini/generative-ai-python/blob/main/docs/api/google/generativeai/protos/FunctionDeclaration.md) objects.\n",
        "- The [response](https://github.com/google-gemini/generative-ai-python/blob/main/docs/api/google/generativeai/protos/GenerateContentResponse.md) may contain a [genai.protos.FunctionCall](https://github.com/google-gemini/generative-ai-python/blob/main/docs/api/google/generativeai/protos/FunctionCall.md), in `response.candidates[0].contents.parts[0]`.\n",
        "- if `enable_automatic_function_calling` is set the [genai.ChatSession](https://github.com/google-gemini/generative-ai-python/blob/main/docs/api/google/generativeai/ChatSession.md) executes the call, and sends back the [genai.protos.FunctionResponse](https://github.com/google-gemini/generative-ai-python/blob/main/docs/api/google/generativeai/protos/FunctionResponse.md).\n",
        "- In response to a [FunctionCall](https://github.com/google-gemini/generative-ai-python/blob/main/docs/api/google/generativeai/protos/FunctionCall.md) the model always expects a [FunctionResponse](https://github.com/google-gemini/generative-ai-python/blob/main/docs/api/google/generativeai/protos/FunctionResponse.md).\n",
        "- If you reply manually using [chat.send_message](https://github.com/google-gemini/generative-ai-python/blob/main/docs/api/google/generativeai/ChatSession.md#send_message) or [model.generate_content](https://github.com/google-gemini/generative-ai-python/blob/main/docs/api/google/generativeai/GenerativeModel.md#generate_content) remember thart the API is stateless you have to send the whole conversation history (a list of [content](https://github.com/google-gemini/generative-ai-python/blob/main/docs/api/google/generativeai/protos/Content.md) objects), not just the last one containing the `FunctionResponse`.\n",
        "\n",
        "### Related examples\n",
        "\n",
        "Check those examples using function calling to give you more ideas on how to use that very useful feature:\n",
        "* [Barista Bot](../examples/Agents_Function_Calling_Barista_Bot.ipynb), an agent to order coffee\n",
        "* Using function calling to [re-rank seach results](../examples/Search_reranking_using_embeddings.ipynb)\n",
        "\n",
        "### Continue your discovery of the Gemini API\n",
        "\n",
        "Learn how to control how the Gemini API interact with your functions in the [function calling config](../quickstarts/Function_calling_config.ipynb) quickstart, discover how to control the model output in [JSON](../quickstarts/JSON_mode.ipynb) or using an [Enum](../quickstarts/Enum.ipynb) or learn how the Gemini API can generate and run code by itself using [Code execution](../quickstarts/Code_Execution.ipynb)"
      ]
    }
  ],
  "metadata": {
    "colab": {
      "name": "Function_calling.ipynb",
      "toc_visible": true
    },
    "google": {
      "image_path": "/site-assets/images/share.png",
      "keywords": [
        "examples",
        "googleai",
        "samplecode",
        "python",
        "embed",
        "function"
      ]
    },
    "kernelspec": {
      "display_name": "Python 3",
      "name": "python3"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}