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

webscout/Provider/OPENAI/api.py

@@ -1,121 +1,282 @@
 """
-OpenAI-Compatible API Server for Webscout
+Webscout OpenAI-Compatible API Server
 
-This module provides an OpenAI-compatible API server that allows using
-various AI providers through a standardized interface compatible with
-OpenAI's API. This enables using Webscout providers with any tool or
-application designed to work with OpenAI's API.
-
-Usage:
-    # From command line:
-    python -m webscout.Provider.OPENAI.api --port 8080 --api-key "your-key"
-    
-    # From Python code:
-    from webscout.Provider.OPENAI.api import start_server
-    start_server(port=8080, api_key="your-key")
+A FastAPI-based server that provides OpenAI-compatible endpoints for various LLM providers.
+Supports streaming and non-streaming chat completions with comprehensive error handling,
+authentication, and provider management.
 """
 
 from __future__ import annotations
 
-import logging
 import json
-import uvicorn
-import secrets
+import logging
 import os
-import uuid
+import secrets
+import sys
 import time
-from pathlib import Path
-from typing import List, Dict, Optional, Union, Any, Generator
-from fastapi import FastAPI, Response, Request, Depends
-from fastapi.middleware.cors import CORSMiddleware
-from fastapi.responses import StreamingResponse, RedirectResponse, HTMLResponse, JSONResponse, FileResponse
-from fastapi.staticfiles import StaticFiles
+import uuid
+import inspect
+import re
+import codecs
+from typing import List, Dict, Optional, Union, Any, Generator, Callable
+import types
 
+import uvicorn
+from fastapi import FastAPI, Response, Request, Body
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import StreamingResponse, RedirectResponse, JSONResponse
+from fastapi.openapi.utils import get_openapi
+from fastapi.routing import APIRoute
 from fastapi.exceptions import RequestValidationError
 from fastapi.security import APIKeyHeader
-from starlette.exceptions import HTTPException
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+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)
 from starlette.status import (
-    HTTP_200_OK,
-    HTTP_422_UNPROCESSABLE_ENTITY, 
+    HTTP_422_UNPROCESSABLE_ENTITY,
     HTTP_404_NOT_FOUND,
     HTTP_401_UNAUTHORIZED,
     HTTP_403_FORBIDDEN,
     HTTP_500_INTERNAL_SERVER_ERROR,
 )
-from fastapi.encoders import jsonable_encoder
-from pydantic import BaseModel, Field
-from typing import List, Optional, Literal, Union
+
+from webscout.Provider.OPENAI.pydantic_imports import BaseModel, Field
+from typing import Literal
 
 # Import provider classes from the OPENAI directory
 from webscout.Provider.OPENAI import *
 from webscout.Provider.OPENAI.utils import (
-    ChatCompletionChunk, ChatCompletion, Choice, ChoiceDelta,
-    ChatCompletionMessage, CompletionUsage
+    ChatCompletion, Choice, ChatCompletionMessage, CompletionUsage
 )
 
-logger = logging.getLogger(__name__)
 
+# Configuration constants
 DEFAULT_PORT = 8000
+DEFAULT_HOST = "0.0.0.0"
+API_VERSION = "v1"
+
+# Setup logging
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    handlers=[
+        logging.StreamHandler(sys.stdout),
+    ]
+)
+logger = logging.getLogger("webscout.api")
+
+
+class ServerConfig:
+    """Centralized configuration management for the API server."""
+
+    def __init__(self):
+        self.api_key: Optional[str] = None
+        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
+
+    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)
+                logger.info(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()))
+            logger.warning(f"Default provider '{self.default_provider}' not found. Available: {available_providers}")
+
+
+# Global configuration instance
+config = ServerConfig()
+
+
+# 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: str
+    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
+    # Future: Add tool_calls and tool_call_id for function calling support
+    # tool_calls: Optional[List[ToolCall]] = None
+    # tool_call_id: Optional[str] = None
 
 class ChatCompletionRequest(BaseModel):
-    model: str
-    messages: List[Message]
-    temperature: Optional[float] = None
-    top_p: Optional[float] = None
-    n: Optional[int] = 1
-    stream: Optional[bool] = False
-    max_tokens: Optional[int] = None
-    presence_penalty: Optional[float] = None
-    frequency_penalty: Optional[float] = None
-    logit_bias: Optional[Dict[str, float]] = None
-    user: Optional[str] = None
-    stop: Optional[Union[str, List[str]]] = None
-    
+    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. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.")
+    top_p: Optional[float] = Field(None, description="An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.")
+    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. Tokens will be sent as data-only server-sent events as they become available, with the stream terminated by a data: [DONE] message.")
+    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, increasing the model's likelihood to talk about new topics.")
+    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, decreasing the model's likelihood to repeat the same line verbatim.")
+    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, which can help the API to monitor and detect abuse.")
+    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"  # Ignore extra fields that aren't in the model
+        schema_extra = {
+            "example": {
+                "model": "ChatGPT/gpt-4o",
+                "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 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[Dict[str, Any]]
+    data: List[ModelInfo]
 
-class ErrorResponse(Response):
-    media_type = "application/json"
 
-    @classmethod
-    def from_exception(cls, exception: Exception, status_code: int = HTTP_500_INTERNAL_SERVER_ERROR):
-        return cls(format_exception(exception), status_code)
+class ErrorDetail(BaseModel):
+    """Error detail structure compatible with OpenAI API."""
+    message: str
+    type: str = "server_error"
+    param: Optional[str] = None
+    code: Optional[str] = None
 
-    @classmethod
-    def from_message(cls, message: str, status_code: int = HTTP_500_INTERNAL_SERVER_ERROR, headers: dict = None):
-        return cls(format_exception(message), status_code, headers=headers)
 
-    def render(self, content) -> bytes:
-        return str(content).encode(errors="ignore")
+class ErrorResponse(BaseModel):
+    """Error response structure compatible with OpenAI API."""
+    error: ErrorDetail
+
+
+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)
+        )
+
 
 class AppConfig:
+    """Legacy configuration class for backward compatibility."""
     api_key: Optional[str] = None
     provider_map = {}
     default_provider = "ChatGPT"
+    base_url: Optional[str] = None
 
     @classmethod
     def set_config(cls, **data):
+        """Set configuration values."""
         for key, value in data.items():
             setattr(cls, key, value)
+        # Sync with new config system
+        config.update(**data)
+
+# Custom route class to handle dynamic base URLs
+# Note: The /docs 404 issue is likely related to server execution (Werkzeug logs vs. Uvicorn script).
+# This DynamicBaseRoute, when AppConfig.base_url is None, should act as a passthrough and not break /docs.
+# If AppConfig.base_url is set, this route class has limitations in correctly handling prefixed routes
+# without more complex path manipulation or using FastAPI's APIRouter prefixing/mounting features.
+class DynamicBaseRoute(APIRoute):
+    def get_route_handler(self) -> Callable:
+        original_route_handler = super().get_route_handler()
+        async def custom_route_handler(request: Request) -> Response:
+            if AppConfig.base_url:
+                if not request.url.path.startswith(AppConfig.base_url):
+                    # This logic might need refinement if base_url is used.
+                    # For API routes not matching the prefix, a 404 might be appropriate.
+                    # Docs routes (/docs, /openapi.json) are usually at the root.
+                    # The current 'pass' allows root docs even if base_url is set for APIs.
+                    pass
+            return await original_route_handler(request)
+        return custom_route_handler
 
 def create_app():
     app = FastAPI(
         title="Webscout OpenAI API",
         description="OpenAI API compatible interface for various LLM providers",
         version="0.1.0",
-        docs_url=None,
+        docs_url="/docs",
+        redoc_url="/redoc",
+        openapi_url="/openapi.json",
     )
