"""Benchmark metric interfaces for NeuroWeave."""

from __future__ import annotations

from typing import Any

import numpy as np


def kernel_recovery_error(
    true_kernel: np.ndarray,
    estimated_kernel: np.ndarray,
) -> float:
    """Measure kernel reconstruction error.

    Parameters
    ----------
    true_kernel : np.ndarray
        Ground-truth kernel.
    estimated_kernel : np.ndarray
        Estimated kernel recovered by a model.

    Returns
    -------
    float
        Scalar kernel-recovery error metric.
    """

    raise NotImplementedError()


def prediction_score(
    y_true: np.ndarray,
    y_pred: np.ndarray,
) -> float:
    """Evaluate prediction accuracy for benchmark outputs.

    Parameters
    ----------
    y_true : np.ndarray
        Ground-truth target values.
    y_pred : np.ndarray
        Predicted target values.

    Returns
    -------
    float
        Scalar prediction-performance score.
    """

    raise NotImplementedError()


def feature_identifiability(
    true_features: Any,
    estimated_contributions: Any,
) -> float:
    """Assess recovery of feature-space contributions.

    Parameters
    ----------
    true_features : Any
        Ground-truth feature-space description.
    estimated_contributions : Any
        Estimated feature-space contributions.

    Returns
    -------
    float
        Scalar feature-identifiability score.
    """

    raise NotImplementedError()
