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 @@ + + + + + + + + + diff --git a/vizro-ai/docs/index.md b/vizro-ai/docs/index.md index 33fed5078..ff4a61fe0 100644 --- a/vizro-ai/docs/index.md +++ b/vizro-ai/docs/index.md @@ -1,47 +1,31 @@ # 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](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/). -## 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. +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.
- +
-
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.

- +
-
User Guides
+
How-to guides

- Our user guides provide step-by-step instructions on how to install `vizro-ai` package and leverage our core features. + How to guides about Vizro-AI and frequently asked questions.

@@ -53,7 +37,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 +48,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 +56,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..41d0e5a32 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..fc7e24d7a 100644 --- a/vizro-ai/docs/pages/explanation/disclaimer.md +++ b/vizro-ai/docs/pages/explanation/disclaimer.md @@ -1,9 +1,11 @@ # 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)](./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 + + +## Third party API - Users are responsible for anything done via their own API key. @@ -11,7 +13,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: @@ -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. + diff --git a/vizro-ai/docs/pages/user-guides/model-config.md b/vizro-ai/docs/pages/explanation/faq.md similarity index 65% rename from vizro-ai/docs/pages/user-guides/model-config.md rename to vizro-ai/docs/pages/explanation/faq.md index 1414c52d0..a9b8d30cd 100644 --- a/vizro-ai/docs/pages/user-guides/model-config.md +++ b/vizro-ai/docs/pages/explanation/faq.md @@ -1,8 +1,24 @@ -# 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 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, 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! + !!! 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.** @@ -10,39 +26,19 @@ 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" ```py linenums="1" from vizro_ai import VizroAI vizro_ai = VizroAI(model_name="gpt-3.5-turbo-0613", temperature=0) ``` - - - -## 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! diff --git a/vizro-ai/docs/pages/explanation/safeguard.md b/vizro-ai/docs/pages/explanation/safeguard.md index f513206e3..c7e96c524 100644 --- a/vizro-ai/docs/pages/explanation/safeguard.md +++ b/vizro-ai/docs/pages/explanation/safeguard.md @@ -1,23 +1,23 @@ -# Safeguard Dynamic Code Execution 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. +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 @@ -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 816111b29..144b13397 100644 --- a/vizro-ai/docs/pages/explanation/safety-in-vizro-ai.md +++ b/vizro-ai/docs/pages/explanation/safety-in-vizro-ai.md @@ -1,57 +1,56 @@ -## 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. +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**, 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. +`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 +### 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 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 +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: @@ -62,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, please 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). diff --git a/vizro-ai/docs/pages/get-started/install.md b/vizro-ai/docs/pages/get-started/install.md new file mode 100644 index 000000000..53dc7e923 --- /dev/null +++ b/vizro-ai/docs/pages/get-started/install.md @@ -0,0 +1,136 @@ +# 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 + +### Python +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. + + +### 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). + +??? 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 + ``` + +### 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/). + +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 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 + + # 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. 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 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, +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 +``` + +## 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 + +print(vizro_ai.__version__) +``` + +You should see a return output of the form `x.y.z`. + +## Upgrade + +To change the version of Vizro-AI installed: + +```bash +pip install -U vizro_ai +``` + +!!! 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/docs/pages/get-started/quickstart.md b/vizro-ai/docs/pages/get-started/quickstart.md new file mode 100644 index 000000000..c3f94e9c6 --- /dev/null +++ b/vizro-ai/docs/pages/get-started/quickstart.md @@ -0,0 +1,105 @@ +# Get started with Vizro-AI +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 and set up the API key for OpenAI, follow the [installation guide](../get-started/install.md). + +### 2. Open a Jupyter Notebook + +A good way to initially explore Vizro-AI is from inside a Jupyter Notebook. + +??? "If you haven't used Jupyter before..." + + You may need to install the Jupyter package if you . From the terminal window: + + ```bash + pip install jupyter + ``` + +Activate the virtual environment you used to install Vizro, and start a new Notebook as follows: + +```bash +jupyter notebook +``` + +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. + +```py +import vizro_ai + +print(vizro_ai.__version__) +``` + +You should see a return output of the form `x.y.z`. + + +### 3. Create your first chart using Vizro-AI + +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 a `pandas` DataFrame using the gapminder data from `plotly express`: + +```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" + ```py + from vizro_ai import VizroAI + import vizro.plotly.express as px + + 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") + ``` + === "Result" + [![BarChart]][BarChart] + + [BarChart]: ../../assets/tutorials/chart/GDP_Composition_Bar.png + +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 insights to explain the rendered chart in detail. Let's create another example to illustrate the information returned: + +!!! example "Specify `explain=True`" + + === "Code for the cell" + ```py + vizro_ai.plot(df, "show me the geo distribution of life expectancy", explain=True) + ``` + === "Result" + [![GeoDistribution]][GeoDistribution] + + [GeoDistribution]: ../../assets/tutorials/chart/GeoDistribution.png + +### 6. Explore 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 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/tutorials/explore-vizro-ai.md b/vizro-ai/docs/pages/tutorials/explore-vizro-ai.md deleted file mode 100644 index 5ae025d5a..000000000 --- a/vizro-ai/docs/pages/tutorials/explore-vizro-ai.md +++ /dev/null @@ -1,123 +0,0 @@ -# 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. - - -??? 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. - -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. - -### 2. Create your visualization 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 - import vizro.plotly.express as px - - df = px.data.gapminder() - - vizro_ai = VizroAI() - vizro_ai.plot(df, "请画一个世界年均GDP的趋势图") - ``` - === "Result" - [![ChineseChart]][ChineseChart] - - [ChineseChart]: ../../assets/tutorials/chart/ChineseExample.png - -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 - import vizro.plotly.express as px - - df = px.data.gapminder() - - vizro_ai = VizroAI() - vizro_ai.plot(df, "Visualiere den Trend von der Lebenserwartung in USA über die Jahre im Vergleich zur Veränderung der weltweiten Lebenserwartung über die Jahre und kreiere eine deutsche Visualisierung", explain=True) - ``` - === "Result" - [![GermanChart]][GermanChart] - - [GermanChart]: ../../assets/tutorials/chart/GermanExample.png - -### 3. 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. - -!!! 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 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.") - ``` - === "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 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 - 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 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.") - ``` - === "Result" - [![AnimatedChart2]][AnimatedChart2] - - [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. - -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. - -!!! 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 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. - -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 deleted file mode 100644 index d35e3800e..000000000 --- a/vizro-ai/docs/pages/tutorials/quickstart.md +++ /dev/null @@ -1,90 +0,0 @@ -# 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. - -## 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. - -??? 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. - -### 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: - -```console -pip install jupyter -``` - -Next, you can start your jupyter notebook in your activated environment by: - -```console -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. - -Confirm that `vizro_ai` is installed by typing the following into a jupyter cell in your notebook and running it. - -```py -import vizro_ai -print(vizro_ai.__version__) -``` - -You should see a return output of the version. - -### 3. Large Language Model (LLM) 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. - -### 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. - -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. - -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. - -!!! example "Vizro AI Syntax" - === "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, "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. - -### 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. - -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) - ``` - === "Result" - [![GeoDistribution]][GeoDistribution] - - [GeoDistribution]: ../../assets/tutorials/chart/GeoDistribution.png - -### 6. Explore further - -Now, you have created your first charts with Vizro-AI and are ready to explore the documentation 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/api-setup.md b/vizro-ai/docs/pages/user-guides/api-setup.md deleted file mode 100644 index 6159cfca8..000000000 --- a/vizro-ai/docs/pages/user-guides/api-setup.md +++ /dev/null @@ -1,73 +0,0 @@ -# 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). - -Users are recommended to review the third party API key section of the [disclaimer](../explanation/disclaimer.md) documentation. - -## 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. - -### Setup the API key -There are two common ways to set up the API key in a development environment. - -__Method 1 (recommended): Set up the API key for a single project__ - -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. - -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. - -!!! example "API key setup and usage" - === ".env" - ```text - OPENAI_API_KEY= - ``` -#### Customizing the .env file location and name -If you would like to customize the `.env` file location and name, you can set it manually. -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) -``` -Note: Please refer to [python-dotenv documentation](https://saurabh-kumar.com/python-dotenv/reference/) for detailed information. - - -__Method 2: Set up the API key as an environment variable for all projects__ - -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 -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. - -This is usually for organizational users. For example, if your organization has designed API gateway, -you can change the API endpoint here. - -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= - ``` 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/install.md b/vizro-ai/docs/pages/user-guides/install.md deleted file mode 100644 index cb53dcecc..000000000 --- a/vizro-ai/docs/pages/user-guides/install.md +++ /dev/null @@ -1,68 +0,0 @@ -# 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. - -## 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="..." -``` - - -More details can be found in the [environment setup guide](../user-guides/api-setup.md). - -??? 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 - -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: - -```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: - -```bash -pip install jupyter -``` - -??? 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: - - - 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 - -## Verify version - -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: - -```py -import vizro_ai - -print(vizro_ai.__version__) -``` - -You should see a return output of the current version. - -## 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 -``` - -The best way to safely upgrade is to check the [release notes]() for any notable breaking changes before migrating an -existing project. 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..420094007 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 [environment setup guide](../user-guides/api-setup.md) and - your api key is set up in a `.env` file in the same folder as your `ipynb` file. + 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" + === "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 [environment setup guide](../user-guides/api-setup.md) 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 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 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. !!! 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) - ``` +- 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) +``` diff --git a/vizro-ai/docs/pages/user-guides/use-different-languages.md b/vizro-ai/docs/pages/user-guides/use-different-languages.md new file mode 100644 index 000000000..1dbd0039a --- /dev/null +++ b/vizro-ai/docs/pages/user-guides/use-different-languages.md @@ -0,0 +1,38 @@ +# 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" + + === "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, "请画一个世界年均GDP的趋势图") + ``` + === "Result" + [![ChineseChart]][ChineseChart] + + [ChineseChart]: ../../assets/tutorials/chart/ChineseExample.png + +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 + import vizro.plotly.express as px + + df = px.data.gapminder() + + vizro_ai = VizroAI() + vizro_ai.plot(df, "Visualiere den Trend von der Lebenserwartung in USA über die Jahre im Vergleich zur Veränderung der weltweiten Lebenserwartung über die Jahre und kreiere eine deutsche Visualisierung", explain=True) + ``` + === "Result" + [![GermanChart]][GermanChart] + + [GermanChart]: ../../assets/tutorials/chart/GermanExample.png diff --git a/vizro-ai/mkdocs.yml b/vizro-ai/mkdocs.yml index c0d9b299c..4f7804f1e 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 - - 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 + - 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 - 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 + - 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