Add AI MicroHack: Inventory Planning with AI Agents, Cosmos DB & Hosted Agents (pro-code)

03-Azure/01-04-AI/03_Inventory_Planning_Agentic/.devcontainer/devcontainer.json

@@ -0,0 +1,35 @@
+{
+  "name": "Agentic Inventory hack",
+  "image": "mcr.microsoft.com/devcontainers/python:3.11-bookworm",
+  "features": {
+    "ghcr.io/devcontainers/features/azure-cli:1": {},
+    "ghcr.io/azure/azure-dev/azd:latest": {},
+    "ghcr.io/devcontainers/features/github-cli:1": {}
+  },
+  "forwardPorts": [8000],
+  "portsAttributes": {
+    "8000": {
+      "label": "Planner Console",
+      "onAutoForward": "openPreview"
+    }
+  },
+  "postCreateCommand": "bash .devcontainer/post-create.sh",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python",
+        "ms-python.vscode-pylance",
+        "ms-azuretools.azure-dev",
+        "ms-azuretools.vscode-azureresourcegroups",
+        "teamsdevapp.vscode-ai-foundry"
+      ],
+      "settings": {
+        "python.defaultInterpreterPath": "/usr/local/bin/python",
+        "python.terminal.activateEnvironment": true
+      }
+    }
+  },
+  "remoteEnv": {
+    "PYTHONPATH": "${containerWorkspaceFolder}/src"
+  }
+}

03-Azure/01-04-AI/03_Inventory_Planning_Agentic/.devcontainer/post-create.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Runs once when the Codespace / devcontainer is created.
+set -euo pipefail
+
+echo "==> Installing uv (fast Python package manager)"
+python -m pip install --upgrade pip uv
+
+echo "==> Installing dependencies from src/pyproject.toml (uv sync)"
+( cd src && uv sync )
+
+echo "==> Seeding src/.env (edit it with your lab dashboard values)"
+if [ ! -f src/.env ]; then
+  cp .env.example src/.env
+fi
+
+echo ""
+echo "============================================================"
+echo " Ready. Next steps:"
+echo "   1. az login"
+echo "   2. Edit src/.env with PROJECT_ENDPOINT + MODEL_DEPLOYMENT_NAME + COSMOS_ENDPOINT"
+echo "   3. cd src && uv run uvicorn ui.app:app --reload --port 8000"
+echo "   4. Open the forwarded port 8000 and follow the console."
+echo "============================================================"

03-Azure/01-04-AI/03_Inventory_Planning_Agentic/.env.example

@@ -0,0 +1,20 @@
+# Copy this file to `.env` and fill in the three values from your lab dashboard.
+# The dashboard shows these after `labautomation/deploy-lab.ps1` provisions your lab.
+
+# Foundry project endpoint (dashboard: FoundryProjectEndpoint)
+PROJECT_ENDPOINT=https://inv-xxxxxxxxxxxx.services.ai.azure.com/api/projects/inventory-hack
+
+# Model deployment name (dashboard: ModelDeploymentName)
+MODEL_DEPLOYMENT_NAME=gpt-5.4-mini
+
+# Per-attendee Cosmos DB endpoint (dashboard: CosmosEndpoint) — the governed data store
+COSMOS_ENDPOINT=https://inv-cos-xxxxxxxxxxxx.documents.azure.com:443/
+COSMOS_DATABASE=inventory
+
+# Optional: set to true to attach the Web Search grounding tool in Challenge 1.
+ENABLE_WEB_SEARCH=false
+
+# Optional: reasoning budget for GPT-5 models. "minimal" keeps the planner console
+# snappy (gpt-5.4-mini is a reasoning model). Options: minimal | low | medium |
+# high | none | default. Use "default" to let the model decide.
+REASONING_EFFORT=minimal

03-Azure/01-04-AI/03_Inventory_Planning_Agentic/.github/agents/hack-compliance-validator.agent.md

