"""Raycast agent definition.

Field set is the union of ``raycast_api.ChatAPI.stream`` parameters useful
as per-agent defaults; per-request values override them where both exist.
"""

from __future__ import annotations

from raycast_api import (  # noqa: F401
    RemoteTool,
    Source,
    UserPreferences,
    UserPreferencesArg,
)

from beaver_gateway.agents.base import BaseAgent


class RaycastAgent(BaseAgent):
    """Agent backed by ``raycast-api``."""

    streaming: bool = True
    available_native_tools: tuple[RemoteTool, ...] = ()
    """Raycast's server-side "remote tools": ``web_search``, ``search_images``,
    ``read_page``."""

    source: Source = Source.AI_CHAT

    temperature: float | None = None
    reasoning_effort: str | None = None
    """Model-specific (e.g. GPT-5: ``"minimal"``/``"low"``/``"medium"``/``"high"``);
    ignored server-side if the model doesn't support it."""

    tool_choice: str | None = None
    user_preferences: UserPreferencesArg = True
    """Auto-fills the ``<user-preferences>`` block from host locale/timezone/date;
    ``False`` omits it, or pass ``UserPreferences(...)`` / a zero-arg callable."""