#MSIgnite Lab 401 | workshop updates v3 (#207)

nitya · web-flow · commit 149ac9ba54fe · 2024-11-19T09:44:02.000-06:00
* fix / msignite-docs-feedback-v3

* fix / clear outputs in eval notebooks for clean start

* fix / update skillable instructions panel
diff --git a/docs/workshop/docs/02-Setup/1-Provision-And-Setup/01-Self-Guided.md b/docs/workshop/docs/02-Setup/1-Provision-And-Setup/01-Self-Guided.md
@@ -25,7 +25,7 @@ Our development environment uses a Visual Studio Code editor with a Python runti
         ``` title="Tip: Click the icon at far right to copy link"
         https://aka.ms/contoso-chat/prebuild
         ```
-1. You will be prompted to log into GitHub. **Login now**
+1. You will be prompted to log into GitHub. **Login now with your GitHub profile.**
 
 ---
 
diff --git a/docs/workshop/docs/02-Setup/1-Provision-And-Setup/02-Skillable.md b/docs/workshop/docs/02-Setup/1-Provision-And-Setup/02-Skillable.md
@@ -62,12 +62,13 @@ At the end of this step you should have:
     https://aka.ms/contoso-chat/prebuild
     ```
 
-1. You will be prompted to log into GitHub. **Login now**
+1. You will be prompted to log into GitHub. **Login now with your GitHub profile.**
 
 ### 2.2 Setup GitHub Codespaces
 
 1. You will see a page titled **"Create codespace for Azure-Samples/contoso-chat"**
-    - Check that the Branch is `msignite-LAB401`
+    - Check branch is `msignite-LAB401` 
+    - Check dev container config is `Contoso Chat (v2)` and region is `US East`
     - Click dropdown for **2-core** and verify it is `Prebuild ready`
 
     !!! tip "Using the pre-build option makes your GitHub Codespaces load up faster."
@@ -137,25 +138,25 @@ Your GitHub Codespaces is running on the _original_ Azure Samples repo for this
 
 ### 2.4 Check Tools Installed
 
-Use the following commands in the VS Code terminal to verify these tools are installed. This step is optional but gives you a sense for the command-line tools we will use in this lab.
-
-```bash title=""
-python --version
-```
-```bash title=""
-fastapi --version
-```
-```bash title=""
-prompty --version
-```
-```bash title=""
-az version
-```
-```bash title=""
-azd version
-```
-
-!!! success "CONGRATULATIONS. You setup your GitHub Codespaces with your fork of the repo!"
+The workshop uses the following tools and commands: `python`, `fastapi`, `prompty`, `az`, `azd`. These are pre-installed for you, but you can optionally verify these to get a sense for their current versions.
+
+??? task "(Optional: Expand to view details) Verify intalled tools." 
+
+    ```bash title=""
+    python --version
+    ```
+    ```bash title=""
+    fastapi --version
+    ```
+    ```bash title=""
+    prompty --version
+    ```
+    ```bash title=""
+    az version
+    ```
+    ```bash title=""
+    azd version
+    ```
 
 
 ## 3. Authenticate with Azure
diff --git a/docs/workshop/docs/02-Setup/1-Provision-And-Setup/03-Validation.md b/docs/workshop/docs/02-Setup/1-Provision-And-Setup/03-Validation.md
@@ -23,17 +23,17 @@ Here's a reminder of the Azure Application Architecture - let's check our provis
 
 ![ACA Architecture](./../../img/aca-architecture.png)
 
-1. Open a new browser tab and navigate to the link below. You will be prompted to login.
+1. Open a new browser tab and navigate to the link below. You may be prompted to login.
     ``` title=""
     https://portal.azure.com/#browse/resourcegroups
     ```
 
-1. **Sign in** → Use the `Username` and `Password` from the "Azure Credentials" section in your Skillable Lab instructions panel.
+1. **Sign in** → If prompted, use the `Username` and `Password` from the "Azure Credentials" section in your Skillable Lab instructions panel.
 1. You may be presented with a "Welcome to Microsoft Azure" screen. Click **Cancel** (to dismiss it) or click **Get Started** (to take an introductory tour of the Azure Portal).
 1. You should be taken directly to the Resource Groups page for your subscription.
     - You should see an `rg-AITOUR` resource. This was created for you and contains all the resources needed to build and deploy your RAG-based copilot. 
 1. **Click** `rg-AITOUR` to visit the Resource Group overview page.
-    - **Check:** Deployments (under "Essentials") - You should see: *35 succeeded*. 
+    - **Check:** Deployments (look under "Essentials") - You should see: *35 succeeded*. 
     - **Check:** Resources (in Overview) - You should see: *15 resources*.
 
 !!! task "Leave the Azure Portal open on this tab. We'll revisit it later."
@@ -51,14 +51,16 @@ Here's a reminder of the Azure Application Architecture - let's check our provis
 
 1. **Click `Sign in`** → you will auto-login with the Azure credentials used to sign into the portal.
 
-    - **Check:** You should see a Project and a Hub listed.
+    - **Check:** You should see a Hub resource (with a name like _ai-hub-XXXXXXXX_)
+    - **Check:** You should see a Project resource (with a name like _ai-project-XXXXXXXX_)
 
-        !!! info "The [AI Studio hub](https://learn.microsoft.com/azure/ai-studio/concepts/ai-resources) collects AI resources that can be shared between AI projects. The [AI Studio project](https://learn.microsoft.com/azure/ai-studio/how-to/create-projects?tabs=ai-studio) helps you organize your work when building applications."
+        !!! info "The [Azure AI hub](https://learn.microsoft.com/azure/ai-studio/concepts/ai-resources) collects AI resources that can be shared between AI projects. The [Azure AI project](https://learn.microsoft.com/azure/ai-studio/how-to/create-projects?tabs=ai-studio) helps you organize your work when building applications."
 
-    - Click on the Hub resource name → it may be something like _ai-hub-45556973_
-    - **Check:** There is 1 project listed under `Projects` for this hub.
+    - Click the Project link. You will be taken to a Project details page.
     - Click "Connected Resources" in the left pane,
-    - **Check:** You see Hub connections to OpenAI endpoints, Azure AI Search & Storage.
+    - **Check:** You should see Hub connections to OpenAI endpoints, Azure AI Search & Storage.
+    - Click "Models + endpoints" in the left pane.
+    - **Check:** You should see deployed models for this project.
 
         !!! info "For this application, we will use the chat completion models `gpt-4` and `gpt-35-turbo`, and the embedding model `text-embedding-ada-002`." 
 
@@ -106,7 +108,7 @@ The Azure AI Search resources contains the product index for our retailer's prod
     - you will see: Results dialog filled with index data for the entire product database.
 1. Enter `sleeping bag` in the text box, and click Search
     - Verify that the first result returned relates to a sleeping bag from the catalog       
-    !!! tip "Look under the 'answers' section of the response to see if the results match." 
+    !!! tip "Check the 'value' section of the response for semantically-ranked results." 
 1. Enter `something to make food with` in the text box, and click Search       
     - Verify that the first result returned relates to a camping stove
 
diff --git a/docs/workshop/docs/03-Ideate/index.md b/docs/workshop/docs/03-Ideate/index.md
@@ -9,7 +9,7 @@
     1. Skillable VM tag - showing the countdown timer & launch page
     1. GitHub Codespaces tab - showing the Visual Studio Code IDE.
     1. Azure Portal tab - showing your `rg-AITOUR` resource group.
-    1. Azire AI Studio tab - showing your AI project page.
+    1. Azure AI Studio tab - showing your AI project page.
     1. Azure Container Apps - showing your deployed application.
     
     We completed the setup, validated the infrastructure and verified that the application was deployed correctly. 
diff --git a/docs/workshop/docs/04-Evaluate/02.md b/docs/workshop/docs/04-Evaluate/02.md
@@ -15,6 +15,9 @@ The "scoring" task could be performed by a human, but this does not scale. Inste
     - `groundedness.prompty`
     - `relevance.prompty`
 1. Run each file and observe the output seen from Prompty execution.
+
+    !!! tip "Run a Prompty file by clicking the _play_ icon or pressing `F5` on your keyboard"
+
 1. **Check:** You see prompty for Coherence, Fluency, Relevance and Groundedness.
 1. **Check:** Running the prompty assets gives scores between `1` and `5`
 
diff --git a/docs/workshop/docs/Tear-Down/index.md b/docs/workshop/docs/Tear-Down/index.md
@@ -1,20 +1,54 @@
 # Cleanup Resources
 
-!!! danger "Don't Forget - End the Skillable Session"
+## 1. Give us a ⭐️ on GitHub
 
-    Visit the Skillable Lab page and click `End Session` to end the session and release all resources. This allows the lab to be run again without quota issues for others.
+!!! task "FOUND THIS WORKSHOP AND SAMPLE USEFUL? MAKE SURE YOU GET UPDATES."
 
+The **[Contoso Chat](https://aka.ms/aitour/contoso-chat)** sample is an actively updated project that will reflect the latest features and best practices for code-first development of RAG-based copilots on the Azure AI platform. **[Visit the repo](https://aka.ms/aitour/contoso-chat)** or click the button below, to give us a ⭐️. 
+<!-- Place this tag where you want the button to render. -->
+<a class="github-button" href="https://github.com/Azure-Samples/contoso-chat" data-color-scheme="no-preference: light; light: light; dark: dark;" data-size="large" data-show-count="true" aria-label="Star Azure-Samples/contoso-chat on GitHub"> Give Contoso Chat a Star!</a>
+
+---
+
+## 2. Feedback & Cleanup
+
+Check that the right tab is selected for your session, and complete the steps!
+
+=== "Self-Guided"
+
+    !!! task "Reminder 1: Give us Feedback"
+
+        Have feedback that can help us make this lab better for others? [Open an issue](https://github.com/Azure-Samples/contoso-chat/issues/new) and let us know.
+
+=== "Microsoft AI Tour"
+
+    !!! task "Reminder 1: Give us Feedback"
+
+        Visit [aka.ms/MicrosoftAITour/Survey](https://aka.ms/MicrosoftAITour/Survey) to give us feedback on this session (#WRK550)
+      
+    !!! danger "Reminder 2: End the Skillable Session"
+
+        Visit the Skillable Lab page and click `End Session` to end the session and release all resources. This allows the lab to be run again without quota issues for others.
 
-!!! danger "Don't Forget - Stop Your Codespaces"
     
-    Visit [https://github.com/codespaces](https://github.com/codespaces) - locate the Codespaces instance you are currently running and delete it to prevent continued usage of the storage or processing quotas.
+=== "Microsoft Ignite"
 
-    If you want to save any changes you have made to files to your fork, use the Source Control tool in VS Code Online to commit and push your changes before you delete the Codespace.
+    !!! success "Reminder 1: Please Give us Feedback"
 
-!!! info "Reminder - Give us Feedback"
+        Visit [aka.ms/MicrosoftIgniteEvals](https://aka.ms/MicrosoftIgniteEvals) to give us feedback on this session (LAB401)
+      
+    !!! warning "Reminder 2: End the Skillable Session"
 
-    Visit [aka.ms/MicrosoftAITour/Survey](https://aka.ms/MicrosoftAITour/Survey) to give us feedback on this session (#WRK550)
+        Visit the Skillable Lab page and click `End Session` to end the session and release all resources. This allows the lab to be run again without quota issues for others.
 
-!!! info "Reminder - Star the Repo"
+---
+
+## 3. Stop your Codespaces
+
+!!! warning "Reminder: Delete your Codespaces instance to preserve quota"
+    
+1. Visit [https://github.com/codespaces](https://github.com/codespaces) in your browser
+1. Locate the Codespaces instance you are currently running 
+1. Delete it to prevent continued usage of the storage or processing quotas.
 
-    Visit [Contoso Chat](https://aka.ms/aitour/contoso-chat) and give us a 🌟 to help raise awareness of this workshop!
+If you want to save any changes you have made to files to your fork, use the Source Control tool in VS Code Online to commit and push your changes before you delete the Codespace.
diff --git a/docs/workshop/docs/index.md b/docs/workshop/docs/index.md
@@ -4,6 +4,8 @@ The workshop teaches you to **build, evaluate, and deploy a retail copilot** cod
 
 You can complete it as a **self-guided** workshop at home. Or you can register for an **instructor-led** workshop at specific events like the [Microsoft AI Tour (2024-2025)](https://aka.ms/aitour) and [Microsoft Ignite 2024](https://ignite.microsoft.com/en-US/sessions?search=LAB401). The primary difference will be in the initial setup steps and the Azure subscription used.
 
+<a class="github-button" href="https://github.com/Azure-Samples/contoso-chat" data-color-scheme="no-preference: light; light: light; dark: dark;" data-size="large" data-show-count="true" aria-label="Star Azure-Samples/contoso-chat on GitHub"> Give Contoso Chat a Star!</a>
+
 <br/>
 
 !!! task "CHOOSE THE TAB FOR YOUR SESSION - This becomes the default context site-wide."
diff --git a/docs/workshop/in-person-starts/MSIgnite-2024-Skillable.md b/docs/workshop/in-person-starts/MSIgnite-2024-Skillable.md
@@ -5,46 +5,50 @@ This file is dynamically retrieved and used by the Skillable VM as the Instructi
 
 # LAB 401: Build a Retail Copilot Code-First on Azure AI Studio
 
-This is a 75-minute instructor-led workshop session at Microsoft Ignite 2024. You must [register](https://ignite.microsoft.com/sessions/LAB401?source=sessions) for an available session, to attend in person.
+This is a 75-minute instructor-led workshop at Microsoft Ignite 2024 where you learn to build, evaluate, and deploy, a RAG-based retail copilot on Azure AI.
 
-_You will learn to build, evaluate, and deploy, a custom retail copilot code-first on Azure AI - using the Retrieval Augmented Generation (RAG) design pattern to ground copilot responses in retailer data_.
-
-
-**‼️ -- DO NOT CLOSE THIS WINDOW -- ‼️** <br/> Closing this window will end your lab prematurely. It is ok to minimize this window so you can return to it later when required.
+**‼️ -- DO NOT CLOSE THIS WINDOW -- ‼️** <br/> Closing this window will end your lab prematurely. Instead, minimize this window so you can return to it later when required.
 
 ---
 
 ## 1. Lab Instructions
 
 **Instructions Link:** ++https://aka.ms/aitour/contoso-chat/workshop++
 
-The lab instructions are available at the link above. To get started:
-1. Open a new incognito (private) browser window on your workstation
-1. Copy the link above into the browser address bar and navigate to it.
-1. Start from the **Setup** section to make best use of your time.
+Open a new private browser in your workstation. 
+
+1. Copy the instructions link to the browser and navigate to it.
+1. In the "Before You Begin" section, **Select the Microsoft Ignite tab**
+1. Leave this browser open and follow the instructions for the lab.
 
 ## 2. Azure Credentials
 
-You will make use of a temporary Azure subscription assigned to this lab instance, with the credentials below. You will need these for the setup stage of the workshop. Verify that you see both _Username_ and _Password_ values below.
+You will be assigned a temporary Azure subscription for this lab. Verify that the _Username_ and _Password_ credentials are not empty below. We will use them during setup.
 
 - **Username:** ++@lab.CloudPortalCredential(User1).Username++
 - **Password:** ++@lab.CloudPortalCredential(User1).Password++
 
-## 3. Skillable VM
+## 3. Skillable VM Credentials
 
-The login screen to the left corresponds to the Skillable Windows VM for your lab instance. You should **NOT** need to use it for this lab - but it may prove helpful for troubleshooting issues with proctor help.
-
-Use these credentials to login (username may be preset):
+The Skillable VM has a login screen (left) that we do **NOT** need to use today. However, we may need it for troubleshooting (with proctor help). The credentials below will be useful for logging in then.
 
 - +++@lab.VirtualMachine(WRK550-Win11(NEW)).Username+++
 - +++@lab.VirtualMachine(WRK550-Win11(NEW)).Password+++
 
 ## 4. Time Tracking
 
-This instruction panel has a _Countdown Timer_ (at the top) showing _"Hours Remaining"_ for lab completion  (with _1h 15 min_ to start).
- - When the timer expires, the VM will terminate automatically
- - When it nears expiry, you will be notified so you can cleanup
+This Skillable page has a countdown timer (top right) that will show **Hours Remaining** for lab completion. Use this to track time left and decide if you want to do optional steps accordingly. 
+
+- You should start with at least 1h 15min on the clock.
+- You will be notified when there are 10 mins left
+- When timer expires, the VM will terminate automatically!
+ 
+## 5. Revisiting Lab at Home
+
+By the end of this workshop, you will have a copy of the sample app in your personal GitHub profile. Revisit it at home to explore and complete sections at your own pace. 
 
-You will walk away with a copy of the application in your GitHub profile. You can revisit that at home, with the _Self-Guided_ workshop option, to complete the workshop at your own pace, with your Azure subscription.
+1. You will need your own Azure subscription for this.
+1. You will need to set the "Before You Begin" tab to **Self-Guided** 
+1. Then continue working through the lab steps there.
 
 ---
diff --git a/docs/workshop/mkdocs.yml b/docs/workshop/mkdocs.yml
@@ -41,6 +41,7 @@ theme:
     text: Roboto       #Regular
   logo: img/logo.svg
   language: en
+  custom_dir: overrides #Add custom header scripts
 
   # Theme Modes ...............................................
   palette:
diff --git a/docs/workshop/overrides/main.html b/docs/workshop/overrides/main.html
@@ -0,0 +1,11 @@
+{% extends "base.html" %}
+
+{% block scripts %}
+  <!-- Add scripts that need to run before here -->
+  {{ super() }}
+  <!-- Add scripts that need to run afterwards here -->
+
+    <!-- Place this tag in your head or just before your close body tag. -->
+    <script async defer src="https://buttons.github.io/buttons.js"></script>
+    
+{% endblock %}
diff --git a/src/api/evaluate-chat-flow.ipynb b/src/api/evaluate-chat-flow.ipynb
