# SPDX-License-Identifier: Apache-2.0
"""
Base classes and interfaces for platform-specific implementations.

Platform-specific implementations (GPU, NPU, etc.) should inherit from
these base classes and implement the abstract methods.
"""

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


class FingerprintPolicy(str, Enum):
    """Policy for machine fingerprint binding."""
    NONE = "none"      # No binding (rely on other protection)
    SINGLE = "single"  # Bind to single machine
    CLUSTER = "cluster"  # Bind to list of machines (for distributed)


class BaseFingerprint(ABC):
    """
    Abstract base class for platform-specific fingerprint providers.

    Each platform (GPU, NPU, etc.) should implement this interface
    to provide hardware-specific fingerprinting.
    """

    @abstractmethod
    def get_fingerprint(self, salt: Optional[str] = None) -> str:
        """
        Generate a unique machine fingerprint.

        Args:
            salt: Optional salt for hashing

        Returns:
            Hex-encoded SHA-256 hash of machine characteristics
        """
        pass

    @abstractmethod
    def get_device_uuids(self) -> list:
        """
        Get device UUIDs for the current platform.

        Returns:
            List of device UUID strings
        """
        pass

    @abstractmethod
    def get_fingerprint_info(self) -> dict:
        """
        Get detailed fingerprint information for debugging.

        Returns:
            Dictionary with fingerprint components
        """
        pass


class BaseEncryptedLoader(ABC):
    """
    Abstract base class for platform-specific encrypted model loaders.

    Each platform should implement this interface to handle
    platform-specific device management and memory operations.
    """

    @abstractmethod
    def get_device_type(self) -> str:
        """
        Get the current device type.

        Returns:
            Device type string (e.g., "cuda", "npu", "cpu")
        """
        pass

    @abstractmethod
    def clear_device_cache(self) -> None:
        """Clear device cache to free memory."""
        pass

    @abstractmethod
    def get_target_device(self, device_config, load_config):
        """
        Get the target device for model loading.

        Args:
            device_config: vLLM device configuration
            load_config: vLLM load configuration

        Returns:
            torch.device instance
        """
        pass


# File format constants (shared across platforms)
ENC_SUFFIX = ".enc"
SAFETENSORS_ENC = ".safetensors.enc"
GGUF_ENC = ".gguf.enc"