Source code for radioviz.typing.tool_types

#  Copyright 2026 European Union
#  Author: Bulgheroni Antonio (antonio.bulgheroni@ec.europa.eu)
#  SPDX-License-Identifier: EUPL-1.2
"""
Typing protocols for tools and related components.

This module defines minimal typing contracts used to decouple tool discovery
and registration from concrete tool implementations while still enabling
strict typing for in-house tools.
"""

from __future__ import annotations

from typing import TYPE_CHECKING, Any, Protocol
from uuid import UUID

from radioviz.models.overlays import OverlaySpec
from radioviz.services.window_factory import WindowSpec

if TYPE_CHECKING:
    from radioviz.tools.base_controller import ToolController
    from radioviz.tools.tool_api import ToolContext




class ToolProtocol(Protocol):
    """
    Minimal protocol implemented by tool definitions.

    This protocol is used for plugin discovery where strict generic typing
    may not be available.

    :ivar tool_id: Unique identifier for the tool.
    :vartype tool_id: str
    :ivar name: Human-readable tool name.
    :vartype name: str
    :ivar description: Short description for the UI.
    :vartype description: str
    :ivar windows_to_be_registered: Window specs registered by the tool.
    :vartype windows_to_be_registered: list[WindowSpec]
    :ivar overlays_to_be_registered: Overlay specs registered by the tool.
    :vartype overlays_to_be_registered: list[OverlaySpec]
    """

    tool_id: str
    name: str
    description: str
    windows_to_be_registered: list[WindowSpec]
    overlays_to_be_registered: list[OverlaySpec]



    def create_controller(self, ctx: ToolContext) -> ToolController[Any, Any]:
        """
        Create the tool controller for this tool.

        :param ctx: Tool context providing access to application services.
        :type ctx: ToolContext
        :return: The controller instance for this tool.
        :rtype: ToolController[Any, Any]
        """
        ...






class ToolSessionProtocol(Protocol):
    """
    Minimal protocol for tool sessions tracked during workspace restoration.

    :ivar session_id: Unique identifier of the session.
    :vartype session_id: UUID
    """

    session_id: UUID