Merge pull request #6 from microsoft/pewill/polishing

Refactor code structure for improved readability and maintainability

Author: pewill-msft

README.md

@@ -30,9 +30,9 @@ All paths teach the same Foundry concepts — pick the one that resonates with y
 
 | Scenario | Description | Start Here |
 |----------|-------------|------------|
-| 🏭 **Factory** | Detect machine anomalies and diagnose faults at TireForge Industries | [Factory Lab](./factory/) |
-| 📋 **Claims** | Triage incoming claims and recommend actions at ClaimSight Insurance | [Claims Lab](./claims/) |
-| 📞 **Call Center** | Classify call intents and advise resolutions at NovaTel Communications | [Call Center Lab](./callcenter/) |
+| 🏭 **Factory** | Detect machine anomalies and diagnose faults at TireForge Industries | [Factory Lab](./factory/README.md) |
+| 📋 **Claims** | Triage incoming claims and recommend actions at ClaimSight Insurance | [Claims Lab](./claims/README.md) |
+| 📞 **Call Center** | Classify call intents and advise resolutions at NovaTel Communications | [Call Center Lab](./callcenter/README.md) |
 
 All scenarios follow the same 5-challenge structure:
 
@@ -46,10 +46,10 @@ All scenarios follow the same 5-challenge structure:
 
 ## Prerequisites
 
-- **Azure subscription** with Contributor access
-- **Python 3.10+** installed locally (not needed for Codespaces)
-- **Azure CLI** (`az`) installed and logged in
-- ~20 minutes for infrastructure provisioning
+- **Azure subscription** with **Contributor** and **Foundry User** access
+- A **GitHub account**
+- **Python 3.10+** installed locally (pre-installed when using Codespaces)
+- **Azure CLI** (`az`) installed (pre-installed when using Codespaces)
 
 ## Ready to Expand Your Knowledge?
 

callcenter/challenge-0-setup/README.md

@@ -15,6 +15,13 @@ By the end of this challenge, you will have:
 
 ## Get Started
 
