# fitz_ai/core/answer.py
"""
Answer - Paradigm-agnostic answer representation.

An Answer encapsulates the response from a knowledge engine.
"""

from dataclasses import dataclass, field
from typing import TYPE_CHECKING, Any, Dict, List, Optional

from .provenance import Provenance

if TYPE_CHECKING:
    from fitz_ai.core.answer_mode import AnswerMode


@dataclass
class Answer:
    """
    Paradigm-agnostic answer representation.

    An answer contains:
    - text: The answer text
    - provenance: List of sources used to generate the answer
    - mode: Epistemic posture of the answer (CONFIDENT, QUALIFIED, DISPUTED, ABSTAIN)
    - metadata: Engine-specific metadata about how the answer was generated

    Examples:
        Simple answer:
        >>> answer = Answer(text="Quantum computing uses qubits...")

        Answer with sources:
        >>> provenance = [
        ...     Provenance(source_id="doc_1", excerpt="Qubits can be 0 and 1..."),
        ...     Provenance(source_id="doc_2", excerpt="Quantum entanglement...")
        ... ]
        >>> answer = Answer(
        ...     text="Quantum computing uses qubits which can exist in superposition...",
        ...     provenance=provenance
        ... )

        Answer with mode:
        >>> from fitz_ai.core.answer_mode import AnswerMode
        >>> answer = Answer(
        ...     text="Sources disagree on this classification...",
        ...     mode=AnswerMode.DISPUTED
        ... )

        Answer with engine metadata:
        >>> answer = Answer(
        ...     text="The answer is 42",
        ...     metadata={
        ...         "engine": "classic_rag",
        ...         "tokens_used": 1523,
        ...         "confidence": 0.95
        ...     }
        ... )
    """

    text: str
    """The answer text generated by the engine."""

    provenance: List[Provenance] = field(default_factory=list)
    """
    List of sources used to generate this answer.

    Provenance provides attribution and allows users to verify the answer
    against source material. Different engines may provide different levels
    of provenance:
    - Classic RAG: chunks retrieved from vector DB
    - CLaRa: documents consulted during reasoning
    - Future engines: whatever makes sense for their paradigm
    """

    mode: Optional["AnswerMode"] = None
    """
    Epistemic posture of the answer.

    Indicates how certain the answer should be interpreted:
    - CONFIDENT: Evidence clearly supports this answer
    - QUALIFIED: Answer has noted uncertainty or limitations
    - DISPUTED: Sources disagree; answer presents multiple perspectives
    - ABSTAIN: Insufficient evidence to answer definitively

    If None, no epistemic assessment was performed (e.g., engine doesn't
    support constraints, or constraints were disabled).
    """

    metadata: Dict[str, Any] = field(default_factory=dict)
    """
    Engine-specific metadata about answer generation.

    This can include:
    - Performance metrics (tokens used, latency)
    - Confidence scores
    - Model information
    - Reasoning traces
    - Debug information

    Consumers should be prepared for this to contain arbitrary data
    depending on the engine that generated the answer.
    """

    def __post_init__(self):
        """Validate answer after initialization."""
        if self.text is None:
            raise ValueError("Answer text cannot be None (use empty string for no answer)")
