"""Shared helpers for deciding whether the optional ML stack should be used."""
from __future__ import annotations

import functools
import importlib.util

from ..config import settings


@functools.lru_cache(maxsize=1)
def _torch_importable() -> bool:
    return importlib.util.find_spec("torch") is not None


def ml_available() -> bool:
    """Resolve the ENABLE_ML tri-state against what's actually installed.

    - "false" -> never use ML (always heuristic fallback)
    - "true"  -> prefer ML (individual modules still degrade on runtime errors)
    - "auto"  -> use ML iff torch is importable
    """
    mode = settings.ENABLE_ML
    if mode == "false":
        return False
    if mode == "true":
        return True
    return _torch_importable()