Merge branch 'main' into agh-doc-review

Author: alguadam

README.md

@@ -1,12 +1,12 @@
 # Real-Time Intelligence for Operations Solution Accelerator
 
-This solution accelerator provides the architecture and working solution for real-time intelligence for operations. We used simulated manufacturing facility asset data for the process flow.  As real-time events are streamed in, anomalies are detected with notifications sent to a specified Outlook email account. The solution includes a customized Fabric Data Agent that provides a chat experience to answer users' questions with intelligence derived from the data. 
+This solution accelerator provides the architecture and working solution for real-time intelligence for operations. We used simulated manufacturing facility asset data for the process flow. As real-time events are streamed in, anomalies are detected with notifications sent to a specified Outlook email account. The solution includes a customized Fabric Data Agent that provides a chat experience to answer users' questions with intelligence derived from the data.
 
 **Key use cases include:**
 
-- Real-time dashboard with up to date analysis and reporting  
-- Anomaly detection and notification 
-- Customized data agent answering users' questions with intelligence derived from the data 
+- Real-time dashboard with up-to-date analysis and reporting.
+- Anomaly detection and notification.
+- Customized data agent answering users' questions with intelligence derived from the data.
 
 <br/>
 
@@ -34,10 +34,10 @@ Below diagram illustrates the solution architecture.
 ### How to customize
 If you'd like to customize the solution accelerator, here are some common areas to start: 
 
-- Data generation and collection: You can customize the data simulator to generate data that is closely aligned with your own industry or your own company. 
-- Update the KQL queries for the tiles in Real-Time intelligence dashboard.  
-- Update the Activator rules to meet your business needs
-- Update the instructions to the Fabric Data Agent to align with your own business goals and data insights. 
+- Data generation and collection: You can customize the data simulator to generate data that is closely aligned with your own industry or your own company.
+- Update the KQL queries for the tiles in Real-Time Intelligence dashboard.
+- Update the Activator rules to meet your business needs.
+- Update the instructions to the Fabric Data Agent to align with your own business goals and data insights.
 
 <br/>
 
@@ -57,15 +57,15 @@ If you'd like to customize the solution accelerator, here are some common areas
 <details>
   <summary>Click to learn more about the key features this solution enables</summary> 
 
-  - **Fabric Data Ingestion Program and Real Time Event Simulator** <br/>One-time batch historical data simulator and real-time telemetry data simulator are provided. For more details, please refer to [Fabric Data Ingestion Guide](./docs/FabricDataIngestion.md) and  [Event Simulator Guide](./docs/EventSimulatorGuide.md).
+  - **Fabric Data Ingestion Program and Real-Time Event Simulator** <br/>One-time batch historical data simulator and real-time telemetry data simulator are provided. For more details, please refer to [Fabric Data Ingestion Guide](./docs/FabricDataIngestion.md) and [Event Simulator Guide](./docs/EventSimulatorGuide.md).
 
-  - **Real Time Intelligence Operations Dashboard** <br/>Real-Time Intelligence Operations Dashboard provides overview on how manufacturing assets are performing, and showing individual sensor data trends. For details, please refer to [Real Time Intelligence Dashboard Guide](./docs/RealTimeIntelligenceDashboardGuide.md).
+  - **Real-Time Intelligence Operations Dashboard** <br/>Real-Time Intelligence Operations Dashboard provides an overview of how manufacturing assets are performing, and shows individual sensor data trends. For details, please refer to [Real-Time Intelligence Dashboard Guide](./docs/RealTimeIntelligenceDashboardGuide.md).
 
   - **Fabric EventHouse with Customized Fabric Data Agent**
 
-    Manufacturing telemetry data is hosted in Fabric EventHouse. You can use conversational interface powered by Fabric Data Agent for live operational queries.  For details, please refer to [Fabric Data Agent Guide](./docs/FabricDataAgentGuide.md).
+    Manufacturing telemetry data is hosted in Fabric EventHouse. You can use conversational interface powered by Fabric Data Agent for live operational queries. For details, please refer to [Fabric Data Agent Guide](./docs/FabricDataAgentGuide.md).
 
-  - **Anomaly Detection and Alerts through Fabric Activator** <br/>Microsoft Activator is configured with anomaly detection rules that triggers outlook email notifications when an anomaly occurs. For more details, please refer to [Activator Guide](./docs/ActivatorGuide.md).
+  - **Anomaly Detection and Alerts through Fabric Activator** <br/>Microsoft Activator is configured with anomaly detection rules that trigger Outlook email notifications when an anomaly occurs. For more details, please refer to [Activator Guide](./docs/ActivatorGuide.md).
 
   - **Useful Data Analysis and Performance Metrics KQL Code** <br/>Reusable KQL code is provided to get you started quickly. For details, please refer to [Data Analysis KQL Guide](./src/kql/data_analysis/data_analysis_guide.md) and [Performance Metrics KQL Queryset Guide](./src/kql/kql_queryset/kql_queryset_guide.md). 
 
