"""RAGState — internal state of the rag_query_subgraph (used by the chat search_documents tool).

Cleanly isolated from the parent ChatState because the RAG retrieval is a
self-contained subsystem. The subgraph can be invoked via its own compile
(which makes the LangSmith trace cleaner).
"""

from __future__ import annotations

from typing import TypedDict


class RAGState(TypedDict, total=False):
    """The rag_query_subgraph state."""

    query: str
    """The user's question (or a search phrase generated by the chat agent)."""

    top_k: int
    """Maximum number of returned hits. Default: 5."""

    raw_hits: list[dict]
    """Raw output of hybrid_search (vector + BM25 RRF combined)."""

    reranked_hits: list[dict]
    """Output of the rerank node (in the baseline this is the same as raw_hits)."""

    output: str
    """Output of the format node: human-readable, with [Source: X] citations."""