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

webscout/server/__init__.py

@@ -0,0 +1,48 @@
+# webscout/server/__init__.py
+from .exceptions import APIError
+from .routes import Api
+
+
+# Import server functions lazily to avoid module execution issues
+def create_app():
+    from .server import create_app as _create_app
+    return _create_app()
+
+def run_api(*args, **kwargs):
+    from .server import run_api as _run_api
+    return _run_api(*args, **kwargs)
+
+def start_server(*args, **kwargs):
+    from .server import start_server as _start_server
+    return _start_server(*args, **kwargs)
+
+
+
+# Lazy imports for config classes to avoid initialization issues
+def get_server_config():
+    from .config import ServerConfig
+    return ServerConfig
+
+def get_app_config():
+    from .config import AppConfig
+    return AppConfig
+
+def initialize_provider_map():
+    from .providers import initialize_provider_map as _init_provider_map
+    return _init_provider_map()
+
+def initialize_tti_provider_map():
+    from .providers import initialize_tti_provider_map as _init_tti_provider_map
+    return _init_tti_provider_map()
+
+__all__ = [
+    "create_app",
+    "run_api",
+    "start_server",
+    "Api",
+    "get_server_config",
+    "get_app_config",
+    "APIError",
+    "initialize_provider_map",
+    "initialize_tti_provider_map"
+]

webscout/server/config.py

@@ -0,0 +1,78 @@
+"""
+Configuration management for the Webscout API server.
+"""
+
+import os
+from typing import Any, Dict, List, Optional
+
+from litprinter import ic
+
+# Configuration constants
+DEFAULT_PORT = 8000
+DEFAULT_HOST = "0.0.0.0"
+
+
+class ServerConfig:
+    """Centralized configuration management for the API server."""
+
+    def __init__(self):
+        self.provider_map: Dict[str, Any] = {}
+        self.default_provider: str = "ChatGPT"
+        self.base_url: Optional[str] = None
+        self.host: str = DEFAULT_HOST
+        self.port: int = DEFAULT_PORT
+        self.debug: bool = False
+        self.cors_origins: List[str] = ["*"]
+        self.max_request_size: int = 10 * 1024 * 1024  # 10MB
+        self.request_timeout: int = 300  # 5 minutes
+        self.auth_required: bool = False
+        self.rate_limit_enabled: bool = False
+        self.request_logging_enabled: bool = os.getenv("WEBSCOUT_REQUEST_LOGGING", "true").lower() == "true"  # Enable request logging by default
+
+    def update(self, **kwargs) -> None:
+        """Update configuration with provided values."""
+        for key, value in kwargs.items():
+            if hasattr(self, key) and value is not None:
+                setattr(self, key, value)
+                ic.configureOutput(prefix='INFO| ')
+                ic(f"Config updated: {key} = {value}")
+
+    def validate(self) -> None:
+        """Validate configuration settings."""
+        if self.port < 1 or self.port > 65535:
+            raise ValueError(f"Invalid port number: {self.port}")
+
+        if self.default_provider not in self.provider_map and self.provider_map:
+            available_providers = list(set(v.__name__ for v in self.provider_map.values()))
+            ic.configureOutput(prefix='WARNING| ')
+            ic(f"Default provider '{self.default_provider}' not found. Available: {available_providers}")
+
+
+class AppConfig:
+    """Legacy configuration class for backward compatibility."""
+    provider_map = {}
+    tti_provider_map = {}  # Add TTI provider map
+    default_provider = "ChatGPT"
+    default_tti_provider = "PollinationsAI"  # Add default TTI provider
+    base_url: Optional[str] = None
+    auth_required: bool = False
+    rate_limit_enabled: bool = False
+    request_logging_enabled: bool = os.getenv("WEBSCOUT_REQUEST_LOGGING", "true").lower() == "true"  # Enable request logging by default
+
+    @classmethod
+    def set_config(cls, **data):
+        """Set configuration values."""
+        # Filter out auth-related keys
+        auth_keys = {'api_key'}
+        filtered_data = {k: v for k, v in data.items() if k not in auth_keys}
+
+        for key, value in filtered_data.items():
+            setattr(cls, key, value)
+        # Sync with new config system
+        try:
+            from .server import get_config
+            config = get_config()
+            config.update(**filtered_data)
+        except ImportError:
+            # Handle case where server module is not available
+            pass