-    
-    # Add CORS middleware to allow cross-origin requests
+    app.router.route_class = DynamicBaseRoute
     app.add_middleware(
         CORSMiddleware,
         allow_origins=["*"],
@@ -123,65 +284,121 @@ def create_app():
         allow_methods=["*"],
         allow_headers=["*"],
     )
-    
     api = Api(app)
     api.register_authorization()
-    api.register_json_middleware()  # Add custom JSON middleware
     api.register_validation_exception_handler()
     api.register_routes()
-    
-    # Initialize provider map
     initialize_provider_map()
-    
+
+    def custom_openapi():
+        if app.openapi_schema:
+            return app.openapi_schema
+
+        openapi_schema = get_openapi(
+            title=app.title,
+            version=app.version,
+            description=app.description,
+            routes=app.routes,
+        )
+
+        if "components" not in openapi_schema: openapi_schema["components"] = {}
+        if "schemas" not in openapi_schema["components"]: openapi_schema["components"]["schemas"] = {}
+
+        # Use Pydantic's schema generation for accuracy
+        # Assuming Pydantic v1 .schema() or v2 .model_json_schema() based on pydantic_imports
+        # For broader compatibility, trying .schema() first.
+        # If using Pydantic v2 primarily, .model_json_schema() is preferred.
+        schema_method_name = "model_json_schema" if hasattr(BaseModel, "model_json_schema") else "schema"
+
+        # Add/update schemas derived from Pydantic models to ensure they are correctly defined
+        pydantic_models_to_register = {
+            "TextPart": TextPart,
+            "ImageURL": ImageURL,
+            "ImagePart": ImagePart,
+            "Message": Message,
+            "ChatCompletionRequest": ChatCompletionRequest,
+        }
+
+        for name, model_cls in pydantic_models_to_register.items():
+            if schema_method_name == "model_json_schema":
+                schema_data = model_cls.model_json_schema(ref_template="#/components/schemas/{model}")
+            else:
+                schema_data = model_cls.schema()
+            # Pydantic might add a "title" to the schema, which is often not desired for component schemas
+            if "title" in schema_data:
+                del schema_data["title"]
+            openapi_schema["components"]["schemas"][name] = schema_data
+
+        app.openapi_schema = openapi_schema
+        return app.openapi_schema
+
+    app.openapi = custom_openapi
     return app
 
 def create_app_debug():
-    logging.basicConfig(level=logging.DEBUG)
     return create_app()
 
