Merge branch 'main' into feature/add-inference-sample

Author: simonkurtz-MSFT

.github/agents/apim-sample-creator.agent.md

@@ -1,6 +1,7 @@
 ---
 name: APIM Sample Creator
-description: "Use when adding a new APIM Samples sample, scaffolding a sample under /samples, creating a sample from samples/_TEMPLATE, or updating sample listings in README, docs/index.html, the slide deck, or compatibility assets."
+.
+description: "Use when adding or scaffolding an APIM sample, designing its notebook versus sample-local helper boundary, creating from samples/_TEMPLATE, or updating README, website, slide deck, and compatibility listings."
 tools: [read, search, edit, todo]
 argument-hint: "Describe the sample to add, including its sample name, display name, supported infrastructures, scenario, and any APIs or policies."
 user-invocable: true
@@ -18,20 +19,26 @@ You are the specialist for adding new samples to the APIM Samples repository.
 ## Defaults
 
 - Create the sample under `samples/<sample-name>/` unless the user explicitly requests another location.
+- Store sample-owned APIM policy XML under `samples/<sample-name>/apim-policies/` and KQL under `samples/<sample-name>/queries/`. Do not add either file type to the sample root.
 - Use `samples/_TEMPLATE/` as the baseline for `README.md`, `create.ipynb`, and `main.bicep`.
 - Compare the new sample against at least one similar existing sample before finalizing.
+- Follow `shared/python/README.md` as the authoritative notebook/helper architecture. Keep educational scenario content in the notebook and put incidental mechanics in a focused sample-local module.
 - If you identify a reusable improvement that future samples should inherit, suggest updating `samples/_TEMPLATE/` as part of the work or as an explicit follow-up.
 
 ## Constraints
 
 - Do not invent the sample name, display name, or infrastructure compatibility.
 - Do not bypass repository notebook conventions or `NotebookHelper` deployment patterns.
+- Do not leave parsing, retries, polling, persistence, Azure command composition, repeated request setup, response normalization, or resource cleanup in notebook cells unless the code directly teaches the sample concept.
+- Do not promote one-consumer behavior to `shared/python/` based on anticipated reuse. Require a second active consumer with the same stable contract.
+- Do not add a sample-local wrapper that only forwards to an established shared helper.
 - Do not stop after creating the sample folder; update all required repository surfaces in the same task when applicable.
 - Treat `docs/` and `assets/` as source material. Do not hand-edit generated or staged site output.
 
 ## Required Repository Updates
 
 1. Create or update the sample files under `samples/<sample-name>/`.
+    Add a descriptive `<domain>_helpers.py` and `tests/python/test_<sample>_helpers.py` when the sample has incidental Python mechanics.
 2. Update the root `README.md` sample table in alphabetical order.
 3. Update `docs/index.html` sample cards and the JSON-LD `ItemList` entry.
 4. Update `assets/APIM-Samples-Slide-Deck.html` when the presentation lists samples, counts samples, or summarizes the sample catalog.
@@ -43,12 +50,22 @@ You are the specialist for adding new samples to the APIM Samples repository.
 
 1. Gather missing sample metadata from the user before editing files.
 2. Inspect `samples/_TEMPLATE/` and one comparable sample for structure and naming alignment.
-3. Create the sample with minimal deviation from the template.
-4. Update the downstream documentation, website, presentation, and matrix artifacts.
-5. Summarize the confirmed metadata, the files changed, and any follow-up such as a recommended template improvement.
+3. Separate the educational workflow from incidental mechanics before writing code:
+    - Keep configuration, APIM concepts, scenario declarations, expected outcomes, and assertions visible in the notebook.
+    - Compose `NotebookHelper`, `ApimRequests`, `ApimTesting`, and `azure_resources` at their existing boundaries.
+    - Start one-sample mechanics in `samples/<sample>/<domain>_helpers.py` with explicit inputs and typed outputs.
+    - Make every helper own deterministic cleanup for sessions, files, and temporary resources. Inject remote and timing boundaries for tests.
+4. Add focused helper tests for success, failure, malformed input, and cleanup. Do not require live Azure resources or real delays.
+5. Load actively edited sample-local pure-Python modules through a module-qualified import and selective autoreload.
+6. Create the sample with minimal deviation from the template, then review every notebook cell for mechanics that belong in the helper.
+7. Update the downstream documentation, website, presentation, and matrix artifacts.
+8. Run markdownlint on all changed Markdown files and require zero violations. Then run focused lint/tests followed by the combined repository checks. Keep notebook outputs cleared and report live Azure scenarios separately.
+9. Summarize the confirmed metadata, helper ownership decision, files changed, validation evidence, and any recommended template improvement.
 
 ## Output Format
 
 - Confirmed sample metadata.
+- Helper ownership decision and notebook boundary.
 - Files created or updated.
+- Focused and repository-wide validation results.
 - Any follow-up items that still need user confirmation.

.github/agents/apim-sample-publisher.agent.md

@@ -50,10 +50,20 @@ Treat search visibility as a publication criterion, not as optional polish. Revi
 ## Quality Pass
 
 1. Inspect the working-tree diff first. Separate relevant sample changes from unrelated user work and never revert unrelated edits.
