"""ProviderAdapter - LLM Provider adapter base class

Defines unified adapter interface that all Provider adapters must implement.
"""
from abc import ABC, abstractmethod
from typing import Dict, List, Any, AsyncGenerator


class ProviderAdapter(ABC):
    """LLM Provider adapter base class
    
    All LLM API adapters must inherit from this class and implement its methods.
    Adapters are responsible for:
    1. Building requests in provider-specific format
    2. Parsing streaming and non-streaming responses
    3. Providing provider capability information
    
    Attributes:
        provider_type: Provider type identifier
    """
    
    @property
    @abstractmethod
    def provider_type(self) -> str:
        """Return provider type identifier
        
        Returns:
            str: Provider type, e.g., "openai", "anthropic"
        """
        pass
    
    @abstractmethod
    def build_request(
        self,
        model: str,
        messages: List[Dict[str, Any]],
        tools: List[Dict[str, Any]] = None,
        **kwargs
    ) -> tuple[Dict[str, Any], Dict[str, str]]:
        """Build request body and headers
        
        Args:
            model: Model name
            messages: Message list
            tools: Tool definition list
            **kwargs: Other parameters (temperature, max_tokens, thinking_enabled, etc.)
            
        Returns:
            tuple: (body, headers) tuple
        """
        pass
    
    @abstractmethod
    async def parse_stream_chunk(
        self, 
        raw_chunk: str
    ) -> AsyncGenerator[Any, None]:
        """Parse streaming response chunk
        
        Args:
            raw_chunk: Raw SSE line or chunk data
            
        Yields:
            ParsedDelta object or other parsed results
        """
        pass
    
    @abstractmethod
    def parse_response(
        self, 
        data: Dict[str, Any]
    ) -> Any:
        """Parse non-streaming response
        
        Args:
            data: API response data
            
        Returns:
            LLMResponse object
        """
        pass
    
    def supports_thinking(self) -> bool:
        """Whether provider supports thinking/reasoning
        
        Returns:
            bool: True if provider supports thinking/reasoning content
        """
        return False
    
    def supports_tools(self) -> bool:
        """Whether provider supports tool/function calls
        
        Returns:
            bool: True if provider supports function calling
        """
        return False