webscout 8.2.2__py3-none-any.whl → 2026.1.19__py3-none-any.whl

webscout/AIbase.py

@@ -1,123 +1,247 @@
-from abc import ABC, abstractmethod
-from pathlib import Path
-from typing import AsyncGenerator, 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 AIProviderError(Exception):
-    pass
-
-class Provider(ABC):
-
-    @abstractmethod
-    def ask(
-        self,
-        prompt: str,
-        stream: bool = False,
-        raw: bool = False,
-        optimizer: Optional[str] = None,
-        conversationally: bool = False,
-    ) -> Response:
-        raise NotImplementedError("Method needs to be implemented in subclass")
-
-    @abstractmethod
-    def chat(
-        self,
-        prompt: str,
-        stream: bool = False,
-        optimizer: Optional[str] = None,
-        conversationally: bool = False,
-    ) -> str:
-        raise NotImplementedError("Method needs to be implemented in subclass")
-
-    @abstractmethod
-    def get_message(self, response: Response) -> str:
-        raise NotImplementedError("Method needs to be implemented in subclass")
-
-class AsyncProvider(ABC):
-
-    @abstractmethod
-    async def ask(
-        self,
-        prompt: str,
-        stream: bool = False,
-        raw: bool = False,
-        optimizer: Optional[str] = None,
-        conversationally: bool = False,
-    ) -> Response:
-        raise NotImplementedError("Method needs to be implemented in subclass")
-
-    @abstractmethod
-    async def chat(
-        self,
-        prompt: str,
-        stream: bool = False,
-        optimizer: Optional[str] = None,
-        conversationally: bool = False,
-    ) -> str:
-        raise NotImplementedError("Method needs to be implemented in subclass")
-
-    @abstractmethod
-    async def get_message(self, response: Response) -> str:
-        raise NotImplementedError("Method needs to be implemented in subclass")
-
-class TTSProvider(ABC):
-
-    @abstractmethod
-    def tts(self, text: str) -> ImageData:
-        raise NotImplementedError("Method needs to be implemented in subclass")
-
-class AsyncTTSProvider(ABC):
-
-    @abstractmethod
-    async def tts(self, text: str) -> AsyncImageData:
-        raise NotImplementedError("Method needs to be implemented in subclass")
-
-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):
-
-    @abstractmethod
-    async def generate(
-        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]:
-        raise NotImplementedError("Method needs to be implemented in subclass")
-
-class AISearch(ABC):
-
-    @abstractmethod
-    def search(
-        self,
-        prompt: str,
-        stream: bool = False,
-        raw: bool = False,
-    ) -> Response:
-        raise NotImplementedError("Method needs to be implemented in subclass")
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any, Dict, Generator, List, Optional, Union
+
+from typing_extensions import TypeAlias
+
+# Type aliases for better readability
+Response: TypeAlias = Union[Dict[str, Any], Generator[Any, None, None], str]
+
+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
+
+class ModelList(ABC):
+    @abstractmethod
+    def list(self) -> List[str]:
+        """Return a list of available models"""
+        raise NotImplementedError
+
+class SimpleModelList(ModelList):
+    def __init__(self, models: List[str]):
+        self._models = models
+    def list(self) -> List[str]:
+        return self._models
+
+class Provider(ABC):
+    required_auth: bool = False
+    conversation: Any
+
+    def __init__(self, *args, **kwargs):
+        self._last_response: Dict[str, Any] = {}
+        self.conversation = None
+
+    @property
+    def last_response(self) -> Dict[str, Any]:
+        return self._last_response
+
+    @last_response.setter
+    def last_response(self, value: Dict[str, Any]):
+        self._last_response = value
+
+    @abstractmethod
+    def ask(
+        self,
+        prompt: str,
+        stream: bool = False,
+        raw: bool = False,
+        optimizer: Optional[str] = None,
+        conversationally: bool = False,
+        **kwargs: Any,
+    ) -> Response:
+        raise NotImplementedError("Method needs to be implemented in subclass")
+
+    @abstractmethod
+    def chat(
+        self,
+        prompt: str,
+        stream: bool = False,
+        optimizer: Optional[str] = None,
+        conversationally: bool = False,
+        **kwargs: Any,
+    ) -> Union[str, Generator[str, None, None]]:
+        raise NotImplementedError("Method needs to be implemented in subclass")
+
+    @abstractmethod
+    def get_message(self, response: Response) -> str:
+        raise NotImplementedError("Method needs to be implemented in subclass")
+
+class TTSProvider(ABC):
+
+    @abstractmethod
+    def tts(self, text: str, voice: Optional[str] = None, verbose: bool = False, **kwargs) -> str:
+        """Convert text to speech and save to a temporary file.
+
+        Args:
+            text (str): The text to convert to speech
+            voice (str, optional): The voice to use. Defaults to provider's default voice.
+            verbose (bool, optional): Whether to print debug information. Defaults to False.
+
+        Returns:
+            str: Path to the generated audio file
+        """
+        raise NotImplementedError("Method needs to be implemented in subclass")
+
+    def save_audio(self, audio_file: str, destination: Optional[str] = None, verbose: bool = False) -> str:
+        """Save audio to a specific destination.
+
+        Args:
+            audio_file (str): Path to the source audio file
+            destination (str, optional): Destination path. Defaults to current directory with timestamp.
+            verbose (bool, optional): Whether to print debug information. Defaults to False.
+
+        Returns:
+            str: Path to the saved audio file
+        """
+        import os
+        import shutil
+        import time
+        from pathlib import Path
+
+        source_path = Path(audio_file)
+
+        if not source_path.exists():
+            raise FileNotFoundError(f"Audio file not found: {audio_file}")
+
+        if destination is None:
+            # Create a default destination with timestamp in current directory
+            timestamp = int(time.time())
+            destination = os.path.join(os.getcwd(), f"tts_audio_{timestamp}{source_path.suffix}")
+
+        # Ensure the destination directory exists
+        os.makedirs(os.path.dirname(os.path.abspath(destination)), exist_ok=True)
+
+        # Copy the file
+        shutil.copy2(source_path, destination)
+
+        if verbose:
+            print(f"[debug] Audio saved to {destination}")
+
+        return destination
+
+    def stream_audio(
+        self,
+        text: str,
+        model: Optional[str] = None,
+        voice: Optional[str] = None,
+        response_format: Optional[str] = None,
+        instructions: Optional[str] = None,
+        chunk_size: int = 1024,
+        verbose: bool = False
+    ) -> Generator[bytes, None, None]:
+        """Stream audio in chunks.
+
+        Args:
+            text (str): The text to convert to speech
+            model (str, optional): The model to use.
+            voice (str, optional): The voice to use. Defaults to provider's default voice.
+            response_format (str, optional): The audio format.
+            instructions (str, optional): Voice instructions.
+            chunk_size (int, optional): Size of audio chunks to yield. Defaults to 1024.
+            verbose (bool, optional): Whether to print debug information. Defaults to False.
+
+        Yields:
+            Generator[bytes, None, None]: Audio data chunks
+        """
+        # Generate the audio file
+        audio_file = self.tts(text, voice=voice, verbose=verbose)
+
+        # Stream the file in chunks
+        with open(audio_file, 'rb') as f:
+            while chunk := f.read(chunk_size):
+                yield chunk
+
+class STTProvider(ABC):
+    """Abstract base class for Speech-to-Text providers."""
+
+    @abstractmethod
+    def transcribe(self, audio_path: Union[str, Path], **kwargs) -> Dict[str, Any]:
+        """Transcribe audio file to text.
+
+        Args:
+            audio_path (Union[str, Path]): Path to the audio file
+            **kwargs: Additional provider-specific parameters
+
+        Returns:
+            Dict[str, Any]: Transcription result in OpenAI Whisper format
+        """
+        raise NotImplementedError("Method needs to be implemented in subclass")
+
+    @abstractmethod
+    def transcribe_from_url(self, audio_url: str, **kwargs) -> Dict[str, Any]:
+        """Transcribe audio from URL to text.
+
+        Args:
+            audio_url (str): URL of the audio file
+            **kwargs: Additional provider-specific parameters
+
+        Returns:
+            Dict[str, Any]: Transcription result in OpenAI Whisper format
+        """
+        raise NotImplementedError("Method needs to be implemented in subclass")
+
+
+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
+    def search(
+        self,
+        prompt: str,
+        stream: bool = False,
+        raw: bool = False,
+        **kwargs: Any,
+    ) -> Union[SearchResponse, Generator[Union[Dict[str, str], SearchResponse], None, None], List[Any], Dict[str, Any], str]:
+        """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")

webscout/AIutel.py

@@ -1,132 +1,68 @@
-import json
-import platform
-import subprocess
-from typing import Union
-
-
-
-def sanitize_stream(
-    chunk: str, intro_value: str = "data:", to_json: bool = True
-) -> Union[str, dict]:
-    """Remove streaming flags
-
-    Args:
-        chunk (str): Streamig chunk.
-        intro_value (str, optional): streaming flag. Defaults to "data:".
-        to_json (bool, optional). Return chunk as dictionary. Defaults to True.
-
-    Returns:
-        str: Sanitized streaming value.
-    """
-
-    if chunk.startswith(intro_value):
-        chunk = chunk[len(intro_value) :]
-
-    return json.loads(chunk) if to_json else chunk
-
-def run_system_command(
-    command: str,
-    exit_on_error: bool = True,
-    stdout_error: bool = True,
-    help: str = None,
-):
-    """Run commands against system
-    Args:
-        command (str): shell command
-        exit_on_error (bool, optional): Exit on error. Defaults to True.
-        stdout_error (bool, optional): Print out the error. Defaults to True
-        help (str, optional): Help info in case of exception. Defaults to None.
-    Returns:
-        tuple : (is_successful, object[Exception|Subprocess.run])
-    """
-    try:
-        # Run the command and capture the output
-        result = subprocess.run(
-            command,
-            shell=True,
-            check=True,
-            text=True,
-            stdout=subprocess.PIPE,
-            stderr=subprocess.PIPE,
-        )
-        return (True, result)
-    except subprocess.CalledProcessError as e:
-        if exit_on_error:
-            raise Exception(f"Command failed with exit code {e.returncode}") from e
-        else:
-            return (False, e)  
-
-class Updates:
-    """Webscout latest release info"""
-
-    url = "https://api.github.com/repos/OE-LUCIFER/Webscout/releases/latest"
-
-    @property
-    def latest_version(self):
-        return self.latest(version=True)
-
-    def executable(self, system: str = platform.system()) -> str:
-        """Url pointing to executable for particular system
-
-        Args:
-            system (str, optional): system name. Defaults to platform.system().
-
-        Returns:
-            str: url
-        """
-        for entry in self.latest()["assets"]:
-            if entry.get("target") == system:
-                return entry.get("url")
-
-    def latest(self, whole: bool = False, version: bool = False) -> dict:
-        """Check Webscout latest version info
-
-        Args:
-            whole (bool, optional): Return whole json response. Defaults to False.
-            version (bool, optional): return version only. Defaults to False.
-
-        Returns:
-            bool|dict: version str or whole dict info
-        """
-        import requests
-
-        data = requests.get(self.url).json()
-        if whole:
-            return data
-
-        elif version:
-            return data.get("tag_name")
-
-        else:
-            sorted = dict(
-                tag_name=data.get("tag_name"),
-                tarball_url=data.get("tarball_url"),
-                zipball_url=data.get("zipball_url"),
-                html_url=data.get("html_url"),
-                body=data.get("body"),
-            )
-            whole_assets = []
-            for entry in data.get("assets"):
-                url = entry.get("browser_download_url")
-                assets = dict(url=url, size=entry.get("size"))
-                if ".deb" in url:
-                    assets["target"] = "Debian"
-                elif ".exe" in url:
-                    assets["target"] = "Windows"
-                elif "macos" in url:
-                    assets["target"] = "Mac"
-                elif "linux" in url:
-                    assets["target"] = "Linux"
-
-                whole_assets.append(assets)
-            sorted["assets"] = whole_assets
-
-            return sorted
-
-from .conversation import Conversation
-
-from .optimizers import Optimizers
-
-from .Extra.autocoder import AutoCoder
-
-from .prompt_manager import AwesomePrompts
+import functools
+import time
+
+# --- Utility Decorators ---
+from typing import Callable, Optional
+
+from .conversation import Conversation  # noqa: E402,F401
+from .optimizers import Optimizers  # noqa: E402,F401
+from .prompt_manager import AwesomePrompts  # noqa: E402,F401
+from .sanitize import *  # noqa: E402, F401, F403
+
+
+def timeIt(func: Callable):
+    """
+    Decorator to measure execution time of a function (sync or async).
+    Prints: - Execution time for '{func.__name__}' : {elapsed:.6f} Seconds.
+    """
+    import asyncio
+    GREEN_BOLD = "\033[1;92m"
+    RESET = "\033[0m"
+    @functools.wraps(func)
+    def sync_wrapper(*args, **kwargs):
+        start_time = time.time()
+        result = func(*args, **kwargs)
+        end_time = time.time()
+        print()
+        func_name = getattr(func, "__name__", str(func))
+        print(f"{GREEN_BOLD}- Execution time for '{func_name}' : {end_time - start_time:.6f} Seconds.  {RESET}\n")
+        return result
+
+    @functools.wraps(func)
+    async def async_wrapper(*args, **kwargs):
+        start_time = time.time()
+        result = await func(*args, **kwargs)
+        end_time = time.time()
+        print()
+        func_name = getattr(func, "__name__", str(func))
+        print(f"{GREEN_BOLD}- Execution time for '{func_name}' : {end_time - start_time:.6f} Seconds.  {RESET}\n")
+        return result
+
+    if asyncio.iscoroutinefunction(func):
+        return async_wrapper
+    else:
+        return sync_wrapper
+
+def retry(retries: int = 3, delay: float = 1) -> Callable:
+    """
+    Decorator to retry a function on exception.
+    """
+    def decorator(func: Callable):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            last_exc = None
+            for attempt in range(retries):
+                try:
+                    return func(*args, **kwargs)
+                except Exception as exc:
+                    last_exc = exc
+                    print(f"Attempt {attempt + 1} failed: {exc}. Retrying in {delay} seconds...")
+                    time.sleep(delay)
+            # Ensure we have an exception to raise
+            if last_exc is not None:
+                raise last_exc
+            else:
+                func_name = getattr(func, "__name__", str(func))
+                raise RuntimeError(f"Function {func_name} failed after {retries} retries with no exception recorded")
+        return wrapper
+    return decorator