refactor / nav sections

docs/workshop/docs/02-Setup/0-PreRequisites/index.md

@@ -1,4 +1,4 @@
-# 0. Pre-Requisites
+# Pre-Requisites
 
 You **must** have a GitHub account to get started. Take a minute to [sign up for a free account](https://github.com/signup) if you don't currently have one. Then check your workshop tab below for additional details.
 

docs/workshop/docs/02-Setup/1-Provision-And-Setup/01-Self-Guided.md

@@ -3,3 +3,87 @@
 !!! warning "If you are are currently in an in-venue instructor-led session, use the [Skillable Setup](./02-Skillable.md) instead!"
 
 ---
+
+## 1. Pre-Requisites
+
+If you have not already done so, review the [Pre-Requisites](./../0-PreRequisites/index.md) for Self-Guided workshops and make sure you have a valid Azure subscription, GitHub account, and access to relevant Azure OpenAI models before you begin. Note that the main difference with this flow is that you will need to _provision your own infrastructure_ for the project.
+
+## 2. Launch GitHub Codespaces
+
+Our development environment uses a Visual Studio Code editor with a Python runtime. The Contoso Chat sample repository is instrumented with a [dev container](https://containers.dev) which specifies all required tools and dependencies. At the end of this step you should have:
+
+- [X] Launched GitHub Codespaces to get the pre-built dev environment.
+- [X] Fork the sample repo to your personal GitHub profile.
+
+### 2.1 Navigate to GitHub & Login
+
+1. Open a browser tab (T1) and navigate to the link below.
+        ``` 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**
+
+### 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`
+    - Click dropdown for **2-core** and verify it is `Prebuild ready`
+
+    !!! tip "Using the pre-build makes the GitHub Codespaces load up faster."
+
+1. Click the green "Create codespace" button
+    - You should see a new browser tab open to a link ending in `*.github.dev`
+    - You should see a Visual Studio Code editor view loading (takes a few mins)
+    - When ready, you should see the README for the "Contoso Chat" repository
+
+    !!! warning "Do NOT Follow those README instructions. Continue with this workshop guide!"
+
+### 2.3 Fork Repo To Your Profile
+
+The Codespaces is running on the original Azure Samples repo. Let's create a fork from Codespaces, so we have a personal copy to modify. For convenience, we'll follow [this process](https://docs.github.com/codespaces/developing-in-a-codespace/creating-a-codespace-from-a-template#publishing-to-a-repository-on-github) which streamlines the process once you make any edit.
+
+1. Lets create an empty file from the VS Code Terminal.
+
+    ``` title="Tip: Click the icon at far right to copy command"
+    touch .workshop-notes.md
+    ```
+
+1. This triggers a notification (blue "1") in Source Control icon on sidebar
+1. Click the notification to start the Commit workflow 
+1. Enter a commit message ("Forking Contoso Chat") and click "Commit"
+1. You will now be prompted to "Publish Branch" 
+    - You should see 2 options (remote = original repo, origin = your fork)
+    - Select the `origin` option (verify that the URL is to your profile)
+1. This will create a fork of the repository in your profile
+    - It also updates the GitHub Codespaces to use your fork for commits
+    - You are now ready to move to the next step!
+
+### 2.4 Verify Dependencies
+
+Use the following commands in the VS Code terminal to verify these tools are installed.
+
+```bash
+python --version
+```
+```bash
+fastapi --version
+```
+```bash
+prompty --version
+```
+```bash
+az version
+```
+```bash
+azd version
+```
+
+You are now ready to connect your VS Code environment to Azure.
+
+### 2.5 Authenticate With Azure 🚨
+
+### 2.6 Provision & Deploy App 🚨
+
+---
+
+## Next: Go To [Validate Setup](./03-Validation.md)

docs/workshop/docs/02-Setup/1-Provision-And-Setup/02-Skillable.md

@@ -34,6 +34,7 @@ You may have completed this step in-venue, with instructor guidance. If not, ple
 
     ✅ **CONGRATULATIONS!** | You setup the Skillable VM tab!
 
+---
 
 ## 2. Launch GitHub Codespaces
 
@@ -50,7 +51,7 @@ Our development environment uses a Visual Studio Code editor with a Python runti
         ```
 1. You will be prompted to log into GitHub. **Login now**
 
-### 2.2 Launch GitHub Codespaces
+### 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`
@@ -74,180 +75,46 @@ The Codespaces is running on the original Azure Samples repo. Let's create a for
     ``` title="Tip: Click the icon at far right to copy command"
     touch .workshop-notes.md
     ```
-1. This triggers a notification (blue "1") in Source Control icon on sidebar
-1. Click the notification to start the Commit flow 
-1. Enter a commit message like this, then click the green "Commit" button
-    ``` title="Tip: Click the icon at far right to copy text"
-    forking sample to my profile
-    ```
-1. Accept the default ("Yes") in the "There are no staged .." pop-up dialog 
-1. 
-
-
-1.  ✅ **Congratulations!** - You launched the GitHub Codespaces prebuild!
-
-
-
-!!! info "Step 1.2 Launch GitHub Codespaces"
-
-    ### 2.1 Log into GitHub
-
-    1. Open a new browser tab (T1)
-    1. Navigate to the link below to create a Codespace
-        ``` title="Tip: Click the files icon at right to copy the link"
-        https://aka.ms/aitour/contoso-chat
-        ```
-    1. Sign into GitHub (if you are not already logged in)
-    1. 
-
-    The source code for the application used in this workshop is available on GitHub. Let's log into GitHub and copy a fork of the source code to your GitHub account.
-
-    1. Open a new browser tab (Tab 1️⃣)
-    1. **Navigate to** the [contoso-chat workshop sample](https://aka.ms/aitour/contoso-chat) with this link:
-
-        ```
-        https://aka.ms/aitour/contoso-chat
-        ```
-
-    1. **Sign into** GitHub - use your own GitHub account to log in
-    1. Click **Fork** in the top-right corner of the page
-
-    1. In the "Create a new fork" page, scroll down and **uncheck** the option "Copy the main branch only".
-
-        !!! warning "If you forget to uncheck that option, you will need to delete your fork and try again."
-
-    1. Click the **Create Fork** button.
-
-        * You should now be at the page `https://github.com/YOURUSERNAME/contoso-chat` within your own GitHub account.
-    
-        * You now have a copy (known as a fork) of this workshop repository in your own GitHub account! Feel free to play with it, you won't break anything.
-
-    **✅ | CONGRATULATIONS!** - Your have a personal copy of the sample to explore!
-
-??? info "Browser Tab 3 - GitHub Codespaces"
-
-    ### 2.2: Launch Codespaces in Tab 2️⃣
-
-    GitHub Codespaces will be our development environment for this workshop. Let's launch CodeSpaces now, starting from the fork of the `contoso-chat` repository you just created.
-
-    !!! tip "Even a free GitHub account will have sufficient GitHub CodeSpaces credits to run this workshop. Be sure to delete the CodeSpace after the workshop to minimize use of your credits."
-
-    1. Use the branch selection drop-down on the left side that now reads **main** and select the branch **aitour-WRK550**.
-
-        ![alt text](../img/branch.png)
-
-    1. Click the green **<> Code** button in the top-right part of the page, click the **Codespaces** tab, and then click **Create codespace on aitour-WRK550**.
-
-    1. This will launch a new browser tab (Tab 2️⃣). It will take a few minutes for the CodeSpace to be ready for use. In the meantime, continue with the next steps. 
-
-
-    ---
-
-    ✅ **Your GitHub Codespaces tab is active!**
-
-
-
-??? info "STEP 3: Open Azure Portal Tab"
-
-    1. Open a new browser tab (Tab 3️⃣)
-    1. Navigate to the [Azure Portal](https://portal.azure.com):
-        ```
-        https://portal.azure.com
-        ```
-    1. **Sign in** using the `Username` and `Password` displayed under "Azure Credentials" in the Skillable Lab window you launched in **Step 1** (above).
-    1. You will be presented with a "Welcome to Microsoft Azure" screen. Click **Cancel** to dismiss, or click **Get Started** if you'd like to take an introductory tour of the Azure Portal.
-    1. In the Navigate section, **Click** `Resource Groups`.
-    1. A resource group has been created for you, containing the resources needed for the RAG application. **Click** `rg-AITOUR`.
-    1. **Check:** Deployments (under "Essentials") - There are **35 succeeded** Deployments. 
-    1. **Check:** Resources (in Overview) - There are **15 resources** in the resource group.
-
-    **✅ | CONGRATULATIONS!** - Your Azure Infra is Provisioned!
-
-    ---
-
-    ✅ **Your Azure Portal tab is active!**
-
-
-??? info "STEP 4: Open Azure AI Studio Tab"
-
-    1. Open a new browser tab = Tab 4️⃣
-    1. Navigate to the [Azure AI Studio](https://ai.azure.com?feature.customportal=false#home):
-        ```
-        https://ai.azure.com
-        ```
-
-    1. **Click** `Sign in` -- you will auto-login with the Azure credentials used to sign into the portal.
-    1. Under Management in the left pane, **click** `All hubs`. One hub resource will be listed.
-
-        !!! warning "The AI Studio UI is evolving. Instead of `All hubs` you may see an `All resources` item in the left pane instead, with 2 resources listed in the right - one of which should be a _hub_ resource."
-
-        !!! info "An [AI Studio hub](https://learn.microsoft.com/azure/ai-studio/concepts/ai-resources) collects resources like generative AI endpoints that can be shared between projects."
-
-    1. **Click** the listed hub resource name to display it. **Check:** 1 project is listed under `Projects`.
-
-        !!! info "An [AI Studio project](https://learn.microsoft.com/azure/ai-studio/how-to/create-projects?tabs=ai-studio) is used to organize your work when building applications."
-
-    1. Under "Shared Resources" in the left pane, **click** `Deployments`. The right pane should show two `*-connection` groups. **Check:** 4 models are listed under each connection. 
-
-        !!! info "The Model Deployments section lists Generative AI models deployed to this Hub. For this application, we will use the chat completion models `gpt-4` and `gpt-35-turbo`, and the embedding model `text-embedding-ada-002`." 
-
-    **✅ | CONGRATULATIONS!** - Your Azure AI Project is ready!
-
 
-    ---
-
-    ✅ **Your Azure AI Studio tab is active!**
-
-
-??? info "STEP 5: Open Azure Container Apps Tab"
-
-    [Azure Container Apps](https://learn.microsoft.com/azure/container-apps/overview) will host the endpoint used to serve the Contoso Chat application on the Contoso Outdoors website. We have deployed a container app, but have not yet pushed code to it. 
-
-    1. Return to the Azure Portal, Tab 3️⃣
-    1. Visit the `rg-AITOUR` Resource group page
-    1. Click the `Container App` resource to display the Overview page
-    1. Look for `Application Url` (at top right), and click it to launch in new tab (Tab 5️⃣)
-        * This creates a new tab `"Welcome to Azure Container Apps!"` displaying the logo
-
-    !!! info "Azure Container Apps (ACA) is an easy-to-use compute solution for hosting our chat AI application. The application is implemented as a FastAPI server that exposes a simple `/create_request` API endpoint to clients for direct use or integration with third-party clients."
-
-    **✅ | CONGRATULATIONS!** - Your ACA Endpoint is ready!
-
-    ---
-
-    ✅ **Your Azure Container Apps tab is active!**
-
-
-??? info "STEP 6: Review Current Status"
-
-    !!! success "Let's Review where we are right now"
-
-        1. Tab 1️⃣ = GitHub Repo (starting point)
-        1. Tab 2️⃣ = GitHub Codespaces (development environment)
-        1. Tab 3️⃣ = Azure Portal (provisioned resources)
-        1. Tab 4️⃣ = Azure AI Studio (AI project & models)
-        1. Tab 5️⃣ = Azure Container Apps (Deployment target)
-
-    
-    1. Return to your GitHub Codespaces tab, Tab 2️⃣.
+1. This triggers a notification (blue "1") in Source Control icon on sidebar
+1. Click the notification to start the Commit workflow 
+1. Enter a commit message ("Forking Contoso Chat") and click "Commit"
+1. You will now be prompted to "Publish Branch" 
+    - You should see 2 options (remote = original repo, origin = your fork)
+    - Select the `origin` option (verify that the URL is to your profile)
+1. This will create a fork of the repository in your profile
+    - It also updates the GitHub Codespaces to use your fork for commits
+    - You are now ready to move to the next step!
 
-    You should see the Visual Studio Online development environment. If you have used Visual Studio Code on the desktop, it will look very familiar. You will see these components:
+### 2.4 Verify Dependencies
 
-    * Left sidebar: The Activity Bar, including the "Prompty" extension logo at the end
-        ![Prompty logo](../img/prompty-logo.png)
-    * Left pane: The Explorer pane, showing the files in the `contoso-chat` repository
-    * Right pane: A preview of the main README.md file from the repository
-    * Lower pane: A terminal pane, with a `bash` prompt ready to receive input
+Use the following commands in the VS Code terminal to verify these tools are installed.
 
-    If you don't see those yet, wait until they appear in your browser.
+```bash
+python --version
+```
+```bash
+fastapi --version
+```
+```bash
+prompty --version
+```
+```bash
+az version
+```
+```bash
+azd version
+```
 
-    **✅ | CONGRATULATIONS!** - Your CodeSpace is running!
 
+### 2.5 Authenticate With Azure 🚨
 
-??? info "STEP 7: Authenticate With Azure"
+You are now ready to connect your VS Code environment to Azure.
 
+### 2.6 Do Post-Provisioning 🚨
 
-??? info "STEP 8: Complete Post-Provisioning"
+You are now ready to connect your VS Code environment to Azure.
 
+---
 
-??? info "STEP 9: Verify Setup Complete!"
+## Next: Go To [Validate Setup](./03-Validation.md)

docs/workshop/docs/02-Setup/1-Provision-And-Setup/03-Validation.md

@@ -13,11 +13,73 @@
 
 ---
 
+
+
+## 3. Validate Provisioning
+
+### 3.1 Azure Portal Tab
+
+1. Open a new browser tab and navigate to the link below:
+    ``` title="Tip: Click the icon at far right to copy text"
+    https://portal.azure.com
+    ```
+
+1. **Sign in** using the `Username` and `Password` displayed under "Azure Credentials" in the Skillable Lab window you launched in **Step 1** (above).
+1. You will be presented with a "Welcome to Microsoft Azure" screen. Click **Cancel** to dismiss, or click **Get Started** if you'd like to take an introductory tour of the Azure Portal.
+1. In the Navigate section, **Click** `Resource Groups`.
+1. A resource group has been created for you, containing the resources needed for the RAG application. **Click** `rg-AITOUR`.
+1. **Check:** Deployments (under "Essentials") - There are **35 succeeded** Deployments. 
+1. **Check:** Resources (in Overview) - There are **15 resources** in the resource group.
+
+---
+
+### 3.2 Azure AI Studio Tab
+
+1. Open a new browser tab = Tab 4️⃣
+1. Navigate to the [Azure AI Studio](https://ai.azure.com?feature.customportal=false#home):
+    ``` title="Tip: Click the icon at far right to copy text"
+    https://ai.azure.com
+    ```
+
+1. **Click** `Sign in` -- you will auto-login with the Azure credentials used to sign into the portal.
+1. Under Management in the left pane, **click** `All hubs`. One hub resource will be listed.
+
+    !!! warning "The AI Studio UI is evolving. Instead of `All hubs` you may see an `All resources` item in the left pane instead, with 2 resources listed in the right - one of which should be a _hub_ resource."
+
+    !!! info "An [AI Studio hub](https://learn.microsoft.com/azure/ai-studio/concepts/ai-resources) collects resources like generative AI endpoints that can be shared between projects."
+
+1. **Click** the listed hub resource name to display it. **Check:** 1 project is listed under `Projects`.
+
+    !!! info "An [AI Studio project](https://learn.microsoft.com/azure/ai-studio/how-to/create-projects?tabs=ai-studio) is used to organize your work when building applications."
+
+1. Under "Shared Resources" in the left pane, **click** `Deployments`. The right pane should show two `*-connection` groups. **Check:** 4 models are listed under each connection. 
+
+    !!! info "The Model Deployments section lists Generative AI models deployed to this Hub. For this application, we will use the chat completion models `gpt-4` and `gpt-35-turbo`, and the embedding model `text-embedding-ada-002`." 
+
+
+---
+
+### 3.3 Azure Container App Tab
+
+[Azure Container Apps](https://learn.microsoft.com/azure/container-apps/overview) will host the endpoint used to serve the Contoso Chat application on the Contoso Outdoors website. The Azure provisioning should have deployed a default Azure Container App to this endpoint.
+
+1. Return to the Azure Portal, Tab 3️⃣
+1. Visit the `rg-AITOUR` Resource group page
+1. Click the `Container App` resource to display the Overview page
+1. Look for `Application Url` (at top right), and click it to launch in new tab (Tab 5️⃣)
+    * This creates a new tab `"Welcome to Azure Container Apps!"` displaying the logo
+
+!!! info "Azure Container Apps (ACA) is an easy-to-use compute solution for hosting our chat AI application. The application is implemented as a FastAPI server that exposes a simple `/create_request` API endpoint to clients for direct use or integration with third-party clients."
+
+
+
+---
+
 _In this section, we'll take a minute to understand what our Azure infrastructure looks like, and validate that the resources are deployed and initialized correctly. Here's a reminder of the Azure Application Architecure showing the key resources used. Let's dive in._
 
 ![ACA Architecture](./../../img/aca-architecture.png)
 
-## Step 1: Validate Azure Cosmos DB is populated
+## 1.1. Check Azure Cosmos DB
 
 The Azure CosmosDB resource holds the customer data for our application. It is a noSQL database that contains JSON data for each customer, and the prior purchases they made.
 
@@ -31,7 +93,7 @@ The Azure CosmosDB resource holds the customer data for our application. It is a
 
 ✅ | Your Azure Cosmos DB resource is ready!
 
-## Step 2: Validate Azure AI Search is populated
+## 1.2. Check Azure AI Search 
 
 The Azure AI Search resources contains the product index for our retailer's product catalog. It is the information **retrieval** service for **R**AG solutions, using sentence similarity and semantic ranking to return the most relevant results for a given customer query.
 
@@ -48,7 +110,7 @@ The Azure AI Search resources contains the product index for our retailer's prod
 
 ✅ | Your Azure AI Search resource is ready!
 
-## Step 3: Test the Deployed Container App
+## 1.3. Check Azure Container App
 
 When iterating on a prototype application, we start with manual testing - using a single "test prompt" to validate our prioritzed scenario interactively, before moving to automated evaluations with larger test datasets. The FastAPI server exposes a `Swagger API` endpoint that can be used to conduct such testing in both local (Codespaces) and cloud (Container Apps). Let's try it on a fully functional version of the endpoint!
 
@@ -73,9 +135,10 @@ You will get a response body with `question`, `answer` and `context` components.
 !!! note "Exercise → Repeat exercise with a different customer ID (between 1 and 12). How did the response change?"
 
 
-✅ | Your Contoso Chat AI is deployed - and works with valid inputs!
+---
+
 
-## Let's Connect The Dots
+## 1.4. Let's Connect The Dots ..
 
 !!! info "Recall that the [Retrieval Augmented Generation](https://learn.microsoft.com/en-us/azure/ai-studio/concepts/retrieval-augmented-generation#how-does-rag-work) works by *retrieving* relevant knowledge from your data stores, and _augmenting_ the user query with it to create an enhanced prompt - which _generates_ the final response."