src/paths.py

"""Centralized result-artifact paths.

All result/plot/checkpoint subdirectories are defined here so the rest of the
codebase (notebooks, scripts, Streamlit pages, report builders) references one
source of truth. Refactoring the layout = change here only.

Subdirectory layout under ``results/``::

    results/
    ├── metrics/      single-seed metrics JSONs (one per model or model category)
    ├── cv/           5-fold stratified CV JSONs (per category)
    ├── multiseed/    multi-seed split eval (per model + aggregate)
    ├── tuning/       hyperparameter grid search artifacts (per model + summary)
    ├── plots/        all PNG figures (confusion matrices, ROC, boxplots, …)
    ├── ranking/      cross-category leaderboard JSON
    └── report/       PNG exports of styled report tables (Styler -> PNG)
"""

from __future__ import annotations

from pathlib import Path

ROOT = Path(__file__).resolve().parent.parent

RESULTS_DIR  = ROOT / "results"
METRICS_DIR  = RESULTS_DIR / "metrics"
CV_DIR       = RESULTS_DIR / "cv"
MULTISEED_DIR = RESULTS_DIR / "multiseed"
TUNING_DIR   = RESULTS_DIR / "tuning"
PLOTS_DIR    = RESULTS_DIR / "plots"
RANKING_DIR  = RESULTS_DIR / "ranking"
REPORT_DIR   = RESULTS_DIR / "report"
DEMO_DIR     = RESULTS_DIR / "demo"

MODELS_DIR   = ROOT / "models"

_ALL_RESULT_SUBDIRS = (
    METRICS_DIR, CV_DIR, MULTISEED_DIR, TUNING_DIR,
    PLOTS_DIR, RANKING_DIR, REPORT_DIR, DEMO_DIR,
)


def ensure_result_dirs() -> None:
    """Create all result subdirectories if missing. Idempotent."""
    for d in _ALL_RESULT_SUBDIRS:
        d.mkdir(parents=True, exist_ok=True)


# Canonical filename mapping - single source of truth for what each artifact
# is named. Used by load_results + notebook save paths.
METRICS_FILES = {
    "trad": METRICS_DIR / "traditional_ml_metrics.json",
    "hybrid": METRICS_DIR / "hybrid_dl_metrics.json",
    "hybrid_transformers": METRICS_DIR / "hybrid_transformers_metrics.json",
    "indobert": METRICS_DIR / "indobert_metrics.json",
    "xlm_roberta": METRICS_DIR / "xlm_roberta_metrics.json",
    "mdeberta": METRICS_DIR / "mdeberta_metrics.json",
    "ibt": METRICS_DIR / "ibt_metrics.json",
}

CV_FILES = {
    "trad": CV_DIR / "traditional_ml_cv.json",
    "hybrid": CV_DIR / "hybrid_dl_cv.json",
    "transformers": CV_DIR / "transformers_cv.json",
    "hybrid_transformers": CV_DIR / "hybrid_transformers_cv.json",
}

MULTISEED_FILES = {
    "default": MULTISEED_DIR / "multiseed_eval.json",
    "tuned": MULTISEED_DIR / "tuned_multiseed_eval.json",
    "ibt_hybrid": MULTISEED_DIR / "tuned_multiseed_ibt_hybrid.json",
}

RANKING_FILE = RANKING_DIR / "cross_category_ranking.json"
TUNING_SUMMARY_FILE = TUNING_DIR / "tuning_results.json"
TUNING_IBT_HYBRID_SUMMARY_FILE = TUNING_DIR / "tuning_ibt_hybrid_results.json"