Predictive maintenance updates

03-Azure/01-04-AI/08_Predictive_Maintenance/challenges/challenge-01.md

@@ -53,25 +53,78 @@ The remaining challenges use this pre-provisioned environment and a repository h
 
 Complete this setup with the credentials provided in your Hackbox. Use the assigned lab account rather than a personal or work account so that you have access to the correct Azure subscription, resource group, GitHub organization, and repository.
 
+> [!TIP]
+> Use an InPrivate or Incognito browser session for this lab to avoid mixing your personal or other work accounts when signing in to Azure and GitHub.
+
 ## ✅ Tasks
 
 ### 1. Sign in to Azure
 
-Open the [Azure portal](https://portal.azure.com) and sign in with the credentials provided in your Hackbox, choosing **Use another account** when prompted.
+Open the [Azure portal](https://portal.azure.com) and sign in with the credentials provided in your Hackbox (see the **Credentials** section at the top of this web page). If you are prompted to pick an account, choose **Use another account**.
+
+<img src="./images/challenge-01-pick-account.png" alt="Pick account for login" width="60%">
+
+Enter the provided **Entra ID Username** and **Entra ID TAP** from the **Credentials** section at the top of this page.
+
+<img src="./images/challenge-01-sign-in.png" alt="Sign in" width="60%">
+
+In the Azure portal, select **Resource groups** from the start page.
+
+<img src="./images/challenge-01-resource-groups-portal.png" alt="Sign in" width="60%">
 
-In the Azure portal, select **Resource groups**, open the resource group assigned to you, and confirm that its resources have been deployed successfully. Verify that you can see the Foundry project, the Cosmos DB account, the Storage account, and the API Management instance described in [Context and Background](#-context-and-background).
+
+Open the resource group assigned to you and confirm that its resources have been deployed successfully.
+
+<img src="./images/challenge-01-azure-portal-resources.png" alt="Azure resources" width="60%">
+
+Verify that you can see the Foundry project, the Cosmos DB account, the Storage account, and the API Management instance described in [Context and Background](#-context-and-background).
+
+> [!NOTE]
+> The Location column values might differ from the screenshot since the resources are provisioned across multiple regions. 
 
 ### 2. Sign in to GitHub
 
-Open [GitHub](https://github.com) and sign in with the credentials provided in your Hackbox, choosing **Use another account** and then **Sign in with your identity provider**.
+Open [GitHub login page](https://github.com/login) and sign in with the **Github SSO Login User** username provided in your Hackbox and select **Sign in with your identity provider**.
+
+<img src="./images/challenge-01-github-login.png" alt="GitHub login" width="60%">
+
+Select **Continue** and accept the consent prompt.
+
+Open the GitHub organization assigned to your lab account by first selecting the avatar in the top right corner and then **Organizations**
 
-Open the organization associated with your lab account and select the `MicroHack` repository. Confirm that you can see the repository files and folders, including `03-Azure/01-04-AI/08_Predictive_Maintenance`.
+<img src="./images/challenge-01-github-organization.png" alt="GitHub organization" width="60%">
+
+Select the assigned organization, then open the pinned microhack repository. 
+
+<img src="./images/challenge-01-select-github-organization.png" alt="GitHub organization" width="60%">
+
+<img src="./images/challenge-01-pinned-github-repository.png" alt="Microhack repository" width="60%">
+
+You then need to fork the repository before you can create a Codespace. To fork the repository, click the Fork button in the top-right corner of the repository page and follow the prompts:
+
+<img src="./images/challenge-01-github-fork-repository.png" alt="Create fork" width="60%">
+
+Select the organization as owner and use a unique name for the repository name to avoid conflicts with other forks. For example, you can append your lab username to the repository name (e.g., `microhack-labuser-0001`):
+
+<img src="./images/challenge-01-github-fork-name.png" alt="Fork name" width="60%">
+
+Finally, you should see your forked repository with the unique name you provided and all files and folders from the original repository:
+
+<img src="./images/challenge-01-github-forked-repository.png" alt="Forked repository" width="60%">
 
 ### 3. Create the development environment
 
-From the repository page, select **Code**, open the **Codespaces** tab, then use the `...` menu to choose **New with options**. For **Dev container configuration**, select **Azure / AI / Predictive Maintenance**, then select **Create codespace**.
+From the repository page, select **Code**, then open the **Codespaces** tab. Select the ... menu and choose **New with options**.
+
+<img src="./images/challenge-01-new-codespace-with-options.png" alt="New Codespace" width="60%">
+
+For Dev container configuration, select **Azure / AI / Predictive Maintenance**, then select **Create codespace**:
 
-GitHub opens the Codespace in a new browser tab. Wait for the container setup to finish, then confirm that the repository files are visible in the Explorer and that the integrated terminal opens without errors.
+<img src="./images/challenge-01-select-devcontainer.png" alt="Select Dev Container" width="60%">
+
+Wait for the container setup to finish, then select the **Trust folders & Continue** button and confirm that the repository files are visible in the Explorer and that the integrated terminal opens without errors.
+
+<img src="./images/challenge-01-codespace-welccome.png" alt="Codespace welcome" width="60%">
 
 Open a terminal in the Codespace and verify that the required tools are installed:
 
@@ -80,25 +133,23 @@ az --version
 dotnet --version
 ```
 
-Install the pinned Python dependencies and activate the environment:
+The pinned Python dependencies were installed automatically when the Codespace was created. Verify that the virtual environment is active:
 
 ```bash
-uv sync --frozen
-source .venv/bin/activate
+which python   # should point to .../.venv/bin/python
 ```
-
-Sign in to Azure from the Codespace terminal with the assigned lab account:
+Sign in to Azure from the Codespace terminal follow the link shown to authenticate with a web browser and the device code using the assigned lab account:
 
 ```bash
 az login --use-device-code
 ```
 
 ### 4. Retrieve environment configuration
 
-From the repository root, run the setup script with the resource group name provided in your Hackbox:
+From the repository root, run the setup script with the resource group name provided in your Hackbox under **Resource Group Name**:
 
 ```bash
-bash labautomation/get-keys.sh --resource-group "<your-resource-group-name>"
+labautomation/get-keys.sh --resource-group "<your-resource-group-name>"
 ```
 
 The script locates your deployed lab resources and creates a local `.env` file. It retrieves the Foundry project endpoint, Cosmos DB connection details, Storage account connection string, and Azure AI Search key and endpoint required by the remaining challenges. The file is excluded from Git and its secret values are not displayed.

03-Azure/01-04-AI/08_Predictive_Maintenance/labautomation/get-keys.sh

@@ -181,6 +181,8 @@ EMBEDDING_MODEL_DEPLOYMENT_NAME="text-embedding-3-large"
 AZURE_OPENAI_ENDPOINT="$azureOpenAIEndpoint"
 AZURE_OPENAI_KEY="$foundryKey"
 AZURE_OPENAI_DEPLOYMENT_NAME="gpt-5.4"
+# Read by agent_framework's OpenAIChatClient (Challenge 2 Python agents)
+AZURE_OPENAI_CHAT_MODEL="gpt-5.4-mini"
 
 # Azure Cosmos DB (SQL API)
 COSMOS_ACCOUNT_NAME="$cosmosAccountName"

03-Azure/01-04-AI/08_Predictive_Maintenance/labautomation/main.bicep

@@ -34,6 +34,7 @@ var searchServiceContributorRoleId = subscriptionResourceId('Microsoft.Authoriza
 var searchIndexDataReaderRoleId = subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '1407120a-92aa-4202-b7e9-c0e197c71c8f')
 var monitoringReaderRoleId = subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '43d0d8ad-25c7-4714-9337-8ba259a9fe05')
 var foundryUserRoleId = subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '53ca6127-db72-4b80-b1b0-d745d6d5456d')
+var openAiContributorRoleId = subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'a001fd3d-188f-4b5d-821b-7da978bf7442')
 var storageBlobDataContributorRoleId = subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'ba92f5b4-2d11-453d-a403-e96b0029c9fe')
 var cosmosDbDataContributorRoleId = '00000000-0000-0000-0000-000000000002'
 
@@ -440,6 +441,28 @@ resource participantFoundryUser 'Microsoft.Authorization/roleAssignments@2022-04
   }
 }
 
+// Account-scope access: the Responses API (/openai/v1/responses) is a data action
+// on the Foundry/AI Services account, not on the project.
+resource participantFoundryUserOnAccount 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
+  scope: aiFoundry
+  name: guid(aiFoundry.id, userObjectId, foundryUserRoleId)
+  properties: {
+    roleDefinitionId: foundryUserRoleId
+    principalId: userObjectId
+    principalType: 'User'
+  }
+}
+
+resource participantOpenAiContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
+  scope: aiFoundry
+  name: guid(aiFoundry.id, userObjectId, openAiContributorRoleId)
+  properties: {
+    roleDefinitionId: openAiContributorRoleId
+    principalId: userObjectId
+    principalType: 'User'
+  }
+}
+
 resource participantCosmosDataContributor 'Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments@2025-05-01-preview' = {
   parent: cosmosDbAccount
   name: guid(cosmosDbAccount.id, userObjectId, cosmosDbDataContributorRoleId)