from __future__ import annotations

# standard
from abc import ABC, abstractmethod
from collections.abc import AsyncIterator

# third party
# custom
from .types import Message, Response, Tool


class BaseEngine(ABC):
    """Abstract base for all provider engines."""

    @abstractmethod
    async def chat(
        self,
        messages: list[Message],
        tools: list[Tool] | None = None,
    ) -> Response:
        """Send a full conversation and return the complete response."""

    @abstractmethod
    def stream(
        self,
        messages: list[Message],
        tools: list[Tool] | None = None,
    ) -> AsyncIterator[Response]:
        """Stream response chunks as they arrive.

        Each yielded Response has the same shape as a chat() Response.
        Content chunks carry the incremental text; the final chunk carries
        the accumulated token counts and stop_reason. Tool calls are not streamed.
        """
