cu-sdk-sample-run

# Run a Specific Sample Run a specific sample from the Azure AI Content Understanding SDK. > **[COPILOT INTERACTION MODEL]:** This skill is designed to be interactive. At each step marked with **[ASK USER]**, pause execution and prompt the user for input or confirmation before proceeding. Do NOT silently skip these prompts. Use the `ask_questions` tool when available. ## Prerequisites - Python >= 3.9 - Virtual environment set up with SDK installed (see `cu-sdk-setup` skill) - Environment variables configured in `.env` - Model deployments configured via `sample_update_defaults.py` -- required for any sample that uses gpt-5.2 / text-embedding-3-large (prebuilt analyzers like `prebuilt-invoice`, custom analyzers with `extract` / `generate` / `classify` field methods, and `sample_create_analyzer_with_labels`) > **[ASK USER] Prerequisites check (run BEFORE Step 1 of the Workflow below):** > Before starting the numbered Workflow, verify the user's environment by asking these three questions in order. Do NOT skip Step 1 until each has a yes/handled answer: > 1. "Have you already set up your Python environment and installed the SDK?" -- If no, direct them to the `cu-sdk-setup` skill first; pause this skill until that finishes. > 2. "Have you configured your `.env` file with your endpoint and credentials?" -- If no, direct them to Step 4 of the `cu-sdk-setup` skill. > 3. "Have you run `sample_update_defaults.py` to configure model defaults?" -- Defer judgement: ask once you know which sample they want (Step 3 below), then check it against the **"Samples that require `sample_update_defaults` first"** list in Step 4. ## Package Directory ``` sdk/contentunderstanding/azure-ai-contentunderstanding ``` ## Available Samples All sync samples have async versions with `_async` suffix in `samples/async_samples/`. ### Getting Started (Run These First) #### `sample_update_defaults` -- Required First! **One-time setup** - Configures model deployment mappings (gpt-5.2, text-embedding-3-large) for your Microsoft Foundry resource. Must run before using prebuilt analyzers. #### `sample_analyze_url` -- Start Here! Analyzes content from a URL using `prebuilt-documentSearch`. Works with documents, images, audio, and video. - Key concepts: URL input, markdown extraction, multi-modal content #### `sample_analyze_binary` Analyzes local PDF/image files using `prebuilt-documentSearch`. - Key concepts: Binary input, local file reading, page properties ### Document Analysis #### `sample_analyze_invoice` Extracts structured fields from invoices using `prebuilt-invoice`. - Key concepts: Field extraction (customer name, totals, dates, line items), confidence scores, array fields #### `sample_analyze_configs` Extracts advanced features: charts, hyperlinks, formulas, annotations. - Key concepts: Chart.js output, LaTeX formulas, PDF annotations, enhanced analysis options #### `sample_analyze_return_raw_json` Gets raw JSON response for custom processing. - Key concepts: Raw response access, saving to file, debugging #### `sample_to_llm_input` Advanced usage of the `to_llm_input` helper -- converts structured `AnalysisResult` into LLM-ready text (YAML front matter + markdown body). - Key concepts: LLM integration, output options (fields-only, markdown-only, custom metadata), multi-segment video/audio rendering, page markers via `content_range` - Python-only helper (not available in other language SDKs) ### Custom Analyzers #### `sample_create_analyzer` Creates custom analyzer with field schema for domain-specific extraction. - Key concepts: Field types (string, number, date, object, array), extraction methods (extract, generate, classify) - **Next step:** to run this workflow on your own folder of documents (validate schema → create → batch test → stdout summary), use the [`cu-sdk-author-analyzer`](../cu-sdk-author-analyzer/SKILL.md) skill. #### `sample_create_classifier` Creates classifier to categorize documents (Loan_Application, Invoice, Bank_Statement). - Key concepts: Content categories, segmentation, document routing - **Next step:** to run this workflow on your own mixed-document packets, use the [`cu-sdk-author-analyzer-classify-route`](../cu-sdk-author-analyzer-classify-route/SKILL.md) skill. #### `sample_create_analyzer_with_labels` Builds analyzers with training labels (labeled data from Azure Blob Storage). - Key concepts: Labeled data, knowledge sources, Blob Storage SAS URIs - Requires additional env vars: `CONTENTUNDERSTANDING_TRAINING_DATA_SAS_URL` (Option A) **or** `CONTENTUNDERSTANDING_TRAINING_DATA_STORAGE_ACCOUNT` + `CONTENTUNDERSTANDING_TRAINING_DATA_CONTAINER` (Option B) ### Analyzer Management #### `sample_get_analyzer` Retrieves analyzer details and configuration. #### `sample_list_analyzers` Lists all available analyzers (prebuilt and custom). #### `sample_update_analyzer` Updates analyzer description and tags. #### `sample_delete_analyzer` Deletes a custom analyzer. #### `sample_copy_analyzer` Copies analyzer within the same resource. #### `sample_grant_copy_auth` Cross-resource copying between different Azure resources/regions. - Requires additional env vars: `CONTENTUNDERSTANDING_TARGET_ENDPOINT`, `CONTENTUNDERSTANDING_TARGET_RESOURCE_ID` ### Result Management #### `sample_get_result_file` Retrieves keyframe images from video analysis. - Key concepts: Operation IDs, extracting generated files #### `sample_delete_result` Deletes analysis results for data cleanup. - Key concepts: Result retention (24-hour auto-deletion), compliance ## Workflow ### Step 1: Navigate to Package Directory ```bash cd sdk/contentunderstanding/azure-ai-contentunderstanding ``` ### Step 2: Activate Virtual Environment ```bash source .venv/bin/activate # Linux/macOS # .venv\Scripts\activate # Windows ``` > **[ASK USER] Confirm venv active:** > Ask: "Is your virtual environment active? Run `which python` (or `where python` on Windows) and confirm it points to a path inside `.venv`." > If the user reports it is not active or does not exist, direct them to the `cu-sdk-setup` skill. ### Step 3: Choose the Sample Pick the sample (and sync/async variant) **before** configuring sample-specific settings -- subsequent `[ASK USER]` blocks in Step 4 are gated on the chosen sample. > **[ASK USER] Which sample?:** > If the user has already named a specific sample (e.g., "run sample_analyze_invoice"), confirm rather than re-prompt: > "You want to run `<sample_name>`. Continuing with that -- correct? (Reply "no" to see the full list.)" > > If the user has not yet specified a sample, ask: "Which sample would you like to run?" with options: > - `sample_analyze_url` -- Analyze content from a URL (recommended for first-time users) > - `sample_analyze_binary` -- Analyze a local PDF/image file > - `sample_analyze_invoice` -- Extract structured fields from an invoice > - `sample_create_analyzer` -- Create a custom analyzer > - `sample_create_analyzer_with_labels` -- Create a labeled-data analyzer (auto-uploads training data) > - `sample_update_defaults` -- Configure model defaults (one-time setup) > - Other -- Let me see the full list > > If the user picks "Other" (or replies "no" to the confirmation), show the full Available Samples list above or run the `--list` command (path note: from package root run `.github/skills/cu-sdk-sample-run/scripts/run_sample.sh --list`; from the workspace root prepend `sdk/contentunderstanding/azure-ai-contentunderstanding/`). > **[ASK USER] Sync or async?:** > Ask: "Would you like to run the **sync** or **async** version of this sample?" > - Sync (default) -- Runs in `samples/` > - Async -- Runs in `samples/async_samples/` with `_async` suffix ### Step 4: Configure Sample-Specific Settings (if needed) Now that the chosen sample is known, run only the subsections below that apply to it. Each subsection's `[ASK USER]` block is already gated on the relevant sample(s); skip a subsection if it doesn't match. For full environment setup (creating `.venv`, installing the SDK, writing `.env`), use the **`cu-sdk-setup`** skill. The subsections below cover settings that are sample-specific and may not have been configured during the initial setup. #### Samples that require `sample_update_defaults` first These samples invoke an analyzer that depends on gpt-5.2 / gpt-5.2 / text-embedding-3-large model deployments. They will fail with a *model deployment not found* error unless `sample_update_defaults.py` has been run for the resource: | Sample | Why | |--------|-----| | `sample_analyze_invoice` | `prebuilt-invoice` uses gpt-5.2 for field extraction | | `sample_analyze_configs` | Advanced features (charts, formulas, etc.) use gpt-5.2 | | `sample_create_analyzer` | Custom field schema with `extract` / `generate` / `classify` methods | | `sample_create_classifier` | Document classification uses gpt-5.2 | | `sample_create_analyzer_with_labels` | Labeled-data analyzer uses gpt-5.2 + text-embedding-3-large | Samples that do **not** require `sample_update_defaults` (safe to run first): `sample_analyze_url`, `sample_analyze_binary`, `sample_analyze_return_raw_json`, `sample_to_llm_input`, all analyzer-management samples (`sample_get_*`, `sample_list_*`, `sample_update_analyzer`, `sample_delete_*`, `sample_copy_analyzer`, `sample_grant_copy_auth`). > **[ASK USER] Model defaults check (only if chosen sample is in the table above):** > Ask: "This sample requires model deployments to be configured. Have you already run `sample_update_defaults.py` for this Microsoft Foundry resource?" > - **Yes** -- proceed. > - **No** -- run it first: `cd samples && python sample_update_defaults.py` (only needed once per resource). > - **Not sure** -- it's safe to re-run; the call is idempotent. #### Settings by sample | Setting | Required By | Description | |---------|-------------|-------------| | `CONTENTUNDERSTANDING_ENDPOINT` | **All samples** | Your Microsoft Foundry resource endpoint URL | | `CONTENTUNDERSTANDING_KEY` | All samples (optional) | API key for key-based auth. If empty, `DefaultAzureCredential` is used (recommended -- run `az login` first) | | `CU_COMPLETION_MODEL` | sample_update_defaults (optional) | Completion model name (default: `gpt-5.2`) | | `CU_COMPLETION_MODEL_MINI` | sample_update_defaults (optional) | Mini completion model name (default: `CU_COMPLETION_MODEL`) | | `CU_EMBEDDING_MODEL` | sample_update_defaults (optional) | Embedding model name (default: `text-embedding-3-large`) | | `CU_COMPLETION_MODEL_DEPLOYMENT` | sample_update_defaults | Completion model deployment name (required) | | `CU_COMPLETION_MINI_DEPLOYMENT` | sample_update_defaults (optional) | Mini completion deployment name (default: `CU_COMPLETION_MODEL_DEPLOYMENT`) | | `CU_EMBEDDING_DEPLOYMENT` | sample_update_defaults | Embedding model deployment name (required) | | `CONTENTUNDERSTANDING_SOURCE_RESOURCE_ID` | sample_grant_copy_auth | Source ARM resource ID for cross-resource copy | | `CONTENTUNDERSTANDING_SOURCE_REGION` | sample_grant_copy_auth | Source region (e.g., `eastus`) for cross-resource copy | | `CONTENTUNDERSTANDING_TARGET_ENDPOINT` | sample_grant_copy_auth | Target Foundry resource endpoint for cross-resource copy | | `CONTENTUNDERSTANDING_TARGET_RESOURCE_ID` | sample_grant_copy_auth | Target ARM resource ID for cross-resource copy | | `CONTENTUNDERSTANDING_TARGET_REGION` | sample_grant_copy_auth | Target region (e.g., `swedencentral`) for cross-resource copy | | `CONTENTUNDERSTANDING_TARGET_KEY` | sample_grant_copy_auth (optional) | Target API key. If empty, `DefaultAzureCredential` is used for the target resource | | `CONTENTUNDERSTANDING_TRAINING_DATA_SAS_URL` | sample_create_analyzer_with_labels (Option A) | SAS URL of the Blob container holding labeled training data (List + Read permissions) | | `CONTENTUNDERSTANDING_TRAINING_DATA_STORAGE_ACCOUNT` | sample_create_analyzer_with_labels (Option B) | Storage account name for auto-upload via `DefaultAzureCredential` | | `CONTENTUNDERSTANDING_TRAINING_DATA_CONTAINER` | sample_create_analyzer_with_labels (Option B) | Container name for auto-upload | | `CONTENTUNDERSTANDING_TRAINING_DATA_PREFIX` | sample_create_analyzer_with_labels (optional) | Virtual directory (prefix) within the container, e.g., `training_samples/` | #### Setting up sample_create_analyzer_with_labels training data `sample_create_analyzer_with_labels` needs labeled training data in an Azure Blob container. Two configurations are supported -- the sample auto-detects which one to use based on which env vars are set. > **[ASK USER] Training data option (sample_create_analyzer_with_labels only):** > If the user chose `sample_create_analyzer_with_labels`, ask: > "How would you like to provide labeled training data?" > > - **Option A -- Pre-generated SAS URL (recommended for production):** You already have labeled files in a Blob container and a SAS URL with **Read + List** permissions. > - Set `CONTENTUNDERSTANDING_TRAINING_DATA_SAS_URL` in `.env` to the full URL (`https://<account>.blob.core.windows.net/<container>?sv=...&se=...`). > > - **Option B -- Auto-upload from local files (recommended for first-time users):** The sample will upload the bundled `samples/sample_files/training_samples/` (receipts + label JSON) to your container and generate a User Delegation SAS automatically. > - Set `CONTENTUNDERSTANDING_TRAINING_DATA_STORAGE_ACCOUNT` and `CONTENTUNDERSTANDING_TRAINING_DATA_CONTAINER` in `.env`. > - Optionally set `CONTENTUNDERSTANDING_TRAINING_DATA_PREFIX` (e.g., `training_samples/`) to scope uploads to a virtual folder. > - Requires `DefaultAzureCredential` to have **Storage Blob Data Contributor** on the storage account (run `az login` first). > > If the user is unsure, recommend **Option B**. The next subsection (**"Samples that need a local file"**) only applies if Option B is chosen. > > **Do not set both options.** If both are configured, Option A (the SAS URL) takes precedence. #### Samples that need a local file The `sample_analyze_binary` and `sample_analyze_configs` samples load a local file from `samples/sample_files/`. The default file paths are built into the samples (`sample_files/sample_invoice.pdf` and `sample_files/sample_document_features.pdf` respectively). To use your own file, update the `file_path` variable in the sample code.