chore: add assistant documentation, overview, kpi, gauge, chart, tabl…

…e, chatbot
awslabs · Nov 26, 2024 · 135bc48 · 135bc48
1 parent 289c135
commit 135bc48
Show file tree

Hide file tree

Showing 19 changed files with 1,058 additions and 153 deletions.
diff --git a/apps/doc-site/.storybook/preview.js b/apps/doc-site/.storybook/preview.js
@@ -16,6 +16,7 @@ const preview = {
           'Overview',
           'Data sources',
           'Components',
+          'Assistant',
           'Core',
           'React hooks',
         ],

diff --git a/apps/doc-site/assets/ChatbotPreview.png b/apps/doc-site/assets/ChatbotPreview.png
diff --git a/apps/doc-site/common/cards.jsx b/apps/doc-site/common/cards.jsx
@@ -156,3 +156,92 @@ export const IntroductionSelectedDemosCards = () => {
       />
   );
 }
+
+export const AssistantComponentsCards = () => {
+  return (
+    <CloudscapeCards
+      ariaLabels={{
+        itemSelectionLabel: (e, t) => `select ${t.name}`,
+        selectionGroupLabel: "Item selection"
+      }}
+      cardDefinition={{
+        header: item => item.title,
+        sections: [
+          {
+            id: "name",
+            content: item => (
+              <CloudscapeLink href={item.link} >
+                {item.image ? <img
+                  style={{ height: "150px" }}
+                  src={item.image}
+                  alt="placeholder"
+                /> : null
+                }
+              </CloudscapeLink>
+            )
+          },
+          {
+            id: "description",
+            content: item => (
+              <>
+                {item.description}&nbsp;
+                <CloudscapeLink
+                  href={item.link}
+                >Learn more</CloudscapeLink>
+              </>
+            )
+          }
+        ]
+      }}
+      cardsPerRow={[
+        { cards: 1 },
+        { minWidth: 500, cards: 3 }
+      ]}
+      items={[
+        {
+          name: "Dashboard",
+          image: "/iot-app-kit/assets/DashboardPreview.jpg",
+          title: "Dashboard",
+          link: "/iot-app-kit/?path=/docs/assistant-components-dashboard---docs",
+          description: "Dashboard component allows you to easily create, modify, view, and organize widgets for a tailored experience to monitor your IoT data."
+        },
+        {
+          name: "KPI",
+          image: "/iot-app-kit/assets/KPIPreview.png",
+          title: "KPI",
+          link: "/iot-app-kit/?path=/docs/assistant-components-kpi--docs",
+          description: "The Key Performance Indicator (KPI) component provides a compact representation when you need an overview of your asset properties. This overview provides critical insights into the overall performance of your devices, equipment, and processes."
+        },
+        {
+          name: "Gauge",
+          image: "/iot-app-kit/assets/GaugePreview.png",
+          title: "Gauge",
+          link: "/iot-app-kit/?path=/docs/assistant-components-gauge--docs",
+          description: "The Gauge component provides a compact representation of an overview of your asset properties. Visualize critical insights into the overall performance of your devices, equipment, or processes."
+        },
+        {
+          name: "Chart",
+          image: "/iot-app-kit/assets/ChartPreview.png",
+          title: "Chart",
+          link: "/iot-app-kit/?path=/docs/assistant-components-chart--docs",
+          description: "The chart component is a way to visualize and navigate time series data from one or more data sources.Chart supports a rich set of features including trend cursors, thresholds, high performance live-streaming and smooth syncing across other IoT App Kit components."
+        },
+        {
+          name: "Chatbot",
+          image: "/iot-app-kit/assets/ChatbotPreview.png",
+          title: "Chatbot",
+          link: "/iot-app-kit/?path=/docs/assistant-components-chatbot--docs",
+          description: "The Assistant Chatbot component provides an interactive chat interface for conversational dive-deeps in IoT applications."
+        },
+        {
+          name: "Table",
+          title: "Table",
+          link: "/iot-app-kit/?path=/docs/assistant-components-table--docs",
+          description: "Presents data in a two-dimensional table format, arranged in columns and rows in a rectangular form."
+        },
+      ]}
+      loadingText="Loading resources"
+      empty={`No resources`}
+      />
+  );
+}
diff --git a/apps/doc-site/stories/components/chart/Docs.mdx b/apps/doc-site/stories/components/chart/Docs.mdx
@@ -295,6 +295,25 @@ This specifies the color and position of the legend section. Default value is `u
 
 <Canvas sourceState="hidden"  story={{height : '450px' }}  of={ChartStories.StandardWithLegend} />
 
+#### assistant
+##### (object, optional)
+This specifies settings to enable the IoT Sitewise AI assistant within the component. Please refer to the [AWS documentation for more details about IoT Sitewise AI assistant](https://aws.amazon.com/iot-sitewise/features/). 
+
+<Markdown>
+{`
+| Name         | Type         | Default        | Description         |
+| ------------ | ------------ | -------------- | ------------------- |
+| \`client\` | object, required | - | Specifies an instantiated assistant client \`IoTSitewiseAssistantClient\`, the assistant client is responsible for interfacing with the Assistant API.|
+| \`conversationId\` | string, required | - | Defines a conversation ID to be used as unique identifier for conversations with the assistant, the conversation ID can be the same for multiple components or unique, depending on use cases. |
+| \`componentId\` | string, required | - | Each component **must define an unique ID** which will be used by the assistant to manage state and assistant results. |
+| \`target\` | object, required | - | Defines the target for the assistant actions, the target options are \`dashboard\` and \`widget\`. For target \`dashboard\` all assistant results will be broadcasted to the Dashboard component, for target \`widget\` the assistant results will be display next to the component. |
+| \`enabled\` | boolean, optional | true | Allows to disable or enable the assistant at the component level. |
+| \`onAction\` | event, optional | - | Allows to pass a callback function to listen for any assistant action within the component. |
+`}
+</Markdown>
+
+**Complete code examples and demos in [Assistant/Components/Chart](/iot-app-kit/?path=/docs/assistant-components-chart--docs) docs.**
+
 ## Alarms
 
 <Canvas sourceState="none"  story={{height : '450px' }}  of={ChartStories.Alarm} />

