"""Base AI data structures and abstract provider interface."""

from __future__ import annotations

from abc import ABC, abstractmethod
from collections.abc import Generator
from dataclasses import dataclass


@dataclass
class AIRequest:
    """Represents a request to an AI provider."""

    prompt: str
    system_prompt: str = "You are a helpful assistant."
    temperature: float = 0.7
    max_tokens: int = 2048
    model: str | None = None
    # Optional multi-turn conversation history: [{"role": "user"|"assistant", "content": "..."}]
    messages: list[dict[str, str]] | None = None


@dataclass
class AIResponse:
    """Represents a response from an AI provider."""

    text: str
    provider: str
    model: str
    tokens_used: int = 0
    error: str | None = None

    @property
    def ok(self) -> bool:
        """True if the response contains no error."""
        return self.error is None


class AIProvider(ABC):
    """Abstract base class for all AI providers."""

    name: str = "unknown"

    @abstractmethod
    def ask(self, request: AIRequest) -> AIResponse:
        """Send a request and return the full response."""

    @abstractmethod
    def stream(self, request: AIRequest) -> Generator[str, None, None]:
        """Stream the response as text chunks."""

    @abstractmethod
    def is_available(self) -> bool:
        """Return True if the provider has an API key and is ready."""