+> [!NOTE]
+> Before you begin, make sure you have:
+> - An **Azure subscription** where you hold both the **Contributor** role (to deploy the infrastructure) and the **Foundry User** role on the Foundry account (to build, evaluate, and run agents in Challenges 1–4).
+> - A **GitHub handle** (account) to fork this repository and run it in GitHub Codespaces.
+>
+> Subscription **Owner** (or Contributor) rights alone are **not** sufficient. Those grant control-plane access to create and manage resources, but building and running agents are data-plane operations that require the separate **Foundry User** role assigned on the Foundry account. An Owner can self-assign it; a Contributor must ask an admin to assign it after deployment.
+
 There are two ways to get started — pick one:
 
 > **First step for both options:** [Fork this repository](https://github.com/microsoft/FrontierWeekHack/fork) to your own GitHub account.
@@ -27,7 +34,7 @@ No local installs needed. Everything runs in a cloud dev environment.
 
 1. Click the badge above (select your fork if applicable)
 2. Wait for the Codespace to build (~2 min)
-3. In the terminal, login to Azure and deploy your scenario:
+3. In the terminal, log in to Azure:
 
 ```bash
 az login
@@ -53,7 +60,7 @@ source .venv/bin/activate  # On Windows: .venv\Scripts\activate
 # 3. Install Python dependencies
 pip install -r requirements.txt
 
-# 4. Login to Azure
+# 4. Log in to Azure
 az login
 ```
 
@@ -74,8 +81,27 @@ From the **callcenter** folder, run one of the following depending on your termi
 
 This will provision all resources **and** automatically write your `.env` file to the repository root as `.env`.
 
+## Verify the creation of your resources
+
+Go to the [Azure Portal](https://portal.azure.com/) and find your resource group, which should now contain resources like this (exact names will differ depending on scenario):
+
+![Azure Portal Resources](./images/azure-portal-resources.png)
+
+Go to the [Microsoft Foundry Portal](https://ai.azure.com) and verify that you can access the Foundry project.
+
+![Foundry Project](./images/foundry-project.png)
+
+Select **Build** in the top navigation, then **Models**, and verify that the **gpt-5.4** model is deployed.
+
+![Foundry Model](./images/foundry-model.png)
+
+Select **gpt-5.4**, enter a test message in the model playground, and verify that you get a response.
+
+![Foundry Model Playground](./images/foundry-model-playground.png)
+
+
 ## Success Criteria
 
-- [ ] You can see your AI Foundry project in the Azure Portal
+- [ ] You can see your Microsoft Foundry project in the Azure Portal
 - [ ] A model deployment for gpt-5.4 shows "Succeeded" status
-- [ ] You can send a test message in the Foundry Playground (Portal)
+- [ ] You can send a test message in the Foundry Model Playground

callcenter/challenge-0-setup/deploy.sh

@@ -19,6 +19,27 @@ MODEL_VERSION="${MODEL_VERSION:-2026-03-05}"
 LOG_ANALYTICS_NAME="${LOG_ANALYTICS_NAME:-foundry-hack-logs-$SUFFIX}"
 APP_INSIGHTS_NAME="${APP_INSIGHTS_NAME:-foundry-hack-insights-$SUFFIX}"
 
+# --- Argument parsing --------------------------------------------------------
+# Resource tags always include the default below. Provide additional tags with:
+#   deploy.sh --tags 'MyTag=MyValue' 'Owner=Jane'
+TAGS=("environment=hack")
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --tags)
+            shift
+            while [[ $# -gt 0 && "$1" != --* ]]; do
+                TAGS+=("$1")
+                shift
+            done
+            ;;
+        *)
+            echo "Unknown argument: $1" >&2
+            echo "Usage: deploy.sh [--tags 'Key=Value' ...]" >&2
+            exit 1
+            ;;
+    esac
+done
+
 echo "=============================================="
 echo "  Foundry Hackathon — Infrastructure Deploy"
 echo "=============================================="
@@ -31,22 +52,24 @@ echo "Project:           $PROJECT_NAME"
 echo "Model Deployment:  $MODEL_DEPLOYMENT_NAME"
 echo "Model Name:        $MODEL_NAME"
 echo "Model Version:     $MODEL_VERSION"
+echo "Tags:              ${TAGS[*]}"
 echo ""
 
 # --- Resource Group ----------------------------------------------------------
 echo ">>> Creating resource group..."
 az group create \
     --name "$RESOURCE_GROUP" \
     --location "$LOCATION" \
-    --output none
+    --output none \
+    --tags "${TAGS[@]}"
 
 # --- AI Foundry Hub ----------------------------------------------------------
-echo ">>> Creating AI Foundry resource (AIServices)..."
+echo ">>> Creating Microsoft Foundry Account resource (AIServices)..."
 SUBSCRIPTION_ID=$(az account show --query id -o tsv)
 az rest \
     --method PUT \
     --url "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.CognitiveServices/accounts/$FOUNDRY_RESOURCE_NAME?api-version=2024-10-01" \
-    --body "{\"kind\": \"AIServices\", \"sku\": {\"name\": \"S0\"}, \"location\": \"$LOCATION\", \"properties\": {\"customSubDomainName\": \"$FOUNDRY_RESOURCE_NAME\", \"publicNetworkAccess\": \"Enabled\", \"allowProjectManagement\": true}}" \
+    --body "{\"kind\": \"AIServices\", \"sku\": {\"name\": \"S0\"}, \"location\": \"$LOCATION\", \"identity\": {\"type\": \"SystemAssigned\"}, \"properties\": {\"customSubDomainName\": \"$FOUNDRY_RESOURCE_NAME\", \"publicNetworkAccess\": \"Enabled\", \"allowProjectManagement\": true}}" \
     --output none || true
 
 echo ">>> Waiting for AIServices resource to reach Succeeded state..."
@@ -92,7 +115,7 @@ if [ "$DISABLE_LOCAL_AUTH" = "true" ]; then
     echo "   The deployment will continue — use DefaultAzureCredential (Entra ID) in your code."
 fi
 
-echo ">>> Creating AI Foundry project..."
+echo ">>> Creating Microsoft Foundry project..."
 az cognitiveservices account project create \
     --name "$FOUNDRY_RESOURCE_NAME" \
     --resource-group "$RESOURCE_GROUP" \
@@ -150,13 +173,23 @@ APP_INSIGHTS_RESOURCE_ID=$(az monitor app-insights component show \
     --resource-group "$RESOURCE_GROUP" \
     --query id -o tsv)
 
-# --- Connect App Insights to the Foundry project ----------------------------
-echo ">>> Connecting Application Insights to Foundry project..."
-az rest \
-    --method PATCH \
-    --url "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.CognitiveServices/accounts/$FOUNDRY_RESOURCE_NAME/projects/$PROJECT_NAME?api-version=2024-10-01" \
-    --body "{\"properties\": {\"applicationInsights\": \"$APP_INSIGHTS_RESOURCE_ID\"}}" \
-    --output none || true ------------------------------------------------
+# --- Connect App Insights to the Foundry account ----------------------------
+# In the new Foundry, monitoring resources surface as "connection" child
+# resources (visible under Management center > Connected resources), not as a
+# project property. The connection uses ApiKey auth (the App Insights
+# connection string); the platform stores that key using the account's
+# system-assigned managed identity, which is why the identity is enabled above.
+echo ">>> Connecting Application Insights to Foundry account..."
+if ! az rest \
+    --method PUT \
+    --url "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.CognitiveServices/accounts/$FOUNDRY_RESOURCE_NAME/connections/appinsights-conn?api-version=2025-06-01" \
+    --body "{\"properties\": {\"category\": \"AppInsights\", \"target\": \"$APP_INSIGHTS_RESOURCE_ID\", \"authType\": \"ApiKey\", \"credentials\": {\"key\": \"$APP_INSIGHTS_CONN_STRING\"}, \"isSharedToAll\": true, \"metadata\": {\"ApiType\": \"Azure\", \"ResourceId\": \"$APP_INSIGHTS_RESOURCE_ID\"}}}" \
+    --output none; then
+    echo "⚠️  Could not link Application Insights to the account automatically."
+    echo "   Tracing (Challenge 2) can still be configured later from the Foundry portal."
+fi
+
+# --- Retrieve endpoint and connection details -------------------------------
 echo ">>> Retrieving Foundry endpoint and keys..."
 FOUNDRY_ENDPOINT=$(az cognitiveservices account show \
     --name "$FOUNDRY_RESOURCE_NAME" \

callcenter/challenge-0-setup/images/azure-portal-resources.png

@@ -15,6 +15,13 @@ By the end of this challenge, you will have:
 
 ## Get Started
 
+> [!NOTE]
+> Before you begin, make sure you have:
+> - An **Azure subscription** where you hold both the **Contributor** role (to deploy the infrastructure) and the **Foundry User** role on the Foundry account (to build, evaluate, and run agents in Challenges 1–4).
+> - A **GitHub handle** (account) to fork this repository and run it in GitHub Codespaces.
+>
+> Subscription **Owner** (or Contributor) rights alone are **not** sufficient. Those grant control-plane access to create and manage resources, but building and running agents are data-plane operations that require the separate **Foundry User** role assigned on the Foundry account. An Owner can self-assign it; a Contributor must ask an admin to assign it after deployment.
+
 There are two ways to get started — pick one:
 
 > **First step for both options:** [Fork this repository](https://github.com/microsoft/FrontierWeekHack/fork) to your own GitHub account.
@@ -27,7 +34,7 @@ No local installs needed. Everything runs in a cloud dev environment.
 
 1. Click the badge above (select your fork if applicable)
 2. Wait for the Codespace to build (~2 min)
-3. In the terminal, login to Azure and deploy your scenario:
+3. In the terminal, log in to Azure:
 
 ```bash
 az login
@@ -53,7 +60,7 @@ source .venv/bin/activate  # On Windows: .venv\Scripts\activate
 # 3. Install Python dependencies
 pip install -r requirements.txt
 
-# 4. Login to Azure
+# 4. Log in to Azure
 az login
 ```
 
@@ -69,8 +76,27 @@ bash challenge-0-setup/deploy.sh
 
 This will provision all resources **and** automatically write your `.env` file to the repository root as `.env`.
 
+## Verify the creation of your resources
+
+Go to the [Azure Portal](https://portal.azure.com/) and find your resource group, which should now contain resources like this (exact names will differ depending on scenario):
+
+![Azure Portal Resources](./images/azure-portal-resources.png)
+
+Go to the [Microsoft Foundry Portal](https://ai.azure.com) and verify that you can access the Foundry project.
+
+![Foundry Project](./images/foundry-project.png)
+
+Select **Build** in the top navigation, then **Models**, and verify that the **gpt-5.4** model is deployed.
+
+![Foundry Model](./images/foundry-model.png)
+
+Select **gpt-5.4**, enter a test message in the model playground, and verify that you get a response.
+
+![Foundry Model Playground](./images/foundry-model-playground.png)
+
+
 ## Success Criteria
 
-- [ ] You can see your AI Foundry project in the Azure Portal
+- [ ] You can see your Microsoft Foundry project in the Azure Portal
 - [ ] A model deployment for gpt-5.4 shows "Succeeded" status
-- [ ] You can send a test message in the Foundry Playground (Portal)
+- [ ] You can send a test message in the Foundry Model Playground

callcenter/challenge-0-setup/images/foundry-model-playground.png

@@ -19,6 +19,27 @@ MODEL_VERSION="${MODEL_VERSION:-2026-03-05}"
 LOG_ANALYTICS_NAME="${LOG_ANALYTICS_NAME:-foundry-hack-logs-$SUFFIX}"
 APP_INSIGHTS_NAME="${APP_INSIGHTS_NAME:-foundry-hack-insights-$SUFFIX}"
 
+# --- Argument parsing --------------------------------------------------------
+# Resource tags always include the default below. Provide additional tags with:
+#   deploy.sh --tags 'MyTag=MyValue' 'Owner=Jane'
+TAGS=("environment=hack")
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --tags)
+            shift
+            while [[ $# -gt 0 && "$1" != --* ]]; do
+                TAGS+=("$1")
+                shift
+            done
+            ;;
+        *)
+            echo "Unknown argument: $1" >&2
+            echo "Usage: deploy.sh [--tags 'Key=Value' ...]" >&2
+            exit 1
+            ;;
+    esac
+done
+
 echo "=============================================="
 echo "  Foundry Hackathon — Infrastructure Deploy"
 echo "=============================================="
@@ -31,22 +52,24 @@ echo "Project:           $PROJECT_NAME"
 echo "Model Deployment:  $MODEL_DEPLOYMENT_NAME"
 echo "Model Name:        $MODEL_NAME"
 echo "Model Version:     $MODEL_VERSION"
+echo "Tags:              ${TAGS[*]}"
 echo ""
 
 # --- Resource Group ----------------------------------------------------------
 echo ">>> Creating resource group..."
 az group create \
     --name "$RESOURCE_GROUP" \
     --location "$LOCATION" \
-    --output none
+    --output none \
+    --tags "${TAGS[@]}"
 
 # --- AI Foundry Hub ----------------------------------------------------------
-echo ">>> Creating AI Foundry resource (AIServices)..."
+echo ">>> Creating Microsoft Foundry Account resource (AIServices)..."
 SUBSCRIPTION_ID=$(az account show --query id -o tsv)
 az rest \
     --method PUT \
     --url "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.CognitiveServices/accounts/$FOUNDRY_RESOURCE_NAME?api-version=2024-10-01" \
-    --body "{\"kind\": \"AIServices\", \"sku\": {\"name\": \"S0\"}, \"location\": \"$LOCATION\", \"properties\": {\"customSubDomainName\": \"$FOUNDRY_RESOURCE_NAME\", \"publicNetworkAccess\": \"Enabled\", \"allowProjectManagement\": true}}" \
+    --body "{\"kind\": \"AIServices\", \"sku\": {\"name\": \"S0\"}, \"location\": \"$LOCATION\", \"identity\": {\"type\": \"SystemAssigned\"}, \"properties\": {\"customSubDomainName\": \"$FOUNDRY_RESOURCE_NAME\", \"publicNetworkAccess\": \"Enabled\", \"allowProjectManagement\": true}}" \
     --output none || true
 
 echo ">>> Waiting for AIServices resource to reach Succeeded state..."
@@ -92,7 +115,7 @@ if [ "$DISABLE_LOCAL_AUTH" = "true" ]; then
     echo "   The deployment will continue — use DefaultAzureCredential (Entra ID) in your code."
 fi
 
-echo ">>> Creating AI Foundry project..."
+echo ">>> Creating Microsoft Foundry project..."
 az cognitiveservices account project create \
     --name "$FOUNDRY_RESOURCE_NAME" \
     --resource-group "$RESOURCE_GROUP" \
@@ -150,13 +173,23 @@ APP_INSIGHTS_RESOURCE_ID=$(az monitor app-insights component show \
     --resource-group "$RESOURCE_GROUP" \
     --query id -o tsv)
 
-# --- Connect App Insights to the Foundry project ----------------------------
-echo ">>> Connecting Application Insights to Foundry project..."
-az rest \
-    --method PATCH \
-    --url "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.CognitiveServices/accounts/$FOUNDRY_RESOURCE_NAME/projects/$PROJECT_NAME?api-version=2024-10-01" \
-    --body "{\"properties\": {\"applicationInsights\": \"$APP_INSIGHTS_RESOURCE_ID\"}}" \
-    --output none || true ------------------------------------------------
+# --- Connect App Insights to the Foundry account ----------------------------
+# In the new Foundry, monitoring resources surface as "connection" child
+# resources (visible under Management center > Connected resources), not as a
+# project property. The connection uses ApiKey auth (the App Insights
+# connection string); the platform stores that key using the account's
+# system-assigned managed identity, which is why the identity is enabled above.
+echo ">>> Connecting Application Insights to Foundry account..."
+if ! az rest \
+    --method PUT \
+    --url "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.CognitiveServices/accounts/$FOUNDRY_RESOURCE_NAME/connections/appinsights-conn?api-version=2025-06-01" \
+    --body "{\"properties\": {\"category\": \"AppInsights\", \"target\": \"$APP_INSIGHTS_RESOURCE_ID\", \"authType\": \"ApiKey\", \"credentials\": {\"key\": \"$APP_INSIGHTS_CONN_STRING\"}, \"isSharedToAll\": true, \"metadata\": {\"ApiType\": \"Azure\", \"ResourceId\": \"$APP_INSIGHTS_RESOURCE_ID\"}}}" \
+    --output none; then
+    echo "⚠️  Could not link Application Insights to the account automatically."
+    echo "   Tracing (Challenge 2) can still be configured later from the Foundry portal."
+fi
+
+# --- Retrieve endpoint and connection details -------------------------------
 echo ">>> Retrieving Foundry endpoint and keys..."
 FOUNDRY_ENDPOINT=$(az cognitiveservices account show \
     --name "$FOUNDRY_RESOURCE_NAME" \