[Docs] Prepare docs for refactoring

.vale/styles/Microsoft/ignore.txt

@@ -93,3 +93,5 @@ virginica
 Hugging Face
 dash_ag_grid
 dash_data_table
+Langchain
+Langchain's

vizro-ai/changelog.d/20240904_100352_maximilian_schulz_vizro_ai_docs.md

@@ -0,0 +1,42 @@
+<!--
+A new scriv changelog fragment.
+
+Uncomment the section that is right (remove the HTML comment wrapper).
+-->
+
+### Highlights ✨
+
+- VizroAI now allows **any** `langchain` model with structured output capabilities to be used, not just `ChatOpenAI` ([#646](https://github.com/mckinsey/vizro/pull/646))
+- VizroAI now has a more flexible output when choosing `VizroAI.plot(...,return_elements=True)`. See documentation for all new options. ([#646](https://github.com/mckinsey/vizro/pull/646))
+
+### Removed
+
+- Removed the automatic display of chart explanation and insights in Jupyter. ([#646](https://github.com/mckinsey/vizro/pull/646))
+
+<!--
+### 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
+
+- Changed the return type of `VizroAI.plot(...,return_elements=True)` from `PlotOutputs` dataclass to a pydantic model with more flexible methods. See documentation for more into ([#646](https://github.com/mckinsey/vizro/pull/646))
+
+### Deprecated
+
+- Removed argument `explain` from VizroAI.plot(). Use `return_elements=True` instead. ([#646](https://github.com/mckinsey/vizro/pull/646))
+
+<!--
+### 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/changelog.d/20240904_101849_maximilian_schulz_vizro_ai_charts_refactor.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/pages/explanation/safeguard.md

@@ -1,7 +1,7 @@
 # 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
-self-debugging and automatic visual rendering in methods such as `vizro_ai._get_chart_code()` and `vizro_ai.plot()`.
+self-debugging and automatic visual rendering in methods such as `.get_fig_object()` and `VizroAI.plot()`.
 One of the primary concerns is the potential for malicious code to access or change critical system resources or data.
 
 ## Understand `exec()`

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

@@ -65,7 +65,12 @@ To learn how to customize the `VizroAI` class, check out the guide on [how to cu
 Finally, we call the `plot()` method with our English language instruction, to generate the visualization:
 
 ```python
-vizro_ai.plot(df, "create a line graph for GDP per capita since 1950 for each continent. Mark the x axis as Year, y axis as GDP Per Cap and don't include a title")
+vizro_ai.plot(
+    df,
+    """create a line graph for GDP per capita since 1950 for
+    each continent. Mark the x axis as Year, y axis as GDP Per Cap
+    and don't include a title. Make sure to take average over continent.""",
+)
 ```
 
 !!! warning "Help! The LLM request was unauthorized"
@@ -82,18 +87,22 @@ vizro_ai.plot(df, "create a line graph for GDP per capita since 1950 for each co
 
 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 returns the chart by executing the generated code.
 
-!!! example "Vizro AI Syntax"
+!!! example "Vizro-AI Syntax"
 
     === "Code for the cell"
         ```py
-        from vizro_ai import VizroAI
         import vizro.plotly.express as px
+        from vizro_ai import VizroAI
 
         df = px.data.gapminder()
 
-        vizro_ai = VizroAI()
-        fig = vizro_ai.plot(df, "create a line graph for GDP per capita since 1950 for each continent. Mark the x axis as Year, y axis as GDP Per Cap and don't include a title", explain=True)
-        fig.show()
+        vizro_ai = VizroAI(model="gpt-4-turbo")
+        fig = vizro_ai.plot(
+            df,
+            """create a line graph for GDP per capita since 1950 for each continent.
+            Mark the x axis as Year, y axis as GDP Per Cap and don't include a title.
+            Make sure to take average over continent.""",
+        )
         ```
     === "Result"
         [![LineGraph]][LineGraph]
@@ -102,7 +111,7 @@ And that's it! By passing the prepared data and written visualization request, V
 
 The chart created is interactive: you can hover over the data for more information.
 
-Passing `explain=True` to the `plot()` method returns the code to create the chart, along with a set of insights to explain the rendered chart in detail. You can then use the code within a Vizro dashboard as illustrated in the [Vizro documentation](https://vizro.readthedocs.io/en/stable/pages/tutorials/explore-components/#22-add-further-components). For the line graph above, the code returned is as follows:
+Passing `return_elements=True` to the `plot()` method returns an object, which includes the code along with a set of insights to explain the rendered chart in detail. You can then use the code within a Vizro dashboard as illustrated in the [Vizro documentation](https://vizro.readthedocs.io/en/stable/pages/tutorials/explore-components/#22-add-further-components). For the line graph above, the code returned may be as follows:
 
 !!! example "Returned by Vizro-AI"
 
@@ -123,17 +132,53 @@ Passing `explain=True` to the `plot()` method returns the code to create the cha
 ### 4. Get an explanation with your chart
 <!-- vale on -->
 
-Let's create another example to illustrate the code and insights returned when passing `explain=True` as a parameter to `plot()`:
+Let's create another example to illustrate the code and insights returned when passing `return_elements=True` as a parameter to `plot()`:
 
-!!! example "Specify  `explain=True`"
+!!! example "Specify  `return_elements=True`"
 
     === "Code for the cell"
         ```py
-        fig = vizro_ai.plot(df, "show me the geo distribution of life expectancy", explain=True)
-        fig.show()
+        res = vizro_ai.plot(df, "show me the geo distribution of life expectancy", return_elements=True)
+        print(res.code)
+        print(res.chart_insights)
+        print(res.code_explanation)
         ```
     === "Result"
-        [![GeoDistribution]][GeoDistribution]
+        Code
+        ```py
+        import plotly.express as px
+
+
+        def custom_chart(data_frame):
+            fig = px.choropleth(
+                data_frame,
+                locations="iso_alpha",
+                color="lifeExp",
+                hover_name="country",
+                color_continuous_scale=px.colors.sequential.Plasma,
+                labels={"lifeExp": "Life Expectancy"},
+            )
+            fig.update_layout(
+                title="Global Life Expectancy Distribution",
+                geo=dict(showframe=False, showcoastlines=True),
+            )
+            return fig
+        ```
+        Chart insights
+        ```
+        This choropleth map visualizes the global distribution of life expectancy across
+        different countries. It highlights variations and trends in life expectancy,
+        providing a clear visual representation of geographical disparities.
+        ```
+        Code explanation
+        ```
+        - Import Plotly Express.
+        - Create a choropleth map using the `px.choropleth` function.
+        - Set the `locations` parameter to the ISO alpha codes from the data.
+        - Color the map based on life expectancy values.
+        - Use a continuous color scale to represent different life expectancies.
+        - Update layout to enhance map readability and aesthetics.
+        ```
 
     [GeoDistribution]: ../../assets/tutorials/chart/GeoDistribution.png
 

vizro-ai/docs/pages/user-guides/add-generated-chart-usecase.md

@@ -27,7 +27,7 @@ This guide explains the different ways in which you can add a chart generated by
                            and GDP per capita for each country over time.
                            Color the bubbles by continent.
                            Add animation on yearly basis, and do not use facets.
-                           Put the legend on top""", explain=True)
+                           Put the legend on top""")
             fig.show()
             ```
         === "Result"
@@ -37,7 +37,7 @@ This guide explains the different ways in which you can add a chart generated by
 
 2. Insert the resulting chart into a dashboard.
 
-    Once you are satisfied with the chart, you can add it to a [Vizro](https://github.com/mckinsey/vizro/tree/main/vizro-core) dashboard. In the explanation section from the result of the example above, you'll find the code snippet used to generate the chart.
+    Once you are satisfied with the chart, you can add it to a [Vizro](https://github.com/mckinsey/vizro/tree/main/vizro-core) dashboard.
 
     ```py
     @capture('graph')
@@ -128,7 +128,7 @@ Executing the code below yields the identical dashboard as the example above.
         from dotenv import load_dotenv
         load_dotenv()
         df = px.data.gapminder()
-        vizro_ai = VizroAI(model="gpt-4-0613")
+        vizro_ai = VizroAI(model="gpt-4")
 
         fig = vizro_ai.plot(df,
                       """Plot a bubble chart to show the changes in life expectancy