Add configurable AI completion audio cues

application/single_app/config.py

@@ -95,7 +95,7 @@
 EXECUTOR_TYPE = 'thread'
 EXECUTOR_MAX_WORKERS = 30
 SESSION_TYPE = 'filesystem'
-VERSION = "0.250.102"
+VERSION = "0.250.103"
 IS_DEVELOPMENT = is_development_env_enabled()
 
 SESSION_COOKIE_SAMESITE = os.getenv('SESSION_COOKIE_SAMESITE', 'Lax')

application/single_app/functions_notifications.py

@@ -18,6 +18,7 @@
 from flask import current_app
 import logging
 from config import cosmos_notifications_container
+from functions_appinsights import log_event
 from functions_group import find_group_by_id
 from functions_debug import debug_print
 from functions_public_workspaces import find_public_workspace_by_id, get_user_public_workspaces
@@ -755,6 +756,42 @@
         return 0
 
 
+def get_recent_chat_response_notifications(user_id, limit=50):
+    """Return recent personal chat completion event identities for one user."""
+    try:
+        normalized_limit = max(1, min(int(limit or 50), 100))
+    except (TypeError, ValueError):
+        normalized_limit = 50
+
+    try:
+        notifications = list(cosmos_notifications_container.query_items(
+            query=(
+                f"SELECT TOP {normalized_limit} "
+                "c.id, c.created_at, c.link_context, c.metadata "
+                "FROM c WHERE c.user_id = @user_id "
+                "AND c.notification_type = @notification_type "
+                "ORDER BY c.created_at DESC"
+            ),
+            parameters=[
+                {"name": "@user_id", "value": user_id},
+                {"name": "@notification_type", "value": "chat_response_complete"},
+            ],
+            partition_key=user_id,
+        ))
+        return notifications
+    except Exception as e:
+        log_event(
+            "[Notifications] Failed to load recent chat completion events.",
+            extra={
+                "user_id": user_id,
+                "error": str(e),
+            },
+            level=logging.ERROR,
+            exceptionTraceback=True,
+        )
+        raise
+
+
 def get_unread_workflow_priority_notifications(user_id, limit=5):
     """Return the most recent unread workflow alert notifications for a user."""
     try:

application/single_app/functions_settings.py

@@ -30,6 +30,20 @@
 USER_SETTINGS_REQUEST_CACHE_ATTR = "simplechat_user_settings_request_cache"
 FONT_SIZE_PREFERENCES = ("xs", "s", "m", "l", "xl")
 DEFAULT_FONT_SIZE_PREFERENCE = "m"
+CHAT_COMPLETION_AUDIO_SOUND_IDS = (
+    "aurora",
+    "bell",
+    "bloom",
+    "chime",
+    "crystal",
+    "glimmer",
+    "marimba",
+    "pulse",
+    "spark",
+    "summit",
+)
+DEFAULT_CHAT_COMPLETION_AUDIO_SOUND = CHAT_COMPLETION_AUDIO_SOUND_IDS[0]
+DEFAULT_CHAT_COMPLETION_AUDIO_VOLUME = 5
 USER_UI_SETTINGS_KEYS = (
     "profileImage",
     "navLayout",
@@ -43,6 +57,10 @@
     "sidebarMenuState",
     LATEST_FEATURES_HIDDEN_VERSION_SETTING,
     "fontSizePreference",
+    "chatCompletionAudioEnabled",
+    "chatCompletionAudioMuted",
+    "chatCompletionAudioSound",
+    "chatCompletionAudioVolume",
 )
 ADMIN_SETTINGS_SECRET_REDACTED_VALUE = "***REDACTED***"
 ADMIN_SETTINGS_FORM_SECRET_FIELDS = (
@@ -141,6 +159,31 @@
     return DEFAULT_FONT_SIZE_PREFERENCE
 
 
+def normalize_chat_completion_audio_preferences(settings):
+    """Return validated completion-audio preferences with opt-in defaults."""
+    source = settings if isinstance(settings, dict) else {}
+    selected_sound = str(
+        source.get("chatCompletionAudioSound") or DEFAULT_CHAT_COMPLETION_AUDIO_SOUND
+    ).strip().lower()
+    if selected_sound not in CHAT_COMPLETION_AUDIO_SOUND_IDS:
+        selected_sound = DEFAULT_CHAT_COMPLETION_AUDIO_SOUND
+
+    try:
+        volume = int(source.get(
+            "chatCompletionAudioVolume",
+            DEFAULT_CHAT_COMPLETION_AUDIO_VOLUME,
+        ))
+    except (TypeError, ValueError):
+        volume = DEFAULT_CHAT_COMPLETION_AUDIO_VOLUME
+
+    return {
+        "chatCompletionAudioEnabled": source.get("chatCompletionAudioEnabled") is True,
+        "chatCompletionAudioMuted": source.get("chatCompletionAudioMuted") is True,
+        "chatCompletionAudioSound": selected_sound,
+        "chatCompletionAudioVolume": min(10, max(1, volume)),
+    }
+
+
 def _get_user_settings_request_cache():
     if not has_request_context():
         return None
@@ -183,6 +226,7 @@
     ui_settings["fontSizePreference"] = normalize_font_size_preference(
         settings.get("fontSizePreference")
     )
+    ui_settings.update(normalize_chat_completion_audio_preferences(settings))
     return ui_settings
 
 
@@ -1020,6 +1064,8 @@
         # Multimedia
         'enable_video_file_support': False,
         'enable_audio_file_support': False,
+        'enable_chat_completion_audio_cues': False,
+        'chat_completion_audio_cues_updated_at': None,
 
         # Metadata Extraction
         'enable_extract_meta_data': False,

application/single_app/route_backend_notifications.py

@@ -2,6 +2,7 @@
 
 from config import *
 from functions_authentication import *
+from functions_appinsights import log_event
 from functions_conversation_cache import bump_conversation_cache_version
 from functions_settings import *
 from functions_notifications import *
@@ -71,10 +72,19 @@
         try:
             user_id = get_current_user_id()
             count = get_unread_notification_count(user_id)
+            app_settings = get_settings()
+            completion_audio_enabled = bool(
+                app_settings.get("enable_chat_completion_audio_cues", False)
+            )
+            completion_audio_updated_at = app_settings.get(
+                "chat_completion_audio_cues_updated_at"
+            )
 
             return jsonify({
                 'success': True,
-                'count': count
+                'count': count,
+                'chat_completion_audio_enabled': completion_audio_enabled,
+                'chat_completion_audio_updated_at': completion_audio_updated_at,
             })
 
         except Exception as e:
@@ -84,6 +94,84 @@
                 'count': 0
             }), 500
 