webscout/server/exceptions.py

@@ -0,0 +1,69 @@
+"""
+Custom exceptions for the Webscout API.
+"""
+
+import json
+import re
+from typing import Optional
+
+from fastapi.responses import JSONResponse
+from starlette.status import HTTP_500_INTERNAL_SERVER_ERROR
+
+from .request_models import ErrorDetail, ErrorResponse
+
+
+def clean_text(text):
+    """Clean text by removing null bytes and control characters except newlines and tabs."""
+    if not isinstance(text, str):
+        return text
+
+    # Remove null bytes
+    text = text.replace('\x00', '')
+
+    # Keep newlines, tabs, and other printable characters, remove other control chars
+    # This regex matches control characters except \n, \r, \t
+    return re.sub(r'[\x01-\x08\x0b\x0c\x0e-\x1f\x7f]', '', text)
+
+
+class APIError(Exception):
+    """Custom exception for API errors."""
+
+    def __init__(self, message: str, status_code: int = HTTP_500_INTERNAL_SERVER_ERROR,
+                 error_type: str = "server_error", param: Optional[str] = None,
+                 code: Optional[str] = None):
+        self.message = message
+        self.status_code = status_code
+        self.error_type = error_type
+        self.param = param
+        self.code = code
+        super().__init__(message)
+
+    def to_response(self) -> JSONResponse:
+        """Convert to FastAPI JSONResponse."""
+        error_detail = ErrorDetail(
+            message=self.message,
+            type=self.error_type,
+            param=self.param,
+            code=self.code
+        )
+        error_response = ErrorResponse(error=error_detail)
+        return JSONResponse(
+            status_code=self.status_code,
+            content=error_response.model_dump(exclude_none=True)
+        )
+
+
+def format_exception(e) -> str:
+    """Format exception for JSON response."""
+    if isinstance(e, str):
+        message = e
+    else:
+        message = f"{e.__class__.__name__}: {str(e)}"
+    return json.dumps({
+        "error": {
+            "message": message,
+            "type": "server_error",
+            "param": None,
+            "code": "internal_server_error"
+        }
+    })

webscout/server/providers.py

