ins-pricing 0.1.11__py3-none-any.whl → 0.2.0__py3-none-any.whl

ins_pricing/cli/utils/__init__.py

@@ -0,0 +1 @@
+"""Shared CLI utilities for ins_pricing modelling."""

ins_pricing/cli/utils/cli_common.py

@@ -0,0 +1,320 @@
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple, Union
+
+import pandas as pd
+from sklearn.model_selection import GroupShuffleSplit, train_test_split
+
+
+PLOT_MODEL_LABELS: Dict[str, Tuple[str, str]] = {
+    "glm": ("GLM", "pred_glm"),
+    "xgb": ("Xgboost", "pred_xgb"),
+    "resn": ("ResNet", "pred_resn"),
+    "ft": ("FTTransformer", "pred_ft"),
+    "gnn": ("GNN", "pred_gnn"),
+}
+
+PYTORCH_TRAINERS = {"resn", "ft", "gnn"}
+
+
+def dedupe_preserve_order(items: Iterable[str]) -> List[str]:
+    seen = set()
+    unique: List[str] = []
+    for item in items:
+        if item not in seen:
+            unique.append(item)
+            seen.add(item)
+    return unique
+
+
+def build_model_names(prefixes: Sequence[str], suffixes: Sequence[str]) -> List[str]:
+    names: List[str] = []
+    for suffix in suffixes:
+        names.extend(f"{prefix}_{suffix}" for prefix in prefixes)
+    return names
+
+
+def parse_model_pairs(raw_pairs: List) -> List[Tuple[str, str]]:
+    pairs: List[Tuple[str, str]] = []
+    for pair in raw_pairs:
+        if isinstance(pair, (list, tuple)) and len(pair) == 2:
+            pairs.append((str(pair[0]), str(pair[1])))
+        elif isinstance(pair, str):
+            parts = [p.strip() for p in pair.split(",") if p.strip()]
+            if len(parts) == 2:
+                pairs.append((parts[0], parts[1]))
+    return pairs
+
+
+def resolve_path(value: Optional[str], base_dir: Path) -> Optional[Path]:
+    if value is None:
+        return None
+    if not isinstance(value, str) or not value.strip():
+        return None
+    p = Path(value)
+    if p.is_absolute():
+        return p
+    return (base_dir / p).resolve()
+
+
+def resolve_dir_path(
+    value: Optional[Union[str, Path]],
+    base_dir: Path,
+    *,
+    create: bool = False,
+) -> Optional[Path]:
+    if value is None:
+        return None
+    if isinstance(value, Path):
+        path = value if value.is_absolute() else (base_dir / value).resolve()
+    else:
+        value_str = str(value)
+        if not value_str.strip():
+            return None
+        path = resolve_path(value_str, base_dir)
+        if path is None:
+            path = Path(value_str)
+            if not path.is_absolute():
+                path = (base_dir / path).resolve()
+    if create:
+        path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def _infer_format_from_path(path: Path) -> str:
+    suffix = path.suffix.lower()
+    if suffix in {".parquet", ".pq"}:
+        return "parquet"
+    if suffix in {".feather", ".ft"}:
+        return "feather"
+    return "csv"
+
+
+def resolve_data_path(
+    data_dir: Path,
+    model_name: str,
+    *,
+    data_format: str = "csv",
+    path_template: Optional[str] = None,
+) -> Path:
+    fmt = str(data_format or "csv").strip().lower()
+    template = path_template or "{model_name}.{ext}"
+    if fmt == "auto":
+        candidates = [
+            data_dir / template.format(model_name=model_name, ext="parquet"),
+            data_dir / template.format(model_name=model_name, ext="feather"),
+            data_dir / template.format(model_name=model_name, ext="csv"),
+        ]
+        for cand in candidates:
+            if cand.exists():
+                return cand.resolve()
+        return candidates[-1].resolve()
+    ext = "csv" if fmt in {"csv"} else fmt
+    return (data_dir / template.format(model_name=model_name, ext=ext)).resolve()
+
+
+def load_dataset(
+    path: Path,
+    *,
+    data_format: str = "auto",
+    dtype_map: Optional[Dict[str, Any]] = None,
+    low_memory: bool = False,
+) -> pd.DataFrame:
+    fmt = str(data_format or "auto").strip().lower()
+    if fmt == "auto":
+        fmt = _infer_format_from_path(path)
+    if fmt == "parquet":
+        df = pd.read_parquet(path)
+    elif fmt == "feather":
+        df = pd.read_feather(path)
+    elif fmt == "csv":
+        df = pd.read_csv(path, low_memory=low_memory, dtype=dtype_map or None)
+    else:
+        raise ValueError(f"Unsupported data_format: {data_format}")
+    if dtype_map:
+        for col, dtype in dtype_map.items():
+            if col in df.columns:
+                df[col] = df[col].astype(dtype)
+    return df
+
+
+def coerce_dataset_types(raw: pd.DataFrame) -> pd.DataFrame:
+    data = raw.copy()
+    for col in data.columns:
+        s = data[col]
+        if pd.api.types.is_numeric_dtype(s):
+            data[col] = pd.to_numeric(s, errors="coerce").fillna(0)
+        else:
+            data[col] = s.astype("object").fillna("<NA>")
+    return data
+
+
+def split_train_test(
+    df: pd.DataFrame,
+    *,
+    holdout_ratio: float,
+    strategy: str = "random",
+    group_col: Optional[str] = None,
+    time_col: Optional[str] = None,
+    time_ascending: bool = True,
+    rand_seed: Optional[int] = None,
+    reset_index_mode: str = "none",
+    ratio_label: str = "holdout_ratio",
+    include_strategy_in_ratio_error: bool = False,
+    validate_ratio: bool = True,
+) -> Tuple[pd.DataFrame, pd.DataFrame]:
+    strategy = str(strategy or "random").strip().lower()
+    holdout_ratio = float(holdout_ratio)
+    if include_strategy_in_ratio_error and strategy in {"time", "timeseries", "temporal", "group", "grouped"}:
+        strategy_label = "time" if strategy in {"time", "timeseries", "temporal"} else "group"
+        ratio_error = (
+            f"{ratio_label} must be in (0, 1) for {strategy_label} split; got {holdout_ratio}."
+        )
+    else:
+        ratio_error = f"{ratio_label} must be in (0, 1); got {holdout_ratio}."
+
+    if strategy in {"time", "timeseries", "temporal"}:
+        if not time_col:
+            raise ValueError("split_time_col is required for time split_strategy.")
+        if time_col not in df.columns:
+            raise KeyError(f"split_time_col '{time_col}' not in dataset columns.")
+        if validate_ratio and not (0.0 < holdout_ratio < 1.0):
+            raise ValueError(ratio_error)
+        ordered = df.sort_values(time_col, ascending=bool(time_ascending))
+        cutoff = int(len(ordered) * (1.0 - holdout_ratio))
+        if cutoff <= 0 or cutoff >= len(ordered):
+            raise ValueError(
+                f"{ratio_label}={holdout_ratio} leaves no data for train/test split.")
+        train_df = ordered.iloc[:cutoff]
+        test_df = ordered.iloc[cutoff:]
+    elif strategy in {"group", "grouped"}:
+        if not group_col:
+            raise ValueError("split_group_col is required for group split_strategy.")
+        if group_col not in df.columns:
+            raise KeyError(f"split_group_col '{group_col}' not in dataset columns.")
+        if validate_ratio and not (0.0 < holdout_ratio < 1.0):
+            raise ValueError(ratio_error)
+        splitter = GroupShuffleSplit(
+            n_splits=1,
+            test_size=holdout_ratio,
+            random_state=rand_seed,
+        )
+        train_idx, test_idx = next(splitter.split(df, groups=df[group_col]))
+        train_df = df.iloc[train_idx]
+        test_df = df.iloc[test_idx]
+    else:
+        train_df, test_df = train_test_split(
+            df, test_size=holdout_ratio, random_state=rand_seed
+        )
+
+    if reset_index_mode == "always" or (
+        reset_index_mode == "time_group"
+        and strategy in {"time", "timeseries", "temporal", "group", "grouped"}
+    ):
+        train_df = train_df.reset_index(drop=True)
+        test_df = test_df.reset_index(drop=True)
+    return train_df, test_df
+
+
+def fingerprint_file(path: Path, *, max_bytes: int = 10_485_760) -> Dict[str, Any]:
+    path = Path(path)
+    stat = path.stat()
+    h = hashlib.sha256()
+    remaining = int(max_bytes)
+    with path.open("rb") as fh:
+        while remaining > 0:
+            chunk = fh.read(min(1024 * 1024, remaining))
+            if not chunk:
+                break
+            h.update(chunk)
+            remaining -= len(chunk)
+    return {
+        "path": str(path),
+        "size": int(stat.st_size),
+        "mtime": int(stat.st_mtime),
+        "sha256_prefix": h.hexdigest(),
+        "max_bytes": int(max_bytes),
+    }
+
+
+def _load_cli_config():
+    try:
+        from . import cli_config as _cli_config  # type: ignore
+    except Exception:  # pragma: no cover
+        import cli_config as _cli_config  # type: ignore
+    return _cli_config
+
+
+def resolve_config_path(raw: str, script_dir: Path) -> Path:
+    return _load_cli_config().resolve_config_path(raw, script_dir)
+
+
+def load_config_json(path: Path, required_keys: Sequence[str]) -> Dict[str, Any]:
+    return _load_cli_config().load_config_json(path, required_keys)
+
+
+def set_env(env_overrides: Dict[str, Any]) -> None:
+    _load_cli_config().set_env(env_overrides)
+
+
+def normalize_config_paths(cfg: Dict[str, Any], config_path: Path) -> Dict[str, Any]:
+    return _load_cli_config().normalize_config_paths(cfg, config_path)
+
+
+def resolve_dtype_map(value: Any, base_dir: Path) -> Dict[str, Any]:
+    return _load_cli_config().resolve_dtype_map(value, base_dir)
+
+
+def resolve_data_config(
+    cfg: Dict[str, Any],
+    config_path: Path,
+    *,
+    create_data_dir: bool = False,
+) -> Tuple[Path, str, Optional[str], Dict[str, Any]]:
+    return _load_cli_config().resolve_data_config(
+        cfg,
+        config_path,
+        create_data_dir=create_data_dir,
+    )
+
+
+def resolve_report_config(cfg: Dict[str, Any]) -> Dict[str, Any]:
+    return _load_cli_config().resolve_report_config(cfg)
+
+
+def resolve_split_config(cfg: Dict[str, Any]) -> Dict[str, Any]:
+    return _load_cli_config().resolve_split_config(cfg)
+
+
+def resolve_runtime_config(cfg: Dict[str, Any]) -> Dict[str, Any]:
+    return _load_cli_config().resolve_runtime_config(cfg)
+
+
+def resolve_output_dirs(
+    cfg: Dict[str, Any],
+    config_path: Path,
+    *,
+    output_override: Optional[str] = None,
+) -> Dict[str, Optional[str]]:
+    return _load_cli_config().resolve_output_dirs(
+        cfg,
+        config_path,
+        output_override=output_override,
+    )
+
+
+def resolve_and_load_config(
+    raw: str,
+    script_dir: Path,
+    required_keys: Sequence[str],
+    *,
+    apply_env: bool = True,
+) -> Tuple[Path, Dict[str, Any]]:
+    return _load_cli_config().resolve_and_load_config(
+        raw,
+        script_dir,
+        required_keys,
+        apply_env=apply_env,
+    )

