webscout 8.2.8__py3-none-any.whl → 8.2.9__py3-none-any.whl

webscout/AIauto.py

@@ -14,13 +14,16 @@ import inspect
 
 def load_providers():
     """
-    Dynamically loads all Provider classes from the webscout.Provider package.
-
-    Identifies providers that require special authentication parameters like
-    'api_key', 'cookie_file', or 'cookie_path'.
-
+    Dynamically loads all Provider classes from the `webscout.Provider` package.
+    
+    This function iterates through the modules in the `webscout.Provider` package,
+    imports each module, and inspects its attributes to identify classes that
+    inherit from the `Provider` base class. It also identifies providers that
+    require special authentication parameters like 'api_key', 'cookie_file', or
+    'cookie_path'.
+    
     Returns:
-        tuple: A tuple containing:
+        tuple: A tuple containing two elements:
             - provider_map (dict): A dictionary mapping uppercase provider names to their classes.
             - api_key_providers (set): A set of uppercase provider names requiring special authentication.
     """
@@ -50,7 +53,10 @@ provider_map, api_key_providers = load_providers()
 
 class AUTO(Provider):
     """
-    An automatic provider that cycles through available free providers
+    An automatic provider that intelligently selects and utilizes an available
+    LLM provider from the webscout library.
+    
+    It cycles through available free providers
     until one successfully processes the request. Excludes providers
     requiring API keys or cookies by default.
     """
@@ -69,7 +75,10 @@ class AUTO(Provider):
         print_provider_info: bool = False,
     ):
         """
-        Initializes the AUTO provider.
+        Initializes the AUTO provider, setting up the parameters for provider selection and request handling.
+        
+        This constructor initializes the AUTO provider with various configuration options,
+        including conversation settings, request limits, and provider exclusions.
 
         Args:
             is_conversation (bool): Flag for conversational mode. Defaults to True.
@@ -102,14 +111,20 @@ class AUTO(Provider):
     @property
     def last_response(self) -> dict[str, Any]:
         """
-        Returns the last response dictionary from the successful provider.
+        Retrieves the last response dictionary from the successfully used provider.
+        
+        Returns:
+            dict[str, Any]: The last response dictionary, or an empty dictionary if no provider has been used yet.
         """
         return self.provider.last_response if self.provider else {}
 
     @property
     def conversation(self) -> object:
         """
-        Returns the conversation object from the successful provider.
+        Retrieves the conversation object from the successfully used provider.
+        
+        Returns:
+            object: The conversation object, or None if no provider has been used yet.
         """
         return self.provider.conversation if self.provider else None
 
@@ -122,8 +137,11 @@ class AUTO(Provider):
         conversationally: bool = False,
     ) -> Union[Dict, Generator]:
         """
-        Sends the prompt to providers, trying each available free provider
-        in a random order until one succeeds.
+        Sends the prompt to available providers, attempting to get a response from each until one succeeds.
+        
+        This method iterates through a shuffled list of available providers (excluding those requiring API keys or
+        specified in the exclusion list) and attempts to send the prompt to each provider until a successful response
+        is received.
 
         Args:
             prompt (str): The user's prompt.