+    @bp.route("/api/notifications/chat-completions", methods=["GET"])
+    @swagger_route(security=get_auth_security())
+    @login_required
+    @user_required
+    def api_get_chat_completion_notifications():
+        """Get recent personal chat completion event identities for audio cues."""
+        user_id = None
+        try:
+            user_id = get_current_user_id()
+            app_settings = get_settings()
+            completion_audio_enabled = bool(
+                app_settings.get("enable_chat_completion_audio_cues", False)
+            )
+            completion_audio_updated_at = app_settings.get(
+                "chat_completion_audio_cues_updated_at"
+            )
+            if not completion_audio_enabled:
+                return jsonify({
+                    "success": True,
+                    "enabled": False,
+                    "updated_at": completion_audio_updated_at,
+                    "notifications": [],
+                })
+            limit = request.args.get("limit", 50)
+            notifications = get_recent_chat_response_notifications(user_id, limit=limit)
+            return jsonify({
+                "success": True,
+                "enabled": True,
+                "updated_at": completion_audio_updated_at,
+                "notifications": notifications,
+            })
+        except Exception as e:
+            log_event(
+                "[Notifications] Chat completion event request failed.",
+                extra={
+                    "user_id": user_id,
+                    "error": str(e),
+                },
+                level=logging.ERROR,
+                exceptionTraceback=True,
+            )
+            return jsonify({
+                "success": False,
+                "notifications": [],
+                "error": "Failed to fetch chat completion events",
+            }), 500
+
+    @bp.route("/api/notifications/chat-completion-audio-status", methods=["GET"])
+    @swagger_route(security=get_auth_security())
+    @login_required
+    @user_required
+    def api_get_chat_completion_audio_status():
+        """Return the current server-authoritative completion audio gate."""
+        try:
+            app_settings = get_settings()
+            enabled = bool(
+                app_settings.get("enable_chat_completion_audio_cues", False)
+            )
+            return jsonify({
+                "success": True,
+                "enabled": enabled,
+                "updated_at": app_settings.get(
+                    "chat_completion_audio_cues_updated_at"
+                ),
+            })
+        except Exception as e:
+            log_event(
+                "[Notifications] Completion audio status request failed.",
+                extra={"error": str(e)},
+                level=logging.ERROR,
+                exceptionTraceback=True,
+            )
+            return jsonify({
+                "success": False,
+                "enabled": False,
+                "error": "Failed to load completion audio status",
+            }), 500
+
     @bp.route("/api/notifications/workflow-alerts", methods=["GET"])
     @swagger_route(security=get_auth_security())
     @login_required

application/single_app/route_backend_users.py

@@ -518,6 +518,9 @@ def user_settings():
                     'microphonePermissionPreference', 'microphonePermissionState',
                     # Text-to-speech settings
                     'ttsEnabled', 'ttsVoice', 'ttsSpeed', 'ttsAutoplay',
+                    # AI response completion audio settings
+                    'chatCompletionAudioEnabled', 'chatCompletionAudioMuted',
+                    'chatCompletionAudioSound', 'chatCompletionAudioVolume',
                     # Tutorial visibility settings
                     'showTutorialButtons',
                     # Desktop conversation notification settings
