diff --git a/examples/README.md b/examples/README.md
index c70265c13..1c206bdba 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -23,6 +23,7 @@ This is a collection of fun examples for the Gemini API.
* [Translate a public domain](https://github.com/google-gemini/cookbook/blob/main/examples/Translate_a_Public_Domain_Book.ipynb): In this notebook, you will explore Gemini model as a translation tool, demonstrating how to prepare data, create effective prompts, and save results into a `.txt` file.
* [Working with Charts, Graphs, and Slide Decks](https://github.com/google-gemini/cookbook/blob/main/examples/Working_with_Charts_Graphs_and_Slide_Decks.ipynb): Gemini models are powerful multimodal LLMs that can process both text and image inputs. This notebook shows how Gemini 1.5 Flash model is capable of extracting data from various images.
* [Entity extraction](https://github.com/google-gemini/cookbook/blob/main/examples/Entity_Extraction.ipynb): Use Gemini API to speed up some of your tasks, such as searching through text to extract needed information. Entity extraction with a Gemini model is a simple query, and you can ask it to retrieve its answer in the form that you prefer.
+* [Generate a company research report using search grounding](https://github.com/google-gemini/cookbook/blob/main/examples/search_grounding_for_research_report.ipynb): Use search grounding to write a company research report with Gemini 1.5 Flash.
### Integrations
diff --git a/examples/search_grounding_for_research_report.ipynb b/examples/search_grounding_for_research_report.ipynb
new file mode 100644
index 000000000..368b124c4
--- /dev/null
+++ b/examples/search_grounding_for_research_report.ipynb
@@ -0,0 +1,1163 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "lb5yiH5h8x3h"
+ },
+ "source": [
+ "##### Copyright 2024 Google LLC."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "metadata": {
+ "id": "906e07f6e562"
+ },
+ "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": "1YXR7Yn480fU"
+ },
+ "source": [
+ "# Search grouding with Gemini 1.5"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "CeJyB7rG82ph"
+ },
+ "source": [
+ "
"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "___eV40o8399"
+ },
+ "source": [
+ "In this tutorial you are going to leverage the grounding with Google Search capability of the Gemini 1.5 model to write a company report.\n",
+ "\n",
+ "You may be asking, why does one need to use the search tool for this purpose? Well, as you may be aware, today's business world evolves very fast and LLMs generally are not trained frequently enough to capture the latest updates. Luckily Google search comes to the rescue. Google search is built to provide accurate and nearly realtime information and can help us fulfill this task nicely.\n",
+ "\n",
+ "Note that the latest [search tool](https://github.com/google-gemini/cookbook/blob/main/gemini-2/search_tool.ipynb) that comes with Gemini 2.0 is much easier to use and should be prioritized over search grounding in Gemini 1.5 models."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "## Setup"
+ ],
+ "metadata": {
+ "id": "Mfk6YY3G5kqp"
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "d5027929de8f"
+ },
+ "source": [
+ "### Install SDK\n",
+ "\n",
+ "The new **[Google Gen AI SDK](https://ai.google.dev/gemini-api/docs/sdks)** provides programmatic access to Gemini 2.0 (and previous models) using both the [Google AI for Developers](https://ai.google.dev/gemini-api/docs) and [Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/docs/overview) APIs. With a few exceptions, code that runs on one platform will run on both. This means that you can prototype an application using the Developer API and then migrate the application to Vertex AI without rewriting your code.\n",
+ "\n",
+ "More details about this new SDK on the [documentation](https://ai.google.dev/gemini-api/docs/sdks) or in the [Getting started](../gemini-2/get_started.ipynb) notebook."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "metadata": {
+ "id": "46zEFO2a9FFd"
+ },
+ "outputs": [],
+ "source": [
+ "!pip install -U -q google-genai"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "CTIfnvCn9HvH"
+ },
+ "source": [
+ "### Setup 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 [Authentication](../quickstarts/Authentication.ipynb) for an example."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 3,
+ "metadata": {
+ "id": "A1pkoyZb9Jm3"
+ },
+ "outputs": [],
+ "source": [
+ "from google.colab import userdata\n",
+ "\n",
+ "GOOGLE_API_KEY=userdata.get('GOOGLE_API_KEY')"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "### Import the libraries"
+ ],
+ "metadata": {
+ "id": "QclzsisW0nTK"
+ }
+ },
+ {
+ "cell_type": "code",
+ "source": [
+ "from google import genai\n",
+ "import json\n",
+ "from IPython.display import display, HTML, Markdown"
+ ],
+ "metadata": {
+ "id": "cXNAAIqOuXlO"
+ },
+ "execution_count": 4,
+ "outputs": []
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "### Initialize SDK client\n",
+ "\n",
+ "With the new SDK you now only need to initialize a client with you API key (or OAuth if using [Vertex AI](https://link_to_vertex_AI)). The model is now set in each call."
+ ],
+ "metadata": {
+ "id": "3Hx_Gw9i0Yuv"
+ }
+ },
+ {
+ "cell_type": "code",
+ "source": [
+ "client = genai.Client(api_key=GOOGLE_API_KEY)"
+ ],
+ "metadata": {
+ "id": "HghvVpbU0Uap"
+ },
+ "execution_count": 5,
+ "outputs": []
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "QOov6dpG99rY"
+ },
+ "source": [
+ "### Select a model\n",
+ "\n",
+ "Search tool is a new feature in the Gemini 2.0 model that automatically retrieves accurate and grounded artifacts from the web for developers to further process. Unlike the search grounding in the Gemini 1.5 models, you do not need to set the dynamic retrieval threshold.\n",
+ "\n",
+ "For more information about all Gemini models, check the [documentation](https://ai.google.dev/gemini-api/docs/models/gemini) for extended information on each of them.\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "source": [
+ "MODEL = \"gemini-1.5-flash\""
+ ],
+ "metadata": {
+ "id": "27Fikag0xSaB"
+ },
+ "execution_count": 6,
+ "outputs": []
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "## Write the report with Gemini 1.5 Flash"
+ ],
+ "metadata": {
+ "id": "F9lFY3h6unY2"
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "### Select a target company to research\n",
+ "\n",
+ "Next you will use Alphabet as an example research target."
+ ],
+ "metadata": {
+ "id": "j562CvvWvASd"
+ }
+ },
+ {
+ "cell_type": "code",
+ "source": [
+ "COMPANY = 'Alphabet'"
+ ],
+ "metadata": {
+ "id": "7UQxJr7UvEhl"
+ },
+ "execution_count": 7,
+ "outputs": []
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "### Plan for searches\n",
+ "You use the Gemini model to plan for 5 key queries to send to Google search to get the latest updates on the company. You can of course use as many queries as you want."
+ ],
+ "metadata": {
+ "id": "ICzjeVfcvIV0"
+ }
+ },
+ {
+ "cell_type": "code",
+ "source": [
+ "from google import genai\n",
+ "from google.genai.types import GenerateContentConfig\n",
+ "\n",
+ "result = client.models.generate_content(\n",
+ " model=MODEL,\n",
+ " contents=[f\"\"\"You are an analyst that conducts comprehensive company research.\n",
+ " You rely heavily on Google search for the latest company news, updates and metrics to write research reports.\n",
+ " For {COMPANY}, please generate a list of 5 key queries you'd like to send to Google to get accurate answers before you write the report.\n",
+ " Return queries only; no other information needed.\"\"\"],\n",
+ " config=GenerateContentConfig(\n",
+ " response_mime_type='application/json',\n",
+ " )\n",
+ ")"
+ ],
+ "metadata": {
+ "id": "bBQ6vEknvJwN"
+ },
+ "execution_count": 8,
+ "outputs": []
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "Here are the 5 queries to be used."
+ ],
+ "metadata": {
+ "id": "ukbRHPX2vOLu"
+ }
+ },
+ {
+ "cell_type": "code",
+ "source": [
+ "search_queries = json.loads(result.candidates[0].content.parts[0].text)['queries']\n",
+ "print(search_queries)"
+ ],
+ "metadata": {
+ "colab": {
+ "base_uri": "https://localhost:8080/"
+ },
+ "id": "-Xde2FASvaUg",
+ "outputId": "609577f7-2347-4b91-90ed-4c38d47e51e3"
+ },
+ "execution_count": 9,
+ "outputs": [
+ {
+ "output_type": "stream",
+ "name": "stdout",
+ "text": [
+ "['Alphabet Inc. latest quarterly earnings report', 'Alphabet Inc. stock price and performance analysis', \"Recent news and updates on Alphabet Inc.'s AI initiatives\", 'Competitive landscape analysis for Alphabet Inc. in the search engine market', \"Alphabet Inc.'s recent investments and acquisitions\"]\n"
+ ]
+ }
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "### Send queries to Google search and save the results"
+ ],
+ "metadata": {
+ "id": "Fhpqir-Zv07P"
+ }
+ },
+ {
+ "cell_type": "code",
+ "source": [
+ "chat = client.chats.create(model=MODEL, config={'tools': [{'google_search_retrieval': {}}]})\n",
+ "\n",
+ "query_answer = {}\n",
+ "search_suggestions = []\n",
+ "for query in search_queries:\n",
+ " print(f'Searhing for query: {query}')\n",
+ " r = chat.send_message(query)\n",
+ " all_parts = []\n",
+ " for part in r.candidates[0].content.parts:\n",
+ " all_parts.extend([v for k, v in part.model_dump().items() if v is not None])\n",
+ " query_answer[query] = all_parts\n",
+ " grounding_metadata = r.candidates[0].grounding_metadata\n",
+ " if grounding_metadata and grounding_metadata.search_entry_point:\n",
+ " search_suggestions.append(grounding_metadata.search_entry_point.rendered_content)"
+ ],
+ "metadata": {
+ "colab": {
+ "base_uri": "https://localhost:8080/"
+ },
+ "id": "JNTIYMsgv5u6",
+ "outputId": "98ed1ec1-51fe-4437-bf1c-3351e0588d15"
+ },
+ "execution_count": 10,
+ "outputs": [
+ {
+ "output_type": "stream",
+ "name": "stdout",
+ "text": [
+ "Searhing for query: Alphabet Inc. latest quarterly earnings report\n",
+ "Searhing for query: Alphabet Inc. stock price and performance analysis\n",
+ "Searhing for query: Recent news and updates on Alphabet Inc.'s AI initiatives\n",
+ "Searhing for query: Competitive landscape analysis for Alphabet Inc. in the search engine market\n",
+ "Searhing for query: Alphabet Inc.'s recent investments and acquisitions\n"
+ ]
+ }
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "### Generate the final report\n",
+ "\n",
+ "Next you define a couple of helper functions to better display the final report."
+ ],
+ "metadata": {
+ "id": "tI0bRGLtv9Mr"
+ }
+ },
+ {
+ "cell_type": "code",
+ "source": [
+ "def show_json(obj):\n",
+ " print(json.dumps(obj.model_dump(exclude_none=True), indent=2))\n",
+ "\n",
+ "def show_report(r, search_suggestions = []):\n",
+ " parts = r.candidates[0].content.parts\n",
+ " if parts is None:\n",
+ " finish_reason = r.candidates[0].finish_reason\n",
+ " print(f'{finish_reason=}')\n",
+ " return\n",
+ " for part in r.candidates[0].content.parts:\n",
+ " if part.text:\n",
+ " display(Markdown(part.text.replace('$', r'\\$'))) # Escape $ signs for better MD rendering\n",
+ " elif part.executable_code:\n",
+ " display(Markdown(f'```python\\n{part.executable_code.code}\\n```'))\n",
+ " else:\n",
+ " show_json(part)\n",
+ "\n",
+ " if len(search_suggestions) > 0:\n",
+ " for s in search_suggestions:\n",
+ " display(HTML(s))"
+ ],
+ "metadata": {
+ "id": "-fx7090PwF_u"
+ },
+ "execution_count": 11,
+ "outputs": []
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "Now you can ask the Gemini model to put together the final research report based on all the previous search results."
+ ],
+ "metadata": {
+ "id": "NqupplULwI0Z"
+ }
+ },
+ {
+ "cell_type": "code",
+ "source": [
+ "final_report = client.models.generate_content(\n",
+ " model=MODEL,\n",
+ " contents=[f\"\"\"You are an analyst that conducts company research.\n",
+ " You are working on a company report on {COMPANY} and have gathered the following comprehensive information based on various Google searches.\n",
+ "\n",
+ " {json.dumps(query_answer)}\n",
+ "\n",
+ " Based on all these information, please write a concise company report.\"\"\"],\n",
+ ")"
+ ],
+ "metadata": {
+ "id": "bO9EuDCswJhN"
+ },
+ "execution_count": 12,
+ "outputs": []
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "Display the final report."
+ ],
+ "metadata": {
+ "id": "aE7oNvkcwLyu"
+ }
+ },
+ {
+ "cell_type": "code",
+ "source": [
+ "show_report(final_report, search_suggestions)"
+ ],
+ "metadata": {
+ "colab": {
+ "base_uri": "https://localhost:8080/",
+ "height": 908
+ },
+ "id": "AkBUXPUawONA",
+ "outputId": "71e64708-ebc5-4d65-96a1-31a47ca04946"
+ },
+ "execution_count": 13,
+ "outputs": [
+ {
+ "output_type": "display_data",
+ "data": {
+ "text/plain": [
+ ""
+ ],
+ "text/markdown": "**Alphabet Inc. Company Report - December 17, 2024**\n\n**Executive Summary:** Alphabet Inc. (GOOGL) delivered record Q3 2024 earnings, exceeding analyst expectations across revenue (\\$88.3B) and profit (\\$26.3B), driven by strong performance in Search, Cloud, and YouTube. The launch of Gemini 2.0 and its integration across products significantly contributed to growth. While the stock price surged post-earnings, it remains below its 52-week high, reflecting previous volatility and concerns around antitrust investigations and substantial AI investments. Analyst sentiment is positive, with a consensus \"Strong Buy\" rating and a 12-month price target of \\$206.95. However, longer-term performance shows a slight decline, highlighting the dynamic competitive landscape.\n\n\n**Financial Performance:**\n\n* Q3 2024: Record revenue and profit exceeding analyst projections. Strong advertising revenue growth.\n* Stock Price: Recent gains following strong Q3 results, but mixed performance over the past year; currently trading around \\$195-\\$198, with variations across sources.\n\n**Key Strategic Initiatives:**\n\n* **AI Leadership:** Aggressive expansion of AI capabilities with Gemini 2.0, impacting various Google products and attracting partnerships (e.g., Malaysian government). AI is used internally for approximately 25% of new software development.\n* **Acquisitions and Investments:** A mixed approach, involving both significant (Mandiant, potential Wiz acquisition) and smaller strategic acquisitions across cybersecurity, AI, and other sectors. Focus on strengthening existing businesses and expanding into new markets. The failed HubSpot acquisition highlights the risks associated with large-scale deals.\n\n\n**Competitive Landscape:**\n\n* **Dominant Market Share:** Google Search maintains over 90% market share.\n* **Intense Competition:** Faces competition from Microsoft (Bing), smaller search engines, vertical search engines, and emerging AI companies.\n* **Competitive Pressures:** Market share battles, technological innovation (especially AI), regulatory scrutiny, and advertising revenue dependence are key challenges.\n\n\n**Risks and Uncertainties:**\n\n* **Antitrust concerns and regulatory pressures:** Potential impact on market dominance and business practices.\n* **Heavy AI investment:** While promising, the substantial investment in AI carries inherent risks and uncertainties regarding future profitability.\n* **Competition:** Maintaining market dominance in a rapidly evolving technological landscape.\n\n\n**Outlook:**\n\nAlphabet's strong Q3 performance and significant AI investments position it for continued growth. However, navigating the competitive landscape and addressing regulatory concerns will be crucial. The potential acquisition of Wiz could be a significant milestone. Analyst sentiment remains positive, predicting further stock price appreciation, although the recent past suggests some volatility is to be expected. Further monitoring of market conditions and the evolution of the AI landscape is essential.\n"
+ },
+ "metadata": {}
+ },
+ {
+ "output_type": "display_data",
+ "data": {
+ "text/plain": [
+ ""
+ ],
+ "text/html": [
+ "\n",
+ "
\n"
+ ]
+ },
+ "metadata": {}
+ }
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "As you can see, the Gemini 1.5 model is able to write an accurate and well-structured research report for us. All the information in the report is factual and up-to-date.\n",
+ "\n",
+ "Note that although Gemini 1.5 Flash is able to finish this task, it still requires 3 manual steps. With Gemini 2.0, you can accomplish the same with one API call. Please check out our search tool for research tool tutorial for details."
+ ],
+ "metadata": {
+ "id": "leOZmicAwTSn"
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "4677dd58e9b5"
+ },
+ "source": [
+ "## Next Steps\n",
+ "### Useful API references:\n",
+ "\n",
+ "* [Grounding with Google Search](https://ai.google.dev/gemini-api/docs/grounding?lang=python)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "source": [],
+ "metadata": {
+ "id": "-JFOffULgVmj"
+ },
+ "execution_count": 13,
+ "outputs": []
+ }
+ ],
+ "metadata": {
+ "colab": {
+ "provenance": []
+ },
+ "kernelspec": {
+ "display_name": "Python 3",
+ "name": "python3"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 0
+}
\ No newline at end of file
![](\"https://www.tensorflow.org/images/colab_logo_32px.png\"){kind=logo}
Run in Google Colab\n",
+ "