@@ -97,7 +97,7 @@ cd real-time-intelligence-operations-solution-accelerator
 azd auth login # Required to deploy with azd up
 az login # Required to use the Azure CLI commands that connect Azure resources to Fabric workspace
 
-# Recommended: set email to recieve alerts
+# Recommended: set email to receive alerts
 azd env set FABRIC_ACTIVATOR_ALERTS_EMAIL "myteam@company.com"
 
 
@@ -158,13 +158,13 @@ Business use case
 </h2>
 Use cases can be summarized as below:
 
-- For manufacturing plants, the plant manager or other business stakeholders can use the Fabric Data Agent to get business and operations intelligence quickly without the need to create query code. For details, please refer to [Fabric Data Agent Guide](./docs/FabricDataAgentGuide.md). 
+- For manufacturing plants, the plant manager or other business stakeholders can use the Fabric Data Agent to get business and operations intelligence quickly without the need to create query code. For details, please refer to [Fabric Data Agent Guide](./docs/FabricDataAgentGuide.md).
 
-- For manufacturing plants, the designated operations team receives email notification when anomaly occurs. The solution can also be configured to send anomaly notifications to a Teams Channel. For rule configuration options (Email or Teams), please refer to [Activator Guide](./docs/ActivatorGuide.md).
+- For manufacturing plants, the designated operations team receives email notification when an anomaly occurs. The solution can also be configured to send anomaly notifications to a Teams Channel. For rule configuration options (Email or Teams), please refer to [Activator Guide](./docs/ActivatorGuide.md).
 
 - Plant manager uses real-time dashboard to analyze manufacturing plant asset performance, key telemetry data over time.
 
-  The image below shows the first page of the real-time intelligence operations dashboard, which displays sensor status, quality metrics, and individual sensor data trends. The second page shows additional information such as daily anomaly rate by asset, asset maintenance status, and fault correlations.  For more details, please refer to [Real Time Intelligence Operations Dashboard Guide](./docs/RealTimeIntelligenceDashboardGuide.md). 
+  The image below shows the first page of the real-time intelligence operations dashboard, which displays sensor status, quality metrics, and individual sensor data trends. The second page shows additional information such as daily anomaly rate by asset, asset maintenance status, and fault correlations. For more details, please refer to [Real-Time Intelligence Operations Dashboard Guide](./docs/RealTimeIntelligenceDashboardGuide.md). 
 
 | ![image](./docs/images/readme/rti-dashboard.png) |
 | ------------------------------------------------ |
@@ -177,21 +177,20 @@ Use cases can be summarized as below:
 <details>
   <summary>Click to learn more about what value this solution provides</summary>
 
-  -  **The solution provides multiple business functions with a simple architecture** <br/>
-    The deployed solution provides real time telemetry data monitoring, analysis, summarization, graphical reports, anomaly detection and notifications with a quick to deploy, secure, and simple architecture. 
+  - **The solution provides multiple business functions with a simple architecture** <br/>
+    The deployed solution provides real-time telemetry data monitoring, analysis, summarization, graphical reports, anomaly detection and notifications with a quick to deploy, secure, and simple architecture.
 
   - **A Fabric Data Agent getting quick business intelligence without programming effort.** <br/>
-    The Fabric Data Agent can be quickly configured with instructions delivered in this solution accelerator, providing quick and accurate insights from data effortlessly. No programming skills are necessary. 
+    The Fabric Data Agent can be quickly configured with instructions delivered in this solution accelerator, providing quick and accurate insights from data effortlessly. No programming skills are necessary.
 
-  - **Real Time Intelligence for Operations Dashboard**<br/>
-    The deployed solution accelerator provides a working architecture with best practices, security, components integration, and real-time intelligence for operations dashboard. 
+  - **Real-Time Intelligence for Operations Dashboard**<br/>
+    The deployed solution accelerator provides a working architecture with best practices, security, components integration, and real-time intelligence for operations dashboard.
 
   - **Configurable Activator providing anomaly detection and notifications** <br/>
-    The deployed and configurable Activator provides real time anomaly detection and alert notifications out of the box. The rules are easily configurable. 
+    The deployed and configurable Activator provides real-time anomaly detection and alert notifications out of the box. The rules are easily configurable.
 
