"""Protocole de fournisseur de synthèse IA."""

from __future__ import annotations

from typing import Protocol, runtime_checkable

from pronote_sync.models.synthesis import SynthesisInput, SynthesisResult

__all__ = ["SynthesisProvider"]


@runtime_checkable
class SynthesisProvider(Protocol):
    """Protocole pour un fournisseur de synthèse IA.

    L'implémentation ne doit jamais lever d'exception : en cas
    d'échec, retourner ``None``.
    """

    def generate(self, input_data: SynthesisInput) -> SynthesisResult | None:
        """Génère une synthèse IA à partir des données d'entrée.

        :param input_data: Données de synthèse (diff agenda, messages, événements).
        :return: Résultat de la synthèse, ou ``None`` en cas d'échec.
        :rtype: SynthesisResult | None
        """
        ...