tools.py

import json
from langchain.agents import Tool
from langchain_core.tools import StructuredTool

from config import SanatanConfig
from nalayiram_helper import (
    get_standardized_azhwar_names,
    get_standardized_divya_desam_names,
    get_standardized_prabandham_names,
)
from push_notifications_helper import push
from serperdev_helper import search as search_web
from sanatan_assistant import (
    format_scripture_answer,
    query,
    query_by_metadata_field,
    query_by_literal_text,
)

tool_push = Tool(
    name="push", description="Send a push notification to the user", func=push
)

allowed_collections = [s["collection_name"] for s in SanatanConfig.scriptures]

tool_search_db = StructuredTool.from_function(
    query,
    name="tool_semantic_vector_search",
    description=(
        "🚫 Never use this tool if the user asks for a verse number, pasuram number, or any explicit metadata field "
        "(like azhwar name, prabandham, divya desam, decade, or chapter). "
        "✅ Only use this tool when the query is vague or thematic, e.g. "
        "'Which pasurams talk about Krishna's childhood?' or 'Show me verses about compassion'. "
        f"The collection_name must be one of: {', '.join(allowed_collections)}."
    ),
)


tool_search_db_for_literal = StructuredTool.from_function(
    query_by_literal_text,
    name="tool_search_db_by_literal_text",
    description=(
        "🚫 Never use this tool by default."
        " ✅ Only use this tool if the user explicitly requests a 'literal match', 'exact phrase search', or uses words like 'match exactly', 'find the exact string', 'verbatim', or 'literal text'."
        " If the user simply asks for a verse number (e.g., verse 34, pasuram 2.3.5, sahasranamam verse 20), you must NOT use this tool — instead you must use `tool_search_db_by_metadata`."
        " Do not fall back to this tool if semantic or metadata search seems difficult or fails — it is reserved strictly for explicit literal match requests."
        f" The collection_name must be one of: {', '.join(allowed_collections)}."
    ),
)



tool_search_db_by_metadata = StructuredTool.from_function(
    query_by_metadata_field,
    name="tool_search_db_by_metadata",
    description=(
        "Use this tool **only when the user provides explicit metadata criteria**, such as: azhwar name, pasuram number, verse number, decade, prabandham name, or divya desam name."
        " This is not meant for general queries."
        f" The collection_name must be one of: {', '.join(allowed_collections)}."
        "you must ALWAYS call one of the standardization tools available to get the correct entity name before using this tool."
        "If the user asks for a specific azhwar, use `tool_get_standardized_azhwar_names` first."
        "If the user asks for a specific prabandham, use `tool_get_standardized_prabandham_names` first."
        "If the user mentions a divya desam, use `tool_get_standardized_divya_desam_names` first."
        "If you set metadata_search_operator to $in, then metadata_value must always be a list — even if it contains only a single item."
        """🔒 Important:
        When using the tool_get_standardized_azhwar_names, tool_get_standardized_divya_desam_names, or any similar standardization tool, you must use the standardized name exactly as returned by the tool — without modifying, reformatting, translating, or simplifying it in any way.
        For example, if the tool returns Thirumālirum Solai, you must pass that exact string to tool_search_db_by_metadata. Do not change it to Thirumalirum Solai, Tirumalirumsolai, or anything else.
        🔍 This is critical for the search to return results correctly.
        🚫 Any deviation will cause the search to fail or miss results."""
    ),
)


tool_search_web = Tool(
    name="search_web", description="Search the web for information", func=search_web
)

tool_format_scripture_answer = StructuredTool.from_function(
    format_scripture_answer,
    name="tool_format_scripture_answer",
    description=(
        """
    Use this tool to generate a custom system prompt based on the scripture title, question, and query_tool_output.
    This is especially useful when the user has asked a question about a scripture, and the relevant context has been fetched using the tools like `tool_search_db_by_metadata` or `tool_search_db_by_literal_text` or `tool_semantic_vector_search`.
    The generated prompt will guide the assistant to respond using only that scripture’s content, with a clear format including Sanskrit/Tamil verses, English explanations, and source chapters.
    Include a santized version of the original native text. Do ensure you dont lose any words from the native text when sanitizing.
    """
    ),
)

tool_get_standardized_azhwar_names = StructuredTool.from_function(
    get_standardized_azhwar_names,
    name="tool_get_standardized_azhwar_names",
    description=(
        "Get a list of standardized  azhwar names and the prabandhams they have written. "
        "Use this tool to standardize the names of the azhwars when the user asks for pasurams written by a specific azhwar."
        "Usually this is followed by passing that standardized azhwar_name for a metadata search using the `tool_search_db_by_metadata` tool."
    ),
)

tool_get_standardized_prabandham_names = StructuredTool.from_function(
    get_standardized_prabandham_names,
    name="tool_get_standardized_prabandham_names",
    description=(
        "Get a list of standardized  prabandham names."
        "Use this tool to standardize the names of the prabandhams when the user asks for pasurams from a specific prabandham."
        "Usually this is followed by passing that `prabandham_name` for a metadata search using the `tool_search_db_by_metadata` tool."
        "if you are passing the prabandham_code, make sure you use metadata field `prabandham` and NOT `prabandham_code` as argument to `tool_search_db_by_metadata` tool."
    ),
)

tool_get_standardized_divya_desam_names = StructuredTool.from_function(
    get_standardized_divya_desam_names,
    name="tool_get_standardized_divya_desam_names",
    description=(
        "Get a list of standardized  divya desam names. "
        "Use this tool to standardize the names of the divya desams when the user asks for pasurams written on a specific divya desam."
        "Usually this is followed by passing that standardized divya desam name for a metadata search using the `tool_search_db_by_metadata` tool by using the fiels `divya_desams`."
    ),
)