@@ -0,0 +1,286 @@
+"""
+Provider management and initialization for the Webscout API.
+"""
+
+import inspect
+import sys
+from typing import Any, Dict, Optional, Tuple
+
+from litprinter import ic
+from starlette.status import HTTP_404_NOT_FOUND, HTTP_500_INTERNAL_SERVER_ERROR
+
+from .config import AppConfig
+from .exceptions import APIError
+
+# Cache for provider instances to avoid reinitialization on every request
+provider_instances: Dict[str, Any] = {}
+tti_provider_instances: Dict[str, Any] = {}
+
+
+def initialize_provider_map() -> None:
+    """Initialize the provider map by discovering available providers."""
+    ic.configureOutput(prefix='INFO| ')
+    ic("Initializing provider map...")
+
+    try:
+        from webscout.Provider.OPENAI.base import OpenAICompatibleProvider, SimpleModelList
+        module = sys.modules["webscout.Provider.OPENAI"]
+
+        provider_count = 0
+        model_count = 0
+
+        for name, obj in inspect.getmembers(module):
+            if (
+                inspect.isclass(obj)
+                and issubclass(obj, OpenAICompatibleProvider)
+                and obj.__name__ != "OpenAICompatibleProvider"
+            ):
+                # Only include providers that don't require authentication
+                if hasattr(obj, 'required_auth') and not getattr(obj, 'required_auth', True):
+                    provider_name = obj.__name__
+                    AppConfig.provider_map[provider_name] = obj
+                    provider_count += 1
+
+                    # Register available models for this provider
+                    available_models = getattr(obj, "AVAILABLE_MODELS", None)
+                    if available_models is not None and isinstance(
+                        available_models, (list, tuple, set)
+                    ):
+                        for model in available_models:
+                            if model and isinstance(model, str):
+                                model_key = f"{provider_name}/{model}"
+                                AppConfig.provider_map[model_key] = obj
+                                model_count += 1
+
+        # Fallback to ChatGPT if no providers found
+        if not AppConfig.provider_map:
+            ic.configureOutput(prefix='WARNING| ')
+            ic("No providers found, using ChatGPT fallback")
+            try:
+                from webscout.Provider.OPENAI.chatgpt import ChatGPT
+                fallback_models = ["gpt-4", "gpt-4o", "gpt-4o-mini", "gpt-3.5-turbo"]
+
+                AppConfig.provider_map["ChatGPT"] = ChatGPT
+
+                for model in fallback_models:
+                    model_key = f"ChatGPT/{model}"
+                    AppConfig.provider_map[model_key] = ChatGPT
+
+                AppConfig.default_provider = "ChatGPT"
+                provider_count = 1
+                model_count = len(fallback_models)
+            except ImportError as e:
+                ic.configureOutput(prefix='ERROR| ')
+                ic(f"Failed to import ChatGPT fallback: {e}")
+                raise APIError("No providers available", HTTP_500_INTERNAL_SERVER_ERROR)
+
+        ic.configureOutput(prefix='INFO| ')
+        ic(f"Initialized {provider_count} providers with {model_count} models")
+
+    except Exception as e:
+        ic.configureOutput(prefix='ERROR| ')
+        ic(f"Failed to initialize provider map: {e}")
+        raise APIError(f"Provider initialization failed: {e}", HTTP_500_INTERNAL_SERVER_ERROR)
+
+
+def initialize_tti_provider_map() -> None:
+    """Initialize the TTI provider map by discovering available TTI providers."""
+    ic.configureOutput(prefix='INFO| ')
+    ic("Initializing TTI provider map...")
+
+    try:
+        from webscout.Provider.TTI.base import TTICompatibleProvider
+        module = sys.modules["webscout.Provider.TTI"]
+
+        provider_count = 0
+        model_count = 0
+
+        for name, obj in inspect.getmembers(module):
+            if (
+                inspect.isclass(obj)
+                and issubclass(obj, TTICompatibleProvider)
+                and obj.__name__ != "TTICompatibleProvider"
+                and obj.__name__ != "BaseImages"
+            ):
+                provider_name = obj.__name__
+                AppConfig.tti_provider_map[provider_name] = obj
+                provider_count += 1
+
+                # Register available models for this TTI provider
+                available_models = getattr(obj, "AVAILABLE_MODELS", None)
+                if available_models is not None and isinstance(
+                    available_models, (list, tuple, set)
+                ):
+                    for model in available_models:
+                        if model and isinstance(model, str):
+                            model_key = f"{provider_name}/{model}"
+                            AppConfig.tti_provider_map[model_key] = obj
+                            model_count += 1
+
+        # Fallback to PollinationsAI if no TTI providers found
+        if not AppConfig.tti_provider_map:
+            ic.configureOutput(prefix='WARNING| ')
+            ic("No TTI providers found, using PollinationsAI fallback")
+            try:
+                from webscout.Provider.TTI.pollinations import PollinationsAI
+                fallback_models = ["flux", "turbo", "gptimage"]
+
+                AppConfig.tti_provider_map["PollinationsAI"] = PollinationsAI
+
+                for model in fallback_models:
+                    model_key = f"PollinationsAI/{model}"
+                    AppConfig.tti_provider_map[model_key] = PollinationsAI
+
+                AppConfig.default_tti_provider = "PollinationsAI"
+                provider_count = 1
+                model_count = len(fallback_models)
+            except ImportError as e:
+                ic.configureOutput(prefix='ERROR| ')
+                ic(f"Failed to import PollinationsAI fallback: {e}")
+                raise APIError("No TTI providers available", HTTP_500_INTERNAL_SERVER_ERROR)
+
+        ic.configureOutput(prefix='INFO| ')
+        ic(f"Initialized {provider_count} TTI providers with {model_count} models")
+
+    except Exception as e:
+        ic.configureOutput(prefix='ERROR| ')
+        ic(f"Failed to initialize TTI provider map: {e}")
+        raise APIError(f"TTI Provider initialization failed: {e}", HTTP_500_INTERNAL_SERVER_ERROR)
+
+
+def resolve_provider_and_model(model_identifier: str) -> Tuple[Any, str]:
+    """Resolve provider class and model name from model identifier."""
+    provider_class = None
+    model_name = None
+
+    # Check for explicit provider/model syntax
+    if model_identifier in AppConfig.provider_map and "/" in model_identifier:
+        provider_class = AppConfig.provider_map[model_identifier]
+        _, model_name = model_identifier.split("/", 1)
+    elif "/" in model_identifier:
+        provider_name, model_name = model_identifier.split("/", 1)
+        provider_class = AppConfig.provider_map.get(provider_name)
+    else:
+        provider_class = AppConfig.provider_map.get(AppConfig.default_provider)
+        model_name = model_identifier
+
+    if not provider_class:
+        available_providers = list(set(v.__name__ for v in AppConfig.provider_map.values()))
+        raise APIError(
+            f"Provider for model '{model_identifier}' not found. Available providers: {available_providers}",
+            HTTP_404_NOT_FOUND,
+            "model_not_found",
+            param="model"
+        )
+
+    # Validate model availability
+    if hasattr(provider_class, "AVAILABLE_MODELS") and model_name is not None:
+        available = getattr(provider_class, "AVAILABLE_MODELS", None)
+        # If it's a property, get from instance
+        if isinstance(available, property):
+            try:
+                available = getattr(provider_class(), "AVAILABLE_MODELS", [])
+            except Exception:
+                available = []
+        # If still not iterable, fallback to empty list
+        if not isinstance(available, (list, tuple, set)):
+            available = list(available) if available and hasattr(available, "__iter__") and not isinstance(available, str) else []
+        if available and model_name not in available:
+            raise APIError(
+                f"Model '{model_name}' not supported by provider '{provider_class.__name__}'. Available models: {available}",
+                HTTP_404_NOT_FOUND,
+                "model_not_found",
+                param="model"
+            )
+
+    return provider_class, model_name
+
+
+def resolve_tti_provider_and_model(model_identifier: str) -> Tuple[Any, str]:
+    """Resolve TTI provider class and model name from model identifier."""
+    provider_class = None
+    model_name = None
+
+    # Check for explicit provider/model syntax
+    if model_identifier in AppConfig.tti_provider_map and "/" in model_identifier:
+        provider_class = AppConfig.tti_provider_map[model_identifier]
+        _, model_name = model_identifier.split("/", 1)
+    elif "/" in model_identifier:
+        provider_name, model_name = model_identifier.split("/", 1)
+        provider_class = AppConfig.tti_provider_map.get(provider_name)
+    else:
+        provider_class = AppConfig.tti_provider_map.get(AppConfig.default_tti_provider)
+        model_name = model_identifier
+
+    if not provider_class:
+        available_providers = list(set(v.__name__ for v in AppConfig.tti_provider_map.values()))
+        raise APIError(
+            f"TTI Provider for model '{model_identifier}' not found. Available TTI providers: {available_providers}",
+            HTTP_404_NOT_FOUND,
+            "model_not_found",
+            param="model"
+        )
+
+    # Validate model availability
+    if hasattr(provider_class, "AVAILABLE_MODELS") and model_name is not None:
+        available = getattr(provider_class, "AVAILABLE_MODELS", None)
+        # If it's a property, get from instance
+        if isinstance(available, property):
+            try:
+                available = getattr(provider_class(), "AVAILABLE_MODELS", [])
+            except Exception:
+                available = []
+        # If still not iterable, fallback to empty list
+        if not isinstance(available, (list, tuple, set)):
+            available = list(available) if available and hasattr(available, "__iter__") and not isinstance(available, str) else []
+        if available and model_name not in available:
+            raise APIError(
+                f"Model '{model_name}' not supported by TTI provider '{provider_class.__name__}'. Available models: {available}",
+                HTTP_404_NOT_FOUND,
+                "model_not_found",
+                param="model"
+            )
+
+    return provider_class, model_name
+
+
+def get_provider_instance(provider_class: Any):
+    """Return a cached instance of the provider, creating it if necessary."""
+    key = provider_class.__name__
+    instance = provider_instances.get(key)
+    if instance is None:
+        try:
+            instance = provider_class()
+        except TypeError as e:
+            # Handle abstract class instantiation error
+            if "abstract class" in str(e):
+                from .exceptions import APIError
+                raise APIError(
+                    f"Provider misconfiguration: Cannot instantiate abstract class '{provider_class.__name__}'. Please check the provider implementation.",
+                    HTTP_500_INTERNAL_SERVER_ERROR,
+                    "provider_error"
+                )
+            raise
+        provider_instances[key] = instance
+    return instance
+
+
+def get_tti_provider_instance(provider_class: Any):
+    """Return a cached instance of the TTI provider, creating it if needed."""
+    key = provider_class.__name__
+    instance = tti_provider_instances.get(key)
+    if instance is None:
+        try:
+            instance = provider_class()
+        except TypeError as e:
+            # Handle abstract class instantiation error
+            if "abstract class" in str(e):
+                from .exceptions import APIError
+                raise APIError(
+                    f"Provider misconfiguration: Cannot instantiate abstract class '{provider_class.__name__}'. Please check the provider implementation.",
+                    HTTP_500_INTERNAL_SERVER_ERROR,
+                    "provider_error",
+                )
+            raise
+        tti_provider_instances[key] = instance
+    return instance

