ai: Implement dynamic host selection mechanism.

app.py

@@ -16,4 +16,4 @@ if __name__ == "__main__":
 
     # Call the 'launch' method on the 'app' object to start the user interface.
     # This typically opens the UI window or begins the event loop, making the application interactive.
-    app.queue(default_concurrency_limit=None).launch(share=True, pwa=True)
+    app.queue().launch(pwa=True)

src/client/chat_handler.py

@@ -125,17 +125,28 @@ async def respond(
         return  # Exit function after handling deep search
 
     # For all other inputs that do not match special commands, use the jarvis function to generate a normal response
-    async for response in jarvis(
-        session_id=session_id,  # Session ID for conversation context
-        model=selected_model,  # Selected model for generation
-        history=new_history,  # Pass the conversation history
-        user_message=input,  # User input message
-        mode=mode,  # Use the mode determined by the thinking flag
-        files=files,  # Pass any attached files along with the message
-        temperature=temperature,  # temperature parameter
-        top_k=top_k,  # top_k parameter
-        min_p=min_p,  # min_p parameter
-        top_p=top_p,  # top_p parameter
-        repetition_penalty=repetition_penalty  # repetition_penalty parameter
-    ):
-        yield response  # Yield each chunk of the response as it is generated by the AI model
+    try:
+        async for response in jarvis(
+            session_id=session_id,  # Session ID for conversation context
+            model=selected_model,  # Selected model for generation
+            history=new_history,  # Pass the conversation history
+            user_message=input,  # User input message
+            mode=mode,  # Use the mode determined by the thinking flag
+            files=files,  # Pass any attached files along with the message
+            temperature=temperature,  # temperature parameter
+            top_k=top_k,  # top_k parameter
+            min_p=min_p,  # min_p parameter
+            top_p=top_p,  # top_p parameter
+            repetition_penalty=repetition_penalty  # repetition_penalty parameter
+        ):
+            yield response  # Yield each chunk of the response as it is generated by the AI model
+
+    # If all servers have been tried and failed, show the error message
+    except RuntimeError as e:
+        # Inform user of service unavailability
+        yield [{
+            "role": "assistant",  # Specify the sender of this message
+            "content": "The server is currently busy. Please wait a moment or try again later"
+                       # Provide a clear, user-friendly message explaining
+        }]
+        return # End the function after exhausting all servers

src/client/responses/audio.py

@@ -84,7 +84,10 @@ async def audio_integration(
                     "content": (
                         "Audio generation failed for the user's request. The user tried to generate audio with the instruction: '"
                         + audio_instruction + "'\n\n\n"
-                        "Please explain to the user that audio generation failed and suggest they wait 15 seconds before trying again.\n"
+                        "Please explain to the user that the audio generation has failed.\n"
+                        "Also, explain all possible reasons why it might have failed.\n"
+                        "Additionally, advise the user not to include, input, or attach any sensitive content, "
+                        "as this may also cause the audio generation process to fail.\n\n"
                         "Be helpful and empathetic in your response.\n\n\n"
                         "Use the same language as the previous user input or user request.\n"
                         "For example, if the previous user input or user request is in Indonesian, explain in Indonesian.\n"

src/client/responses/image.py

@@ -84,7 +84,10 @@ async def image_integration(
                     "content": (
                         "Image generation failed for the user's request. The user tried to generate an image with the instruction: '"
                         + generate_image_instruction + "'\n\n\n"
-                        "Please explain to the user that image generation failed and suggest they wait 15 seconds before trying again.\n"
+                        "Please explain to the user that the image generation has failed.\n"
+                        "Also, explain all possible reasons why it might have failed.\n"
+                        "Additionally, advise the user not to include, input, or attach any sensitive content, "
+                        "as this may also cause the image generation process to fail.\n\n"
                         "Be helpful and empathetic in your response.\n\n\n"
                         "Use the same language as the previous user input or user request.\n"
                         "For example, if the previous user input or user request is in Indonesian, explain in Indonesian.\n"

src/core/server.py

@@ -91,7 +91,14 @@ async def jarvis(
 
         # Attempt to stream the response using the primary HTTP transport method (httpx)
         try:
+            # Iterate over each chunk of data yielded by the asynchronous httpx_transport function
             async for chunk in httpx_transport(host, headers, payload, mode):  # Stream response chunks asynchronously
+                # Skip any None chunks to prevent errors
+                if chunk is None:
+                    continue  # Skip this iteration and wait for the next chunk without processing
+                # If the chunk is a dictionary but does not have a "content" key
+                if isinstance(chunk, dict) and "content" not in chunk:
+                    chunk["content"] = ""  # Add an empty "content" key to maintain a consistent data structure for downstream processing
                 yield chunk  # Yield each chunk to the caller as it arrives for real-time processing
             return  # Exit the function if streaming completes successfully without errors
 
@@ -108,7 +115,14 @@ async def jarvis(
 
         # If the primary transport fails, attempt to stream response using fallback transport (aiohttp)
         try:
+            # Asynchronously iterate over chunks yielded by aiohttp_transport
             async for chunk in aiohttp_transport(host, headers, payload, mode):  # Use fallback streaming method
+                # Skip any None chunks to prevent errors
+                if chunk is None:
+                    continue  # Skip this iteration and wait for the next chunk without processing
+                # If the chunk is a dictionary but does not have a "content" key
+                if isinstance(chunk, dict) and "content" not in chunk:
+                    chunk["content"] = ""  # Add an empty "content" key to maintain a consistent data structure for downstream processing
                 yield chunk  # Yield streamed chunks to caller as they arrive
             return  # Exit if fallback transport succeeds
 
@@ -123,6 +137,5 @@ async def jarvis(
         except Exception:  # Catch generic exceptions to avoid crashing
             mark(server)  # Mark fallback server as failed
 
-    # If all servers have been tried and failed, show the error message
-    yield {"role": "assistant", "content": "The server is currently busy. Please wait a moment or try again later"}  # Inform user of service unavailability
-    return  # End the function after exhausting all servers
+    # If all servers have been tried and failed, raise an exception
+    raise RuntimeError()  # End the function after exhausting all servers

src/tools/audio.py

@@ -3,128 +3,91 @@
 # SPDX-License-Identifier: Apache-2.0
 #
 
-import asyncio  # Import asyncio to enable asynchronous programming, including async/await syntax and event loop management
-import httpx  # Import httpx library to perform asynchronous HTTP requests with advanced features like connection pooling and timeout control
-import aiohttp  # Import aiohttp library to provide an alternative asynchronous HTTP client for flexible request handling
-from urllib.parse import quote  # Import quote function to safely encode strings for URL usage, escaping special characters
-from src.utils.ip_generator import generate_ip  # Import a custom utility function to generate random IP addresses
-from config import auth  # Import authentication credentials or configuration from the config module (not used directly here but imported for completeness)
-from src.utils.tools import initialize_tools  # Import utility function to initialize and retrieve service endpoints or tool URLs
+import aiohttp  # Import aiohttp library to handle asynchronous HTTP requests and responses
+from urllib.parse import quote  # Import quote function to safely encode URL query parameters
+from src.utils.ip_generator import generate_ip  # Import custom utility to generate random IP addresses for request headers
+from src.utils.tools import initialize_tools  # Import initialize_tools function to set up necessary API tools and retrieve tokens
 
-# Define a class named AudioGeneration to encapsulate functionalities related to generating audio content
+# Define a class to handle audio generation tasks asynchronously
 class AudioGeneration:
-    # This class provides methods to create audio files based on text instructions and voice parameters
-
     """
-    This class provides methods to generate audio files from text instructions asynchronously.
-    It supports retrying requests until successful audio generation is confirmed.
+    This class provides functionality to generate audio content based on textual instructions asynchronously.
+    It encapsulates all necessary steps including preparing the request, encoding parameters, initializing tools,
+    making HTTP requests to the audio generation service, and handling the response.
+    
+    The design leverages asynchronous programming to efficiently manage network I/O without blocking the main thread.
+    It uses external utilities for IP generation to simulate diverse client requests and for tool initialization to
+    obtain API endpoints and authorization tokens securely.
+    
+    This class is intended for integration in larger applications requiring dynamic audio content creation from text,
+    supporting scalability and responsiveness in asynchronous environments.
     """
-
-    @staticmethod  # This method does not depend on class instance state and can be called directly on the class
-    async def create_audio(generate_audio_instruction: str, voice: str = "echo") -> str:
+    @staticmethod  # Decorator indicating this method does not depend on instance state
+    # Asynchronous method to create an audio based on given instructions and parameters
+    async def create_audio(generate_audio_instruction: str) -> str:
         """
-        Asynchronously generate an audio file URL by sending a request to an audio generation service.
-        The method continuously retries until it receives a successful HTTP 200 response with audio content.
-
+        Asynchronously generates an audio URL from a given textual instruction describing the desired audio content.
+        
+        This method performs the following steps:
+        - Encodes the input text to ensure it is safe for URL transmission
+        - Initializes necessary tools and retrieves the audio generation endpoint and authorization token
+        - Constructs the request URL and query parameters specifying the audio model and voice characteristics
+        - Sets up HTTP headers including authorization and IP address to simulate client diversity
+        - Opens an asynchronous HTTP session and sends a GET request to the audio generation service
+        - Checks the response status and content type to verify successful audio generation
+        - Returns the URL of the generated audio if successful, otherwise raises an exception
+        
+        The method is designed to be non-blocking and suitable for use in asynchronous workflows.
+        
         Args:
-            generate_audio_instruction (str): The text instruction or content to convert into audio.
-            voice (str, optional): The voice style or effect to apply on the generated audio. Defaults to "echo".
-
+            generate_audio_instruction (str): A textual description or instruction for the audio to be generated
+        
         Returns:
-            str: The URL of the generated audio file upon successful retrieval.
-
+            str: The URL pointing to the generated audio resource
+        
         Raises:
-            Exception: Currently, the method retries indefinitely and does not raise exceptions on failure.
+            Exception: If the HTTP response indicates failure or the content is not audio
         """
-        # Encode the text instruction to make it safe for URL path inclusion by escaping special characters
+        # Encode the textual instruction to be safely included in a URL path segment
         generate_audio_instruct = quote(generate_audio_instruction)
-
-        # Initialize tools and extract the audio generation service endpoint (third element in the returned tuple)
+        
+        # Initialize external tools and retrieve the audio generation endpoint and authorization token
         _, _, audio_tool, poll_token = initialize_tools()
-
-        # Construct the full URL by appending the encoded instruction to the base audio tool URL
+        
+        # Construct the full URL by appending the encoded instruction to the audio tool base URL
         url = f"{audio_tool}/{generate_audio_instruct}"
-
-        # Define query parameters specifying the audio generation model and voice effect
+        
+        # Define query parameters specifying the audio generation model and voice style to be used
         params = {
-            "model": "openai-audio",  # Specify the model used by the audio generation service
-            "voice": voice            # Specify the voice style or effect for the generated audio
+            "model": "openai-audio",  # Specify the audio generation model identifier
+            "voice": "echo"  # Specify the voice style or effect to apply to the generated audio
         }
 
-        # Create an aiohttp asynchronous HTTP client session with no timeout to allow long-running requests
-        async with aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=None)) as session:
-            # Enter an infinite loop to retry the request until success criteria are met
-            while True:
-                # Generate a random IP address to spoof the client's origin in the request headers
-                headers = {
-                    "Authorization": f"Bearer {poll_token}",  # Pollinations AI API Token
-                    "X-Forwarded-For": generate_ip()  # Set the X-Forwarded-For header to a random IP address
-                }
-
-                try:
-                    # Perform an asynchronous GET request to the audio generation service with URL, parameters, and headers
-                    async with session.get(url, params=params, headers=headers) as resp:
-                        # Check if the response status code is 200 (OK) and content type indicates MPEG audio stream
-                        content_type = resp.headers.get('Content-Type', '')
-                        if resp.status == 200 and 'audio/mpeg' in content_type:
-                            # Return the final URL of the generated audio resource as a string
-                            return str(resp.url)
-                        else:
-                            # If the response is not successful or content type is unexpected, wait before retrying
-                            await asyncio.sleep(15)  # Pause for 15 seconds to avoid overwhelming the server
-                except aiohttp.ClientError:
-                    # Catch network-related errors such as connection issues and wait before retrying
-                    await asyncio.sleep(15)  # Pause for 15 seconds before retrying after an exception
-
-    @staticmethod  # Provide an alternative implementation using httpx for flexibility or fallback
-    async def create_audio_httpx(generate_audio_instruction: str, voice: str = "echo") -> str:
-        """
-        Alternative asynchronous method to generate audio using httpx client.
-        This method also retries indefinitely until a successful response with audio content is received.
-
-        Args:
-            generate_audio_instruction (str): The text instruction to convert into audio.
-            voice (str, optional): Voice style or effect. Defaults to "echo".
-
-        Returns:
-            str: URL of the generated audio file.
-        """
-        # Encode instruction for safe URL usage
-        generate_audio_instruct = quote(generate_audio_instruction)
-
-        # Initialize tools and get audio generation endpoint
-        _, _, audio_tool, poll_token = initialize_tools()
-
-        # Construct request URL
-        url = f"{audio_tool}/{generate_audio_instruct}"
-
-        # Define query parameters for the request
-        params = {
-            "model": "openai-audio",
-            "voice": voice
+        # Prepare HTTP headers
+        headers = {
+            "Authorization": f"Bearer {poll_token}",  # Bearer token for API authorization
+            "X-Forwarded-For": generate_ip()  # Random IP address for request header to simulate client origin
         }
 
-        # Create an asynchronous HTTP client with no timeout limit
-        async with httpx.AsyncClient(timeout=None) as client:
-            # Retry loop until success
-            while True:
-              # Define HTTP headers for the request, including random IP address to simulate different client origins
-                headers = {
-                    "Authorization": f"Bearer {poll_token}",  # Pollinations AI API Token
-                    "X-Forwarded-For": generate_ip()  # Generate and set a random IP address for the request header
-                }
-
-                try:
-                    # Send GET request asynchronously
-                    resp = await client.get(url, params=params, headers=headers)
-
-                    # Check for successful response with audio content type
-                    if resp.status_code == 200 and 'audio/mpeg' in resp.headers.get('Content-Type', ''):
-                        # Return the URL of generated audio
-                        return str(resp.url)
-                    else:
-                        # Wait before retrying on failure
-                        await asyncio.sleep(15)
-                except httpx.RequestError:
-                    # Handle network errors and wait before retrying
-                    await asyncio.sleep(15)
+        # Create an asynchronous HTTP client session to manage connections efficiently
+        async with aiohttp.ClientSession() as session:
+            """
+            This block manages the lifecycle of the HTTP client session, ensuring proper connection handling,
+            resource cleanup, and support for asynchronous request execution to avoid blocking the event loop.
+            """
+            # Send an asynchronous GET request to the audio generation service with specified URL, parameters, and headers
+            async with session.get(
+                url,  # The fully constructed URL including the encoded instruction
+                params=params,  # Query parameters dictating model and voice options
+                headers=headers  # Authorization and client identity headers
+            ) as resp:
+                """
+                This context manages the HTTP response object, allowing inspection of status, headers,
+                and content in an asynchronous manner, suitable for streaming or large payloads.
+                """
+                # Verify that the response status is HTTP 200 OK and the content type indicates an audio MPEG file
+                if resp.status == 200 and 'audio/mpeg' in resp.headers.get('Content-Type', ''):
+                    # Return the final URL from which the generated audio can be accessed or downloaded
+                    return str(resp.url)
+                # If the response is not successful or content type is unexpected, raise an exception
+                raise Exception()

src/tools/image.py

@@ -3,128 +3,102 @@
 # SPDX-License-Identifier: Apache-2.0
 #
 
-import asyncio  # Import asyncio for asynchronous programming and managing event loops
-import httpx  # Import httpx for async HTTP requests with HTTP/1.1 and HTTP/2 support
-import aiohttp  # Import aiohttp for alternative async HTTP client capabilities
-from urllib.parse import quote  # Import quote to safely encode URL path components
-from typing import Optional  # Import Optional for type hinting parameters that may be None
+import aiohttp  # Import aiohttp library for asynchronous HTTP client functionality
+from urllib.parse import quote  # Import quote function to URL-encode query parameters safely
+from typing import Optional  # Import Optional type hint for parameters that may be None
 from src.utils.ip_generator import generate_ip  # Import custom utility to generate random IP addresses for request headers
-from src.utils.tools import initialize_tools  # Import utility to initialize and get tool endpoints
+from src.utils.tools import initialize_tools  # Import custom function to initialize necessary tools and tokens
 
-# Define a class named ImageGeneration to encapsulate functionalities related to generating image content
+# Define a class to handle image generation requests asynchronously
 class ImageGeneration:
-    # This class provides methods to create image files based on text instructions
-
     """
-    Class to handle asynchronous image generation requests to an external service.
-
-    Attributes:
-        FORMATS (dict): Maps image format names to (width, height) tuples.
-
-    Methods:
-        create_image: Async method to generate an image URL from a text prompt,
-                      retrying until successful, using httpx and aiohttp.
+    This class provides a comprehensive interface for generating images asynchronously via HTTP requests.
+    It supports multiple image formats with predefined dimensions and allows customization of generation parameters such as model type, seed, and enhancement options.
+    The class handles URL encoding, authentication headers, and IP generation to simulate diverse client requests.
+    It uses aiohttp for efficient asynchronous HTTP client sessions and manages error handling for invalid inputs and HTTP response failures.
     """
-
-    # Supported image formats with their dimensions (width, height)
+    # Dictionary mapping image format names to their corresponding width and height dimensions
     FORMATS = {
-        "default": (1024, 1024),
-        "square": (1024, 1024),
-        "landscape": (1024, 768),
-        "landscape_large": (1440, 1024),
-        "portrait": (768, 1024),
-        "portrait_large": (1024, 1440),
+        "default": (1024, 1024),  # Default square format with 1024x1024 pixels
+        "square": (1024, 1024),   # Square format identical to default size
+        "landscape": (1024, 768),  # Landscape format with width greater than height
+        "landscape_large": (1440, 1024),  # Larger landscape format for higher resolution images
+        "portrait": (768, 1024),  # Portrait format with height greater than width
+        "portrait_large": (1024, 1440),  # Larger portrait format for higher resolution images
     }
 
-    @staticmethod
+    @staticmethod  # Decorator indicating this method does not depend on instance state
+    # Asynchronous method to create an image based on given instructions and parameters
     async def create_image(
-        generate_image_instruction: str,  # Text description for the image to generate
-        image_format: str = "default",  # Format key from FORMATS dict
-        model: Optional[str] = "flux-realism",  # Model name for generation, default 'flux-realism'
-        seed: Optional[int] = None,  # Optional seed for reproducible randomness
-        nologo: bool = True,  # Whether to exclude logo watermark
-        private: bool = True,  # Whether the image should be private
-        enhance: bool = True,  # Whether to apply enhancement filters
+        generate_image_instruction: str,  # Text instruction describing the image to generate
+        image_format: str = "default",  # Desired image format key from FORMATS dictionary
+        model: Optional[str] = "flux",  # Optional model identifier controlling generation style or algorithm
+        seed: Optional[int] = None,  # Optional random seed to reproduce specific image outputs
+        nologo: bool = True,  # Flag to remove logo watermark from generated image
+        private: bool = True,  # Flag to mark image generation as private, restricting visibility
+        enhance: bool = True,  # Flag to apply enhancement filters to improve image quality
     ) -> str:
         """
-        Asynchronously generate an image URL by sending requests to the image generation service.
-        Uses httpx for initial requests and aiohttp as fallback, retrying indefinitely until success.
-
-        Args:
-            generate_image_instruction (str): Text prompt describing the desired image.
-            image_format (str): Key for image dimensions.
-            model (Optional[str]): Model to use for generation.
-            seed (Optional[int]): Seed for randomization control.
-            nologo (bool): Flag to exclude logo watermark.
-            private (bool): Flag to mark image as private.
-            enhance (bool): Flag to apply image enhancement.
-
-        Returns:
-            str: URL of the generated image on success.
-
-        Raises:
-            ValueError: If image_format is invalid.
+        This asynchronous method generates an image URL based on detailed instructions and customization options.
+        It validates the requested image format against supported formats, retrieves corresponding dimensions,
+        initializes necessary tools and authentication tokens, constructs the request URL with encoded parameters,
+        and performs an HTTP GET request asynchronously using aiohttp.
+        The method includes headers for authorization and IP address to simulate requests from different clients.
+        On successful response (HTTP 200), it returns the final URL of the generated image.
+        If the response status is not successful, it raise an exception.
         """
-        # Validate image format key
+        # Validate if the requested image format is supported, otherwise raise an error
         if image_format not in ImageGeneration.FORMATS:
-            raise ValueError("Invalid image format.")
+            raise ValueError("Invalid image format")
 
-        # Extract width and height for the requested format
+        # Retrieve width and height dimensions for the requested image format
         width, height = ImageGeneration.FORMATS[image_format]
 
-        # Initialize tools and get image generation service endpoint URL
-        _, image_tool, poll_token, _ = initialize_tools()
-
-        # Encode instruction safely for URL path usage
-        generate_image_instruct = quote(generate_image_instruction)
+        # Initialize external tools and retrieve the image tool URL and authorization token
+        _, image_tool, _, poll_token = initialize_tools()
 
-        # Construct the full URL endpoint for image generation
-        url = f"{image_tool}{generate_image_instruct}"
+        # Construct the base URL for the image generation request with URL-encoded instruction
+        url = f"{image_tool}{quote(generate_image_instruction)}"
 
-        # Prepare query parameters with image size, model, flags as strings
+        # Prepare query parameters dictionary for the HTTP request with all relevant options
         params = {
-            "width": width,
-            "height": height,
-            "model": model,
-            "nologo": "true" if nologo else "false",
-            "private": "true" if private else "false",
-            "enhance": "true" if enhance else "false",
+            "width": width,  # Image width in pixels
+            "height": height,  # Image height in pixels
+            "model": model,  # Model identifier string for image generation
+            "nologo": str(nologo).lower(),  # Convert boolean to lowercase string for query parameter
+            "private": str(private).lower(),  # Convert boolean to lowercase string for query parameter
+            "enhance": str(enhance).lower(),  # Convert boolean to lowercase string for query parameter
         }
 
-        # Add seed parameter if provided
+        # If a seed value is provided, add it to the query parameters to control randomness
         if seed is not None:
             params["seed"] = seed
 
-        # Prepare headers
+        # Prepare HTTP headers
         headers = {
-            "Authorization": f"Bearer {poll_token}",  # Pollinations AI API Token
+            "Authorization": f"Bearer {poll_token}",  # Bearer token for API authentication
             "X-Forwarded-For": generate_ip()  # Random IP address for request header to simulate client origin
         }
 
-        # Use httpx.AsyncClient with no timeout for initial requests
-        async with httpx.AsyncClient(timeout=None) as client:
-            while True:
-                try:
-                    # Send GET request to the image generation endpoint
-                    resp = await client.get(url, params=params, headers=headers)
-
-                    # If response is successful, return the final URL
-                    if resp.status_code == 200:
-                        return str(resp.url)
-                except httpx.HTTPError:
-                    # On httpx errors, fallback to aiohttp for robustness
-                    pass
-
-                # Fallback retry with aiohttp client
-                async with aiohttp.ClientSession() as session:
-                    try:
-                        async with session.get(url, params=params, headers=headers) as resp:
-                            if resp.status == 200:
-                                # Return the final URL (aiohttp does not provide direct URL property)
-                                return str(resp.url)
-                    except aiohttp.ClientError:
-                        # Ignore aiohttp errors and retry
-                        pass
-
-                # Wait 15 seconds before retrying to avoid overwhelming the server
-                await asyncio.sleep(15)
+        # Create an asynchronous HTTP client session to perform the GET request
+        async with aiohttp.ClientSession() as session:
+            """
+            This context manager ensures that the HTTP session is properly opened and closed asynchronously,
+            enabling efficient connection reuse and resource cleanup after the request completes.
+            """
+            # Perform the HTTP GET request asynchronously with the constructed URL, parameters, and headers
+            async with session.get(
+                url,  # The fully constructed URL including encoded instruction
+                params=params,  # Query parameters controlling image generation options
+                headers=headers  # Authorization and client identity headers
+            ) as resp:
+                """
+                This context manager handles the HTTP response asynchronously.
+                It waits for the server's response and manages the response lifecycle.
+                """
+                # Check if the HTTP response status indicates success
+                if resp.status == 200 and 'image/' in resp.headers.get('Content-Type', ''):
+                    # Return the final URL of the generated image as a string
+                    return str(resp.url)
+                # If the response is not successful or content type is unexpected, raise an exception
+                raise Exception()

src/ui/interface.py

@@ -3,159 +3,209 @@
 # SPDX-License-Identifier: Apache-2.0
 #
 
-import gradio as gr  # Import the Gradio library to build interactive web interfaces for machine learning applications
-from src.core.parameter import parameters  # Import the 'parameters' function from the core parameter module, which returns model parameter settings based on reasoning mode
-from src.client.chat_handler import respond  # Import the 'respond' function from the chat handler module, responsible for generating AI assistant responses
-from config import model, meta_tags  # Import 'model' dictionary containing available model precision options and their details, and 'meta_tags' containing HTML meta tag data
-
-# Gradio
+import logging  # Import the logging module to enable tracking of events, errors, and debugging information during program execution
+import warnings  # Import the warnings module to manage and control warning messages generated by the code or libraries
+import os  # Import the os module to interact with the operating system, such as file system operations and environment variables
+import sys  # Import the sys module to access system-specific parameters and functions, including command-line arguments and interpreter information
+import gradio as gr  # Import the Gradio library to build interactive web interfaces for machine learning applications, enabling easy deployment and testing
+from src.core.parameter import parameters  # Import the 'parameters' function from the core parameter module, which provides model parameter configurations based on the selected reasoning mode
+from src.client.chat_handler import respond  # Import the 'respond' function from the chat handler module, responsible for generating AI assistant responses to user inputs
+from config import model, meta_tags  # Import 'model' dictionary containing available model precision options and their details, and 'meta_tags' dictionary containing HTML meta tag information for web interface setup
+
+# Define the main user interface function for the Gradio application
 def ui():
     """
-    Constructs the Gradio user interface for the J.A.R.V.I.S. AI assistant application.
-
-    This function sets up a web app with a sidebar for configuring model parameters and a main chat interface
-    for user interaction. It returns the Gradio Blocks object representing the entire app.
+    This function constructs and configures the entire user interface for the AI assistant web application using the Gradio Blocks API.
+    The function is responsible for setting up logging and warning filters, suppressing unwanted output, and building a highly interactive sidebar for model configuration.
+    It provides users with a comprehensive set of controls to adjust model precision, reasoning mode, and advanced generation parameters such as temperature, top_k, min_p, top_p, and repetition penalty.
+    The sidebar also allows users to enable or disable additional features like image generation, audio generation, and deep web search, each with descriptive tooltips to guide user interaction.
+    The function dynamically updates parameter sliders based on the state of the reasoning checkbox, ensuring that the UI always reflects the current configuration.
+    The main chat interface is constructed with a set of example prompts to help users explore the assistant's capabilities, and all configuration states are passed as additional inputs to the response handler.
+    Output and error streams are redirected to prevent extraneous log messages from appearing in the web interface, creating a clean and focused user experience.
+    The function returns the fully constructed Gradio app object, ready to be launched or embedded as needed.
+    This approach ensures the application is robust, user-friendly, and highly customizable, making it suitable for both demonstration and production use
     """
-    # Create a Gradio Blocks container that fills the entire available height and width of the browser window
-    with gr.Blocks(fill_height=True, fill_width=True, head=meta_tags) as app:
-        # Create a sidebar panel on the left side, initially closed, to hold model configuration controls
+    # Suppress all warning messages globally to prevent them from displaying in the application output and confusing users
+    warnings.filterwarnings(
+        "ignore"  # Specify the action to ignore all warnings, ensuring a clean user interface free from warning clutter
+    )
+    # Set the warnings filter to ignore warnings by default, providing an additional layer of suppression for any warnings that might arise during runtime
+    warnings.simplefilter(
+        "ignore"  # Apply the ignore filter to all warning categories, further ensuring that no warnings are shown to users
+    )
+    # Configure the logging system to only display messages at the CRITICAL level or higher, effectively hiding informational, warning, and error logs from the application's output
+    logging.basicConfig(
+        level=logging.CRITICAL  # Set the logging threshold to CRITICAL, which is the highest severity level, to minimize log output
+    )
+    # Define a list of logger names associated with common web and async frameworks used in Gradio apps
+    logger_keywords = [
+        "uvicorn",  # Uvicorn is an ASGI web server commonly used with FastAPI and Gradio
+        "fastapi",  # FastAPI is a modern web framework for building APIs with Python
+        "gradio",  # Gradio's own logger, which may emit internal messages
+        "httpx",  # HTTPX is an HTTP client for Python, often used for making web requests
+        "aiohttp",  # Aiohttp is an asynchronous HTTP client and server library
+        "asyncio",  # Asyncio is Python's standard library for asynchronous programming
+        "starlette",  # Starlette is a lightweight ASGI framework used by FastAPI
+        "anyio",  # AnyIO is an asynchronous networking and concurrency library
+    ]
+    # Iterate through all registered loggers in the logging system to suppress their output if they match any of the specified keywords
+    for name, logger in logging.root.manager.loggerDict.items():
+        # Check if the logger's name contains any of the keywords from the list, indicating it is associated with a third-party library whose logs should be suppressed
+        if any(k in name for k in logger_keywords):
+            # Ensure the logger object is an instance of the Logger class before attempting to set its level
+            if isinstance(
+                logger,  # The logger object retrieved from the logger dictionary
+                logging.Logger  # The Logger class from the logging module
+            ):
+                # Set the logger's level to CRITICAL to prevent it from emitting lower-severity log messages during application execution
+                logger.setLevel(
+                    logging.CRITICAL  # Only allow critical errors to be logged, hiding all informational and warning messages
+                )
+    # Redirect the standard output stream to the null device, effectively silencing all print statements and unwanted output from third-party libraries
+    sys.stdout = open(
+        os.devnull, "w"  # Open the operating system's null device in write mode, discarding any data written to it
+    )
+    # Redirect the standard error stream to the null device, ensuring that error messages and tracebacks do not appear in the application's output
+    sys.stderr = open(
+        os.devnull, "w"  # Open the null device for error output, suppressing all error messages from being displayed to users
+    )
+    # Create the main Gradio Blocks application, which serves as the container for all UI components and layout
+    with gr.Blocks(
+        fill_height=True,  # Automatically adjust the block's height to fill the available vertical space in the browser window, ensuring a responsive design
+        fill_width=True,  # Automatically adjust the block's width to fill the available horizontal space, maximizing the use of screen real estate
+        head=meta_tags  # Inject custom meta tags into the HTML head section, allowing for SEO optimization
+    ) as app:
+        """
+        This code block initializes the main Gradio Blocks context, which acts as the root container for all user interface components in the application.
+        The fill_height and fill_width parameters ensure that the app dynamically resizes to fit the user's browser window, providing a seamless and visually appealing experience.
+        The head parameter inserts custom meta tags into the HTML head, enabling advanced customization such as setting the page title, description, favicon, or viewport settings.
+        All UI elements, including the sidebar configuration controls and the main chat interface, are defined within this context to ensure they are properly managed and rendered by Gradio.
+        The resulting 'app' object encapsulates the entire interactive application, making it easy to launch or embed as needed
+        """
+        # Begin the sidebar section, which slides in from the left and contains all model configuration controls. The sidebar starts in a closed state for a cleaner initial appearance
         with gr.Sidebar(open=False):
-            # Dropdown menu for selecting the model precision from the keys of the 'model' dictionary
+            # Create a dropdown menu that allows users to select the desired model precision from the available options defined in the 'model' dictionary
             model_precision = gr.Dropdown(
-                choices=list(model.keys()),  # List of available model precision options, e.g., "F16", "F32"
-                label="Model Precision",  # Label displayed above the dropdown menu
+                choices=list(model.keys()),  # Populate the dropdown with the keys from the model dictionary, such as "F16", "F32", or custom precision names
+                label="Model Precision",  # Display this label above the dropdown to clearly indicate its purpose to users
                 info=(
-                    # Tooltip explaining the tradeoff between speed and accuracy based on precision choice
+                    # Provide a tooltip that explains the impact of different precision settings on model speed and accuracy, helping users make informed choices
                     "The smaller the value, the faster the response but less accurate. "
                     "Conversely, the larger the value, the response is slower but more accurate."
                 ),
-                value="Q8_K_XL"  # Default selected precision value
+                value="Q8_K_XL"  # Set the default selected value to "Q8_K_XL", which represents a specific model precision configuration
             )
-
-            # Checkbox to enable or disable reasoning mode, which toggles the AI's "thinking" capability
+            # Add a checkbox that enables or disables reasoning mode, which affects how the AI assistant processes user queries and generates responses
             reasoning = gr.Checkbox(
-                label="Reasoning",  # Label shown next to the checkbox
-                info="Switching between thinking and non-thinking mode.",  # Tooltip describing the feature
-                value=True  # Default state is enabled (checked)
+                label="Reasoning",  # Show this label next to the checkbox to indicate its function
+                info="Switching between thinking and non-thinking mode.",  # Display a tooltip explaining that this option toggles the AI's ability to perform complex reasoning
+                value=True  # Set the default state to enabled, so the AI uses reasoning mode by default
             )
-
-            # Slider controlling the 'Temperature' parameter, affecting randomness in AI responses, initially non-interactive
+            # Create a slider for the 'Temperature' parameter, which controls the randomness of the AI's text generation. The slider is initially non-interactive and updated dynamically based on reasoning mode
             temperature = gr.Slider(
-                minimum=0.0,  # Minimum slider value
-                maximum=2.0,  # Maximum slider value
-                step=0.01,  # Increment step size
-                label="Temperature",  # Label for the slider
-                interactive=False  # User cannot directly adjust this slider, updated dynamically
+                minimum=0.0,  # Allow the temperature value to range from 0.0, representing deterministic output
+                maximum=2.0,  # Set the upper limit to 2.0, allowing for highly random and creative responses
+                step=0.01,  # Allow fine-grained adjustments in increments of 0.01 for precise control
+                label="Temperature",  # Label the slider so users know what parameter they are adjusting
+                interactive=False  # Disable direct user interaction, as the value is set programmatically when reasoning mode changes
             )
-
-            # Slider controlling the 'Top K' parameter, which limits the number of highest probability tokens considered, non-interactive initially
+            # Add a slider for the 'Top K' parameter, which limits the number of highest-probability tokens considered during text generation. This helps control output diversity
             top_k = gr.Slider(
-                minimum=0,
-                maximum=100,
-                step=1,
-                label="Top K",
-                interactive=False
+                minimum=0,  # Allow the top_k value to start at 0, which may disable the filter
+                maximum=100,  # Set the maximum to 100, providing a wide range for experimentation with model output diversity
+                step=1,  # Adjust the value in whole number increments for clarity
+                label="Top K",  # Label the slider for user understanding
+                interactive=False  # Make the slider non-interactive, as it is updated based on reasoning mode
             )
-
-            # Slider for 'Min P' parameter, representing minimum cumulative probability threshold, non-interactive initially
+            # Create a slider for the 'Min P' parameter, representing the minimum cumulative probability threshold for token selection during generation
             min_p = gr.Slider(
-                minimum=0.0,
-                maximum=1.0,
-                step=0.01,
-                label="Min P",
-                interactive=False
+                minimum=0.0,  # Allow the minimum probability to start at 0.0, including all tokens
+                maximum=1.0,  # Set the maximum to 1.0, representing the full probability mass
+                step=0.01,  # Use small increments for precise tuning
+                label="Min P",  # Label the slider to clarify its function
+                interactive=False  # Disable direct interaction, as it is controlled programmatically
             )
-
-            # Slider for 'Top P' parameter, controlling nucleus sampling probability, non-interactive initially
+            # Add a slider for the 'Top P' parameter, which controls nucleus sampling by limiting the cumulative probability of selected tokens
             top_p = gr.Slider(
-                minimum=0.0,
-                maximum=1.0,
-                step=0.01,
-                label="Top P",
-                interactive=False
+                minimum=0.0,  # Allow the top_p value to start at 0.0, which may restrict output to only the most probable token
+                maximum=1.0,  # Set the upper limit to 1.0, including all tokens in the sampling pool
+                step=0.01,  # Enable fine adjustments for optimal output control
+                label="Top P",  # Label the slider accordingly
+                interactive=False  # Make the slider non-interactive, as it is set based on reasoning mode
             )
-
-            # Slider for 'Repetition Penalty' parameter to reduce repetitive text generation, non-interactive initially
+            # Create a slider for the 'Repetition Penalty' parameter, which discourages the model from generating repetitive text by penalizing repeated tokens
             repetition_penalty = gr.Slider(
-                minimum=0.1,
-                maximum=2.0,
-                step=0.01,
-                label="Repetition Penalty",
-                interactive=False
+                minimum=0.1,  # Set the minimum penalty to 0.1, allowing for low but non-zero penalties
+                maximum=2.0,  # Allow penalties up to 2.0, strongly discouraging repetition
+                step=0.01,  # Use small increments for precise adjustment
+                label="Repetition Penalty",  # Label the slider for clarity
+                interactive=False  # Make the slider non-interactive, as it is updated programmatically
             )
-
-            # Define a function to update the model parameter sliders based on the reasoning checkbox state
+            # Define a function to update all parameter sliders when the reasoning checkbox is toggled by the user
             def update_parameters(switching):
                 """
-                Retrieve updated model parameter values based on reasoning mode.
-
-                Args:
-                    switching (bool): Current state of the reasoning checkbox.
-
-                Returns:
-                    tuple: Updated values for temperature, top_k, min_p, top_p, and repetition_penalty sliders.
+                This function is triggered whenever the user changes the state of the reasoning checkbox in the sidebar.
+                It calls the 'parameters' function, passing the new reasoning state, to retrieve a tuple of updated values for temperature, top_k, min_p, top_p, and repetition penalty.
+                The returned values are then used to update the corresponding sliders in the sidebar, ensuring that the UI always reflects the current configuration for the selected reasoning mode.
+                This dynamic updating mechanism provides immediate feedback to users and helps prevent configuration mismatches, improving the overall user experience and reliability of the application
                 """
-                # Call the 'parameters' function passing the reasoning state to get new parameter values
+                # Call the external 'parameters' function with the current reasoning state to get updated parameter values
                 return parameters(switching)
-
-            # Set up an event listener to update parameter sliders when the reasoning checkbox state changes
+            # Set up an event listener that calls 'update_parameters' whenever the reasoning checkbox state changes, updating all related sliders with new values
             reasoning.change(
-                fn=update_parameters,  # Function to call on checkbox state change
-                inputs=[reasoning],  # Input is the reasoning checkbox's current value
-                outputs=[temperature, top_k, min_p, top_p, repetition_penalty],  # Update these sliders with new values
-                api_name=False # Disable API
+                fn=update_parameters,  # Specify the function to call when the checkbox value changes
+                inputs=[reasoning],  # Pass the current value of the reasoning checkbox as input
+                outputs=[temperature, top_k, min_p, top_p, repetition_penalty],  # Update all relevant sliders with the new parameter values
+                api_name=False # Disable API exposure for this event, as it is only used internally by the UI
             )
-
-            # Initialize the parameter sliders with values corresponding to the default reasoning checkbox state
+            # Initialize all parameter sliders with values corresponding to the default state of the reasoning checkbox, ensuring the UI is consistent on first load
             values = parameters(reasoning.value)
             temperature.value, top_k.value, min_p.value, top_p.value, repetition_penalty.value = values
-
-            # Checkbox to enable or disable the image generation feature in the chat interface
+            # Add a checkbox to enable or disable image generation capabilities in the chat interface, allowing users to control access to this feature
             image_generation = gr.Checkbox(
-                label="Image Generation",  # Label displayed next to the checkbox
+                label="Image Generation",  # Display this label next to the checkbox for clarity
                 info=(
-                    # Tooltip explaining how to trigger image generation via chat commands
+                    # Provide a tooltip explaining how to trigger image generation using a special chat command
                     "Type <i><b>/image</b></i> followed by the instructions to start generating an image."
                 ),
-                value=True  # Enabled by default
+                value=True  # Enable image generation by default for user convenience
             )
-
-            # Checkbox to enable or disable the audio generation feature in the chat interface
+            # Add a checkbox to enable or disable audio generation in the chat, giving users control over this feature
             audio_generation = gr.Checkbox(
-                label="Audio Generation",
+                label="Audio Generation",  # Label the checkbox for clarity
                 info=(
+                    # Tooltip instructing users to use the /audio command to generate audio responses
                     "Type <i><b>/audio</b></i> followed by the instructions to start generating audio."
                 ),
-                value=True
+                value=True  # Enable audio generation by default
             )
-
-            # Checkbox to enable or disable the deep web search feature in the chat interface
+            # Add a checkbox to enable or disable deep web search functionality in the chat interface
             search_generation = gr.Checkbox(
-                label="Deep Search",
+                label="Deep Search",  # Label the checkbox to indicate its purpose
                 info=(
+                    # Tooltip explaining how to trigger deep search using the /dp command in chat
                     "Type <i><b>/dp</b></i> followed by the instructions to search the web."
                 ),
-                value=True
+                value=True  # Enable deep search by default
             )
-
-        # Create the main chat interface where users interact with the AI assistant
+        # Create the main chat interface where users can interact with the AI assistant, send messages, and receive responses
         gr.ChatInterface(
-            fn=respond,  # Function called to generate responses to user inputs
+            fn=respond,  # Specify the function that processes user input and generates assistant responses
+            # Provide a list of additional input components whose current values are passed to the respond function for each user message
             additional_inputs=[
-                # Pass the current states of all configuration controls as additional inputs to the respond function
-                model_precision,
-                temperature,
-                top_k,
-                min_p,
-                top_p,
-                repetition_penalty,
-                reasoning,
-                image_generation,
-                audio_generation,
-                search_generation
+                model_precision,  # Current selected model precision value from the dropdown
+                temperature,  # Current temperature value from the slider
+                top_k,  # Current top_k value from the slider
+                min_p,  # Current min_p value from the slider
+                top_p,  # Current top_p value from the slider
+                repetition_penalty,  # Current repetition penalty value from the slider
+                reasoning,  # Current state of the reasoning checkbox
+                image_generation,  # Whether image generation is enabled
+                audio_generation,  # Whether audio generation is enabled
+                search_generation  # Whether deep search is enabled
             ],
+            # Provide a list of example prompts that users can click to quickly test the assistant's capabilities and explore different features
             examples=[
-                # Predefined example inputs to help users quickly test the assistant's features
                 ["Please introduce yourself."],
                 ["/audio Could you explain what Artificial Intelligence (AI) is?"],
                 ["/audio What is Hugging Face?"],
@@ -170,20 +220,15 @@ def ui():
                 ["Please generate a highly complex code snippet on any topic."],
                 ["Explain about quantum computers."]
             ],
-            cache_examples=False,  # Disable caching of example outputs to always generate fresh responses
+            cache_examples=False,  # Disable caching of example outputs to ensure fresh responses are generated each time an example is selected
             chatbot=gr.Chatbot(
-                label="J.A.R.V.I.S.",   # Title label displayed above the chat window
-                show_copy_button=True,  # Show a button allowing users to copy chat messages
-                scale=1,  # Scale factor for the chatbot UI size
-                allow_tags=["think"] # Reasoning tag
+                label="J.A.R.V.I.S.",   # Set the title label above the chat window to "J.A.R.V.I.S." for branding and recognition
+                show_copy_button=True,  # Display a button that allows users to easily copy chat messages for later use
+                scale=1,  # Set the scale factor for the chatbot UI, keeping the default size
+                allow_tags=["think"]  # Allow the use of the "think" tag to indicate reasoning mode in chat
             ),
-            multimodal=False, # Disable support for multimodal inputs such as images or audio files
-            fill_height=True, # Duplicate from Blocks to Chat Interface
-            fill_width=True,  # Duplicate from Blocks to Chat Interface
-            head=meta_tags,   # Duplicate from Blocks to Chat Interface
-            show_progress="full", # Progress animation
-            api_name="api", # API endpoint
-            concurrency_limit=None  # Queuing
+            multimodal=False,  # Disable file upload capabilities, restricting the chat to text-only interactions
+            api_name="api",  # Expose the chat interface as an API endpoint named "api" for programmatic access if needed
         )
-    # Return the complete Gradio app object for launching or embedding
+    # Return the fully constructed Gradio app object, which can be launched as a standalone web application or embedded in other platforms
     return app

src/utils/session_mapping.py

@@ -3,74 +3,117 @@
 # SPDX-License-Identifier: Apache-2.0
 #
 
-import random  # Import random module to enable random selection from a list
-import gradio as gr  # Import the Gradio library to build interactive web interfaces for machine learning applications
-from datetime import datetime  # Import datetime class to work with current UTC time
-from typing import Dict, List  # Import type hints for dictionaries and lists (not explicitly used here but imported)
-from config import auth  # Import authentication configuration, likely a list of host dictionaries with credentials
-from src.utils.helper import busy, mark  # Import 'busy' dictionary and 'mark' function to track and update host busy status
+import random  # Import the random module to enable random selection of elements from a list, which helps in load balancing host assignments
+from datetime import datetime  # Import the datetime class to work with timestamps, particularly to check and compare current UTC time against host busy status
+from typing import Dict, List  # Import type hinting classes for dictionaries and lists to improve code readability and static analysis, though not explicitly used here
+from config import auth  # Import the 'auth' configuration, which is expected to be a list of host dictionaries containing credentials and identifiers for available hosts
+from src.utils.helper import busy, mark  # Import 'busy', a dictionary tracking host busy states with expiration timestamps, and 'mark', a function to update the busy status of hosts when assigned
 
-# Initialize a global dictionary to map session IDs to assigned hosts
-mapping = {}  # Store session_id to host assignment mapping to maintain consistent host allocation per session
+# Initialize a global dictionary named 'mapping' that will maintain a persistent association between session IDs and their assigned hosts
+mapping = {}  # This dictionary stores session_id keys mapped to host dictionaries, ensuring consistent host allocation for repeated requests within the same session
 
-# Define a function to get an available host for a given session, optionally excluding certain hosts
+# Define a function to get an available hosts for a given session
 def get_host(session_id: str, exclude_hosts: List[str] = None) -> dict:
     """
-    Retrieve or assign a host for the given session ID.
+    Obtain a host for the specified session ID, guaranteeing that the function never raises exceptions or returns None.
+    This function implements a robust mechanism to ensure a host is always returned by dynamically excluding busy or failed hosts,
+    and retrying until a suitable host becomes available.
 
     Args:
-        session_id (str): A unique identifier for the current session.
+        session_id (str): A unique string identifier representing the current user or process session requesting a host.
+        exclude_hosts (List[str], optional): An optional list of host identifiers to be excluded from selection, useful for avoiding problematic or previously failed hosts. Defaults to None.
 
     Returns:
-        dict: The selected host dictionary from the auth configuration.
+        dict: A dictionary representing the selected host from the 'auth' configuration, including its credentials and identifier.
 
-    Raises:
-        Exception: If no available hosts are found to assign.
+    Detailed Explanation:
+        The function first checks if the session already has an assigned host in the 'mapping' dictionary. If so, it verifies whether
+        the assigned host is neither excluded nor currently busy. If the assigned host is available, it refreshes its busy status to
+        extend its reservation and returns it immediately, ensuring session affinity.
 
-    Explanation:
-        Retrieve an available host for the specified session ID, ensuring excluded hosts are not assigned.
-        This function maintains a mapping of session IDs to hosts to provide consistent host assignment.
-        It filters out busy hosts and those explicitly excluded, then randomly selects an available host.
-        If no hosts are available, it raises an exception.
-    """
-
-    # If no list of hosts to exclude is provided, initialize it as an empty list
-    if exclude_hosts is None:  # Check if exclude_hosts parameter was omitted or set to None
-        exclude_hosts = []  # Initialize exclude_hosts to an empty list to avoid errors during filtering
-
-    # Check if the session ID already has an assigned host in the mapping dictionary
-    if session_id in mapping:  # Verify if a host was previously assigned to this session
-        assigned_host = mapping[session_id]  # Retrieve the assigned host dictionary for this session
-        # If the assigned host is not in the list of hosts to exclude, return it immediately
-        if assigned_host["jarvis"] not in exclude_hosts:  # Ensure assigned host is allowed for this request
-            return assigned_host  # Return the cached host assignment for session consistency
-        else:
-            # If the assigned host is excluded, remove the mapping to allow reassignment
-            del mapping[session_id]  # Delete the existing session-host mapping to find a new host
-
-    # Get the current UTC time to compare against host busy status timestamps
-    now = datetime.utcnow()  # Capture current time to filter out hosts that are still busy
+        If the assigned host is excluded or busy, the mapping is deleted to allow reassignment. The function then filters the list of
+        all hosts from 'auth' to exclude busy hosts, explicitly excluded hosts, and hosts already tried in the current function call.
+        From the filtered list, it randomly selects a host to distribute load evenly.
 
-    # Create a list of hosts that are not currently busy and not in the exclude list
-    available_hosts = [
-        h for h in auth  # Iterate over all hosts defined in the authentication configuration
-        if h["jarvis"] not in busy or busy[h["jarvis"]] <= now  # Include hosts not busy or whose busy time has expired
-        if h["jarvis"] not in exclude_hosts  # Exclude hosts specified in the exclude_hosts list
-    ]
+        If no suitable hosts are found, the function updates the set of tried hosts to include all currently busy and excluded hosts,
+        and clears the exclude list to retry all hosts again. This loop continues indefinitely until a host becomes available,
+        ensuring that the function never fails or returns None.
 
-    # If no hosts are available after filtering, raise an exception to indicate resource exhaustion
-    if not available_hosts:  # Check if the filtered list of hosts is empty
-        raise gr.Error("The server is currently busy. Please wait a moment or try again later", duration=5, title="INFO")
-        # Inform user of service unavailability
-
-    # Randomly select one host from the list of available hosts to distribute load evenly
-    selected = random.choice(available_hosts)  # Choose a host at random to avoid bias in host selection
-
-    # Store the selected host in the mapping dictionary for future requests with the same session ID
-    mapping[session_id] = selected  # Cache the selected host to maintain session affinity
+        This design supports high availability and fault tolerance by dynamically adapting to host availability and avoiding deadlocks
+        or infinite retries on unavailable hosts.
+    """
 
-    # Mark the selected host as busy using the helper function to update its busy status
-    mark(selected["jarvis"])  # Update the busy dictionary to indicate this host is now in use
+    # Initialize exclude_hosts as an empty list if no value is provided to avoid errors during host filtering
+    if exclude_hosts is None:
+        exclude_hosts = []  # Assign an empty list to exclude_hosts to safely perform membership checks and list operations later
+
+    # Create a set to track hosts that have been attempted and found unsuitable during this invocation of the function
+    tried_hosts = set()  # Using a set for efficient membership testing and to prevent repeated attempts on the same hosts within this call
+
+    # Enter an infinite loop that will only exit when a valid host is found and returned, ensuring robustness and continuous operation
+    while True:
+        # Check if the current session ID already has a host assigned in the mapping dictionary
+        if session_id in mapping:
+            assigned_host = mapping[session_id]  # Retrieve the previously assigned host dictionary for this session to maintain session consistency
+
+            # Determine if the assigned host is not in the exclude list and is either not busy or its busy period has expired
+            if (
+                assigned_host["jarvis"] not in exclude_hosts  # Confirm the assigned host is not explicitly excluded for this request
+                and (
+                    assigned_host["jarvis"] not in busy  # Check if the host is not currently marked as busy
+                    or busy[assigned_host["jarvis"]] <= datetime.utcnow()  # Alternatively, check if the host's busy timestamp has expired, meaning it is free
+                )
+            ):
+                # Since the assigned host is available, update its busy timestamp to extend its reservation for this session
+                mark(assigned_host["jarvis"])  # Call the helper function to refresh the busy status, preventing other sessions from using it simultaneously
+                return assigned_host  # Return the assigned host dictionary immediately to maintain session affinity and reduce latency
+
+            else:
+                # If the assigned host is either excluded or currently busy, remove the mapping to allow reassignment of a new host
+                del mapping[session_id]  # Delete the session-to-host association to enable the selection of a different host in subsequent steps
+
+        # Capture the current UTC time once to use for filtering hosts based on their busy status
+        now = datetime.utcnow()  # Store the current time to compare against busy timestamps for all hosts
+
+        # Generate a list of hosts that are eligible for selection by applying multiple filters:
+        # 1. Hosts not currently busy or whose busy period has expired
+        # 2. Hosts not included in the exclude_hosts list provided by the caller
+        # 3. Hosts not already attempted in this function call to avoid redundant retries
+        available_hosts = [
+            h for h in auth  # Iterate over all hosts defined in the authentication configuration list
+            if h["jarvis"] not in busy or busy[h["jarvis"]] <= now  # Include only hosts that are free or whose busy reservation has expired
+            if h["jarvis"] not in exclude_hosts  # Exclude hosts explicitly marked to be avoided for this selection
+            if h["jarvis"] not in tried_hosts  # Exclude hosts that have already been tried and failed during this function call to prevent infinite loops
+        ]
+
+        # If there are any hosts available after filtering, proceed to select one randomly
+        if available_hosts:
+            selected = random.choice(available_hosts)  # Randomly pick one host from the available list to distribute load fairly among hosts
+
+            # Store the selected host in the global mapping dictionary to maintain session affinity for future requests with the same session ID
+            mapping[session_id] = selected  # Cache the selected host so subsequent calls with this session ID return the same host
+
+            # Mark the selected host as busy by updating its busy timestamp, indicating it is currently reserved for this session
+            mark(selected["jarvis"])  # Update the busy dictionary to reflect that this host is now occupied, preventing concurrent use
+
+            # Return the selected host dictionary to the caller, completing the host assignment process for the session
+            return selected
 
-    # Return the selected host dictionary to the caller for use in processing the session
-    return selected  # Provide the caller with the assigned host details
+        else:
+            # If no hosts are available that have not already been tried, update the tried_hosts set to include all hosts currently busy or excluded
+            # This prevents immediate reattempts on these hosts in the next iteration, allowing time for busy hosts to become free
+            tried_hosts.update(
+                h["jarvis"] for h in auth  # Iterate over all hosts in the auth list to identify those currently busy
+                if h["jarvis"] in busy and busy[h["jarvis"]] > now  # Add hosts whose busy timestamp is still in the future, indicating they are occupied
+            )
+            tried_hosts.update(exclude_hosts)  # Also add all explicitly excluded hosts to the tried_hosts set to avoid retrying them immediately
+
+            # Create a set of all host identifiers from the auth configuration to compare against tried_hosts
+            all_host_ids = {h["jarvis"] for h in auth}  # Extract all host IDs to check if all hosts have been attempted
+
+            # If the set of tried hosts now includes every host in the configuration, clear the tried_hosts set to reset the retry mechanism
+            if tried_hosts >= all_host_ids:
+                tried_hosts.clear()  # Clear the tried_hosts set to allow all hosts to be considered again, enabling retries after some time
+
+            # Clear the exclude_hosts list as well to allow all hosts to be eligible for selection in the next iteration
+            exclude_hosts.clear()  # Reset the exclude list so that no hosts are excluded in the upcoming retry cycle, maximizing availability

src/utils/tools.py

@@ -3,65 +3,85 @@
 # SPDX-License-Identifier: Apache-2.0
 #
 
-import random  # Import random module to enable random selection from a list
-import gradio as gr  # Import the Gradio library to build interactive web interfaces for machine learning applications
-from datetime import datetime  # Import datetime class to work with current UTC time
-from config import auth  # Import authentication configuration, likely a list of host dictionaries with credentials
-from src.utils.helper import busy, mark  # Import 'busy' dictionary and 'mark' function to track and update host busy status
+import random  # Import the random module to enable functions for random selection and shuffling, which are essential for distributing workload evenly across multiple hosts and avoiding selection bias
+from datetime import datetime, timedelta  # Import datetime and timedelta classes to handle precise time calculations, which are crucial for managing host availability windows and expiration of busy statuses
+from config import auth  # Import the 'auth' configuration list, which contains dictionaries representing hosts with their respective credentials, endpoints, and tokens necessary for tool integration
+from src.utils.helper import busy, mark  # Import 'busy', a dictionary tracking the busy state and expiration timestamps of hosts, and 'mark', a utility function to update this dictionary to indicate when a host has been assigned and for how long
 
+# Define a function to get available tools
 def initialize_tools():
     """
-    Initialize and select available tools (endpoints) from the configured hosts.
+    This function is designed to robustly and perpetually search for an available host from a predefined list of hosts, ensuring that the selected host is fully configured with all required service endpoints and tokens before returning.
 
-    Returns:
-        tuple: A tuple containing three elements:
-            - tool_setup (str): The endpoint or configuration for the main tool setup.
-            - image_tool (str): The endpoint URL for image generation services.
-            - audio_tool (str): The endpoint URL for audio generation services.
+    It operates in an infinite loop to guarantee that it never returns a None value or raises an exception, thereby providing a reliable mechanism for host selection even in dynamic environments where host availability fluctuates frequently.
 
-    Raises:
-        Exception: If no available hosts are found or if any required tool endpoint is missing.
+    The detailed workflow is as follows:
+    - Obtain the current UTC timestamp to accurately evaluate the expiration of hosts' busy periods.
+    - Filter the list of configured hosts to include only those that are either not currently marked as busy or whose busy period has elapsed, thus ensuring only eligible hosts are considered for assignment.
+    - If no hosts meet the availability criteria, identify and remove expired busy entries from the tracking dictionary to free up hosts and retry immediately.
+    - Randomly shuffle the filtered list of available hosts to prevent selection bias and promote equitable distribution of workload.
+    - Iterate through the shuffled hosts, verifying that each host possesses all critical configuration elements: the main tool setup endpoint, image generation endpoint, audio generation endpoint, and Pollinations AI API token.
+    - Upon finding a host with complete and valid configurations, mark it as busy for a fixed duration (one hour) to prevent immediate reassignment and potential conflicts.
+    - Return a tuple containing the four key elements from the selected host, enabling downstream components to utilize these endpoints and tokens for their operations.
+    - If no suitable host is found after checking all available hosts, perform a cleanup of expired busy statuses and continue the search without delay.
 
-    Explanation:
-        This function filters the list of hosts from 'auth' to find those not currently busy or whose busy period has expired.
-        It randomly selects one available host, marks it as busy for one hour,
-        and retrieves the required tool endpoints ('done', 'image', 'audio') from the selected host's configuration.
-        If any of these endpoints are missing, it raises an exception.
-        Finally, it returns the three tool endpoints as a tuple.
-    """
-    # Get the current UTC time for busy status comparison
-    now = datetime.utcnow()
+    This approach ensures continuous availability of a properly configured host, adapts dynamically to changing host states, and maintains system stability by preventing simultaneous conflicting assignments.
 
-    # Filter hosts that are either not marked busy or whose busy period has expired
-    available = [
-        item for item in auth
-        if item["jarvis"] not in busy or busy[item["jarvis"]] <= now
-    ]
+    Returns:
+        tuple: A four-element tuple consisting of:
+            - tool_setup (str): The endpoint or configuration string for the primary tool setup service.
+            - image_tool (str): The URL endpoint for the image generation service.
+            - audio_tool (str): The URL endpoint for the audio generation service.
+            - poll_token (str): The API token string required for authenticating with Pollinations AI services.
+    """
+    while True:  # Start an endless loop that only breaks when a fully valid and available host is successfully selected and returned
+        now = datetime.utcnow()  # Capture the current coordinated universal time to accurately compare against host busy expiration timestamps
 
-    # Raise an exception if no hosts are currently available
-    if not available:
-        raise gr.Error("The server is currently busy. Please wait a moment or try again later", duration=5, title="INFO")
-        # Inform user of service unavailability
+        # Create a filtered list of hosts that are eligible for assignment
+        # Eligibility criteria include hosts not currently marked as busy or those whose busy period has expired, thereby allowing their reuse
+        available = [
+            item for item in auth  # Iterate over each host configuration dictionary in the 'auth' list imported from the configuration module
+            if item["jarvis"] not in busy or busy[item["jarvis"]] <= now  # Include the host if it is not present in the busy dictionary or if its busy timestamp is earlier than or equal to the current time, indicating availability
+        ]
 
-    # Randomly select one host from the available list
-    selected = random.choice(available)
+        # Check if the filtered list of available hosts is empty, which means all hosts are currently busy with unexpired busy periods
+        if not available:
+            # Identify all hosts in the busy dictionary whose busy periods have expired by comparing their timestamps to the current time
+            expired_hosts = [host for host in busy if busy[host] <= now]  # Generate a list of host identifiers whose busy status has expired and are thus candidates for cleanup
+            for host in expired_hosts:  # Iterate over each expired host to perform cleanup operations
+                del busy[host]  # Remove the host's busy status entry from the dictionary, effectively marking it as available again for assignment
+            # After cleaning up expired busy statuses, continue the loop to reattempt host selection immediately, ensuring responsiveness and minimal delay in availability checks
+            continue
 
-    # Mark the selected host as busy for the next hour to prevent immediate reassignment
-    mark(selected["jarvis"])
+        # Randomize the order of the available hosts list to prevent any selection bias and promote fair workload distribution among hosts
+        random.shuffle(available)
 
-    # Retrieve the tool endpoints from the selected host's configuration dictionary
-    tool_setup = selected.get("done")  # Main tool setup endpoint or configuration
-    image_tool = selected.get("image")  # Image generation service endpoint
-    audio_tool = selected.get("audio")  # Audio generation service endpoint
-    poll_token = selected.get("pol")  # Pollinations AI API Token
+        # Iterate through each host in the shuffled list to find one that has all the required endpoints and tokens properly configured
+        for selected in available:
+            # Extract the main tool setup endpoint from the selected host's configuration dictionary using the key 'done'
+            tool_setup = selected.get("done")
+            # Extract the image generation service endpoint URL using the key 'image'
+            image_tool = selected.get("image")
+            # Extract the audio generation service endpoint URL using the key 'audio'
+            audio_tool = selected.get("audio")
+            # Extract the Pollinations AI API token string using the key 'pol'
+            poll_token = selected.get("pol")
 
-    # Verify that all required tool endpoints are present, raise exception if any is missing
-    if not tool_setup or not image_tool or not audio_tool or not poll_token:
-        raise gr.Error("The server is currently busy. Please wait a moment or try again later", duration=5, title="INFO")
-    # Inform user of service unavailability
+            # Verify that all four critical configuration values are present and non-empty, ensuring the host is fully capable of handling the required services
+            if tool_setup and image_tool and audio_tool and poll_token:
+                # Mark the selected host as busy for the next hour by invoking the 'mark' function with the host's unique identifier
+                # This prevents the same host from being assigned again immediately, allowing for load balancing and avoiding conflicts
+                mark(selected["jarvis"])
+                # Return a tuple containing all four endpoints and the token, signaling successful host selection and configuration retrieval
+                return tool_setup, image_tool, audio_tool, poll_token
+            # If any required endpoint or token is missing, skip this host and continue checking the next one in the list
 
-    # Return the three tool endpoints as a tuple
-    return tool_setup, image_tool, audio_tool, poll_token
+        # If none of the available hosts had all required endpoints and tokens, perform cleanup of expired busy statuses again before retrying
+        expired_hosts = [host for host in busy if busy[host] <= now]  # Identify hosts whose busy times have expired and are eligible to be freed up
+        for host in expired_hosts:
+            del busy[host]  # Remove expired busy entries to free up hosts for reassignment
+        # Continue the loop to retry host selection immediately, maintaining continuous operation without delay
 
-# Initialize the tools by selecting an available host and retrieving its endpoints
-tool_setup, image_tool, audio_tool, poll_token = initialize_tools()
+# Execute the host initialization process by calling the function to obtain an available host's endpoints and tokens
+tool_setup, image_tool, audio_tool, poll_token = initialize_tools()
+# This call blocks until a suitable host is found and returns the necessary configuration for downstream tool usage