Merge branch 'main' into bug/chart_dataframe_mutation

vizro-ai/changelog.d/20240725_132140_nadija_ratkusic_graca_vizroai_update_docs.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/changelog.d/20240727_031259_lingyi_zhang_vizroai_code.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/user-guides/run-vizro-ai.md

@@ -81,36 +81,50 @@ There are two ways to integrate Vizro-AI into an application, directly and by ac
             ```
 
 
-2. Vizro-AI's `_get_chart_code` method returns a string of Python code that manipulates the data and creates the visualization. Vizro-AI validates the code to ensure that it is executable and can be integrated.
+2. When the `return_elements` argument of VizroAI's `plot` method is set to `True`, the method returns a `PlotOutputs` data class which contains all possible `VizroAI.plot()` outputs.
+By setting `return_elements=True` you can access code or the figure object. Vizro-AI validates the code to ensure that it is executable and can be integrated.
 
-    !!! example "Application integration via chart code"
+    !!! example "Accessing outputs from PlotOutputs data class"
 
         === "app.py"
-            ```py
-            import vizro.plotly.express as px
-            from vizro_ai import VizroAI
-
-            vizro_ai = VizroAI()
+           ```py
+           import vizro_ai
+           from vizro_ai import VizroAI
+           import vizro.plotly.express as px
+           from dotenv import load_dotenv
 
-            df = px.data.gapminder()
-            code_string = vizro_ai._get_chart_code(df, "describe life expectancy per continent over time")
-            ```
-        === "code_string"
-            [![ResultCode]][ResultCode]
+           load_dotenv()
 
-        [ResultCode]: ../../assets/user_guides/code_string_app_integration.png
+           df = px.data.gapminder()
+           vizro_ai = VizroAI()
 
-    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.
+           plot_outputs = vizro_ai.plot(df, "describe life expectancy per continent over time", explain=True, return_elements=True)
+           fig = plot_outputs.figure
+           code_string = plot_outputs.code
+           ```
 
-    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
+- Type: `int`
 - 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)
 ```
