"""Tool dict builders for the ARBI SDK.

Pure dict factories — no pydantic or attrs dependency.
Pass the returned dicts as the ``tools`` parameter to ``MessageInput``.

Example::

    from arbi_client.sdk.tools import retrieval_chunk, retrieval_full_context, web_search

    tools = retrieval_chunk(doc_ext_ids=["doc-abc"], search_mode="hybrid")
    tools |= web_search()
"""

from __future__ import annotations


def retrieval_chunk(
    doc_ext_ids: list[str] | None = None,
    search_mode: str = "hybrid",
) -> dict:
    """Build a ``retrieval_chunk`` tool dict for semantic/keyword/hybrid search.

    Args:
        doc_ext_ids: Scope search to specific documents. ``None`` searches all.
        search_mode: ``"hybrid"`` (default), ``"semantic"``, or ``"keyword"``.
    """
    args: dict = {"search_mode": search_mode}
    if doc_ext_ids is not None:
        args["doc_ext_ids"] = list(doc_ext_ids)
    return {
        "retrieval_chunk": {
            "name": "retrieval_chunk",
            "tool_args": args,
        }
    }


def retrieval_full_context(
    doc_ext_ids: list[str],
    from_ref: str,
    to_ref: str,
) -> dict:
    """Build a ``retrieval_full_context`` tool dict for passage retrieval.

    Args:
        doc_ext_ids: Documents to retrieve passages from.
        from_ref: Start reference (``"page.chunk_idx"``, e.g. ``"5.0"``).
        to_ref: End reference (e.g. ``"8.4"``).
    """
    return {
        "retrieval_full_context": {
            "name": "retrieval_full_context",
            "tool_args": {
                "doc_ext_ids": list(doc_ext_ids),
                "from_ref": from_ref,
                "to_ref": to_ref,
            },
        }
    }


def retrieval_toc(doc_ext_ids: list[str]) -> dict:
    """Build a ``retrieval_toc`` tool dict for table-of-contents retrieval.

    Args:
        doc_ext_ids: Documents to get headings for.
    """
    return {
        "retrieval_toc": {
            "name": "retrieval_toc",
            "tool_args": {
                "doc_ext_ids": list(doc_ext_ids),
            },
        }
    }


def web_search() -> dict:
    """Build a ``web_search`` tool dict (no arguments required)."""
    return {
        "web_search": {
            "name": "web_search",
            "tool_args": {},
        }
    }
