"""Paper names and executable fixed-family constructors (no baselines)."""

from __future__ import annotations

from typing import Any

FIXED_METHODS = {
    "wisp_ss": "WISP-SS",
    "wisp_rc": "WISP-RC",
    "wisp_so": "WISP-SO",
    "wisp_cse": "WISP-CSE",
    "wisp_gis": "WISP-GIS",
    "wisp_cis": "WISP-CIS",
    "wisp_ese": "WISP-ESE",
}
SELECTION_METHODS = {
    "wisp_select5": "WISP-Select5",
    "wisp_select7": "WISP-Select7",
}
SEARCH_METHODS = {
    "wisp_random": "WISP-Random",
    "wisp_evolution": "WISP-Evolution",
}


def list_methods() -> list[dict[str, Any]]:
    """Describe the full paper series without importing optional backends."""
    out: list[dict[str, Any]] = []
    for group, names in (
        ("fixed_family", FIXED_METHODS),
        ("validation_selection", SELECTION_METHODS),
        ("search", SEARCH_METHODS),
    ):
        for method_id, name in names.items():
            out.append({
                "method_id": method_id,
                "paper_name": name,
                "group": group,
                "checkpoint_loading": True,
                "family_fit": group == "fixed_family",
                "select_fit": group == "validation_selection",
                "search": group == "search",
            })
    return out


def build_family(method_id: str, *, seed: int, n_jobs: int = 1,
                 direct: bool = False, overrides: dict[str, Any] | None = None) -> Any:
    """Construct one fixed WISP family; construction does not fit it."""
    if method_id not in FIXED_METHODS:
        raise ValueError(f"family-fit supports fixed families only: {', '.join(FIXED_METHODS)}")
    if n_jobs < 1:
        raise ValueError("n_jobs must be positive")
    from wisp.registry import build_method

    params = dict(overrides or {})
    if direct:
        params["use_hmm"] = False
    return build_method(method_id, seed=seed, n_jobs=n_jobs, overrides=params)