"""Benchmark result objects for NeuroWeave."""

from __future__ import annotations

from dataclasses import dataclass, field
from typing import Any

import pandas as pd


@dataclass
class BenchmarkResult:
    """Store outputs from a single benchmark experiment.

    Parameters
    ----------
    scores : dict[str, float]
        Benchmark scores keyed by evaluation label.
    metrics : dict[str, Any]
        Additional benchmark metrics.
    metadata : dict[str, Any]
        Metadata describing benchmark configuration or execution.
    """

    scores: dict[str, float] = field(default_factory=dict)
    metrics: dict[str, Any] = field(default_factory=dict)
    metadata: dict[str, Any] = field(default_factory=dict)

    def summary(self) -> str:
        """Summarize a benchmark result.

        Returns
        -------
        str
            Human-readable benchmark summary.
        """

        raise NotImplementedError()

    def plot(self) -> None:
        """Plot benchmark outputs."""

        raise NotImplementedError()

    def to_dataframe(self) -> pd.DataFrame:
        """Convert benchmark outputs to a tabular representation.

        Returns
        -------
        pandas.DataFrame
            Tabular benchmark summary.
        """

        raise NotImplementedError()


@dataclass
class BenchmarkSuiteResult:
    """Store outputs from a suite of benchmark experiments.

    Parameters
    ----------
    benchmark_results : list[BenchmarkResult]
        Individual benchmark results included in the suite.
    aggregate_scores : dict[str, float]
        Aggregate benchmark scores across the suite.
    """

    benchmark_results: list[BenchmarkResult] = field(default_factory=list)
    aggregate_scores: dict[str, float] = field(default_factory=dict)

    def summary(self) -> str:
        """Summarize benchmark suite results.

        Returns
        -------
        str
            Human-readable suite summary.
        """

        raise NotImplementedError()

    def plot_comparison(self) -> None:
        """Plot comparisons across benchmark results."""

        raise NotImplementedError()

    def export(self, path: str) -> None:
        """Export benchmark suite results.

        Parameters
        ----------
        path : str
            Destination path for exported suite outputs.
        """

        raise NotImplementedError()
