cu-sdk-sample-run

# Run a Specific Sample Run a specific sample from the Azure AI Content Understanding Java 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 - Java >= 8 (JDK) - Maven - SDK package available (public Maven Central or local build) - Environment variables configured (via shell `export`) - For prebuilt analyzers: model deployments configured (run `Sample00_UpdateDefaults` first) > **[ASK USER] Prerequisites check:** > Before proceeding, verify the user's environment: > 1. "Do you have **Java** and **Maven** installed?" -- If no, direct them to install JDK 8+ and Maven. > 2. "Have you **built the SDK** or is it available on Maven Central?" -- If no, direct them to Step 2 below. > 3. "Have you configured your **environment variables** (endpoint and credentials)?" -- If no, direct them to Step 3. > 4. "Have you run `Sample00_UpdateDefaults` to configure model defaults?" -- If no and they want to use prebuilt analyzers, guide them to run it first. > 5. *(Deferred — only if the user later picks `Sample16_CreateAnalyzerWithLabels`.)* "Do you plan to **train with labeled data**? If yes, you'll need an Azure Blob container with the receipt label files uploaded and a SAS URL." Walk them through Step 5's Sample16 subsection when relevant. ## Package Directory ``` sdk/contentunderstanding/azure-ai-contentunderstanding ``` ## Available Samples All sync samples have async versions with an `Async` suffix. Samples are located in: ``` src/samples/java/com/azure/ai/contentunderstanding/samples/ ``` ### Getting Started (Run These First) #### `Sample00_UpdateDefaults` -- Required First! **One-time setup** - Configures model deployment mappings (GPT-4.1, GPT-4.1-mini, text-embedding-3-large) for your Microsoft Foundry resource. Must run before using prebuilt analyzers. #### `Sample02_AnalyzeUrl` -- 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 #### `Sample01_AnalyzeBinary` Analyzes local PDF/image files using `prebuilt-documentSearch`. - Key concepts: Binary input, local file reading, page properties ### Document Analysis #### `Sample03_AnalyzeInvoice` Extracts structured fields from invoices using `prebuilt-invoice`. - Key concepts: Field extraction (customer name, totals, dates, line items), confidence scores, array fields #### `Sample10_AnalyzeConfigs` Extracts advanced features: charts, hyperlinks, formulas, annotations. - Key concepts: Chart.js output, LaTeX formulas, PDF annotations, enhanced analysis options #### `Sample11_AnalyzeReturnRawJson` Gets raw JSON response for custom processing. - Key concepts: Raw response access, saving to file, debugging ### Custom Analyzers #### `Sample04_CreateAnalyzer` Creates custom analyzer with field schema for domain-specific extraction. - Key concepts: Field types (string, number, date, object, array), extraction methods (extract, generate, classify) #### `Sample05_CreateClassifier` Creates classifier to categorize documents (Loan_Application, Invoice, Bank_Statement). - Key concepts: Content categories, segmentation, document routing #### `Sample16_CreateAnalyzerWithLabels` Builds an analyzer using **labeled training data** loaded from Azure Blob Storage. The repo ships labeled receipt data at `src/samples/resources/receipt_labels/` (`*.jpg`, `*.jpg.labels.json`, optional `*.jpg.result.json`). - Key concepts: `LabeledDataKnowledgeSource`, knowledge sources on `ContentAnalyzerConfig`, container SAS URLs, optional path prefix, falls back to creating analyzer **without** training data if SAS URL is unset - Requires either: (a) a SAS URL for an Azure Blob container with labeled data uploaded, or (b) accepting that no training data is used - For an easier labeling workflow, use [Azure AI Content Understanding Studio](https://contentunderstanding.ai.azure.com/) ### Analyzer Management #### `Sample06_GetAnalyzer` Retrieves analyzer details and configuration. #### `Sample07_ListAnalyzers` Lists all analyzers in the Content Understanding resource. - Key concepts: Paginated listing, analyzer enumeration #### `Sample08_UpdateAnalyzer` Updates analyzer description and tags. #### `Sample09_DeleteAnalyzer` Deletes a custom analyzer. #### `Sample14_CopyAnalyzer` Copies analyzer within the same resource. #### `Sample15_GrantCopyAuth` Cross-resource copying between different Azure resources/regions. - Requires additional env vars: `CONTENTUNDERSTANDING_SOURCE_RESOURCE_ID`, `CONTENTUNDERSTANDING_SOURCE_REGION`, `CONTENTUNDERSTANDING_TARGET_ENDPOINT`, `CONTENTUNDERSTANDING_TARGET_RESOURCE_ID`, `CONTENTUNDERSTANDING_TARGET_REGION`, `CONTENTUNDERSTANDING_TARGET_KEY` (optional) ### Result Management #### `Sample12_GetResultFile` Retrieves keyframe images from video analysis. - Key concepts: Operation IDs, extracting generated files #### `Sample13_DeleteResult` Deletes analysis results for data cleanup. - Key concepts: Result retention (24-hour auto-deletion), compliance ### Advanced Helpers #### `Sample_Advanced_ToLlmInput` Advanced usage of the `LlmInputHelper.toLlmInput` helper that converts an `AnalysisResult` into LLM-ready text. For introductory usage, see `Sample01_AnalyzeBinary`, `Sample03_AnalyzeInvoice`, and `Sample05_CreateClassifier`. - Key concepts: `ToLlmInputOptions`, content ranges, multi-modal flattening, prompt-friendly formatting ## Workflow ### Step 1: Navigate to Package Directory ```bash cd sdk/contentunderstanding/azure-ai-contentunderstanding ``` ### Step 2: Build the SDK Package The SDK package must be available for Maven to resolve. It will be published to **Maven Central** — if it's already available there, Maven will download it automatically and you can **skip this step**. If the package is **not yet published** (or you want to test local changes), build and install it to your local Maven repository. The recommended command (run from the azure-sdk-for-java repo root) is: ```bash cd ~/repos/azure-sdk-for-java # or wherever you cloned the repo mvn install -DskipTests -pl sdk/contentunderstanding/azure-ai-contentunderstanding -am ``` > **Tip:** Building from the repo root with `-pl ... -am` is preferred when you are contributing across modules or testing in-repo dependency changes (e.g., a local `azure-core` patch). For most users, `mvn install -DskipTests` from within `sdk/contentunderstanding/azure-ai-contentunderstanding` also works, since this module's parent POM is resolved via `relativePath` and its runtime dependencies (e.g., `azure-core`) come from published artifacts. > **[ASK USER] Build check:** > Ask: "Is the package already published on Maven Central, or do you need to build locally?" > - If published: Skip to Step 3. > - If not published / unsure: Run `mvn install -DskipTests` above and confirm it shows `BUILD SUCCESS`. > > If the build fails, common fixes: > - Missing JDK: ensure `java -version` shows JDK 8+ > - Missing Maven: ensure `mvn -version` works > - Parent POM not found: run `mvn install -DskipTests -f ../../parents/azure-client-sdk-parent/pom.xml` first ### Step 3: Configure Environment Variables > **[ASK USER] Configuration check:** > Ask the user: "Do you already have your environment variables configured (`.env` file or exported in shell)?" > - If yes: Skip to Step 4. > - If no: Direct them to the `cu-sdk-setup` skill for interactive setup, or guide them through the steps below. Java samples read credentials from **OS environment variables** via `System.getenv()`. Java does not load `.env` files automatically, so the variables must be present in the shell environment when the JVM starts. The recommended approach is to create a **`.env` file** and source it before running samples. > **Tip:** Use the `cu-sdk-setup` skill for an interactive walkthrough that creates your `.env` file step by step. **Create a `.env` file** in the package root (`sdk/contentunderstanding/azure-ai-contentunderstanding/.env`): ``` # Azure AI Content Understanding - Environment Variables # Required: Your Microsoft Foundry resource endpoint CONTENTUNDERSTANDING_ENDPOINT=https://your-foundry.services.ai.azure.com/ # Optional: API key (leave empty to use DefaultAzureCredential via az login) CONTENTUNDERSTANDING_KEY= # Model deployment names (used by Sample00_UpdateDefaults) GPT_4_1_DEPLOYMENT=gpt-4.1 GPT_4_1_MINI_DEPLOYMENT=gpt-4.1-mini TEXT_EMBEDDING_3_LARGE_DEPLOYMENT=text-embedding-3-large ``` **Then load it into your shell:** ```bash set -a && source .env && set +a ``` > **Note:** You must re-run `set -a && source .env && set +a` each time you open a new terminal or edit `.env`. <details> <summary>Alternative: export variables directly (without .env file)</summary> **Linux / macOS:** ```bash export CONTENTUNDERSTANDING_ENDPOINT="https://your-foundry.services.ai.azure.com/" export CONTENTUNDERSTANDING_KEY="" # Leave empty to use DefaultAzureCredential export GPT_4_1_DEPLOYMENT="gpt-4.1" export GPT_4_1_MINI_DEPLOYMENT="gpt-4.1-mini" export TEXT_EMBEDDING_3_LARGE_DEPLOYMENT="text-embedding-3-large" ``` **Windows (PowerShell):** ```powershell $env:CONTENTUNDERSTANDING_ENDPOINT = "https://your-foundry.services.ai.azure.com/" $env:CONTENTUNDERSTANDING_KEY = "" # Leave empty to use DefaultAzureCredential $env:GPT_4_1_DEPLOYMENT = "gpt-4.1" $env:GPT_4_1_MINI_DEPLOYMENT = "gpt-4.1-mini" $env:TEXT_EMBEDDING_3_LARGE_DEPLOYMENT = "text-embedding-3-large" ``` </details> > **[ASK USER] Provide endpoint:** > Ask the user: "Please provide your **Microsoft Foundry endpoint URL**." > - It should look like: `https://<your-resource-name>.services.ai.azure.com/` > - If the user does not know where to find it: direct them to Azure Portal → Their Foundry resource → Keys and Endpoint. > **[ASK USER] Authentication method:** > Ask the user: "How would you like to **authenticate** with Azure?" > - **Option A: DefaultAzureCredential (recommended)** — Uses `az login` or managed identity. No API key needed. Make sure you have run `az login`. > - **Option B: API Key** — Provide your `CONTENTUNDERSTANDING_KEY` from the Azure Portal → Keys and Endpoint → Key1 or Key2. Update `.env` so `CONTENTUNDERSTANDING_KEY=<your-key>` (replace the empty default). > **[ASK USER] Confirm env vars:** > After the user sets their variables, ask: "Does this configuration look correct?" Wait for confirmation before proceeding. ### Step 4: Choose the Sample > **[ASK USER] Which sample?:** > Ask the user: "Which sample would you like to run?" with options: > - `Sample00_UpdateDefaults` — Configure model defaults (one-time setup, required first) > - `Sample02_AnalyzeUrl` — Analyze content from a URL (recommended for first-time users) > - `Sample01_AnalyzeBinary` — Analyze a local PDF/image file > - `Sample03_AnalyzeInvoice` — Extract structured fields from an invoice > - `Sample04_CreateAnalyzer` — Create a custom analyzer > - `Sample16_CreateAnalyzerWithLabels` — Create an analyzer with labeled training data > - Other — Let me see the full list > **[ASK USER] Sync or async?:** > Ask: "Would you like to run the **sync** or **async** version of this sample?" > - Sync (default) — e.g., `Sample02_AnalyzeUrl` > - Async — e.g., `Sample02_AnalyzeUrlAsync` ### Step 5: Configure Sample-Specific Settings Most samples only need the base environment variables from Step 3. The following samples require **additional configuration** before running. > **[ASK USER] Sample-specific config:** > Based on the sample chosen in Step 4, walk the user through the matching subsection below: > - **Prebuilt-analyzer samples** — `Sample02_AnalyzeUrl`, `Sample01_AnalyzeBinary`, `Sample03_AnalyzeInvoice`, `Sample10_AnalyzeConfigs`, `Sample11_AnalyzeReturnRawJson`, `Sample12_GetResultFile`, `Sample13_DeleteResult` → "Have you run `Sample00_UpdateDefaults`?" subsection > - `Sample01_AnalyzeBinary`, `Sample10_AnalyzeConfigs` → also "Samples that need a local file" subsection > - `Sample15_GrantCopyAuth` → "Sample15_GrantCopyAuth cross-resource environment" subsection > - `Sample16_CreateAnalyzerWithLabels` → "Sample16_CreateAnalyzerWithLabels training data" subsection > - `Sample00_UpdateDefaults` — sets up the model defaults itself; only the base env vars from Step 3 are needed > - Custom-analyzer samples (`Sample04_CreateAnalyzer`, `Sample05_CreateClassifier`) and management samples (`Sample06`–`Sample09`, `Sample14`) — only the base env vars from Step 3 are needed > > If none apply, proceed directly to Step 6. #### 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) | | `GPT_4_1_DEPLOYMENT` | Sample00_UpdateDefaults | Deployment name for gpt-4.1 model (default: `gpt-4.1`) | | `GPT_4_1_MINI_DEPLOYMENT` | Sample00_UpdateDefaults | Deployment name for gpt-4.1-mini model (default: `gpt-4.1-mini`) | | `TEXT_EMBEDDING_3_LARGE_DEPLOYMENT` | Sample00_UpdateDefaults | Deployment name for text-embedding-3-large model (default: `text-embedding-3-large`) | | `CONTENTUNDERSTANDING_SOURCE_RESOURCE_ID` | Sample15_GrantCopyAuth | Source ARM resource ID for cross-resource copy | | `CONTENTUNDERSTANDING_SOURCE_REGION` | Sample15_GrantCopyAuth | Region of the source Foundry resource (e.g., `westus`) | | `CONTENTUNDERSTANDING_TARGET_ENDPOINT` | Sample15_GrantCopyAuth | Target Foundry resource endpoint for cross-resource copy |