diff --git a/_dashboards/dashboards-assistant/index.md b/_dashboards/dashboards-assistant/index.md index bf2d754be8..183a9082d9 100644 --- a/_dashboards/dashboards-assistant/index.md +++ b/_dashboards/dashboards-assistant/index.md @@ -2,7 +2,7 @@ layout: default title: OpenSearch Assistant for OpenSearch Dashboards nav_order: 3 -has_children: false +has_children: true has_toc: false --- @@ -22,7 +22,7 @@ To enable **OpenSearch Assistant** in OpenSearch Dashboards, locate your copy of ```yaml assistant.chat.enabled: true ``` -{% include copy-curl.html %} +{% include copy.html %} Then configure the root `agent_id` through the following API: @@ -135,4 +135,4 @@ assistant.next.enabled: true - [Getting started guide for OpenSearch Assistant in OpenSearch Dashboards](https://github.com/opensearch-project/dashboards-assistant/blob/main/GETTING_STARTED_GUIDE.md) - [OpenSearch Assistant configuration through the REST API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/opensearch-assistant/) -- [Build your own chatbot]({{site.url}}{{site.baseurl}}/ml-commons-plugin/tutorials/build-chatbot/) \ No newline at end of file +- [Build your own chatbot]({{site.url}}{{site.baseurl}}/ml-commons-plugin/tutorials/build-chatbot/) diff --git a/_dashboards/dashboards-assistant/text-to-visualization.md b/_dashboards/dashboards-assistant/text-to-visualization.md new file mode 100644 index 0000000000..24971ab7a6 --- /dev/null +++ b/_dashboards/dashboards-assistant/text-to-visualization.md @@ -0,0 +1,117 @@ +--- +layout: default +title: Text to Visualization +parent: OpenSearch Assistant for OpenSearch Dashboards +nav_order: 1 +has_children: false +--- + +# Text to Visualization +**Experimental** +{: .label .label-purple } + +The OpenSearch-Dashboards Assistant text to visualization feature helps you create visualizations with natural language. + +## Configuration + +### Prerequisites +Follow this [guide](http://localhost:4000/docs/latest/dashboards/dashboards-assistant/index/#configuring-opensearch-assistant) to setup `os_query_assist_ppl`, +please note that you only need to setup `os_query_assist_ppl` agent for text to visualization feature. + +### Enable Text to Visualization +```yaml +assistant.text2viz.enabled: true +``` +{% include copy.html %} + +### Create agents with OpenSearch flow-framework +Use OpenSearch flow-framework to create the required agents. Please follow [flow-framework documentation](https://github.com/opensearch-project/flow-framework) to create the agents. +You can start with the flow-framework example template for text to visualization, see the example template [here](https://github.com/opensearch-project/flow-framework/tree/main/sample-templates). + +### Configure agents +Create root agent of text to visualization +``` +POST /.plugins-ml-config/_doc/os_text2vega +{ + "type": "os_chat_root_agent", + "configuration": { + "agent_id": "your root agent id" + } +} +``` +{% include copy-curl.html %} + +Create root agent of text to visualization for user inputs with instruction +``` +POST /.plugins-ml-config/_doc/os_text2vega_with_instructions +{ + "type": "os_chat_root_agent", + "configuration": { + "agent_id": "your root agent id" + } +} +``` +{% include copy-curl.html %} + +### Verify +You can verify if the agents were create successfully by call the agents with example payload +``` +POST /_plugins/_ml/agents//_execute +{ + "parameters": { + "input_question": "find unique visitors and average bytes every 3 hours", + "input_instruction": "display with different layers, use independent scale for different layers, display unique visitors with light blue bar chart", + "ppl": "source=opensearch_dashboards_sample_data_ecommerce| stats DISTINCT_COUNT(user) as unique_visitors, AVG(taxful_total_price) as avg_bytes by span(order_date, 3h)", + "sampleData": """[{\"unique_visitors\":15,\"avg_bytes\":90.98684210526316,\"span(order_date,3h)\":\"2024-04-25 00:00:00\"},{\"unique_visitors\":14,\"avg_bytes\":72.72083333333333,\"span(order_date,3h)\":\"2024-04-25 03:00:00\"}]""", + "dataSchema": """[{\"name\":\"unique_visitors\",\"type\":\"integer\"},{\"name\":\"avg_bytes\",\"type\":\"double\"},{\"name\":\"span(order_date,3h)\",\"type\":\"timestamp\"}]""" + } +} +``` +{% include copy-curl.html %} + +## Text to visualization API +Call API `/api/assistant/text2vega` to generate vega based visualization, `input_instruction` is optional. +``` +POST /api/assistant/text2vega +{ + "input_instruction": "", + "input_question": "", + "ppl": "", + "dataSchema": "", + "sampleData": "" +} +``` +{% include copy-curl.html %} + +Parameter | Description | Required +:--- | :--- | :--- +input_instruction | the instruction for styling the visualization | `true` +input_question | the original question used to generate the PPL query +ppl | the generated PPL query for the visualization data +dataSchema | the schema of the visualization data +sampleData | a few samples of the visualization data + + +## Text to visualization UI +Start with creating a new visualization with natural language + +Create a visualization by selecting natural language + +Select a data source + +Create a visualization by selecting natural language + +Ask a question with natural language + +Create a visualization by selecting natural language + +Adjust the visualization by clicking the "Edit visual" button + +Create a visualization by selecting natural language + +See the updated visualization + +Create a visualization by selecting natural language + + + diff --git a/images/dashboards-assistant/t2viz-ask-question.png b/images/dashboards-assistant/t2viz-ask-question.png new file mode 100644 index 0000000000..e5b7e86f64 Binary files /dev/null and b/images/dashboards-assistant/t2viz-ask-question.png differ diff --git a/images/dashboards-assistant/t2viz-edit-visual-response.png b/images/dashboards-assistant/t2viz-edit-visual-response.png new file mode 100644 index 0000000000..1fd35425a7 Binary files /dev/null and b/images/dashboards-assistant/t2viz-edit-visual-response.png differ diff --git a/images/dashboards-assistant/t2viz-edit-visual.png b/images/dashboards-assistant/t2viz-edit-visual.png new file mode 100644 index 0000000000..0c57dd58aa Binary files /dev/null and b/images/dashboards-assistant/t2viz-edit-visual.png differ diff --git a/images/dashboards-assistant/t2viz-select-data-source.png b/images/dashboards-assistant/t2viz-select-data-source.png new file mode 100644 index 0000000000..2862b744c8 Binary files /dev/null and b/images/dashboards-assistant/t2viz-select-data-source.png differ diff --git a/images/dashboards-assistant/t2viz-start.png b/images/dashboards-assistant/t2viz-start.png new file mode 100644 index 0000000000..f6d46a21e5 Binary files /dev/null and b/images/dashboards-assistant/t2viz-start.png differ