from abc import ABC, abstractmethod
from typing import Awaitable, Callable, List, Optional, Tuple

from app.models.schemas import PreviousReviewContext, SubReview


class BaseAgent(ABC):
    """Abstract base class for all review agents."""

    name: str = "Base Agent"

    @abstractmethod
    async def analyze(
        self,
        images: List[Tuple[bytes, str]],
        previous_review: Optional[PreviousReviewContext] = None,
        on_fallback: Optional[Callable[[], Awaitable[None]]] = None,
    ) -> SubReview:
        """
        Analyze the proof and return a SubReview.

        Args:
            images: List of (file_data, mime_type) tuples representing the proof.
                   For single images/videos, this will contain one tuple.
                   For multi-page PDFs, this will contain one tuple per page.
            previous_review: Optional context from the previous version's review
                   for revision-aware analysis.

        Returns:
            SubReview containing ragStatus, feedback, and issues.
            When previous_review is provided, also includes resolvedIssues,
            outstandingIssues, and newIssues.
        """
        pass