from abc import ABC, abstractmethod
from typing import Dict, Any

from pydantic import BaseModel, Field

# [DEF:PluginBase:Class]
# @SEMANTICS: plugin, interface, base, abstract
# @PURPOSE: Defines the abstract base class that all plugins must implement to be recognized by the system. It enforces a common structure for plugin metadata and execution.
# @LAYER: Core
# @RELATION: Used by PluginLoader to identify valid plugins.
# @INVARIANT: All plugins MUST inherit from this class.
class PluginBase(ABC):
    """
    Base class for all plugins.
    Plugins must inherit from this class and implement the abstract methods.
    """

    @property
    @abstractmethod
    def id(self) -> str:
        """A unique identifier for the plugin."""
        pass

    @property
    @abstractmethod
    def name(self) -> str:
        """A human-readable name for the plugin."""
        pass

    @property
    @abstractmethod
    def description(self) -> str:
        """A brief description of what the plugin does."""
        pass

    @property
    @abstractmethod
    def version(self) -> str:
        """The version of the plugin."""
        pass

    @abstractmethod
    def get_schema(self) -> Dict[str, Any]:
        """
        Returns the JSON schema for the plugin's input parameters.
        This schema will be used to generate the frontend form.
        """
        pass

    @abstractmethod
    async def execute(self, params: Dict[str, Any]):
        """
        Executes the plugin's logic.
        The `params` argument will be validated against the schema returned by `get_schema()`.
        """
        pass
# [/DEF]

# [DEF:PluginConfig:Class]
# @SEMANTICS: plugin, config, schema, pydantic
# @PURPOSE: A Pydantic model used to represent the validated configuration and metadata of a loaded plugin. This object is what gets exposed to the API layer.
# @LAYER: Core
# @RELATION: Instantiated by PluginLoader after validating a PluginBase instance.
class PluginConfig(BaseModel):
    """Pydantic model for plugin configuration."""
    id: str = Field(..., description="Unique identifier for the plugin")
    name: str = Field(..., description="Human-readable name for the plugin")
    description: str = Field(..., description="Brief description of what the plugin does")
    version: str = Field(..., description="Version of the plugin")
    input_schema: Dict[str, Any] = Field(..., description="JSON schema for input parameters", alias="schema")
# [/DEF]