# Familiar - Self-Hosted AI Companion Platform
# Copyright (c) 2026 George Scott Foley
# ORCID: 0009-0006-4957-0540
# Email: Georgescottfoley@proton.me
# Licensed under the MIT License - see LICENSE file for details

"""WizardHost Protocol — type-only contract for handler functions.

Handler functions in service modules (``_llm.py``, ``_email_calendar.py``, etc.)
accept a ``host: WizardHost`` parameter instead of ``self``.  This avoids circular
imports while providing full type safety.
"""

from __future__ import annotations

from typing import TYPE_CHECKING, Protocol, runtime_checkable

if TYPE_CHECKING:
    from ..formatting import FormatMode


@runtime_checkable
class WizardHost(Protocol):
    """Minimal interface that every channel adapter exposes to wizard handlers."""

    format_mode: FormatMode
    supports_buttons: bool
    supports_message_deletion: bool
    _wizard_state: dict[str, dict]

    def _ensure_wizard_state(self) -> None: ...

    async def wizard_send(self, recipient_id: str, text: str) -> None: ...

    async def wizard_send_menu(
        self, recipient_id: str, text: str, options: list[tuple[str, str]]
    ) -> None: ...

    async def wizard_delete_message(self, recipient_id: str, message_ref: object) -> bool: ...

    def _get_current_provider_name(self) -> str: ...
