Source code for lalandre_rag.response.factories

"""
Response factory functions for each RAG mode.
"""

from typing import Any, Dict, List, Optional

from .builder import RAGResponse, ResponseBuilder




def create_llm_only_response(query: str, answer: str, include_warning: bool = True) -> Dict[str, Any]:
    """Factory pour réponse mode llm_only."""
    builder = ResponseBuilder(mode="llm_only", query=query).set_answer(answer).set_sources([])

    if include_warning:
        builder.add_metadata(
            "warning",
            "WARNING: Cette réponse est générée uniquement par le LLM "
            "et n'est pas basée sur votre base documentaire. "
            "Elle peut contenir des inexactitudes.",
        )

    return builder.build()





def create_rag_response(
    query: str,
    answer: str,
    documents: List[Dict[str, Any]],
    context_summary: Optional[Dict[str, Any]] = None,
    acts: Optional[Dict[str, Dict[str, Any]]] = None,
) -> Dict[str, Any]:
    """Factory pour réponse mode rag (hybrid RAG)."""
    builder = ResponseBuilder(mode="rag", query=query).set_answer(answer).set_sources(documents).set_acts(acts or {})

    if context_summary:
        builder.add_metadata("context_summary", context_summary)

    return builder.build()





def create_summarize_response(
    query: str, answer: str, documents: List[Dict[str, Any]], acts: Optional[Dict[str, Dict[str, Any]]] = None
) -> Dict[str, Any]:
    """Factory for summarize-mode response."""
    return (
        ResponseBuilder(mode="summarize", query=query)
        .set_answer(answer)
        .set_sources(documents)
        .set_acts(acts or {})
        .build()
    )





def create_compare_response(
    query: str,
    answer: str,
    documents: List[Dict[str, Any]],
    documents_compared: List[str],
    acts: Optional[Dict[str, Dict[str, Any]]] = None,
) -> Dict[str, Any]:
    """Factory for compare-mode response."""
    return (
        ResponseBuilder(mode="compare", query=query)
        .set_answer(answer)
        .set_sources(documents)
        .set_acts(acts or {})
        .add_metadata("documents_compared", documents_compared)
        .build()
    )





def create_empty_response(
    mode: str,
    query: str,
    empty_message: Optional[str] = None,
) -> Dict[str, Any]:
    """Factory for an empty response (no results).

    Si empty_message est None, un message par défaut adapté au mode est utilisé.
    Passer une string vide pour ne pas afficher de message.
    """
    if empty_message is None:
        if mode in ["rag", "hybrid"]:
            empty_message = (
                "Aucun document pertinent trouvé dans la base de données. "
                "La base peut être vide ou en cours de population par les workers. "
                "Vous pouvez utiliser le mode 'llm_only' pour une réponse basée sur les connaissances générales."
            )
        else:
            empty_message = "Aucun document pertinent trouvé."

    return (
        ResponseBuilder(mode=mode, query=query)
        .set_answer(empty_message)
        .set_sources([])
        .set_acts({})
        .add_metadata("database_empty", True)
        .build()
    )





def validate_response_format(response: Dict[str, Any] | RAGResponse) -> bool:
    """Validate that a response respects the unified format.

    With Pydantic models built via ResponseBuilder.build(), validation
    is already guaranteed at construction time.  This function remains
    for external callers that pass raw dicts.
    """
    if isinstance(response, RAGResponse):
        return True
    RAGResponse.model_validate(response)
    return True