"""
Base adapter interface for provider-agnostic tool calling.

This module defines the abstract base class that all LLM provider adapters
must implement to support tool calling in Lyra.
"""

from abc import ABC, abstractmethod
from typing import Dict, List, Optional


class ToolAdapter(ABC):
    """Base class for provider-specific tool adapters.

    Each LLM provider (OpenAI, Ollama, llama.cpp, etc.) has its own
    way of handling tool calls. This adapter pattern allows Lyra to
    support tools across all providers with a unified interface.
    """

    @abstractmethod
    async def prepare_request(
        self,
        messages: List[Dict],
        tools: List[Dict],
        tool_choice: Optional[str] = None
    ) -> Dict:
        """Convert Lyra tool definitions to provider-specific format.

        Args:
            messages: Conversation history in OpenAI format
            tools: List of Lyra tool definitions (provider-agnostic)
            tool_choice: Optional tool forcing ("auto", "required", "none")

        Returns:
            dict: Provider-specific request payload ready to send to LLM
        """
        pass

    @abstractmethod
    async def parse_response(self, response) -> Dict:
        """Extract tool calls from provider response.

        Args:
            response: Raw provider response (format varies by provider)

        Returns:
            dict: Standardized response in Lyra format:
                {
                    "content": str,  # Assistant's text response
                    "tool_calls": [  # List of tool calls or None
                        {
                            "id": str,       # Unique call ID
                            "name": str,     # Tool name
                            "arguments": dict  # Tool arguments
                        }
                    ] or None
                }
        """
        pass

    @abstractmethod
    def format_tool_result(
        self,
        tool_call_id: str,
        tool_name: str,
        result: Dict
    ) -> Dict:
        """Format tool execution result for next LLM call.

        Args:
            tool_call_id: ID from the original tool call
            tool_name: Name of the executed tool
            result: Tool execution result dictionary

        Returns:
            dict: Message object to append to conversation
                (format varies by provider)
        """
        pass