"""Public API for permutation testing."""

from __future__ import annotations

from collections.abc import Callable

import numpy as np

from .results import PermutationTestResult


def permutation_test(
    observed: np.ndarray,
    null_generator: Callable[[], np.ndarray],
    n_permutations: int = 1000,
) -> PermutationTestResult:
    """Run a generic permutation test.

    Parameters
    ----------
    observed : np.ndarray
        Observed statistic or observed data summary.
    null_generator : Callable[[], np.ndarray]
        Callable returning one draw from the null distribution.
    n_permutations : int, optional
        Number of permutations to request.

    Returns
    -------
    PermutationTestResult
        Result object containing the observed statistic, null distribution,
        and associated p-value.
    """

    raise NotImplementedError()
