"""
Metadata descriptions for all registered metrics.

This module centralizes metric metadata that was previously scattered
in metrics/__init__.py, making it easier to maintain and extend.

Note: Several metadata entries have been corrected:
- recall_score: Was incorrectly described as "Report Coverage" (now correct)
- f1_score: Was incorrectly described as "Provenance Completeness" (now correct)
"""

# Metric metadata for interpretability
METRIC_METADATA = {
    "demographic_parity_diff": {
        "name": "Demographic Parity",
        "description": "Difference in positive prediction rates between groups",
        "category": "fairness",
        "required_roles": ["target", "prediction", "dimension"],
        "ideal_value": 0.0,
        "scale": (0.0, 1.0),
        "reference": "https://fairlearn.org",
    },
    "equal_opportunity_diff": {
        "name": "Equal Opportunity",
        "description": "Difference in true positive rates (only positive labels)",
        "category": "fairness",
        "required_roles": ["target", "prediction", "dimension"],
        "ideal_value": 0.0,
        "scale": (0.0, 1.0),
        "reference": "https://arxiv.org/abs/1610.02413",
    },
    "equalized_odds_ratio": {
        "name": "Equalized Odds",
        "description": "Combined TPR and FPR parity across groups",
        "category": "fairness",
        "required_roles": ["target", "prediction", "dimension"],
        "ideal_value": 0.0,
        "scale": (0.0, 2.0),
        "reference": "https://arxiv.org/abs/1610.02413",
    },
    "predictive_parity": {
        "name": "Predictive Parity",
        "description": "Difference in precision (positive predictive value) between groups",
        "category": "fairness",
        "required_roles": ["target", "prediction", "dimension"],
        "ideal_value": 0.0,
        "scale": (0.0, 1.0),
        "reference": "https://fairlearn.org",
    },
    "multiclass_demographic_parity": {
        "name": "Multi-class Demographic Parity",
        "description": "One-vs-rest demographic parity across classes. Use aggregation='max'|'macro'|'micro'",
        "category": "fairness",
        "required_roles": ["target", "prediction", "dimension"],
        "ideal_value": 0.0,
        "scale": (0.0, 1.0),
        "reference": "https://fairlearn.org/v0.8/user_guide/fairness_metrics/index.html",
    },
    "multiclass_equal_opportunity": {
        "name": "Multi-class Equal Opportunity",
        "description": "One-vs-rest TPR parity for each class across groups",
        "category": "fairness",
        "required_roles": ["target", "prediction", "dimension"],
        "ideal_value": 0.0,
        "scale": (0.0, 1.0),
        "reference": "https://arxiv.org/abs/1610.02413",
    },
    "multiclass_confusion_metrics": {
        "name": "Multi-class Confusion Matrix Metrics",
        "description": "Comprehensive per-class and per-group metrics (dict output)",
        "category": "fairness",
        "ideal_value": "See documentation",
        "scale": "Variable",
        "reference": "https://scikit-learn.org/stable/modules/generated/sklearn.metrics.confusion_matrix.html",
    },
    "k_anonymity": {
        "name": "k-Anonymity",
        "description": "Minimum group size (higher = better privacy)",
        "category": "privacy",
        "ideal_value": float("inf"),  # Higher is better
        "scale": (1.0, float("inf")),
        "reference": "https://en.wikipedia.org/wiki/K-anonymity",
    },
    "l_diversity": {
        "name": "l-Diversity",
        "description": "Minimum distinct sensitive values per group",
        "category": "privacy",
        "ideal_value": float("inf"),
        "scale": (1.0, float("inf")),
        "reference": "https://en.wikipedia.org/wiki/L-diversity",
    },
    "t_closeness": {
        "name": "t-Closeness",
        "description": "Max distribution difference (lower = better)",
        "category": "privacy",
        "ideal_value": 0.0,
        "scale": (0.0, 1.0),
        "reference": "https://en.wikipedia.org/wiki/T-closeness",
    },
    "data_minimization": {
        "name": "Data Minimization (GDPR Art. 5)",
        "description": "Proportion of non-sensitive columns",
        "category": "privacy",
        "ideal_value": 1.0,
        "scale": (0.0, 1.0),
        "reference": "https://gdpr-info.eu/",
    },
    "weighted_demographic_parity_multiclass": {
        "name": "Weighted Demographic Parity (Multi-class)",
        "description": "Demographic parity across 3+ classes with weighted aggregation",
        "category": "fairness",
        "ideal_value": 0.0,
        "scale": (0.0, 1.0),
        "reference": "https://fairlearn.org/v0.8/user_guide/fairness_metrics/index.html",
    },
    "macro_equal_opportunity_multiclass": {
        "name": "Macro-averaged Equal Opportunity (Multi-class)",
        "description": "Equal opportunity (TPR parity) averaged across all classes",
        "category": "fairness",
        "ideal_value": 0.0,
        "scale": (0.0, 1.0),
        "reference": "https://arxiv.org/abs/1610.02413",
    },
    "micro_equalized_odds_multiclass": {
        "name": "Micro-averaged Equalized Odds (Multi-class)",
        "description": "TPR and FPR parity with micro-aggregation of confusion matrices",
        "category": "fairness",
        "ideal_value": 0.0,
        "scale": (0.0, 2.0),
        "reference": "https://arxiv.org/abs/1610.02413",
    },
    "predictive_parity_multiclass": {
        "name": "Predictive Parity (Multi-class)",
        "description": "Precision parity across groups for each class",
        "category": "fairness",
        "ideal_value": 0.0,
        "scale": (0.0, 1.0),
        "reference": "https://fairlearn.org",
    },
    "path_decomposition": {
        "name": "Causal Path Decomposition",
        "description": "Decomposes protected attribute effect into direct and indirect (mediated) components",
        "category": "causal_fairness",
        "ideal_value": "Low direct effect, high indirect",
        "scale": "Variable",
        "reference": "https://en.wikipedia.org/wiki/Mediation_(statistics)",
    },
    "counterfactual_fairness": {
        "name": "Counterfactual Fairness",
        "description": "Proportion of individuals affected if protected attribute counterfactually changed",
        "category": "causal_fairness",
        "ideal_value": 0.0,
        "scale": (0.0, 1.0),
        "reference": "https://arxiv.org/abs/1705.08857",
    },
    "fairness_through_awareness": {
        "name": "Fairness Through Awareness",
        "description": "Evaluates whether legitimate features can predict outcomes without leaking protected information",
        "category": "causal_fairness",
        "ideal_value": "Low information leakage",
        "scale": "Variable",
        "reference": "https://arxiv.org/abs/1412.5644",
    },
    "causal_fairness_diagnostic": {
        "name": "Comprehensive Causal Fairness Diagnostic",
        "description": "Combined path decomposition, counterfactual fairness, and fairness-through-awareness report",
        "category": "causal_fairness",
        "ideal_value": "See diagnostic verdict",
        "scale": "Variable",
        "reference": "https://arxiv.org/abs/1705.08857",
    },
    "accuracy_score": {
        "name": "Accuracy",
        "description": "Proportion of correct predictions",
        "category": "performance",
        "required_roles": ["target", "prediction"],
        "ideal_value": 1.0,
        "scale": (0.0, 1.0),
    },
    "precision_score": {
        "name": "Precision",
        "description": "Proportion of positive identifications that were actually correct",
        "category": "performance",
        "required_roles": ["target", "prediction"],
        "ideal_value": 1.0,
        "scale": (0.0, 1.0),
    },
    "recall_score": {
        "name": "Recall",
        "description": "Proportion of actual positive cases that were correctly identified",
        "category": "performance",
        "required_roles": ["target", "prediction"],
        "ideal_value": 1.0,
        "scale": (0.0, 1.0),
    },
    "f1_score": {
        "name": "F1 Score",
        "description": "Harmonic mean of precision and recall",
        "category": "performance",
        "required_roles": ["target", "prediction"],
        "ideal_value": 1.0,
        "scale": (0.0, 1.0),
    },
    "disparate_impact": {
        "name": "Disparate Impact",
        "description": "Ratio of positive outcomes between groups",
        "category": "data_quality",
        "required_roles": ["target", "dimension"],
        "ideal_value": 1.0,
        "scale": (0.0, float("inf")),
    },
    "class_imbalance": {
        "name": "Class Imbalance",
        "description": "Ratio between minority and majority classes",
        "category": "data_quality",
        "required_roles": ["target"],
        "ideal_value": 1.0,
        "scale": (0.0, 1.0),
    },
    "group_min_positive_rate": {
        "name": "Group Minimum Positive Rate",
        "description": "Minimum positive class rate across groups (e.g., by gender or age buckets).",
        "category": "data_quality",
        "required_roles": ["target", "dimension"],
        "ideal_value": 0.5,
        "scale": (0.0, 1.0),
        "reference": "internal",
    },
    "data_completeness": {
        "name": "Data Completeness",
        "description": "Average fraction of non-missing values across dataset columns.",
        "category": "data_quality",
        "required_roles": [],
        "ideal_value": 1.0,
        "scale": (0.0, 1.0),
        "reference": "internal",
    },
    "classification_distribution": {
        "name": "ESG Classification Balance",
        "description": "Diversity score across Environmental, Social, Governance categories",
        "category": "data_quality",
        "required_roles": ["target"],
        "ideal_value": 1.0,
        "scale": (0.0, 1.0),
    },
    "report_coverage": {
        "name": "Report Coverage",
        "description": "Fraction of unique sustainability reports represented",
        "category": "data_quality",
        "required_roles": ["target"],
        "ideal_value": 1.0,
        "scale": (0.0, 1.0),
    },
    "provenance_completeness": {
        "name": "Provenance Completeness",
        "description": "Fraction of samples with traceable metadata (page_number, chunk_number)",
        "category": "data_quality",
        "required_roles": ["target"],
        "ideal_value": 1.0,
        "scale": (0.0, 1.0),
    },
    "chunk_diversity": {
        "name": "Chunk Diversity",
        "description": "Average unique chunks per sustainability report",
        "category": "data_quality",
        "required_roles": ["target", "dimension"],
        "ideal_value": 3.0,
        "scale": (1.0, float("inf")),
    },
    "subtitle_diversity": {
        "name": "Subtitle Diversity",
        "description": "Average unique subtitles per report (measures topical coverage)",
        "category": "data_quality",
        "required_roles": ["target", "dimension"],
        "ideal_value": 5.0,
        "scale": (0.0, 1.0),
    },
}