ins_pricing/cli/utils/cli_config.py

@@ -0,0 +1,375 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional, Sequence, Tuple
+
+try:
+    from .cli_common import resolve_dir_path, resolve_path  # type: ignore
+except Exception:  # pragma: no cover
+    from cli_common import resolve_dir_path, resolve_path  # type: ignore
+
+
+def resolve_config_path(raw: str, script_dir: Path) -> Path:
+    candidate = Path(raw)
+    if candidate.exists():
+        return candidate.resolve()
+    candidate2 = (script_dir / raw)
+    if candidate2.exists():
+        return candidate2.resolve()
+    raise FileNotFoundError(
+        f"Config file not found: {raw}. Tried: {Path(raw).resolve()} and {candidate2.resolve()}"
+    )
+
+
+def load_config_json(path: Path, required_keys: Sequence[str]) -> Dict[str, Any]:
+    cfg = json.loads(path.read_text(encoding="utf-8"))
+    missing = [key for key in required_keys if key not in cfg]
+    if missing:
+        raise ValueError(f"Missing required keys in {path}: {missing}")
+    return cfg
+
+
+def set_env(env_overrides: Dict[str, Any]) -> None:
+    """Apply environment variables from config.json.
+
+    Notes (DDP/Optuna hang debugging):
+    - You can add these keys into config.json's `env` to debug distributed hangs:
+      - `TORCH_DISTRIBUTED_DEBUG=DETAIL`
+      - `NCCL_DEBUG=INFO`
+      - `BAYESOPT_DDP_BARRIER_DEBUG=1`
+      - `BAYESOPT_DDP_BARRIER_TIMEOUT=300`
+      - `BAYESOPT_CUDA_SYNC=1` (optional; can slow down)
+      - `BAYESOPT_CUDA_IPC_COLLECT=1` (optional; can slow down)
+    - This function uses `os.environ.setdefault`, so a value already set in the
+      shell will take precedence over config.json.
+    """
+    for key, value in (env_overrides or {}).items():
+        os.environ.setdefault(str(key), str(value))
+
+
+def _looks_like_url(value: str) -> bool:
+    value = str(value)
+    return "://" in value
+
+
+def normalize_config_paths(cfg: Dict[str, Any], config_path: Path) -> Dict[str, Any]:
+    """Resolve relative paths against the config.json directory.
+
+    Fields handled:
+    - data_dir / output_dir / optuna_storage / gnn_graph_cache
+    - best_params_files (dict: model_key -> path)
+    """
+    base_dir = config_path.parent
+    out = dict(cfg)
+
+    for key in ("data_dir", "output_dir", "gnn_graph_cache", "preprocess_artifact_path",
+                "prediction_cache_dir", "report_output_dir", "registry_path"):
+        if key in out and isinstance(out.get(key), str):
+            resolved = resolve_path(out.get(key), base_dir)
+            if resolved is not None:
+                out[key] = str(resolved)
+
+    storage = out.get("optuna_storage")
+    if isinstance(storage, str) and storage.strip():
+        if not _looks_like_url(storage):
+            resolved = resolve_path(storage, base_dir)
+            if resolved is not None:
+                out["optuna_storage"] = str(resolved)
+
+    best_files = out.get("best_params_files")
+    if isinstance(best_files, dict):
+        resolved_map: Dict[str, str] = {}
+        for mk, path_str in best_files.items():
+            if not isinstance(path_str, str):
+                continue
+            resolved = resolve_path(path_str, base_dir)
+            resolved_map[str(mk)] = str(resolved) if resolved is not None else str(path_str)
+        out["best_params_files"] = resolved_map
+
+    return out
+
+
+def resolve_dtype_map(value: Any, base_dir: Path) -> Dict[str, Any]:
+    if value is None:
+        return {}
+    if isinstance(value, dict):
+        return {str(k): v for k, v in value.items()}
+    if isinstance(value, str):
+        path = resolve_path(value, base_dir)
+        if path is None or not path.exists():
+            raise FileNotFoundError(f"dtype_map not found: {value}")
+        payload = json.loads(path.read_text(encoding="utf-8"))
+        if not isinstance(payload, dict):
+            raise ValueError(f"dtype_map must be a dict: {path}")
+        return {str(k): v for k, v in payload.items()}
+    raise ValueError("dtype_map must be a dict or JSON path.")
+
+
+def resolve_data_config(
+    cfg: Dict[str, Any],
+    config_path: Path,
+    *,
+    create_data_dir: bool = False,
+) -> Tuple[Path, str, Optional[str], Dict[str, Any]]:
+    base_dir = config_path.parent
+    data_dir = resolve_dir_path(cfg.get("data_dir"), base_dir, create=create_data_dir)
+    if data_dir is None:
+        raise ValueError("data_dir is required in config.json.")
+    data_format = cfg.get("data_format", "csv")
+    data_path_template = cfg.get("data_path_template")
+    dtype_map = resolve_dtype_map(cfg.get("dtype_map"), base_dir)
+    return data_dir, data_format, data_path_template, dtype_map
+
+
+def add_config_json_arg(parser: argparse.ArgumentParser, *, help_text: str) -> None:
+    parser.add_argument(
+        "--config-json",
+        required=True,
+        help=help_text,
+    )
+
+
+def add_output_dir_arg(parser: argparse.ArgumentParser, *, help_text: str) -> None:
+    parser.add_argument(
+        "--output-dir",
+        default=None,
+        help=help_text,
+    )
+
+
+def resolve_model_path_value(
+    value: Any,
+    *,
+    model_name: str,
+    base_dir: Path,
+    data_dir: Optional[Path] = None,
+) -> Optional[Path]:
+    if value is None:
+        return None
+    if isinstance(value, dict):
+        value = value.get(model_name)
+    if value is None:
+        return None
+    path_str = str(value)
+    try:
+        path_str = path_str.format(model_name=model_name)
+    except Exception:
+        pass
+    if data_dir is not None and not Path(path_str).is_absolute():
+        candidate = data_dir / path_str
+        if candidate.exists():
+            return candidate.resolve()
+    resolved = resolve_path(path_str, base_dir)
+    if resolved is None:
+        return None
+    return resolved
+
+
+def resolve_explain_save_root(value: Any, base_dir: Path) -> Optional[Path]:
+    if not value:
+        return None
+    path_str = str(value)
+    resolved = resolve_path(path_str, base_dir)
+    return resolved if resolved is not None else Path(path_str)
+
+
+def resolve_explain_save_dir(
+    save_root: Optional[Path],
+    *,
+    result_dir: Optional[Any],
+) -> Path:
+    if save_root is not None:
+        return Path(save_root)
+    if result_dir is None:
+        raise ValueError("result_dir is required when explain save_root is not set.")
+    return Path(result_dir) / "explain"
+
+
+def resolve_explain_output_overrides(
+    explain_cfg: Dict[str, Any],
+    *,
+    model_name: str,
+    base_dir: Path,
+) -> Dict[str, Optional[Path]]:
+    return {
+        "model_dir": resolve_model_path_value(
+            explain_cfg.get("model_dir"),
+            model_name=model_name,
+            base_dir=base_dir,
+            data_dir=None,
+        ),
+        "result_dir": resolve_model_path_value(
+            explain_cfg.get("result_dir") or explain_cfg.get("results_dir"),
+            model_name=model_name,
+            base_dir=base_dir,
+            data_dir=None,
+        ),
+        "plot_dir": resolve_model_path_value(
+            explain_cfg.get("plot_dir"),
+            model_name=model_name,
+            base_dir=base_dir,
+            data_dir=None,
+        ),
+    }
+
+
+def resolve_and_load_config(
+    raw: str,
+    script_dir: Path,
+    required_keys: Sequence[str],
+    *,
+    apply_env: bool = True,
+) -> Tuple[Path, Dict[str, Any]]:
+    config_path = resolve_config_path(raw, script_dir)
+    cfg = load_config_json(config_path, required_keys=required_keys)
+    cfg = normalize_config_paths(cfg, config_path)
+    if apply_env:
+        set_env(cfg.get("env", {}))
+    return config_path, cfg
+
+
+def resolve_report_config(cfg: Dict[str, Any]) -> Dict[str, Any]:
+    def _as_list(value: Any) -> list[str]:
+        if value is None:
+            return []
+        if isinstance(value, (list, tuple, set)):
+            return [str(item) for item in value]
+        return [str(value)]
+
+    report_output_dir = cfg.get("report_output_dir")
+    report_group_cols = _as_list(cfg.get("report_group_cols"))
+    if not report_group_cols:
+        report_group_cols = None
+    report_time_col = cfg.get("report_time_col")
+    report_time_freq = cfg.get("report_time_freq", "M")
+    report_time_ascending = bool(cfg.get("report_time_ascending", True))
+    psi_bins = cfg.get("psi_bins", 10)
+    psi_strategy = cfg.get("psi_strategy", "quantile")
+    psi_features = _as_list(cfg.get("psi_features"))
+    if not psi_features:
+        psi_features = None
+    calibration_cfg = cfg.get("calibration", {}) or {}
+    threshold_cfg = cfg.get("threshold", {}) or {}
+    bootstrap_cfg = cfg.get("bootstrap", {}) or {}
+    register_model = bool(cfg.get("register_model", False))
+    registry_path = cfg.get("registry_path")
+    registry_tags = cfg.get("registry_tags", {})
+    registry_status = cfg.get("registry_status", "candidate")
+    data_fingerprint_max_bytes = int(
+        cfg.get("data_fingerprint_max_bytes", 10_485_760))
+    calibration_enabled = bool(
+        calibration_cfg.get("enable", False) or calibration_cfg.get("method")
+    )
+    threshold_enabled = bool(
+        threshold_cfg.get("enable", False)
+        or threshold_cfg.get("value") is not None
+        or threshold_cfg.get("metric")
+    )
+    bootstrap_enabled = bool(bootstrap_cfg.get("enable", False))
+    report_enabled = any([
+        bool(report_output_dir),
+        register_model,
+        bool(report_group_cols),
+        bool(report_time_col),
+        bool(psi_features),
+        calibration_enabled,
+        threshold_enabled,
+        bootstrap_enabled,
+    ])
+    return {
+        "report_output_dir": report_output_dir,
+        "report_group_cols": report_group_cols,
+        "report_time_col": report_time_col,
+        "report_time_freq": report_time_freq,
+        "report_time_ascending": report_time_ascending,
+        "psi_bins": psi_bins,
+        "psi_strategy": psi_strategy,
+        "psi_features": psi_features,
+        "calibration_cfg": calibration_cfg,
+        "threshold_cfg": threshold_cfg,
+        "bootstrap_cfg": bootstrap_cfg,
+        "register_model": register_model,
+        "registry_path": registry_path,
+        "registry_tags": registry_tags,
+        "registry_status": registry_status,
+        "data_fingerprint_max_bytes": data_fingerprint_max_bytes,
+        "report_enabled": report_enabled,
+    }
+
+
+def resolve_split_config(cfg: Dict[str, Any]) -> Dict[str, Any]:
+    prop_test = cfg.get("prop_test", 0.25)
+    holdout_ratio = cfg.get("holdout_ratio", prop_test)
+    if holdout_ratio is None:
+        holdout_ratio = prop_test
+    val_ratio = cfg.get("val_ratio", prop_test)
+    if val_ratio is None:
+        val_ratio = prop_test
+    split_strategy = str(cfg.get("split_strategy", "random")).strip().lower()
+    split_group_col = cfg.get("split_group_col")
+    split_time_col = cfg.get("split_time_col")
+    split_time_ascending = bool(cfg.get("split_time_ascending", True))
+    cv_strategy = cfg.get("cv_strategy")
+    cv_group_col = cfg.get("cv_group_col")
+    cv_time_col = cfg.get("cv_time_col")
+    cv_time_ascending = cfg.get("cv_time_ascending", split_time_ascending)
+    cv_splits = cfg.get("cv_splits")
+    ft_oof_folds = cfg.get("ft_oof_folds")
+    ft_oof_strategy = cfg.get("ft_oof_strategy")
+    ft_oof_shuffle = cfg.get("ft_oof_shuffle", True)
+    return {
+        "prop_test": prop_test,
+        "holdout_ratio": holdout_ratio,
+        "val_ratio": val_ratio,
+        "split_strategy": split_strategy,
+        "split_group_col": split_group_col,
+        "split_time_col": split_time_col,
+        "split_time_ascending": split_time_ascending,
+        "cv_strategy": cv_strategy,
+        "cv_group_col": cv_group_col,
+        "cv_time_col": cv_time_col,
+        "cv_time_ascending": cv_time_ascending,
+        "cv_splits": cv_splits,
+        "ft_oof_folds": ft_oof_folds,
+        "ft_oof_strategy": ft_oof_strategy,
+        "ft_oof_shuffle": ft_oof_shuffle,
+    }
+
+
+def resolve_runtime_config(cfg: Dict[str, Any]) -> Dict[str, Any]:
+    return {
+        "save_preprocess": bool(cfg.get("save_preprocess", False)),
+        "preprocess_artifact_path": cfg.get("preprocess_artifact_path"),
+        "rand_seed": cfg.get("rand_seed", 13),
+        "epochs": cfg.get("epochs", 50),
+        "plot_path_style": cfg.get("plot_path_style"),
+        "reuse_best_params": bool(cfg.get("reuse_best_params", False)),
+        "xgb_max_depth_max": int(cfg.get("xgb_max_depth_max", 25)),
+        "xgb_n_estimators_max": int(cfg.get("xgb_n_estimators_max", 500)),
+        "optuna_storage": cfg.get("optuna_storage"),
+        "optuna_study_prefix": cfg.get("optuna_study_prefix"),
+        "best_params_files": cfg.get("best_params_files"),
+        "bo_sample_limit": cfg.get("bo_sample_limit"),
+        "cache_predictions": bool(cfg.get("cache_predictions", False)),
+        "prediction_cache_dir": cfg.get("prediction_cache_dir"),
+        "prediction_cache_format": cfg.get("prediction_cache_format", "parquet"),
+        "ddp_min_rows": cfg.get("ddp_min_rows", 50000),
+    }
+
+
+def resolve_output_dirs(
+    cfg: Dict[str, Any],
+    config_path: Path,
+    *,
+    output_override: Optional[str] = None,
+) -> Dict[str, Optional[str]]:
+    output_root = resolve_dir_path(
+        output_override or cfg.get("output_dir"),
+        config_path.parent,
+    )
+    return {
+        "output_dir": str(output_root) if output_root is not None else None,
+    }