+
+### How to use `return_elements` parameter in plot function
+- Default Value: False
+- Type: `bool`
+- Brief: By default, the `return_elements` is set to `False`, and the `VizroAI.plot()` returns a `plotly.graph_objects` object. If `return_elements` is set to `True` `VizroAI.plot()` returns the `PlotOutputs` data class.
+The `PlotOutputs` data class is designed to encapsulate all possible outputs generated by the `VizroAI.plot()` method.
+
+Attributes of `PlotOutputs`:
+
+- **`code`**: A string representing of the Python code that manipulates the data and creates the visualization.
+- **`figure`**: A [`CapturedCallable`](https://vizro.readthedocs.io/en/stable/pages/API-reference/models/#vizro.models.types.CapturedCallable) object from [`Vizro`](https://vizro.readthedocs.io/en/stable/), representing the visual plot generated by `VizroAI.plot()`. This object is designed to run immediately in the Vizro dashboard, but otherwise, it behaves like a plotly `go.Figure`.
+- **`business_insights`**: A string containing high-level business insights derived from the plot. `business_insights` is only available if `explain=True`.
+- **`code_explanation`**: A string offering a detailed explanation of the code used to produce the plot. `code_explanation` is only available if `explain=True`.
+-

vizro-ai/src/vizro_ai/plot/components/__init__.py

@@ -1,4 +1,4 @@
-from ._base import VizroAiComponentBase
+from ._base import VizroAIComponentBase
 from .chart_selection import GetChartSelection
 from .code_validation import GetDebugger
 from .custom_chart_wrap import GetCustomChart
@@ -7,7 +7,7 @@
 from .visual_code import GetVisualCode
 
 __all__ = [
-    "VizroAiComponentBase",
+    "VizroAIComponentBase",
     "GetChartSelection",
     "GetDataFrameCraft",
     "GetVisualCode",

vizro-ai/src/vizro_ai/plot/components/_base.py

@@ -6,7 +6,7 @@
 from vizro_ai.chains import FunctionCallChain
 
 
-class VizroAiComponentBase(ABC):
+class VizroAIComponentBase(ABC):
     """Abstract Base Class that represents a blueprint for Vizro-AI components.
 
     Attributes

vizro-ai/src/vizro_ai/plot/components/chart_selection.py

@@ -12,7 +12,7 @@
 from langchain_core.language_models.chat_models import BaseChatModel
 
 from vizro_ai.chains._chain_utils import _log_time
-from vizro_ai.plot.components import VizroAiComponentBase
+from vizro_ai.plot.components import VizroAIComponentBase
 from vizro_ai.plot.schema_manager import SchemaManager
 from vizro_ai.utils.helper import _get_df_info
 
@@ -40,7 +40,7 @@ class ChartSelection(BaseModel):
 
 
 # 3. Define Component
-class GetChartSelection(VizroAiComponentBase):
+class GetChartSelection(VizroAIComponentBase):
     """Get chart type.
 
     Attributes

vizro-ai/src/vizro_ai/plot/components/code_validation.py

@@ -11,7 +11,7 @@
 from langchain_core.language_models.chat_models import BaseChatModel
 
 from vizro_ai.chains._chain_utils import _log_time
-from vizro_ai.plot.components import VizroAiComponentBase
+from vizro_ai.plot.components import VizroAIComponentBase
 from vizro_ai.plot.schema_manager import SchemaManager
 
 # 1. Define schema
@@ -42,7 +42,7 @@ class CodeDebug(BaseModel):
 
 
 # 3. Define Component
-class GetDebugger(VizroAiComponentBase):
+class GetDebugger(VizroAIComponentBase):
     """Get Visual code.
 
     Attributes

vizro-ai/src/vizro_ai/plot/components/custom_chart_wrap.py

@@ -11,7 +11,7 @@
 from langchain_core.language_models.chat_models import BaseChatModel
 
 from vizro_ai.chains._chain_utils import _log_time
-from vizro_ai.plot.components import VizroAiComponentBase
+from vizro_ai.plot.components import VizroAIComponentBase
 from vizro_ai.plot.schema_manager import SchemaManager
 
 logger = logging.getLogger(__name__)
@@ -44,7 +44,7 @@ class CustomChart(BaseModel):
 """
 
 
-class GetCustomChart(VizroAiComponentBase):
+class GetCustomChart(VizroAIComponentBase):
     # TODO Explore if it is possible to create CustomChart without LLM
     """Get custom chart code.
 

vizro-ai/src/vizro_ai/plot/components/dataframe_craft.py

@@ -14,7 +14,7 @@
 from langchain_core.language_models.chat_models import BaseChatModel
 
 from vizro_ai.chains._chain_utils import _log_time
-from vizro_ai.plot.components import VizroAiComponentBase
+from vizro_ai.plot.components import VizroAIComponentBase
 from vizro_ai.plot.schema_manager import SchemaManager
 from vizro_ai.utils.helper import _get_df_info
 
@@ -50,7 +50,7 @@ class DataFrameCraft(BaseModel):
 
 
 # 3. Define Component
-class GetDataFrameCraft(VizroAiComponentBase):
+class GetDataFrameCraft(VizroAIComponentBase):
     """Get dataframe code.
 
     Attributes

vizro-ai/src/vizro_ai/plot/components/explanation.py

@@ -10,7 +10,7 @@
 from langchain_core.language_models.chat_models import BaseChatModel
 
 from vizro_ai.chains._chain_utils import _log_time
-from vizro_ai.plot.components import VizroAiComponentBase
+from vizro_ai.plot.components import VizroAIComponentBase
 from vizro_ai.plot.schema_manager import SchemaManager
 
 # 1. Define schema
@@ -35,7 +35,7 @@ class CodeExplanation(BaseModel):
 
 
 # 3. Define Component
-class GetCodeExplanation(VizroAiComponentBase):
+class GetCodeExplanation(VizroAIComponentBase):
     """Get Explanation of a code snippet.
 
     Attributes

vizro-ai/src/vizro_ai/plot/components/visual_code.py

@@ -12,7 +12,7 @@
 from langchain_core.language_models.chat_models import BaseChatModel
 
 from vizro_ai.chains._chain_utils import _log_time
-from vizro_ai.plot.components import VizroAiComponentBase
+from vizro_ai.plot.components import VizroAIComponentBase
 from vizro_ai.plot.schema_manager import SchemaManager
 from vizro_ai.utils.helper import _get_df_info
 
@@ -56,7 +56,7 @@ class VizroCode(BaseModel):
 
 
 # 3. Define Component
-class GetVisualCode(VizroAiComponentBase):
+class GetVisualCode(VizroAIComponentBase):
     """Get Visual code.
 
     Attributes