-def initialize_provider_map():
-    """Initialize the provider map with available provider classes"""
-    import sys
-    import inspect
-    from webscout.Provider.OPENAI.base import OpenAICompatibleProvider
-    
-    # Get all imported modules from OPENAI package
-    module = sys.modules["webscout.Provider.OPENAI"]
-    
-    # Find all provider classes (subclasses of OpenAICompatibleProvider)
-    for name, obj in inspect.getmembers(module):
-        if inspect.isclass(obj) and issubclass(obj, OpenAICompatibleProvider) and obj.__name__ != "OpenAICompatibleProvider":
-            # Register the provider class by its name
-            AppConfig.provider_map[obj.__name__] = obj
-            logger.info(f"Registered provider: {obj.__name__}")
-            
-            # Also add additional mappings for model names
-            if hasattr(obj, "AVAILABLE_MODELS") and isinstance(obj.AVAILABLE_MODELS, (list, tuple, set)):
-                for model in obj.AVAILABLE_MODELS:
-                    if model and isinstance(model, str) and model != obj.__name__:
-                        AppConfig.provider_map[model] = obj
-                        logger.info(f"Mapped model {model} to provider {obj.__name__}")
-    
-    # If no providers were found, add a fallback for testing
-    if not AppConfig.provider_map:
-        logger.warning("No providers found, using ChatGPT as fallback")
-        from webscout.Provider.OPENAI.chatgpt import ChatGPT
-        AppConfig.provider_map["ChatGPT"] = ChatGPT
-        AppConfig.provider_map["gpt-4"] = ChatGPT
-        AppConfig.provider_map["gpt-4o"] = ChatGPT
-        AppConfig.provider_map["gpt-4o-mini"] = ChatGPT
-        AppConfig.default_provider = "ChatGPT"
-    
-    # Get distinct provider names
-    provider_names = list(set(v.__name__ for v in AppConfig.provider_map.values()))
-    
-    # Get model names (excluding provider class names)
-    provider_class_names = set(v.__name__ for v in AppConfig.provider_map.values())
-    model_names = [model for model in AppConfig.provider_map.keys() if model not in provider_class_names]
-    
-    logger.info(f"Available providers ({len(provider_names)}): {provider_names}")
-    logger.info(f"Available models ({len(model_names)}): {sorted(model_names)}")
-    logger.info(f"Default provider: {AppConfig.default_provider}")
+def initialize_provider_map() -> None:
+    """Initialize the provider map by discovering available providers."""
+    logger.info("Initializing provider map...")
+
+    try:
+        from webscout.Provider.OPENAI.base import OpenAICompatibleProvider
+        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"
+            ):
+                provider_name = obj.__name__
+                AppConfig.provider_map[provider_name] = obj
+                config.provider_map[provider_name] = obj
+                provider_count += 1
+
+                # Register available models for this provider
+                if hasattr(obj, "AVAILABLE_MODELS") and isinstance(
+                    obj.AVAILABLE_MODELS, (list, tuple, set)
+                ):
+                    for model in obj.AVAILABLE_MODELS:
+                        if model and isinstance(model, str):
+                            model_key = f"{provider_name}/{model}"
+                            AppConfig.provider_map[model_key] = obj
+                            config.provider_map[model_key] = obj
+                            model_count += 1
+
+        # Fallback to ChatGPT if no providers found
+        if not AppConfig.provider_map:
+            logger.warning("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
+                config.provider_map["ChatGPT"] = ChatGPT
+
+                for model in fallback_models:
+                    model_key = f"ChatGPT/{model}"
+                    AppConfig.provider_map[model_key] = ChatGPT
+                    config.provider_map[model_key] = ChatGPT
+
+                AppConfig.default_provider = "ChatGPT"
+                config.default_provider = "ChatGPT"
+                provider_count = 1
+                model_count = len(fallback_models)
+            except ImportError as e:
+                logger.error(f"Failed to import ChatGPT fallback: {e}")
+                raise APIError("No providers available", HTTP_500_INTERNAL_SERVER_ERROR)
+
+        logger.info(f"Initialized {provider_count} providers with {model_count} models")
+
+    except Exception as e:
+        logger.error(f"Failed to initialize provider map: {e}")
+        raise APIError(f"Provider initialization failed: {e}", HTTP_500_INTERNAL_SERVER_ERROR)
 
 class Api:
     def __init__(self, app: FastAPI) -> None:
@@ -194,522 +411,498 @@ class Api:
             if AppConfig.api_key is not None:
                 auth_header = await self.get_api_key(request)
                 path = request.url.path
-                if path.startswith("/v1"):
+                if path.startswith("/v1"): # Only protect /v1 routes
+                    # Also allow access to /docs, /openapi.json etc. if AppConfig.base_url is not set or path is not under it
+                    # This logic should be fine as it only protects /v1 paths
                     if auth_header is None:
                         return ErrorResponse.from_message("API key required", HTTP_401_UNAUTHORIZED)
-                    # Strip "Bearer " prefix if present
                     if auth_header.startswith("Bearer "):
                         auth_header = auth_header[7:]
-                    if AppConfig.api_key is None or not secrets.compare_digest(AppConfig.api_key, auth_header):
+                    if AppConfig.api_key is None or not secrets.compare_digest(AppConfig.api_key, auth_header): # AppConfig.api_key check is redundant after outer if
                         return ErrorResponse.from_message("Invalid API key", HTTP_403_FORBIDDEN)
             return await call_next(request)
 
-    def register_json_middleware(self):
-        @self.app.middleware("http")
-        async def parse_json_middleware(request: Request, call_next):
-            if request.method == "POST" and "/v1/chat/completions" in request.url.path:
-                try:
-                    # Try parsing the JSON body manually first to catch JSON errors early
-                    body = await request.body()
-                    if body:
-                        body_str = body.decode('utf-8', errors='ignore')
-                        original_body = body_str
-                        logger.debug(f"Original request body: {body_str}")
-                        
-                        # PowerShell with curl often has formatting issues with JSON
-                        try:
-                            # First try normal JSON parsing
-                            json.loads(body_str)
-                            logger.debug("JSON parsed successfully")
-                        except json.JSONDecodeError as e:
-                            logger.warning(f"JSON parse error, attempting fixes: {str(e)}")
-                            
-                            # Series of fixes to try for common PowerShell JSON issues
-                            try:
-                                # Fix 1: Try to clean up the JSON string
-                                # Replace literal backslash+quote with just quote
-                                body_str = body_str.replace("\\\"", "\"")
-                                # Add double quotes to unquoted property names and string values
-                                # This is a common issue with PowerShell's curl
-                                import re
-                                
-                                # Try a full JSON correction - replace single quotes with double quotes
-                                # This is a more aggressive fix that might work in simple cases
-                                fixed_body = body_str.replace("'", "\"")
-                                try:
-                                    json.loads(fixed_body)
-                                    body_str = fixed_body
-                                    logger.info("Fixed JSON by replacing single quotes with double quotes")
-                                except json.JSONDecodeError:
-                                    # If that didn't work, try more sophisticated fixes
-                                    pass
-                                
-                                # Check for missing quotes around property names
-                                # Look for patterns like {model: instead of {"model":
-                                body_str = re.sub(r'\{([^"\s][^:\s]*)(\s*:)', r'{"\1"\2', body_str)
-                                body_str = re.sub(r',\s*([^"\s][^:\s]*)(\s*:)', r', "\1"\2', body_str)
-                                
-                                # Try to parse with the fixed body
-                                json.loads(body_str)
-                                # If successful, modify the request._body for downstream processing
-                                logger.info(f"Successfully fixed JSON format\nOriginal: {original_body}\nFixed: {body_str}")
-                                request._body = body_str.encode('utf-8')
-                            except Exception as fix_error:
-                                logger.error(f"Failed to fix JSON: {str(fix_error)}")
-                                
-                                # Let's return a helpful error message with the proper format example
-                                example = json.dumps({
-                                    "model": "gpt-4",
-                                    "messages": [{"role": "user", "content": "Hello"}]
-                                })
-                                return JSONResponse(
-                                    status_code=HTTP_422_UNPROCESSABLE_ENTITY,
-                                    content=jsonable_encoder({
-                                        "detail": [
-                                            {
-                                                "loc": ["body", 0],
-                                                "message": f"Invalid JSON format: {str(e)}. Make sure to use double quotes for both keys and values. Example: {example}",
-                                                "type": "json_invalid"
-                                            }
-                                        ]
-                                    }),
-                                )
-                except Exception as e:
-                    error_detail = str(e)
-                    logger.error(f"Request processing error: {error_detail}")
-                    return JSONResponse(
-                        status_code=HTTP_422_UNPROCESSABLE_ENTITY,
-                        content=jsonable_encoder({
-                            "detail": [
-                                {
-                                    "loc": ["body", 0],
-                                    "message": f"Request processing error: {error_detail}",
-                                    "type": "request_invalid"
-                                }
-                            ]
-                        }),
-                    )
-            return await call_next(request)
-
     def register_validation_exception_handler(self):
+        """Register comprehensive exception handlers."""
+
+        @self.app.exception_handler(APIError)
+        async def api_error_handler(request: Request, exc: APIError):
+            """Handle custom API errors."""
+            logger.error(f"API Error: {exc.message} (Status: {exc.status_code})")
+            return exc.to_response()
+
         @self.app.exception_handler(RequestValidationError)
         async def validation_exception_handler(request: Request, exc: RequestValidationError):
-            details = exc.errors()
-            modified_details = []
-            for error in details:
-                modified_details.append({
-                    "loc": error["loc"],
-                    "message": error["msg"],
-                    "type": error["type"],
-                })
+            errors = exc.errors()
+            error_messages = []
+            body = await request.body()
+            is_empty_body = not body or body.strip() in (b"", b"null", b"{}")
+            for error in errors:
+                loc = error.get("loc", [])
+                # Ensure loc_str is user-friendly
+                loc_str_parts = []
+                for item in loc:
+                    if item == "body": # Skip "body" part if it's the first element of a longer path
+                        if len(loc) > 1: continue
+                    loc_str_parts.append(str(item))
+                loc_str = " -> ".join(loc_str_parts)
+
+                msg = error.get("msg", "Validation error")
+
+                # Check if this error is for the 'content' field specifically due to multimodal input
+                if len(loc) >=3 and loc[0] == 'body' and loc[1] == 'messages' and loc[-1] == 'content':
+                     # Check if the error type suggests a string was expected but a list (or vice-versa) was given for content
+                    if "Input should be a valid string" in msg and error.get("input_type") == "list":
+                         error_messages.append({
+                            "loc": loc,
+                            "message": f"Invalid message content: {msg}. Ensure content matches the expected format (string or list of content parts). Path: {loc_str}",
+                            "type": error.get("type", "validation_error")
+                        })
+                         continue # Skip default message formatting for this specific case
+                    elif "Input should be a valid list" in msg and error.get("input_type") == "string":
+                         error_messages.append({
+                            "loc": loc,
+                            "message": f"Invalid message content: {msg}. Ensure content matches the expected format (string or list of content parts). Path: {loc_str}",
+                            "type": error.get("type", "validation_error")
+                        })
+                         continue
+
+                if "body" in loc:
+                    if len(loc) > 1 and loc[1] == "messages":
+                        error_messages.append({
+                            "loc": loc,
+                            "message": "The 'messages' field is required and must be a non-empty array of message objects. " + f"Error: {msg} at {loc_str}",
+                            "type": error.get("type", "validation_error")
+                        })
+                    elif len(loc) > 1 and loc[1] == "model":
+                        error_messages.append({
+                            "loc": loc,
+                            "message": "The 'model' field is required and must be a string. " + f"Error: {msg} at {loc_str}",
+                            "type": error.get("type", "validation_error")
+                        })
+                    else:
+                        error_messages.append({
+                            "loc": loc,
+                            "message": f"{msg} at {loc_str}",
+                            "type": error.get("type", "validation_error")
+                        })
+                else:
+                    error_messages.append({
+                        "loc": loc,
+                        "message": f"{msg} at {loc_str}",
+                        "type": error.get("type", "validation_error")
+                    })
+            if request.url.path == "/v1/chat/completions":
+                example = ChatCompletionRequest.Config.schema_extra["example"]
+                if is_empty_body:
+                    return JSONResponse(
+                        status_code=HTTP_422_UNPROCESSABLE_ENTITY,
+                        content={
+                            "error": {
+                                "message": "Request body is required and must include 'model' and 'messages'.",
+                                "type": "invalid_request_error",
+                                "param": None,
+                                "code": "body_missing"
+                            },
+                            "example": example
+                        }
+                    )
+                return JSONResponse(
+                    status_code=HTTP_422_UNPROCESSABLE_ENTITY,
+                    content={"detail": error_messages, "example": example}
+                )
             return JSONResponse(
                 status_code=HTTP_422_UNPROCESSABLE_ENTITY,
-                content=jsonable_encoder({"detail": modified_details}),
+                content={"detail": error_messages}
             )
-            
-        @self.app.exception_handler(HTTPException)
-        async def http_exception_handler(request: Request, exc: HTTPException):
+        @self.app.exception_handler(StarletteHTTPException)
+        async def http_exception_handler(request: Request, exc: StarletteHTTPException):
             return JSONResponse(
                 status_code=exc.status_code,
-                content=jsonable_encoder({"detail": exc.detail}),
+                content={"detail": exc.detail}
             )
-            
-        @self.app.exception_handler(json.JSONDecodeError)
-        async def json_decode_error_handler(request: Request, exc: json.JSONDecodeError):
+        @self.app.exception_handler(Exception)
+        async def general_exception_handler(request: Request, exc: Exception):
             return JSONResponse(
-                status_code=HTTP_422_UNPROCESSABLE_ENTITY,
-                content=jsonable_encoder({
-                    "detail": [
-                        {
-                            "loc": ["body", 0],
-                            "message": f"Invalid JSON format: {str(exc)}",
-                            "type": "json_invalid"
-                        }
-                    ]
-                }),
+                status_code=HTTP_500_INTERNAL_SERVER_ERROR,
+                content={"detail": f"Internal server error: {str(exc)}"}
             )
 
     def register_routes(self):
-        @self.app.get("/")
-        async def read_root(request: Request):
-            return RedirectResponse(url="/docs")
-
-        @self.app.get("/v1")
-        async def read_root_v1(request: Request):
+        @self.app.get("/", include_in_schema=False)
+        async def root():
+            # Note: If /docs is 404ing, check if server is Uvicorn (expected) or Werkzeug (from logs).
+            # Werkzeug logs suggest possible execution of a Flask app or WSGI misconfiguration.
+            # This api.py file is intended for Uvicorn.
             return RedirectResponse(url="/docs")
 
-        @self.app.get("/docs", include_in_schema=False)
-        async def custom_swagger_ui(request: Request):
-            from fastapi.openapi.docs import get_swagger_ui_html
-            return get_swagger_ui_html(
-                openapi_url=self.app.openapi_url,
-                title=f"{self.app.title} - Swagger UI"
-            )
-
-        @self.app.get("/v1//models", include_in_schema=False)  # Handle double slash case
-        async def list_models_double_slash():
-            """Redirect double slash models endpoint to the correct one"""
-            return RedirectResponse(url="/v1/models")
-            
-        @self.app.get("/v1/models")
+        @self.app.get("/v1/models", response_model=ModelListResponse)
         async def list_models():
-            """List available models"""
-            from webscout.Provider.OPENAI.utils import ModelData, ModelList
-            models_data = []
-
-            # Get current timestamp
-            created_time = int(time.time())
-
+            models = []
             for model_name, provider_class in AppConfig.provider_map.items():
-                if not hasattr(provider_class, "AVAILABLE_MODELS") or model_name in provider_class.AVAILABLE_MODELS:
-                    # Create a more detailed model data object with proper fields
-                    model = ModelData(
-                        id=model_name,
-                        created=created_time,
-                        owned_by=getattr(provider_class, "__name__", "webscout"),
-                        permission=[{
-                            "id": f"modelperm-{model_name}",
-                            "object": "model_permission",
-                            "created": created_time,
-                            "allow_create_engine": False,
-                            "allow_sampling": True,
-                            "allow_logprobs": True,
-                            "allow_search_indices": hasattr(provider_class, "supports_embeddings") and provider_class.supports_embeddings,
-                            "allow_view": True,
-                            "allow_fine_tuning": False,
-                            "organization": "*",
-                            "group": None,
-                            "is_blocking": False
-                        }]
-                    )
-                    models_data.append(model)
-            
-            # Return as ModelList for proper formatting
-            response = ModelList(data=models_data)
-            return response.to_dict()
-
-        @self.app.get("/v1/models/{model_name}")
-        async def get_model(model_name: str):
-            """Get information about a specific model"""
-            from webscout.Provider.OPENAI.utils import ModelData
-            created_time = int(time.time())
-            
-            # Check if the model exists in our provider map
-            if model_name in AppConfig.provider_map:
-                provider_class = AppConfig.provider_map[model_name]
-                
-                # Create a proper OpenAI-compatible model response
-                model = ModelData(
-                    id=model_name,
-                    created=created_time,
-                    owned_by=getattr(provider_class, "__name__", "webscout"),
-                    permission=[{
-                        "id": f"modelperm-{model_name}",
-                        "object": "model_permission",
-                        "created": created_time,
-                        "allow_create_engine": False,
-                        "allow_sampling": True,
-                        "allow_logprobs": True,
-                        "allow_search_indices": hasattr(provider_class, "supports_embeddings") and provider_class.supports_embeddings,
-                        "allow_view": True,
-                        "allow_fine_tuning": False,
-                        "organization": "*",
-                        "group": None,
-                        "is_blocking": False
-                    }]
-                )
-                return model.to_dict()
-            
-            # If we reached here, the model was not found
-            return ErrorResponse.from_message(f"Model '{model_name}' not found", HTTP_404_NOT_FOUND)
-
-        @self.app.post("/v1/chat/completions")
-        async def chat_completions(request: Request):
-            """Create a chat completion"""
-            # First manually extract the request body to better handle parsing errors
-            try:
-                # Note: We don't need to parse JSON here as our middleware already handles that
-                # and fixes PowerShell JSON issues
-                body = await request.json()
-                logger.debug(f"Request body parsed successfully: {body}")
-                
-                # Check for required fields
-                if "model" not in body:
-                    return JSONResponse(
-                        status_code=HTTP_422_UNPROCESSABLE_ENTITY,
-                        content=jsonable_encoder({
-                            "detail": [
-                                {
-                                    "loc": ["body", "model"],
-                                    "message": "Field 'model' is required",
-                                    "type": "missing"
-                                }
-                            ]
-                        }),
-                    )
-                    
-                if "messages" not in body or not isinstance(body["messages"], list) or len(body["messages"]) == 0:
-                    return JSONResponse(
-                        status_code=HTTP_422_UNPROCESSABLE_ENTITY,
-                        content=jsonable_encoder({
-                            "detail": [
-                                {
-                                    "loc": ["body", "messages"],
-                                    "message": "Field 'messages' must be a non-empty array",
-                                    "type": "missing"
-                                }
-                            ]
-                        }),
-                    )
-                
-                # Now parse it through Pydantic model
-                try:
-                    chat_request = ChatCompletionRequest(**body)
-                except Exception as validation_error:
-                    logger.warning(f"Validation error: {validation_error}")
-                    # Try to provide helpful error messages for common validation issues
-                    error_msg = str(validation_error)
-                    if "role" in error_msg:
-                        return JSONResponse(
-                            status_code=HTTP_422_UNPROCESSABLE_ENTITY,
-                            content=jsonable_encoder({
-                                "detail": [
-                                    {
-                                        "loc": ["body", "messages", 0, "role"],
-                                        "message": "Each message must have a 'role' field with one of these values: 'system', 'user', 'assistant'",
-                                        "type": "value_error"
-                                    }
-                                ]
-                            }),
-                        )
-                    elif "content" in error_msg:
-                        return JSONResponse(
-                            status_code=HTTP_422_UNPROCESSABLE_ENTITY,
-                            content=jsonable_encoder({
-                                "detail": [
-                                    {
-                                        "loc": ["body", "messages", 0, "content"],
-                                        "message": "Each message must have a 'content' field with string value",
-                                        "type": "value_error"
-                                    }
-                                ]
-                            }),
-                        )
-                    else:
-                        return JSONResponse(
-                            status_code=HTTP_422_UNPROCESSABLE_ENTITY,
-                            content=jsonable_encoder({
-                                "detail": [
-                                    {
-                                        "loc": ["body"],
-                                        "message": f"Validation error: {error_msg}",
-                                        "type": "value_error"
-                                    }
-                                ]
-                            }),
-                        )
-                        
-            except json.JSONDecodeError as e:
-                logger.error(f"JSON decode error in chat_completions: {e}")
-                example = json.dumps({
-                    "model": "gpt-4",
-                    "messages": [{"role": "user", "content": "Hello"}]
+                if "/" not in model_name:
+                    continue  # Skip provider names
+                if any(m["id"] == model_name for m in models):
+                    continue
+                models.append({
+                    "id": model_name,
+                    "object": "model",
+                    "created": int(time.time()),
+                    "owned_by": provider_class.__name__
                 })
-                return JSONResponse(
-                    status_code=HTTP_422_UNPROCESSABLE_ENTITY,
-                    content=jsonable_encoder({
-                        "detail": [
-                            {
-                                "loc": ["body", 0],
-                                "message": f"Invalid JSON format: {str(e)}. Example of correct format: {example}",
-                                "type": "json_invalid"
-                            }
-                        ]
-                    }),
-                )
-            except Exception as e:
-                logger.exception(f"Unexpected error in chat_completions: {e}")
-                return ErrorResponse.from_message(
-                    f"Invalid request parameters: {str(e)}",
-                    HTTP_422_UNPROCESSABLE_ENTITY
-                )
-            """Create a chat completion"""
+            return {
+                "object": "list",
+                "data": models
+            }
+
+        @self.app.post(
+            "/v1/chat/completions",
+            response_model_exclude_none=True,
+            response_model_exclude_unset=True,
+            openapi_extra={ # This ensures the example is shown in docs
+                "requestBody": {
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "$ref": "#/components/schemas/ChatCompletionRequest" # Relies on custom_openapi
+                            },
+                            "example": ChatCompletionRequest.Config.schema_extra["example"]
+                        }
+                    }
+                }
+            }
+        )
+        async def chat_completions(
+            chat_request: ChatCompletionRequest = Body(...)
+        ):
+            """Handle chat completion requests with comprehensive error handling."""
+            start_time = time.time()
+            request_id = f"chatcmpl-{uuid.uuid4()}"
+
             try:
