app/tools.py

"""
Function-calling definitions + handlers.

These demonstrate two things the JD asks for:
  - structured output (JSON) for integrations
  - escalation to a human operator

In production the handlers make REST calls to the contact-center / road-company
systems (passing interaction_id, session_id, etc.). Here they return stub data.
"""
import json

TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "get_road_restriction",
            "description": "Получить актуальные ограничения движения по трассе на дату "
                           "(сезонная нагрузка на ось, габариты, перекрытия).",
            "parameters": {
                "type": "object",
                "properties": {
                    "road": {"type": "string", "description": "Название или номер трассы, напр. 'A-2'"},
                    "date": {"type": "string", "description": "Дата в формате YYYY-MM-DD (необязательно)"},
                },
                "required": ["road"],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "escalate_to_operator",
            "description": "Перевести обращение на живого оператора, если бот не может помочь "
                           "или клиент просит человека.",
            "parameters": {
                "type": "object",
                "properties": {
                    "reason": {"type": "string", "description": "Краткая причина эскалации"},
                },
                "required": ["reason"],
            },
        },
    },
]


def execute_tool(name: str, args: dict, session_id: str) -> dict:
    if name == "get_road_restriction":
        # STUB — in production: REST GET to the road company's restrictions API.
        return {
            "road": args.get("road"),
            "date": args.get("date"),
            "restriction": "Весеннее ограничение: нагрузка на ось не более 8 т",
            "status": "active",
        }
    if name == "escalate_to_operator":
        # STUB — in production: POST to the contact-center queue with session_id.
        return {
            "status": "escalated",
            "queue": "operator",
            "session_id": session_id,
            "reason": args.get("reason"),
        }
    return {"error": f"unknown tool: {name}"}