"""Provider adapter interface definitions.

This module defines the protocol/interface that all provider adapters must implement.
"""

from __future__ import annotations

from typing import Any, Generator, Protocol, runtime_checkable

from ember.models.schemas import ChatResponse


@runtime_checkable
class ProviderAdapter(Protocol):
    """Protocol defining the interface for provider adapters.

    All provider adapters must implement this interface to be usable
    by the gateway routing system.

    Attributes:
        name: Unique identifier for this provider (e.g., "openai", "anthropic").
        supports_streaming: Whether this adapter supports streaming responses.
    """

    name: str
    supports_streaming: bool

    def complete(
        self,
        model: str,
        prompt_text: str,
        temperature: float = 0.0,
        **kwargs: Any,
    ) -> tuple[str, int, int, object | None]:
        """Execute a non-streaming completion request.

        Args:
            model: The model identifier to use.
            prompt_text: The prompt text to send.
            temperature: Sampling temperature (0.0-2.0).
            **kwargs: Additional provider-specific parameters.

        Returns:
            A tuple of (response_text, prompt_tokens, completion_tokens, metadata).
        """
        ...

    def stream_complete(
        self,
        model: str,
        prompt_text: str,
        temperature: float = 0.0,
        **kwargs: Any,
    ) -> Generator[str, None, ChatResponse]:
        """Execute a streaming completion request.

        Args:
            model: The model identifier to use.
            prompt_text: The prompt text to send.
            temperature: Sampling temperature (0.0-2.0).
            **kwargs: Additional provider-specific parameters.

        Yields:
            Text chunks as they arrive from the provider.

        Returns:
            The final ChatResponse with complete usage statistics.
        """
        ...


__all__ = ["ProviderAdapter"]