diff --git a/apps/doc-site/stories/components/gauge/Docs.mdx b/apps/doc-site/stories/components/gauge/Docs.mdx
@@ -178,7 +178,7 @@ It has the following style settings that are customizable:
 
 #### assistant
 ##### (object, optional)
-This specifies settings to enable the IoT Sitewise AI assistant within the component. Please refer to the [AWS documentation for more details about IoT Sitewise AI assistant](#). 
+This specifies settings to enable the IoT Sitewise AI assistant within the component. Please refer to the [AWS documentation for more details about IoT Sitewise AI assistant](https://aws.amazon.com/iot-sitewise/features/). 
 
 <Markdown>
 {`
@@ -193,49 +193,7 @@ This specifies settings to enable the IoT Sitewise AI assistant within the compo
 `}
 </Markdown>
 
-<Source dark="true" code={`import React, { useEffect } from 'react';
-import { Gauge, useAssistant } from '@iot-app-kit/react-components';
-import { IoTSitewiseAssistantClient } from '@iot-app-kit/core-util';
-
-export const GaugeWithAssistant = () => {
-  const client = new IoTSitewiseAssistantClient({
-    iotSiteWiseClient
-  });
-
-  const { generateSummary } = useAssistant({
-    assistantClient: client,
-  });
-
-  useEffect(() => {
-    generateSummary({
-      componentId: 'my-kpi-component-id',
-      conversationId: 'my-conversation-id',
-      target: 'widget',
-      utterance: 'generate a summary and return the response in markdown format.',
-    });
-  }, []);
-
-  return (
-    <Gauge
-      query: sitewise,
-      settings: {
-        showUnit: true,
-        showName: true,
-        showTimestamp: true,
-        showAggregationAndResolution: true,
-        fontSize: 30,
-        secondaryFontSize: 12,
-        backgroundColor: '#ffffff',
-      }
-      assistant={{
-        client,
-        componentId: 'my-kpi-component-id',
-        conversationId: 'my-conversation-id',
-        target: 'widget',
-      }}
-    />
-  );
-};`} />
+**Complete code examples and demos in [Assistant/Components/Gauge](/iot-app-kit/?path=/docs/assistant-components-gauge--docs) docs.**
 
 ## Alarms
 

diff --git a/apps/doc-site/stories/components/kpi/Docs.mdx b/apps/doc-site/stories/components/kpi/Docs.mdx
@@ -116,7 +116,7 @@ For more information, [Number.toFixed](https://developer.mozilla.org/en-US/docs/
 
 #### assistant
 ##### (object, optional)
-This specifies settings to enable the IoT Sitewise AI assistant within the component. Please refer to the [AWS documentation for more details about IoT Sitewise AI assistant](#). 
+This specifies settings to enable the IoT Sitewise AI assistant within the component. Please refer to the [AWS documentation for more details about IoT Sitewise AI assistant](https://aws.amazon.com/iot-sitewise/features/). 
 
 <Markdown>
 {`
@@ -131,52 +131,7 @@ This specifies settings to enable the IoT Sitewise AI assistant within the compo
 `}
 </Markdown>
 
-<Canvas sourceState="none" story={{ height : '550px' }} of={KpiStories.Assistant} />
-<Source dark="true" code={`import React, { useEffect } from 'react';
-import { KPI, useAssistant } from '@iot-app-kit/react-components';
-import { IoTSitewiseAssistantClient } from '@iot-app-kit/core-util';
-
-export const KPIWithAssistant = () => {
-  const client = new IoTSitewiseAssistantClient({
-    iotSiteWiseClient
-  });
-
-  const { generateSummary } = useAssistant({
-    assistantClient: client,
-  });
-
-  useEffect(() => {
-    generateSummary({
-      componentId: 'my-kpi-component-id',
-      conversationId: 'my-conversation-id',
-      target: 'widget',
-      utterance: 'generate a summary and return the response in markdown format.',
-    });
-  }, []);
-
-  return (
-    <div style={{ width: '300px', height: '200px', border: '1px solid lightgrey' }}>
-      <KPI
-        query: sitewise,
-        settings: {
-          showUnit: true,
-          showName: true,
-          showTimestamp: true,
-          showAggregationAndResolution: true,
-          fontSize: 30,
-          secondaryFontSize: 12,
-          backgroundColor: '#ffffff',
-        }
-        assistant={{
-          client,
-          componentId: 'my-kpi-component-id',
-          conversationId: 'my-conversation-id',
-          target: 'widget',
-        }}
-      />
-    </div>
-  );
-};`} />
+**Complete code examples and demos in [Assistant/Components/KPI](/iot-app-kit/?path=/docs/assistant-components-kpi--docs) docs.**
 
 ## Alarms
 

diff --git a/apps/doc-site/stories/components/kpi/Kpi.stories.tsx b/apps/doc-site/stories/components/kpi/Kpi.stories.tsx
@@ -1,5 +1,4 @@
-import { useEffect } from 'react';
-import { KPI, useAssistant } from '@iot-app-kit/react-components';
+import { KPI } from '@iot-app-kit/react-components';
 import {
   mockSinWaveData,
   mockSinWaveDataWithQuality,
@@ -8,9 +7,7 @@ import {
   mockTimeSeriesDataQueryWithError,
   mockTimeSeriesDataQueryLoading,
 } from '@iot-app-kit/testing-util';
-import { IoTSitewiseAssistantClient } from '@iot-app-kit/core-util';
 import { type Meta, type StoryObj } from '@storybook/react';
-import { MockInvokeAssistant } from '../../mockAssistantAPI';
 
 // More on how to set up stories at: https://storybook.js.org/docs/7.0/react/writing-stories/introduction
 const meta: Meta<typeof KPI> = {
@@ -155,61 +152,3 @@ export const SignificantDigits: Story = {
     significantDigits: 2,
   },
 };
-
-const componentId = 'a8cdf292-8a1c-4809-9c9a-3485d88c447b';
-const client = new IoTSitewiseAssistantClient({
-  iotSiteWiseClient: {
-    invokeAssistant: MockInvokeAssistant,
-  },
-  defaultContext: '',
-});
-
-export const Assistant: Story = {
-  render: (props) => {
-    const { generateSummary } = useAssistant({
-      assistantClient: client,
-    });
-
-    useEffect(() => {
-      generateSummary({
-        componentId,
-        conversationId: crypto.randomUUID(),
-        target: 'widget',
-        utterance:
-          'generate a summary and return the response in markdown format.',
-      });
-    }, []);
-
-    return (
-      <div
-        style={{
-          width: '300px',
-          height: '200px',
-          border: '1px solid lightgrey',
-        }}
-      >
-        <KPI
-          {...props}
-          assistant={{
-            client,
-            componentId,
-            conversationId: 'mockConversationId',
-            target: 'widget',
-          }}
-        />
-      </div>
-    );
-  },
-  args: {
-    query: mockSinWaveData('5s'),
-    settings: {
-      showUnit: true,
-      showName: true,
-      showTimestamp: true,
-      showAggregationAndResolution: true,
-      fontSize: 30,
-      secondaryFontSize: 12,
-      backgroundColor: '#ffffff',
-    },
-  },
-};
diff --git a/apps/doc-site/stories/components/table/Docs.mdx b/apps/doc-site/stories/components/table/Docs.mdx
@@ -269,6 +269,25 @@ If set to true, the pagination will enable for the table. Use it together with `
 ##### (number, optional)
 The number of items it should display in a table page. Available only if you specify the `paginationEnabled` property as true.
 
+#### assistant
+##### (object, optional)
+This specifies settings to enable the IoT Sitewise AI assistant within the component. Please refer to the [AWS documentation for more details about IoT Sitewise AI assistant](https://aws.amazon.com/iot-sitewise/features/). 
+
+<Markdown>
+{`
+| Name         | Type         | Default        | Description         |
+| ------------ | ------------ | -------------- | ------------------- |
+| \`client\` | object, required | - | Specifies an instantiated assistant client \`IoTSitewiseAssistantClient\`, the assistant client is responsible for interfacing with the Assistant API.|
+| \`conversationId\` | string, required | - | Defines a conversation ID to be used as unique identifier for conversations with the assistant, the conversation ID can be the same for multiple components or unique, depending on use cases. |
+| \`componentId\` | string, required | - | Each component **must define an unique ID** which will be used by the assistant to manage state and assistant results. |
+| \`target\` | object, required | - | Defines the target for the assistant actions, the target options are \`dashboard\` and \`widget\`. For target \`dashboard\` all assistant results will be broadcasted to the Dashboard component, for target \`widget\` the assistant results will be display next to the component. |
+| \`enabled\` | boolean, optional | true | Allows to disable or enable the assistant at the component level. |
+| \`onAction\` | event, optional | - | Allows to pass a callback function to listen for any assistant action within the component. |
+`}
+</Markdown>
+
+**Complete code examples and demos in [Assistant/Components/Table](/iot-app-kit/?path=/docs/assistant-components-table--docs) docs.**
+
 ## Alarms
 
 <Canvas sourceState='hidden' of={TableStories.Alarm} />

diff --git a/packages/doc-site/stories/assistant/Overview.mdx b/packages/doc-site/stories/assistant/Overview.mdx
@@ -0,0 +1,26 @@
+import { Meta, IconGallery, IconItem } from '@storybook/blocks';
+import { AssistantComponentsCards } from "../../common/cards";
+
+<Meta title="Assistant/Overview" />
+
+# AWS IoT SiteWise Assistant
+
+AWS IoT SiteWise Assistant, a generative AI-powered assistant in AWS IoT SiteWise that allows industrial users to gain insights, 
+solve problems, and take actions from their operational data and other data sources intuitively using natural language queries.
+
+## Get Started
+Please check our user guide about how to setup and enable the AWS IoT Sitewise assistant: [https://docs.aws.amazon.com/iot-sitewise/latest/userguide/assistant-get-started.html](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/assistant-get-started.html)
+
+## Features
+
+For more details, please read [Transforming industrial decision making with AWS IoT SiteWise Assistant](https://aws.amazon.com/blogs/industries/transforming-industrial-decision-making-with-aws-iot-sitewise-assistant/)
+
+- Summarization: Cut through the noise
+- Deep-dive: Uncover Insights with Q&A
+- Analysis: Accelerating Decision-Making
+- Seamless Integration and Accessibility
+- Security and Privacy
+
+## AI-aware app kit components 
+
+<AssistantComponentsCards />