Consolidate the four vision exercises into two modular labs

Instructions/Exercises/Consolidated/A-analyze-visual-content-with-ai.md

@@ -0,0 +1,143 @@
+---
+lab:
+    title: 'Analyze visual content with AI'
+    description: 'Build the Wide World Importers visual analysis toolkit: a vision-enabled chat app that answers questions about produce photos, and an Azure AI Content Understanding analyzer that turns the campaign asset library into searchable structured metadata. A modular lab you can complete end to end or one task at a time.'
+    level: 300
+    concepts: 'multimodal chat, image input, Responses API, Azure AI Content Understanding, structured metadata'
+    duration: 30
+    islab: true
+    status: 'draft'
+---
+
+# Analyze visual content with AI
+
+**Difficulty** ▰▰▰▱▱ **L300**  (filled bars out of 5; **L100** beginner → **L500** expert)
+
+A photograph is full of information that your systems can't use — until a model reads it for
+you. In this lab you'll build the **Wide World Importers** visual analysis toolkit: first a chat
+app that can *look* at a photo and answer questions about it, then an analyzer that turns a whole
+image library into structured, searchable metadata.
+
+<style>
+/* "Ask Mika" just-in-time concept blocks */
+details.concept { margin:.6rem 0 1rem; }
+details.concept > summary { display:inline-block; cursor:pointer; list-style:none;
+  font-size:.85em; font-weight:600; color:#6b4ba1; background:#6b4ba112;
+  border:1px solid #6b4ba133; border-radius:999px; padding:.2em .7em; }
+details.concept > summary::-webkit-details-marker { display:none; }
+details.concept > summary::before { content:"Ask Mika: "; font-weight:700; }
+details.concept > summary:hover { background:#6b4ba1; color:#fff; border-color:#6b4ba1; }
+details.concept[open] > summary { border-bottom-left-radius:0; border-bottom-right-radius:0; }
+details.concept .concept-body { border:1px solid #6b4ba133; border-top:none;
+  border-radius:0 8px 8px 8px; padding:.6rem .9rem; background:#6b4ba108; font-size:.95em; }
+</style>
+
+<details markdown="1" class="concept">
+<summary>What makes a model "multimodal"?</summary>
+<div class="concept-body" markdown="1">
+
+A **multimodal** model accepts more than one kind of input. A text-only model can only read the
+words you send it; a multimodal model can accept an **image** alongside your text and reason about
+both together. That means you can send a photo of an unfamiliar fruit and ask "what is this and
+what would I cook with it?" in a single request — no separate image classifier, no fixed list of
+labels.
+
+[Learn more →](https://learn.microsoft.com/azure/foundry/openai/how-to/responses)
+
+</div>
+</details>
+
+**Your scenario:** you work at **Wide World Importers**, a specialty grocery importer that ships
+unusual produce to supermarkets worldwide, and runs its own marketing studio. Store staff regularly
+receive crates of fruit nobody on the floor recognizes, and the studio's asset library has grown to
+thousands of untagged photographs. Across this lab you'll build the AI that fixes both problems.
+
+You'll start with the **Core** task that gets you to a working, vision-enabled app as quickly as
+possible. From there, a set of **Optional** tasks lets you go deeper.
+
+> **Note**: Some of the technologies used in this exercise are in preview or in active
+> development. You may experience some unexpected behavior, warnings, or errors.
+
+## What you'll learn
+
+By completing the **Core** task of this exercise, you'll be able to:
+
+- **Send an image to a multimodal model** with the Responses API — combine an `input_text` prompt
+  and an `input_image` reference in one request and read the model's answer.
+
+The **Optional** tasks let you additionally:
+
+- **Send a local image file** to the model by base64-encoding it into a data URL, instead of
+  pointing at a public link.
+- **Extract structured metadata** from images with **Azure AI Content Understanding** — define a
+  schema of fields, build an analyzer against it, and call that analyzer from Python to get
+  consistent descriptions and tags back.
+
+## How this lab is organized
+
+This lab is **modular**. Each task is written to be completed **on its own, starting fresh** —
+so you can pick a single task and do just that one. Every task also shares one starter folder,
+one virtual environment, and one `.env`, so if you'd rather work straight through, you can.
+
+1. **Start with [Getting started](A0-getting-started.md)** — create your Microsoft Foundry
+   project, deploy a model, get the starter code, and set up your `.env`. Every task begins
+   here; if you're doing the whole lab in one sitting, you only need to do this once.
+2. **Do any task.** Each task lists the setup it needs so you can start it independently. If
+   you're moving straight from the previous task, a short *"Continuing from a previous task?"*
+   note at the top lets you skip the repeated setup and keep going.
+
+## Lab at a glance
+
+Complete the **Core** task first (about **30 minutes**) — it ends with a working vision-enabled
+chat app. Then expand any **Optional** tasks that interest you. The full lab, including all
+optional tasks, takes about **1 hour 15 minutes**.
+
+| Section | Task | Difficulty | Time |
+| --- | --- | --- | --- |
+| **Core** | [Task 1 – Ask a model about an image](A1-ask-a-model-about-an-image.md) | ▰▰▰▱▱ L300 | ~30 min |
+| *Optional* | [Task 2 – Send a local image file](A2-send-a-local-image-file.md) | ▰▰▱▱▱ L200 | ~15 min |
+| *Optional* | [Task 3 – Extract structured metadata with Content Understanding](A3-extract-structured-metadata.md) | ▰▰▰▱▱ L300 | ~30 min |
+
+**Choosing your path** — pick the tasks that fit the time you have:
+
+- **Core only (~30 min):** do Task 1.
+- **Core + local files (~45 min):** add **Task 2**, which swaps the public image link for a file on disk.
+- **Everything (~1h 15m):** add **Task 3**, which moves from conversational answers to structured,
+  schema-driven metadata you can index and search.
+
+## Two ways to read an image
+
+The tasks in this lab deliberately show two different shapes of the same idea, and knowing when to
+reach for each is the real lesson:
+
+- In **Task 1** and **Task 2**, you send an image to a **chat model** and get a free-form,
+  conversational answer. This is ideal when a human is asking the question, and every question is
+  different — "what is this?", "is it ripe?", "what would I cook with it?".
+- In **Task 3**, you send an image to a **Content Understanding analyzer** and get a **structured
+  result** that always has the same fields. This is what you want when a *system* is asking, and
+  you need thousands of images described the same way so you can index and search them.
+
+Same photograph, two very different outputs — one for people, one for pipelines.
+
+## Summary
+
+Across this lab you:
+
+- Sent an **image and a prompt** to a multimodal model with the Responses API and read the answer.
+- (Optionally) **base64-encoded a local file** into a data URL so the model could read an image
+  that isn't published anywhere.
+- (Optionally) built a **Content Understanding analyzer** with a custom schema and called it from
+  Python to generate consistent descriptions and tags for a library of images.
+
+Together these cover both halves of visual analysis: answering a person's question about one
+image, and describing a whole library consistently enough to search.
+
+## Clean up
+
+If you're finished, delete the resources you created to avoid unnecessary Azure costs.
+
+1. In the [Azure portal](https://portal.azure.com), navigate to the resource group that contains your Foundry resource.
+1. On the toolbar, select **Delete resource group**, enter the resource group name, and confirm.
+
+> If you completed Task 3, the same resource group also contains the storage account you created
+> for Content Understanding — deleting the resource group removes it too.

Instructions/Exercises/Consolidated/A0-getting-started.md

@@ -0,0 +1,146 @@
+---
+lab:
+    title: 'Getting started: set up your environment'
+    description: 'Shared setup for the Analyze visual content with AI lab: create a Microsoft Foundry project, deploy a multimodal model, get the starter code, and configure your environment. Complete this once before any task.'
+    level: 300
+    concepts: 'environment setup, Microsoft Foundry project, model deployment'
+    status: 'draft'
+---
+
+# Getting started
+
+This page sets up everything the **Analyze visual content with AI** lab needs. **Every task begins
+here** — complete this page first. Each task is written so you can then do it on its own; if you're
+working through the whole lab in one sitting, you only need to do this setup once.
+
+**Your scenario:** you work at **Wide World Importers**, a specialty grocery importer that ships
+unusual produce to supermarkets worldwide, and runs its own marketing studio. Across the lab you'll
+build the AI that helps store staff identify unfamiliar produce and helps the studio tag its image
+library.
+
+> **Note**: Some of the technologies used in this lab are in preview or in active
+> development. You may experience some unexpected behavior, warnings, or errors.
+
+## Prerequisites
+
+Before starting, ensure you have:
+
+- An active [Azure subscription](https://azure.microsoft.com/pricing/purchase-options/azure-account) with sufficient permissions and quota to provision Azure AI resources
+- [Visual Studio Code](https://code.visualstudio.com/) installed on your local machine
+- [Python 3.13](https://www.python.org/downloads/) or later installed\*
+- [Git](https://git-scm.com/downloads) installed and configured
+- [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) installed
+- Basic familiarity with Python
+
+> \* Python 3.14 is available, but some dependencies are not yet compiled for that release. The lab has been successfully tested with Python 3.13.12.
+
+## Create a Microsoft Foundry project
+
+Microsoft Foundry uses projects to organize models, resources, data, and other assets used to
+develop an AI solution.
+
+1. In a web browser, open the [Foundry portal](https://ai.azure.com) at `https://ai.azure.com` and sign in using your Azure credentials. Close any tips or quick start panes that are opened the first time you sign in.
+
+    > **Important**: For this lab, you're using the **New** Foundry experience. If it isn't already enabled, enable the **New Foundry** option in the toolbar at the top of the page.
+
+1. When prompted, create a **new** project with a unique name. Expand the **Advanced options** area and specify:
+    - **Foundry resource**: *Use the default name for your resource (usually {project_name}-resource)*
+    - **Subscription**: *Your Azure subscription*
+    - **Resource group**: *Create or select a resource group*
+    - **Region**: *Select any available region*\*
+
+    > \* Some Azure AI resources are constrained by regional model quotas. If you hit a quota limit later, you may need to create another resource in a different region.
+
+1. Select **Create** and wait for your project to be created.
+
+1. On the home page for your project, note that the API key, project endpoint, and **Azure OpenAI endpoint** are displayed.
+
+    > **Important**: You need the **Azure OpenAI endpoint**, <u>not</u> the project endpoint. Copy it now — you'll add it to your `.env` in a moment.
+
+## Deploy a model
+
+Tasks 1 and 2 need a model that can process image-based input.
+
+1. On the **Discover** page, select the **Models** tab to view the Microsoft Foundry model catalog.
+
+1. Search for and deploy the `gpt-5.2` model using the default settings. Deployment may take a minute or so.
+
+    > **Tip**: Model deployments are subject to regional quotas. If you don't have enough quota to deploy `gpt-5.2` in your project's region, use another generally available multimodal model such as `gpt-4.1` or `gpt-4o`. Alternatively, create a new project in a different region.
+
+1. When the model has been deployed, the model playground page opens, where you can chat with the model.
+
+    > **Tip**: Note the model deployment name (which by default matches the model name, for example *gpt-5.2*) — you'll need it for `MODEL_DEPLOYMENT_NAME`.
+
+## Test the model in the playground
+
+Before you write any code, confirm your deployment can actually read an image.
+
+1. In a new browser tab, download [mango.jpeg](https://microsoftlearning.github.io/mslearn-ai-vision/Labfiles/A-analyze-visual-content-with-ai/mango.jpeg) from `https://microsoftlearning.github.io/mslearn-ai-vision/Labfiles/A-analyze-visual-content-with-ai/mango.jpeg` and save it to a folder on your local file system.
+
+1. Navigate back to the chat playground page for your model deployment in the Foundry portal.
+
+1. In the main chat session panel, under the chat input box, use the attach button (**&#128206;**) to upload the *mango.jpeg* image file, and then add the text `What desserts could I make with this fruit?` and submit the prompt.
+
+    ![Screenshot of the chat playground page.](../../media/chat-playground-image-new.png)
+
+1. Review the response, which should provide relevant guidance for desserts you can make using a mango.
+
+## Get the starter code
+
+1. In VS Code, open the Command Palette (**Ctrl+Shift+P**), run **Git: Clone**, and enter:
+
+    ```
+    https://github.com/microsoftlearning/mslearn-ai-vision.git
+    ```
+
+    You may be prompted to confirm you trust the authors.
+
+1. Open the cloned repo, then **File > Open Folder** and select `mslearn-ai-vision/Labfiles/A-analyze-visual-content-with-ai/Python`. This single folder holds the starter code for **every** task in this lab — you use one virtual environment and one `.env` throughout.
+
+1. In VS Code, view the **Extensions** pane and, if it isn't already installed, install the **Python** extension.
+
+1. Right-click **requirements.txt** and choose **Open in Integrated Terminal**. Then create a virtual environment and install packages:
+
+    ```
+    python -m venv labenv
+    .\labenv\Scripts\Activate.ps1
+    pip install -r requirements.txt
+    ```
+
+1. Copy **.env.example** to a new file named **.env**, then open it and set the values you have so far:
+
+    - `OPENAI_ENDPOINT` — the Azure OpenAI endpoint for your Foundry resource, ending in `/openai/v1/`, so it looks like `https://{your-resource-name}.openai.azure.com/openai/v1/`
+    - `MODEL_DEPLOYMENT_NAME` — the deployment name of the model you deployed above
+
+    Save the file.
+
+    > `CONTENT_UNDERSTANDING_ENDPOINT` and `ANALYZER_ID` are only used by **Task 3**, which walks you through creating the analyzer they refer to. Leave them as they are for now.
+
+## Sign in to Azure
+
+Every task in this lab authenticates with `DefaultAzureCredential`, which uses your Azure CLI
+sign-in. In the terminal, run:
+
+```
+az login
+```
+
+> **Note**: In most scenarios, just using *az login* will be sufficient. However, if you have subscriptions in multiple tenants, you may need to specify the tenant by using the *--tenant* parameter. See [Sign into Azure interactively using the Azure CLI](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively) for details.
+
+## Check you're ready for a task
+
+Each task needs specific values in your `.env`. Before starting a task, run the preflight
+check from the `Python` folder — it reads your `.env` and tells
+you what (if anything) is missing:
+
+```
+python ../setup/check_env.py --task 1
+```
+
+Swap `1` for the task number you're about to start. That's it — head to any task:
+
+| Task | Page |
+| --- | --- |
+| Task 1 – Ask a model about an image | [A1](A1-ask-a-model-about-an-image.md) |
+| Task 2 – Send a local image file | [A2](A2-send-a-local-image-file.md) |
+| Task 3 – Extract structured metadata with Content Understanding | [A3](A3-extract-structured-metadata.md) |