[Docs] colab notebook for chart

vizro-ai/README.md

@@ -19,6 +19,12 @@ It serves as an extension to Vizro, leveraging natural language capabilities to
 
 </div>
 
+## Try out live
+
+| Platform     | Chart creation                                                                                                                                                                            |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Google Colab | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/mckinsey/vizro/blob/main/vizro-ai/examples/chart_by_vizro_ai.ipynb) |
+
 ## Why Vizro-AI?
 
 ### Easy-to-use

vizro-ai/changelog.d/20240807_005926_lingyi_zhang_add_colab_link.md

@@ -0,0 +1,47 @@
+<!--
+A new scriv changelog fragment.
+
+Uncomment the section that is right (remove the HTML comment wrapper).
+-->
+
+<!--
+### Highlights ✨
+
+- A bullet item for the Highlights ✨ category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Removed
+
+- A bullet item for the Removed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+
+### Added
+
+- Add Google Colab notebook for users to experiment with `VizroAI.plot` method without local setup ([#618](https://github.com/mckinsey/vizro/pull/618))
+
+<!--
+### Changed
+
+- A bullet item for the Changed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Deprecated
+
+- A bullet item for the Deprecated category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Fixed
+
+- A bullet item for the Fixed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Security
+
+- A bullet item for the Security category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->

vizro-ai/examples/chart_by_vizro_ai.ipynb

@@ -0,0 +1,331 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "id": "b72a43eb-2991-45da-844a-a88c1b9b6f1e",
+      "metadata": {
+        "id": "b72a43eb-2991-45da-844a-a88c1b9b6f1e"
+      },
+      "source": [
+        "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/mckinsey/vizro/blob/main/vizro-ai/examples/chart_by_vizro_ai.ipynb)"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 12,
+      "id": "I6KPM-CnY_ag",
+      "metadata": {
+        "cellView": "form",
+        "colab": {
+          "base_uri": "https://localhost:8080/",
+          "height": 352
+        },
+        "id": "I6KPM-CnY_ag",
+        "outputId": "f138818d-28b4-47ea-b9c0-ed5c6c70eff5"
+      },
+      "outputs": [
+        {
+          "data": {
+            "text/html": [
+              "<style>\n",
+              "  .cell-bg {\n",
+              "    background-color: #E6F3FF;\n",
+              "    padding: 10px;\n",
+              "    width: 100%;\n",
+              "  }\n",
+              "  .disclaimer {\n",
+              "    background-color: #ffffff;\n",
+              "    border: 1px solid #ddd;\n",
+              "    border-radius: 5px;\n",
+              "    padding: 15px;\n",
+              "    margin: 10px 0;\n",
+              "    font-family: Arial, sans-serif;\n",
+              "  }\n",
+              "  .disclaimer h3 {\n",
+              "    margin-top: 0;\n",
+              "  }\n",
+              "  .disclaimer ol {\n",
+              "    padding-left: 20px;\n",
+              "  }\n",
+              "  .disclaimer li {\n",
+              "    margin-bottom: 10px;\n",
+              "  }\n",
+              "  .disclaimer p {\n",
+              "    font-weight: bold;\n",
+              "    margin-bottom: 0;\n",
+              "  }\n",
+              "</style>\n",
+              "\n",
+              "<div class=\"cell-bg\">\n",
+              "  <div class=\"disclaimer\">\n",
+              "    <h3>Disclaimer: Using Google Colab</h3>\n",
+              "    <p>Please read carefully before proceeding:</p>\n",
+              "    <ol>\n",
+              "      <li><strong>Google's Servers:</strong> This notebook runs on Google's servers. Your code and data will be processed and temporarily stored on Google's infrastructure.</li>\n",
+              "      <li><strong>Data Privacy:</strong> Be mindful of the data you upload or process here. Avoid using sensitive, confidential, or personal information that shouldn't be shared with third parties.</li>\n",
+              "      <li><strong>Security Considerations:</strong> Colab is a shared environment. While Google implements security measures, treat it as a public environment and act accordingly.</li>\n",
+              "      <li><strong>Terms of Service:</strong> Ensure your usage complies with Google Colab's Terms of Service and Google Cloud's Terms of Service.</li>\n",
+              "      <li><strong>Data Persistence:</strong> Data in Colab notebooks is not permanently stored. Save important data and results to your local machine or a secure cloud storage.</li>\n",
+              "      <li><strong>Resource Limitations:</strong> Colab provides free resources, but these are subject to availability and usage limits.</li>\n",
+              "    </ol>\n",
+              "    <p>By using this Colab notebook, you acknowledge that you understand and accept these conditions. Please use Colab at your own discretion and responsibility.</p>\n",
+              "  </div>\n",
+              "</div>\n"
+            ],
+            "text/plain": [
+              "<IPython.core.display.HTML object>"
+            ]
+          },
+          "metadata": {},
+          "output_type": "display_data"
+        }
+      ],
+      "source": [
+        "# @title\n",
+        "%%html\n",
+        "<style>\n",
+        "  .cell-bg {\n",
+        "    background-color: #E6F3FF;\n",
+        "    padding: 10px;\n",
+        "    width: 100%;\n",
+        "  }\n",
+        "  .disclaimer {\n",
+        "    background-color: #ffffff;\n",
+        "    border: 1px solid #ddd;\n",
+        "    border-radius: 5px;\n",
+        "    padding: 15px;\n",
+        "    margin: 10px 0;\n",
+        "    font-family: Arial, sans-serif;\n",
+        "  }\n",
+        "  .disclaimer h3 {\n",
+        "    margin-top: 0;\n",
+        "  }\n",
+        "  .disclaimer ol {\n",
+        "    padding-left: 20px;\n",
+        "  }\n",
+        "  .disclaimer li {\n",
+        "    margin-bottom: 10px;\n",
+        "  }\n",
+        "  .disclaimer p {\n",
+        "    font-weight: bold;\n",
+        "    margin-bottom: 0;\n",
+        "  }\n",
+        "</style>\n",
+        "\n",
+        "<div class=\"cell-bg\">\n",
+        "  <div class=\"disclaimer\">\n",
+        "    <h3>Disclaimer: Using Google Colab</h3>\n",
+        "    <p>Please read carefully before proceeding:</p>\n",
+        "    <ol>\n",
+        "      <li><strong>Google's Servers:</strong> This notebook runs on Google's servers. Your code and data will be processed and temporarily stored on Google's infrastructure.</li>\n",
+        "      <li><strong>Data Privacy:</strong> Be mindful of the data you upload or process here. Avoid using sensitive, confidential, or personal information that shouldn't be shared with third parties.</li>\n",
+        "      <li><strong>Security Considerations:</strong> Colab is a shared environment. While Google implements security measures, treat it as a public environment and act accordingly.</li>\n",
+        "      <li><strong>Terms of Service:</strong> Ensure your usage complies with Google Colab's Terms of Service and Google Cloud's Terms of Service.</li>\n",
+        "      <li><strong>Data Persistence:</strong> Data in Colab notebooks is not permanently stored. Save important data and results to your local machine or a secure cloud storage.</li>\n",
+        "      <li><strong>Resource Limitations:</strong> Colab provides free resources, but these are subject to availability and usage limits.</li>\n",
+        "    </ol>\n",
+        "    <p>By using this Colab notebook, you acknowledge that you understand and accept these conditions. Please use Colab at your own discretion and responsibility.</p>\n",
+        "  </div>\n",
+        "</div>"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "6Och8D7u0ovX",
+      "metadata": {
+        "id": "6Och8D7u0ovX"
+      },
+      "source": [
+        "#### Setup the LLM API key"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "FlndiROX0bmX",
+      "metadata": {
+        "id": "FlndiROX0bmX"
+      },
+      "source": [
+        "Secure your LLM API key as environment variable\n",
+        "- click the `Secrets` button on the left\n",
+        "- click `Add new secret`\n",
+        "- insert \"OPENAI_API_KEY\" under `Name`\n",
+        "- insert the API key value under `Value` (use raw string without quote. e.g., `xyz` instead of `\"xyz\"`)\n",
+        "- [optional] you might also need to insert \"OPENAI_BASE_URL\" and its value, based on the requirements from your API key provider (use raw string without quote. e.g., `xyz` instead of `\"xyz\"`)\n",
+        "- click the `Notebook access` toggle to make it available for the notebook run\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "fbc65f78",
+      "metadata": {
+        "id": "fbc65f78"
+      },
+      "source": [
+        "# Use Vizro-AI to generate Vizro charts\n",
+        "# **At the top of this notebook, click `Runtime` -> `Run all`**"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "rdnxbyKfNZkT",
+      "metadata": {
+        "cellView": "form",
+        "id": "rdnxbyKfNZkT"
+      },
+      "outputs": [],
+      "source": [
+        "# @title ## Setup\n",
+        "#@markdown #### 1. Install Vizro-AI\n",
+        "print(\"Installing dependencies\")\n",
+        "%pip install uv -q -q -q\n",
+        "!uv pip install --system \"vizro-ai @ git+https://github.com/mckinsey/vizro.git@main#subdirectory=vizro-ai\" --quiet\n",
+        "print(\"✅ Installation finished\")\n",
+        "\n",
+        "#@markdown #### 2. Setup LLM API access\n",
+        "import os\n",
+        "from google.colab import userdata\n",
+        "\n",
+        "def safe_get_userdata(key):\n",
+        "    try:\n",
+        "        return userdata.get(key)\n",
+        "    except Exception as e:\n",
+        "        print(f\"Warning: Unable to access {key}. Reason: {str(e)}\")\n",
+        "        return None\n",
+        "\n",
+        "# Always try to set the OPENAI_API_KEY\n",
+        "api_key = safe_get_userdata(\"OPENAI_API_KEY\")\n",
+        "if api_key:\n",
+        "    os.environ[\"OPENAI_API_KEY\"] = api_key\n",
+        "else:\n",
+        "    print(\"❌ OPENAI_API_KEY not set. Click `Secrets` icon on the left to setup.\")\n",
+        "\n",
+        "# Conditionally set OPENAI_BASE_URL if provided and accessible\n",
+        "openai_base_url = safe_get_userdata(\"OPENAI_BASE_URL\")\n",
+        "if openai_base_url:\n",
+        "    os.environ[\"OPENAI_BASE_URL\"] = openai_base_url\n",
+        "else:\n",
+        "    print(\"User defined OPENAI_BASE_URL not set. Using default URL.\")\n",
+        "\n",
+        "print(\"\\nCurrent environment variables:\")\n",
+        "print(f\"OPENAI_API_KEY: {'✅ Set' if 'OPENAI_API_KEY' in os.environ else 'Not set'}\")\n",
+        "print(f\"OPENAI_BASE_URL: {'✅ Set' if 'OPENAI_BASE_URL' in os.environ else 'Not set by user, use default'}\")"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "c6ac1b7d-5830-495b-94be-1ad7bf3022d3",
+      "metadata": {
+        "cellView": "form",
+        "id": "c6ac1b7d-5830-495b-94be-1ad7bf3022d3"
+      },
+      "outputs": [],
+      "source": [
+        "# @title ## Data upload\n",
+        "\n",
+        "#@markdown #### Upload your CSV data (only 1 dataframe accepted per chart)\n",
+        "#@markdown - click `Choose Files` if you'd like to upload and use your own data\n",
+        "#@markdown - or click `Cancel upload` and use the default example data for initial exploration\n",
+        "\n",
+        "import pandas as pd\n",
+        "from plotly.express.data import gapminder\n",
+        "from google.colab import files\n",
+        "\n",
+        "uploaded = files.upload()\n",
+        "\n",
+        "if not uploaded:\n",
+        "    print(\"No files uploaded. Use the plotly gapminder dataset as an example.\")\n",
+        "    df = gapminder()\n",
+        "else:\n",
+        "    for fn in uploaded.keys():\n",
+        "        print('User uploaded file \"{name}\"'.format(\n",
+        "            name=fn, length=len(uploaded[fn])))\n",
+        "\n",
+        "        df = pd.read_csv(fn)\n",
+        "print(f\"Dataframe used for plotting: \\n{df.head()}\")\n",
+        "\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "_yeVqs9nUgYH",
+      "metadata": {
+        "cellView": "form",
+        "id": "_yeVqs9nUgYH"
+      },
+      "outputs": [],
+      "source": [
+        "# @title ## Input the LLM model choice and user prompt { run: \"auto\" }\n",
+        "\n",
+        "#@markdown #### 1. Choose the LLM model\n",
+        "\n",
+        "LLM = 'gpt-4o' # @param [\"gpt-4o\", \"gpt-3.5-turbo\", \"gpt-4-turbo\", \"gpt-4o-mini\"]\n",
+        "\n",
+        "print(f\"Selected LLM: {LLM}\")\n",
+        "\n",
+        "#@markdown ---\n",
+        "#@markdown #### 2. Input your chart question\n",
+        "\n",
+        "# @markdown #### Instructions:\n",
+        "user_input = 'Describe the composition of gdp in continent.' # @param {type:\"string\", placeholder:\"Enter the requirements for the chart\"}\n",
+        "\n",
+        "print(f\"User input: {user_input}\")"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "O-LSNhSA7j3r",
+      "metadata": {
+        "cellView": "form",
+        "id": "O-LSNhSA7j3r"
+      },
+      "outputs": [],
+      "source": [
+        "# @title ## Create the chart using Vizro-AI\n",
+        "#@markdown Note: to iterate with different data, model, and prompt, please edit in cells above and click the corresponding `Run cell` buttons.\n",
+        "\n",
+        "print(\"Running VizroAI...\")\n",
+        "print(f\"Selected LLM: {LLM}\")\n",
+        "print(f\"User input: {user_input}\")\n",
+        "from vizro_ai import VizroAI\n",
+        "\n",
+        "vizro_ai = VizroAI()\n",
+        "result = vizro_ai.plot(df, user_input, return_elements=True)\n",
+        "\n",
+        "print(\"✅ VizroAI finished\")\n",
+        "print(\"\\n-----\\nCode:\\n-----\\n\")\n",
+        "print(result.code)\n",
+        "print(\"\\n-------\\nFigure:\\n-------\\n\")\n",
+        "result.figure.show()"
+      ]
+    }
+  ],
+  "metadata": {
+    "colab": {
+      "provenance": []
+    },
+    "kernelspec": {
+      "display_name": "Python 3 (ipykernel)",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "codemirror_mode": {
+        "name": "ipython",
+        "version": 3
+      },
+      "file_extension": ".py",
+      "mimetype": "text/x-python",
+      "name": "python",
+      "nbconvert_exporter": "python",
+      "pygments_lexer": "ipython3",
+      "version": "3.9.7"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}