"""Plugin base class and hook definitions."""

from __future__ import annotations

from abc import ABC, abstractmethod
from enum import Enum
from typing import Any


class HookType(str, Enum):
    """Hook points in the BilgeAI pipeline."""

    PRE_PROFILE = "pre_profile"
    POST_PROFILE = "post_profile"
    PRE_ANALYZE = "pre_analyze"
    POST_ANALYZE = "post_analyze"
    PRE_OPTIMIZE = "pre_optimize"
    POST_OPTIMIZE = "post_optimize"
    PRE_TRAIN = "pre_train"
    POST_TRAIN = "post_train"
    PRE_GENERATE = "pre_generate"
    POST_GENERATE = "post_generate"


class BilgePlugin(ABC):
    """Abstract base class for BilgeAI plugins.

    Plugins must implement `name` and `version` properties and at least one hook.
    Register plugins via the `bilgeai.plugins` entry point group.
    """

    @property
    @abstractmethod
    def name(self) -> str:
        """Unique plugin name."""
        ...

    @property
    @abstractmethod
    def version(self) -> str:
        """Plugin version string."""
        ...

    @property
    def description(self) -> str:
        """Short description of the plugin."""
        return ""

    def get_hooks(self) -> dict[HookType, Any]:
        """Return a mapping of hook types to handler methods.

        Override this to register hooks. Example:
            return {HookType.POST_TRAIN: self.on_post_train}
        """
        return {}

    def activate(self) -> None:  # noqa: B027
        """Called when the plugin is loaded. Override for setup logic."""

    def deactivate(self) -> None:  # noqa: B027
        """Called when the plugin is unloaded. Override for cleanup logic."""