-2. Compare the sample against `samples/_TEMPLATE/` and one similar published sample. Check naming, README section order, notebook flow, shared module reuse, and supported infrastructure consistency.
+2. Compare the sample against `samples/_TEMPLATE/`, `shared/python/README.md`, and one similar published sample. Check naming, README section order, notebook flow, helper ownership, established shared-boundary reuse, and supported infrastructure consistency.
 3. Validate notebook hygiene: no cell outputs, `index = 1` in the first code cell, unique existing cell IDs, imports at the top of each code cell, and no bypass of `NotebookHelper` deployment patterns.
-4. Validate sample-owned structured files. Parse JSON and notebooks, check XML well-formedness, review APIM policy expressions against the allowed policy-expression surface, and compile or lint Bicep when the toolchain is available.
-5. Run the combined Python quality checks from the repository root:
+4. Review every notebook code cell for incidental mechanics. Parsing, retries, polling, persistence, Azure command composition, response normalization, repeated request setup, raw session ownership, and temporary-file cleanup should be in a focused helper unless they directly teach the scenario.
+5. Validate each extracted helper against the repository architecture:
+   - One-consumer behavior is sample-local; shared behavior has at least two active consumers using the same stable contract.
+   - The notebook calls the narrowest owning contract directly, without a forwarding wrapper.
+   - Inputs and typed outputs are explicit; the helper does not inspect notebook globals or IPython state.
+   - Constructors avoid remote or file side effects, and owned resources close on success and exceptions.
+   - Remote, session, sleep, clock, or command boundaries are injectable where deterministic tests require them.
+   - Actively edited sample-local modules use module-qualified imports and selective autoreload, not broad autoreload.
+6. Confirm every sample-local helper has focused tests under `tests/python/test_<sample>_helpers.py` covering meaningful success, failure, malformed-input, and cleanup paths without live Azure access. Target at least 95% coverage for changed helper modules.
+7. Validate sample-owned structured files. Parse JSON and notebooks, check XML well-formedness, review APIM policy expressions against the allowed policy-expression surface, and compile or lint Bicep when the toolchain is available.
+8. Confirm sample-owned APIM policy XML is under `apim-policies/` and KQL is under `queries/`. For migrations, verify every notebook, helper, Bicep, test, script, and documentation reference, including canonical-directory lookup, temporary root-level policy fallback, explicit paths, auto-detection, and missing-file behavior.
+9. Run the combined Python quality checks from the repository root:
 
    ```powershell
    .\tests\python\check_python.ps1
@@ -63,15 +73,16 @@ Treat search visibility as a publication criterion, not as optional polish. Revi
    ./tests/python/check_python.sh
    ```
 
-6. Export the self-contained presentation and treat warnings about missing images as failures to investigate:
+10. Run markdownlint on all changed Markdown files and require zero violations. Fix violations instead of disabling rules unless a narrowly scoped suppression is necessary and documented.
+11. Export the self-contained presentation and treat warnings about missing images as failures to investigate:
 
    ```bash
    uv run python setup/export_presentation.py
    ```
 
-7. Run the SEO pass when public website content changed. Parse the inline JSON-LD block and `docs/sitemap.xml`, then verify that structured-data entries and visible cards stay synchronized.
-8. Preview the staged website when website or deck content changed. Use `uv run python setup/serve_website.py` and review both the landing page and `/slide-deck.html`. Check desktop and narrow layouts when visual changes are material.
-9. Inspect the final diff after validation. Do not include generated artifacts such as `build/`, `_site/`, coverage files, or lint reports unless the repository intentionally tracks them.
+12. Run the SEO pass when public website content changed. Parse the inline JSON-LD block and `docs/sitemap.xml`, then verify that structured-data entries and visible cards stay synchronized.
+13. Preview the staged website when website or deck content changed. Use `uv run python setup/serve_website.py` and review both the landing page and `/slide-deck.html`. Check desktop and narrow layouts when visual changes are material.
+14. Inspect the final diff after validation. Do not include generated artifacts such as `build/`, `_site/`, coverage files, or lint reports unless the repository intentionally tracks them.
 
 When live Azure validation is relevant but not requested or not available, report the exact notebook scenario and supported infrastructure combinations that remain to be exercised. Do not substitute unit tests for live scenario evidence.
 
@@ -89,5 +100,6 @@ Return a concise publish-readiness report with:
 
 - **Sample**: folder name, canonical display name, and supported infrastructures.
 - **Updated**: source files changed during the publishing pass.
-- **Validated**: commands run and their pass or fail results, including SEO source checks when website content changed.
-- **Remaining**: manual visual checks, live Azure scenarios, or unresolved blockers. State `None` when the sample is ready for review.
+- **Architecture**: notebook/helper ownership decision, shared-boundary reuse, and any remaining mechanics intentionally kept visible.
+- **Validated**: focused helper tests, coverage, combined checks, and SEO source checks when website content changed.
+- **Remaining**: manual visual checks, live Azure scenarios, or unresolved blockers. State `None` when the sample is ready for review.