Merge pull request Azure-Samples#136 from Azure-Samples/pmishra/retail_soln_doc_updates

fixed doc links for eCommerce copilot

Author: vivekchettiar

Solution_Accelerators/Retail/ARCHITECTURE.md

@@ -13,7 +13,7 @@
   - [AI skills](#ai-skills)
     - [Image Describer Skill](#image-describer-skill)
     - [Recommender Skill](#recommender-skill)
-- [Sharing Intermediate Results](#sharing-intermediate-skill)
+- [Sharing Intermediate Results](#sharing-intermediate-results)
 - [Architecture Features](#Architecture-features)
 - [Secure Runtime and Deployment of Copilot](#secure-runtime-and-deployment-of-copilot)
   - [Security](#security)
@@ -30,8 +30,6 @@
 Ingestion service is a generic service that use different Azure AI services to enrich the content (chunks) as it indexes them to improve search quality.
 For example, when indexing product catalog, it uses AzureOpenAI services to extract salient features of the product images and adds them to the index. This improves searching across product even better.
 
-Have you experiences poor search results on retailer site specially for 3rd party market place products? We think this capability would drastically help improve search results across the board.
-
 The ingestion process primarily consists of three steps: Image Encoding, Catalog Enrichment, and Catalog Indexing.
 
 For more details refer ingestion service documentation [Ingestion Service](./src/skills/ingestion/README_RETAIL.md).
@@ -61,7 +59,7 @@ The orchestrator service acts as the central controller, coordinating between va
 
 #### Configuration Service
 
-The runtime configuration service enhances the architecture's dynamicity and flexibility. It enables core services and AI skills to decouple and parameterize various components, such as prompts, search data settings, and operational parameters. These services can easily override default configurations with new versions at runtime, allowing for dynamic behavior adjustments during operation. The biggest benefit of the configuration service is its ability to expose different configurations for various microservices during runtime, making processes like evaluations much easier - no need for any more deployments. This could also be used to demo against different search indexes as well. Example: default index is the one that is with this repo. However you can bring your own product catalog and create a new Index and use that via runtime configuration. More details on how to configure the entire demo for your data is [here](./Setup.md/#build-your-own-copilot)
+The runtime configuration service enhances the architecture's dynamicity and flexibility. It enables core services and AI skills to decouple and parameterize various components, such as prompts, search data settings, and operational parameters. These services can easily override default configurations with new versions at runtime, allowing for dynamic behavior adjustments during operation. The biggest benefit of the configuration service is its ability to expose different configurations for various microservices during runtime, making processes like evaluations much easier - no need for any more deployments. This could also be used to demo against different search indexes as well. Example: default index is the one that is with this repo. However you can bring your own product catalog and create a new Index and use that via runtime configuration. More details on how to configure the entire demo for your data is [here](./SETUP_RETAIL.md/#build-your-own-copilot)
 
 For more details refer config service documentation [Configuration Service](./src/config_hub/README.md).
 

Solution_Accelerators/Retail/README.md

@@ -18,7 +18,7 @@ This solution enables users to explore retail products such as clothing and acce
 
 Imagine getting ready for a party and finding a complete outfit—simply by conversing with the bot. Whether you're searching for a suit, shoes, or complementary accessories, the bot provides relevant and tailored suggestions.
 
-To showcase the solution’s capabilities, a pre-recorded voiceover demonstrates its functionality, ranging from simple queries to complex multimodal interactions. Watch the [Demo Video](docs/media/Retail_Accelerator_Demo%20(GitHub).mp4) and follow along with the [Demo Script](docs/demo_script/Retail%20Demo_Script.docx).
+To showcase the solution’s capabilities, a pre-recorded voiceover demonstrates its functionality, ranging from simple queries to complex multimodal interactions. Watch the [Demo Video](docs/media/Retail_Accelerator_Demo%20(GitHub).mp4) and follow along with the [Demo Script](docs/demo_script/Retail%20Demo_Script.pdf).
 
 ## Features
 The repository includes a complete end-to-end solution, comprising:
@@ -39,7 +39,7 @@ The solution includes the following key components:
 
 4. **Testing and Evaluation**: This includes the ability to simulate conversations with the copilot, run certain end-to-end tests on demand, and an evaluation tool to help perform end-to-end evaluation of the copilot.
 
-Detailed architecture for the eCommerce Copilot can be found [here](Architecture.md)
+Detailed architecture for the eCommerce Copilot can be found [here](ARCHITECTURE.md)
 
 ![Copilot Solution Architecture](./docs/media/copilot_solution_architecture.png)
 

Solution_Accelerators/Retail/SETUP_RETAIL.md

@@ -2,24 +2,24 @@
 
 ## Table of Contents
 - [Azure Resources Setup](#azure-resources-setup)
-  - [Prerequisites](#prerequisite)
+  - [Prerequisites](#prerequisites)
   - [Deployment Steps](#deployment-steps)
   - [Manual Configuration](#manual-configuration)
     - [Azure OpenAI](#azure-openai)
     - [Azure AI Search](#azure-ai-search)
     - [Creating App registration for user Authentication with EntraID](#creating-app-registration-for-user-authentication-with-entraid)
 - [Deploying Services](#deploying-services)
   - [Running Services Locally](#running-services-locally)
-    - [Prerequisites](#prerequisites)
+    - [Local Setup Prerequisites](#local-setup-prerequisites)
     - [Verify Azure Resources](#verify-azure-resources)
     - [Setup CosmosDB Emulator](#setup-cosmosdb-emulator)
     - [Project Initialization](#project-initialization)
       - [Frontend](#frontend)
       - [Core Microservices](#core-microservices)
-    - [Ingesting Retail data for testing](#ingesting-retail-data-for-testing)
+    - [Ingesting Retail Data for Testing](#ingesting-retail-data-for-testing)
     - [Testing](#testing)
     - [Instrumentation and application logs](#instrumentation-and-application-logs)
-  - [Deploying Services to Azure Kubernetes](#deploying-services-to-azure-kubernetes)
+  - [Deploying Services to Azure](#deploying-services-to-azure)
 - [Build Your Own Copilot](#build-your-own-copilot)
 - [Guidance](#guidance)
 - [Additional Resources](#additional-resources)
@@ -40,17 +40,17 @@ You will also need docker running locally if you want to build and deploy the so
 Installation Instructions: https://docs.docker.com/desktop/setup/install/windows-install/
 
 ### Deployment Steps
-1. Login to [portal.azure.com](portal.azure.com). If you do not have an Azure account, you should create one. Visit [here](https://azure.microsoft.com/en-us/pricing/purchase-options/azure-account/)
+1. Login to [portal.azure.com](https://portal.azure.com). If you do not have an Azure account, you should create one. Visit [here](https://azure.microsoft.com/en-us/pricing/purchase-options/azure-account/)
 
 2. Create a new Resource Group (similar to a folder in windows explorer) where all the azure resources for this PoC would be created. Select the region where these resources needs to be created.
 
 3. Note the Resource Group name, Region and your Azure subscription ID. These will be needed for the later steps
 
-4. Open Windows PowerShell window and change directory to root of this repo: `<repo root>\multimodalbot`
+4. Open Windows PowerShell window and change directory to root of this repo: `<repo root>\Retail`
 
 5. Type `azd init` and hit enter. This will ask for an environment name. Provide a name - say `retail_demo`. You should see a success message that the environment was initialized.
 
-6. Open windows explorer and go to folder `<repo root>\multimodalbot\.azure`. The `.azure` will have `retail_demo` folder with a .env file.
+6. Open windows explorer and go to folder `<repo root>\Retail\.azure`. The `.azure` will have `retail_demo` folder with a .env file.
 
 7. Open text editor and open .env file and, then add your resource group, location, and subscription to the .env file.
 
@@ -63,7 +63,7 @@ Installation Instructions: https://docs.docker.com/desktop/setup/install/windows
       AZURE_SUBSCRIPTION_ID="SubscriptionID_GUID"
       ```
 
-8. Open the `<repo root>\multimodalbot\infra\main.parameters.json` in a file editor. This file has parameters that can be passed to the various azure resources when creating them. 
+8. Open the `<repo root>\Retail\infra\main.parameters.json` in a file editor. This file has parameters that can be passed to the various azure resources when creating them. 
     * Create a web app for the frontend, name of which is as below. Change Line 72 to title your web app, in this case "value": "retail-demo-fe":
 
           ```
@@ -72,7 +72,7 @@ Installation Instructions: https://docs.docker.com/desktop/setup/install/windows
             },
           ```
 
-      Your deployed front end web app will reside in this link- https://retail-demo-fe.azurewebsites.net will be created. Save this link.
+      Your deployed front end web app will reside in this link- https://retail-demo-fe.azurewebsites.net will be created. Save this link. Note: This link will not work until front end is deployed to Azure Web App Service resource.
 
       >Note: These web app names should be unique across azurewebsites.net domain.
 
@@ -118,15 +118,15 @@ Installation Instructions: https://docs.docker.com/desktop/setup/install/windows
         ```
       >Note: If you have access to multiple azure subscriptions you could set the context to the right subscription by running `az account set --subscription <subscription ID>` command first on the PowerShell prompt.
 
-    * Save `<repo root>\multimodalbot\infra\main.parameters.json` file
+    * Save `<repo root>\Retail\infra\main.parameters.json` file
 
     * OPTIONAL:
       To specify your existing Azure resource, see: FAQ.md, "How can I use my own Azure Resources"
 
 9. Deploy your Azure resources, open PowerShell window and type `azd provision`, hit enter.
 
     ```
-          (venv) PS C:\Repo\MultiModalBot> azd provision
+          (venv) PS C:\Repo\Retail> azd provision
     ```
     `azd provision` will install all the resources in the selected resource group. It will open your browser to authenticate you to the azure portal and then continue with the deployment. If all goes well, you should see a message on the command prompt that the application was provisioned, otherwise try to fix the resource deployment issues before proceeding to the next steps of doing some manual updates and configurations.
 
@@ -189,7 +189,7 @@ Installation Instructions: https://docs.docker.com/desktop/setup/install/windows
 
 ## Running Services Locally
 <!-- From README -->
-### Prerequisites
+### Local Setup Prerequisites
 
 Before you begin, ensure you have the following prerequisites installed:
 
@@ -301,7 +301,7 @@ The project is divided into three main components:
 
 #### Frontend
 Frontend is a reactjs/typescript project. 
-Path: `<repo root>/Multimodalbot/src/frontend_retail`
+Path: `<repo root>/Retail/src/frontend_retail`
 
 To run the front end locally follow the steps below:
 
@@ -322,7 +322,7 @@ To run the front end locally follow the steps below:
     ```
     - ![frontendretail](./docs/media/retail_env.png) 
 
-4. On the command prompt, in the `<repo root>/multimodalbot/src/frontend_retail` folder, run `npm install`.
+4. On the command prompt, in the `<repo root>/Retail/src/frontend_retail` folder, run `npm install`.
 5. Run `npm run dev`. This should start the frontend at port 3000. You can browse the frontend (web app) by going to `http://localhost:3000`.
 
 ![signinpage](./docs/media/login_browser.png)
@@ -370,7 +370,7 @@ To run the front end locally follow the steps below:
    > **NOTE**: Core Microservice with a `.debug.env` will be fetched from the KeyVault. So `KEYVAULT-URI` configuration is required and update as needed.
 
 3. **Run and debug services locally inside VS Code**:
-    - Open the folder `<repo root>\multimodalbot` in VSCode:
+    - Open the folder `<repo root>\Retail` in VSCode:
     - Click on `Run and Debug` or Ctrl+Shift+D
     - Click on the `Drop Down Menu` at the top of VSCode
     - Select a Microservice from below then click `Play Button` to start the instance 
@@ -397,7 +397,7 @@ To run the front end locally follow the steps below:
 
 
 ### Ingesting Retail Data for Testing
-- Details on how to use ingestion service to ingest retail data can be found in the [ingestion service readme](../MultiModalBot/src/skills/ingestion/README_RETAIL.md) file.
+- Details on how to use ingestion service to ingest retail data can be found in the [ingestion service readme](../Retail/src/skills/ingestion/README_RETAIL.md) file.
 
 
 ### Testing
@@ -412,7 +412,7 @@ To run the front end locally follow the steps below:
 
 ### Azure Kubernetes Setup
 **Note:**
-Setting up the Azure Kubernetes Service (AKS) and application gateway is only needed if you want the services to be deployed to cloud. Users can proceed with setting up the keyvault and then follow the instructions to [run the solution locally in VSCode](#local-setup). Once that succeeds, they can then come and setup the AKS.
+Setting up the Azure Kubernetes Service (AKS) and application gateway is only needed if you want the services to be deployed to cloud. Users can proceed with setting up the keyvault and then follow the instructions to [run the solution locally in VSCode](#running-services-locally). Once that succeeds, they can then come and setup the AKS.
 
 1. To work with the AKS cluster, developers will need `Azure Kubernetes Service RBAC Admin` role assigned.
 
@@ -422,16 +422,16 @@ Setting up the Azure Kubernetes Service (AKS) and application gateway is only ne
     kubelogin convert-kubeconfig -l azurecli
     ```
 
-3. Update the secrets_provider.yaml file in the `<repo root>\multimodalbot\infra\aks_post_provision` folder  to update `KEYVAULTNAME` name and `TENANTID`, which can be found from your recent deployment of the azure resources. Save the file.
+3. Update the secrets_provider.yaml file in the `<repo root>\Retail\infra\aks_post_provision` folder  to update `KEYVAULTNAME` name and `TENANTID`, which can be found from your recent deployment of the azure resources. Save the file.
 
-4. Run kubectl apply command to apply these changes to AKS cluster. Change directory to `<repo root>\multimodalbot\infra` and run:
+4. Run kubectl apply command to apply these changes to AKS cluster. Change directory to `<repo root>\Retail\infra` and run:
     ```
     kubectl apply -f .\aks_post_provision\secrets_provide.yaml
     ```
 
 5. Deploy redis pods to AKS.
-    1. Review the `<repo root>\multimodalbot\infra\aks_post_provision\redis_deployment.yaml` file for redis password used
-    2. Change directory to `<repo root>\multimodalbot\infra` and run:\
+    1. Review the `<repo root>\Retail\infra\aks_post_provision\redis_deployment.yaml` file for redis password used
+    2. Change directory to `<repo root>\Retail\infra` and run:\
       `
       kubectl apply -f .\aks_post_provision\redis_deployment.yaml
       `
@@ -511,8 +511,8 @@ Additionally, developers would need `Cosmos DB Built-in Data Contributor` role w
     ```
 
 ### Keyvault
-1. To work with keyvault, developers will need GET, LIST and SET permissions to keyvault secrets. Refer [AKS](#aks) to grant these permissions via access policies tab.
-2. Navigate through `config.py` files across micro-services in the `<repo root>\multimodalbot\src` folder: config_hub, skills\search, orchestrator_rag, data, session_manager and add any un-populated secrets with appropriate values in the keyvault. Examples:
+1. To work with keyvault, developers will need GET, LIST and SET permissions to keyvault secrets. Refer [AKS](#azure-kubernetes-setup) to grant these permissions via access policies tab.
+2. Navigate through `config.py` files across micro-services in the `<repo root>\Retail\src` folder: config_hub, skills\search, orchestrator_rag, data, session_manager and add any un-populated secrets with appropriate values in the keyvault. Examples:
     ```
     az keyvault secret set --vault-name <key vault name> --name "KEYVAULT-URI" --value "https://<keyvault name>.vault.azure.net/"
 

Solution_Accelerators/Retail/docs/demo_script/Retail Demo_Script.docx

@@ -34,7 +34,7 @@ if (-Not (Test-Path -Path "$Path/.venv/pip.ini")) {
     Write-Host "Creating pip.ini file in directory $Path/.venv and set up the index-url"
     $pipIniContent = @"
 [global]
-index-url=https://pkgs.dev.azure.com/AIP-CXE-Eng/Engineering/_packaging/CustomerEng/pypi/simple/
+index-url=https://pypi.python.org/simple
 "@
 
   $pipIniPath = Join-Path -Path "$Path/.venv" -ChildPath "pip.ini"

Solution_Accelerators/Retail/docs/demo_script/Retail Demo_Script.pdf

@@ -108,7 +108,7 @@ If you cannot separate new data, you can create a new index. In your search serv
 
 ## Bring your own data
 To bring your data and use this CoPilot on it, the easiest scenario would be when your indexing needs can be met with the existing fields. However if you determine more fields are reqiured then following things needs to be considered:
-1. Search Index: Does all the fields in the current design match to your product catalog. If not, you will need to create new search index with required fileds to index. Here are fields and their configuration for the [current index](../../../infra/search_index/retail_index.json)
+1. Search Index: Does all the fields in the current design match to your product catalog. If not, you will need to create new search index with required fileds to index. Here are fields and their configuration for the [retail_index.json](../../../infra/search_index/retail_index.json)
 2. Ingestion Service: Currently ingestion service expects these additional fields to be present in the index and then uses these fields and images to generate this additional data.
 > a. Uses article_id field to find the product catalog image (one only). 
 ```
@@ -137,7 +137,7 @@ Here is an example of how to invoke [ingestion service](../../../docs/services/i
 3. Update the solution code:
 If your product catalog is in a different domain, you also want to consider updating the prompts used by the [recommender](../recommender/src/prompts_config.yaml) and [image describer](../image_describer/src/static/prompts_config.yaml) skills to match your domain.
 
-4. If there are changes in the fields, then update the [search index template](../cognitiveSearch/src/components/templates/retail.config.json) that the search skil is using to match the updated search index
+4. If there are changes in the fields, then update the [search index template](../Search/src/components/templates/retail.config.json) that the search skil is using to match the updated search index
 
 5. Update the data models used by the Search Skill. They can be found [here](../../common/contracts/skills/search/api_models.py).