"""Base class for LLM providers."""


def normalize_provider(provider):
    """Normalize provider name to lowercase canonical form.

    All provider comparisons in route/service code should use
    this function to ensure consistent casing.
    """
    return provider.lower() if provider else None


class BaseLLMProvider:
    """Base class for all LLM providers.

    Defines the minimum interface that all providers
    must satisfy. Subclasses should override these
    methods as needed.
    """

    @classmethod
    def create_llm(cls, model_name=None, temperature=0.7, **kwargs):
        """Create and return a LangChain chat model instance.

        Subclasses MUST override this method.

        Args:
            model_name: Name of the model to use
            temperature: Model temperature (0.0-1.0)
            **kwargs: Additional arguments including settings_snapshot

        Returns:
            A configured BaseChatModel instance

        Raises:
            NotImplementedError: If not overridden by subclass
        """
        raise NotImplementedError(f"{cls.__name__} must implement create_llm()")

    @classmethod
    def is_available(cls, settings_snapshot=None):
        """Check if this provider is available.

        Returns False by default (fail-closed). Subclasses MUST override
        this method to implement their own availability logic.
        """
        return False

    @classmethod
    def requires_auth_for_models(cls):
        """Whether auth is needed to list models.

        Returns True by default. Override in subclasses that allow
        unauthenticated model listing (e.g., local providers).
        """
        return True
