CitedRAG

def build_graph() -> StateGraph[AgentState]:
    """构建 Supervisor 委派制多 Agent 协作图。

    返回未编译的 StateGraph，调用方可根据需要：
    - .compile() 获取 CompiledStateGraph
    - 注入 checkpointer（M3 多轮会话持久化用）
    - 设置 interrupt_before（调试用）

    Returns:
        已添加所有节点和边的 StateGraph builder
    """
    builder = StateGraph(AgentState)

    # 添加所有节点
    builder.add_node("supervisor", supervisor_node)
    builder.add_node("direct", direct_node)
    builder.add_node("planner", planner_node)
    builder.add_node("researcher", researcher_node)
    builder.add_node("writer", writer_node)

    # START → supervisor（入口）
    builder.add_edge(START, "supervisor")

    # 所有 worker 节点 → 条件边 → supervisor（继续）或 END（终止）
    # supervisor 通过 Command(goto=...) 动态路由到各 worker
    # path_map: should_continue 返回 Literal["supervisor","END"]，需显式映射到节点/哨兵
    for worker in ["direct", "planner", "researcher", "writer"]:
        builder.add_conditional_edges(
            worker,
            should_continue,
            path_map={"supervisor": "supervisor", "END": END},
        )

    return builder

def enforce_citations(
    answer: str, citations: list[dict[str, Any]]
) -> tuple[str, list[dict[str, Any]]]:
    """Reject invalid citations and keep only citations actually used by an answer.

    Marker parsing is evaluation-only code, so an unexpected validation failure must
    fail closed to the ordinary insufficient-evidence response rather than break an
    answer request.
    """
    try:
        parsed = parse_citation_markers(answer)
        if parsed.malformed:
            return INSUFFICIENT_EVIDENCE_ANSWER, []

        markers = parsed.markers
        if any(number > len(citations) for number in (marker.number for marker in markers)):
            return INSUFFICIENT_EVIDENCE_ANSWER, []
        if not markers:
            if answer.strip() == INSUFFICIENT_EVIDENCE_ANSWER:
                return answer, []
            return INSUFFICIENT_EVIDENCE_ANSWER, []

        # Repeated markers map to the same citation; numbering follows first
        # occurrence so the public contract remains contiguous and unambiguous.
        renumbering: dict[int, int] = {}
        normalized_parts: list[str] = []
        used_citations: list[dict[str, Any]] = []
        previous_end = 0
        for marker in markers:
            new_number = renumbering.get(marker.number)
            if new_number is None:
                new_number = len(used_citations) + 1
                renumbering[marker.number] = new_number
                used_citations.append(citations[marker.number - 1])
            normalized_parts.append(answer[previous_end:marker.start])
            normalized_parts.append(f"[{new_number}]")
            previous_end = marker.end
        normalized_parts.append(answer[previous_end:])
        return "".join(normalized_parts), used_citations
    except Exception:  # noqa: BLE001 - validation must fail closed in the request path.
        return INSUFFICIENT_EVIDENCE_ANSWER, []

def _flush(self, force: bool) -> None:
    prefix, remainder = _split_complete_sentences(self._buffer, force)
    self._buffer = remainder
    if not prefix.strip():
        return
    if any(
        marker.number > len(self._citations)
        for marker in parse_citation_markers(prefix).markers
    ):
        self._dropped += max(1, len(_claims_for_validation(prefix, True)))
        return
    verdicts = verify_cited_claims(
        prefix,
        self._chunks,
        self._llm_config,
        self._policy,
        include_uncited=True,
    )
    if verdicts is None:
        self._validation_failed = True
        return
    self._dropped += sum(1 for supported in verdicts.values() if not supported)
    supported = _drop_unsupported_claims(prefix, verdicts, include_uncited=True)
    if not supported.strip():
        return
    streamed = self._renumber(supported)
    self._stream_callback(streamed)
    self._streamed.append(streamed)