"""Public API for cluster-based statistical inference."""

from __future__ import annotations

import numpy as np

from .results import ClusterTestResult


def cluster_permutation_test(
    data: np.ndarray,
    threshold: float,
    n_permutations: int = 1000,
) -> ClusterTestResult:
    """Run a cluster-based permutation test.

    Parameters
    ----------
    data : np.ndarray
        Statistical map or structured test input.
    threshold : float
        Cluster-forming threshold.
    n_permutations : int, optional
        Number of permutations to request.

    Returns
    -------
    ClusterTestResult
        Result object describing clusters, their p-values, and the test map.
    """

    raise NotImplementedError()
