"""
Abstract base for agent providers.

Each provider takes a user message + session context and yields response
text chunks for streaming into the UI.
"""

from abc import ABC, abstractmethod
from dataclasses import dataclass, field
from pathlib import Path
from typing import Iterator


@dataclass
class FrameRef:
    id: str           # "F0001"
    path: Path        # absolute path to JPEG
    timestamp: float  # seconds into recording


@dataclass
class SessionContext:
    session_dir: Path
    frames: list[FrameRef]               # all captured frames so far
    duration: float                       # current recording duration (seconds)
    mentioned_frames: list[FrameRef] = field(default_factory=list)  # @-referenced in message


class AgentProvider(ABC):
    @abstractmethod
    def stream(self, message: str, context: SessionContext) -> Iterator[str]:
        """Yield response text chunks."""
        ...

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