backend/core/interference.py

"""Interference level resolution for generation depth (minimum / medium / maximum)."""

from __future__ import annotations

from typing import Literal

InterferenceLevel = Literal["minimum", "medium", "maximum"]

_SURVEY_TO_INTERFERENCE: dict[int, InterferenceLevel] = {
    1: "minimum",
    2: "medium",
    3: "maximum",
}


def resolve_interference_level(
    explicit: str | None,
    survey_level: int = 3,
) -> InterferenceLevel:
    """Resolve the composition path from an explicit level or RICS survey tier."""
    if explicit:
        level = explicit.strip().lower()
        if level in _SURVEY_TO_INTERFERENCE.values():
            return level  # type: ignore[return-value]
    tier = max(1, min(3, int(survey_level or 3)))
    return _SURVEY_TO_INTERFERENCE.get(tier, "maximum")


def uses_llm_composition(interference_level: InterferenceLevel) -> bool:
    """Medium and maximum always target the LLM compose/expand path when available."""
    return interference_level in ("medium", "maximum")