"""
Base Adapter — Abstract interface for all Brynq tool adapters.

Every adapter (MCP, REST, CLI, etc.) implements this interface so the
runtime can discover available tools (introspect) and call them (execute)
through a uniform contract.

All stdlib — no external packages.
"""

from __future__ import annotations

import abc
from typing import Any, Dict


class BaseAdapter(abc.ABC):
    """Abstract base class that all tool adapters must implement."""

    @abc.abstractmethod
    def introspect(self) -> Dict[str, Any]:
        """Return the adapter's schema and available tools.

        Returns a dict with at least:
          - ``tools``: list of tool descriptors (name, description, parameters)
          - ``version``: adapter protocol version string

        Raises ``NotImplementedError`` if the subclass forgets to override.
        """

    @abc.abstractmethod
    def execute(self, tool_name: str, args: Dict[str, Any]) -> Dict[str, Any]:
        """Execute a tool by name with the given arguments.

        Parameters
        ----------
        tool_name:
            Name of the tool to invoke (must be one returned by ``introspect``).
        args:
            Keyword arguments forwarded to the tool.

        Returns a dict with at least:
          - ``status``: ``"ok"`` or ``"error"``
          - ``result``: the tool's output (arbitrary JSON-serialisable value)

        Raises ``NotImplementedError`` if the subclass forgets to override.
        """