@@ -0,0 +1,62 @@
+---
+description: "Use when you want to validate that this hack is fully compliant with the microsoft/MicroHack platform conventions. Checks directory naming, deploy-lab.ps1 parameter contract, lab-defaults.json schema validity, platform integration rules (no Connect-AzAccount, no premature RG creation), credential return pattern, and content structure. Run before committing or requesting platform access."
+name: "Hack Compliance Validator"
+tools: [read, search]
+user-invocable: true
+argument-hint: "Validate this hack for EMEA platform compliance"
+---
+
+You are a strict EMEA MicroHack platform compliance auditor based on [microsoft/MicroHack](https://github.com/microsoft/MicroHack).
+Inspect this workspace and produce a pass/fail report against every mandatory convention.
+
+## Compliance Checklist
+
+Work through each item. Mark ✅ PASS or ❌ FAIL with a brief reason.
+
+### 1. Directory Structure
+- [ ] `labautomation/` directory exists (no dashes — exactly `labautomation`).
+- [ ] `labautomation/` contains **only** `deploy-lab.ps1`, `lab-defaults.json`, and `README.md` — no stray files (facilitator notes, runbooks, secrets, etc.). One-time setup / prerequisite docs belong in `walkthrough/` or a separate top-level folder, not here.
+- [ ] `labautomation/lab-defaults.json` exists.
+- [ ] `labautomation/README.md` exists.
+- [ ] The root readme is **`README.md`** (all caps), and **every link that targets it uses that exact casing** — the `[Home]` links in `challenges/` (`../README.md`) and `walkthrough/` (`../../README.md`). GitHub is case-sensitive, so a `../Readme.md` link would 404. Flag any casing mismatch as **blocking** — even though it resolves on Windows.
+- [ ] `challenges/` directory exists.
+- [ ] `walkthrough/` directory exists.
+
+### 2. deploy-lab.ps1 — Parameter Contract
+- [ ] `labautomation/deploy-lab.ps1` exists (optional but recommended).
+- [ ] If it exists: parameter block declares exactly `$DeploymentType`, `$SubscriptionId`, `$ResourceGroupName`, `$PreferredLocation`, `$AllowedEntraUserIds`.
+- [ ] `$DeploymentType` has `[ValidateSet('subscription','resourcegroup','resourcegroup-with-subscriptionowner')]`.
+
+### 3. deploy-lab.ps1 — Platform Integration Rules
+- [ ] Script does **NOT** call `Connect-AzAccount` (platform pre-sets Az context).
+- [ ] For `resourcegroup` deployment type: script does **NOT** call `New-AzResourceGroup` (platform pre-creates it).
+- [ ] For `subscription` deployment type: script uses `Get-MhhStableHash` to generate a deterministic RG name.
+- [ ] Any `Get-MhhStableHash` call passes `-Length` within the valid **12–64** range. Values below 12 throw at runtime and silently fail the whole deployment — flag as **blocking**.
+
+### 4. deploy-lab.ps1 — Credential Return
+- [ ] Script emits at least one `@{ HackboxCredential = @{ name = ...; value = ...; note = ... } }` to the output stream.
+
+### 5. lab-defaults.json — Schema Validity
+- [ ] File is valid JSON (no comments, no trailing commas).
+- [ ] Contains `"$schema"` pointing to the MicroHack schema URL.
+- [ ] `deploymentType` is one of: `"resourcegroup"`, `"resourcegroup-with-subscriptionowner"`, `"subscription"`.
+- [ ] `preferredLocation` is a comma-separated string of Azure region names.
+- [ ] `estimatedDailyCostsUsd` is a non-negative number.
+
+### 6. Platform Compatibility
+- [ ] No hard-coded corporate network, specific DNS, or environment-specific blocks.
+- [ ] Script works for on-site, online, and hybrid event formats.
+
+---
+
+## How to Run
+
+1. Use `#tool:search` and `#tool:read` to locate and read each required file.
+2. For each checklist item, read the relevant section and determine pass/fail.
+3. Output the full checklist with ✅/❌ status.
+4. Output a **Summary** section:
+   - Total: X/6 categories passing
+   - Blocking issues (❌ on categories 1–5 are blocking)
+   - Recommendations (non-blocking improvements)
+
+Be strict. A missing `$schema` in lab-defaults.json or a wrong parameter name in deploy-lab.ps1 causes the platform to skip the script silently — flag these as blocking. A root-readme casing mismatch and an out-of-range `Get-MhhStableHash -Length` are also blocking (broken GitHub links / runtime failure respectively).

03-Azure/01-04-AI/03_Inventory_Planning_Agentic/.github/copilot-instructions.md

@@ -0,0 +1,80 @@
+# MicroHack Lab — EMEA Platform Conventions
+
+This workspace is a microhack lab for the **EMEA MicroHack platform** ([microsoft/MicroHack](https://github.com/microsoft/MicroHack)).
+The platform renders a front-end UI, but **all resource provisioning comes from `labautomation/deploy-lab.ps1`**.
+Without a working deployment script, no resources appear in the Azure portal — the platform is just a shiny front end.
+
+## Mandatory Structure
+
+```
+labautomation/          ← exactly this name, no dashes
+  deploy-lab.ps1        ← platform entry point (optional but recommended)
+  lab-defaults.json     ← platform configuration (required if folder exists)
+  README.md             ← usage notes
+challenges/             ← challenge instructions (Markdown)
+walkthrough/            ← solutions
+README.md               ← hack intro, objectives, prerequisites
+```
+
+## deploy-lab.ps1 — Parameter Contract
+
+The platform **skips the script** if the parameter block does not exactly match:
+
+```powershell
+param(
+    [Parameter(Mandatory=$true)]
+    [ValidateSet('subscription','resourcegroup','resourcegroup-with-subscriptionowner')]
+    [string]$DeploymentType,
+
+    [Parameter(Mandatory=$true)]
+    [string]$SubscriptionId,
+
+    [string]$ResourceGroupName = "",
+
+    [string[]]$PreferredLocation = @(),
+
+    [string[]]$AllowedEntraUserIds = @()
+)
+```
+
+## Platform Guarantees (before your script runs)
+
+- Az context is already set to `$SubscriptionId` — **do NOT call `Connect-AzAccount`**
+- For `resourcegroup`/`resourcegroup-with-subscriptionowner`: the RG exists and your script has `Owner` — **do NOT call `New-AzResourceGroup`**
+- For `subscription`: your script has `Owner` on the subscription; **you must create the RG yourself** using `Get-MhhStableHash` for deterministic naming
+- `Az.Accounts` and `Az.Resources` modules are already imported
+
+## lab-defaults.json — Required Shape
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/microsoft/MicroHack/refs/heads/main/lab-defaults-schema.json",
+  "groups": [],
+  "deploymentType": "resourcegroup",
+  "labsPerSubscription": 4,
+  "preferredLocation": "westeurope, swedencentral, norwayeast",
+  "estimatedDailyCostsUsd": 5.0
+}
+```
+
+- `deploymentType`: `"resourcegroup"` | `"resourcegroup-with-subscriptionowner"` | `"subscription"`
+- `groups`: `[]` (Azure only), `["GHCPUsers"]` (GitHub Copilot seat), `["M365-E5-Users"]` (M365 E5)
+- `preferredLocation`: comma-separated regions, priority order
+- `estimatedDailyCostsUsd`: per-user per-day cost for the lifecycle wizard
+
+## Returning Credentials to Users
+
+Write a hashtable to the output stream — the platform captures it and shows it on the user's dashboard:
+
+```powershell
+@{ HackboxCredential = @{ name = "AdminPassword"; value = "TopSecret!"; note = "VM admin password" } }
+```
+
+## Delivery Deadline
+
+Labs must have at least a skeleton committed by **end of July** — September events are already scheduled.
+
+## Platform Compatibility
+
+The platform supports **on-site**, **online**, and **hybrid** delivery.
+Do not hard-code corporate network or specific DNS assumptions.

03-Azure/01-04-AI/03_Inventory_Planning_Agentic/.github/instructions/labautomation.instructions.md

@@ -0,0 +1,101 @@
+---
+description: "Use when creating, editing, or reviewing labautomation/deploy-lab.ps1, lab-defaults.json, or any PowerShell helper inside labautomation/. Enforces microsoft/MicroHack platform deployment conventions."
+applyTo: "labautomation/**"
+---
+
+# Lab Automation Conventions (microsoft/MicroHack)
+
+## deploy-lab.ps1 — Required Parameter Contract
+
+The platform **silently skips** the script if the parameter block does not match exactly:
+
+```powershell
+param(
+    [Parameter(Mandatory=$true)]
+    [ValidateSet('subscription','resourcegroup','resourcegroup-with-subscriptionowner')]
+    [string]$DeploymentType,
+
+    [Parameter(Mandatory=$true)]
+    [string]$SubscriptionId,
+
+    [string]$ResourceGroupName = "",
+
+    [string[]]$PreferredLocation = @(),
+
+    [string[]]$AllowedEntraUserIds = @()
+)
+```
+
+## Critical Platform Rules
+
+**NEVER do these — they break platform integration:**
+
+```powershell
+# WRONG — platform already sets Az context
+Connect-AzAccount
+
+# WRONG — platform pre-creates the RG for resourcegroup deployments
+New-AzResourceGroup -Name $ResourceGroupName ...
+```
+
+**For `subscription` deployments only** — you must create your own RG using a deterministic name:
+
+```powershell
+$stableHash = Get-MhhStableHash $AllowedEntraUserIds -Length 24
+$effectiveResourceGroup = "lab-$stableHash"
+New-AzResourceGroup -Name $effectiveResourceGroup -Location $effectiveLocation
+```
+
+## Resolving Effective Location
+
+```powershell
+$effectiveLocation = if ($PreferredLocation.Count -gt 0) { $PreferredLocation[0] } else { "westeurope" }
+```
+
+## Deploying Resources
+
+Reference templates relative to `$scriptPath`:
+
+```powershell
+$scriptPath = Split-Path -Parent $MyInvocation.MyCommand.Definition
+$template = Join-Path $scriptPath "template.bicep"
+New-AzResourceGroupDeployment -ResourceGroupName $effectiveResourceGroup -TemplateFile $template -Verbose
+```
+
+## Returning Credentials to the User Dashboard
+
+Write a hashtable to the output stream — the platform captures every one:
+
+```powershell
+@{ HackboxCredential = @{ name = "AdminPassword"; value = "TopSecret!"; note = "VM admin password" } }
+```
+
+Always return at minimum the resource group name so users can find their resources.
+
+## lab-defaults.json — Required Shape
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/microsoft/MicroHack/refs/heads/main/lab-defaults-schema.json",
+  "groups": [],
+  "deploymentType": "resourcegroup",
+  "labsPerSubscription": 4,
+  "preferredLocation": "westeurope, swedencentral, norwayeast",
+  "estimatedDailyCostsUsd": 5.0
+}
+```
+
+- `$schema` is **required** — the platform validates against it
+- `deploymentType`: `"resourcegroup"` | `"resourcegroup-with-subscriptionowner"` | `"subscription"`
+- `groups`: `[]` for Azure-only; add `"GHCPUsers"` or `"M365-E5-Users"` as needed
+- `preferredLocation`: comma-separated regions in priority order — list multiple for regional fallback
+- `estimatedDailyCostsUsd`: cost per user per day; used in the lifecycle cost wizard
+
+## Available Platform Helper Cmdlets
+
+| Cmdlet | Use |
+|--------|-----|
+| `Get-MhhStableHash` | Deterministic per-user hash for resource naming in `subscription` mode |
+| `Get-MhhLabUser` | Get Entra user details for `$AllowedEntraUserIds` |
+| `Invoke-MhhDeploymentWithRegionFallback` | Deploy with automatic region fallback |
+| `Test-MhhDeploymentFailureRetryable` | Check if a deployment error is transient |