"""
Tool Module Name
================
Brief description of tools in this module.
"""
from __future__ import annotations
from typing import Any
from apps.artagent.backend.registries.toolstore.registry import register_tool
from utils.ml_logging import get_logger
logger = get_logger("agents.tools.module_name")
# ═══════════════════════════════════════════════════════════════════════════════
# SCHEMAS
# ═══════════════════════════════════════════════════════════════════════════════
tool_name_schema: dict[str, Any] = {
    "name": "tool_name",
    "description": "Clear description of what this tool does and when to use it.",
    "parameters": {
        "type": "object",
        "properties": {
            "param1": {"type": "string", "description": "Parameter description"},
            "param2": {"type": "integer", "description": "Optional param"},
        },
        "required": ["param1"],
    },
}
# ═══════════════════════════════════════════════════════════════════════════════
# EXECUTORS
# ═══════════════════════════════════════════════════════════════════════════════
async def tool_name(args: dict[str, Any]) -> dict[str, Any]:
    """Execute the tool with given arguments."""
    param1 = (args.get("param1") or "").strip()
    if not param1:
        return {"success": False, "message": "param1 is required."}
    # Tool implementation
    logger.info("Tool executed: %s", param1)
    return {
        "success": True,
        "result": "Tool output",
    }
# ═══════════════════════════════════════════════════════════════════════════════
# REGISTRATION
# ═══════════════════════════════════════════════════════════════════════════════
register_tool(
    "tool_name",
    tool_name_schema,
    tool_name,
    tags={"category1", "category2"},
)

register_tool(
    name="tool_name",           # Unique identifier
    schema=tool_name_schema,    # OpenAI function schema
    executor=tool_name,         # Async function
    is_handoff=False,           # True if triggers agent transfer
    tags={"category"},          # Optional categorization
    override=False,             # Allow re-registration
)

handoff_specialist_schema = {
    "name": "handoff_specialist",
    "description": "Transfer to specialist agent for [reason].",
    "parameters": {
        "type": "object",
        "properties": {
            "reason": {"type": "string", "description": "Why transferring"},
            "context": {"type": "string", "description": "Relevant context"},
        },
        "required": ["reason"],
    },
}
async def handoff_specialist(args: dict[str, Any]) -> dict[str, Any]:
    return {
        "success": True,
        "handoff": True,
        "target_agent": "specialist",
        "reason": args.get("reason", ""),
    }
register_tool(
    "handoff_specialist",
    handoff_specialist_schema,
    handoff_specialist,
    is_handoff=True,
    tags={"handoff"},
)