From afb8db88179c0abdd5c15abf7d372906404120d2 Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Thu, 21 Mar 2024 17:45:38 +0000 Subject: [PATCH 01/17] First chunk of changes to Vizro-AI Signed-off-by: Jo Stichbury --- vizro-ai/docs/index.md | 43 ++--- vizro-ai/docs/pages/contribute/authors.md | 18 +- .../docs/pages/contribute/contributing.md | 2 +- vizro-ai/docs/pages/explanation/disclaimer.md | 4 +- vizro-ai/docs/pages/explanation/safeguard.md | 2 +- .../pages/explanation/safety-in-vizro-ai.md | 20 +-- vizro-ai/docs/pages/tutorials/quickstart.md | 47 ++--- vizro-ai/docs/pages/user-guides/api-setup.md | 72 ++++---- vizro-ai/docs/pages/user-guides/install.md | 167 ++++++++++++++---- vizro-ai/mkdocs.yml | 17 +- 10 files changed, 241 insertions(+), 151 deletions(-) diff --git a/vizro-ai/docs/index.md b/vizro-ai/docs/index.md index 33fed5078..4cddb216f 100644 --- a/vizro-ai/docs/index.md +++ b/vizro-ai/docs/index.md @@ -1,26 +1,11 @@ # Vizro-AI -Vizro-AI is a tool designed for generating data visualizations. It serves as an extension to Vizro, leveraging natural language capabilities to empower users in creating charts effortlessly. +Vizro-AI extends [Vizro] with a user-friendly interface that uses natural language capabilities to help you create interactive charts effortlessly. -## Why Vizro-AI? - -### Easy-to-use -One of the key strengths of Vizro-AI lies in its natural language capabilities, making it accessible to coding novices. Vizro-AI provides a user-friendly interface that allows to create interactive charts while offering detailed insights about the data and the generated code. - -### Visually-optimized -Vizro-AI also caters to data practitioners who often find themselves spending more time in formatting rather than actual visualization creation. Vizro-AI enables users to speed up the process of creating visually appealing charts by using Vizro's themes which incorporate design best practices by default. - -### Dashboard-ready -Vizro-AI leverages the power of [Plotly](https://plotly.com/python/) to produce interactive charts, making it easier to seamlessly integrate these generated charts directly into dashboard applications. - -!!! notice "Notice" - Please review this [disclaimer](pages/explanation/disclaimer.md) - before using the `vizro-ai` package. - - Since users must connect to Large Language Models (LLMs) in order to use Vizro-AI, - please also ensure that you review our guides on the [usage of LLMs](pages/explanation/safety-in-vizro-ai.md) - and the required [safeguarding for dynamic code evaluation](pages/explanation/safeguard.md). +If you're new to coding, Vizro-AI simplifies the process of creating charts that offer detailed insights about your data. Even if you're an experienced data practitioner, Vizro-AI optimizes how you create visually appealing charts. +* It uses Vizro's themes, which incorporate design best practices by default. +* It uses [Plotly](https://plotly.com/python/) and makes it easy to integrate the interactive charts it generates seamlessly into dashboard applications.
@@ -28,9 +13,9 @@ Vizro-AI leverages the power of [Plotly](https://plotly.com/python/) to produce
-
Get Started
+
Get started

- New to Vizro-AI? Take a look at our tutorials to get started and to explore our core features. + New to Vizro-AI? Tutorials to get started and to explore the key features.

@@ -39,9 +24,9 @@ Vizro-AI leverages the power of [Plotly](https://plotly.com/python/) to produce
-
User Guides
+
User guides

- Our user guides provide step-by-step instructions on how to install `vizro-ai` package and leverage our core features. + Step-by-step instructions on how to use Vizro-AI.

@@ -53,7 +38,7 @@ Vizro-AI leverages the power of [Plotly](https://plotly.com/python/) to produce
Explanation

- Our explanation section contains background information and disclaimer. + The explanation section contains background information and a disclaimer.

@@ -64,7 +49,7 @@ Vizro-AI leverages the power of [Plotly](https://plotly.com/python/) to produce
Contribute

- Find our contribution guidelines and all our current and previous contributors here. + Contribution guidelines and all our current and past contributors.

@@ -72,3 +57,11 @@ Vizro-AI leverages the power of [Plotly](https://plotly.com/python/) to produce + +!!! notice "Notice" + Please review this [disclaimer](pages/explanation/disclaimer.md) + before using the `vizro-ai` package. + + Users must connect to Large Language Models (LLMs) to use Vizro-AI. + Please review our [guidelines on the use of LLMs](pages/explanation/safety-in-vizro-ai.md) + and the required [safeguarding for dynamic code evaluation](pages/explanation/safeguard.md). diff --git a/vizro-ai/docs/pages/contribute/authors.md b/vizro-ai/docs/pages/contribute/authors.md index 83f65cee6..5ec75ffc6 100644 --- a/vizro-ai/docs/pages/contribute/authors.md +++ b/vizro-ai/docs/pages/contribute/authors.md @@ -1,17 +1,17 @@ # Authors ## Current team members - +[Alexey Snigir](https://github.com/l0uden), [Anna Xiong](https://github.com/Anna-Xiong), -[Maximilian Schulz](https://github.com/maxschulz-COL), -[Chiara Pullem](https://github.com/chiara-sophie), -[Lingyi Zhang](https://github.com/lingyielia), [Antony Milne](https://github.com/antonymilne), -[Alexey Snigir](https://github.com/l0uden), +[Chiara Pullem](https://github.com/chiara-sophie), +[Dan Dumitriu](https://github.com/dandumitriu1), [Huong Li Nguyen](https://github.com/huong-li-nguyen), -[Petar Pejovic](https://github.com/petar-qb), +[Jo Stichbury](https://github.com/stichbury), +[Joseph Perkins](https://github.com/Joseph-Perkins), +[Lingyi Zhang](https://github.com/lingyielia), +[Maximilian Schulz](https://github.com/maxschulz-COL), [Nadija Graca](https://github.com/nadijagraca), -[Joseph Perkins](https://github.com/Joseph-Perkins) +[Petar Pejovic](https://github.com/petar-qb) -with thanks to Sam Bourton and Stephen Xu for sponsorhip, inspiration and guidance, -(plus everyone else who helped to test, guide, support and encourage development) +with thanks to Sam Bourton and Stephen Xu for sponsorship, inspiration and guidance, plus everyone else who helped to test, guide, support and encourage development. diff --git a/vizro-ai/docs/pages/contribute/contributing.md b/vizro-ai/docs/pages/contribute/contributing.md index 245759fb9..413db8e14 100644 --- a/vizro-ai/docs/pages/contribute/contributing.md +++ b/vizro-ai/docs/pages/contribute/contributing.md @@ -1 +1 @@ -# Contributing Guidelines +# Contributing guidelines diff --git a/vizro-ai/docs/pages/explanation/disclaimer.md b/vizro-ai/docs/pages/explanation/disclaimer.md index 27b233f7e..6ad9964e1 100644 --- a/vizro-ai/docs/pages/explanation/disclaimer.md +++ b/vizro-ai/docs/pages/explanation/disclaimer.md @@ -3,7 +3,7 @@ Users must select one of the [supported Large Language Models (LLMs)](../user-guides/model-config.md) in order to use the `vizro_ai` package, and are responsible for obtaining their own suitable API key for the relevant model. -## Third Party API +## Third party API - Users are responsible for anything done via their own API key. @@ -11,7 +11,7 @@ and are responsible for obtaining their own suitable API key for the relevant mo - Users are wholly responsible for the use and security of the third-party generative AI tools and of Vizro. -## User Acknowledgments +## User acknowledgments Users acknowledge and agree that: diff --git a/vizro-ai/docs/pages/explanation/safeguard.md b/vizro-ai/docs/pages/explanation/safeguard.md index f513206e3..22c20a46c 100644 --- a/vizro-ai/docs/pages/explanation/safeguard.md +++ b/vizro-ai/docs/pages/explanation/safeguard.md @@ -1,4 +1,4 @@ -# Safeguard Dynamic Code Execution in Vizro-AI +# Safeguard dynamic code dxecution in Vizro-AI Vizro-AI uses the `exec()` statement in Python to run generated code from Large Language Models (LLMs) for self-debugging and automatic visual rendering in methods such as `vizro_ai._get_chart_code()` and `vizro_ai.plot()`. diff --git a/vizro-ai/docs/pages/explanation/safety-in-vizro-ai.md b/vizro-ai/docs/pages/explanation/safety-in-vizro-ai.md index 816111b29..f11540ac4 100644 --- a/vizro-ai/docs/pages/explanation/safety-in-vizro-ai.md +++ b/vizro-ai/docs/pages/explanation/safety-in-vizro-ai.md @@ -1,4 +1,4 @@ -## Warning and Safety usage for Generative AI Models +## Warning and safety usage for generative AI models Generative AI models, especially Large Language Models (LLMs) represent significant advancements in the AI field. Vizro-AI also leverages LLMs, however, as with any powerful tool, there are potential risks associated. @@ -9,47 +9,47 @@ We recommend users research and understand the selected model before using `vizr Users are encouraged to treat AI-generated content as supplementary, **always apply human judgment**, approach with caution, review the relevant [disclaimer](disclaimer.md) page, and consider the following: -### 1. Hallucination and Misrepresentation +### 1. Hallucination and misrepresentation Generative models can potentially generate information while appearing factual, being entirely fictitious or misleading. The vendor models might lack real-time knowledge or events beyond its last updates. `vizro_ai` output may vary and please always verify critical information. It is the user's responsibility to discern the accuracy, consistent, and reliability of the generated content. -### 2. Unintended and Sensitive output +### 2. Unintended and sensitive output The outputs from these models can be unexpected, inappropriate, or even harmful. Users as human in the loop is an essential part. Users must check and interpret the final output. It is necessary to approach the generated content with caution, especially when shared or applied in various contexts. -### 3. Data Privacy +### 3. Data privacy Your data is sent to model vendors if you connect to LLMs via their APIs. For example, if you connect to the model "gpt-3.5-turbo-0613" from Open AI, your data will be sent to OpenAI via their API. Users should be cautious about sharing or inputting any personal or sensitive information. -### 4. Bias and Fairness +### 4. Bias and fairness Generative AI can exhibit biases present in their training data. Users need to be aware of and navigate potential biases in generated outputs and be cautious when interpreting the generated content. -### 5. Malicious Use +### 5. Malicious use These models can be exploited for various malicious activities. Users should be cautious about how and where they deploy and access such models. It's crucial for users to remain informed, cautious, and ethical in their applications. -## Dependencies, Code Scanners and Infosec +## Dependencies, code scanners and information security -It may occur that dependencies of `vizro_ai` get flagged by code scanners and other infosec tools. As a consequence it may happen that +It may occur that dependencies of `vizro_ai` get flagged by code scanners and other information security tools. As a consequence it may happen that `vizro_ai` also get flagged. -While we aim to resolve any flagged issues as soon as possible, there may not always be an immediate available fix, especially in a very dynamic environment such as generative AI. We encourage users to investigate if any flagged infosec issues are actually related +While we aim to resolve any flagged issues as soon as possible, there may not always be an immediate available fix, especially in a very dynamic environment such as generative AI. We encourage users to investigate if any flagged information security issues are actually related to any functionality used in our code base or if they only concern functionality outside the scope of `vizro_ai`. In case those issues are related to code execution, note that `vizro_ai` has its own process of executing dynamic code (see [Safeguard Execution of Dynamic Code](safeguard.md)), and does not rely on its dependencies to do so. -## Execution of Dynamic Code in Vizro-AI +## Execution of dynamic code in Vizro-AI The `exec()` statement is used in `vizro_ai`. It allows for dynamic execution of Python programs which can be powerful, but can also pose security risk if used without caution. When paired with outputs from generative models, there is potential for unintended or malicious code execution. diff --git a/vizro-ai/docs/pages/tutorials/quickstart.md b/vizro-ai/docs/pages/tutorials/quickstart.md index d35e3800e..41a8903cd 100644 --- a/vizro-ai/docs/pages/tutorials/quickstart.md +++ b/vizro-ai/docs/pages/tutorials/quickstart.md @@ -1,45 +1,48 @@ # Get started with Vizro-AI This tutorial serves as an introduction to Vizro-AI. -It is a step-by-step guide to help you experiment and create your initial Vizro chart using Vizro-AI, our English-to-visualization package. The goal is to provide you with the necessary knowledge to explore further into our documentation. +It is a step-by-step guide to help you experiment and create an initial Vizro chart using Vizro-AI, which is an English-to-visualization package. The goal is to provide you with the necessary knowledge to explore further into our documentation. -## Let's get started! -### 1. Install Vizro-AI and its dependencies -If you haven't already installed `vizro_ai` package, follow the [installation guide](../user-guides/install.md) -to do so inside a virtual environment. +### 1. Install Vizro and its dependencies -??? tip "Beginners/Code novices" - If you consider yourself a beginner to python and/or virtual environments, there is also a section in the [installation guide](../user-guides/install.md) that avoids any use of terminals and relies only upon a graphical user interface. +If you haven't already installed Vizro-AI, follow the [installation guide](../user-guides/install.md). -### 2. Set up jupyter notebook -A good way to initially explore Vizro-AI is from a Jupyter notebook. -Activate your previously created virtual environment and install Jupyter using the following command: +### 2. Open a Jupyter Notebook -```console -pip install jupyter -``` +A good way to initially explore Vizro-AI is from inside a Jupyter Notebook. + +??? "Install and run Jupyter" + + If you haven't used Jupyter before, you may need to install the Jupyter package. From the terminal window: + + ```bash + pip install jupyter + ``` -Next, you can start your jupyter notebook in your activated environment by: + Alternatively, you can [work within Anaconda Navigator](../user-guides/install.md#use-vizro-inside-anaconda-navigator) as described in the Vizro installation guide. -```console + +Activate the virtual environment you used to install Vizro, and start a new Notebook as follows: + +```bash jupyter notebook ``` -This opens a browser tab, and you can navigate to your preferred folder for this new project. Create a new notebook Python 3 (ipykernel) notebook from the "New" dropdown. Make sure that you select your environment as kernel. -??? tip "Beginners/Code novices" - If you followed the beginners steps in the [installation guide](../user-guides/install.md), you should already be set, and you can continue below. +The command opens Jupyter in a browser tab. Navigate to a preferred folder in which to create this new dashboard. -Confirm that `vizro_ai` is installed by typing the following into a jupyter cell in your notebook and running it. +Create a new `Python 3 (ipykernel)` Notebook from the "New" dropdown. Confirm your Vizro installation by typing the following into a cell in the Notebook and running it. ```py import vizro_ai + print(vizro_ai.__version__) ``` -You should see a return output of the version. +You should see a return output of the form `x.y.z`. + -### 3. Large Language Model (LLM) API KEY +### 3. OpenAI API KEY -A prerequisite to use Vizro-AI is access to one of the supported LLMs. Refer to the [user guide](../user-guides/api-setup.md) on how to set up the API. +Use of Vizro-AI requires an API key for the OpenAI large language model. Refer to the [API set-up user guide](../user-guides/api-setup.md) for information about how to get set up. ### 4. Ask your first question using Vizro-AI diff --git a/vizro-ai/docs/pages/user-guides/api-setup.md b/vizro-ai/docs/pages/user-guides/api-setup.md index 6159cfca8..20cabc320 100644 --- a/vizro-ai/docs/pages/user-guides/api-setup.md +++ b/vizro-ai/docs/pages/user-guides/api-setup.md @@ -1,35 +1,33 @@ -# How to setup the API -This guide shows how to set up the API key and other environment variables (e.g., -base URL) so that you can seamlessly communicate with the Large Language Model (LLM). +# How to set up and use a large language model with Vizro-AI +Use of Vizro-AI requires the use of a large language model. At present, we only support [OpenAI](https://openai.com/). -Users are recommended to review the third party API key section of the [disclaimer](../explanation/disclaimer.md) documentation. +## Set up OpenAI +To use OpenAI with Vizro-AI you need an API key, which you can get by [creating an OpenAI account if you don't already have one](https://platform.openai.com/account/api-keys). -## OpenAI -To communicate with the OpenAI API, you need to provide the API key. Additionally, you -might need to provide the base URL if you are using a custom OpenAI resource endpoint. +!!! note -### Setup the API key -There are two common ways to set up the API key in a development environment. + We recommend that you consult the [third-party API key section of the disclaimer documentation](../explanation/disclaimer.md) documentation. -__Method 1 (recommended): Set up the API key for a single project__ +### Set up the API key +There are two common ways to set up the API key in a development environment. -To make the API key available for a specific project, you can set it in a `.env` -file. Then, you can load the API key from the `.env` file in your development environment. -Avoid committing the `.env` file if you are using a version control system such as Git. -You can add `.env` to your `.gitignore` file to avoid committing it. +#### Method 1: Set an environment variable for a single project -By default, when `vizro-ai` is imported, it automatically loads the `.env` file. -This file is searched for in the current directory and, if not found, the search continues upwards through the directory hierarchy. +To make the API key available for a single project, you can create a locacl `.env` +file to store it. Then, you can load the API key from that `.env` file in your development environment. -!!! example "API key setup and usage" +!!! example "The `.env` file should look as follows (containing your key rather than `abc123`)" === ".env" ```text - OPENAI_API_KEY= + OPENAI_API_KEY=abc123 ``` -#### Customizing the .env file location and name -If you would like to customize the `.env` file location and name, you can set it manually. + +By default, `vizro-ai` automatically loads the `.env` file, by searching the current directory and, if it does not find `.env`, the search continues upwards through the directory hierarchy. + +If you would like to customize the `.env` file location and name, you can manually customize the search. The default import of the `.env` file can be overridden by specifying the path and name. Here's how you can do it: + ```py from dotenv import load_dotenv, find_dotenv from pathlib import Path @@ -43,31 +41,29 @@ env_file = find_dotenv(".env.dev") # Replace ".env.dev" with your file name # Load the specified .env file load_dotenv(env_file) ``` -Note: Please refer to [python-dotenv documentation](https://saurabh-kumar.com/python-dotenv/reference/) for detailed information. +Refer to [python-dotenv documentation](https://saurabh-kumar.com/python-dotenv/reference/) for further information. +!!! warning "Don't share your secret API key!" -__Method 2: Set up the API key as an environment variable for all projects__ + You should avoid committing the `.env` file to version control. You can do this for Git by adding `.env` to your `.gitignore` file. -To make the API key available for all projects, you can set it as an environment -variable. Please refer to the section ["Setup your API key for all projects"](https://platform.openai.com/docs/quickstart/step-2-setup-your-api-key?context=python) -in the OpenAI documentation. (It is under the dropdown of Step 2: Setup your API key). -It provides step-by-step instructions for setting up the API key as an environment +#### Method 2: Set an environment variable for all projects + +To make the OpenAI API key available for all projects, you can set it as a system environment +variable. Please refer to the section ["Set up your API key for all projects"](https://platform.openai.com/docs/quickstart/step-2-setup-your-api-key?context=python) +in the OpenAI documentation. (It is under the dropdown of "Step 2: Set up your API key"). + +The documentation provides step-by-step instructions for setting up the API key as an environment variable, on operating systems including Windows and MacOS. -### Setup the Base URL (optional) -The API Base URL used for the OpenAI connector is set to `https://api.openai.com/v1` by default. -If you are using a custom API endpoint, you can set it as an environment variable. +### Setup the base URL (optional) +You might need to provide the base URL if you are using a custom OpenAI resource endpoint. -This is usually for organizational users. For example, if your organization has designed API gateway, -you can change the API endpoint here. +The API base URL used for the OpenAI connector is set to `https://api.openai.com/v1` by default. +If you are using a custom API endpoint, for example, if your organization has a designated API gateway, +you can change the base URL by setting it as an environment variable. -You can follow the approach in the section "Setup your API key for all projects -(recommended)" to add the environment variable `OPENAI_API_BASE` to your environment. -!!! example "API Base setup and usage" - === ".env" - ```text - OPENAI_API_BASE= - ``` +Follow the approach above in Method 2 to [add the environment variable `OPENAI_API_BASE` for use by all projects](#method-2-set-an-environment-variable-for-all-projects). diff --git a/vizro-ai/docs/pages/user-guides/install.md b/vizro-ai/docs/pages/user-guides/install.md index cb53dcecc..3cfcbf0ef 100644 --- a/vizro-ai/docs/pages/user-guides/install.md +++ b/vizro-ai/docs/pages/user-guides/install.md @@ -1,53 +1,150 @@ # How to install Vizro-AI -This guide offers instructions on installing Vizro-AI and provides comprehensive explanation on how to install, update and verify the current version of Vizro-AI. +This guide shows you how to install Vizro-AI, how to verify the installation succeeded and find the version of Vizro-AI, and how to update Vizro-AI. + +If you already have a virtual environment setup in Python then you can skip this page and just install Vizro-AI straight away by running: +```bash +pip install vizro_ai +``` ## Prerequisites -- **Python**: Vizro-AI supports macOS, Linux, and Windows. It is designed to work with Python 3.8 and above. The python - version can be specified when setting up your virtual environment. -- **Virtual environment**: We recommend creating a new virtual environment for each new Vizro-AI project you work on to - isolate the Python dependencies from those of other projects. To learn more, please see the following references about [python virtual environments](https://realpython.com/python-virtual-environments-a-primer/), [conda virtual environments](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html#starting-conda) or [watch an explainer video about them](https://youtu.be/YKfAwIItO7M). -- **OpenAI API Key**: Using Vizro-AI requires an API key, which you can get by creating an account [here](https://platform.openai.com/account/api-keys). (Users are recommended to review the third party API key section of the [disclaimer](../explanation/disclaimer.md) documentation. -). Once you have your API key, the next step is to set your environment variable by: -```bash -export OPENAI_API_KEY="..." +### Python +Vizro-AI supports macOS, Linux, and Windows. It works with Python 3.8 and later. You can specify the version of Python to use with Vizro-AI when you set up a virtual environment. + + +### Virtual environment +You should create a virtual environment for each Vizro-AI project you work on to isolate its Python dependencies from those of other projects. See the following references to learn more about [Python virtual environments](https://realpython.com/python-virtual-environments-a-primer/), [Conda virtual environments](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html#starting-conda) or [watch an explainer video about them](https://youtu.be/YKfAwIItO7M). + +!!! tip "Prefer to use Vizro-AI without opening a terminal window?" + + If you are a beginner or coding novice, you may prefer to avoid using a terminal to work with Vizro. Skip to the ["Use Vizro-AI inside Anaconda" section](#use-vizro-ai-inside-anaconda-navigator) below. + + + +??? information "How to create a virtual environment for your Vizro-AI project" + + The simplest way to create a virtual environment in Python is `venv`, which is included in the Python standard library. Create a directory for your project and navigate to it. For example: + + ```bash + mkdir vizroai-project + cd vizroai-project + ``` + + Next, create and activate a new virtual environment in this directory with `venv`: + ```bash + python3 -m venv .venv + source .venv/bin/activate + ``` + + Alternatively, you might like to use [`conda` as your virtual environment manager](https://docs.conda.io/projects/conda/en/latest/user-guide/install/). Once installed, you can create and activate a virtual environment from the terminal as follows: + + ```bash + conda create --name vizroai-environment + conda activate vizroai-environment + ``` + +### Large language model + +Use of Vizro-AI requires the use of a large language model. At present, we only support [OpenAI](https://openai.com/). + +To use OpenAI with Vizro-AI you need an API key, which you can get by [creating an OpenAI account if you don't already have one](https://platform.openai.com/account/api-keys). + +!!! note + + We recommend that you consult the [third-party API key section of the disclaimer documentation](../explanation/disclaimer.md) documentation. + +There are two common ways to set up the API key in a development environment. + +__Method 1: Set an environment variable for a single project__ + +To make the API key available for a single project, you can create a local `.env` +file to store it. Then, you can load the API key from that `.env` file in your development environment. + +The `.env` file should look as follows (containing your key rather than `abc123`): + +```text +OPENAI_API_KEY=abc123 ``` +By default, `vizro-ai` automatically loads the `.env` file, by searching the current directory and, if it does not find `.env`, the search continues upwards through the directory hierarchy. + +If you would like to customize the `.env` file location and name, you can manually customize the search. + -More details can be found in the [environment setup guide](../user-guides/api-setup.md). +??? example "How to override the default location of the .`env` file:" -??? tip "Beginners/Code novices" - If you are a beginner or new to coding and wish to avoid using the terminal, you can follow these steps: - - Install [Anaconda Navigator](https://www.anaconda.com/download) - - Create a new environment as detailed [here](https://docs.anaconda.com/free/navigator/tutorials/manage-environments/), and select a Python version `>=3.8` -## Install + ```py + from dotenv import load_dotenv, find_dotenv + from pathlib import Path -To install Vizro-AI from the Python Package Index (PyPI), utilize [`pip`](https://pip.pypa.io/en/stable/) in your terminal with the following command: + # Specify the exact path to your .env file + env_file = Path.cwd() / ".env" # Adjust the path as needed + + # Alternatively, specify a different .env file name + env_file = find_dotenv(".env.dev") # Replace ".env.dev" with your file name + + # Load the specified .env file + load_dotenv(env_file) + ``` + Refer to [python-dotenv documentation](https://saurabh-kumar.com/python-dotenv/reference/) for further information. + +!!! warning "Don't share your secret API key!" + + You should avoid committing the `.env` file to version control. You can do this for Git by adding `.env` to your `.gitignore` file. + + +__Method 2: Set an environment variable for all projects__ + +To make the OpenAI API key available for all projects, you can set it as a system environment +variable. Please refer to the section ["Set up your API key for all projects"](https://platform.openai.com/docs/quickstart/step-2-setup-your-api-key?context=python) +in the OpenAI documentation. (It is under the dropdown of "Step 2: Set up your API key"). + +The documentation provides step-by-step instructions for setting up the API key as an environment +variable, on operating systems including Windows and MacOS. + + +__Set the base URL (optional)__ + +You might need to provide the base URL if you are using a custom OpenAI resource endpoint. + +The API base URL used for the OpenAI connector is set to `https://api.openai.com/v1` by default. +If you are using a custom API endpoint, for example, if your organization has a designated API gateway, +you can change the base URL by setting it as an environment variable. + + +Follow the approach above in Method 2 to add the environment variable `OPENAI_API_BASE` for use by all projects. + + +## Install Vizro + +To install Vizro-AI, use [`pip`](https://pip.pypa.io/en/stable/) in your terminal window: ```bash pip install vizro_ai ``` -While you can execute code from the tutorials and user guides using a Python script, using a Jupyter notebook is often considered more convenient. You can install `jupyter` with the following command: +## Use Vizro-AI inside Anaconda Navigator -```bash -pip install jupyter -``` +To completely avoid terminal usage, follow these steps to work with Vizro-AI: + + +1. Install [Anaconda Navigator](https://www.anaconda.com/download). -??? tip "Beginners/Code novices" - If you're new to coding or consider yourself a beginner, you can follow these following steps to avoid using the terminal: +2. Create a new environment as [outlined in the Anaconda documentation](https://docs.anaconda.com/free/navigator/tutorials/manage-environments/). Choose a Python version `>=3.8`. - - Search `vizro_ai` and install it using the Anaconda Navigator package manager. You can find instructions [here](https://docs.anaconda.com/free/navigator/tutorials/manage-packages/) - - Similarly, search `jupyter` and install it through the same procedure - - Once installed, launching a Jupyter notebook becomes straightforward; you can find guidance [here](https://problemsolvingwithpython.com/02-Jupyter-Notebooks/02.04-Opening-a-Jupyter-Notebook/#open-a-jupyter-notebook-with-anaconda-navigator) - - With Jupyter, you can easily copy and paste any of the provided examples into a notebook cell, evaluate the cell, and examine the results +3. Search `vizro_ai` and install it [using the Anaconda Navigator package manager](https://docs.anaconda.com/free/navigator/tutorials/manage-packages/). -## Verify version +4. Similarly, search `jupyter` and install it. -After successfully installing Vizro-AI, to verify the version or confirm the installation, you can run the following code from a Python script or a Jupyter notebook cell: +5. [Launch a Jupyter notebook](https://problemsolvingwithpython.com/02-Jupyter-Notebooks/02.04-Opening-a-Jupyter-Notebook/#open-a-jupyter-notebook-with-anaconda-navigator) to work with Vizro-AI. + + +## Confirm a successful installation + +To confirm the installation was successful, and verify the version of Vizro-AI installed, call the following. You can do this from within a Jupyter notebook cell, or run the following as a Python script: ```py import vizro_ai @@ -55,14 +152,16 @@ import vizro_ai print(vizro_ai.__version__) ``` -You should see a return output of the current version. +You should see a return output of the form `x.y.z`. ## Upgrade -If you want to upgrade Vizro-AI to a different version later on, you can do so by running the following command: -``` -pip install vizro_ai -U +To change the version of Vizro-AI installed: + +```bash +pip install -U vizro_ai ``` -The best way to safely upgrade is to check the [release notes]() for any notable breaking changes before migrating an -existing project. +!!! tip Check the Vizro-AI release notes + + To upgrade safely, check the [release notes](https://github.com/mckinsey/vizro/blob/main/vizro-ai/CHANGELOG.md) for any notable breaking changes before migrating an existing project. diff --git a/vizro-ai/mkdocs.yml b/vizro-ai/mkdocs.yml index c0d9b299c..1d9fbc0ec 100644 --- a/vizro-ai/mkdocs.yml +++ b/vizro-ai/mkdocs.yml @@ -3,18 +3,17 @@ site_url: https://vizro-ai.readthedocs.io/en/latest/ nav: - Vizro-AI: index.md - Get started: - - Quickstart: pages/tutorials/quickstart.md + - Install Vizro-AI: pages/user-guides/install.md + - A first dashboard: pages/tutorials/quickstart.md - Explore Vizro-AI: pages/tutorials/explore-vizro-ai.md - - User Guides: - - Fundamentals: - - Installation: pages/user-guides/install.md - - API Setup: pages/user-guides/api-setup.md - - Run Methods: pages/user-guides/run-vizro-ai.md - - Model Configuration: pages/user-guides/model-config.md + - How-to Guides: + - LLM setup: pages/user-guides/api-setup.md + - Run methods: pages/user-guides/run-vizro-ai.md + - Model configuration: pages/user-guides/model-config.md - Explanation: - Disclaimer: pages/explanation/disclaimer.md - - Safeguard Code Execution: pages/explanation/safeguard.md - - Safety in Vizro AI: pages/explanation/safety-in-vizro-ai.md + - Safeguard code execution: pages/explanation/safeguard.md + - Safety in Vizro-AI: pages/explanation/safety-in-vizro-ai.md - Contribute: # - Contributing: pages/contribute/contributing.md - Authors: pages/contribute/authors.md From 6f1e348b72b6fa1e18425c405b26740095d6e1d6 Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Thu, 21 Mar 2024 17:46:40 +0000 Subject: [PATCH 02/17] remove API key setup page Signed-off-by: Jo Stichbury --- vizro-ai/docs/pages/user-guides/api-setup.md | 69 -------------------- 1 file changed, 69 deletions(-) delete mode 100644 vizro-ai/docs/pages/user-guides/api-setup.md diff --git a/vizro-ai/docs/pages/user-guides/api-setup.md b/vizro-ai/docs/pages/user-guides/api-setup.md deleted file mode 100644 index 20cabc320..000000000 --- a/vizro-ai/docs/pages/user-guides/api-setup.md +++ /dev/null @@ -1,69 +0,0 @@ -# How to set up and use a large language model with Vizro-AI -Use of Vizro-AI requires the use of a large language model. At present, we only support [OpenAI](https://openai.com/). - -## Set up OpenAI -To use OpenAI with Vizro-AI you need an API key, which you can get by [creating an OpenAI account if you don't already have one](https://platform.openai.com/account/api-keys). - -!!! note - - We recommend that you consult the [third-party API key section of the disclaimer documentation](../explanation/disclaimer.md) documentation. - -### Set up the API key -There are two common ways to set up the API key in a development environment. - -#### Method 1: Set an environment variable for a single project - -To make the API key available for a single project, you can create a locacl `.env` -file to store it. Then, you can load the API key from that `.env` file in your development environment. - -!!! example "The `.env` file should look as follows (containing your key rather than `abc123`)" - === ".env" - ```text - OPENAI_API_KEY=abc123 - ``` - -By default, `vizro-ai` automatically loads the `.env` file, by searching the current directory and, if it does not find `.env`, the search continues upwards through the directory hierarchy. - -If you would like to customize the `.env` file location and name, you can manually customize the search. -The default import of the `.env` file can be overridden by specifying the path and name. -Here's how you can do it: - -```py -from dotenv import load_dotenv, find_dotenv -from pathlib import Path - -# Specify the exact path to your .env file -env_file = Path.cwd() / ".env" # Adjust the path as needed - -# Alternatively, specify a different .env file name -env_file = find_dotenv(".env.dev") # Replace ".env.dev" with your file name - -# Load the specified .env file -load_dotenv(env_file) -``` -Refer to [python-dotenv documentation](https://saurabh-kumar.com/python-dotenv/reference/) for further information. - -!!! warning "Don't share your secret API key!" - - You should avoid committing the `.env` file to version control. You can do this for Git by adding `.env` to your `.gitignore` file. - - -#### Method 2: Set an environment variable for all projects - -To make the OpenAI API key available for all projects, you can set it as a system environment -variable. Please refer to the section ["Set up your API key for all projects"](https://platform.openai.com/docs/quickstart/step-2-setup-your-api-key?context=python) -in the OpenAI documentation. (It is under the dropdown of "Step 2: Set up your API key"). - -The documentation provides step-by-step instructions for setting up the API key as an environment -variable, on operating systems including Windows and MacOS. - - -### Setup the base URL (optional) -You might need to provide the base URL if you are using a custom OpenAI resource endpoint. - -The API base URL used for the OpenAI connector is set to `https://api.openai.com/v1` by default. -If you are using a custom API endpoint, for example, if your organization has a designated API gateway, -you can change the base URL by setting it as an environment variable. - - -Follow the approach above in Method 2 to [add the environment variable `OPENAI_API_BASE` for use by all projects](#method-2-set-an-environment-variable-for-all-projects). From 74b74961bf2dc8fe8f1131bb9c59d08773439e46 Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Fri, 22 Mar 2024 15:14:01 +0000 Subject: [PATCH 03/17] Further updates to docs --- vizro-ai/docs/index.md | 4 ++-- .../docs/pages/tutorials/explore-vizro-ai.md | 4 ++-- vizro-ai/docs/pages/tutorials/quickstart.md | 21 +++++++------------ vizro-ai/docs/pages/user-guides/install.md | 11 ++-------- .../docs/pages/user-guides/run-vizro-ai.md | 4 ++-- vizro-ai/mkdocs.yml | 3 +-- 6 files changed, 17 insertions(+), 30 deletions(-) diff --git a/vizro-ai/docs/index.md b/vizro-ai/docs/index.md index 4cddb216f..f4767863b 100644 --- a/vizro-ai/docs/index.md +++ b/vizro-ai/docs/index.md @@ -21,10 +21,10 @@ If you're new to coding, Vizro-AI simplifies the process of creating charts that - +
-
User guides
+
How-to guides

Step-by-step instructions on how to use Vizro-AI.

diff --git a/vizro-ai/docs/pages/tutorials/explore-vizro-ai.md b/vizro-ai/docs/pages/tutorials/explore-vizro-ai.md index 5ae025d5a..5459dbef1 100644 --- a/vizro-ai/docs/pages/tutorials/explore-vizro-ai.md +++ b/vizro-ai/docs/pages/tutorials/explore-vizro-ai.md @@ -11,13 +11,13 @@ Before proceeding, ensure the installation of the `vizro_ai` package by followin ??? tip "Beginners/Code novices" For those new to Python or virtual environments, a user-friendly alternative is available in the [installation guide](../user-guides/install.md), offering a graphical user interface without the need for terminal commands. -A prerequisite for this tutorial is access to one of the supported large language models. Please refer to the [api setup](../user-guides/api-setup.md) for instructions on setting up the API. +A prerequisite for this tutorial is access to one of the supported large language models. Please refer to the [LLM setup guide](../user-guides/install.md#large-language-model) for instructions on setting up the API key. Upon successful setup, your API key should be ready in the environment when you import `vizro_ai`. If you would like to customize the `.env` file location and name, you can set it manually. You can override the default import of the `.env` file by specifying the path and name of your custom `.env` file. -Please refer to [API setup](../user-guides/api-setup.md) for instructions on customizing the `.env` file location and name. +Please refer to [LLM setup guide](../user-guides/install.md#large-language-model) for instructions on customizing the `.env` file location and name. ### 2. Create your visualization using different languages diff --git a/vizro-ai/docs/pages/tutorials/quickstart.md b/vizro-ai/docs/pages/tutorials/quickstart.md index 41a8903cd..e6bc6bd63 100644 --- a/vizro-ai/docs/pages/tutorials/quickstart.md +++ b/vizro-ai/docs/pages/tutorials/quickstart.md @@ -1,18 +1,17 @@ # Get started with Vizro-AI -This tutorial serves as an introduction to Vizro-AI. -It is a step-by-step guide to help you experiment and create an initial Vizro chart using Vizro-AI, which is an English-to-visualization package. The goal is to provide you with the necessary knowledge to explore further into our documentation. +This tutorial introduces you to Vizro-AI, which is an English-to-visualization package. In a series of steps, we will explain the basics and set you up with the knowledge to explore the package further. ### 1. Install Vizro and its dependencies -If you haven't already installed Vizro-AI, follow the [installation guide](../user-guides/install.md). +If you haven't already installed Vizro-AI and set up the API key for OpenAI, follow the [installation guide](../user-guides/install.md). ### 2. Open a Jupyter Notebook A good way to initially explore Vizro-AI is from inside a Jupyter Notebook. -??? "Install and run Jupyter" +??? "If you haven't used Jupyter before..." - If you haven't used Jupyter before, you may need to install the Jupyter package. From the terminal window: + You may need to install the Jupyter package if you . From the terminal window: ```bash pip install jupyter @@ -27,7 +26,7 @@ Activate the virtual environment you used to install Vizro, and start a new Note jupyter notebook ``` -The command opens Jupyter in a browser tab. Navigate to a preferred folder in which to create this new dashboard. +The command opens Jupyter in a browser tab. Use the UI to navigate to a preferred folder in which to create this new dashboard. Create a new `Python 3 (ipykernel)` Notebook from the "New" dropdown. Confirm your Vizro installation by typing the following into a cell in the Notebook and running it. @@ -40,13 +39,9 @@ print(vizro_ai.__version__) You should see a return output of the form `x.y.z`. -### 3. OpenAI API KEY +### 3. Ask your first question using Vizro-AI -Use of Vizro-AI requires an API key for the OpenAI large language model. Refer to the [API set-up user guide](../user-guides/api-setup.md) for information about how to get set up. - -### 4. Ask your first question using Vizro-AI - -For your first visualization, we will create a chart illustrating the GDP of various continents while including a reference line for the average. +We will create a chart to illustrate the GDP of various continents while including a reference line for the average. Let's go through the code step-by-step to understand how to use Vizro-AI. First, we create `pandas` DataFrame using the gapminder data from `plotly express`. Next, we instantiate `VizroAI` to call the `plot()` method to generate your visualization. @@ -88,6 +83,6 @@ Let's create another example and read through the additional information. ### 6. Explore further -Now, you have created your first charts with Vizro-AI and are ready to explore the documentation further. +Now, you have created your first charts with Vizro-AI you are ready to explore it further. A good place to start would be to go through the [model configuration](../user-guides/model-config.md) or different [run options](../user-guides/run-vizro-ai.md) including application integration. diff --git a/vizro-ai/docs/pages/user-guides/install.md b/vizro-ai/docs/pages/user-guides/install.md index 3cfcbf0ef..025306116 100644 --- a/vizro-ai/docs/pages/user-guides/install.md +++ b/vizro-ai/docs/pages/user-guides/install.md @@ -1,11 +1,6 @@ -# How to install Vizro-AI +# Install Vizro-AI -This guide shows you how to install Vizro-AI, how to verify the installation succeeded and find the version of Vizro-AI, and how to update Vizro-AI. - -If you already have a virtual environment setup in Python then you can skip this page and just install Vizro-AI straight away by running: -```bash -pip install vizro_ai -``` +In this guide you'll learn how to set up the prerequisites needed for Vizro-AI, and how to install it. You'll also find out how to verify the Vizro-AI installation succeeded, find the version of Vizro-AI, and learn how to update it. ## Prerequisites @@ -20,8 +15,6 @@ You should create a virtual environment for each Vizro-AI project you work on to If you are a beginner or coding novice, you may prefer to avoid using a terminal to work with Vizro. Skip to the ["Use Vizro-AI inside Anaconda" section](#use-vizro-ai-inside-anaconda-navigator) below. - - ??? information "How to create a virtual environment for your Vizro-AI project" The simplest way to create a virtual environment in Python is `venv`, which is included in the Python standard library. Create a directory for your project and navigate to it. For example: diff --git a/vizro-ai/docs/pages/user-guides/run-vizro-ai.md b/vizro-ai/docs/pages/user-guides/run-vizro-ai.md index d43dfa7fa..12105b888 100644 --- a/vizro-ai/docs/pages/user-guides/run-vizro-ai.md +++ b/vizro-ai/docs/pages/user-guides/run-vizro-ai.md @@ -6,7 +6,7 @@ This guide offers insights into different options of running Vizro-AI, including To run Vizro-AI in jupyter, create a new cell and execute the code below to render the described visualization. You should see the chart as an output. ??? note "Note: API key" - Make sure you have followed the [environment setup guide](../user-guides/api-setup.md) and + Make sure you have followed the [LLM setup guide](./install.md#large-language-model) and your api key is set up in a `.env` file in the same folder as your `ipynb` file. !!! example "Bar chart" @@ -31,7 +31,7 @@ Please note that the chart's appearance may not precisely resemble the one displ You can utilize Vizro-AI in any standard development environment by creating a `.py` file and executing the following code. As a result, the rendered chart will display in a browser window. ??? note "Note: API key" - Make sure you have followed [environment setup guide](../user-guides/api-setup.md) and + Make sure you have followed [LLM setup guide](./install.md#large-language-model) and your API key is set up in the environment where your `.py` script is running with command as below: ``` export OPENAI_API_KEY="your api key" diff --git a/vizro-ai/mkdocs.yml b/vizro-ai/mkdocs.yml index 1d9fbc0ec..84222b3b1 100644 --- a/vizro-ai/mkdocs.yml +++ b/vizro-ai/mkdocs.yml @@ -6,8 +6,7 @@ nav: - Install Vizro-AI: pages/user-guides/install.md - A first dashboard: pages/tutorials/quickstart.md - Explore Vizro-AI: pages/tutorials/explore-vizro-ai.md - - How-to Guides: - - LLM setup: pages/user-guides/api-setup.md + - How-to guides: - Run methods: pages/user-guides/run-vizro-ai.md - Model configuration: pages/user-guides/model-config.md - Explanation: From bd733a6df0a80500fedb694bf8c91c9a422d6a6d Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Mon, 25 Mar 2024 12:14:30 +0000 Subject: [PATCH 04/17] Another round of revisions Signed-off-by: Jo Stichbury --- vizro-ai/docs/index.md | 2 +- vizro-ai/docs/pages/contribute/authors.md | 4 +-- vizro-ai/docs/pages/explanation/disclaimer.md | 2 +- vizro-ai/docs/pages/tutorials/quickstart.md | 34 +++++++++++++++---- .../user-guides/{model-config.md => faq.md} | 0 vizro-ai/mkdocs.yml | 2 +- 6 files changed, 32 insertions(+), 12 deletions(-) rename vizro-ai/docs/pages/user-guides/{model-config.md => faq.md} (100%) diff --git a/vizro-ai/docs/index.md b/vizro-ai/docs/index.md index f4767863b..713d50cea 100644 --- a/vizro-ai/docs/index.md +++ b/vizro-ai/docs/index.md @@ -1,6 +1,6 @@ # Vizro-AI -Vizro-AI extends [Vizro] with a user-friendly interface that uses natural language capabilities to help you create interactive charts effortlessly. +Vizro-AI extends [Vizro](https://vizro.readthedocs.io) with a user-friendly interface that uses natural language capabilities to help you create interactive charts effortlessly. If you're new to coding, Vizro-AI simplifies the process of creating charts that offer detailed insights about your data. Even if you're an experienced data practitioner, Vizro-AI optimizes how you create visually appealing charts. diff --git a/vizro-ai/docs/pages/contribute/authors.md b/vizro-ai/docs/pages/contribute/authors.md index 5ec75ffc6..41d0e5a32 100644 --- a/vizro-ai/docs/pages/contribute/authors.md +++ b/vizro-ai/docs/pages/contribute/authors.md @@ -12,6 +12,6 @@ [Lingyi Zhang](https://github.com/lingyielia), [Maximilian Schulz](https://github.com/maxschulz-COL), [Nadija Graca](https://github.com/nadijagraca), -[Petar Pejovic](https://github.com/petar-qb) +[Petar Pejovic](https://github.com/petar-qb). -with thanks to Sam Bourton and Stephen Xu for sponsorship, inspiration and guidance, plus everyone else who helped to test, guide, support and encourage development. +With thanks to Sam Bourton and Stephen Xu for sponsorship, inspiration and guidance, plus everyone else who helped to test, guide, support and encourage development. diff --git a/vizro-ai/docs/pages/explanation/disclaimer.md b/vizro-ai/docs/pages/explanation/disclaimer.md index 6ad9964e1..5abb25b54 100644 --- a/vizro-ai/docs/pages/explanation/disclaimer.md +++ b/vizro-ai/docs/pages/explanation/disclaimer.md @@ -1,6 +1,6 @@ # Disclaimer -Users must select one of the [supported Large Language Models (LLMs)](../user-guides/model-config.md) in order to use the `vizro_ai` package, +Users must select one of the [supported Large Language Models (LLMs)](../user-guides/faq.md#which-llms-are-supported-by-vizro-ai) in order to use the `vizro_ai` package, and are responsible for obtaining their own suitable API key for the relevant model. ## Third party API diff --git a/vizro-ai/docs/pages/tutorials/quickstart.md b/vizro-ai/docs/pages/tutorials/quickstart.md index e6bc6bd63..e8e8c97d6 100644 --- a/vizro-ai/docs/pages/tutorials/quickstart.md +++ b/vizro-ai/docs/pages/tutorials/quickstart.md @@ -39,13 +39,33 @@ print(vizro_ai.__version__) You should see a return output of the form `x.y.z`. -### 3. Ask your first question using Vizro-AI +### 3. Create your first chart using Vizro-AI -We will create a chart to illustrate the GDP of various continents while including a reference line for the average. +We will create a chart to illustrate the GDP of various continents while including a reference line for the average by using the instruction "*describe the composition of gdp in continent and color by continent, and add a horizontal line for avg gdp*". -Let's go through the code step-by-step to understand how to use Vizro-AI. First, we create `pandas` DataFrame using the gapminder data from `plotly express`. Next, we instantiate `VizroAI` to call the `plot()` method to generate your visualization. +Let's go through the code step-by-step. First, we create `pandas` DataFrame using the gapminder data from `plotly express`: -By passing your prepared data and your written visualization request to this method, Vizro-AI takes care of the processing. It generates the necessary code for data manipulation and chart creation, and then it proceeds to render the chart by executing the generated code. +```python +from vizro_ai import VizroAI +import vizro.plotly.express as px + +df = px.data.gapminder() +``` + + +Next, we instantiate `VizroAI`: + +```python +vizro_ai = VizroAI() +``` + +Finally, we call the `plot()` method with our English language instruction, to generate the visualization: + +```python +vizro_ai.plot(df, "describe the composition of gdp in continent and color by continent, and add a horizontal line for avg gdp") +``` + +And that's it! By passing the prepared data and written visualization request, Vizro-AI takes care of the processing. It generates the necessary code for data manipulation and chart creation, and renders the chart by executing the generated code. !!! example "Vizro AI Syntax" === "Code for the cell" @@ -67,7 +87,7 @@ The created chart is interactive, and you can hover over the data for additional ### 5. Get an explanation with your chart -By passing `explain=True` to the `plot()` method will provide additional insights in addition to the rendered chart. +Passing `explain=True` to the `plot()` method provides additional insights in addition to the rendered chart. Let's create another example and read through the additional information. @@ -83,6 +103,6 @@ Let's create another example and read through the additional information. ### 6. Explore further -Now, you have created your first charts with Vizro-AI you are ready to explore it further. +Now, you have created your first charts with Vizro-AI you are ready to explore further. -A good place to start would be to go through the [model configuration](../user-guides/model-config.md) or different [run options](../user-guides/run-vizro-ai.md) including application integration. +A good place to start would be to review the different [run options](../user-guides/run-vizro-ai.md) including application integration. diff --git a/vizro-ai/docs/pages/user-guides/model-config.md b/vizro-ai/docs/pages/user-guides/faq.md similarity index 100% rename from vizro-ai/docs/pages/user-guides/model-config.md rename to vizro-ai/docs/pages/user-guides/faq.md diff --git a/vizro-ai/mkdocs.yml b/vizro-ai/mkdocs.yml index 84222b3b1..a16fdcfce 100644 --- a/vizro-ai/mkdocs.yml +++ b/vizro-ai/mkdocs.yml @@ -8,7 +8,7 @@ nav: - Explore Vizro-AI: pages/tutorials/explore-vizro-ai.md - How-to guides: - Run methods: pages/user-guides/run-vizro-ai.md - - Model configuration: pages/user-guides/model-config.md + - FAQs: pages/user-guides/faq.md - Explanation: - Disclaimer: pages/explanation/disclaimer.md - Safeguard code execution: pages/explanation/safeguard.md From 24072f2de03e95f55ebf844d307d3eebd714e5b0 Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Mon, 25 Mar 2024 12:15:09 +0000 Subject: [PATCH 05/17] Update faq.md --- vizro-ai/docs/pages/user-guides/faq.md | 40 ++++++++++++-------------- 1 file changed, 19 insertions(+), 21 deletions(-) diff --git a/vizro-ai/docs/pages/user-guides/faq.md b/vizro-ai/docs/pages/user-guides/faq.md index 1414c52d0..fb27a5220 100644 --- a/vizro-ai/docs/pages/user-guides/faq.md +++ b/vizro-ai/docs/pages/user-guides/faq.md @@ -1,4 +1,20 @@ -# How to configure Vizro-AI parameters +# Frequently asked questions + +## Which LLMs are supported by Vizro-AI? +Vizro-AI currently supports OpenAI models as follows: + +- gpt-3.5-turbo-0613 (to be deprecated on June 13, 2024) +- gpt-4-0613 +- gpt-3.5-turbo-1106 (under testing) +- gpt-4-1106-preview (under testing, not suitable for production use) + +These models provide different levels of performance and +cost. In general, the `gpt-3.5-turbo` collection provides the most cost-effective models, +which would be a good starting point for most users. `gpt-4` models are more powerful than `gpt-3` models, e.g. they allow for more tokens per request. You can refer to these models' [capabilities](https://platform.openai.com/docs/models/overview) +and [pricing](https://openai.com/pricing) for more information. + +We are working on supporting more models and more vendors. Please stay tuned! + !!! Warning @@ -10,15 +26,13 @@ Users are also recommended to review the third party API key section of the [disclaimer](../explanation/disclaimer.md) documentation. -## Supported parameters +## What parameters does Vizro-AI support? Currently, Vizro-AI supports the following parameters: - `temperature`: A parameter for tuning the randomness of the output. It is set to 0 by default. We recommend setting it to 0 for Vizro-AI usage, as it's mostly deterministic. -- `model_name`: The name of the model to use. Please refer to the section - [Models currently supported by Vizro-AI](#supported-models) for available - model options. +- `model_name`: The name of the model to use. See above for [models currently supported by Vizro-AI](#which-llms-are-supported-by-vizro-ai) for the models supported. !!! example "Config and construct Vizro-AI" === "python" @@ -30,19 +44,3 @@ Currently, Vizro-AI supports the following parameters: -## Supported models -Vizro-AI currently supports the following LLMs: - -### OpenAI models - -- gpt-3.5-turbo-0613 (to be deprecated on June 13, 2024) -- gpt-4-0613 -- gpt-3.5-turbo-1106 (under testing) -- gpt-4-1106-preview (under testing, not suitable for production use) - -These models provide different levels of performance and -cost. In general, the `gpt-3.5-turbo` collection provides the most cost-effective models, -which would be a good starting point for most users. `gpt-4` models are more powerful than `gpt-3` models, e.g. they allow for more tokens per request. You can refer to these models' [capabilities](https://platform.openai.com/docs/models/overview) -and [pricing](https://openai.com/pricing) for more information. - -We are working on supporting more models and more vendors. Please stay tuned! From 84ab2790075702f556c54414f9c6d2b0fb0b5fda Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 25 Mar 2024 12:15:49 +0000 Subject: [PATCH 06/17] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- vizro-ai/docs/pages/user-guides/faq.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/vizro-ai/docs/pages/user-guides/faq.md b/vizro-ai/docs/pages/user-guides/faq.md index fb27a5220..8f616dbab 100644 --- a/vizro-ai/docs/pages/user-guides/faq.md +++ b/vizro-ai/docs/pages/user-guides/faq.md @@ -41,6 +41,3 @@ Currently, Vizro-AI supports the following parameters: vizro_ai = VizroAI(model_name="gpt-3.5-turbo-0613", temperature=0) ``` - - - From c2bd3c6fc43b8859323ad7790eba0702f8d0daeb Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Mon, 25 Mar 2024 15:43:52 +0000 Subject: [PATCH 07/17] Update docs further --- vizro-ai/docs/pages/explanation/disclaimer.md | 2 +- vizro-ai/docs/pages/explanation/safeguard.md | 10 ++--- .../pages/explanation/safety-in-vizro-ai.md | 8 ++-- .../docs/pages/tutorials/explore-vizro-ai.md | 45 +++++++++---------- vizro-ai/docs/pages/tutorials/quickstart.md | 4 +- vizro-ai/docs/pages/user-guides/faq.md | 3 +- vizro-ai/docs/pages/user-guides/install.md | 7 +-- .../docs/pages/user-guides/run-vizro-ai.md | 37 ++++++++------- 8 files changed, 60 insertions(+), 56 deletions(-) diff --git a/vizro-ai/docs/pages/explanation/disclaimer.md b/vizro-ai/docs/pages/explanation/disclaimer.md index 5abb25b54..f34c25ffe 100644 --- a/vizro-ai/docs/pages/explanation/disclaimer.md +++ b/vizro-ai/docs/pages/explanation/disclaimer.md @@ -1,6 +1,6 @@ # Disclaimer -Users must select one of the [supported Large Language Models (LLMs)](../user-guides/faq.md#which-llms-are-supported-by-vizro-ai) in order to use the `vizro_ai` package, +Users must select one of the [supported large language models (LLMs)](../user-guides/faq.md#which-llms-are-supported-by-vizro-ai) in order to use the `vizro_ai` package, and are responsible for obtaining their own suitable API key for the relevant model. ## Third party API diff --git a/vizro-ai/docs/pages/explanation/safeguard.md b/vizro-ai/docs/pages/explanation/safeguard.md index 22c20a46c..b496f58ee 100644 --- a/vizro-ai/docs/pages/explanation/safeguard.md +++ b/vizro-ai/docs/pages/explanation/safeguard.md @@ -1,6 +1,6 @@ -# Safeguard dynamic code dxecution in Vizro-AI +# Safeguard dynamic code execution in Vizro-AI -Vizro-AI uses the `exec()` statement in Python to run generated code from Large Language Models (LLMs) for +Vizro-AI uses the `exec()` statement in Python to run generated code from large language models (LLMs) for self-debugging and automatic visual rendering in methods such as `vizro_ai._get_chart_code()` and `vizro_ai.plot()`. One of the primary concerns is the potential for malicious code to access or modify critical system resources or data. @@ -17,7 +17,7 @@ these measures cannot guarantee absolute security. It is imperative for users to ### Our effort on safeguarding code execution in Vizro-AI To help to mitigate these risks, we limit the execution of certain modules and functions. -One approach is to leverage Python's built-in sys module to restrict access to unsafe modules or functions. +One approach is to leverage Python's built-in `sys` module to restrict access to unsafe modules or functions. By defining a whitelist of safe modules and packages and restricting certain built-in functions. !!! Warning @@ -77,10 +77,10 @@ The lists below are a reflection of the security and functionality we have imple ### Safeguard for user environment and input -- **Isolated Environment**: Always run code in an isolated or contained environment, such as a virtual environment, +- **Isolated environment**: Always run code in an isolated or contained environment, such as a virtual environment, virtual machine or container, to minimize potential harm to the primary system. -- **Avoid Malicious Input**: Never feed untrusted or malicious input. Regardless of safeguards, +- **Avoid malicious input**: Never feed untrusted or malicious input. Regardless of safeguards, there's always a risk associated with executing dynamic code. It remains the user's responsibility to ensure the safety and appropriateness of executing any generated code, particularly in sensitive or critical contexts. diff --git a/vizro-ai/docs/pages/explanation/safety-in-vizro-ai.md b/vizro-ai/docs/pages/explanation/safety-in-vizro-ai.md index f11540ac4..08581471c 100644 --- a/vizro-ai/docs/pages/explanation/safety-in-vizro-ai.md +++ b/vizro-ai/docs/pages/explanation/safety-in-vizro-ai.md @@ -1,9 +1,7 @@ ## Warning and safety usage for generative AI models -Generative AI models, especially Large Language Models (LLMs) represent significant advancements in the AI field. -Vizro-AI also leverages LLMs, however, as with any powerful tool, there are potential risks associated. +Vizro-AI uses generative AI models because large language models (LLMs) represent significant advancements in the AI field. However, as with any powerful tool, there are potential risks associated with connecting to a generative AI model. -Users must connect to a generative AI model, specifically LLMs to use Vizro-AI. We recommend users research and understand the selected model before using `vizro_ai` package. Users are encouraged to treat AI-generated content as supplementary, **always apply human judgment**, @@ -13,7 +11,7 @@ approach with caution, review the relevant [disclaimer](disclaimer.md) page, and Generative models can potentially generate information while appearing factual, being entirely fictitious or misleading. The vendor models might lack real-time knowledge or events beyond its last updates. -`vizro_ai` output may vary and please always verify critical information. +`vizro_ai` output may vary and you should always verify critical information. It is the user's responsibility to discern the accuracy, consistent, and reliability of the generated content. ### 2. Unintended and sensitive output @@ -62,4 +60,4 @@ Users must exercise caution when executing code generated by or influenced by AI - Always be aware that malicious code execution cannot be mitigated with 100% certainty - Always review and understand the selected model before connecting with `vizro_ai` -If you would like to learn more about our efforts in safeguarding code execution, please refer to [Safeguard Execution of Dynamic Code](safeguard.md) for more information. +If you would like to learn more about our efforts in safeguarding code execution, refer to [Safeguard Execution of Dynamic Code](safeguard.md) for more information. diff --git a/vizro-ai/docs/pages/tutorials/explore-vizro-ai.md b/vizro-ai/docs/pages/tutorials/explore-vizro-ai.md index 5459dbef1..54d4fe6bb 100644 --- a/vizro-ai/docs/pages/tutorials/explore-vizro-ai.md +++ b/vizro-ai/docs/pages/tutorials/explore-vizro-ai.md @@ -1,29 +1,23 @@ # Explore Vizro-AI -This tutorial serves as an exploration of the extended applications offered by Vizro-AI beyond the initial [quickstart guide](../tutorials/quickstart.md). - -By the end of this tutorial, you will have gained an understanding of different language options and leveraging Vizro-AI to enhance the formatting your visualizations. - -## Let's get started! -### 1. Install Vizro-AI and get ready to run your code -Before proceeding, ensure the installation of the `vizro_ai` package by following the steps outlined in the [installation guide](../user-guides/install.md). Once installed, you can execute your code either by pasting it into a Jupyter notebook cell or running it from a Python script. +This tutorial serves as an exploration of Vizro-AI beyond the initial [quickstart guide](../tutorials/quickstart.md). It explains the different language options and shows how to use Vizro-AI to enhance the formatting your visualizations. +## Install Vizro-AI and get ready to run your code +Before proceeding, you'll need to install Vizro-AI by following the steps in the [installation guide](../user-guides/install.md). To execute code either paste it into a Jupyter Notebook or run it from a Python script, or see the [guide on how to run Vizro-AI](../user-guides/run-vizro-ai.md) for more detail. ??? tip "Beginners/Code novices" - For those new to Python or virtual environments, a user-friendly alternative is available in the [installation guide](../user-guides/install.md), offering a graphical user interface without the need for terminal commands. - -A prerequisite for this tutorial is access to one of the supported large language models. Please refer to the [LLM setup guide](../user-guides/install.md#large-language-model) for instructions on setting up the API key. -Upon successful setup, your API key should be ready in the environment when you import `vizro_ai`. + For those new to Python or virtual environments, you may prefer to [use Vizro-AI inside Anaconda Navigator](../user-guides/install.md#use-vizro-ai-inside-anaconda-navigator) to take advantage of a graphical user interface without the need for terminal commands. -If you would like to customize the `.env` file location and name, you can set it manually. -You can override the default import of the `.env` file by specifying the path and name of your custom `.env` file. -Please refer to [LLM setup guide](../user-guides/install.md#large-language-model) for instructions on customizing the `.env` file location and name. +### Set up access to a large language model +A prerequisite for this tutorial is access to one of the supported large language models. Refer to the [installation guide](../user-guides/install.md#large-language-model) for instructions on setting up an API key. -### 2. Create your visualization using different languages +Upon successful setup, your API key should be ready in the environment when you import `vizro_ai`. +## How to create visualizations using different languages Vizro-AI is versatile, supporting prompts and chart visualizations in multiple languages. Let's explore this capability with two examples, starting with Chinese where we inquire about visualizing the GDP per capita over time. !!! example "Vizro-AI Chinese" + === "Code for the cell" ```py from vizro_ai import VizroAI @@ -42,6 +36,7 @@ Vizro-AI is versatile, supporting prompts and chart visualizations in multiple l Subsequently, we'll switch to German and prompt the visualization of life expectancy in the United States over time, comparing it to the global life expectancy trend. For this example, we'll include `explain=True` to obtain comprehensive insights into both the data and the generated code. !!! example "Vizro-AI German" + === "Code for the cell" ```py from vizro_ai import VizroAI @@ -57,12 +52,13 @@ Subsequently, we'll switch to German and prompt the visualization of life expect [GermanChart]: ../../assets/tutorials/chart/GermanExample.png -### 3. Create advanced charts and formatting +## How to create advanced charts and formatting Now, let's explore more advanced visualizations and leverage Vizro-AI for enhanced formatting. -To begin, we'll create an animated bar chart illustrating the population development of each continent over time. Let's run the code below and look at the result. +To begin, we'll create an animated bar chart illustrating the population development of each continent over time. Run the code below and look at the result. !!! example "Vizro-AI animated chart" + === "Code for the cell" ```py from vizro_ai import VizroAI @@ -71,7 +67,7 @@ To begin, we'll create an animated bar chart illustrating the population develop df = px.data.gapminder() vizro_ai = VizroAI() - vizro_ai.plot(df, "The chart should be an animated stacked bar chart with popoluation on the y axis and continent on the x axis with all respective countries, allowing you to observe changes in the population over consecutive years.") + vizro_ai.plot(df, "The chart should be an animated stacked bar chart with population on the y axis and continent on the x axis with all respective countries, allowing you to observe changes in the population over consecutive years.") ``` === "Result" [![AnimatedChart1]][AnimatedChart1] @@ -81,6 +77,7 @@ To begin, we'll create an animated bar chart illustrating the population develop Having unveiled our animated bar chart showcasing population development per country, it's apparent that crucial details are overshadowed by the legend. Next, we will try to tweak our prompt to group the countries into continents and improve the overall layout. !!! example "Vizro-AI animated chart" + === "Code for the cell" ```py from vizro_ai import VizroAI @@ -89,7 +86,7 @@ Having unveiled our animated bar chart showcasing population development per cou df = px.data.gapminder() vizro_ai = VizroAI() - vizro_ai.plot(df, "The chart should be an animated stacked bar chart with popoluation on the y axis and continent on the x axis with all respective countries, allowing you to observe changes in the population over consecutive years. Please improve layout.") + vizro_ai.plot(df, "The chart should be an animated stacked bar chart with population on the y axis and continent on the x axis with all respective countries, allowing you to observe changes in the population over consecutive years. Please improve layout.") ``` === "Result" [![AnimatedChart2]][AnimatedChart2] @@ -97,11 +94,12 @@ Having unveiled our animated bar chart showcasing population development per cou [AnimatedChart2]: ../../assets/tutorials/chart/animated_bar_chart_2.png -Great, by incorporating the directive `Please improve layout`, we've successfully refined our animation and are now able to better interpret our result. +By incorporating the directive `Please improve layout`, we've successfully refined our animation and are now able to better interpret our result. -Now, upon closer inspection, two challenges emerge. Firstly, the legend overlaps the x-axis. Secondly, the y-axis range is insufficient to capture the full spectrum of Asia's population development. Let's run the code below and see how we can improve and finalize our chart. +Upon closer inspection, two challenges emerge: the legend overlaps the x-axis and the y-axis range is insufficient to capture the full spectrum of Asia's population development. Let's run the code below to improve and finalize the chart. !!! example "Vizro-AI animated chart" + === "Code for the cell" ```py from vizro_ai import VizroAI @@ -117,7 +115,8 @@ Now, upon closer inspection, two challenges emerge. Firstly, the legend overlaps [AnimatedChart3]: ../../assets/tutorials/chart/animated_bar_chart_3.png -Congratulations! You've now gained insights into harnessing the power of Vizro-AI for crafting advanced charts and elevating formatting. Don't forget, enabling `explain=True` is a good way of learning more about how a chart can be further improved and formatted. +Congratulations! You've now gained insights into harnessing the power of a LLM and Vizro-AI for crafting advanced charts and improving formatting. Don't forget, enabling `explain=True` is a good way of learning more about how a chart can be further improved and formatted. + +Advanced charts are well-suited for [Vizro](https://github.com/mckinsey/vizro/tree/main/vizro-core) dashboard applications. You can create a chart using `vizro-ai` to plug into your `vizro` dashboard in seconds! -Those advanced charts are well-suited for ('vizro')[https://github.com/mckinsey/vizro/tree/main/vizro-core] dashboard applications. Try to create a chart by `vizro-ai` and plug it in your `vizro` dashboard in seconds! ![chart-into-dashboard](../../assets/tutorials/chart_into_dashboard.gif) diff --git a/vizro-ai/docs/pages/tutorials/quickstart.md b/vizro-ai/docs/pages/tutorials/quickstart.md index e8e8c97d6..be9bdcb1e 100644 --- a/vizro-ai/docs/pages/tutorials/quickstart.md +++ b/vizro-ai/docs/pages/tutorials/quickstart.md @@ -68,6 +68,7 @@ vizro_ai.plot(df, "describe the composition of gdp in continent and color by con And that's it! By passing the prepared data and written visualization request, Vizro-AI takes care of the processing. It generates the necessary code for data manipulation and chart creation, and renders the chart by executing the generated code. !!! example "Vizro AI Syntax" + === "Code for the cell" ```py from vizro_ai import VizroAI @@ -92,6 +93,7 @@ Passing `explain=True` to the `plot()` method provides additional insights in ad Let's create another example and read through the additional information. !!! example "Specify `explain=True`" + === "Code for the cell" ```py vizro_ai.plot(df, "show me the geo distribution of life expectancy", explain=True) @@ -105,4 +107,4 @@ Let's create another example and read through the additional information. Now, you have created your first charts with Vizro-AI you are ready to explore further. -A good place to start would be to review the different [run options](../user-guides/run-vizro-ai.md) including application integration. +A good place to start would be the [Explore Vizro-AI](./explore-vizro-ai.md) tutorial or you may want to review the different [run options](../user-guides/run-vizro-ai.md) including application integration. diff --git a/vizro-ai/docs/pages/user-guides/faq.md b/vizro-ai/docs/pages/user-guides/faq.md index 8f616dbab..f6a5b8699 100644 --- a/vizro-ai/docs/pages/user-guides/faq.md +++ b/vizro-ai/docs/pages/user-guides/faq.md @@ -13,7 +13,7 @@ cost. In general, the `gpt-3.5-turbo` collection provides the most cost-effectiv which would be a good starting point for most users. `gpt-4` models are more powerful than `gpt-3` models, e.g. they allow for more tokens per request. You can refer to these models' [capabilities](https://platform.openai.com/docs/models/overview) and [pricing](https://openai.com/pricing) for more information. -We are working on supporting more models and more vendors. Please stay tuned! +We are working on supporting more models and more vendors. Stay tuned! !!! Warning @@ -35,6 +35,7 @@ Currently, Vizro-AI supports the following parameters: - `model_name`: The name of the model to use. See above for [models currently supported by Vizro-AI](#which-llms-are-supported-by-vizro-ai) for the models supported. !!! example "Config and construct Vizro-AI" + === "python" ```py linenums="1" from vizro_ai import VizroAI diff --git a/vizro-ai/docs/pages/user-guides/install.md b/vizro-ai/docs/pages/user-guides/install.md index 025306116..389d493d8 100644 --- a/vizro-ai/docs/pages/user-guides/install.md +++ b/vizro-ai/docs/pages/user-guides/install.md @@ -62,13 +62,10 @@ OPENAI_API_KEY=abc123 By default, `vizro-ai` automatically loads the `.env` file, by searching the current directory and, if it does not find `.env`, the search continues upwards through the directory hierarchy. -If you would like to customize the `.env` file location and name, you can manually customize the search. - +If you would like to customize the `.env` file location and name, you can manually customize the search to override the default and specify the path and name of a custom `.env` file. ??? example "How to override the default location of the .`env` file:" - - ```py from dotenv import load_dotenv, find_dotenv from pathlib import Path @@ -92,7 +89,7 @@ If you would like to customize the `.env` file location and name, you can manual __Method 2: Set an environment variable for all projects__ To make the OpenAI API key available for all projects, you can set it as a system environment -variable. Please refer to the section ["Set up your API key for all projects"](https://platform.openai.com/docs/quickstart/step-2-setup-your-api-key?context=python) +variable. Refer to the section ["Set up your API key for all projects"](https://platform.openai.com/docs/quickstart/step-2-setup-your-api-key?context=python) in the OpenAI documentation. (It is under the dropdown of "Step 2: Set up your API key"). The documentation provides step-by-step instructions for setting up the API key as an environment diff --git a/vizro-ai/docs/pages/user-guides/run-vizro-ai.md b/vizro-ai/docs/pages/user-guides/run-vizro-ai.md index 12105b888..121a33de5 100644 --- a/vizro-ai/docs/pages/user-guides/run-vizro-ai.md +++ b/vizro-ai/docs/pages/user-guides/run-vizro-ai.md @@ -1,15 +1,16 @@ # How to run Vizro-AI -This guide offers insights into different options of running Vizro-AI, including Jupyter notebook, Python scripts, and integration into your applications. +This guide offers insights into different ways of running Vizro-AI code, including within a Jupyter Notebook, as a Python script, or through integration into an application. -### 1. Jupyter notebook -To run Vizro-AI in jupyter, create a new cell and execute the code below to render the described visualization. You should see the chart as an output. +## Jupyter Notebook +To run Vizro-AI code in a Jupyter Notebook, create a new cell and execute the code below to render the described visualization. You should see the chart as output. ??? note "Note: API key" Make sure you have followed the [LLM setup guide](./install.md#large-language-model) and - your api key is set up in a `.env` file in the same folder as your `ipynb` file. + your api key is set up in a `.env` file in the same folder as your Notebook file (`.ipynb`). !!! example "Bar chart" + === "Code for the cell" ```py import vizro.plotly.express as px @@ -25,19 +26,22 @@ To run Vizro-AI in jupyter, create a new cell and execute the code below to rend [BarChart]: ../../assets/user_guides/bar_chart_gdp_per_continent.png -Please note that the chart's appearance may not precisely resemble the one displayed below, as it is generated by a generative AI and can vary. +Note that the chart's appearance may not precisely resemble the one displayed below, as it is generated by a generative AI and can vary. -### 2. Python script -You can utilize Vizro-AI in any standard development environment by creating a `.py` file and executing the following code. As a result, the rendered chart will display in a browser window. +## Python script +You can use Vizro-AI in any standard development environment by creating a `.py` file and executing the following code. As a result, the rendered chart will display in a browser window. ??? note "Note: API key" + Make sure you have followed [LLM setup guide](./install.md#large-language-model) and your API key is set up in the environment where your `.py` script is running with command as below: - ``` + + ```bash export OPENAI_API_KEY="your api key" ``` !!! example "Line chart" + === "example.py" ```py import vizro.plotly.express as px @@ -53,13 +57,14 @@ You can utilize Vizro-AI in any standard development environment by creating a ` [LineChart]: ../../assets/user_guides/line_chart_life_expect.png -### 3. Application integration +## Application integration -You have the possibility to integrate Vizro-AI into your application. For example, this can be achieved through a frontend that allows users to input prompts using a text field. +You may prefer to integrate Vizro-AI into an application with a UI that allows users to input prompts using a text field. Vizro-AI's `_get_chart_code` method returns the Python code string that can be used to prepare the data and create the visualization. This code is validated and debugged to ensure that it is executable and ready to be integrated. !!! example "Application integration" + === "app.py" ```py import vizro.plotly.express as px @@ -76,14 +81,16 @@ Vizro-AI's `_get_chart_code` method returns the Python code string that can be u [ResultCode]: ../../assets/user_guides/code_string_app_integration.png The returned `code_string` can be used to dynamically render charts within your application. You may have the option to encapsulate the chart within a `fig` object or convert the figure into a JSON string for further integration. -In case you would like to use the insights or code explanation, you can use `vizro_ai._run_plot_tasks(df, ..., explain=True)`, which returns a dictionary containing the code explanation and chart insights alongside the code. -### 4. `max_debug_retry` parameter in plot function +To use the insights or code explanation, you can use `vizro_ai._run_plot_tasks(df, ..., explain=True)`, which returns a dictionary containing the code explanation and chart insights alongside the code. + +### How to use `max_debug_retry` parameter in plot function - Default Value: 3 - Type: int - Brief: By default, the `max_debug_retry` is set to 3, the function will attempt to debug errors up to three times. If the errors are not resolved after the maximum number of retries, the function will cease further debugging attempts. E.g. if you would like adjust to 5 debugging attempts, you can set `max_debug_retry = 5` in the plot function: - ```py - vizro_ai.plot(df = df, user_input = "your user input", max_debug_retry= 5) - ``` + +```py +vizro_ai.plot(df = df, user_input = "your user input", max_debug_retry= 5) +``` From 8a85aa3066aadfdf0412e35d49326a4d60248efe Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Mon, 25 Mar 2024 16:57:17 +0000 Subject: [PATCH 08/17] Vale corrections --- vizro-ai/docs/pages/explanation/disclaimer.md | 5 ++++- vizro-ai/docs/pages/explanation/safeguard.md | 8 ++++---- .../docs/pages/explanation/safety-in-vizro-ai.md | 7 ++++--- vizro-ai/docs/pages/tutorials/explore-vizro-ai.md | 8 ++++---- vizro-ai/docs/pages/tutorials/quickstart.md | 12 +++++------- vizro-ai/docs/pages/user-guides/faq.md | 4 ++-- vizro-ai/docs/pages/user-guides/install.md | 7 +++---- vizro-ai/docs/pages/user-guides/run-vizro-ai.md | 8 ++++---- 8 files changed, 30 insertions(+), 29 deletions(-) diff --git a/vizro-ai/docs/pages/explanation/disclaimer.md b/vizro-ai/docs/pages/explanation/disclaimer.md index f34c25ffe..cc2d48d9a 100644 --- a/vizro-ai/docs/pages/explanation/disclaimer.md +++ b/vizro-ai/docs/pages/explanation/disclaimer.md @@ -1,8 +1,10 @@ # Disclaimer -Users must select one of the [supported large language models (LLMs)](../user-guides/faq.md#which-llms-are-supported-by-vizro-ai) in order to use the `vizro_ai` package, +Users must select one of the [supported large language models (LLMs)](../user-guides/faq.md#which-llms-are-supported-by-vizro-ai) to use the `vizro_ai` package, and are responsible for obtaining their own suitable API key for the relevant model. + + ## Third party API - Users are responsible for anything done via their own API key. @@ -33,3 +35,4 @@ The Outputs shall be verified and validated by the users and shall not be used w Users remain solely responsible for the use of the Output, in particular, the users will need to determine the level of human oversight needed to be given the context and use case, as well as for informing the users’ personnel and other affected users about the nature of the GenAI Output. Users are also fully responsible for their decisions, actions, use of Vizro and Vizro-AI and compliance with applicable laws, rules, and regulations, including but not limited to confirming that the Outputs do not infringe any third-party rights. + \ No newline at end of file diff --git a/vizro-ai/docs/pages/explanation/safeguard.md b/vizro-ai/docs/pages/explanation/safeguard.md index b496f58ee..c7e96c524 100644 --- a/vizro-ai/docs/pages/explanation/safeguard.md +++ b/vizro-ai/docs/pages/explanation/safeguard.md @@ -2,22 +2,22 @@ Vizro-AI uses the `exec()` statement in Python to run generated code from large language models (LLMs) for self-debugging and automatic visual rendering in methods such as `vizro_ai._get_chart_code()` and `vizro_ai.plot()`. -One of the primary concerns is the potential for malicious code to access or modify critical system resources or data. +One of the primary concerns is the potential for malicious code to access or change critical system resources or data. ## Understand `exec()` -The `exec()` function allows for the dynamic execution of Python programs which can either be a string or object code. +The `exec()` function enables the dynamic execution of Python programs which can either be a string or object code. While it offers great flexibility, it also poses a significant security risk, especially when executing untrusted code. ## Safeguarding code execution While we have made considerable efforts to safeguard its usage by limiting the usage to specific modules and functions and by restricting certain built-in operations, -these measures cannot guarantee absolute security. It is imperative for users to take additional precautions. +these measures cannot guarantee absolute security. It is imperative for users to take extra precautions. ### Our effort on safeguarding code execution in Vizro-AI To help to mitigate these risks, we limit the execution of certain modules and functions. -One approach is to leverage Python's built-in `sys` module to restrict access to unsafe modules or functions. +One approach is to use Python's built-in `sys` module to restrict access to unsafe modules or functions. By defining a whitelist of safe modules and packages and restricting certain built-in functions. !!! Warning diff --git a/vizro-ai/docs/pages/explanation/safety-in-vizro-ai.md b/vizro-ai/docs/pages/explanation/safety-in-vizro-ai.md index 08581471c..5c9601b0f 100644 --- a/vizro-ai/docs/pages/explanation/safety-in-vizro-ai.md +++ b/vizro-ai/docs/pages/explanation/safety-in-vizro-ai.md @@ -8,8 +8,9 @@ Users are encouraged to treat AI-generated content as supplementary, **always ap approach with caution, review the relevant [disclaimer](disclaimer.md) page, and consider the following: ### 1. Hallucination and misrepresentation - + Generative models can potentially generate information while appearing factual, being entirely fictitious or misleading. + The vendor models might lack real-time knowledge or events beyond its last updates. `vizro_ai` output may vary and you should always verify critical information. It is the user's responsibility to discern the accuracy, consistent, and reliability of the generated content. @@ -42,14 +43,14 @@ It's crucial for users to remain informed, cautious, and ethical in their applic It may occur that dependencies of `vizro_ai` get flagged by code scanners and other information security tools. As a consequence it may happen that `vizro_ai` also get flagged. -While we aim to resolve any flagged issues as soon as possible, there may not always be an immediate available fix, especially in a very dynamic environment such as generative AI. We encourage users to investigate if any flagged information security issues are actually related +While we aim to resolve any flagged issues as soon as possible, there may not always be an immediate available fix, especially in a dynamic environment such as generative AI. We encourage users to investigate if any flagged information security issues are actually related to any functionality used in our code base or if they only concern functionality outside the scope of `vizro_ai`. In case those issues are related to code execution, note that `vizro_ai` has its own process of executing dynamic code (see [Safeguard Execution of Dynamic Code](safeguard.md)), and does not rely on its dependencies to do so. ## Execution of dynamic code in Vizro-AI -The `exec()` statement is used in `vizro_ai`. It allows for dynamic execution of Python programs which can be powerful, but can also pose security risk +The `exec()` statement is used in `vizro_ai`. It enables dynamic execution of Python programs which can be powerful, but can also pose security risk if used without caution. When paired with outputs from generative models, there is potential for unintended or malicious code execution. Users must exercise caution when executing code generated by or influenced by AI models. It's essential to: diff --git a/vizro-ai/docs/pages/tutorials/explore-vizro-ai.md b/vizro-ai/docs/pages/tutorials/explore-vizro-ai.md index 54d4fe6bb..acc835de6 100644 --- a/vizro-ai/docs/pages/tutorials/explore-vizro-ai.md +++ b/vizro-ai/docs/pages/tutorials/explore-vizro-ai.md @@ -14,7 +14,7 @@ A prerequisite for this tutorial is access to one of the supported large languag Upon successful setup, your API key should be ready in the environment when you import `vizro_ai`. ## How to create visualizations using different languages -Vizro-AI is versatile, supporting prompts and chart visualizations in multiple languages. Let's explore this capability with two examples, starting with Chinese where we inquire about visualizing the GDP per capita over time. +Vizro-AI is versatile, supporting prompts and chart visualizations in languages other than English. Let's explore this capability with two examples, starting with Chinese where we inquire about visualizing the GDP per capita over time. !!! example "Vizro-AI Chinese" @@ -53,7 +53,7 @@ Subsequently, we'll switch to German and prompt the visualization of life expect [GermanChart]: ../../assets/tutorials/chart/GermanExample.png ## How to create advanced charts and formatting -Now, let's explore more advanced visualizations and leverage Vizro-AI for enhanced formatting. +Now, let's explore more advanced visualizations and use Vizro-AI for enhanced formatting. To begin, we'll create an animated bar chart illustrating the population development of each continent over time. Run the code below and look at the result. @@ -74,7 +74,7 @@ To begin, we'll create an animated bar chart illustrating the population develop [AnimatedChart1]: ../../assets/tutorials/chart/animated_bar_chart_1.png -Having unveiled our animated bar chart showcasing population development per country, it's apparent that crucial details are overshadowed by the legend. Next, we will try to tweak our prompt to group the countries into continents and improve the overall layout. +Having unveiled our animated bar chart showcasing population development per country, it's clear that crucial details are overshadowed by the legend. Next, we will try to tweak our prompt to group the countries into continents and improve the overall layout. !!! example "Vizro-AI animated chart" @@ -96,7 +96,7 @@ Having unveiled our animated bar chart showcasing population development per cou By incorporating the directive `Please improve layout`, we've successfully refined our animation and are now able to better interpret our result. -Upon closer inspection, two challenges emerge: the legend overlaps the x-axis and the y-axis range is insufficient to capture the full spectrum of Asia's population development. Let's run the code below to improve and finalize the chart. +Upon closer inspection, two challenges emerge: the legend overlaps the x-axis and the y-axis range is insufficient to capture the full spectrum of Asia's population development. Let's run the code below to improve the chart. !!! example "Vizro-AI animated chart" diff --git a/vizro-ai/docs/pages/tutorials/quickstart.md b/vizro-ai/docs/pages/tutorials/quickstart.md index be9bdcb1e..61edb29fa 100644 --- a/vizro-ai/docs/pages/tutorials/quickstart.md +++ b/vizro-ai/docs/pages/tutorials/quickstart.md @@ -41,7 +41,7 @@ You should see a return output of the form `x.y.z`. ### 3. Create your first chart using Vizro-AI -We will create a chart to illustrate the GDP of various continents while including a reference line for the average by using the instruction "*describe the composition of gdp in continent and color by continent, and add a horizontal line for avg gdp*". +Let's create a chart to illustrate the GDP of various continents while including a reference line for the average. We give Vizro-AI the English language instruction "*describe the composition of GDP in continent and color by continent, and add a horizontal line for avg GDP*". Let's go through the code step-by-step. First, we create `pandas` DataFrame using the gapminder data from `plotly express`: @@ -62,7 +62,7 @@ vizro_ai = VizroAI() Finally, we call the `plot()` method with our English language instruction, to generate the visualization: ```python -vizro_ai.plot(df, "describe the composition of gdp in continent and color by continent, and add a horizontal line for avg gdp") +vizro_ai.plot(df, "describe the composition of GDP in continent and color by continent, and add a horizontal line for avg GDP") ``` And that's it! By passing the prepared data and written visualization request, Vizro-AI takes care of the processing. It generates the necessary code for data manipulation and chart creation, and renders the chart by executing the generated code. @@ -77,20 +77,18 @@ And that's it! By passing the prepared data and written visualization request, V df = px.data.gapminder() vizro_ai = VizroAI() - vizro_ai.plot(df, "describe the composition of gdp in continent and color by continent, and add a horizontal line for avg gdp") + vizro_ai.plot(df, "describe the composition of GDP in continent and color by continent, and add a horizontal line for avg GDP") ``` === "Result" [![BarChart]][BarChart] [BarChart]: ../../assets/tutorials/chart/GDP_Composition_Bar.png -The created chart is interactive, and you can hover over the data for additional information. +The created chart is interactive: you can hover over the data for more information. ### 5. Get an explanation with your chart -Passing `explain=True` to the `plot()` method provides additional insights in addition to the rendered chart. - -Let's create another example and read through the additional information. +Passing `explain=True` to the `plot()` method provides insights to explain the rendered chart in detail. Let's create another example to illustrate the information returned: !!! example "Specify `explain=True`" diff --git a/vizro-ai/docs/pages/user-guides/faq.md b/vizro-ai/docs/pages/user-guides/faq.md index f6a5b8699..dbd6fc937 100644 --- a/vizro-ai/docs/pages/user-guides/faq.md +++ b/vizro-ai/docs/pages/user-guides/faq.md @@ -8,9 +8,9 @@ Vizro-AI currently supports OpenAI models as follows: - gpt-3.5-turbo-1106 (under testing) - gpt-4-1106-preview (under testing, not suitable for production use) -These models provide different levels of performance and +These models offer different levels of performance and cost. In general, the `gpt-3.5-turbo` collection provides the most cost-effective models, -which would be a good starting point for most users. `gpt-4` models are more powerful than `gpt-3` models, e.g. they allow for more tokens per request. You can refer to these models' [capabilities](https://platform.openai.com/docs/models/overview) +which would be a good starting point for most users. `gpt-4` models are more powerful than `gpt-3` models, for example, they use more tokens per request. You can refer to these models' [capabilities](https://platform.openai.com/docs/models/overview) and [pricing](https://openai.com/pricing) for more information. We are working on supporting more models and more vendors. Stay tuned! diff --git a/vizro-ai/docs/pages/user-guides/install.md b/vizro-ai/docs/pages/user-guides/install.md index 389d493d8..de90892dd 100644 --- a/vizro-ai/docs/pages/user-guides/install.md +++ b/vizro-ai/docs/pages/user-guides/install.md @@ -95,10 +95,9 @@ in the OpenAI documentation. (It is under the dropdown of "Step 2: Set up your A The documentation provides step-by-step instructions for setting up the API key as an environment variable, on operating systems including Windows and MacOS. - __Set the base URL (optional)__ -You might need to provide the base URL if you are using a custom OpenAI resource endpoint. +You might need to give the base URL if you are using a custom OpenAI resource endpoint. The API base URL used for the OpenAI connector is set to `https://api.openai.com/v1` by default. If you are using a custom API endpoint, for example, if your organization has a designated API gateway, @@ -129,12 +128,12 @@ To completely avoid terminal usage, follow these steps to work with Vizro-AI: 4. Similarly, search `jupyter` and install it. -5. [Launch a Jupyter notebook](https://problemsolvingwithpython.com/02-Jupyter-Notebooks/02.04-Opening-a-Jupyter-Notebook/#open-a-jupyter-notebook-with-anaconda-navigator) to work with Vizro-AI. +5. [Launch a Jupyter Notebook](https://problemsolvingwithpython.com/02-Jupyter-Notebooks/02.04-Opening-a-Jupyter-Notebook/#open-a-jupyter-notebook-with-anaconda-navigator) to work with Vizro-AI. ## Confirm a successful installation -To confirm the installation was successful, and verify the version of Vizro-AI installed, call the following. You can do this from within a Jupyter notebook cell, or run the following as a Python script: +To confirm the installation was successful, and verify the version of Vizro-AI installed, call the following. You can do this from within a Jupyter Notebook cell, or run the following as a Python script: ```py import vizro_ai diff --git a/vizro-ai/docs/pages/user-guides/run-vizro-ai.md b/vizro-ai/docs/pages/user-guides/run-vizro-ai.md index 121a33de5..68e0fd2d2 100644 --- a/vizro-ai/docs/pages/user-guides/run-vizro-ai.md +++ b/vizro-ai/docs/pages/user-guides/run-vizro-ai.md @@ -59,7 +59,7 @@ You can use Vizro-AI in any standard development environment by creating a `.py` ## Application integration -You may prefer to integrate Vizro-AI into an application with a UI that allows users to input prompts using a text field. +You may prefer to integrate Vizro-AI into an application with a UI that users use to input prompts using a text field. Vizro-AI's `_get_chart_code` method returns the Python code string that can be used to prepare the data and create the visualization. This code is validated and debugged to ensure that it is executable and ready to be integrated. @@ -87,9 +87,9 @@ To use the insights or code explanation, you can use `vizro_ai._run_plot_tasks(d ### How to use `max_debug_retry` parameter in plot function - Default Value: 3 - Type: int -- Brief: By default, the `max_debug_retry` is set to 3, the function will attempt to debug errors up to three times. -If the errors are not resolved after the maximum number of retries, the function will cease further debugging attempts. -E.g. if you would like adjust to 5 debugging attempts, you can set `max_debug_retry = 5` in the plot function: +- Brief: By default, the `max_debug_retry` is set to 3, the function will try to debug errors up to three times. +If the errors are not resolved after the maximum number of retries, the function will stop further debugging retries. +For example, if you would like adjust to 5 retries, you can set `max_debug_retry = 5` in the plot function: ```py vizro_ai.plot(df = df, user_input = "your user input", max_debug_retry= 5) From f05e58fbdc370eb3cf3ff3cc77f2c24e316d78fa Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 25 Mar 2024 17:03:18 +0000 Subject: [PATCH 09/17] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- vizro-ai/docs/pages/explanation/disclaimer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vizro-ai/docs/pages/explanation/disclaimer.md b/vizro-ai/docs/pages/explanation/disclaimer.md index cc2d48d9a..ed66cd4cc 100644 --- a/vizro-ai/docs/pages/explanation/disclaimer.md +++ b/vizro-ai/docs/pages/explanation/disclaimer.md @@ -35,4 +35,4 @@ The Outputs shall be verified and validated by the users and shall not be used w Users remain solely responsible for the use of the Output, in particular, the users will need to determine the level of human oversight needed to be given the context and use case, as well as for informing the users’ personnel and other affected users about the nature of the GenAI Output. Users are also fully responsible for their decisions, actions, use of Vizro and Vizro-AI and compliance with applicable laws, rules, and regulations, including but not limited to confirming that the Outputs do not infringe any third-party rights. - \ No newline at end of file + From 0a96c3c93ba63ba3d5897f312753fd3abdb29ea0 Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Mon, 25 Mar 2024 17:03:38 +0000 Subject: [PATCH 10/17] Create 20240325_170323_jo_stichbury_revise_vizro_ai_docs.md --- ...70323_jo_stichbury_revise_vizro_ai_docs.md | 48 +++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 vizro-ai/changelog.d/20240325_170323_jo_stichbury_revise_vizro_ai_docs.md diff --git a/vizro-ai/changelog.d/20240325_170323_jo_stichbury_revise_vizro_ai_docs.md b/vizro-ai/changelog.d/20240325_170323_jo_stichbury_revise_vizro_ai_docs.md new file mode 100644 index 000000000..f1f65e73c --- /dev/null +++ b/vizro-ai/changelog.d/20240325_170323_jo_stichbury_revise_vizro_ai_docs.md @@ -0,0 +1,48 @@ + + + + + + + + + From 450b7418b7a7ed931527a14bb317cce43357f9d1 Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Tue, 26 Mar 2024 09:57:55 +0000 Subject: [PATCH 11/17] Update vizro-ai/docs/pages/explanation/safety-in-vizro-ai.md Co-authored-by: Li Nguyen <90609403+huong-li-nguyen@users.noreply.github.com> Signed-off-by: Jo Stichbury --- vizro-ai/docs/pages/explanation/safety-in-vizro-ai.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vizro-ai/docs/pages/explanation/safety-in-vizro-ai.md b/vizro-ai/docs/pages/explanation/safety-in-vizro-ai.md index 5c9601b0f..144b13397 100644 --- a/vizro-ai/docs/pages/explanation/safety-in-vizro-ai.md +++ b/vizro-ai/docs/pages/explanation/safety-in-vizro-ai.md @@ -61,4 +61,4 @@ Users must exercise caution when executing code generated by or influenced by AI - Always be aware that malicious code execution cannot be mitigated with 100% certainty - Always review and understand the selected model before connecting with `vizro_ai` -If you would like to learn more about our efforts in safeguarding code execution, refer to [Safeguard Execution of Dynamic Code](safeguard.md) for more information. +To learn more, refer to the section that describes how to [safeguard execution of dynamic code](safeguard.md). From f90b9b2cfcc232c955fc6f31458b9ee3934fbd8f Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Tue, 26 Mar 2024 09:58:10 +0000 Subject: [PATCH 12/17] Update vizro-ai/docs/pages/tutorials/explore-vizro-ai.md Co-authored-by: Li Nguyen <90609403+huong-li-nguyen@users.noreply.github.com> Signed-off-by: Jo Stichbury --- vizro-ai/docs/pages/tutorials/explore-vizro-ai.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vizro-ai/docs/pages/tutorials/explore-vizro-ai.md b/vizro-ai/docs/pages/tutorials/explore-vizro-ai.md index acc835de6..4eb40855b 100644 --- a/vizro-ai/docs/pages/tutorials/explore-vizro-ai.md +++ b/vizro-ai/docs/pages/tutorials/explore-vizro-ai.md @@ -1,5 +1,5 @@ # Explore Vizro-AI -This tutorial serves as an exploration of Vizro-AI beyond the initial [quickstart guide](../tutorials/quickstart.md). It explains the different language options and shows how to use Vizro-AI to enhance the formatting your visualizations. +This tutorial serves as an exploration of Vizro-AI beyond the initial [quickstart guide](../tutorials/quickstart.md). It explains the different language options and shows how to use Vizro-AI to enhance the formatting of your visualizations. ## Install Vizro-AI and get ready to run your code Before proceeding, you'll need to install Vizro-AI by following the steps in the [installation guide](../user-guides/install.md). To execute code either paste it into a Jupyter Notebook or run it from a Python script, or see the [guide on how to run Vizro-AI](../user-guides/run-vizro-ai.md) for more detail. From 376b345baaca9218b3d6215a72831ad1b75ca5d0 Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Tue, 26 Mar 2024 09:59:53 +0000 Subject: [PATCH 13/17] Update vizro-ai/docs/pages/tutorials/quickstart.md Co-authored-by: Li Nguyen <90609403+huong-li-nguyen@users.noreply.github.com> Signed-off-by: Jo Stichbury --- vizro-ai/docs/pages/tutorials/quickstart.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vizro-ai/docs/pages/tutorials/quickstart.md b/vizro-ai/docs/pages/tutorials/quickstart.md index 61edb29fa..fbe044aa2 100644 --- a/vizro-ai/docs/pages/tutorials/quickstart.md +++ b/vizro-ai/docs/pages/tutorials/quickstart.md @@ -43,7 +43,7 @@ You should see a return output of the form `x.y.z`. Let's create a chart to illustrate the GDP of various continents while including a reference line for the average. We give Vizro-AI the English language instruction "*describe the composition of GDP in continent and color by continent, and add a horizontal line for avg GDP*". -Let's go through the code step-by-step. First, we create `pandas` DataFrame using the gapminder data from `plotly express`: +Let's go through the code step-by-step. First, we create a `pandas` DataFrame using the gapminder data from `plotly express`: ```python from vizro_ai import VizroAI From e12d8dfbd6fd66521e119a046883e81722d357ec Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Tue, 26 Mar 2024 10:00:10 +0000 Subject: [PATCH 14/17] Update vizro-ai/docs/pages/user-guides/install.md Co-authored-by: Li Nguyen <90609403+huong-li-nguyen@users.noreply.github.com> Signed-off-by: Jo Stichbury --- vizro-ai/docs/pages/user-guides/install.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vizro-ai/docs/pages/user-guides/install.md b/vizro-ai/docs/pages/user-guides/install.md index de90892dd..df8f02a07 100644 --- a/vizro-ai/docs/pages/user-guides/install.md +++ b/vizro-ai/docs/pages/user-guides/install.md @@ -5,7 +5,7 @@ In this guide you'll learn how to set up the prerequisites needed for Vizro-AI, ## Prerequisites ### Python -Vizro-AI supports macOS, Linux, and Windows. It works with Python 3.8 and later. You can specify the version of Python to use with Vizro-AI when you set up a virtual environment. +Vizro-AI supports macOS, Linux, and Windows. It works with Python 3.9 and later. You can specify the version of Python to use with Vizro-AI when you set up a virtual environment. ### Virtual environment From d56acefc66633ae92653fcf4e87665bb1feac9fb Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Tue, 26 Mar 2024 10:07:30 +0000 Subject: [PATCH 15/17] Changes following review --- vizro-ai/docs/index.md | 9 ++++----- vizro-ai/docs/pages/user-guides/faq.md | 2 +- vizro-ai/docs/pages/user-guides/install.md | 4 ++-- vizro-ai/mkdocs.yml | 2 +- 4 files changed, 8 insertions(+), 9 deletions(-) diff --git a/vizro-ai/docs/index.md b/vizro-ai/docs/index.md index 713d50cea..96e023333 100644 --- a/vizro-ai/docs/index.md +++ b/vizro-ai/docs/index.md @@ -1,11 +1,10 @@ # Vizro-AI -Vizro-AI extends [Vizro](https://vizro.readthedocs.io) with a user-friendly interface that uses natural language capabilities to help you create interactive charts effortlessly. +Vizro-AI extends [Vizro](https://vizro.readthedocs.io) to enable a user to use English or other languages to effortlessly create create interactive charts with [Plotly](https://plotly.com/python/). If you're new to coding, Vizro-AI simplifies the process of creating charts that offer detailed insights about your data. Even if you're an experienced data practitioner, Vizro-AI optimizes how you create visually appealing charts. -* It uses Vizro's themes, which incorporate design best practices by default. -* It uses [Plotly](https://plotly.com/python/) and makes it easy to integrate the interactive charts it generates seamlessly into dashboard applications. +Vizro-AI uses a large language model and Plotly to generate code for an interactive chart that you can add into a [Vizro dashboard application](https://vizro.readthedocs.io). By using Vizro's themes, you can incorporate design best practices by default.
@@ -26,7 +25,7 @@ If you're new to coding, Vizro-AI simplifies the process of creating charts that
How-to guides

- Step-by-step instructions on how to use Vizro-AI. + How to run Vizro-AI and frequently asked questions.

@@ -62,6 +61,6 @@ If you're new to coding, Vizro-AI simplifies the process of creating charts that Please review this [disclaimer](pages/explanation/disclaimer.md) before using the `vizro-ai` package. - Users must connect to Large Language Models (LLMs) to use Vizro-AI. + Users must connect to large language models (LLMs) to use Vizro-AI. Please review our [guidelines on the use of LLMs](pages/explanation/safety-in-vizro-ai.md) and the required [safeguarding for dynamic code evaluation](pages/explanation/safeguard.md). diff --git a/vizro-ai/docs/pages/user-guides/faq.md b/vizro-ai/docs/pages/user-guides/faq.md index dbd6fc937..a9b8d30cd 100644 --- a/vizro-ai/docs/pages/user-guides/faq.md +++ b/vizro-ai/docs/pages/user-guides/faq.md @@ -18,7 +18,7 @@ We are working on supporting more models and more vendors. Stay tuned! !!! Warning - Users are recommended to exercise caution and to research and understand the selected Large Language Model (LLM) before using `vizro_ai`. + Users are recommended to exercise caution and to research and understand the selected large language model (LLM) before using `vizro_ai`. Users should be cautious about sharing or inputting any personal or sensitive information. **Data is sent to model vendors if you connect to LLMs via their APIs.** diff --git a/vizro-ai/docs/pages/user-guides/install.md b/vizro-ai/docs/pages/user-guides/install.md index de90892dd..b11e0b954 100644 --- a/vizro-ai/docs/pages/user-guides/install.md +++ b/vizro-ai/docs/pages/user-guides/install.md @@ -8,7 +8,7 @@ In this guide you'll learn how to set up the prerequisites needed for Vizro-AI, Vizro-AI supports macOS, Linux, and Windows. It works with Python 3.8 and later. You can specify the version of Python to use with Vizro-AI when you set up a virtual environment. -### Virtual environment +### Set up a virtual environment You should create a virtual environment for each Vizro-AI project you work on to isolate its Python dependencies from those of other projects. See the following references to learn more about [Python virtual environments](https://realpython.com/python-virtual-environments-a-primer/), [Conda virtual environments](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html#starting-conda) or [watch an explainer video about them](https://youtu.be/YKfAwIItO7M). !!! tip "Prefer to use Vizro-AI without opening a terminal window?" @@ -37,7 +37,7 @@ You should create a virtual environment for each Vizro-AI project you work on to conda activate vizroai-environment ``` -### Large language model +### Set up access to a large language model Use of Vizro-AI requires the use of a large language model. At present, we only support [OpenAI](https://openai.com/). diff --git a/vizro-ai/mkdocs.yml b/vizro-ai/mkdocs.yml index a16fdcfce..dd030ca6f 100644 --- a/vizro-ai/mkdocs.yml +++ b/vizro-ai/mkdocs.yml @@ -4,7 +4,7 @@ nav: - Vizro-AI: index.md - Get started: - Install Vizro-AI: pages/user-guides/install.md - - A first dashboard: pages/tutorials/quickstart.md + - A first example: pages/tutorials/quickstart.md - Explore Vizro-AI: pages/tutorials/explore-vizro-ai.md - How-to guides: - Run methods: pages/user-guides/run-vizro-ai.md From 203831041691284717a6eb098e4712524cb332f0 Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Tue, 26 Mar 2024 12:20:16 +0000 Subject: [PATCH 16/17] changes following review --- vizro-ai/docs/index.md | 4 +- .../{user-guides => get-started}/install.md | 20 ------ .../{tutorials => get-started}/quickstart.md | 7 +- .../user-guides/create-advanced-charts.md | 68 +++++++++++++++++++ .../docs/pages/user-guides/run-vizro-ai.md | 4 +- .../use-different-languages.md} | 17 +---- vizro-ai/mkdocs.yml | 7 +- 7 files changed, 79 insertions(+), 48 deletions(-) rename vizro-ai/docs/pages/{user-guides => get-started}/install.md (84%) rename vizro-ai/docs/pages/{tutorials => get-started}/quickstart.md (88%) create mode 100644 vizro-ai/docs/pages/user-guides/create-advanced-charts.md rename vizro-ai/docs/pages/{tutorials/explore-vizro-ai.md => user-guides/use-different-languages.md} (78%) diff --git a/vizro-ai/docs/index.md b/vizro-ai/docs/index.md index 96e023333..ff4a61fe0 100644 --- a/vizro-ai/docs/index.md +++ b/vizro-ai/docs/index.md @@ -9,7 +9,7 @@ Vizro-AI uses a large language model and Plotly to generate code for an interact
- +
Get started
@@ -25,7 +25,7 @@ Vizro-AI uses a large language model and Plotly to generate code for an interact
How-to guides

- How to run Vizro-AI and frequently asked questions. + How to guides about Vizro-AI and frequently asked questions.

diff --git a/vizro-ai/docs/pages/user-guides/install.md b/vizro-ai/docs/pages/get-started/install.md similarity index 84% rename from vizro-ai/docs/pages/user-guides/install.md rename to vizro-ai/docs/pages/get-started/install.md index b9cdf1b28..53dc7e923 100644 --- a/vizro-ai/docs/pages/user-guides/install.md +++ b/vizro-ai/docs/pages/get-started/install.md @@ -11,10 +11,6 @@ Vizro-AI supports macOS, Linux, and Windows. It works with Python 3.9 and later. ### Set up a virtual environment You should create a virtual environment for each Vizro-AI project you work on to isolate its Python dependencies from those of other projects. See the following references to learn more about [Python virtual environments](https://realpython.com/python-virtual-environments-a-primer/), [Conda virtual environments](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html#starting-conda) or [watch an explainer video about them](https://youtu.be/YKfAwIItO7M). -!!! tip "Prefer to use Vizro-AI without opening a terminal window?" - - If you are a beginner or coding novice, you may prefer to avoid using a terminal to work with Vizro. Skip to the ["Use Vizro-AI inside Anaconda" section](#use-vizro-ai-inside-anaconda-navigator) below. - ??? information "How to create a virtual environment for your Vizro-AI project" The simplest way to create a virtual environment in Python is `venv`, which is included in the Python standard library. Create a directory for your project and navigate to it. For example: @@ -115,22 +111,6 @@ To install Vizro-AI, use [`pip`](https://pip.pypa.io/en/stable/) in your termina pip install vizro_ai ``` -## Use Vizro-AI inside Anaconda Navigator - -To completely avoid terminal usage, follow these steps to work with Vizro-AI: - - -1. Install [Anaconda Navigator](https://www.anaconda.com/download). - -2. Create a new environment as [outlined in the Anaconda documentation](https://docs.anaconda.com/free/navigator/tutorials/manage-environments/). Choose a Python version `>=3.8`. - -3. Search `vizro_ai` and install it [using the Anaconda Navigator package manager](https://docs.anaconda.com/free/navigator/tutorials/manage-packages/). - -4. Similarly, search `jupyter` and install it. - -5. [Launch a Jupyter Notebook](https://problemsolvingwithpython.com/02-Jupyter-Notebooks/02.04-Opening-a-Jupyter-Notebook/#open-a-jupyter-notebook-with-anaconda-navigator) to work with Vizro-AI. - - ## Confirm a successful installation To confirm the installation was successful, and verify the version of Vizro-AI installed, call the following. You can do this from within a Jupyter Notebook cell, or run the following as a Python script: diff --git a/vizro-ai/docs/pages/tutorials/quickstart.md b/vizro-ai/docs/pages/get-started/quickstart.md similarity index 88% rename from vizro-ai/docs/pages/tutorials/quickstart.md rename to vizro-ai/docs/pages/get-started/quickstart.md index fbe044aa2..c3f94e9c6 100644 --- a/vizro-ai/docs/pages/tutorials/quickstart.md +++ b/vizro-ai/docs/pages/get-started/quickstart.md @@ -3,7 +3,7 @@ This tutorial introduces you to Vizro-AI, which is an English-to-visualization p ### 1. Install Vizro and its dependencies -If you haven't already installed Vizro-AI and set up the API key for OpenAI, follow the [installation guide](../user-guides/install.md). +If you haven't already installed Vizro-AI and set up the API key for OpenAI, follow the [installation guide](../get-started/install.md). ### 2. Open a Jupyter Notebook @@ -17,9 +17,6 @@ A good way to initially explore Vizro-AI is from inside a Jupyter Notebook. pip install jupyter ``` - Alternatively, you can [work within Anaconda Navigator](../user-guides/install.md#use-vizro-inside-anaconda-navigator) as described in the Vizro installation guide. - - Activate the virtual environment you used to install Vizro, and start a new Notebook as follows: ```bash @@ -105,4 +102,4 @@ Passing `explain=True` to the `plot()` method provides insights to explain the r Now, you have created your first charts with Vizro-AI you are ready to explore further. -A good place to start would be the [Explore Vizro-AI](./explore-vizro-ai.md) tutorial or you may want to review the different [run options](../user-guides/run-vizro-ai.md) including application integration. +A good place to start would be to review the different how-to guides, such as [how to run Vizro-AI](../user-guides/run-vizro-ai.md), [how to create visualizations using different languages](../user-guides/use-different-languages.md), and [how to create advanced charts](../user-guides/create-advanced-charts.md). diff --git a/vizro-ai/docs/pages/user-guides/create-advanced-charts.md b/vizro-ai/docs/pages/user-guides/create-advanced-charts.md new file mode 100644 index 000000000..1318fbf9c --- /dev/null +++ b/vizro-ai/docs/pages/user-guides/create-advanced-charts.md @@ -0,0 +1,68 @@ +# How to create advanced charts +Now, let's explore more advanced visualizations and use Vizro-AI for enhanced formatting. + +To begin, we'll create an animated bar chart illustrating the population development of each continent over time. Run the code below and look at the result. + +!!! example "Vizro-AI animated chart" + + === "Code for the cell" + ```py + from vizro_ai import VizroAI + import vizro.plotly.express as px + + df = px.data.gapminder() + + vizro_ai = VizroAI() + vizro_ai.plot(df, "The chart should be an animated stacked bar chart with population on the y axis and continent on the x axis with all respective countries, allowing you to observe changes in the population over consecutive years.") + ``` + === "Result" + [![AnimatedChart1]][AnimatedChart1] + + [AnimatedChart1]: ../../assets/tutorials/chart/animated_bar_chart_1.png + +Having unveiled our animated bar chart showcasing population development per country, it's clear that crucial details are overshadowed by the legend. Next, we will try to tweak our prompt to group the countries into continents and improve the overall layout. + +!!! example "Vizro-AI animated chart" + + === "Code for the cell" + ```py + from vizro_ai import VizroAI + import vizro.plotly.express as px + + df = px.data.gapminder() + + vizro_ai = VizroAI() + vizro_ai.plot(df, "The chart should be an animated stacked bar chart with population on the y axis and continent on the x axis with all respective countries, allowing you to observe changes in the population over consecutive years. Please improve layout.") + ``` + === "Result" + [![AnimatedChart2]][AnimatedChart2] + + [AnimatedChart2]: ../../assets/tutorials/chart/animated_bar_chart_2.png + + +By incorporating the directive `Please improve layout`, we've successfully refined our animation and are now able to better interpret our result. + +Upon closer inspection, two challenges emerge: the legend overlaps the x-axis and the y-axis range is insufficient to capture the full spectrum of Asia's population development. Let's run the code below to improve the chart. + +!!! example "Vizro-AI animated chart" + + === "Code for the cell" + ```py + from vizro_ai import VizroAI + import vizro.plotly.express as px + + df = px.data.gapminder() + + vizro_ai = VizroAI() + vizro_ai.plot(df, "The chart should be an animated stacked bar chart with population on the y axis and continent on the x axis with all respective countries, allowing you to observe changes in the population over consecutive years. Make sure that y axis range fits entire data. Please improve layout and optimize layout of legend.") + ``` + === "Result" + [![AnimatedChart3]][AnimatedChart3] + + [AnimatedChart3]: ../../assets/tutorials/chart/animated_bar_chart_3.png + +Congratulations! You've now gained insights into harnessing the power of a LLM and Vizro-AI for crafting advanced charts and improving formatting. Don't forget, enabling `explain=True` is a good way of learning more about how a chart can be further improved and formatted. + +Advanced charts are well-suited for [Vizro](https://github.com/mckinsey/vizro/tree/main/vizro-core) dashboard applications. You can create a chart using `vizro-ai` to plug into your `vizro` dashboard in seconds! + +![chart-into-dashboard](../../assets/tutorials/chart_into_dashboard.gif) diff --git a/vizro-ai/docs/pages/user-guides/run-vizro-ai.md b/vizro-ai/docs/pages/user-guides/run-vizro-ai.md index 68e0fd2d2..420094007 100644 --- a/vizro-ai/docs/pages/user-guides/run-vizro-ai.md +++ b/vizro-ai/docs/pages/user-guides/run-vizro-ai.md @@ -6,7 +6,7 @@ This guide offers insights into different ways of running Vizro-AI code, includi To run Vizro-AI code in a Jupyter Notebook, create a new cell and execute the code below to render the described visualization. You should see the chart as output. ??? note "Note: API key" - Make sure you have followed the [LLM setup guide](./install.md#large-language-model) and + Make sure you have followed the [LLM setup guide](../get-started/install.md#large-language-model) and your api key is set up in a `.env` file in the same folder as your Notebook file (`.ipynb`). !!! example "Bar chart" @@ -33,7 +33,7 @@ You can use Vizro-AI in any standard development environment by creating a `.py` ??? note "Note: API key" - Make sure you have followed [LLM setup guide](./install.md#large-language-model) and + Make sure you have followed [LLM setup guide](../get-started/install.md#large-language-model) and your API key is set up in the environment where your `.py` script is running with command as below: ```bash diff --git a/vizro-ai/docs/pages/tutorials/explore-vizro-ai.md b/vizro-ai/docs/pages/user-guides/use-different-languages.md similarity index 78% rename from vizro-ai/docs/pages/tutorials/explore-vizro-ai.md rename to vizro-ai/docs/pages/user-guides/use-different-languages.md index 4eb40855b..eb7934430 100644 --- a/vizro-ai/docs/pages/tutorials/explore-vizro-ai.md +++ b/vizro-ai/docs/pages/user-guides/use-different-languages.md @@ -1,19 +1,4 @@ -# Explore Vizro-AI -This tutorial serves as an exploration of Vizro-AI beyond the initial [quickstart guide](../tutorials/quickstart.md). It explains the different language options and shows how to use Vizro-AI to enhance the formatting of your visualizations. - -## Install Vizro-AI and get ready to run your code -Before proceeding, you'll need to install Vizro-AI by following the steps in the [installation guide](../user-guides/install.md). To execute code either paste it into a Jupyter Notebook or run it from a Python script, or see the [guide on how to run Vizro-AI](../user-guides/run-vizro-ai.md) for more detail. - -??? tip "Beginners/Code novices" - - For those new to Python or virtual environments, you may prefer to [use Vizro-AI inside Anaconda Navigator](../user-guides/install.md#use-vizro-ai-inside-anaconda-navigator) to take advantage of a graphical user interface without the need for terminal commands. - -### Set up access to a large language model -A prerequisite for this tutorial is access to one of the supported large language models. Refer to the [installation guide](../user-guides/install.md#large-language-model) for instructions on setting up an API key. - -Upon successful setup, your API key should be ready in the environment when you import `vizro_ai`. - -## How to create visualizations using different languages +# How to create visualizations using different languages Vizro-AI is versatile, supporting prompts and chart visualizations in languages other than English. Let's explore this capability with two examples, starting with Chinese where we inquire about visualizing the GDP per capita over time. !!! example "Vizro-AI Chinese" diff --git a/vizro-ai/mkdocs.yml b/vizro-ai/mkdocs.yml index dd030ca6f..a4654bc3c 100644 --- a/vizro-ai/mkdocs.yml +++ b/vizro-ai/mkdocs.yml @@ -3,11 +3,12 @@ site_url: https://vizro-ai.readthedocs.io/en/latest/ nav: - Vizro-AI: index.md - Get started: - - Install Vizro-AI: pages/user-guides/install.md - - A first example: pages/tutorials/quickstart.md - - Explore Vizro-AI: pages/tutorials/explore-vizro-ai.md + - Install Vizro-AI: pages/get-started/install.md + - A first example: pages/get-started/quickstart.md - How-to guides: - Run methods: pages/user-guides/run-vizro-ai.md + - Create advanced charts: pages/user-guides/create-advanced-charts.md + - Use different languages: pages/user-guides/use-different-languages.md - FAQs: pages/user-guides/faq.md - Explanation: - Disclaimer: pages/explanation/disclaimer.md From df86874c61ca8a3c0af43c008296e63821c7389c Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Tue, 26 Mar 2024 17:01:05 +0000 Subject: [PATCH 17/17] Revise following review --- vizro-ai/docs/pages/explanation/disclaimer.md | 2 +- .../pages/{user-guides => explanation}/faq.md | 0 .../user-guides/use-different-languages.md | 69 ------------------- vizro-ai/mkdocs.yml | 2 +- 4 files changed, 2 insertions(+), 71 deletions(-) rename vizro-ai/docs/pages/{user-guides => explanation}/faq.md (100%) diff --git a/vizro-ai/docs/pages/explanation/disclaimer.md b/vizro-ai/docs/pages/explanation/disclaimer.md index ed66cd4cc..fc7e24d7a 100644 --- a/vizro-ai/docs/pages/explanation/disclaimer.md +++ b/vizro-ai/docs/pages/explanation/disclaimer.md @@ -1,6 +1,6 @@ # Disclaimer -Users must select one of the [supported large language models (LLMs)](../user-guides/faq.md#which-llms-are-supported-by-vizro-ai) to use the `vizro_ai` package, +Users must select one of the [supported large language models (LLMs)](./faq.md#which-llms-are-supported-by-vizro-ai) to use the `vizro_ai` package, and are responsible for obtaining their own suitable API key for the relevant model. diff --git a/vizro-ai/docs/pages/user-guides/faq.md b/vizro-ai/docs/pages/explanation/faq.md similarity index 100% rename from vizro-ai/docs/pages/user-guides/faq.md rename to vizro-ai/docs/pages/explanation/faq.md diff --git a/vizro-ai/docs/pages/user-guides/use-different-languages.md b/vizro-ai/docs/pages/user-guides/use-different-languages.md index eb7934430..1dbd0039a 100644 --- a/vizro-ai/docs/pages/user-guides/use-different-languages.md +++ b/vizro-ai/docs/pages/user-guides/use-different-languages.md @@ -36,72 +36,3 @@ Subsequently, we'll switch to German and prompt the visualization of life expect [![GermanChart]][GermanChart] [GermanChart]: ../../assets/tutorials/chart/GermanExample.png - -## How to create advanced charts and formatting -Now, let's explore more advanced visualizations and use Vizro-AI for enhanced formatting. - -To begin, we'll create an animated bar chart illustrating the population development of each continent over time. Run the code below and look at the result. - -!!! example "Vizro-AI animated chart" - - === "Code for the cell" - ```py - from vizro_ai import VizroAI - import vizro.plotly.express as px - - df = px.data.gapminder() - - vizro_ai = VizroAI() - vizro_ai.plot(df, "The chart should be an animated stacked bar chart with population on the y axis and continent on the x axis with all respective countries, allowing you to observe changes in the population over consecutive years.") - ``` - === "Result" - [![AnimatedChart1]][AnimatedChart1] - - [AnimatedChart1]: ../../assets/tutorials/chart/animated_bar_chart_1.png - -Having unveiled our animated bar chart showcasing population development per country, it's clear that crucial details are overshadowed by the legend. Next, we will try to tweak our prompt to group the countries into continents and improve the overall layout. - -!!! example "Vizro-AI animated chart" - - === "Code for the cell" - ```py - from vizro_ai import VizroAI - import vizro.plotly.express as px - - df = px.data.gapminder() - - vizro_ai = VizroAI() - vizro_ai.plot(df, "The chart should be an animated stacked bar chart with population on the y axis and continent on the x axis with all respective countries, allowing you to observe changes in the population over consecutive years. Please improve layout.") - ``` - === "Result" - [![AnimatedChart2]][AnimatedChart2] - - [AnimatedChart2]: ../../assets/tutorials/chart/animated_bar_chart_2.png - - -By incorporating the directive `Please improve layout`, we've successfully refined our animation and are now able to better interpret our result. - -Upon closer inspection, two challenges emerge: the legend overlaps the x-axis and the y-axis range is insufficient to capture the full spectrum of Asia's population development. Let's run the code below to improve the chart. - -!!! example "Vizro-AI animated chart" - - === "Code for the cell" - ```py - from vizro_ai import VizroAI - import vizro.plotly.express as px - - df = px.data.gapminder() - - vizro_ai = VizroAI() - vizro_ai.plot(df, "The chart should be an animated stacked bar chart with population on the y axis and continent on the x axis with all respective countries, allowing you to observe changes in the population over consecutive years. Make sure that y axis range fits entire data. Please improve layout and optimize layout of legend.") - ``` - === "Result" - [![AnimatedChart3]][AnimatedChart3] - - [AnimatedChart3]: ../../assets/tutorials/chart/animated_bar_chart_3.png - -Congratulations! You've now gained insights into harnessing the power of a LLM and Vizro-AI for crafting advanced charts and improving formatting. Don't forget, enabling `explain=True` is a good way of learning more about how a chart can be further improved and formatted. - -Advanced charts are well-suited for [Vizro](https://github.com/mckinsey/vizro/tree/main/vizro-core) dashboard applications. You can create a chart using `vizro-ai` to plug into your `vizro` dashboard in seconds! - -![chart-into-dashboard](../../assets/tutorials/chart_into_dashboard.gif) diff --git a/vizro-ai/mkdocs.yml b/vizro-ai/mkdocs.yml index a4654bc3c..4f7804f1e 100644 --- a/vizro-ai/mkdocs.yml +++ b/vizro-ai/mkdocs.yml @@ -9,8 +9,8 @@ nav: - Run methods: pages/user-guides/run-vizro-ai.md - Create advanced charts: pages/user-guides/create-advanced-charts.md - Use different languages: pages/user-guides/use-different-languages.md - - FAQs: pages/user-guides/faq.md - Explanation: + - FAQs: pages/explanation/faq.md - Disclaimer: pages/explanation/disclaimer.md - Safeguard code execution: pages/explanation/safeguard.md - Safety in Vizro-AI: pages/explanation/safety-in-vizro-ai.md