Update vizro-ai documentation (#159)

vizro-ai/changelog.d/20231110_151408_chiara_pullem_update.md

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

vizro-ai/docs/index.md

@@ -1,6 +1,18 @@
 # Vizro-AI
 
-Vizro-AI is a tool for generating data visualizations.
+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.
+
+## 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 explanations about the data and the generated code.
+
+### Visually-optimized
+Vizro-AI also caters data scientist who often spend more time on formatting than creating a visualization. Vizro-AI enables the user to speed up the formatting process and create a visually appealing chart, also leveraging the design library of Vizro.
+
+### Dashboard-ready
+Vizro-AI focuses currently on plotly and is used to create interactive chart. Thus, it is primarily aimed at dashboards, ensuring that the generated charts are well-suited for dashboard applications.
+
 !!! notice "Notice"
     Please review this [disclaimer](pages/explanation/disclaimer.md)
     before using the `vizro-ai` package.

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/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

vizro-ai/docs/pages/explanation/safety_in_vizro_ai.md

@@ -4,7 +4,7 @@ Generative AI models, especially Large Language Models (LLMs) represent signific
 Vizro-AI also leverages LLMs, however, as with any powerful tool, there are potential risks associated.
 
 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.
+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:
@@ -13,7 +13,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 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
@@ -41,17 +41,17 @@ It's crucial for users to remain informed, cautious, and ethical in their applic
 
 ## Dependencies, Code Scanners and Infosec
 
-It may occur that dependencies of `vizro-ai` get flagged by code scanners and other infosec tools. As a consequence it may happen that
-`vizro-ai` also get flagged.
+It may occur that dependencies of `vizro_ai` get flagged by code scanners and other infosec 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
-to any functionality used in our code base or if they only concern functionality outside the scope of `vizro-ai`.
+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.
+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 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.
 
 Users must exercise caution when executing code generated by or influenced by AI models. It's essential to:
@@ -60,6 +60,6 @@ Users must exercise caution when executing code generated by or influenced by AI
 - Always consider using controlled environments, such as virtual machines or containers, to execute uncertain code
 - Always be aware of potential risks when executing dynamically generated code in environments with access to sensitive data or systems
 - 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`
+- 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.

vizro-ai/docs/pages/tutorials/explore_vizro_ai.md

@@ -0,0 +1,131 @@
+# 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, load your API key with the following two lines:
+
+```py
+from dotenv import load_dotenv
+load_dotenv()
+```
+
+### 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
+
+        from dotenv import load_dotenv
+        load_dotenv()
+
+        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
+
+        from dotenv import load_dotenv
+        load_dotenv()
+
+        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
+
+        from dotenv import load_dotenv
+        load_dotenv()
+
+        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
+
+        from dotenv import load_dotenv
+        load_dotenv()
+
+        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
+
+        from dotenv import load_dotenv
+        load_dotenv()
+
+        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.

vizro-ai/docs/pages/tutorials/quickstart.md

@@ -3,8 +3,8 @@ 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)
+### 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"
@@ -28,7 +28,7 @@ This opens a browser tab, and you can navigate to your preferred folder for this
 ??? 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.
+Confirm that `vizro_ai` is installed by typing the following into a jupyter cell in your notebook and running it.
 
 ```py
 import vizro_ai
@@ -48,7 +48,7 @@ from dotenv import load_dotenv
 load_dotenv()
 ```
 
-### 4. Ask your first question using vizro-ai
+### 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.
 
@@ -60,22 +60,27 @@ By passing your prepared data and your written visualization request to this met
     === "Code for the cell"
         ```py
         from vizro_ai import VizroAI
-        import plotly.express as px
+        import vizro.plotly.express as px
 
         from dotenv import load_dotenv
         load_dotenv()
 
         df = px.data.gapminder()
         vizro_ai = VizroAI()
-        vizro_ai.plot(df, "describe the composition of gdp in continent, and add 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
 
-You can also pass `explain=True` to `plot()` method which will provide
-additional insights in addition to the rendered chart.
+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"
@@ -87,7 +92,7 @@ additional insights in addition to the rendered chart.
 
     [GeoDistribution]: ../../assets/tutorials/chart/GeoDistribution.png
 
-### 5. Explore further
+### 6. Explore further
 
 Now, you have created your first charts with Vizro-AI and are ready to explore the documentation further.
 

vizro-ai/docs/pages/user_guides/install.md

@@ -28,7 +28,7 @@ More details can be found in the [environment setup guide](../user_guides/api_se
 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
+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:
@@ -40,7 +40,7 @@ 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/)
+    - 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
@@ -50,9 +50,9 @@ pip install jupyter
 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
+import vizro_ai
 
-print(vizro-ai.__version__)
+print(vizro_ai.__version__)
 ```
 
 You should see a return output of the current version.
@@ -61,7 +61,7 @@ You should see a return output of the current version.
 
 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
+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

vizro-ai/docs/pages/user_guides/model_config.md

@@ -2,7 +2,7 @@
 
 !!! 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.**