from __future__ import annotations

from collections.abc import AsyncIterator
from typing import Any, Protocol

from app.llm.types import ChatCompletionResult, ModelInfo, ToolCompletionResult


class LLMProvider(Protocol):
    """Provider-neutral LLM surface matching historical LLMClient methods."""

    async def complete(
        self,
        messages: list[dict[str, str]],
        *,
        model: str | None = None,
        response_format: dict[str, Any] | None = None,
    ) -> ChatCompletionResult: ...

    async def complete_with_tools(
        self,
        messages: list[dict[str, Any]],
        tools: list[dict[str, Any]],
        *,
        model: str | None = None,
        tool_choice: str | dict[str, Any] | None = "auto",
    ) -> ToolCompletionResult: ...

    async def complete_json(
        self,
        messages: list[dict[str, str]],
        *,
        model: str | None = None,
    ) -> dict[str, Any]: ...

    async def stream(
        self,
        messages: list[dict[str, str]],
        *,
        model: str | None = None,
    ) -> AsyncIterator[str]: ...

    async def list_models(self) -> list[ModelInfo]: ...