@@ -562,6 +565,36 @@ def user_settings():
                     if not isinstance(settings_to_update["conversationContentsDrawerEnabled"], bool):
                         return jsonify({"error": "Invalid conversation contents drawer preference"}), 400
 
+                for boolean_key in (
+                    "chatCompletionAudioEnabled",
+                    "chatCompletionAudioMuted",
+                ):
+                    if (
+                        boolean_key in settings_to_update
+                        and not isinstance(settings_to_update[boolean_key], bool)
+                    ):
+                        return jsonify({"error": f"Invalid {boolean_key} preference"}), 400
+
+                if "chatCompletionAudioSound" in settings_to_update:
+                    selected_sound = str(
+                        settings_to_update.get("chatCompletionAudioSound") or ""
+                    ).strip().lower()
+                    if selected_sound not in CHAT_COMPLETION_AUDIO_SOUND_IDS:
+                        return jsonify({"error": "Invalid completion audio sound"}), 400
+                    settings_to_update["chatCompletionAudioSound"] = selected_sound
+
+                if "chatCompletionAudioVolume" in settings_to_update:
+                    volume = settings_to_update.get("chatCompletionAudioVolume")
+                    if isinstance(volume, bool):
+                        return jsonify({"error": "Invalid completion audio volume"}), 400
+                    try:
+                        volume = int(volume)
+                    except (TypeError, ValueError):
+                        return jsonify({"error": "Invalid completion audio volume"}), 400
+                    if volume < 1 or volume > 10:
+                        return jsonify({"error": "Completion audio volume must be between 1 and 10"}), 400
+                    settings_to_update["chatCompletionAudioVolume"] = volume
+
                 if "desktopNotificationsEnabled" in settings_to_update:
                     if not isinstance(settings_to_update["desktopNotificationsEnabled"], bool):
                         return jsonify({"error": "Invalid desktop notification preference"}), 400

application/single_app/route_frontend_admin_settings.py

@@ -1104,6 +1104,14 @@ def parse_admin_int(raw_value, fallback_value, field_name="unknown", hard_defaul
             # ... (fetch all other fields using form_data.get) ...
             enable_video_file_support = form_data.get('enable_video_file_support') == 'on'
             enable_audio_file_support = form_data.get('enable_audio_file_support') == 'on'
+            enable_chat_completion_audio_cues = form_data.get('enable_chat_completion_audio_cues') == 'on'
+            chat_completion_audio_cues_updated_at = settings.get(
+                'chat_completion_audio_cues_updated_at'
+            )
+            if enable_chat_completion_audio_cues != bool(
+                settings.get('enable_chat_completion_audio_cues', False)
+            ):
+                chat_completion_audio_cues_updated_at = datetime.now(timezone.utc).isoformat()
             enable_extract_meta_data = form_data.get('enable_extract_meta_data') == 'on'
 
             # Vision settings
@@ -2689,6 +2697,8 @@ def is_valid_url(url):
                 'video_index_timeout': int(form_data.get('video_index_timeout', 600)),
 
                 # Audio file settings with Azure speech service
+                'enable_chat_completion_audio_cues': enable_chat_completion_audio_cues,
+                'chat_completion_audio_cues_updated_at': chat_completion_audio_cues_updated_at,
                 'speech_service_endpoint': form_data.get('speech_service_endpoint', '').strip(),
                 'speech_service_location': form_data.get('speech_service_location', '').strip(),
                 'speech_service_subscription_id': form_data.get('speech_service_subscription_id', '').strip(),

application/single_app/static/audio/completion-cues/LICENSE.txt

@@ -0,0 +1,6 @@
+SimpleChat Completion Cue Assets
+
+The ten WAV files in this directory were generated specifically for the
+SimpleChat project from synthesized sine waves and contain no third-party
+recordings or samples. They are distributed under the same license as the
+SimpleChat repository.

application/single_app/static/js/chat/chat-streaming.js

@@ -90,6 +90,19 @@ function markStreamingConversationReadIfActive(conversationId, contextLabel) {
     });
 }
 
+function notifySuccessfulStreamingCompletion(finalData) {
+    if (!window.simpleChatCompletionAudio?.handleCompletion) {
+        return;
+    }
+
+    window.simpleChatCompletionAudio.handleCompletion({
+        conversationId: finalData?.conversation_id,
+        messageId: finalData?.message_id,
+    }, {
+        refreshAdminGate: true,
+    });
+}
+
 function buildDefaultCancelEndpoint(conversationId) {
     const normalizedConversationId = String(conversationId || '').trim();
     if (!normalizedConversationId) {
@@ -1244,6 +1257,7 @@ function handleStreamError(messageId, partialContent, errorMessage, errorDetails
 
 function finalizeStreamingMessage(messageId, userMessageId, finalData, fallbackAgentInfo = null) {
     finalData = applyFallbackAgentIcon(finalData, fallbackAgentInfo);
+    notifySuccessfulStreamingCompletion(finalData);
     const messageElement = document.querySelector(`[data-message-id="${messageId}"]`);
     if (!messageElement) return;