-                # Determine which provider to use based on the model
-                provider_class = None
-                model = chat_request.model
-                logger.info(f"Chat completion request for model: {model}")
-                
-                if model in AppConfig.provider_map:
-                    provider_class = AppConfig.provider_map[model]
-                    logger.info(f"Found provider class for model {model}: {provider_class.__name__}")
-                else:
-                    # Use default provider if specific provider not found
-                    provider_class = AppConfig.provider_map.get(AppConfig.default_provider)
-                    logger.info(f"Using default provider {AppConfig.default_provider} for model {model}")
-
-                if not provider_class:
-                    logger.error(f"No provider available for model {model}. Available models: {list(AppConfig.provider_map.keys())}")
-                    return ErrorResponse.from_message(
-                        f"Model '{model}' not supported. Available models: {list(AppConfig.provider_map.keys())}",
-                        HTTP_404_NOT_FOUND
-                    )
+                logger.info(f"Processing chat completion request {request_id} for model: {chat_request.model}")
+
+                # Resolve provider and model
+                provider_class, model_name = resolve_provider_and_model(chat_request.model)
 
-                # Initialize provider
-                logger.info(f"Initializing provider {provider_class.__name__}")
+                # Initialize provider with error handling
                 try:
                     provider = provider_class()
+                    logger.debug(f"Initialized provider: {provider_class.__name__}")
                 except Exception as e:
