"""Provider abstraction.

架构文档 §4.3 requires the gateway interface to be designed as if it were a
remote call, so providers take a fully-specified request (explicit timeout,
serialisable payload) and return a fully-specified response. No provider is
allowed to reach back into gateway state.
"""

from __future__ import annotations

from typing import Protocol, runtime_checkable

from packages.llm.types import ProviderRequest, ProviderResponse


@runtime_checkable
class LLMProvider(Protocol):
    @property
    def name(self) -> str:
        """Stable identifier used in routing config and in ``ob_ai_call``."""
        ...

    @property
    def default_model(self) -> str:
        """Model used when the scene config does not pin one."""
        ...

    async def complete(self, request: ProviderRequest) -> ProviderResponse:
        """Perform one completion. Must raise ``packages.llm.errors.ProviderError``."""
        ...

    async def aclose(self) -> None:
        """Release connections."""
        ...