"""
Response Generation Agent.

Takes the final, compressed evidence set and the user's question, and
produces the answer. This is the only place in the pipeline that calls
the LLM to generate answer text — kept separate so hallucination
detection and evidence verification can audit its output without being
tangled into the generation call itself.
"""

from typing import List, Optional

from langchain_core.documents import Document

from hybrid_rag_pipeline import build_prompt_context


def generate_response(
    llm,
    docs: List[Document],
    query: str,
    extra_instructions: Optional[str] = None,
) -> str:
    """
    Build the grounded prompt from docs + query (via build_prompt_context
    from hybrid_rag_pipeline.py) and invoke the LLM to produce the answer.

    extra_instructions, when given, is appended to the prompt — used on
    a rewrite retry to push the model toward stricter grounding/
    completeness/citation behavior without changing build_prompt_context
    itself.
    """
    prompt = build_prompt_context(docs, query)
    if extra_instructions:
        prompt = f"{prompt}\n\nAdditional instructions:\n{extra_instructions}\n"
    response = llm.invoke(prompt)
    return response.content