quickstarts/Prompting.ipynb

{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "Tce3stUlHN0L"
      },
      "source": [
        "##### Copyright 2025 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": "yeadDkMiISin"
      },
      "source": [
        "# Gemini API: Prompting Quickstart\n",
        "\n",
        "<a target=\"_blank\" href=\"https://colab.research.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Prompting.ipynb\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" height=30/></a>"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "dpOYALec6N8Z"
      },
      "source": [
        "This notebook contains examples of how to write and run your first prompts with the Gemini API."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 1,
      "metadata": {
        "id": "0c13de5f68f6"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "\u001b[?25l   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m0.0/159.7 kB\u001b[0m \u001b[31m?\u001b[0m eta \u001b[36m-:--:--\u001b[0m\r\u001b[2K   \u001b[91m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m\u001b[91m╸\u001b[0m\u001b[90m━\u001b[0m \u001b[32m153.6/159.7 kB\u001b[0m \u001b[31m109.0 MB/s\u001b[0m eta \u001b[36m0:00:01\u001b[0m\r\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m159.7/159.7 kB\u001b[0m \u001b[31m3.9 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25h"
          ]
        }
      ],
      "source": [
        "%pip install -U -q \"google-genai>=1.4.0\" # 1.4.0 is needed for chat history"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "w4YDYyfRYN7L"
      },
      "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](https://github.com/google-gemini/cookbook/blob/main/quickstarts/Authentication.ipynb) quickstart for an example."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 2,
      "metadata": {
        "id": "p8K1RpmMfh20"
      },
      "outputs": [],
      "source": [
        "from google.colab import userdata\n",
        "from google import genai\n",
        "\n",
        "GOOGLE_API_KEY = userdata.get('GOOGLE_API_KEY')\n",
        "client = genai.Client(api_key=GOOGLE_API_KEY)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "zwtL8wmX4rqP"
      },
      "source": [
        "## Select your model\n",
        "\n",
        "Now select the model you want to use in this guide, either by selecting one in the list or writing it down. Keep in mind that some models, like the 2.5 ones are thinking models and thus take slightly more time to respond (cf. [thinking notebook](./Get_started_thinking.ipynb) for more details and in particular learn how to switch the thiking off)."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 3,
      "metadata": {
        "id": "Ll79uwEK4uPJ"
      },
      "outputs": [],
      "source": [
        "MODEL_ID = \"gemini-2.5-flash-preview-04-17\" # @param [\"gemini-2.0-flash-lite\",\"gemini-2.0-flash\",\"gemini-2.5-flash-preview-04-17\",\"gemini-2.5-pro-exp-03-25\"] {\"allow-input\":true, isTemplate: true}"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "HTNQymX8YN9c"
      },
      "source": [
        "## Run your first prompt\n",
        "\n",
        "Use the `generate_content` method to generate responses to your prompts. You can pass text directly to generate_content, and use the `.text` property to get the text content of the response."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 4,
      "metadata": {
        "id": "XSuyaGmcf6sr"
      },
      "outputs": [
        {
          "data": {
            "text/markdown": "Okay, Python provides two primary ways to sort a list:\n\n1.  **`list.sort()`:** This method sorts the list **in-place**. It modifies the original list directly and returns `None`.\n2.  **`sorted(list)`:** This is a built-in function that returns a **new** sorted list. It does **not** modify the original list.\n\nHere are examples of how to use both:\n\n**1. Using `list.sort()` (Sorts In-Place)**\n\n```python\n# Define a list\nmy_list = [3, 1, 4, 1, 5, 9, 2, 6]\n\n# Sort the list in-place (modifies the original list)\nmy_list.sort()\n\n# Print the modified list\nprint(\"Using list.sort():\", my_list)\n\n# Example with strings\nstring_list = [\"banana\", \"apple\", \"cherry\", \"date\"]\nstring_list.sort()\nprint(\"Using list.sort() on strings:\", string_list)\n\n# Example of sorting in descending order\nmy_list_desc = [3, 1, 4, 1, 5, 9, 2, 6]\nmy_list_desc.sort(reverse=True)\nprint(\"Using list.sort() (descending):\", my_list_desc)\n```\n\n**2. Using `sorted(list)` (Returns a New List)**\n\n```python\n# Define a list (original remains unchanged)\nmy_list = [3, 1, 4, 1, 5, 9, 2, 6]\n\n# Get a new sorted list using the sorted() function\nnew_sorted_list = sorted(my_list)\n\n# Print the original list (it's unchanged)\nprint(\"Original list:\", my_list)\n\n# Print the new sorted list\nprint(\"Using sorted():\", new_sorted_list)\n\n# Example with strings\nstring_list = [\"banana\", \"apple\", \"cherry\", \"date\"]\nnew_sorted_string_list = sorted(string_list)\nprint(\"Using sorted() on strings:\", new_sorted_string_list)\nprint(\"Original string list (unchanged):\", string_list) # Show original is unchanged\n\n# Example of sorting in descending order\nmy_list_desc = [3, 1, 4, 1, 5, 9, 2, 6]\nnew_desc_sorted_list = sorted(my_list_desc, reverse=True)\nprint(\"Using sorted() (descending):\", new_desc_sorted_list)\n```\n\n**Key Difference:**\n\n*   Choose `list.sort()` when you don't need the original list and want to save memory by modifying it directly.\n*   Choose `sorted(list)` when you need to keep the original list intact and get a sorted copy.\n\nBoth methods can accept a `key` argument for custom sorting criteria (e.g., sorting a list of strings by their length).",
            "text/plain": [
              "<IPython.core.display.Markdown object>"
            ]
          },
          "metadata": {},
          "output_type": "display_data"
        }
      ],
      "source": [
        "from IPython.display import Markdown\n",
        "\n",
        "response = client.models.generate_content(\n",
        "    model=MODEL_ID,\n",
        "    contents=\"Give me python code to sort a list\"\n",
        ")\n",
        "\n",
        "display(Markdown(response.text))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "0GTyrWHugKFi"
      },
      "source": [
        "## Use images in your prompt\n",
        "\n",
        "Here you will download an image from a URL and pass that image in our prompt.\n",
        "\n",
        "First, you download the image and load it with PIL:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 5,
      "metadata": {
        "id": "JgbFtil0gLNf"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n",
            "                                 Dload  Upload   Total   Spent    Left  Speed\n",
            "\r  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0\r100  349k  100  349k    0     0  2216k      0 --:--:-- --:--:-- --:--:-- 2224k\n"
          ]
        }
      ],
      "source": [
        "!curl -o image.jpg \"https://storage.googleapis.com/generativeai-downloads/images/jetpack.jpg\""
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 6,
      "metadata": {
        "id": "0rcYDbcDga8s"
      },
      "outputs": [
        {
          "data": {
            "text/plain": "Output hidden; open in https://colab.research.google.com to view."
          },
          "metadata": {},
          "output_type": "display_data"
        }
      ],
      "source": [
        "import PIL.Image\n",
        "img = PIL.Image.open('image.jpg')\n",
        "img"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 7,
      "metadata": {
        "id": "UTgRAmEHOaAz"
      },
      "outputs": [],
      "source": [
        "prompt = \"\"\"\n",
        "    This image contains a sketch of a potential product along with some notes.\n",
        "    Given the product sketch, describe the product as thoroughly as possible based on what you\n",
        "   see in the image, making sure to note all of the product features. Return output in json format:\n",
        "   {description: description, features: [feature1, feature2, feature3, etc]}\n",
        "\"\"\""
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "RJyRsfQi0tp6"
      },
      "source": [
        "Then you can include the image in our prompt by just passing a list of items to `generate_content`."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 11,
      "metadata": {
        "id": "Aoil5YiTgbZS"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "```json\n",
            "{\n",
            "  \"description\": \"The Jetpack Backpack is a product designed to resemble a normal backpack while incorporating jetpack capabilities. It features a padded strap support for comfort, a compartment large enough to fit an 18-inch laptop, and retractable boosters located at the bottom. The jetpack is described as lightweight, steam-powered, and environmentally friendly (green/clean). It offers USB-C charging and has a stated battery life of 15 minutes.\",\n",
            "  \"features\": [\n",
            "    \"Fits 18\\\" laptop\",\n",
            "    \"Padded strap support\",\n",
            "    \"Lightweight\",\n",
            "    \"Looks like a normal backpack\",\n",
            "    \"USB-C charging\",\n",
            "    \"15-min battery life\",\n",
            "    \"Retractable boosters\",\n",
            "    \"Steam-powered\",\n",
            "    \"Green/clean (environmentally friendly)\"\n",
            "  ]\n",
            "}\n",
            "```\n"
          ]
        }
      ],
      "source": [
        "response = client.models.generate_content(\n",
        "    model=MODEL_ID,\n",
        "    contents=[prompt, img],\n",
        ")\n",
        "\n",
        "print(response.text)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "XE-6e7gePN7Q"
      },
      "source": [
        "## Have a chat\n",
        "\n",
        "The Gemini API enables you to have freeform conversations across multiple turns.\n",
        "\n",
        "The [ChatSession](https://ai.google.dev/api/python/google/generativeai/ChatSession) class will store the conversation history for multi-turn interactions."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 12,
      "metadata": {
        "id": "ZKAtY5oIPQW0"
      },
      "outputs": [],
      "source": [
        "chat = client.chats.create(model=MODEL_ID)"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 13,
      "metadata": {
        "id": "9tXNVnqxPcXy"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "A computer is like a super-fast helper that follows tiny instructions to show you pictures, play games, and help you do things.\n"
          ]
        }
      ],
      "source": [
        "response = chat.send_message(\n",
        "    message=\"In one sentence, explain how a computer works to a young child.\"\n",
        ")\n",
        "\n",
        "print(response.text)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "7TChH2l5PhFf"
      },
      "source": [
        "You can see the chat history:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 14,
      "metadata": {
        "id": "dHwrC82YPiWS"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "user: In one sentence, explain how a computer works to a young child.\n",
            "model: A computer is like a super-fast helper that follows tiny instructions to show you pictures, play games, and help you do things.\n"
          ]
        }
      ],
      "source": [
        "messages = chat.get_history()\n",
        "for message in messages:\n",
        "  print(f\"{message.role}: {message.parts[0].text}\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "EvHvt1OEPl7D"
      },
      "source": [
        "You can keep sending messages to continue the conversation:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 17,
      "metadata": {
        "id": "-fXZZQPzPkie"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "Okay, for a high schooler:\n",
            "\n",
            "A computer works by taking input data (from your keyboard, mouse, etc.), processing it at incredibly high speeds using its central processing unit (CPU) based on detailed step-by-step instructions from programs (software) held temporarily in fast memory (RAM), and then producing output (like showing things on your screen or saving files to storage) according to those instructions.\n"
          ]
        }
      ],
      "source": [
        "response = chat.send_message(\"Okay, how about a more detailed explanation to a high schooler?\")\n",
        "\n",
        "print(response.text)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "65476e75ece0"
      },
      "source": [
        "## Set the temperature"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "56f68c900144"
      },
      "source": [
        "Every prompt you send to the model includes parameters that control how the model generates responses. Use a `types.GenerateContentConfig` to set these, or omit it to use the defaults.\n",
        "\n",
        "Temperature controls the degree of randomness in token selection. Use higher values for more creative responses, and lower values for more deterministic responses."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "e3c68071ed8b"
      },
      "source": [
        "Note: Although you can set the `candidate_count` in the generation_config, 2.0 and later models will only return a single candidate at the this time."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 22,
      "metadata": {
        "id": "c97c16e6a961"
      },
      "outputs": [
        {
          "data": {
            "text/markdown": "Okay, here's a list of fascinating cat facts:\n\n1.  **Cats sleep a lot:** On average, cats sleep for 12-16 hours a day.\n\n2.  **Unique nose prints:** Like human fingerprints, a cat's nose has a unique pattern of ridges and bumps.\n\n3.  **Whiskers are multi-functional:** Whiskers are not just cute; they help cats navigate in the dark, sense changes in air currents, and even gauge the width of openings.\n\n4.  **Purring is complex:** While cats often purr when content, they can also purr when stressed, injured, or giving birth as a form of self-soothing. The frequency (25-150 Hertz) can promote healing.\n\n5.  **Excellent jumpers:** Cats can jump up to six times their height thanks to their strong leg muscles and flexible spine.\n",
            "text/plain": [
              "<IPython.core.display.Markdown object>"
            ]
          },
          "metadata": {},
          "output_type": "display_data"
        }
      ],
      "source": [
        "from google.genai import types\n",
        "\n",
        "response = client.models.generate_content(\n",
        "    model=MODEL_ID,\n",
        "    contents='Give me a numbered list of cat facts.',\n",
        "    config=types.GenerateContentConfig(\n",
        "        max_output_tokens=2000,\n",
        "        temperature=1.9,\n",
        "        stop_sequences=['\\n6'] # Limit to 5 facts.\n",
        "    )\n",
        ")\n",
        "\n",
        "display(Markdown(response.text))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "gvkDhXtHgol7"
      },
      "source": [
        "## Learn more\n",
        "\n",
        "There's lots more to learn!\n",
        "\n",
        "* For more fun prompts, check out [Market a Jetpack](https://github.com/google-gemini/cookbook/blob/main/examples/Market_a_Jet_Backpack.ipynb).\n",
        "* Check out the [safety quickstart](https://github.com/google-gemini/cookbook/blob/main/quickstarts/Safety.ipynb) next to learn about the Gemini API's configurable safety settings, and what to do if your prompt is blocked.\n",
        "* For lots more details on using the Python SDK, check out the [get started notebook](./Get_started.ipynb) or the [documentation's quickstart](https://ai.google.dev/tutorials/python_quickstart)."
      ]
    }
  ],
  "metadata": {
    "colab": {
      "name": "Prompting.ipynb",
      "toc_visible": true
    },
    "google": {
      "image_path": "/static/site-assets/images/docs/logo-python.svg",
      "keywords": [
        "examples",
        "gemini",
        "beginner",
        "googleai",
        "quickstart",
        "python",
        "text",
        "chat",
        "vision",
        "embed"
      ]
    },
    "kernelspec": {
      "display_name": "Python 3",
      "name": "python3"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}