{
  "contract_version": 1,
  "description": "Python decorators Mantle authors write in tool and hook modules. This is a contract document, not JSON Schema for a YAML file.",
  "field_glossary": {
    "contract_version": "Shape version of this document. Starts at 1. Bump it when a key is removed, renamed, or changes meaning, so a reader of the previous shape would break. Adding a decorator, a payload field, or a control signal does not bump it. This is not the Rasa release.",
    "description": "What this file is, in one sentence.",
    "field_glossary": "Meaning of each field path in this document. A path uses [] for each element of an array and * for a map whose keys are catalogue names rather than fields.",
    "hooks": "Contract for the public on_* and modify_* hook decorators.",
    "hooks.call_required": "True when the author must call the decorator, including when every argument is omitted. @on_turn_started() is valid. A bare @on_turn_started is not, because the decorator is a factory.",
    "hooks.control_signals": "Exceptions a modify hook may raise instead of returning a payload, keyed by class name. A decorator lists the names its point allows.",
    "hooks.control_signals.*": "Constructor of one control signal.",
    "hooks.control_signals.*.import_from": "Module the author imports this control signal from.",
    "hooks.control_signals.*.parameters": "Constructor arguments.",
    "hooks.control_signals.*.parameters[]": "One argument of a decorator or a control-signal constructor.",
    "hooks.control_signals.*.parameters[].default": "Present only when required is false. The value used when the author omits the argument. null means the default is None.",
    "hooks.control_signals.*.parameters[].keyword_only": "True when the argument cannot be passed positionally.",
    "hooks.control_signals.*.parameters[].name": "Argument name as the author writes it.",
    "hooks.control_signals.*.parameters[].required": "True when the author must pass the argument.",
    "hooks.control_signals.*.parameters[].type": "Annotation as text, such as str, int | None, Optional[str], or list[str].",
    "hooks.decorators": "One entry per public hook decorator, in catalogue order.",
    "hooks.decorators[]": "One public hook decorator.",
    "hooks.decorators[].control_signals": "Names of exceptions this point allows a modify hook to raise instead of returning a payload. Empty for every observe decorator. Constructors are under hooks.control_signals.",
    "hooks.decorators[].control_signals[]": "One control-signal name allowed at this decorator's point.",
    "hooks.decorators[].default_timeout_ms": "Timeout in milliseconds when the author omits timeout_ms.",
    "hooks.decorators[].fail_policy": "open or closed. open logs a crash or timeout and keeps the original payload. closed stops the action. Observe entries are always open. Modify entries use the point's own policy.",
    "hooks.decorators[].lane": "observe for on_*, modify for modify_*.",
    "hooks.decorators[].name": "Decorator name, without @.",
    "hooks.decorators[].parameters": "Arguments of the decorator itself.",
    "hooks.decorators[].parameters[]": "One argument of a decorator or a control-signal constructor.",
    "hooks.decorators[].parameters[].default": "Present only when required is false. The value used when the author omits the argument. null means the default is None.",
    "hooks.decorators[].parameters[].keyword_only": "True when the argument cannot be passed positionally.",
    "hooks.decorators[].parameters[].name": "Argument name as the author writes it.",
    "hooks.decorators[].parameters[].required": "True when the author must pass the argument.",
    "hooks.decorators[].parameters[].type": "Annotation as text, such as str, int | None, Optional[str], or list[str].",
    "hooks.decorators[].payload_type": "Payload class the function's parameter must use. The class's JSON Schema is hooks.payloads under this name.",
    "hooks.decorators[].point": "Insertion point this decorator registers.",
    "hooks.function": "Rules for the function a hook decorator registers.",
    "hooks.function.async": "True when the function must be declared with async def.",
    "hooks.function.payload_parameter_count": "How many parameters the function takes. Each hook takes one, the payload.",
    "hooks.import_from": "Module the author imports hook decorators, payloads, and control signals from.",
    "hooks.lanes": "Rules shared by every decorator of a lane.",
    "hooks.lanes.modify": "Rules for modify_* decorators.",
    "hooks.lanes.modify.awaited": "True when the engine waits for the modify hook before continuing.",
    "hooks.lanes.modify.max_per_point": "How many modify hooks one point may have. A second registration fails at train time.",
    "hooks.lanes.modify.returns": "What a modify hook returns. payload_type means the same payload class the decorator's payload_type names.",
    "hooks.lanes.observe": "Rules for on_* decorators.",
    "hooks.lanes.observe.awaited": "False when the engine does not wait for these hooks on the turn path.",
    "hooks.lanes.observe.fail_policy": "What an observe hook does on crash or timeout. open means the error is logged and the turn continues. Every observe point uses this policy.",
    "hooks.lanes.observe.max_per_point": "How many observe hooks one point may have. null means many.",
    "hooks.lanes.observe.returns": "What an observe hook returns. None means no value.",
    "hooks.payloads": "JSON Schema of each hook payload, keyed by the class name in decorators[].payload_type. Keys inside each schema are JSON Schema, not fields of this contract.",
    "kind": "Fixed marker python_decorator_contract. A reader that globs every JSON file in this directory uses it to skip this file when it expects a YAML JSON Schema.",
    "tool": "Contract for the @tool decorator authors apply to async functions in tools.py and tools/.",
    "tool.call_required": "True when the author must call the decorator. @tool(description=\"...\") is valid. A bare @tool is not, because description is a required keyword argument.",
    "tool.decorator": "Decorator name, without @.",
    "tool.decorator_parameters": "Arguments of @tool itself, not of the tool function.",
    "tool.decorator_parameters[]": "One argument of a decorator or a control-signal constructor.",
    "tool.decorator_parameters[].keyword_only": "True when the argument cannot be passed positionally.",
    "tool.decorator_parameters[].name": "Argument name as the author writes it.",
    "tool.decorator_parameters[].required": "True when the author must pass the argument.",
    "tool.decorator_parameters[].type": "Annotation as text, such as str, int | None, Optional[str], or list[str].",
    "tool.function": "Rules for the function @tool decorates.",
    "tool.function.async": "True when the function must be declared with async def.",
    "tool.function.returns": "Type the function must return.",
    "tool.function.returns.import_from": "Module the author imports the return type from.",
    "tool.function.returns.name": "Class name of the return type.",
    "tool.import_from": "Module the author imports the decorator from.",
    "tool.injected_parameters": "Parameters the runtime passes into the tool function. They are not part of the schema the LLM sees.",
    "tool.injected_parameters[]": "One runtime-injected parameter.",
    "tool.injected_parameters[].in_tool_schema": "False when this parameter is left out of the schema sent to the LLM.",
    "tool.injected_parameters[].name": "Parameter name the author declares and the runtime passes as a keyword.",
    "tool.injected_parameters[].passed_as": "How the runtime supplies the value. keyword means it is passed by name.",
    "tool.injected_parameters[].type": "Type of the injected parameter.",
    "tool.injected_parameters[].type.import_from": "Module the author imports the injected type from.",
    "tool.injected_parameters[].type.name": "Class name of the injected parameter.",
    "tool.schema_excluded_parameters": "Parameter names left out of the LLM schema that the runtime does not inject. Injected names are listed under injected_parameters.",
    "tool.schema_excluded_parameters[]": "One parameter name the schema builder skips without passing a value.",
    "tool.schema_excluded_parameters[].in_tool_schema": "False. The name does not appear in the schema sent to the LLM.",
    "tool.schema_excluded_parameters[].injected": "False. The runtime does not pass this parameter.",
    "tool.schema_excluded_parameters[].name": "Parameter name as the author would declare it.",
    "tool.tool_schema": "How the runtime turns the rest of the function signature into the schema the LLM sees.",
    "tool.tool_schema.additional_properties": "False when the generated object schema rejects unknown properties.",
    "tool.tool_schema.description_source": "Where the tool description in that schema comes from.",
    "tool.tool_schema.list_annotations": "How every list[...] annotation is mapped. The value is an array. An item type in type_mapping uses that mapping. An item type that is not uses unmapped_item_json_schema. A bare list has no items schema and is listed in type_mapping.",
    "tool.tool_schema.list_annotations.json_schema_type": "JSON Schema type of every list annotation. array.",
    "tool.tool_schema.list_annotations.unmapped_item_json_schema": "JSON Schema of a list item whose type is not in type_mapping. Keys inside it are JSON Schema, not fields of this contract.",
    "tool.tool_schema.name_source": "Where the tool name in that schema comes from.",
    "tool.tool_schema.optional_annotations": "How Optional[T] and T | None are mapped: the schema uses T.",
    "tool.tool_schema.parameters_source": "Which function parameters become properties of that schema: every parameter that is neither injected nor listed in schema_excluded_parameters.",
    "tool.tool_schema.required_rule": "Which of those properties are required: parameters declared without a default.",
    "tool.tool_schema.type_mapping": "Python annotations the runtime maps to a JSON Schema, and the schema it emits for each.",
    "tool.tool_schema.type_mapping[]": "One annotation and its JSON Schema.",
    "tool.tool_schema.type_mapping[].annotation": "Python annotation text, such as str or list[int].",
    "tool.tool_schema.type_mapping[].json_schema": "JSON Schema the runtime emits for that annotation. Keys inside it are JSON Schema, not fields of this contract.",
    "tool.tool_schema.unmapped_annotation_json_schema": "JSON Schema used when a non-list annotation is not in type_mapping. List annotations follow list_annotations instead."
  },
  "hooks": {
    "call_required": true,
    "control_signals": {
      "HookRejection": {
        "import_from": "rasa.mantle.hooks",
        "parameters": [
          {
            "keyword_only": false,
            "name": "reason",
            "required": true,
            "type": "str"
          },
          {
            "default": null,
            "keyword_only": false,
            "name": "response_message",
            "required": false,
            "type": "Optional[str]"
          }
        ]
      },
      "RetryModel": {
        "import_from": "rasa.mantle.hooks",
        "parameters": [
          {
            "keyword_only": false,
            "name": "feedback",
            "required": true,
            "type": "str"
          }
        ]
      }
    },
    "decorators": [
      {
        "control_signals": [],
        "default_timeout_ms": 100,
        "fail_policy": "open",
        "lane": "observe",
        "name": "on_turn_started",
        "parameters": [
          {
            "default": null,
            "keyword_only": true,
            "name": "timeout_ms",
            "required": false,
            "type": "int | None"
          }
        ],
        "payload_type": "TurnStartedPayload",
        "point": "turn_started"
      },
      {
        "control_signals": [],
        "default_timeout_ms": 100,
        "fail_policy": "open",
        "lane": "observe",
        "name": "on_turn_finished",
        "parameters": [
          {
            "default": null,
            "keyword_only": true,
            "name": "timeout_ms",
            "required": false,
            "type": "int | None"
          }
        ],
        "payload_type": "TurnFinishedPayload",
        "point": "turn_finished"
      },
      {
        "control_signals": [],
        "default_timeout_ms": 100,
        "fail_policy": "open",
        "lane": "observe",
        "name": "on_incoming_message",
        "parameters": [
          {
            "default": null,
            "keyword_only": true,
            "name": "timeout_ms",
            "required": false,
            "type": "int | None"
          }
        ],
        "payload_type": "IncomingMessagePayload",
        "point": "incoming_message"
      },
      {
        "control_signals": [
          "HookRejection"
        ],
        "default_timeout_ms": 500,
        "fail_policy": "closed",
        "lane": "modify",
        "name": "modify_incoming_message",
        "parameters": [
          {
            "default": null,
            "keyword_only": true,
            "name": "timeout_ms",
            "required": false,
            "type": "int | None"
          }
        ],
        "payload_type": "IncomingMessagePayload",
        "point": "incoming_message"
      },
      {
        "control_signals": [],
        "default_timeout_ms": 100,
        "fail_policy": "open",
        "lane": "observe",
        "name": "on_model_request",
        "parameters": [
          {
            "default": null,
            "keyword_only": true,
            "name": "timeout_ms",
            "required": false,
            "type": "int | None"
          }
        ],
        "payload_type": "ModelRequestPayload",
        "point": "model_request"
      },
      {
        "control_signals": [],
        "default_timeout_ms": 500,
        "fail_policy": "closed",
        "lane": "modify",
        "name": "modify_model_request",
        "parameters": [
          {
            "default": null,
            "keyword_only": true,
            "name": "timeout_ms",
            "required": false,
            "type": "int | None"
          }
        ],
        "payload_type": "ModelRequestPayload",
        "point": "model_request"
      },
      {
        "control_signals": [],
        "default_timeout_ms": 100,
        "fail_policy": "open",
        "lane": "observe",
        "name": "on_model_response",
        "parameters": [
          {
            "default": null,
            "keyword_only": true,
            "name": "timeout_ms",
            "required": false,
            "type": "int | None"
          }
        ],
        "payload_type": "ModelResponsePayload",
        "point": "model_response"
      },
      {
        "control_signals": [
          "RetryModel"
        ],
        "default_timeout_ms": 500,
        "fail_policy": "open",
        "lane": "modify",
        "name": "modify_model_response",
        "parameters": [
          {
            "default": null,
            "keyword_only": true,
            "name": "timeout_ms",
            "required": false,
            "type": "int | None"
          }
        ],
        "payload_type": "ModelResponsePayload",
        "point": "model_response"
      },
      {
        "control_signals": [],
        "default_timeout_ms": 100,
        "fail_policy": "open",
        "lane": "observe",
        "name": "on_tool_call",
        "parameters": [
          {
            "default": null,
            "keyword_only": true,
            "name": "timeout_ms",
            "required": false,
            "type": "int | None"
          }
        ],
        "payload_type": "ToolCallPayload",
        "point": "tool_call"
      },
      {
        "control_signals": [
          "RetryModel"
        ],
        "default_timeout_ms": 500,
        "fail_policy": "closed",
        "lane": "modify",
        "name": "modify_tool_call",
        "parameters": [
          {
            "default": null,
            "keyword_only": true,
            "name": "timeout_ms",
            "required": false,
            "type": "int | None"
          }
        ],
        "payload_type": "ToolCallPayload",
        "point": "tool_call"
      },
      {
        "control_signals": [],
        "default_timeout_ms": 100,
        "fail_policy": "open",
        "lane": "observe",
        "name": "on_tool_result",
        "parameters": [
          {
            "default": null,
            "keyword_only": true,
            "name": "timeout_ms",
            "required": false,
            "type": "int | None"
          }
        ],
        "payload_type": "ToolResultPayload",
        "point": "tool_result"
      },
      {
        "control_signals": [],
        "default_timeout_ms": 500,
        "fail_policy": "open",
        "lane": "modify",
        "name": "modify_tool_result",
        "parameters": [
          {
            "default": null,
            "keyword_only": true,
            "name": "timeout_ms",
            "required": false,
            "type": "int | None"
          }
        ],
        "payload_type": "ToolResultPayload",
        "point": "tool_result"
      },
      {
        "control_signals": [],
        "default_timeout_ms": 100,
        "fail_policy": "open",
        "lane": "observe",
        "name": "on_knowledge_query",
        "parameters": [
          {
            "default": null,
            "keyword_only": true,
            "name": "timeout_ms",
            "required": false,
            "type": "int | None"
          }
        ],
        "payload_type": "KnowledgeQueryPayload",
        "point": "knowledge_query"
      },
      {
        "control_signals": [],
        "default_timeout_ms": 500,
        "fail_policy": "closed",
        "lane": "modify",
        "name": "modify_knowledge_query",
        "parameters": [
          {
            "default": null,
            "keyword_only": true,
            "name": "timeout_ms",
            "required": false,
            "type": "int | None"
          }
        ],
        "payload_type": "KnowledgeQueryPayload",
        "point": "knowledge_query"
      },
      {
        "control_signals": [],
        "default_timeout_ms": 100,
        "fail_policy": "open",
        "lane": "observe",
        "name": "on_knowledge_results",
        "parameters": [
          {
            "default": null,
            "keyword_only": true,
            "name": "timeout_ms",
            "required": false,
            "type": "int | None"
          }
        ],
        "payload_type": "KnowledgeResultsPayload",
        "point": "knowledge_results"
      },
      {
        "control_signals": [],
        "default_timeout_ms": 500,
        "fail_policy": "open",
        "lane": "modify",
        "name": "modify_knowledge_results",
        "parameters": [
          {
            "default": null,
            "keyword_only": true,
            "name": "timeout_ms",
            "required": false,
            "type": "int | None"
          }
        ],
        "payload_type": "KnowledgeResultsPayload",
        "point": "knowledge_results"
      },
      {
        "control_signals": [],
        "default_timeout_ms": 100,
        "fail_policy": "open",
        "lane": "observe",
        "name": "on_outgoing_message",
        "parameters": [
          {
            "default": null,
            "keyword_only": true,
            "name": "timeout_ms",
            "required": false,
            "type": "int | None"
          }
        ],
        "payload_type": "OutgoingMessagePayload",
        "point": "outgoing_message"
      },
      {
        "control_signals": [
          "HookRejection"
        ],
        "default_timeout_ms": 500,
        "fail_policy": "open",
        "lane": "modify",
        "name": "modify_outgoing_message",
        "parameters": [
          {
            "default": null,
            "keyword_only": true,
            "name": "timeout_ms",
            "required": false,
            "type": "int | None"
          }
        ],
        "payload_type": "OutgoingMessagePayload",
        "point": "outgoing_message"
      }
    ],
    "function": {
      "async": true,
      "payload_parameter_count": 1
    },
    "import_from": "rasa.mantle.hooks",
    "lanes": {
      "modify": {
        "awaited": true,
        "max_per_point": 1,
        "returns": "payload_type"
      },
      "observe": {
        "awaited": false,
        "fail_policy": "open",
        "max_per_point": null,
        "returns": "None"
      }
    },
    "payloads": {
      "IncomingMessagePayload": {
        "$defs": {
          "CallInfo": {
            "description": "Telephony / session identity, when present.",
            "properties": {
              "metadata": {
                "additionalProperties": true,
                "title": "Metadata",
                "type": "object"
              },
              "phone_number": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "default": null,
                "title": "Phone Number"
              }
            },
            "title": "CallInfo",
            "type": "object"
          },
          "ChannelInfo": {
            "description": "Channel identity and front-end metadata.",
            "properties": {
              "metadata": {
                "additionalProperties": true,
                "title": "Metadata",
                "type": "object"
              },
              "name": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "default": null,
                "title": "Name"
              }
            },
            "title": "ChannelInfo",
            "type": "object"
          }
        },
        "properties": {
          "call": {
            "$ref": "#/$defs/CallInfo"
          },
          "channel": {
            "$ref": "#/$defs/ChannelInfo"
          },
          "message_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Message Id"
          },
          "sender_id": {
            "title": "Sender Id",
            "type": "string"
          },
          "text": {
            "title": "Text",
            "type": "string"
          }
        },
        "required": [
          "sender_id",
          "text"
        ],
        "title": "IncomingMessagePayload",
        "type": "object"
      },
      "KnowledgeQueryPayload": {
        "$defs": {
          "CallInfo": {
            "description": "Telephony / session identity, when present.",
            "properties": {
              "metadata": {
                "additionalProperties": true,
                "title": "Metadata",
                "type": "object"
              },
              "phone_number": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "default": null,
                "title": "Phone Number"
              }
            },
            "title": "CallInfo",
            "type": "object"
          },
          "ChannelInfo": {
            "description": "Channel identity and front-end metadata.",
            "properties": {
              "metadata": {
                "additionalProperties": true,
                "title": "Metadata",
                "type": "object"
              },
              "name": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "default": null,
                "title": "Name"
              }
            },
            "title": "ChannelInfo",
            "type": "object"
          }
        },
        "properties": {
          "call": {
            "$ref": "#/$defs/CallInfo"
          },
          "channel": {
            "$ref": "#/$defs/ChannelInfo"
          },
          "query": {
            "title": "Query",
            "type": "string"
          },
          "sender_id": {
            "title": "Sender Id",
            "type": "string"
          }
        },
        "required": [
          "sender_id",
          "query"
        ],
        "title": "KnowledgeQueryPayload",
        "type": "object"
      },
      "KnowledgeResultsPayload": {
        "$defs": {
          "CallInfo": {
            "description": "Telephony / session identity, when present.",
            "properties": {
              "metadata": {
                "additionalProperties": true,
                "title": "Metadata",
                "type": "object"
              },
              "phone_number": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "default": null,
                "title": "Phone Number"
              }
            },
            "title": "CallInfo",
            "type": "object"
          },
          "ChannelInfo": {
            "description": "Channel identity and front-end metadata.",
            "properties": {
              "metadata": {
                "additionalProperties": true,
                "title": "Metadata",
                "type": "object"
              },
              "name": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "default": null,
                "title": "Name"
              }
            },
            "title": "ChannelInfo",
            "type": "object"
          }
        },
        "properties": {
          "call": {
            "$ref": "#/$defs/CallInfo"
          },
          "channel": {
            "$ref": "#/$defs/ChannelInfo"
          },
          "passages": {
            "items": {
              "additionalProperties": true,
              "type": "object"
            },
            "title": "Passages",
            "type": "array"
          },
          "query": {
            "title": "Query",
            "type": "string"
          },
          "sender_id": {
            "title": "Sender Id",
            "type": "string"
          }
        },
        "required": [
          "sender_id",
          "query",
          "passages"
        ],
        "title": "KnowledgeResultsPayload",
        "type": "object"
      },
      "ModelRequestPayload": {
        "$defs": {
          "CallInfo": {
            "description": "Telephony / session identity, when present.",
            "properties": {
              "metadata": {
                "additionalProperties": true,
                "title": "Metadata",
                "type": "object"
              },
              "phone_number": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "default": null,
                "title": "Phone Number"
              }
            },
            "title": "CallInfo",
            "type": "object"
          },
          "ChannelInfo": {
            "description": "Channel identity and front-end metadata.",
            "properties": {
              "metadata": {
                "additionalProperties": true,
                "title": "Metadata",
                "type": "object"
              },
              "name": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "default": null,
                "title": "Name"
              }
            },
            "title": "ChannelInfo",
            "type": "object"
          }
        },
        "properties": {
          "call": {
            "$ref": "#/$defs/CallInfo"
          },
          "channel": {
            "$ref": "#/$defs/ChannelInfo"
          },
          "iteration": {
            "default": 0,
            "title": "Iteration",
            "type": "integer"
          },
          "messages": {
            "items": {
              "additionalProperties": true,
              "type": "object"
            },
            "title": "Messages",
            "type": "array"
          },
          "model_settings": {
            "additionalProperties": true,
            "title": "Model Settings",
            "type": "object"
          },
          "sender_id": {
            "title": "Sender Id",
            "type": "string"
          },
          "tool_names": {
            "items": {
              "type": "string"
            },
            "title": "Tool Names",
            "type": "array"
          }
        },
        "required": [
          "sender_id",
          "messages"
        ],
        "title": "ModelRequestPayload",
        "type": "object"
      },
      "ModelResponsePayload": {
        "$defs": {
          "CallInfo": {
            "description": "Telephony / session identity, when present.",
            "properties": {
              "metadata": {
                "additionalProperties": true,
                "title": "Metadata",
                "type": "object"
              },
              "phone_number": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "default": null,
                "title": "Phone Number"
              }
            },
            "title": "CallInfo",
            "type": "object"
          },
          "ChannelInfo": {
            "description": "Channel identity and front-end metadata.",
            "properties": {
              "metadata": {
                "additionalProperties": true,
                "title": "Metadata",
                "type": "object"
              },
              "name": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "default": null,
                "title": "Name"
              }
            },
            "title": "ChannelInfo",
            "type": "object"
          }
        },
        "properties": {
          "call": {
            "$ref": "#/$defs/CallInfo"
          },
          "channel": {
            "$ref": "#/$defs/ChannelInfo"
          },
          "latency_ms": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Latency Ms"
          },
          "sender_id": {
            "title": "Sender Id",
            "type": "string"
          },
          "text": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Text"
          },
          "tool_calls": {
            "items": {
              "additionalProperties": true,
              "type": "object"
            },
            "title": "Tool Calls",
            "type": "array"
          }
        },
        "required": [
          "sender_id"
        ],
        "title": "ModelResponsePayload",
        "type": "object"
      },
      "OutgoingMessagePayload": {
        "$defs": {
          "CallInfo": {
            "description": "Telephony / session identity, when present.",
            "properties": {
              "metadata": {
                "additionalProperties": true,
                "title": "Metadata",
                "type": "object"
              },
              "phone_number": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "default": null,
                "title": "Phone Number"
              }
            },
            "title": "CallInfo",
            "type": "object"
          },
          "ChannelInfo": {
            "description": "Channel identity and front-end metadata.",
            "properties": {
              "metadata": {
                "additionalProperties": true,
                "title": "Metadata",
                "type": "object"
              },
              "name": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "default": null,
                "title": "Name"
              }
            },
            "title": "ChannelInfo",
            "type": "object"
          }
        },
        "properties": {
          "call": {
            "$ref": "#/$defs/CallInfo"
          },
          "channel": {
            "$ref": "#/$defs/ChannelInfo"
          },
          "is_voice": {
            "default": false,
            "title": "Is Voice",
            "type": "boolean"
          },
          "sender_id": {
            "title": "Sender Id",
            "type": "string"
          },
          "text": {
            "title": "Text",
            "type": "string"
          }
        },
        "required": [
          "sender_id",
          "text"
        ],
        "title": "OutgoingMessagePayload",
        "type": "object"
      },
      "ToolCallPayload": {
        "$defs": {
          "CallInfo": {
            "description": "Telephony / session identity, when present.",
            "properties": {
              "metadata": {
                "additionalProperties": true,
                "title": "Metadata",
                "type": "object"
              },
              "phone_number": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "default": null,
                "title": "Phone Number"
              }
            },
            "title": "CallInfo",
            "type": "object"
          },
          "ChannelInfo": {
            "description": "Channel identity and front-end metadata.",
            "properties": {
              "metadata": {
                "additionalProperties": true,
                "title": "Metadata",
                "type": "object"
              },
              "name": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "default": null,
                "title": "Name"
              }
            },
            "title": "ChannelInfo",
            "type": "object"
          }
        },
        "description": "One LLM tool call presented to tool-call hooks.\n\n``metadata`` is optional data for that call's MCP ``_meta`` only. Observers\nrun on the pre-modify payload, which does not carry it. Preflight keeps it\nbeside the rewritten call (deep-copied), not on ``arguments``. On\n``requires_confirmation`` for an MCP tool, it is stored on\n``system.pending_tool_confirmation`` and replayed on resume. That memory\nwrite stays in tracker history after the memory field is cleared, so it is\nnot a place for secrets. A local tool pause does not store it. It is not\nwritten to ``ToolExecuted`` or model history.",
        "properties": {
          "arguments": {
            "additionalProperties": true,
            "title": "Arguments",
            "type": "object"
          },
          "call": {
            "$ref": "#/$defs/CallInfo"
          },
          "channel": {
            "$ref": "#/$defs/ChannelInfo"
          },
          "headers": {
            "additionalProperties": {
              "type": "string"
            },
            "title": "Headers",
            "type": "object"
          },
          "metadata": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Metadata"
          },
          "sender_id": {
            "title": "Sender Id",
            "type": "string"
          },
          "tool_name": {
            "title": "Tool Name",
            "type": "string"
          }
        },
        "required": [
          "sender_id",
          "tool_name",
          "arguments"
        ],
        "title": "ToolCallPayload",
        "type": "object"
      },
      "ToolResultPayload": {
        "$defs": {
          "CallInfo": {
            "description": "Telephony / session identity, when present.",
            "properties": {
              "metadata": {
                "additionalProperties": true,
                "title": "Metadata",
                "type": "object"
              },
              "phone_number": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "default": null,
                "title": "Phone Number"
              }
            },
            "title": "CallInfo",
            "type": "object"
          },
          "ChannelInfo": {
            "description": "Channel identity and front-end metadata.",
            "properties": {
              "metadata": {
                "additionalProperties": true,
                "title": "Metadata",
                "type": "object"
              },
              "name": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "default": null,
                "title": "Name"
              }
            },
            "title": "ChannelInfo",
            "type": "object"
          }
        },
        "properties": {
          "arguments": {
            "additionalProperties": true,
            "title": "Arguments",
            "type": "object"
          },
          "call": {
            "$ref": "#/$defs/CallInfo"
          },
          "channel": {
            "$ref": "#/$defs/ChannelInfo"
          },
          "is_error": {
            "default": false,
            "title": "Is Error",
            "type": "boolean"
          },
          "sender_id": {
            "title": "Sender Id",
            "type": "string"
          },
          "tool_name": {
            "title": "Tool Name",
            "type": "string"
          },
          "value": {
            "title": "Value"
          }
        },
        "required": [
          "sender_id",
          "tool_name",
          "arguments",
          "value"
        ],
        "title": "ToolResultPayload",
        "type": "object"
      },
      "TurnFinishedPayload": {
        "$defs": {
          "CallInfo": {
            "description": "Telephony / session identity, when present.",
            "properties": {
              "metadata": {
                "additionalProperties": true,
                "title": "Metadata",
                "type": "object"
              },
              "phone_number": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "default": null,
                "title": "Phone Number"
              }
            },
            "title": "CallInfo",
            "type": "object"
          },
          "ChannelInfo": {
            "description": "Channel identity and front-end metadata.",
            "properties": {
              "metadata": {
                "additionalProperties": true,
                "title": "Metadata",
                "type": "object"
              },
              "name": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "default": null,
                "title": "Name"
              }
            },
            "title": "ChannelInfo",
            "type": "object"
          }
        },
        "properties": {
          "call": {
            "$ref": "#/$defs/CallInfo"
          },
          "channel": {
            "$ref": "#/$defs/ChannelInfo"
          },
          "sender_id": {
            "title": "Sender Id",
            "type": "string"
          },
          "status": {
            "enum": [
              "completed",
              "cancelled",
              "error"
            ],
            "title": "Status",
            "type": "string"
          },
          "turn_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Turn Id"
          }
        },
        "required": [
          "sender_id",
          "status"
        ],
        "title": "TurnFinishedPayload",
        "type": "object"
      },
      "TurnStartedPayload": {
        "$defs": {
          "CallInfo": {
            "description": "Telephony / session identity, when present.",
            "properties": {
              "metadata": {
                "additionalProperties": true,
                "title": "Metadata",
                "type": "object"
              },
              "phone_number": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "default": null,
                "title": "Phone Number"
              }
            },
            "title": "CallInfo",
            "type": "object"
          },
          "ChannelInfo": {
            "description": "Channel identity and front-end metadata.",
            "properties": {
              "metadata": {
                "additionalProperties": true,
                "title": "Metadata",
                "type": "object"
              },
              "name": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "default": null,
                "title": "Name"
              }
            },
            "title": "ChannelInfo",
            "type": "object"
          }
        },
        "properties": {
          "call": {
            "$ref": "#/$defs/CallInfo"
          },
          "channel": {
            "$ref": "#/$defs/ChannelInfo"
          },
          "is_voice": {
            "default": false,
            "title": "Is Voice",
            "type": "boolean"
          },
          "sender_id": {
            "title": "Sender Id",
            "type": "string"
          },
          "turn_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Turn Id"
          }
        },
        "required": [
          "sender_id"
        ],
        "title": "TurnStartedPayload",
        "type": "object"
      }
    }
  },
  "kind": "python_decorator_contract",
  "tool": {
    "call_required": true,
    "decorator": "tool",
    "decorator_parameters": [
      {
        "keyword_only": true,
        "name": "description",
        "required": true,
        "type": "str"
      }
    ],
    "function": {
      "async": true,
      "returns": {
        "import_from": "rasa.mantle.tools.result",
        "name": "ToolResult"
      }
    },
    "import_from": "rasa.mantle.tools.decorator",
    "injected_parameters": [
      {
        "in_tool_schema": false,
        "name": "context",
        "passed_as": "keyword",
        "type": {
          "import_from": "rasa.mantle.tools.decorator",
          "name": "ToolContext"
        }
      }
    ],
    "schema_excluded_parameters": [
      {
        "in_tool_schema": false,
        "injected": false,
        "name": "tracker_handle"
      }
    ],
    "tool_schema": {
      "additional_properties": false,
      "description_source": "decorator_parameter:description",
      "list_annotations": {
        "json_schema_type": "array",
        "unmapped_item_json_schema": {
          "type": "string"
        }
      },
      "name_source": "function_name",
      "optional_annotations": "unwrapped_to_inner_type",
      "parameters_source": "function_parameters_except_schema_excluded",
      "required_rule": "parameters_without_default",
      "type_mapping": [
        {
          "annotation": "int",
          "json_schema": {
            "type": "integer"
          }
        },
        {
          "annotation": "list[int]",
          "json_schema": {
            "items": {
              "type": "integer"
            },
            "type": "array"
          }
        },
        {
          "annotation": "float",
          "json_schema": {
            "type": "number"
          }
        },
        {
          "annotation": "list[float]",
          "json_schema": {
            "items": {
              "type": "number"
            },
            "type": "array"
          }
        },
        {
          "annotation": "bool",
          "json_schema": {
            "type": "boolean"
          }
        },
        {
          "annotation": "list[bool]",
          "json_schema": {
            "items": {
              "type": "boolean"
            },
            "type": "array"
          }
        },
        {
          "annotation": "str",
          "json_schema": {
            "type": "string"
          }
        },
        {
          "annotation": "list[str]",
          "json_schema": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        {
          "annotation": "list",
          "json_schema": {
            "type": "array"
          }
        }
      ],
      "unmapped_annotation_json_schema": {
        "type": "string"
      }
    }
  }
}
