"""
نقطه‌ی ورودِ RAG برای ai_tutor.

ai_tutor.views.generate_tutor_answer وقتی rag_is_configured() باشه این را
صدا می‌زنه؛ در غیرِ این‌صورت به همون پاسخِ stubِ قبلی برمی‌گرده.
"""
import logging

from .config import rag_is_configured  # noqa: F401  (re-export برای ai_tutor)
from .generation import generate_answer
from .retrieval import retrieve_context

logger = logging.getLogger(__name__)


def answer_question(user_question: str, *, subject: str = '', grade_id=None,
                    lesson_number=None) -> tuple[str, list[str], list[dict]]:
    """
    خروجی: (answer, follow_ups, used_chunks)

    used_chunks = [{title, summary, score}, ...] — ممکنه خالی باشه وقتی
    subject/lesson_number ارسال نشده یا اون درس هنوز در Qdrant نیست؛ در این
    حالت پاسخ به‌صورتِ «تدریسِ عمومی» تولید می‌شه (بدونِ استناد به کتاب).

    استثناهای شبکه/provider اینجا خفه نمی‌شن؛ لایه‌ی بالا (AskAIView) اون‌ها
    رو به 503 AIProviderUnavailable تبدیل می‌کنه.
    """
    context, _meta = retrieve_context(
        user_question,
        subject=subject,
        grade_id=grade_id,
        lesson_number=lesson_number,
    )
    answer, follow_ups = generate_answer(user_question, context)
    return answer, follow_ups, context