webscout 8.2.8__tar.gz → 8.2.9__tar.gz

{webscout-8.2.8/webscout.egg-info → webscout-8.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: webscout
-Version: 8.2.8
+Version: 8.2.9
 Summary: Search for anything using Google, DuckDuckGo, phind.com, Contains AI models, can transcribe yt videos, temporary email and phone number generation, has TTS support, webai (terminal gpt and open interpreter) and offline LLMs and more
 Author-email: OEvortex <helpingai5@gmail.com>
 License: HelpingAI
@@ -60,6 +60,7 @@ Requires-Dist: openai
 Requires-Dist: gradio_client
 Requires-Dist: psutil
 Requires-Dist: aiohttp
+Requires-Dist: zstandard
 Provides-Extra: dev
 Requires-Dist: ruff>=0.1.6; extra == "dev"
 Requires-Dist: pytest>=7.4.2; extra == "dev"
@@ -68,6 +69,7 @@ Requires-Dist: fastapi; extra == "api"
 Requires-Dist: uvicorn[standard]; extra == "api"
 Requires-Dist: pydantic; extra == "api"
 Requires-Dist: python-multipart; extra == "api"
+Requires-Dist: tiktoken; extra == "api"
 Dynamic: license-file
 
 <div align="center">
@@ -170,7 +172,7 @@ Dynamic: license-file
 * **[GitAPI](webscout/Extra/GitToolkit/gitapi):** Powerful GitHub data extraction toolkit without authentication requirements for public data
 * **[SwiftCLI](webscout/swiftcli/Readme.md):** A powerful and elegant CLI framework for beautiful command-line interfaces
 * **[LitPrinter](webscout/litprinter/Readme.md):** Styled console output with rich formatting and colors
-* **[LitLogger](webscout/litlogger/Readme.md):** Simplified logging with customizable formats and color schemes
+* **[LitLogger](webscout/litlogger/README.md):** Simplified logging with customizable formats and color schemes
 * **[LitAgent](webscout/litagent/Readme.md):** Modern user agent generator that keeps your requests undetectable
 * **[Scout](webscout/scout/README.md):** Advanced web parsing and crawling library with intelligent HTML/XML parsing
 * **[Inferno](https://github.com/HelpingAI/inferno):** Run local LLMs with an OpenAI-compatible API and interactive CLI (now a standalone package: `pip install inferno-llm`)
@@ -191,45 +193,154 @@ Dynamic: license-file
 
 ## ⚙️ Installation
 
-Install Webscout using pip:
+Webscout supports multiple installation methods to fit your workflow:
+
+### 📦 Standard Installation
 
 ```bash
+# Install from PyPI
 pip install -U webscout
+
+# Install with API server dependencies
+pip install -U "webscout[api]"
+
+# Install with development dependencies
+pip install -U "webscout[dev]"
+```
+
+### ⚡ UV Package Manager (Recommended)
+
+[UV](https://github.com/astral-sh/uv) is a fast Python package manager. Webscout has full UV support:
+
+```bash
+# Install UV first (if not already installed)
+pip install uv
+
+# Install Webscout with UV
+uv add webscout
+
+# Install with API dependencies
+uv add "webscout[api]"
+
+# Run Webscout directly with UV (no installation needed)
+uv run webscout --help
+
+# Run with API dependencies
+uv run --extra api webscout-server
+
+# Install as a UV tool for global access
+uv tool install webscout
+
+# Use UV tool commands
+webscout --help
+webscout-server --help
+```
+
+### 🔧 Development Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/OEvortex/Webscout.git
+cd Webscout
+
+# Install in development mode with UV
+uv sync --extra dev --extra api
+
+# Or with pip
+pip install -e ".[dev,api]"
+```
+
+### 🐳 Docker Installation
+
+```bash
+# Pull and run the Docker image
+docker pull oevortex/webscout:latest
+docker run -it oevortex/webscout:latest
+```
+
+### 📱 Quick Start Commands
+
+After installation, you can immediately start using Webscout:
+
+```bash
+# Check version
+webscout version
+
+# Search the web
+webscout text -k "python programming"
+
+# Start API server
+webscout-server
+
+# Get help
+webscout --help
 ```
-</div>
 
 <hr/>
 
 ## 🖥️ Command Line Interface
 
-Webscout provides a powerful command-line interface for quick access to its features:
+Webscout provides a powerful command-line interface for quick access to its features. You can use it in multiple ways:
+
+### 🚀 Direct Commands (Recommended)
+
+After installing with `uv tool install webscout` or `pip install webscout`:
+
+```bash
+# Get help
+webscout --help
+
+# Start API server
+webscout-server
+```
+
+### 🔧 UV Run Commands (No Installation Required)
+
+```bash
+# Run directly with UV (downloads and runs automatically)
+uv run webscout --help
+uv run --extra api webscout-server
+```
+
+### 📦 Python Module Commands
 
 ```bash
+# Traditional Python module execution
 python -m webscout --help
+python -m webscout.client  # Start API server
 ```
 
 <details open>
-<summary><b>Web Search Commands</b></summary>
+<summary><b>🔍 Web Search Commands</b></summary>
 <p>
 
-| Command | Description |
-|---------|-------------|
-| `python -m webscout answers -k "query"` | Perform an answers search |
-| `python -m webscout images -k "query"` | Search for images |
-| `python -m webscout maps -k "query"` | Perform a maps search |
-| `python -m webscout news -k "query"` | Search for news articles |
-| `python -m webscout suggestions -k "query"` | Get search suggestions |
-| `python -m webscout text -k "query"` | Perform a text search |
-| `python -m webscout translate -k "text"` | Translate text |
-| `python -m webscout version` | Display the current version |
-| `python -m webscout videos -k "query"` | Search for videos |
-| `python -m webscout weather -l "location"` | Get weather information |
-| `python -m webscout google_text -k "query"` | Perform a text search using Google |
-| `python -m webscout google_news -k "query"` | Search for news using Google |
-| `python -m webscout google_suggestions -q "query"` | Get search suggestions from Google |
-| `python -m webscout yep_text -k "query"` | Perform a text search using Yep |
-| `python -m webscout yep_images -k "query"` | Search for images using Yep |
-| `python -m webscout yep_suggestions -q "query"` | Get search suggestions from Yep |
+| Command | Description | Example |
+|---------|-------------|---------|
+| `webscout text -k "query"` | Perform a text search | `webscout text -k "python programming"` |
+| `webscout answers -k "query"` | Get instant answers | `webscout answers -k "what is AI"` |
+| `webscout images -k "query"` | Search for images | `webscout images -k "nature photography"` |
+| `webscout videos -k "query"` | Search for videos | `webscout videos -k "python tutorials"` |
+| `webscout news -k "query"` | Search for news articles | `webscout news -k "technology trends"` |
+| `webscout maps -k "query"` | Perform a maps search | `webscout maps -k "restaurants near me"` |
+| `webscout translate -k "text"` | Translate text | `webscout translate -k "hello world"` |
+| `webscout suggestions -k "query"` | Get search suggestions | `webscout suggestions -k "how to"` |
+| `webscout weather -l "location"` | Get weather information | `webscout weather -l "New York"` |
+| `webscout version` | Display the current version | `webscout version` |
+
+**Google Search Commands:**
+| Command | Description | Example |
+|---------|-------------|---------|
+| `webscout google_text -k "query"` | Google text search | `webscout google_text -k "machine learning"` |
+| `webscout google_news -k "query"` | Google news search | `webscout google_news -k "AI breakthrough"` |
+| `webscout google_suggestions -q "query"` | Google suggestions | `webscout google_suggestions -q "python"` |
+
+**Yep Search Commands:**
+| Command | Description | Example |
+|---------|-------------|---------|
+| `webscout yep_text -k "query"` | Yep text search | `webscout yep_text -k "web development"` |
+| `webscout yep_images -k "query"` | Yep image search | `webscout yep_images -k "landscapes"` |
+| `webscout yep_suggestions -q "query"` | Yep suggestions | `webscout yep_suggestions -q "javascript"` |
+
 </p>
 </details>
 
@@ -279,30 +390,46 @@ Webscout includes an OpenAI-compatible API server that allows you to use any sup
 
 ### Starting the API Server
 
-#### From Command Line
+#### From Command Line (Recommended)
 
 ```bash
 # Start with default settings (port 8000)
-python -m webscout.Provider.OPENAI.api
+webscout-server
 
 # Start with custom port
-python -m webscout.Provider.OPENAI.api --port 8080
+webscout-server --port 8080
 
 # Start with API key authentication
-python -m webscout.Provider.OPENAI.api --api-key "your-secret-key"
+webscout-server --api-key "your-secret-key"
 
 # Specify a default provider
-python -m webscout.Provider.OPENAI.api --default-provider "Claude"
+webscout-server --default-provider "Claude"
 
 # Run in debug mode
-python -m webscout.Provider.OPENAI.api --debug
+webscout-server --debug
+
+# Get help for all options
+webscout-server --help
+```
+
+#### Alternative Methods
+
+```bash
+# Using UV (no installation required)
+uv run --extra api webscout-server
+
+# Using Python module
+python -m webscout.client
+
+# Legacy method (still supported)
+python -m webscout.Provider.OPENAI.api
 ```
 
 #### From Python Code
 
 ```python
 # Method 1: Using the helper function
-from webscout.Provider.OPENAI.api import start_server
+from webscout.client import start_server  # <--- Now recommended
 
 # Start with default settings
 start_server()
@@ -311,13 +438,10 @@ start_server()
 start_server(port=8080, api_key="your-secret-key", default_provider="Claude")
 
 # Method 2: Using the run_api function for more control
-from webscout.Provider.OPENAI.api import run_api
+from webscout.client import run_api
 
 run_api(
     host="0.0.0.0",
-    port=8080,
-    api_key="your-secret-key",
-    default_provider="Claude",
     debug=True
 )
 ```

{webscout-8.2.8 → webscout-8.2.9}/README.md

@@ -98,7 +98,7 @@
 * **[GitAPI](webscout/Extra/GitToolkit/gitapi):** Powerful GitHub data extraction toolkit without authentication requirements for public data
 * **[SwiftCLI](webscout/swiftcli/Readme.md):** A powerful and elegant CLI framework for beautiful command-line interfaces
 * **[LitPrinter](webscout/litprinter/Readme.md):** Styled console output with rich formatting and colors
-* **[LitLogger](webscout/litlogger/Readme.md):** Simplified logging with customizable formats and color schemes
+* **[LitLogger](webscout/litlogger/README.md):** Simplified logging with customizable formats and color schemes
 * **[LitAgent](webscout/litagent/Readme.md):** Modern user agent generator that keeps your requests undetectable
 * **[Scout](webscout/scout/README.md):** Advanced web parsing and crawling library with intelligent HTML/XML parsing
 * **[Inferno](https://github.com/HelpingAI/inferno):** Run local LLMs with an OpenAI-compatible API and interactive CLI (now a standalone package: `pip install inferno-llm`)
@@ -119,45 +119,154 @@
 
 ## ⚙️ Installation
 
-Install Webscout using pip:
+Webscout supports multiple installation methods to fit your workflow:
+
+### 📦 Standard Installation
 
 ```bash
+# Install from PyPI
 pip install -U webscout
+
+# Install with API server dependencies
+pip install -U "webscout[api]"
+
+# Install with development dependencies
+pip install -U "webscout[dev]"
+```
+
+### ⚡ UV Package Manager (Recommended)
+
+[UV](https://github.com/astral-sh/uv) is a fast Python package manager. Webscout has full UV support:
+
+```bash
+# Install UV first (if not already installed)
+pip install uv
+
+# Install Webscout with UV
+uv add webscout
+
+# Install with API dependencies
+uv add "webscout[api]"
+
+# Run Webscout directly with UV (no installation needed)
+uv run webscout --help
+
+# Run with API dependencies
+uv run --extra api webscout-server
+
+# Install as a UV tool for global access
+uv tool install webscout
+
+# Use UV tool commands
+webscout --help
+webscout-server --help
+```
+
+### 🔧 Development Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/OEvortex/Webscout.git
+cd Webscout
+
+# Install in development mode with UV
+uv sync --extra dev --extra api
+
+# Or with pip
+pip install -e ".[dev,api]"
+```
+
+### 🐳 Docker Installation
+
+```bash
+# Pull and run the Docker image
+docker pull oevortex/webscout:latest
+docker run -it oevortex/webscout:latest
+```
+
+### 📱 Quick Start Commands
+
+After installation, you can immediately start using Webscout:
+
+```bash
+# Check version
+webscout version
+
+# Search the web
+webscout text -k "python programming"
+
+# Start API server
+webscout-server
+
+# Get help
+webscout --help
 ```
-</div>
 
 <hr/>
 
 ## 🖥️ Command Line Interface
 
-Webscout provides a powerful command-line interface for quick access to its features:
+Webscout provides a powerful command-line interface for quick access to its features. You can use it in multiple ways:
+
+### 🚀 Direct Commands (Recommended)
+
+After installing with `uv tool install webscout` or `pip install webscout`:
+
+```bash
+# Get help
+webscout --help
+
+# Start API server
+webscout-server
+```
+
+### 🔧 UV Run Commands (No Installation Required)
+
+```bash
+# Run directly with UV (downloads and runs automatically)
+uv run webscout --help
+uv run --extra api webscout-server
+```
+
+### 📦 Python Module Commands
 
 ```bash
+# Traditional Python module execution
 python -m webscout --help
+python -m webscout.client  # Start API server
 ```
 
 <details open>
-<summary><b>Web Search Commands</b></summary>
+<summary><b>🔍 Web Search Commands</b></summary>
 <p>
 
-| Command | Description |
-|---------|-------------|
-| `python -m webscout answers -k "query"` | Perform an answers search |
-| `python -m webscout images -k "query"` | Search for images |
-| `python -m webscout maps -k "query"` | Perform a maps search |
-| `python -m webscout news -k "query"` | Search for news articles |
-| `python -m webscout suggestions -k "query"` | Get search suggestions |
-| `python -m webscout text -k "query"` | Perform a text search |
-| `python -m webscout translate -k "text"` | Translate text |
-| `python -m webscout version` | Display the current version |
-| `python -m webscout videos -k "query"` | Search for videos |
-| `python -m webscout weather -l "location"` | Get weather information |
-| `python -m webscout google_text -k "query"` | Perform a text search using Google |
-| `python -m webscout google_news -k "query"` | Search for news using Google |
-| `python -m webscout google_suggestions -q "query"` | Get search suggestions from Google |
-| `python -m webscout yep_text -k "query"` | Perform a text search using Yep |
-| `python -m webscout yep_images -k "query"` | Search for images using Yep |
-| `python -m webscout yep_suggestions -q "query"` | Get search suggestions from Yep |
+| Command | Description | Example |
+|---------|-------------|---------|
+| `webscout text -k "query"` | Perform a text search | `webscout text -k "python programming"` |
+| `webscout answers -k "query"` | Get instant answers | `webscout answers -k "what is AI"` |
+| `webscout images -k "query"` | Search for images | `webscout images -k "nature photography"` |
+| `webscout videos -k "query"` | Search for videos | `webscout videos -k "python tutorials"` |
+| `webscout news -k "query"` | Search for news articles | `webscout news -k "technology trends"` |
+| `webscout maps -k "query"` | Perform a maps search | `webscout maps -k "restaurants near me"` |
+| `webscout translate -k "text"` | Translate text | `webscout translate -k "hello world"` |
+| `webscout suggestions -k "query"` | Get search suggestions | `webscout suggestions -k "how to"` |
+| `webscout weather -l "location"` | Get weather information | `webscout weather -l "New York"` |
+| `webscout version` | Display the current version | `webscout version` |
+
+**Google Search Commands:**
+| Command | Description | Example |
+|---------|-------------|---------|
+| `webscout google_text -k "query"` | Google text search | `webscout google_text -k "machine learning"` |
+| `webscout google_news -k "query"` | Google news search | `webscout google_news -k "AI breakthrough"` |
+| `webscout google_suggestions -q "query"` | Google suggestions | `webscout google_suggestions -q "python"` |
+
+**Yep Search Commands:**
+| Command | Description | Example |
+|---------|-------------|---------|
+| `webscout yep_text -k "query"` | Yep text search | `webscout yep_text -k "web development"` |
+| `webscout yep_images -k "query"` | Yep image search | `webscout yep_images -k "landscapes"` |
+| `webscout yep_suggestions -q "query"` | Yep suggestions | `webscout yep_suggestions -q "javascript"` |
+
 </p>
 </details>
 
@@ -207,30 +316,46 @@ Webscout includes an OpenAI-compatible API server that allows you to use any sup
 
 ### Starting the API Server
 
-#### From Command Line
+#### From Command Line (Recommended)
 
 ```bash
 # Start with default settings (port 8000)
-python -m webscout.Provider.OPENAI.api
+webscout-server
 
 # Start with custom port
-python -m webscout.Provider.OPENAI.api --port 8080
+webscout-server --port 8080
 
 # Start with API key authentication
-python -m webscout.Provider.OPENAI.api --api-key "your-secret-key"
+webscout-server --api-key "your-secret-key"
 
 # Specify a default provider
-python -m webscout.Provider.OPENAI.api --default-provider "Claude"
+webscout-server --default-provider "Claude"
 
 # Run in debug mode
-python -m webscout.Provider.OPENAI.api --debug
+webscout-server --debug
+
+# Get help for all options
+webscout-server --help
+```
+
+#### Alternative Methods
+
+```bash
+# Using UV (no installation required)
+uv run --extra api webscout-server
+
+# Using Python module
+python -m webscout.client
+
+# Legacy method (still supported)
+python -m webscout.Provider.OPENAI.api
 ```
 
 #### From Python Code
 
 ```python
 # Method 1: Using the helper function
-from webscout.Provider.OPENAI.api import start_server
+from webscout.client import start_server  # <--- Now recommended
 
 # Start with default settings
 start_server()
@@ -239,13 +364,10 @@ start_server()
 start_server(port=8080, api_key="your-secret-key", default_provider="Claude")
 
 # Method 2: Using the run_api function for more control
-from webscout.Provider.OPENAI.api import run_api
+from webscout.client import run_api
 
 run_api(
     host="0.0.0.0",
-    port=8080,
-    api_key="your-secret-key",
-    default_provider="Claude",
     debug=True
 )
 ```

{webscout-8.2.8 → webscout-8.2.9}/pyproject.toml

@@ -39,9 +39,9 @@ classifiers = [
     "Topic :: Utilities",
 ]
 keywords = [
-    "search", "ai", "chatbot", "llm", "language-model", "gpt", "openai", 
-    "gemini", "claude", "llama", "search-engine", "text-to-speech", "tts", 
-    "text-to-image", "tti", "weather", "youtube", "toolkit", "utilities", 
+    "search", "ai", "chatbot", "llm", "language-model", "gpt", "openai",
+    "gemini", "claude", "llama", "search-engine", "text-to-speech", "tts",
+    "text-to-image", "tti", "weather", "youtube", "toolkit", "utilities",
     "web-search", "duckduckgo", "google", "yep"
 ]
 dependencies = [
@@ -71,11 +71,13 @@ dependencies = [
     "gradio_client",
     "psutil",
     "aiohttp",
+    "zstandard",
 ]
 
 [project.scripts]
 WEBS = "webscout.cli:main"
 webscout = "webscout.cli:main"
+webscout-server = "webscout.client:start_server"  # Instantly start the OpenAI-compatible API server
 
 [project.urls]
 Source = "https://github.com/OE-LUCIFER/Webscout"
@@ -92,6 +94,7 @@ api = [
     "uvicorn[standard]",
     "pydantic",
     "python-multipart",
+    "tiktoken",  # Added tiktoken for token counting support
 ]
 
 [tool.setuptools]
@@ -116,7 +119,3 @@ line-length = 100
 target-version = "py39"
 select = ["E", "F", "W", "I"]
 ignore = ["E501"]
-
-[tool.pytest]
-testpaths = ["tests"]
-python_files = "test_*.py"

{webscout-8.2.8 → webscout-8.2.9}/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.