webscout/server/request_models.py

@@ -0,0 +1,131 @@
+"""
+Pydantic models for API requests and responses.
+"""
+
+from typing import Dict, List, Literal, Optional, Union
+
+try:
+    from webscout.Provider.OPENAI.pydantic_imports import BaseModel, Field
+except ImportError:
+    from pydantic import BaseModel, Field
+
+
+# Define Pydantic models for multimodal content parts, aligning with OpenAI's API
+class TextPart(BaseModel):
+    """Text content part for multimodal messages."""
+    type: Literal["text"]
+    text: str
+
+
+class ImageURL(BaseModel):
+    """Image URL configuration for multimodal messages."""
+    url: str  # Can be http(s) or data URI
+    detail: Optional[Literal["auto", "low", "high"]] = Field(
+        "auto",
+        description="Specifies the detail level of the image."
+    )
+
+
+class ImagePart(BaseModel):
+    """Image content part for multimodal messages."""
+    type: Literal["image_url"]
+    image_url: ImageURL
+
+
+MessageContentParts = Union[TextPart, ImagePart]
+
+
+class Message(BaseModel):
+    """Chat message model compatible with OpenAI API."""
+    role: Literal["system", "user", "assistant", "function", "tool"]
+    content: Optional[Union[str, List[MessageContentParts]]] = Field(
+        None,
+        description="The content of the message. Can be a string, a list of content parts (for multimodal), or null."
+    )
+    name: Optional[str] = None
+
+
+class ChatCompletionRequest(BaseModel):
+    """Request model for chat completions."""
+    model: str = Field(..., description="ID of the model to use. See the model endpoint for the available models.")
+    messages: List[Message] = Field(..., description="A list of messages comprising the conversation so far.")
+    temperature: Optional[float] = Field(None, description="What sampling temperature to use, between 0 and 2.")
+    top_p: Optional[float] = Field(None, description="An alternative to sampling with temperature, called nucleus sampling.")
+    n: Optional[int] = Field(1, description="How many chat completion choices to generate for each input message.")
+    stream: Optional[bool] = Field(False, description="If set, partial message deltas will be sent, like in ChatGPT.")
+    max_tokens: Optional[int] = Field(None, description="The maximum number of tokens to generate in the chat completion.")
+    presence_penalty: Optional[float] = Field(None, description="Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far.")
+    frequency_penalty: Optional[float] = Field(None, description="Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far.")
+    logit_bias: Optional[Dict[str, float]] = Field(None, description="Modify the likelihood of specified tokens appearing in the completion.")
+    user: Optional[str] = Field(None, description="A unique identifier representing your end-user.")
+    stop: Optional[Union[str, List[str]]] = Field(None, description="Up to 4 sequences where the API will stop generating further tokens.")
+
+    class Config:
+        extra = "ignore"
+        schema_extra = {
+            "example": {
+                "model": "Cloudflare/@cf/meta/llama-4-scout-17b-16e-instruct",
+                "messages": [
+                    {"role": "system", "content": "You are a helpful assistant."},
+                    {"role": "user", "content": "Hello, how are you?"}
+                ],
+                "temperature": 0.7,
+                "max_tokens": 150,
+                "stream": False
+            }
+        }
+
+
+class ImageGenerationRequest(BaseModel):
+    """Request model for OpenAI-compatible image generation endpoint."""
+    prompt: str = Field(..., description="A text description of the desired image(s). The maximum length is 1000 characters.")
+    model: str = Field(..., description="The model to use for image generation.")
+    n: Optional[int] = Field(1, description="The number of images to generate. Must be between 1 and 10.")
+    size: Optional[str] = Field("1024x1024", description="The size of the generated images. Must be one of: '256x256', '512x512', or '1024x1024'.")
+    response_format: Optional[Literal["url", "b64_json"]] = Field("url", description="The format in which the generated images are returned.")
+    user: Optional[str] = Field(None, description="A unique identifier representing your end-user.")
+    style: Optional[str] = Field(None, description="Optional style for the image (provider/model-specific).")
+    aspect_ratio: Optional[str] = Field(None, description="Optional aspect ratio for the image (provider/model-specific).")
+    timeout: Optional[int] = Field(None, description="Optional timeout for the image generation request in seconds.")
+    image_format: Optional[str] = Field(None, description="Optional image format (e.g., 'png', 'jpeg').")
+    seed: Optional[int] = Field(None, description="Optional random seed for reproducibility.")
+
+    class Config:
+        extra = "ignore"
+        schema_extra = {
+            "example": {
+                "prompt": "A futuristic cityscape at sunset, digital art",
+                "model": "PollinationsAI/turbo",
+                "n": 1,
+                "size": "1024x1024",
+                "response_format": "url",
+                "user": "user-1234"
+            }
+        }
+
+
+class ModelInfo(BaseModel):
+    """Model information for the models endpoint."""
+    id: str
+    object: str = "model"
+    created: int
+    owned_by: str
+
+
+class ModelListResponse(BaseModel):
+    """Response model for the models list endpoint."""
+    object: str = "list"
+    data: List[ModelInfo]
+
+
+class ErrorDetail(BaseModel):
+    """Error detail structure compatible with OpenAI API."""
+    message: str
+    type: str = "server_error"
+    param: Optional[str] = None
+    code: Optional[str] = None
+
+
+class ErrorResponse(BaseModel):
+    """Error response structure compatible with OpenAI API."""
+    error: ErrorDetail