From a016126fdb952c005b55681ac33e275f3ad48a53 Mon Sep 17 00:00:00 2001 From: Mara3l Date: Thu, 29 May 2025 13:02:10 +0200 Subject: [PATCH] feat(ai): Document new AI capabilities --- docs/content/en/latest/execution/ai/_index.md | 49 ++++++++++++++ .../content/en/latest/execution/ai/ai_chat.md | 40 ++++++++++++ .../en/latest/execution/ai/ai_chat_stream.md | 37 +++++++++++ .../ai/build_exec_def_from_chat_result.md | 38 +++++++++++ .../execution/ai/get_ai_chat_history.md | 40 ++++++++++++ .../execution/ai/reset_ai_chat_history.md | 32 ++++++++++ .../en/latest/execution/ai/search_ai.md | 64 +++++++++++++++++++ .../ai/set_ai_chat_history_feedback.md | 40 ++++++++++++ .../en/latest/execution/ai/sync_metadata.md | 35 ++++++++++ 9 files changed, 375 insertions(+) create mode 100644 docs/content/en/latest/execution/ai/_index.md create mode 100644 docs/content/en/latest/execution/ai/ai_chat.md create mode 100644 docs/content/en/latest/execution/ai/ai_chat_stream.md create mode 100644 docs/content/en/latest/execution/ai/build_exec_def_from_chat_result.md create mode 100644 docs/content/en/latest/execution/ai/get_ai_chat_history.md create mode 100644 docs/content/en/latest/execution/ai/reset_ai_chat_history.md create mode 100644 docs/content/en/latest/execution/ai/search_ai.md create mode 100644 docs/content/en/latest/execution/ai/set_ai_chat_history_feedback.md create mode 100644 docs/content/en/latest/execution/ai/sync_metadata.md diff --git a/docs/content/en/latest/execution/ai/_index.md b/docs/content/en/latest/execution/ai/_index.md new file mode 100644 index 000000000..c70febfb4 --- /dev/null +++ b/docs/content/en/latest/execution/ai/_index.md @@ -0,0 +1,49 @@ +--- +title: "GoodData AI (beta)" +linkTitle: "GoodData AI (beta)" +weight: 24 +no_list: true +--- + +GoodData AI is a feature that allows you to ask questions about your data in natural language. + +For more information on how to use and setup GoodData AI, see the [GoodData AI documentation](https://www.gooddata.com/docs/cloud/ai/). + +## Methods + +* [ai_chat](./ai_chat/) +* [ai_chat_stream](./ai_chat_stream/) +* [get_ai_chat_history](./get_ai_chat_history/) +* [reset_ai_chat_history](./reset_ai_chat_history/) +* [set_ai_chat_history_feedback](./set_ai_chat_history_feedback/) +* [search_ai](./search_ai/) +* [sync_metadata](./sync_metadata/) + + +## Example + +This example shows how to use the GoodData AI to get execution definition. You can also use it to get a pandas dataframe, but for that you need to use the [GoodPandas](../../pandas/). + +```python +from gooddata_sdk import GoodDataSdk # For AI chat and execution definition. +from gooddata_pandas import GoodDataPandas # For pandas dataframe. + + +host = "https://www.example.com" +token = "" +sdk = GoodDataSdk.create(host, token) + +# Get execution definition from AI chat (not needed for pandas dataframe) +response = sdk.compute.ai_chat(test_workspace_id, "Display the revenue by product") +execution_definition = sdk.compute.buid_exec_def_from_chat_result(response) + +# Create a pandas dataframe from the AI response. +gp = GoodDataPandas(host, token) +gdf = gp.data_frames(workspace_id) +df, df_metadata = gdf.for_created_visualization(response) + +# Print the results +print(execution_definition) # Execution Definition. +print(df_metadata) # Dataframe metadata. +print(df) # Pandas dataframe. +``` diff --git a/docs/content/en/latest/execution/ai/ai_chat.md b/docs/content/en/latest/execution/ai/ai_chat.md new file mode 100644 index 000000000..143cd11dc --- /dev/null +++ b/docs/content/en/latest/execution/ai/ai_chat.md @@ -0,0 +1,40 @@ +--- +title: "ai_chat" +linkTitle: "ai_chat" +weight: 92 +superheading: "compute." +--- + +``ai_chat(workspace_id: str, question: str) -> ChatResult`` + +Chat with AI in GoodData workspace. + + +{{% parameters-block title="Parameters" %}} +{{< parameter p_name="workspace_id" p_type="str" >}} +The ID of the GoodData Workspace. +{{< /parameter >}} +{{< parameter p_name="question" p_type="str" >}} +The question to ask the AI. +{{< /parameter >}} +{{% /parameters-block %}} + +{{% parameters-block title="Returns"%}} +{{< parameter p_name="chat_result" p_type="ChatResult" >}} +Chat response +{{< /parameter >}} +{{% /parameters-block %}} + + +## Example + +```python + +host = "https://www.example.com" +token = "" +sdk = GoodDataSdk.create(host, token) + +chat_result = sdk.compute.ai_chat(workspace_id, "Display the revenue by product") + +print(chat_result) +``` diff --git a/docs/content/en/latest/execution/ai/ai_chat_stream.md b/docs/content/en/latest/execution/ai/ai_chat_stream.md new file mode 100644 index 000000000..b3084ab8c --- /dev/null +++ b/docs/content/en/latest/execution/ai/ai_chat_stream.md @@ -0,0 +1,37 @@ +--- +title: "ai_chat_stream" +linkTitle: "ai_chat_stream" +weight: 93 +superheading: "compute." +--- + +``ai_chat_stream(workspace_id: str, question: str) -> Iterator[Any]`` + +Chat with AI in GoodData workspace. Stream the response. + + +{{% parameters-block title="Parameters" %}} +{{< parameter p_name="workspace_id" p_type="str" >}} +The ID of the GoodData Workspace. +{{< /parameter >}} +{{< parameter p_name="question" p_type="str" >}} +The question to ask the AI. +{{< /parameter >}} +{{% /parameters-block %}} + +{{% parameters-block title="Returns"%}} +{{< parameter p_name="chat_result" p_type="Iterator[Any]" >}} +Yields parsed JSON objects from each SSE event's data field{{< /parameter >}} +{{% /parameters-block %}} + + +## Example + +```python + +host = "https://www.example.com" +token = "" +sdk = GoodDataSdk.create(host, token) + +chat_result = sdk.compute.ai_chat_stream(workspace_id, "Display the revenue by product") +``` diff --git a/docs/content/en/latest/execution/ai/build_exec_def_from_chat_result.md b/docs/content/en/latest/execution/ai/build_exec_def_from_chat_result.md new file mode 100644 index 000000000..4040b3754 --- /dev/null +++ b/docs/content/en/latest/execution/ai/build_exec_def_from_chat_result.md @@ -0,0 +1,38 @@ +--- +title: "build_exec_def_from_chat_result" +linkTitle: "build_exec_def_from_chat_result" +weight: 95 +superheading: "compute." +--- + +``build_exec_def_from_chat_result(chat_result: ChatResult) -> ExecutionDefinition`` + +Build execution definition from chat result. + + +{{% parameters-block title="Parameters" %}} +{{< parameter p_name="chat_result" p_type="ChatResult" >}} +ChatResult object containing visualization details from AI chat response +{{< /parameter >}} +{{% /parameters-block %}} + +{{% parameters-block title="Returns" %}} +{{< parameter p_name="execution_definition" p_type="ExecutionDefinition" >}} +ExecutionDefinition object containing the execution definition for the visualization +{{< /parameter >}} +{{% /parameters-block %}} + + +## Example + +```python + +host = "https://www.example.com" +token = "" +sdk = GoodDataSdk.create(host, token) + +chat_result = sdk.compute.ai_chat(workspace_id, "Display the revenue by product") +execution_definition = sdk.compute.build_exec_def_from_chat_result(chat_result) + +print(execution_definition) +``` diff --git a/docs/content/en/latest/execution/ai/get_ai_chat_history.md b/docs/content/en/latest/execution/ai/get_ai_chat_history.md new file mode 100644 index 000000000..0f5ab7e46 --- /dev/null +++ b/docs/content/en/latest/execution/ai/get_ai_chat_history.md @@ -0,0 +1,40 @@ +--- +title: "ai_chat" +linkTitle: "ai_chat" +weight: 96 +superheading: "compute." +--- + +``ai_chat(workspace_id: str, question: str) -> ChatResult`` + +Chat with AI in GoodData workspace. + + +{{% parameters-block title="Parameters" %}} +{{< parameter p_name="workspace_id" p_type="str" >}} +The ID of the GoodData Workspace. +{{< /parameter >}} +{{< parameter p_name="question" p_type="str" >}} +The question to ask the AI. +{{< /parameter >}} +{{% /parameters-block %}} + +{{% parameters-block title="Returns"%}} +{{< parameter p_name="chat_result" p_type="ChatResult" >}} +Chat response +{{< /parameter >}} +{{% /parameters-block %}} + + +## Example + +```python + +host = "https://www.example.com" +token = "" +sdk = GoodDataSdk.create(host, token) + +chat_result = sdk.compute.ai_chat(workspace_id, "Display the revenue by product") + +print(chat_result) +``` diff --git a/docs/content/en/latest/execution/ai/reset_ai_chat_history.md b/docs/content/en/latest/execution/ai/reset_ai_chat_history.md new file mode 100644 index 000000000..1570f1b18 --- /dev/null +++ b/docs/content/en/latest/execution/ai/reset_ai_chat_history.md @@ -0,0 +1,32 @@ +--- +title: "reset_ai_chat_history" +linkTitle: "reset_ai_chat_history" +weight: 97 +superheading: "compute." +--- + +``reset_ai_chat_history(workspace_id: str) -> None`` + +Reset AI chat history in GoodData workspace. + + +{{% parameters-block title="Parameters" %}} +{{< parameter p_name="workspace_id" p_type="str" >}} +The ID of the GoodData Workspace. +{{< /parameter >}} +{{% /parameters-block %}} + +{{% parameters-block title="Returns" None="true"%}} +{{% /parameters-block %}} + + +## Example + +```python + +host = "https://www.example.com" +token = "" +sdk = GoodDataSdk.create(host, token) + +sdk.compute.reset_ai_chat_history(workspace_id) +``` diff --git a/docs/content/en/latest/execution/ai/search_ai.md b/docs/content/en/latest/execution/ai/search_ai.md new file mode 100644 index 000000000..dc9edb221 --- /dev/null +++ b/docs/content/en/latest/execution/ai/search_ai.md @@ -0,0 +1,64 @@ +--- +title: "search_ai" +linkTitle: "search_ai" +weight: 98 +superheading: "compute." +--- + +``search_ai( + workspace_id: str, + question: str, + deep_search: Optional[bool] = None, + limit: Optional[int] = None, + object_types: Optional[list[str]] = None, + relevant_score_threshold: Optional[float] = None, + title_to_descriptor_ratio: Optional[float] = None, + ) -> SearchResult:`` + +Search for metadata objects using similarity search. + +Default values for optional parameters are documented in the AI Search endpoint of the GoodData API. + + +{{% parameters-block title="Parameters" %}} +{{< parameter p_name="workspace_id" p_type="str" >}} +The ID of the GoodData Workspace. +{{< /parameter >}} +{{< parameter p_name="question" p_type="str" >}} +The question to ask the AI. +{{< /parameter >}} +{{< parameter p_name="deep_search" p_type="Optional[bool]" >}} +turn on deep search - if true, content of complex objects will be searched as well +{{< /parameter >}} +{{< parameter p_name="limit" p_type="Optional[int]" >}} +maximum number of results to return. Defaults to None. +{{< /parameter >}} +{{< parameter p_name="object_types" p_type="Optional[list[str]]" >}} +list of object types to search for. Enum items: "attribute", "metric", "fact", "label", "date", "dataset", "visualization" and "dashboard". Defaults to None. +{{< /parameter >}} +{{< parameter p_name="relevant_score_threshold" p_type="Optional[float]" >}} +minimum relevance score threshold for results. Defaults to None. +{{< /parameter >}} +{{< parameter p_name="title_to_descriptor_ratio" p_type="Optional[float]" >}} +ratio of title score to descriptor score. Defaults to None. +{{< /parameter >}} +{{% /parameters-block %}} + +{{% parameters-block title="Returns"%}} +{{< parameter p_name="search_result" p_type="SearchResult" >}} +SearchResult: Search results{{< /parameter >}} +{{% /parameters-block %}} + + +## Example + +```python + +host = "https://www.example.com" +token = "" +sdk = GoodDataSdk.create(host, token) + +chat_result = sdk.compute.ai_chat(workspace_id, "Display the revenue by product") + +print(chat_result) +``` diff --git a/docs/content/en/latest/execution/ai/set_ai_chat_history_feedback.md b/docs/content/en/latest/execution/ai/set_ai_chat_history_feedback.md new file mode 100644 index 000000000..3e7df39d1 --- /dev/null +++ b/docs/content/en/latest/execution/ai/set_ai_chat_history_feedback.md @@ -0,0 +1,40 @@ +--- +title: "set_ai_chat_history_feedback" +linkTitle: "set_ai_chat_history_feedback" +weight: 101 +superheading: "compute." +--- +``set_ai_chat_history_feedback(workspace_id: str, interaction_id: str, user_feedback: str, chat_history_interaction_id: str, thread_id_suffix: str = "") -> None`` + +Set feedback for an AI chat history interaction. + + +{{% parameters-block title="Parameters" %}} +{{< parameter p_name="workspace_id" p_type="str" >}} +workspace identifier +{{< /parameter >}} +{{< parameter p_name="interaction_id" p_type="str" >}} +feedback to provide ("POSITIVE", "NEGATIVE" or "NONE"). +{{< /parameter >}} +{{< parameter p_name="user_feedback" p_type="str" >}} +interaction id to provide feedback for. +{{< /parameter >}} +{{< parameter p_name="chat_history_interaction_id" p_type="str" >}} +suffix to identify a specific chat thread. Defaults to "". +{{< /parameter >}} +{{% /parameters-block %}} + +{{% parameters-block title="Returns" None="true"%}} +{{% /parameters-block %}} + + +## Example + +```python + +host = "https://www.example.com" +token = "" +sdk = GoodDataSdk.create(host, token) + +sdk.compute.set_ai_chat_history_feedback(workspace_id, "POSITIVE", "123", "456") +``` diff --git a/docs/content/en/latest/execution/ai/sync_metadata.md b/docs/content/en/latest/execution/ai/sync_metadata.md new file mode 100644 index 000000000..517d99aa4 --- /dev/null +++ b/docs/content/en/latest/execution/ai/sync_metadata.md @@ -0,0 +1,35 @@ +--- +title: "sync_metadata" +linkTitle: "sync_metadata" +weight: 100 +superheading: "compute." +--- + +``sync_metadata(workspace_id: str, async_req: bool = False) -> None`` + +Sync metadata in GoodData workspace. + + +{{% parameters-block title="Parameters" %}} +{{< parameter p_name="workspace_id" p_type="str" >}} +The ID of the GoodData Workspace. +{{< /parameter >}} +{{< parameter p_name="async_req" p_type="bool" >}} +Whether to perform the request asynchronously. +{{< /parameter >}} +{{% /parameters-block %}} + +{{% parameters-block title="Returns" None="true"%}} +{{% /parameters-block %}} + + +## Example + +```python + +host = "https://www.example.com" +token = "" +sdk = GoodDataSdk.create(host, token) + +sdk.compute.sync_metadata(workspace_id) +```