diff --git a/docs/explanation/features/AI_VOICE_CONVERSATIONS_SETUP_GUIDE.md b/docs/explanation/features/AI_VOICE_CONVERSATIONS_SETUP_GUIDE.md deleted file mode 100644 index 155dddaf..00000000 --- a/docs/explanation/features/AI_VOICE_CONVERSATIONS_SETUP_GUIDE.md +++ /dev/null @@ -1,85 +0,0 @@ -# AI Voice Conversations Setup Guide - -Version implemented: **0.241.009** -Enhanced in version: **0.241.010** - -## Overview and Purpose - -This feature adds a dedicated Setup Guide modal to the Admin Settings AI Voice Conversations card. The guide gives admins an in-app reference for configuring Azure AI Speech for audio uploads, voice input, and voice responses without leaving the settings page. - -Dependencies: - -- Azure AI Speech -- Admin Settings Search & Extract tab -- Shared Speech configuration fields in the AI Voice Conversations card - -## Technical Specifications - -### Architecture Overview - -The feature follows the same UI pattern already used by the Azure AI Video Indexer setup guide: - -- A Setup Guide button is rendered in the AI Voice Conversations card header. -- A dedicated modal partial contains setup guidance, required field descriptions, and a snapshot of the current form state. -- Client-side modal update logic reads the current Speech settings just before the modal opens. - -### Configuration Options - -The guide explains the settings used by the shared Speech configuration section: - -- Speech Service Endpoint -- Speech Service Location -- Speech Service Locale -- Authentication Type -- Speech Service Key -- Speech Resource ID -- Speech Subscription ID -- Speech Resource Group -- Speech Resource Name - -### File Structure - -- `application/single_app/templates/admin_settings.html` -- `application/single_app/templates/_speech_service_info.html` -- `ui_tests/test_admin_multimedia_guidance.py` -- `functional_tests/test_multimedia_support_reorganization.py` - -## Usage Instructions - -### How to Open the Guide - -1. Go to Admin Settings. -2. Open the Search & Extract tab. -3. Find the AI Voice Conversations card. -4. Click **Setup Guide**. - -### What the Guide Covers - -1. The shared-resource model for audio uploads, voice input, and voice responses. -2. The difference between API key and managed-identity authentication. -3. A step-by-step custom-domain walkthrough for managed identity: **Networking** → **Firewalls and virtual networks** → **Generate Custom Domain Name** → verify on **Keys and Endpoint**. -4. Speech-specific RBAC role guidance. -5. When the Speech Resource ID is required and how the built-in helper fields can construct it. - -### Custom-Domain Walkthrough - -The guide now walks admins through the exact managed-identity endpoint setup flow in Azure: - -1. Open the Speech resource in Azure portal. -2. Go to **Resource Management** → **Networking**. -3. Open **Firewalls and virtual networks**. -4. Choose **Generate Custom Domain Name**. -5. Save a globally unique custom name. -6. Verify the resulting endpoint in **Keys and Endpoint** before copying it into Simple Chat. - -## Testing and Validation - -### Test Coverage - -- Functional test coverage verifies that the AI Voice setup guide modal is included in the admin settings template and that the Setup Guide trigger is present. -- UI test coverage verifies that the modal opens from the Admin Settings page and reflects the current shared Speech configuration values. - -### Known Limitations - -- The guide is informational. It does not provision Azure resources or assign roles automatically. -- The UI test requires an authenticated admin Playwright session to run end to end. \ No newline at end of file diff --git a/docs/explanation/fixes/GROUP_PROMPTS_ROLE_UI_NULL_GUARD_FIX.md b/docs/explanation/fixes/GROUP_PROMPTS_ROLE_UI_NULL_GUARD_FIX.md deleted file mode 100644 index f0a8019e..00000000 --- a/docs/explanation/fixes/GROUP_PROMPTS_ROLE_UI_NULL_GUARD_FIX.md +++ /dev/null @@ -1,46 +0,0 @@ -# Group Prompts Role UI Null Guard Fix - -Fixed/Implemented in version: **0.241.003** - -## Header Information - -Issue description: -The group workspace page could throw a client-side exception while refreshing active group state: `Cannot read properties of null (reading 'style')` from `updateGroupPromptsRoleUI()`. - -Root cause analysis: -The prompt role-toggle logic assumed `create-group-prompt-section` and `group-prompts-role-warning` always existed in the DOM and wrote directly to `.style.display` without checking for missing nodes. - -Version implemented: -`config.py` was updated to `VERSION = "0.241.003"` for this fix. - -## Technical Details - -Files modified: -- `application/single_app/templates/group_workspaces.html` -- `application/single_app/config.py` -- `ui_tests/test_group_workspace_prompt_role_ui_resilience.py` - -Code changes summary: -- Switched the prompt role warning and create button containers to Bootstrap `d-none` state classes instead of inline `display: none` styles. -- Updated `updateGroupPromptsRoleUI()` to tolerate missing prompt DOM nodes and toggle visibility via `classList` instead of unsafe `.style` access. -- Added an early return in `fetchGroupPrompts()` when the prompt table container is unavailable. -- Added a UI regression test that removes the prompt role UI containers before changing the active group and asserts that no page error is raised. - -Testing approach: -- Added a Playwright UI regression test covering group changes with missing prompt role containers. -- Targeted validation should include the new UI test file plus a syntax/error pass on the updated template and config version bump. - -Impact analysis: -The group workspace now keeps loading and switching groups even when prompt role UI fragments are omitted, customized, or temporarily unavailable. - -## Validation - -Test results: -The regression test is designed to fail on the old `.style` access and pass once the null-safe toggle logic is present. - -Before/after comparison: -- Before: group changes could throw an uncaught promise error from `updateGroupPromptsRoleUI()`. -- After: group changes skip missing prompt role nodes safely and continue updating the rest of the workspace. - -User experience improvements: -Users no longer see the prompt role UI exception interrupt the group workspace load flow when those prompt elements are missing. \ No newline at end of file diff --git a/docs/explanation/fixes/MEDIA_ENHANCED_CITATION_BADGE_FIX.md b/docs/explanation/fixes/MEDIA_ENHANCED_CITATION_BADGE_FIX.md deleted file mode 100644 index 01879805..00000000 --- a/docs/explanation/fixes/MEDIA_ENHANCED_CITATION_BADGE_FIX.md +++ /dev/null @@ -1,48 +0,0 @@ -# Media Enhanced Citation Badge Fix - -Fixed/Implemented in version: **0.241.007** - -## Issue Description - -Audio and video files uploaded while Enhanced Citations was enabled were stored in Azure Blob Storage and could open through the enhanced citation experience on the chat page, but the workspace document details panel still showed the citation mode as Standard. - -## Root Cause Analysis - -The workspace document list renders the citation badge from the persisted `enhanced_citations` field on the document metadata record. - -Audio and video processing uploaded originals to blob storage, but the metadata record was not updated to set `enhanced_citations` to `true`. - -At the same time, the chat-side enhanced citation metadata endpoint could still infer enhanced support from blob-backed document state, so chat behavior and workspace metadata drifted apart. - -## Technical Details - -Files modified: `application/single_app/functions_documents.py`, `application/single_app/route_enhanced_citations.py`, `application/single_app/config.py`, `functional_tests/test_media_enhanced_citations_metadata_flag.py` - -Code changes summary: - -- Added normalization helpers so blob-backed documents read back with `enhanced_citations=True` even when older records are missing that field. -- Updated `upload_to_blob()` to stamp `enhanced_citations=True` on the stored document metadata for new blob-backed uploads. -- Initialized new document metadata records with `enhanced_citations=False` so the field is always explicit. -- Updated the enhanced citation document metadata route to use the normalized per-document flag instead of inferring state from a derived blob path. - -Impact analysis: - -- Existing audio and video documents that already have persisted blob references now render the Enhanced badge in workspace details without requiring re-upload. -- New blob-backed uploads keep workspace metadata aligned with the chat enhanced citation experience. - -## Validation - -Test coverage: `functional_tests/test_media_enhanced_citations_metadata_flag.py` - -Test results: - -- Validates normalization of current and archived blob-backed documents to `enhanced_citations=True`. -- Validates that blob uploads stamp the document metadata with the enhanced citation flag. -- Validates that document list/detail reads and the enhanced citation metadata route use the normalized value. - -Before/after comparison: - -- Before: Blob-backed media could behave as enhanced in chat while still displaying Standard in workspace details. -- After: Workspace details and chat enhanced citation behavior use the same normalized document metadata state. - -Related config.py version update: `VERSION = "0.241.007"` \ No newline at end of file diff --git a/docs/explanation/fixes/TABULAR_EXHAUSTIVE_RESULT_SYNTHESIS_FIX.md b/docs/explanation/fixes/TABULAR_EXHAUSTIVE_RESULT_SYNTHESIS_FIX.md deleted file mode 100644 index 347a8cf6..00000000 --- a/docs/explanation/fixes/TABULAR_EXHAUSTIVE_RESULT_SYNTHESIS_FIX.md +++ /dev/null @@ -1,42 +0,0 @@ -# Tabular Exhaustive Result Synthesis Fix - -Fixed/Implemented in version: **0.241.006** - -## Issue Description - -For exhaustive tabular questions such as "list out all of the security controls," the tabular analysis workflow could successfully execute an analytical tool call that returned the full matching result set, but the inner synthesis step could still answer as though it only had workbook schema samples. - -## Root Cause Analysis - -The main tabular retry guardrails in [route_backend_chats.py](application/single_app/route_backend_chats.py) only treated this kind of bad synthesis as retry-worthy in entity-lookup mode. General analytical requests could therefore accept a response that claimed only sample rows or workbook metadata were available even after a successful `query_tabular_data` call had returned the full result set. - -## Technical Details - -### Files Modified - -- `application/single_app/route_backend_chats.py` -- `functional_tests/test_tabular_exhaustive_result_synthesis_fix.py` -- `application/single_app/config.py` - -### Code Changes Summary - -- Expanded the access-limited synthesis detector to catch responses that say the data only includes sample rows, workbook metadata, or not the full list. -- Added result-coverage helpers that distinguish between full and partial analytical result slices. -- Reused those coverage signals in the primary tabular analysis loop so successful analytical calls can trigger a retry for general analysis mode, not just entity lookup. -- Added prompt guidance telling the tabular synthesis model to treat `returned_rows == total_matches` and `returned_values == distinct_count` as full result availability. - -### Testing Approach - -- Added a regression test covering full-result exhaustive list retries. -- Added a regression test covering partial-result exhaustive list reruns. - -## Validation - -### Expected Improvement - -- Exhaustive list questions no longer stop at a synthesis response that wrongly claims only schema samples are available after successful analytical tool calls. -- When only a partial slice is returned, the workflow now has explicit retry guidance to rerun the relevant analytical call with a higher limit before answering. - -### Related Version Update - -- `application/single_app/config.py` updated to `0.241.006`. \ No newline at end of file diff --git a/docs/explanation/fixes/TABULAR_RESULT_COVERAGE_REDUNDANT_COMPARISON_FIX.md b/docs/explanation/fixes/TABULAR_RESULT_COVERAGE_REDUNDANT_COMPARISON_FIX.md deleted file mode 100644 index 4cdf10bc..00000000 --- a/docs/explanation/fixes/TABULAR_RESULT_COVERAGE_REDUNDANT_COMPARISON_FIX.md +++ /dev/null @@ -1,40 +0,0 @@ -# Tabular Result Coverage Redundant Comparison Fix - -Fixed/Implemented in version: **0.241.007** - -## Issue Description - -The tabular result coverage helper in `application/single_app/route_backend_chats.py` used complementary `elif` comparisons immediately after `>=` checks when determining whether returned rows or distinct values covered the full result set. - -## Root Cause Analysis - -`parse_tabular_result_count()` normalizes these metadata fields to non-negative integers or `None`, and the helper already guards against `None` before comparing. Under those preconditions, `returned_rows >= total_matches` and `returned_values >= distinct_count` fully partition the remaining numeric cases, so the follow-up `<` tests were redundant and triggered static-analysis noise. - -## Technical Details - -### Files Modified - -- `application/single_app/route_backend_chats.py` -- `functional_tests/test_tabular_exhaustive_result_synthesis_fix.py` -- `application/single_app/config.py` - -### Code Changes Summary - -- Replaced the redundant complementary `elif` comparisons with `else` branches in `get_tabular_result_coverage_summary()`. -- Added regression coverage for partial distinct-value result slices so the touched branch remains explicitly exercised. -- Updated the application version to `0.241.007`. - -### Testing Approach - -- Extended the existing tabular exhaustive-result synthesis functional test to verify partial distinct-value coverage is still detected. - -## Validation - -### Expected Improvement - -- CodeQL no longer reports the redundant comparison finding for the tabular result coverage helper. -- Runtime behavior remains unchanged for valid parsed numeric counts. - -### Related Version Update - -- `application/single_app/config.py` updated to `0.241.007`. \ No newline at end of file diff --git a/docs/explanation/fixes/v0.241.007/SPEECH_VIDEO_INDEXER_GUIDANCE_FIX.md b/docs/explanation/fixes/v0.241.007/SPEECH_VIDEO_INDEXER_GUIDANCE_FIX.md deleted file mode 100644 index 16ad4f07..00000000 --- a/docs/explanation/fixes/v0.241.007/SPEECH_VIDEO_INDEXER_GUIDANCE_FIX.md +++ /dev/null @@ -1,75 +0,0 @@ -# Speech And Video Indexer Guidance Fix - -Fixed in version: **0.241.007** - -## Overview - -This fix aligns the admin multimedia setup experience with the way Simple Chat actually authenticates to Azure Speech Service and Azure AI Video Indexer. - -The update removes stale Video Indexer API-key guidance, adds cloud-aware Video Indexer endpoint selection, and documents the additional Speech Resource ID required for managed-identity text-to-speech. - -## Issue Description - -Users were encountering conflicting instructions across the admin UI and documentation: - -- Video Indexer walkthrough steps still implied an API-key-style setup even though the runtime uses ARM plus managed identity. -- Video Indexer guidance mixed the managed identity used by the Video Indexer resource itself with the App Service managed identity used by Simple Chat. -- The shared Speech section implied that all Speech features used the same minimal managed-identity inputs, but text-to-speech also needs the Speech Resource ID. - -## Root Cause - -The UI, backend, and written guidance drifted over time. - -- The admin walkthrough still referenced legacy Video Indexer fields. -- The admin JavaScript only revealed the Speech configuration when audio uploads were enabled, not when speech-to-text input or text-to-speech were enabled. -- Text-to-speech still used a key-centric backend path while other Speech flows already supported managed identity. - -## Technical Details - -### Files Modified - -- `application/single_app/config.py` -- `application/single_app/functions_authentication.py` -- `application/single_app/functions_documents.py` -- `application/single_app/functions_settings.py` -- `application/single_app/route_backend_tts.py` -- `application/single_app/route_frontend_admin_settings.py` -- `application/single_app/static/js/admin/admin_settings.js` -- `application/single_app/templates/_video_indexer_info.html` -- `application/single_app/templates/admin_settings.html` -- `docs/admin_configuration.md` -- `docs/reference/admin_configuration.md` -- `docs/how-to/azure_speech_managed_identity_manul_setup.md` -- `docs/setup_instructions_special.md` -- `functional_tests/test_multimedia_support_reorganization.py` -- `functional_tests/test_video_indexer_dual_authentication_support.py` -- `ui_tests/test_admin_multimedia_guidance.py` - -### Code Changes Summary - -- Added `speech_service_resource_id` to admin settings and persistence. -- Added a shared Speech synthesis configuration helper so text-to-speech can use managed identity correctly. -- Updated the admin multimedia walkthrough to use Video Indexer cloud selection and ARM resource fields instead of a legacy API-key path. -- Updated admin JavaScript so the shared Speech section appears when any Speech feature is enabled. -- Added Video Indexer cloud selection, effective endpoint display, and clearer identity guidance in the admin UI and help modal. - -### Testing Approach - -- Updated source-inspection functional tests for the current multimedia UI. -- Updated the legacy Video Indexer functional test to validate the managed-identity-only flow. -- Added a Playwright admin UI regression test for the Video Indexer cloud selector and shared Speech managed-identity fields. - -## Validation - -### Before - -- Users could still find walkthrough and documentation references to Video Indexer API keys. -- The Speech settings panel could stay hidden when only speech-to-text input or text-to-speech was enabled. -- Managed-identity text-to-speech lacked the required Speech Resource ID guidance and backend support. - -### After - -- The admin UI consistently points users to managed identity for Video Indexer. -- Video Indexer cloud selection and endpoint behavior are explicit. -- Shared Speech guidance now explains the extra managed-identity requirement for voice responses. -- Functional and UI regression coverage now checks the updated configuration path. \ No newline at end of file diff --git a/docs/explanation/fixes/v0.241.008/SPEECH_RESOURCE_ID_BUILDER_FIX.md b/docs/explanation/fixes/v0.241.008/SPEECH_RESOURCE_ID_BUILDER_FIX.md deleted file mode 100644 index f7e8bef5..00000000 --- a/docs/explanation/fixes/v0.241.008/SPEECH_RESOURCE_ID_BUILDER_FIX.md +++ /dev/null @@ -1,48 +0,0 @@ -# Speech Resource ID Builder Fix - -Fixed in version: **0.241.008** - -## Overview - -This fix makes the managed-identity Speech configuration easier to complete by helping admins build the Azure Resource Manager Speech resource ID directly in the Admin Settings page. - -## Issue Description - -The Speech Resource ID is required for managed-identity text-to-speech, but it is not easy to locate in the Azure portal. Users had to either find the value manually in the resource properties page or use Azure CLI commands outside the app. - -## Root Cause - -The admin UI only exposed a single raw Speech Resource ID field. It did not provide any assistance for constructing the ARM path even though the required parts are predictable. - -## Technical Details - -### Files Modified - -- `application/single_app/config.py` -- `application/single_app/functions_settings.py` -- `application/single_app/route_frontend_admin_settings.py` -- `application/single_app/static/js/admin/admin_settings.js` -- `application/single_app/templates/admin_settings.html` -- `application/external_apps/databaseseeder/artifacts/admin_settings.json` -- `docs/how-to/azure_speech_managed_identity_manul_setup.md` -- `functional_tests/test_multimedia_support_reorganization.py` -- `ui_tests/test_admin_multimedia_guidance.py` - -### Code Changes Summary - -- Added optional helper fields for Speech Subscription ID, Speech Resource Group, and Speech Resource Name. -- Added client-side builder logic that assembles the Speech ARM resource ID in the format `/subscriptions//resourceGroups//providers/Microsoft.CognitiveServices/accounts/`. -- Added endpoint-based resource-name inference for common custom-domain Speech endpoints. -- Persisted the helper fields in admin settings and the seeded sample admin settings artifact. - -## Validation - -### Before - -- Admins had to find or type the full Speech Resource ID manually. -- The portal location for the Resource ID was easy to miss. - -### After - -- Admins can provide the subscription ID, resource group, and Speech resource name and let the UI build the full Resource ID. -- The built value is still editable, so manual overrides remain possible. \ No newline at end of file