-  - **Reusable and updatable real time event simulator and batch data update program** <br/>
-
-    Real time telemetry data simulator and batch data ingestion / update program are provided to help to bring the solution to simulate a real time environment quickly. 
+  - **Reusable and updatable real-time event simulator and batch data update program** <br/>
+    Real-time telemetry data simulator and batch data ingestion / update program are provided to help to bring the solution to simulate a real-time environment quickly. 
 
 </details>
 
@@ -228,7 +227,7 @@ Check out similar solution accelerators
 | Solution Accelerator | Description |
 |---|---|
 | [Unified Data Foundation with Microsoft Fabric](https://github.com/microsoft/unified-data-foundation-with-fabric-solution-accelerator) | Unified Data Foundation with Microsoft Fabric with Options to Integrate with Azure Databricks and Microsoft Purview. |
-| [Agentic applications for unified data foundation](https://github.com/microsoft/agentic-applications-for-unified-data-foundation-solution-accelerator) | Agentic AI application that provides nature language query of the data using unified data foundation.  Description of solution accelerator. |
+| [Agentic applications for unified data foundation](https://github.com/microsoft/agentic-applications-for-unified-data-foundation-solution-accelerator) | Agentic AI application that provides natural language query of the data using unified data foundation. Description of solution accelerator. |
 
 <br/>   
 

docs/ActivatorGuide.md

@@ -16,7 +16,7 @@ After you are done with the updates, you can click `Save`, and then `Start` to a
 
 ![Activator Rule Example](../docs/images/deployment/activator-rule-example-vibration.png)
 
-If any one of the rules were triggered by the set condition, for example, the rule set for high vibration, an email alert ill be sent to the specified account, as illustrated below.
+If any one of the rules were triggered by the set condition, for example, the rule set for high vibration, an email alert will be sent to the specified account, as illustrated below.
 
 ![Email Alert](../docs/images/deployment/activator-email-alert.png)
 

docs/DemonstratorGuide.md

@@ -6,12 +6,12 @@ Please review the Access Requirements Section to ensure you have proper access f
 
 ## Access Requirements 
 
-If you deployed the solution accelerator via AZD following the [Deployment Guide](./DeploymentGuide.md), you have already established the required access to the solution, and **you can skip this section**. 
+If you deployed the solution accelerator via AZD following the [Deployment Guide](./DeploymentGuide.md), you have already established the required access to the solution, and **you can skip this Access Requirements section**, and start at [Step 1. Refresh Historical Data](#step-1-refresh-historical-data).
 
 If you are using a demonstration environment already set up by someone else, you will need below accesses: 
 
-1. You will need to be added as a contributor/viewer of the Fabric workspace. If you are a viewer, you will not be able to update any resources such as [Real-Time Intelligence Operations Dashboard](./RealTimeIntelligenceDashboardGuide.md) or [Activator](./ActivatorGuide.md). If you are a contributor, you will be able to update all the resources in Fabric workspace. **Recommend role: Viewer**. 
-2. You will need to be able to send simulated events to the Azure Event Hub deployed with the solution. The owner of the Event Hub or your Azure Admin can add you to the role of Azure Event Hubs Data Sender. Below diagram illustrates the key steps. 
+1. You will need to be added as a contributor of the Fabric workspace. If you are a viewer, you will not be able to update any resources such as [Real-Time Intelligence Operations Dashboard](./RealTimeIntelligenceDashboardGuide.md) or [Activator](./ActivatorGuide.md). Recommend role: **contributor**. 
+2. You will need to be able to send simulated events to the Azure Event Hub deployed with the solution. The owner of the Event Hub or your Azure Admin can add you to the role of **Azure Event Hubs Data Sender**. Below diagram illustrates the key steps. 
 
 ![Event Hubs Data Sender Role](../docs/images/deployment/eventhubs-data-sender-role.png)
 

docs/FabricDataIngestion.md

@@ -25,6 +25,7 @@ az login
 ```
 
 ```bash
+cd infra/scripts/fabric
 python fabric_data_ingester.py --cluster-uri <CLUSTER_URI> --database <DATABASE_NAME> [OPTIONS]
 ```
 

docs/RealTimeIntelligenceDashboardGuide.md

@@ -2,22 +2,22 @@
 
 ## Overview
 
-The Real-Time Intelligence (RTI) Operations Dashboard provides instant visibility into the health and performance of key assets at manufacturing facility located at **Contoso Outdoors – Ho Chi Minh Facility**.
+The Real-Time Intelligence (RTI) Operations Dashboard provides instant visibility into the health and performance of key assets at a manufacturing facility located at **Contoso Outdoors – Ho Chi Minh Facility**.
 It monitors two critical assets:
 
 - **Robotic Arm 1 (A_1000)**
 - **Packaging Line 1 (A_1001)**
 
-The dashboard uses **live sensor data, Z-score–based anomaly detection**, and **trend analysis** to help teams identify issues early, prevent downtime, and improve product quality. For more information about the statistical z-score analysis, please refer to [Data Analysis Guide](../src/kql/data_analysis/data_analysis_guide.md) for the details. 
+The dashboard uses **live sensor data, Z-score-based anomaly detection**, and **trend analysis** to help teams identify issues early, prevent downtime, and improve product quality. For more information about the statistical z-score analysis, please refer to [Data Analysis Guide](../src/kql/data_analysis/data_analysis_guide.md) for the details. 
 
 ## Data Requirement 
 
 The dashboard's effectiveness depends on the quality of the underlying dataset. To ensure accurate analysis using the sample data provided by this solution accelerator:
 
-1. **Refresh Historical Data**: Follow the [Fabric Data Ingestion Guide](./FabricDataIngestion.md) to load baseline data. Use the options `--refresh-dates` and `--overwrite` to get a fresh and up to date dataset. 
+1. **Refresh Historical Data**: Follow the [Fabric Data Ingestion Guide](./FabricDataIngestion.md) to load baseline data. Use the options `--refresh-dates` and `--overwrite` to get a fresh and up-to-date dataset.
 2. **Start Real-Time Simulation**: Use the [Event Simulator Guide](./EventSimulatorGuide.md) to generate streaming telemetry.
 
-The event simulator streams real-time telemetry data into the Fabric Event House, which serves as the data source for the RTI Operations Dashboard. It supports multiple operational modes: **Normal Mode** and **Enhanced Anomaly Mode**
+The event simulator streams real-time telemetry data into the Fabric Event House, which serves as the data source for the RTI Operations Dashboard. It supports multiple operational modes: **Normal Mode** and **Enhanced Anomaly Mode**..
 
 
 ## RTI Operations Dashboard 
@@ -32,7 +32,7 @@ The Real-Time Intelligence Operations Dashboard is a two-page interactive dashbo
 
 ### Page 1: Asset Performance Overview
 
-This page serves as main monitoring view. It shows current equipment health, sensor status, and key performance trends.
+This page serves as the main monitoring view. It shows current equipment health, sensor status, and key performance trends.
 
 
 ![image](images/readme/rti-dashboard-pg1.png)
@@ -46,8 +46,8 @@ Displays latest sensor readings with real-time anomaly status. Each row shows Sp
 Side-by-side comparison of anomaly rates and quality issues between assets in a column chart format. Uses Z-score analysis with a 30-day baseline (excludes last 24 hours).
 
 - Key Metrics Displayed:
-  - **Anomaly Rate %:** Combined percentage of speed, temperature, and vibration anomalies
-  - **Quality Issues %:** Percentage of events with defect probability exceeding 5%
+  - **Anomaly Rate %**: Combined percentage of speed, temperature, and vibration anomalies
+  - **Quality Issues %**: Percentage of events with defect probability exceeding 5%
 
 
 #### Trend Analysis 
@@ -73,14 +73,14 @@ This table highlights how often different sensor metrics experience anomalies to
 
 **Columns Explained:**
 
-- **Asset**: Name of the equipment being monitored.
-- **Speed→Temp**: How often speed anomalies coincide with temperature anomalies.
-- **Speed→Vibration**: Indicates if speed fluctuations are linked to mechanical stress.
-- **Speed→Quality**: Shows whether abnormal speed impacts defect probability.
-- **Temp→Vibration**: Correlation between thermal issues and vibration problems.
-- **Temp→Quality**: Highlights if overheating affects product quality.
-- **Vibration→Quality**: Relationship between mechanical health and manufacturing precision.
-- **Total Anomalies**: Combined count of all anomaly events for the asset.
+- **Asset**: Name of the equipment being monitored
+- **Speed→Temp**: How often speed anomalies coincide with temperature anomalies
+- **Speed→Vibration**: Indicates if speed fluctuations are linked to mechanical stress
+- **Speed→Quality**: Shows whether abnormal speed impacts defect probability
+- **Temp→Vibration**: Correlation between thermal issues and vibration problems
+- **Temp→Quality**: Highlights if overheating affects product quality
+- **Vibration→Quality**: Relationship between mechanical health and manufacturing precision
+- **Total Anomalies**: Combined count of all anomaly events for the asset
 
 **Example Interpretations:**