# retoor <retoor@molodetz.nl>

from __future__ import annotations

from .spec import Action, Param

REMOTE_NOTE = (
    "This is an EXTERNAL public service, not this DevPlace platform. Only call it when the user "
    "explicitly asks to search the web or an outside source; prefer platform tools otherwise."
)

RSEARCH_ACTIONS: tuple[Action, ...] = (
    Action(
        name="rsearch",
        method="LOCAL",
        path="",
        summary="Search the public web (and images) via the external rsearch aggregator",
        description=(
            "Queries multiple independent web search providers and returns ranked results "
            "(title, URL, description, source). Set content=true to also fetch each page's "
            "readable text, deep=true for a deeper research pass, and type=images for image "
            "results. " + REMOTE_NOTE
        ),
        handler="rsearch",
        requires_auth=False,
        read_only=True,
        params=(
            Param(
                name="query",
                location="body",
                description="The web search query.",
                required=True,
            ),
            Param(
                name="count",
                location="body",
                description="Number of results (1-100, default 10).",
                type="integer",
            ),
            Param(
                name="content",
                location="body",
                description="Fetch full page content for each result.",
                type="boolean",
            ),
            Param(
                name="deep",
                location="body",
                description="Run a deeper research pass.",
                type="boolean",
            ),
            Param(
                name="type",
                location="body",
                description="Result type: 'web' (default) or 'images'.",
            ),
        ),
    ),
    Action(
        name="rsearch_answer",
        method="LOCAL",
        path="",
        summary="Get an AI answer to a question, grounded in fresh public web search",
        description=(
            "Sends the question to an external AI that autonomously searches the public web and "
            "returns a written answer plus the source links it used. Use for current, real-world "
            "questions the platform cannot answer. " + REMOTE_NOTE
        ),
        handler="rsearch",
        requires_auth=False,
        read_only=True,
        params=(
            Param(
                name="query",
                location="body",
                description="The question or prompt to answer.",
                required=True,
            ),
            Param(
                name="content",
                location="body",
                description="Let the AI read full page content while answering.",
                type="boolean",
            ),
            Param(
                name="count",
                location="body",
                description="Max sources to consider (1-100, default 10).",
                type="integer",
            ),
        ),
    ),
    Action(
        name="rsearch_chat",
        method="LOCAL",
        path="",
        summary="Send a prompt to the external rsearch AI for a direct answer (no web search)",
        description=(
            "Direct chat completion from the external rsearch AI model, with no web search or "
            "platform context. Set json=true to force a JSON-only answer, or pass a system message "
            "to steer the persona. " + REMOTE_NOTE
        ),
        handler="rsearch",
        requires_auth=False,
        read_only=True,
        params=(
            Param(
                name="prompt",
                location="body",
                description="The prompt to send.",
                required=True,
            ),
            Param(
                name="json",
                location="body",
                description="Force a valid-JSON-only response.",
                type="boolean",
            ),
            Param(
                name="system",
                location="body",
                description="Optional system message to steer the answer.",
            ),
        ),
    ),
    Action(
        name="rsearch_describe_image",
        method="LOCAL",
        path="",
        summary="Describe a public image URL using the external rsearch vision model",
        description=(
            "Sends an image URL to the external rsearch vision model and returns a written "
            "description. " + REMOTE_NOTE
        ),
        handler="rsearch",
        requires_auth=False,
        read_only=True,
        params=(
            Param(
                name="url",
                location="body",
                description="Public URL of the image to describe.",
                required=True,
            ),
        ),
    ),
)
