chore: add assistant documentation, overview and kpi

chore: add gauge
awslabs · Nov 22, 2024 · 1536e10 · 1536e10
1 parent 25c456c
commit 1536e10
Show file tree

Hide file tree

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

diff --git a/packages/doc-site/assets/ChatbotPreview.png b/packages/doc-site/assets/ChatbotPreview.png
diff --git a/packages/doc-site/common/cards.jsx b/packages/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/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 />
diff --git a/packages/doc-site/stories/assistant/components/Gauge.mdx b/packages/doc-site/stories/assistant/components/Gauge.mdx
@@ -0,0 +1,72 @@
+import { Canvas, Meta, Story, Source, Markdown } from '@storybook/blocks';
+import * as GaugeStories from './Gauge.stories';
+
+# Gauge
+
+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. 
+Interact with IoT data from one or more data sources with Gauge.
+
+<Meta title="Assistant/Components/Gauge" />
+
+## 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>
+
+<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: {
+        gaugeThickness: 30,
+        showUnit: true,
+        showName: false,
+        fontSize: 40,
+        labelFontSize: 16,
+        unitFontSize: 16,
+        yMin: 0,
+        yMax: 100,
+      }
+      assistant={{
+        client,
+        componentId: 'my-kpi-component-id',
+        conversationId: 'my-conversation-id',
+        target: 'widget',
+      }}
+    />
+  );
+};`} />
diff --git a/packages/doc-site/stories/assistant/components/Gauge.stories.tsx b/packages/doc-site/stories/assistant/components/Gauge.stories.tsx
@@ -0,0 +1,79 @@
+import { useEffect } from 'react';
+// eslint-disable-next-line import/default
+import { Gauge, useAssistant} from '@iot-app-kit/react-components';
+import {
+  mockSinWaveDataWithQuality,
+} from '@iot-app-kit/testing-util';
+import { type Meta, type StoryObj } from '@storybook/react';
+import { IoTSitewiseAssistantClient } from '@iot-app-kit/core-util';
+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 Gauge> = {
+  title: 'Assistant/Components/Gauge',
+  component: Gauge,
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Gauge>;
+
+const componentId1 = 'a1cdf292-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: componentId1,
+        conversationId: crypto.randomUUID(),
+        target: 'widget',
+        utterance:
+          'generate a summary and return the response in markdown format.',
+      });
+    }, []);
+
+    return (
+      <div
+        style={{
+          width: '400px',
+          height: '300px',
+          border: '1px solid lightgrey',
+          margin: '0 auto',
+        }}
+      >
+        <Gauge 
+          {...props}
+          assistant={{
+            client,
+            componentId: componentId1,
+            conversationId: 'mockConversationId',
+            target: 'widget',
+          }}
+        />
+      </div>
+    );
+  },
+  args: {
+    query: mockSinWaveDataWithQuality({ frequency: '5s', positiveOnly: true }),
+    settings: {
+      gaugeThickness: 30,
+      showUnit: true,
+      showName: false,
+      fontSize: 40,
+      labelFontSize: 16,
+      unitFontSize: 16,
+      yMin: -100,
+      yMax: 100,
+    },
+  },
+};
diff --git a/packages/doc-site/stories/assistant/components/KPI.mdx b/packages/doc-site/stories/assistant/components/KPI.mdx
@@ -0,0 +1,82 @@
+import { Canvas, Meta, Story, Source, Markdown } from '@storybook/blocks';
+import * as KPIStories from './KPI.stories';
+
+<Meta of={KPIStories} />
+
+# KPI
+
+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.
+The KPI component lets you can interact with IoT data from one or more data sources.
+
+## 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>
+
+<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>
+  );
+};`} />
+
+## Alarms
+
+<Canvas sourceState='hidden' of={KPIStories.Alarm} />
+
+When you add an IoT SiteWise alarm to the KPI the alarm's state will be displayed as a label, and the alarm's threshold will be added.
+
+An IoT SiteWise alarm is triggered based on a SiteWise input property. The associated input property data will automatically be displayed on the KPI as well.