quickstarts/rest/Function_calling_config_REST.ipynb

{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "Tce3stUlHN0L"
      },
      "source": [
        "##### Copyright 2024 Google LLC."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "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": "Jfj-4AdKHjJI"
      },
      "source": [
        "# Gemini API: Function calling config with REST\n",
        "\n",
        "<table align=\"left\">\n",
        "  <td>\n",
        "    <a target=\"_blank\" href=\"https://colab.research.google.com/github/google-gemini/cookbook/blob/main/quickstarts/rest/Function_calling_config_REST.ipynb\"><img src=\"https://www.tensorflow.org/images/colab_logo_32px.png\" />Run in Google Colab</a>\n",
        "  </td>\n",
        "</table>"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "tV_jXDT0IrfK"
      },
      "source": [
        "Specifying a `function_calling_config` allows you to control how the Gemini API acts when `tools` have been specified. For example, you can choose to only allow free-text output (disabling function calling), force it to choose from a subset of the functions provided in `tools`, or let it act automatically.\n",
        "\n",
        "This guide assumes you are already familiar with function calling. For an introduction, check out the [Function calling with REST](./Function_calling_REST.ipynb) recipe."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "CYi9bLkjI8NJ"
      },
      "source": [
        "This notebook provides quick code examples that show you how to get started with function calling using `curl`.\n",
        "\n",
        "You can run this in Google Colab, or you can copy/paste the `curl` commands into your terminal.\n",
        "\n",
        "To run this notebook, your API key must be stored it in a Colab Secret named `GOOGLE_API_KEY`. If you are running in a different environment, you can store your key in an environment variable. See [Authentication](https://github.com/google-gemini/cookbook/blob/main/quickstarts/Authentication.ipynb) to learn more."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "M0O2o_tMHeo8"
      },
      "outputs": [],
      "source": [
        "import os\n",
        "from google.colab import userdata\n",
        "\n",
        "os.environ['GOOGLE_API_KEY'] = userdata.get('GOOGLE_API_KEY')"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "G2d8-T2dOpMu"
      },
      "source": [
        "## Set up a model with tools\n",
        "\n",
        "This example provides the model with some functions that control a hypothetical lighting system. Using these functions requires them to be called in a specific order. For example, you must turn the light system on before you can change the color.\n",
        "\n",
        "While you can pass these directly to the model and let it try to call them correctly, specifying the `function_calling_config` gives you precise control over the functions that are available to the model.\n",
        "\n",
        "Write the tools to `tools.json` so that you can reference it in later steps."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "SS_h6C3MfH48"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "Overwriting tools.json\n"
          ]
        }
      ],
      "source": [
        "%%file tools.json\n",
        "{\n",
        "  \"function_declarations\": [\n",
        "    {\n",
        "      \"name\": \"enable_lights\",\n",
        "      \"description\": \"Turn on the lighting system.\",\n",
        "      \"parameters\": { \"type\": \"object\" }\n",
        "    },\n",
        "    {\n",
        "      \"name\": \"set_light_color\",\n",
        "      \"description\": \"Set the light color. Lights must be enabled for this to work.\",\n",
        "      \"parameters\": {\n",
        "        \"type\": \"object\",\n",
        "        \"properties\": {\n",
        "          \"rgb_hex\": {\n",
        "            \"type\": \"string\",\n",
        "            \"description\": \"The light color as a 6-digit hex string, e.g. ff0000 for red.\"\n",
        "          }\n",
        "        },\n",
        "        \"required\": [\n",
        "          \"rgb_hex\"\n",
        "        ]\n",
        "      }\n",
        "    },\n",
        "    {\n",
        "      \"name\": \"stop_lights\",\n",
        "      \"description\": \"Turn off the lighting system.\",\n",
        "      \"parameters\": { \"type\": \"object\" }\n",
        "    }\n",
        "  ]\n",
        "}"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "k6eYRyKUlw2S"
      },
      "source": [
        "## Text-only mode: `NONE`\n",
        "\n",
        "If you have provided the model with tools, but do not want to use those tools for the current conversational turn, then specify `NONE` as the mode. `NONE` tells the model not to make any function calls, and it will behave as though none have been provided.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "u1MWQ82Phsav"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "      \"content\": {\n",
            "        \"parts\": [\n",
            "          {\n",
            "            \"text\": \"As your lighting system, I can turn the lights on and off, and I can set the color of the lights. \\n\"\n",
            "          }\n",
            "        ],\n",
            "        \"role\": \"model\"\n",
            "      },\n",
            "      \"finishReason\": \"STOP\",\n"
          ]
        }
      ],
      "source": [
        "%%bash\n",
        "curl \"https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-pro-latest:generateContent?key=$GOOGLE_API_KEY\" \\\n",
        "  -H 'Content-Type: application/json' \\\n",
        "  -d @<(echo '\n",
        "  {\n",
        "    \"system_instruction\": {\n",
        "      \"parts\": {\n",
        "        \"text\": \"You are a helpful lighting system bot. You can turn lights on and off, and you can set the color. Do not perform any other tasks.\"\n",
        "      }\n",
        "    },\n",
        "    \"tools\": [' $(cat tools.json) '],\n",
        "\n",
        "    \"tool_config\": {\n",
        "      \"function_calling_config\": {\"mode\": \"none\"}\n",
        "    },\n",
        "\n",
        "    \"contents\": {\n",
        "      \"role\": \"user\",\n",
        "      \"parts\": {\n",
        "        \"text\": \"What can you do?\"\n",
        "      }\n",
        "    }\n",
        "  }\n",
        "') 2>/dev/null |sed -n '/\"content\"/,/\"finishReason\"/p'"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "BaAie9Sjnd4u"
      },
      "source": [
        "## Automatic mode: `AUTO`\n",
        "\n",
        "To allow the model to decide whether to respond in text or call specific functions, you can specify `AUTO` as the mode."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "tqHz3Gd8neSd"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "      \"content\": {\n",
            "        \"parts\": [\n",
            "          {\n",
            "            \"functionCall\": {\n",
            "              \"name\": \"enable_lights\",\n",
            "              \"args\": {}\n",
            "            }\n",
            "          }\n",
            "        ],\n",
            "        \"role\": \"model\"\n",
            "      },\n",
            "      \"finishReason\": \"STOP\",\n"
          ]
        }
      ],
      "source": [
        "%%bash\n",
        "curl \"https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-pro-latest:generateContent?key=$GOOGLE_API_KEY\" \\\n",
        "  -H 'Content-Type: application/json' \\\n",
        "  -d @<(echo '\n",
        "  {\n",
        "    \"system_instruction\": {\n",
        "      \"parts\": {\n",
        "        \"text\": \"You are a helpful lighting system bot. You can turn lights on and off, and you can set the color. Do not perform any other tasks.\"\n",
        "      }\n",
        "    },\n",
        "    \"tools\": [' $(cat tools.json) '],\n",
        "\n",
        "    \"tool_config\": {\n",
        "      \"function_calling_config\": {\"mode\": \"auto\"}\n",
        "    },\n",
        "\n",
        "    \"contents\": {\n",
        "      \"role\": \"user\",\n",
        "      \"parts\": {\n",
        "        \"text\": \"Light this place up!\"\n",
        "      }\n",
        "    }\n",
        "  }\n",
        "') 2>/dev/null |sed -n '/\"content\"/,/\"finishReason\"/p'"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "EYE8-BDepHJn"
      },
      "source": [
        "## Function-calling mode: `ANY`\n",
        "\n",
        "Setting the mode to `ANY` will force the model to make a function call. By setting `allowed_function_names`, the model will only choose from those functions. If it is not set, all of the functions in `tools` are candidates for function calling.\n",
        "\n",
        "In this example system, if the lights are already on, then the user can change color or turn the lights off.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "J2vaxGdYpPGt"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "      \"content\": {\n",
            "        \"parts\": [\n",
            "          {\n",
            "            \"functionCall\": {\n",
            "              \"name\": \"set_light_color\",\n",
            "              \"args\": {\n",
            "                \"rgb_hex\": \"9400d3\"\n",
            "              }\n",
            "            }\n",
            "          }\n",
            "        ],\n",
            "        \"role\": \"model\"\n",
            "      },\n",
            "      \"finishReason\": \"STOP\",\n"
          ]
        }
      ],
      "source": [
        "%%bash\n",
        "curl \"https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-pro-latest:generateContent?key=$GOOGLE_API_KEY\" \\\n",
        "  -H 'Content-Type: application/json' \\\n",
        "  -d @<(echo '\n",
        "  {\n",
        "    \"system_instruction\": {\n",
        "      \"parts\": {\n",
        "        \"text\": \"You are a helpful lighting system bot. You can turn lights on and off, and you can set the color. Do not perform any other tasks.\"\n",
        "      }\n",
        "    },\n",
        "    \"tools\": [' $(cat tools.json) '],\n",
        "\n",
        "    \"tool_config\": {\n",
        "      \"function_calling_config\": {\n",
        "        \"mode\": \"any\",\n",
        "        \"allowed_function_names\": [\"set_light_color\", \"stop_lights\"]\n",
        "      }\n",
        "    },\n",
        "\n",
        "    \"contents\": {\n",
        "      \"role\": \"user\",\n",
        "      \"parts\": {\n",
        "        \"text\": \"Make this place PURPLE!\"\n",
        "      }\n",
        "    }\n",
        "  }\n",
        "') 2>/dev/null |sed -n '/\"content\"/,/\"finishReason\"/p'"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "WbXzyFVTqYwn"
      },
      "source": [
        "## Further reading\n",
        "\n",
        "Check out the [function calling recipe](./Function_calling_REST.ipynb) for more on function calling."
      ]
    }
  ],
  "metadata": {
    "colab": {
      "name": "Function_calling_config_REST.ipynb",
      "toc_visible": true
    },
    "kernelspec": {
      "display_name": "Python 3",
      "name": "python3"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}