"""Protocol classes for structural typing across AgentiCraft packages."""

from __future__ import annotations

from typing import Any, Protocol, runtime_checkable

from .models import CompletionResponse, StreamChunk


@runtime_checkable
class Provider(Protocol):
    """Protocol for LLM provider implementations."""

    @property
    def name(self) -> str: ...

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

    def supports_model(self, model: str) -> bool: ...


@runtime_checkable
class StreamingProvider(Protocol):
    """Protocol for providers that support streaming."""

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


@runtime_checkable
class Router(Protocol):
    """Protocol for provider routing implementations."""

    async def route(
        self,
        providers: list[str],
        **kwargs: Any,
    ) -> str | None: ...

    def get_stats(self) -> dict[str, Any]: ...


@runtime_checkable
class CircuitBreakerLike(Protocol):
    """Protocol for circuit breaker implementations."""

    @property
    def is_open(self) -> bool: ...

    def record_success(self) -> None: ...

    def record_failure(self) -> None: ...

    def reset(self) -> None: ...


@runtime_checkable
class KeyPoolLike(Protocol):
    """Protocol for API key pool implementations."""

    async def acquire(self) -> str: ...

    async def record_success(self, key: str, **kwargs: Any) -> None: ...

    async def record_error(self, key: str, **kwargs: Any) -> None: ...


__all__ = [
    "Provider",
    "StreamingProvider",
    "Router",
    "CircuitBreakerLike",
    "KeyPoolLike",
]