-                    logger.exception(f"Failed to initialize provider {provider_class.__name__}: {e}")
-                    return ErrorResponse.from_message(
+                    logger.error(f"Failed to initialize provider {provider_class.__name__}: {e}")
+                    raise APIError(
                         f"Failed to initialize provider {provider_class.__name__}: {e}",
-                        HTTP_500_INTERNAL_SERVER_ERROR
+                        HTTP_500_INTERNAL_SERVER_ERROR,
+                        "provider_error"
                     )
 
-                # Prepare completion parameters
-                # Convert Message objects to dictionaries for the provider
-                messages = []
-                for msg in chat_request.messages:
-                    message_dict = {
-                        "role": msg.role,
-                        "content": msg.content
-                    }
-                    # Add name field if present
-                    if msg.name:  
-                        message_dict["name"] = msg.name
-                    messages.append(message_dict)
-                
-                params = {
-                    "model": model,
-                    "messages": messages,
-                    "stream": chat_request.stream,
-                }
+                # Process and validate messages
+                processed_messages = process_messages(chat_request.messages)
 
-                # Add optional parameters if provided
-                if chat_request.temperature is not None:
-                    params["temperature"] = chat_request.temperature
-                if chat_request.max_tokens is not None:
-                    params["max_tokens"] = chat_request.max_tokens
-                if chat_request.top_p is not None:
-                    params["top_p"] = chat_request.top_p
+                # Prepare parameters for provider
+                params = prepare_provider_params(chat_request, model_name, processed_messages)
 
-                # Create completion
+                # Handle streaming vs non-streaming
                 if chat_request.stream:
-                    async def streaming():
-                        try:
-                            logger.info(f"Creating streaming completion with {provider_class.__name__}")
-                            completion_stream = provider.chat.completions.create(**params)
-                            logger.info(f"Got streaming response: {type(completion_stream)}")
-                            
-                            if isinstance(completion_stream, Generator):
-                                for chunk in completion_stream:
-                                    logger.debug(f"Streaming chunk: {type(chunk)}")
-                                    if hasattr(chunk, 'to_dict'):
-                                        # Use to_dict() for our custom dataclasses
-                                        yield f"data: {json.dumps(chunk.to_dict())}\n\n"
-                                    elif hasattr(chunk, 'model_dump'):
-                                        # For Pydantic models
-                                        yield f"data: {json.dumps(chunk.model_dump())}\n\n"
-                                    else:
-                                        # For dictionaries or other JSON-serializable objects
-                                        yield f"data: {json.dumps(chunk)}\n\n"
-                            else:
-                                # If the provider doesn't implement streaming but stream=True,
-                                # simulate streaming with a single chunk
-                                logger.info(f"Provider returned non-streaming response, simulating stream")
-                                yield f"data: {json.dumps(completion_stream)}\n\n"
-                        except Exception as e:
-                            logger.exception(f"Error in streaming: {e}")
-                            yield f"data: {format_exception(e)}\n\n"
-                        yield "data: [DONE]\n\n"
-
-                    return StreamingResponse(streaming(), media_type="text/event-stream")
+                    return await handle_streaming_response(provider, params, request_id)
                 else:
-                    logger.info(f"Creating non-streaming completion with {provider_class.__name__}")
-                    try:
-                        completion = provider.chat.completions.create(**params)
-                        logger.info(f"Got completion response: {type(completion)}")
-                        
-                        # If the response is empty or None, create a default response
-                        if completion is None:
-                            logger.warning(f"Provider {provider_class.__name__} returned None for completion")
-                            return {
-                                "id": f"chatcmpl-{uuid.uuid4()}",
-                                "created": int(time.time()),
-                                "model": model,
-                                "choices": [
-                                    {
-                                        "index": 0,
-                                        "message": {
-                                            "role": "assistant",
-                                            "content": "I apologize, but I couldn't generate a response. Please try again or try a different model.",
-                                        },
-                                        "finish_reason": "stop",
-                                    }
-                                ],
-                                "usage": {
-                                    "prompt_tokens": 0,
-                                    "completion_tokens": 0,
-                                    "total_tokens": 0,
-                                },
-                            }
-                            
-                        # Return the response in the appropriate format
-                        if isinstance(completion, dict):
-                            return completion
-                        elif hasattr(completion, "model_dump"):
-                            return completion.model_dump()
-                        else:
-                            return completion
-                    except Exception as e:
-                        logger.exception(f"Error in completion: {e}")
-                        return ErrorResponse.from_exception(e, HTTP_500_INTERNAL_SERVER_ERROR)
+                    return await handle_non_streaming_response(provider, params, request_id, start_time)
 
+            except APIError:
+                # Re-raise API errors as-is
+                raise
             except Exception as e:
-                logger.exception(e)
-                return ErrorResponse.from_exception(e, HTTP_500_INTERNAL_SERVER_ERROR)
+                logger.error(f"Unexpected error in chat completion {request_id}: {e}")
+                raise APIError(
+                    f"Internal server error: {str(e)}",
+                    HTTP_500_INTERNAL_SERVER_ERROR,
+                    "internal_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 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 process_messages(messages: List[Message]) -> List[Dict[str, Any]]:
+    """Process and validate chat messages."""
+    processed_messages = []
+
+    for i, msg_in in enumerate(messages):
+        try:
+            message_dict_out = {"role": msg_in.role}
+
+            if msg_in.content is None:
+                message_dict_out["content"] = None
+            elif isinstance(msg_in.content, str):
+                message_dict_out["content"] = msg_in.content
+            else:  # List[MessageContentParts]
+                message_dict_out["content"] = [
+                    part.model_dump(exclude_none=True) for part in msg_in.content
+                ]
+
+            if msg_in.name:
+                message_dict_out["name"] = msg_in.name
+
+            processed_messages.append(message_dict_out)
+
+        except Exception as e:
+            raise APIError(
+                f"Invalid message at index {i}: {str(e)}",
+                HTTP_422_UNPROCESSABLE_ENTITY,
+                "invalid_request_error",
+                param=f"messages[{i}]"
+            )
+
+    return processed_messages
+
+
+def prepare_provider_params(chat_request: ChatCompletionRequest, model_name: str,
+                          processed_messages: List[Dict[str, Any]]) -> Dict[str, Any]:
+    """Prepare parameters for the provider."""
+    params = {
+        "model": model_name,
+        "messages": processed_messages,
+        "stream": chat_request.stream,
+    }
+
+    # Add optional parameters if present
+    optional_params = [
+        "temperature", "max_tokens", "top_p", "presence_penalty",
+        "frequency_penalty", "stop", "user"
+    ]
+
+    for param in optional_params:
+        value = getattr(chat_request, param, None)
+        if value is not None:
+            params[param] = value
+
+    return params
+
+
+async def handle_streaming_response(provider: Any, params: Dict[str, Any], request_id: str) -> StreamingResponse:
+    """Handle streaming chat completion response."""
+    async def streaming():
+        try:
+            logger.debug(f"Starting streaming response for request {request_id}")
+            completion_stream = provider.chat.completions.create(**params)
+
+            # Check if it's iterable (generator, iterator, or other iterable types)
+            if hasattr(completion_stream, '__iter__') and not isinstance(completion_stream, (str, bytes, dict)):
+                try:
+                    for chunk in completion_stream:
+                        # Standardize chunk format before sending
+                        if hasattr(chunk, 'model_dump'):  # Pydantic v2
+                            chunk_data = chunk.model_dump(exclude_none=True)
+                        elif hasattr(chunk, 'dict'):  # Pydantic v1
+                            chunk_data = chunk.dict(exclude_none=True)
+                        elif isinstance(chunk, dict):
+                            chunk_data = chunk
+                        else:  # Fallback for unknown chunk types
+                            chunk_data = chunk
+                        
+                        # Clean text content in the chunk to remove control characters
+                        if isinstance(chunk_data, dict) and 'choices' in chunk_data:
+                            for choice in chunk_data.get('choices', []):
+                                if isinstance(choice, dict):
+                                    # Handle delta for streaming
+                                    if 'delta' in choice and isinstance(choice['delta'], dict) and 'content' in choice['delta']:
+                                        choice['delta']['content'] = clean_text(choice['delta']['content'])
+                                    # Handle message for non-streaming
+                                    elif 'message' in choice and isinstance(choice['message'], dict) and 'content' in choice['message']:
+                                        choice['message']['content'] = clean_text(choice['message']['content'])
+                        
+                        yield f"data: {json.dumps(chunk_data, ensure_ascii=False)}\n\n"
+                except TypeError as te:
+                    logger.error(f"Error iterating over completion_stream: {te}")
+                    # Fall back to treating as non-generator response
+                    if hasattr(completion_stream, 'model_dump'):
+                        response_data = completion_stream.model_dump(exclude_none=True)
+                    elif hasattr(completion_stream, 'dict'):
+                        response_data = completion_stream.dict(exclude_none=True)
+                    else:
+                        response_data = completion_stream
+                    
+                    # Clean text content in the response
+                    if isinstance(response_data, dict) and 'choices' in response_data:
+                        for choice in response_data.get('choices', []):
+                            if isinstance(choice, dict):
+                                if 'delta' in choice and isinstance(choice['delta'], dict) and 'content' in choice['delta']:
+                                    choice['delta']['content'] = clean_text(choice['delta']['content'])
+                                elif 'message' in choice and isinstance(choice['message'], dict) and 'content' in choice['message']:
+                                    choice['message']['content'] = clean_text(choice['message']['content'])
+                    
+                    yield f"data: {json.dumps(response_data, ensure_ascii=False)}\n\n"
+            else:  # Non-generator response
+                if hasattr(completion_stream, 'model_dump'):
+                    response_data = completion_stream.model_dump(exclude_none=True)
+                elif hasattr(completion_stream, 'dict'):
+                    response_data = completion_stream.dict(exclude_none=True)
+                else:
+                    response_data = completion_stream
+                
+                # Clean text content in the response
+                if isinstance(response_data, dict) and 'choices' in response_data:
+                    for choice in response_data.get('choices', []):
+                        if isinstance(choice, dict):
+                            if 'delta' in choice and isinstance(choice['delta'], dict) and 'content' in choice['delta']:
+                                choice['delta']['content'] = clean_text(choice['delta']['content'])
+                            elif 'message' in choice and isinstance(choice['message'], dict) and 'content' in choice['message']:
+                                choice['message']['content'] = clean_text(choice['message']['content'])
+                
+                yield f"data: {json.dumps(response_data, ensure_ascii=False)}\n\n"
+
+        except Exception as e:
+            logger.error(f"Error in streaming response for request {request_id}: {e}")
+            error_message = clean_text(str(e))
+            error_data = {
+                "error": {
+                    "message": error_message,
+                    "type": "server_error",
+                    "code": "streaming_error"
+                }
+            }
+            yield f"data: {json.dumps(error_data, ensure_ascii=False)}\n\n"
+        finally:
+            yield "data: [DONE]\n\n"
+    return StreamingResponse(streaming(), media_type="text/event-stream")
+
+
+async def handle_non_streaming_response(provider: Any, params: Dict[str, Any],
+                                      request_id: str, start_time: float) -> Dict[str, Any]:
+    """Handle non-streaming chat completion response."""
+    try:
+        logger.debug(f"Starting non-streaming response for request {request_id}")
+        completion = provider.chat.completions.create(**params)
+
+        if completion is None:
+            # Return a valid OpenAI-compatible error response
+            return ChatCompletion(
+                id=request_id,
+                created=int(time.time()),
+                model=params.get("model", "unknown"),
+                choices=[Choice(
+                    index=0,
+                    message=ChatCompletionMessage(role="assistant", content="No response generated."),
+                    finish_reason="error"
+                )],
+                usage=CompletionUsage(prompt_tokens=0, completion_tokens=0, total_tokens=0)
+            ).model_dump(exclude_none=True)
+
+        # Standardize response format
+        if hasattr(completion, "model_dump"):  # Pydantic v2
+            response_data = completion.model_dump(exclude_none=True)
+        elif hasattr(completion, "dict"):  # Pydantic v1
+            response_data = completion.dict(exclude_none=True)
+        elif isinstance(completion, dict):
+            response_data = completion
+        else:
+            raise APIError(
+                "Invalid response format from provider",
+                HTTP_500_INTERNAL_SERVER_ERROR,
+                "provider_error"
+            )
+        
+        # Clean text content in the response to remove control characters
+        if isinstance(response_data, dict) and 'choices' in response_data:
+            for choice in response_data.get('choices', []):
+                if isinstance(choice, dict) and 'message' in choice:
+                    if isinstance(choice['message'], dict) and 'content' in choice['message']:
+                        choice['message']['content'] = clean_text(choice['message']['content'])
+
+        elapsed = time.time() - start_time
+        logger.info(f"Completed non-streaming request {request_id} in {elapsed:.2f}s")
+
+        return response_data
+
+    except Exception as e:
+        logger.error(f"Error in non-streaming response for request {request_id}: {e}")
+        error_message = clean_text(str(e))
+        raise APIError(
+            f"Provider error: {error_message}",
+            HTTP_500_INTERNAL_SERVER_ERROR,
+            "provider_error"
+        )
 
 def format_exception(e: Union[Exception, str]) -> str:
-    """Format exception into a JSON string"""
     if isinstance(e, str):
         message = e
     else:
-        message = f"{e.__class__.__name__}: {e}"
+        message = f"{e.__class__.__name__}: {str(e)}" # Keep it concise
     return json.dumps({
         "error": {
             "message": message,
-            "type": "server_error",
+            "type": "server_error", # Or more specific if possible
             "param": None,
-            "code": "internal_server_error"
+            "code": "internal_server_error" # Or more specific
         }
     })
 
-def start_server(port: int = DEFAULT_PORT, api_key: str = None, default_provider: str = None):
-    """
-    Simple helper function to start the OpenAI-compatible API server.
-    
-    Args:
-        port: Port to run the server on (default: 8000)
-        api_key: Optional API key for authentication
-        default_provider: Default provider to use (e.g., "ChatGPT", "Claude", etc.)
-        
-    Example:
-        ```python
-        from webscout.Provider.OPENAI.api import start_server
-        
-        # Start server with default settings
-        start_server()
-        
-        # Start server with custom settings
-        start_server(port=8080, api_key="your-api-key", default_provider="Claude")
-        ```
-    """
+def start_server(
+    port: int = DEFAULT_PORT,
+    host: str = DEFAULT_HOST,
+    api_key: str = None,
+    default_provider: str = None,
+    base_url: str = None,
+    workers: int = 1,
+    log_level: str = 'info',
+    debug: bool = False
+):
+    """Start the API server with the given configuration."""
     run_api(
-        host="0.0.0.0",
+        host=host,
         port=port,
         api_key=api_key,
         default_provider=default_provider,
-        debug=False,
+        base_url=base_url,
+        workers=workers,
+        log_level=log_level,
+        debug=debug,
     )
 
 def run_api(
@@ -717,94 +910,126 @@ def run_api(
     port: int = None,
     api_key: str = None,
     default_provider: str = None,
+    base_url: str = None,
     debug: bool = False,
+    workers: int = 1,
+    log_level: str = 'info',
     show_available_providers: bool = True,
 ) -> None:
-    """Run the API server
-    
-    Args:
-        host: Host to bind the server to
-        port: Port to bind the server to
-        api_key: API key for authentication (optional)
-        default_provider: Default provider to use if no provider is specified
-        debug: Whether to run in debug mode
-        show_available_providers: Whether to display available providers on startup
-    """
-    print(f"Starting Webscout OpenAI API server...")
-    
+    print("Starting Webscout OpenAI API server...")
     if port is None:
         port = DEFAULT_PORT
-    
-    # Set configuration
     AppConfig.set_config(
         api_key=api_key,
-        default_provider=default_provider or AppConfig.default_provider
+        default_provider=default_provider or AppConfig.default_provider,
+        base_url=base_url
     )
-    
-    # Initialize provider map early to show available providers
-    initialize_provider_map()
-    
-    if show_available_providers:
-        print("\n=== Available Providers ===")
+    # initialize_provider_map() # This is called inside create_app now.
+                              # Call here if create_app doesn't exist yet or for early info.
+                              # For showing providers, it needs to be called before printing.
+    if show_available_providers: # Initialize map if needed for display before app creation
+        if not AppConfig.provider_map: # Avoid re-initializing if already done by app creation logic path
+            initialize_provider_map()
+
+        print("\n=== Webscout OpenAI API Server ===")
+        print(f"Server URL: http://{host if host != '0.0.0.0' else 'localhost'}:{port}")
+        if AppConfig.base_url:
+            print(f"Base Path: {AppConfig.base_url}")
+            api_endpoint_base = f"http://{host if host != '0.0.0.0' else 'localhost'}:{port}{AppConfig.base_url}"
+        else:
+            api_endpoint_base = f"http://{host if host != '0.0.0.0' else 'localhost'}:{port}"
+
+        print(f"API Endpoint: {api_endpoint_base}/v1/chat/completions")
+        print(f"Docs URL: {api_endpoint_base}/docs") # Adjusted for potential base_url in display
+        print(f"API Authentication: {'Enabled' if api_key else 'Disabled'}")
+        print(f"Default Provider: {AppConfig.default_provider}")
+        print(f"Workers: {workers}")
+        print(f"Log Level: {log_level}")
+        print(f"Debug Mode: {'Enabled' if debug else 'Disabled'}")
+
         providers = list(set(v.__name__ for v in AppConfig.provider_map.values()))
-        for i, provider in enumerate(providers, 1):
-            print(f"{i}. {provider}")
-        
-        print("\n=== Available Models ===")
-        # Filter out provider class names from the model list
+        print(f"\n--- Available Providers ({len(providers)}) ---")
+        for i, provider_name in enumerate(sorted(providers), 1):
+            print(f"{i}. {provider_name}")
+
         provider_class_names = set(v.__name__ for v in AppConfig.provider_map.values())
-        models = [model for model in AppConfig.provider_map.keys() if model not in provider_class_names]
-        
-        # Display models in a more organized way
+        models = sorted([model for model in AppConfig.provider_map.keys() if model not in provider_class_names])
         if models:
-            for i, model in enumerate(sorted(models), 1):
-                print(f"{i}. {model}")
+            print(f"\n--- Available Models ({len(models)}) ---")
+            for i, model_name in enumerate(models, 1):
+                print(f"{i}. {model_name} (via {AppConfig.provider_map[model_name].__name__})")
         else:
-            print("No specific models registered. Use provider names as models.")
+            print("\nNo specific models registered. Use provider names as models.")
 
-        print(f"\nDefault provider: {AppConfig.default_provider}")
-        print(f"API Authentication: {'Enabled' if api_key else 'Disabled'}")
-        print(f"Server URL: http://{host if host != '0.0.0.0' else 'localhost'}:{port}")
-        print(f"API Endpoint: http://{host if host != '0.0.0.0' else 'localhost'}:{port}/v1/chat/completions")
-        print(f"Documentation: http://{host if host != '0.0.0.0' else 'localhost'}:{port}/docs")
-        print("\nUse Ctrl+C to stop the server")
-        print("=" * 30 + "\n")
-    
-    # Run the server
-    uvicorn.run(
-        "webscout.Provider.OPENAI.api:create_app_debug" if debug else "webscout.Provider.OPENAI.api:create_app",
-        host=host,
-        port=int(port),
-        factory=True,
-    )
+        print("\nUse Ctrl+C to stop the server.")
+        print("=" * 40 + "\n")
+
+    uvicorn_app_str = "webscout.Provider.OPENAI.api:create_app_debug" if debug else "webscout.Provider.OPENAI.api:create_app"
+
+    # Configure uvicorn settings
+    uvicorn_config = {
+        "app": uvicorn_app_str,
+        "host": host,
+        "port": int(port),
+        "factory": True,
+        "reload": debug,  # Enable reload only in debug mode for stability
+        "log_level": log_level.lower() if log_level else ("debug" if debug else "info"),
+    }
+
+    # Add workers only if not in debug mode (reload and workers are incompatible)
+    if not debug and workers > 1:
+        uvicorn_config["workers"] = workers
+        print(f"Starting with {workers} workers...")
+    elif debug:
+        print("Debug mode enabled - using single worker with reload...")
+
+    # Note: Logs show "werkzeug". If /docs 404s persist, ensure Uvicorn is the actual server running.
+    # The script uses uvicorn.run, so "werkzeug" logs are unexpected for this file.
+    uvicorn.run(**uvicorn_config)
 
-# Command line interface
 if __name__ == "__main__":
     import argparse
-    
-    parser = argparse.ArgumentParser(description="Webscout OpenAI-compatible API server")
-    parser.add_argument("--host", default="0.0.0.0", help="Host to bind the server to")
-    parser.add_argument("--port", type=int, default=DEFAULT_PORT, help="Port to bind the server to")
-    parser.add_argument("--api-key", help="API key for authentication (optional)")
-    parser.add_argument("--default-provider", help="Default provider to use if no provider is specified")
-    parser.add_argument("--debug", action="store_true", help="Run in debug mode")
-    parser.add_argument("--quiet", action="store_true", help="Don't show available providers on startup")
-    
+
+    # Read environment variables with fallbacks
+    default_port = int(os.getenv('WEBSCOUT_PORT', os.getenv('PORT', DEFAULT_PORT)))
+    default_host = os.getenv('WEBSCOUT_HOST', DEFAULT_HOST)
+    default_workers = int(os.getenv('WEBSCOUT_WORKERS', '1'))
+    default_log_level = os.getenv('WEBSCOUT_LOG_LEVEL', 'info')
+    default_api_key = os.getenv('WEBSCOUT_API_KEY', os.getenv('API_KEY'))
+    default_provider = os.getenv('WEBSCOUT_DEFAULT_PROVIDER', os.getenv('DEFAULT_PROVIDER'))
+    default_base_url = os.getenv('WEBSCOUT_BASE_URL', os.getenv('BASE_URL'))
+    default_debug = os.getenv('WEBSCOUT_DEBUG', os.getenv('DEBUG', 'false')).lower() == 'true'
+
+    parser = argparse.ArgumentParser(description='Start Webscout OpenAI-compatible API server')
+    parser.add_argument('--port', type=int, default=default_port, help=f'Port to run the server on (default: {default_port})')
+    parser.add_argument('--host', type=str, default=default_host, help=f'Host to bind the server to (default: {default_host})')
+    parser.add_argument('--workers', type=int, default=default_workers, help=f'Number of worker processes (default: {default_workers})')
+    parser.add_argument('--log-level', type=str, default=default_log_level, choices=['debug', 'info', 'warning', 'error', 'critical'], help=f'Log level (default: {default_log_level})')
+    parser.add_argument('--api-key', type=str, default=default_api_key, help='API key for authentication (optional)')
+    parser.add_argument('--default-provider', type=str, default=default_provider, help='Default provider to use (optional)')
+    parser.add_argument('--base-url', type=str, default=default_base_url, help='Base URL for the API (optional, e.g., /api/v1)')
+    parser.add_argument('--debug', action='store_true', default=default_debug, help='Run in debug mode')
     args = parser.parse_args()
-    
-    try:
-        run_api(
-            host=args.host,
-            port=args.port,
-            api_key=args.api_key,
-            default_provider=args.default_provider,
-            debug=args.debug,
-            show_available_providers=not args.quiet,
-        )
-    except KeyboardInterrupt:
-        print("\nServer stopped by user")
-    except Exception as e:
-        print(f"\nError: {e}")
-        if args.debug:
-            import traceback
-            traceback.print_exc()
+
+    # Print configuration summary
+    print(f"Configuration:")
+    print(f"  Host: {args.host}")
+    print(f"  Port: {args.port}")
+    print(f"  Workers: {args.workers}")
+    print(f"  Log Level: {args.log_level}")
+    print(f"  Debug Mode: {args.debug}")
+    print(f"  API Key: {'Set' if args.api_key else 'Not set'}")
+    print(f"  Default Provider: {args.default_provider or 'Not set'}")
+    print(f"  Base URL: {args.base_url or 'Not set'}")
+    print()
+
+    run_api(
+        host=args.host,
+        port=args.port,
+        workers=args.workers,
+        log_level=args.log_level,
+        api_key=args.api_key,
+        default_provider=args.default_provider,
+        base_url=args.base_url,
+        debug=args.debug
+    )