"""High-level Library API: one-call thumbnail creation."""

from typing import Optional

from .session import ThumbnailResult, ThumbnailSession


def create_thumbnail(
    input_path: str,
    *,
    mode: str = "auto",
    format: str = "poster",
    crop_position: Optional[str] = None,
    overlay_title: Optional[str] = None,
    overlay_category: Optional[str] = None,
    overlay_category_logo_path: Optional[str] = None,
    overlay_note: Optional[str] = None,
    output_dir: Optional[str] = None,
    output_path: Optional[str] = None,
    output_name_suffix: str = "-poster",
    fanart: bool = False,
    no_badges: bool = False,
    template: Optional[dict] = None,
    description: Optional[str] = None,
    ffmpeg: str = "ffmpeg",
    ffprobe: str = "ffprobe",
) -> ThumbnailResult:
    """Create a thumbnail from a video or image file in one call.

    This is a convenience wrapper around :class:`~video_thumbnail_creator.session.ThumbnailSession`
    for the simplest possible integration.  For full control over each step use
    :class:`~video_thumbnail_creator.session.ThumbnailSession` directly.

    Parameters
    ----------
    input_path:
        Path to the input video or image file.
    mode:
        Selection mode.  Currently only ``"auto"`` is supported (AI decides
        frame and crop position automatically).
    format:
        Output format: ``"poster"`` (2:3) or ``"landscape"`` (16:9).
    crop_position:
        Explicit crop position.  When ``None`` and ``format`` is ``"poster"``,
        the AI suggests one automatically.
    overlay_title:
        Optional title text to render on the image.
    overlay_category:
        Optional category label shown above the title (poster only).
    overlay_category_logo_path:
        Optional path to a PNG logo shown instead of category text.
    overlay_note:
        Optional small text at the bottom-right of the text area (poster only).
    output_dir:
        Directory for the output file.  Defaults to the same directory as
        ``input_path``.
    output_path:
        Explicit output file path.  Takes priority over ``output_dir`` and
        ``output_name_suffix``.
    output_name_suffix:
        Suffix appended to the input file stem for the output file name.
    fanart:
        When ``True`` also compose a 16:9 fanart image.
    no_badges:
        When ``True`` suppress all badges even if auto-detected.
    template:
        Optional design template dict.
    description:
        Optional description of the video content used as context for AI
        frame selection.
    ffmpeg:
        Path or name of the ``ffmpeg`` binary.
    ffprobe:
        Path or name of the ``ffprobe`` binary.

    Returns
    -------
    :class:`~video_thumbnail_creator.session.ThumbnailResult`

    Raises
    ------
    ValueError
        If an unsupported ``mode`` is specified.
    RuntimeError
        If the AI call fails or no API key is configured.
    FileNotFoundError
        If ``input_path`` does not exist.
    """
    if mode != "auto":
        raise ValueError(f"Unsupported mode: {mode!r}. Only 'auto' is supported.")

    session = ThumbnailSession(input_path, ffmpeg=ffmpeg, ffprobe=ffprobe)
    try:
        reasoning = ""

        if not session._is_image:
            suggestion = session.suggest_frame(
                title=overlay_title, description=description
            )
            session.select_frame(suggestion["frame_index"])
            reasoning = suggestion["reasoning"]

        effective_crop = crop_position
        if effective_crop is None and format == "poster":
            crop_suggestion = session.suggest_crop()
            effective_crop = crop_suggestion["crop_position"]
            crop_reasoning = crop_suggestion["reasoning"]
            reasoning = (
                f"{reasoning} | Crop: {crop_reasoning}" if reasoning else crop_reasoning
            )

        result = session.compose(
            crop_position=effective_crop or "center",
            overlay_title=overlay_title,
            format=format,
            output_dir=output_dir,
            output_path=output_path,
            output_name_suffix=output_name_suffix,
            fanart=fanart,
            overlay_category=overlay_category,
            overlay_category_logo_path=overlay_category_logo_path,
            overlay_note=overlay_note,
            template=template,
            no_badges=no_badges,
        )
        result.reasoning = reasoning
        return result
    finally:
        session.cleanup()