@@ -187,7 +205,7 @@ class AUTO(Provider):
         conversationally: bool = False,
     ) -> Union[str, Generator[str, None, None]]: 
         """
-        Provides a simplified chat interface, returning the message string(s).
+        Provides a simplified chat interface, returning the message string or a generator of message strings.
 
         Args:
             prompt (str): The user's prompt.
@@ -218,7 +236,7 @@ class AUTO(Provider):
         Extracts the message text from the provider's response dictionary.
 
         Args:
-            response (dict): The response dictionary from the ask method.
+            response (dict): The response dictionary obtained from the `ask` method.
 
         Returns:
             str: The extracted message string.

webscout/AIbase.py

@@ -1,13 +1,37 @@
 from abc import ABC, abstractmethod
 from pathlib import Path
-from typing import AsyncGenerator, List, Union, Generator, Optional
+from typing import AsyncGenerator, Dict, List, Union, Generator, Optional
 from typing_extensions import TypeAlias
 
 # Type aliases for better readability
 Response: TypeAlias = dict[str, Union[str, bool, None]]
-ImageData: TypeAlias = Union[bytes, str, Generator[bytes, None, None]]
 AsyncImageData: TypeAlias = Union[bytes, str, AsyncGenerator[bytes, None]]
 
+class SearchResponse:
+    """A wrapper class for search API responses.
+    
+    This class automatically converts response objects to their text representation
+    when printed or converted to string.
+    
+    Attributes:
+        text (str): The text content of the response
+        
+    Example:
+        >>> response = SearchResponse("Hello, world!")
+        >>> print(response)
+        Hello, world!
+        >>> str(response)
+        'Hello, world!'
+    """
+    def __init__(self, text: str):
+        self.text = text
+    
+    def __str__(self):
+        return self.text
+    
+    def __repr__(self):
+        return self.text
+
 class AIProviderError(Exception):
     pass
 
@@ -213,48 +237,83 @@ class AsyncTTSProvider(ABC):
         async with aiofiles.open(audio_file, 'rb') as f:
             while chunk := await f.read(chunk_size):
                 yield chunk
-
-class ImageProvider(ABC):
-
-    @abstractmethod
-    def generate(self, prompt: str, amount: int = 1) -> List[bytes]:
-        raise NotImplementedError("Method needs to be implemented in subclass")
-
-    @abstractmethod
-    def save(
-        self,
-        response: List[bytes],
-        name: Optional[str] = None,
-        dir: Optional[Union[str, Path]] = None
-    ) -> List[str]:
-        raise NotImplementedError("Method needs to be implemented in subclass")
-
-class AsyncImageProvider(ABC):
-
+                
+class AISearch(ABC):
+    """Abstract base class for AI-powered search providers.
+    
+    This class defines the interface for AI search providers that can perform
+    web searches and return AI-generated responses based on search results.
+    
+    All search providers should inherit from this class and implement the
+    required methods.
+    """
+    
     @abstractmethod
-    async def generate(
+    def search(
         self,
         prompt: str,
-        amount: int = 1
-    ) -> Union[AsyncGenerator[bytes, None], List[bytes]]:
-        raise NotImplementedError("Method needs to be implemented in subclass")
-
-    @abstractmethod
-    async def save(
-        self,
-        response: Union[AsyncGenerator[bytes, None], List[bytes]],
-        name: Optional[str] = None,
-        dir: Optional[Union[str, Path]] = None
-    ) -> List[str]:
+        stream: bool = False,
+        raw: bool = False,
+    ) -> Union[SearchResponse, Generator[Union[Dict[str, str], SearchResponse], None, None]]:
+        """Search using the provider's API and get AI-generated responses.
+        
+        This method sends a search query to the provider and returns the AI-generated response.
+        It supports both streaming and non-streaming modes, as well as raw response format.
+        
+        Args:
+            prompt (str): The search query or prompt to send to the API.
+            stream (bool, optional): If True, yields response chunks as they arrive.
+                                   If False, returns complete response. Defaults to False.
+            raw (bool, optional): If True, returns raw response dictionaries.
+                                If False, returns SearchResponse objects that convert to text automatically.
+                                Defaults to False.
+        
+        Returns:
+            Union[SearchResponse, Generator[Union[Dict[str, str], SearchResponse], None, None]]: 
+                - If stream=False: Returns complete response as SearchResponse object
+                - If stream=True: Yields response chunks as either Dict or SearchResponse objects
+        
+        Raises:
+            APIConnectionError: If the API request fails
+        """
         raise NotImplementedError("Method needs to be implemented in subclass")
 
-class AISearch(ABC):
-
+class AsyncAISearch(ABC):
+    """Abstract base class for asynchronous AI-powered search providers.
+    
+    This class defines the interface for asynchronous AI search providers that can perform
+    web searches and return AI-generated responses based on search results.
+    
+    All asynchronous search providers should inherit from this class and implement the
+    required methods.
+    """
+    
     @abstractmethod
-    def search(
+    async def search(
         self,
         prompt: str,
         stream: bool = False,
         raw: bool = False,
-    ) -> Response:
-        raise NotImplementedError("Method needs to be implemented in subclass")
+    ) -> Union[SearchResponse, AsyncGenerator[Union[Dict[str, str], SearchResponse], None]]:
+        """Search using the provider's API and get AI-generated responses asynchronously.
+        
+        This method sends a search query to the provider and returns the AI-generated response.
+        It supports both streaming and non-streaming modes, as well as raw response format.
+        
+        Args:
+            prompt (str): The search query or prompt to send to the API.
+            stream (bool, optional): If True, yields response chunks as they arrive.
+                                   If False, returns complete response. Defaults to False.
+            raw (bool, optional): If True, returns raw response dictionaries.
+                                If False, returns SearchResponse objects that convert to text automatically.
+                                Defaults to False.
+        
+        Returns:
+            Union[SearchResponse, AsyncGenerator[Union[Dict[str, str], SearchResponse], None]]: 
+                - If stream=False: Returns complete response as SearchResponse object
+                - If stream=True: Yields response chunks as either Dict or SearchResponse objects
+        
+        Raises:
+            APIConnectionError: If the API request fails
+        """
+        raise NotImplementedError("Method needs to be implemented in subclass")