fix: cross-source reranker → RetrievalResult.excerpts (UI 정렬 일치)

- pipeline.build_context: ranker.rank 후 cross-source rerank 적용
- context_builder: rerank 호출 분리, build()는 슬라이스만 (NameError 버그 동시 수정)
- ui/gradio + server: 3-tier 정렬 제거 → reranker 적합도 순으로 카드 표시
- server: constitutional/oldnew/article_history 라벨·배경색 누락 보강

src/kpaa/pipeline.py

@@ -78,10 +78,14 @@ async def build_context(
         )
     raw = await retrieve(plan, client=client, on_progress=on_progress)
     ranked = ranker.rank(raw)
-    block = context_builder.build(ranked, query=plan.query)
+    # Cross-source reranker 를 *전체 excerpts* 에 적용해 source 무관 적합도 순으로
+    # 재정렬. RetrievalResult.excerpts 가 이 순서를 그대로 가져 LLM 컨텍스트
+    # ([근거1]..[근거N]) 와 UI references 패널 모두 reranker 신호로 정렬됨.
+    reranked = context_builder.cross_source_rerank(plan.query, ranked, top_k=None)
+    block = context_builder.build(reranked, query=plan.query)
     return RetrievalResult(
         plan=plan,
-        excerpts=ranked,
+        excerpts=reranked,
         context_block=block,
         elapsed_ms=int((time.monotonic() - t0) * 1000),
     )

src/kpaa/retrieval/context_builder.py

@@ -5,20 +5,15 @@
 
 토큰 예산은 글자수로 근사 (한국어 1글자 ≈ 1.5~2 토큰).
 
-KPAA v2.4 — *답변 LLM 속도* 가 prefill 토큰 수에 선형 비례 (CPU 50-100 tok/s)
-라서 RAG context 압축이 곧 응답 시간 단축. 정책:
-
-    - max_excerpts=7: ranker 정렬 상위 7건을 LLM 에 전달. LLM 은 그중 가장
-                      적합한 3건을 골라 명시 인용 (system prompt 분량 강제).
-                      7→3 큐레이션 — 5건 cap 에서 빠져나간 좋은 후보까지 LLM
-                      판단 풀에 들어오면서, 8건 대비 prefill 토큰은 절감.
-                      나머지 excerpts 는 *retrieval result 자체* 에는 살아있어
-                      Gradio references 패널엔 전체 노출, LLM 입력만 cap.
-    - **다양화 픽 (round-robin by source_type)**: 단순 상위 N 자르기는 ranker
-                      priority 가 같은 type (예: 법조문 3건 연속) 이 7건을 독점
-                      가능 → 7건이어도 다양성 부족. 그래서 build() 가
-                      source_type 별 큐를 만들어 라운드로빈으로 N개 채움. 같은
-                      타입 안에선 ranker 순서 유지.
+KPAA v2.5 — cross-source reranker 는 pipeline 단계에서 *전체 excerpts* 에
+적용되어 `RetrievalResult.excerpts` 자체가 reranker 적합도 순. build() 는
+단순히 상위 N건을 슬라이스해 LLM 컨텍스트로 만든다 (재정렬·라운드로빈 ✗).
+UI references 패널도 `RetrievalResult.excerpts` 그대로 표시 → 답변·UI 양쪽
+모두 reranker 신호 우선.
+
+    - max_excerpts=7: 상위 7건을 LLM 에 전달. 7→3 큐레이션 — 5건 cap 에서
+                      빠져나간 좋은 후보까지 LLM 판단 풀에 들어오면서, 8건 대비
+                      prefill 토큰은 절감.
     - DEFAULT_MAX_CHARS=8_000: 7건 × 평균 1000자 ≈ 7K자 (≈ 3,500 토큰).
                       excerpt 가 길면 cap 에 닿아 마지막 항목 절단.
 """
@@ -98,23 +93,29 @@ def _rerank_text(e: Excerpt) -> str:
     return f"{title}\n{body}" if title else body
 
 
-def _cross_source_rerank(query: str, excerpts: list[Excerpt], *, k: int) -> list[Excerpt]:
-    """Cross-encoder reranker 로 source 무관 적합도 순 top-k 선정.
+def cross_source_rerank(
+    query: str, excerpts: list[Excerpt], *, top_k: int | None = None
+) -> list[Excerpt]:
+    """Cross-encoder reranker 로 source 무관 적합도 순 정렬.
+
+    `top_k=None` (기본): 전체를 reranker 점수 순으로 *재정렬*만 (cap ✗).
+    `top_k=N`: 상위 N건만.
+
+    Reranker 미설치/disabled 또는 query 없으면 입력 순서 그대로 (이때는
+    ranker.rank 의 sort_priority 순).
 
     이전 버전(2026-05-05까지)에는 `_diversified_pick` 라운드로빈으로 source_type
     다양성을 강제했으나, cross-encoder 도입 후엔 source 무관 적합도가 가장 신뢰할
     만한 신호 — 정답이 한 source 에 집중돼 있어도 reranker 가 옳게 골라내고,
     실제로 다양한 source 가 적합하면 자연스럽게 섞임.
-
-    Reranker 미설치/disabled 또는 query 없으면 입력 순서 그대로 슬라이스 (이때는
-    ranker.rank 의 sort_priority 순).
     """
-    if not excerpts or k <= 0:
-        return excerpts[:k]
-    if len(excerpts) <= k:
-        return list(excerpts)
+    if not excerpts:
+        return []
+    k = top_k if top_k is not None else len(excerpts)
+    if k <= 0:
+        return []
     if not query:
-        return excerpts[:k]
+        return list(excerpts[:k])
     try:
         from kpaa.retrieval.reranker import Reranker
 
@@ -122,35 +123,40 @@ def _cross_source_rerank(query: str, excerpts: list[Excerpt], *, k: int) -> list
     except Exception:  # noqa: BLE001
         rr = None
     if rr is None:
-        return excerpts[:k]
-    return rr.rerank(query, excerpts, text_fn=_rerank_text, top_k=k)
+        return list(excerpts[:k])
+    # Reranker.rerank 는 len<=top_k 일 때 short-circuit 으로 입력 순서를 반환하므로,
+    # *전체 재정렬* 이 필요한 본 함수에선 직접 score+sort.
+    try:
+        pairs = [(query, _rerank_text(e)) for e in excerpts]
+        scores = rr.model.predict(pairs, show_progress_bar=False)
+        ranked = sorted(zip(excerpts, scores), key=lambda x: -float(x[1]))
+        return [e for e, _ in ranked[:k]]
+    except Exception:  # noqa: BLE001
+        return list(excerpts[:k])
 
 
 def build(
     excerpts: list[Excerpt],
     *,
-    query: str | None = None,
+    query: str | None = None,  # noqa: ARG001 — 호환용. rerank 는 pipeline 단계로 이동됨.
     max_chars: int = DEFAULT_MAX_CHARS,
     max_excerpts: int | None = DEFAULT_MAX_EXCERPTS,
 ) -> str:
     """`[근거1] ... [근거2] ...` 형태의 단일 문자열 반환.
 
     Args:
-        excerpts: ranker 정렬 후의 후보 리스트 (source 간 dedup·우선순위 적용됨).
-        query: 사용자 원본 질문. cross-source reranker 입력. 없으면 입력 순서 슬라이스.
+        excerpts: pipeline 에서 cross-source reranker 적용 후의 리스트 (적합도 순).
+        query: (deprecated) 호환 위해 남김. 실제 rerank 는 pipeline.build_context 가 수행.
         max_chars: 최종 블록 글자 수 cap. 초과 시 마지막 항목 절단.
         max_excerpts: LLM 에 전달할 상위 N건 cap. None 이면 무제한 (전체 사용).
                       기본 7 — 답변 LLM prefill 토큰을 줄여 응답 속도 ↑.
-                      cap 적용 시 cross-encoder 가 source 무관 적합도 순으로 top-N
-                      을 골라냄. 라운드로빈 다양화 X (reranker 신호 우선).
-                      retrieval result 의 `excerpts` 자체는 안 건드리므로 UI
-                      references 패널엔 전체가 그대로 노출됨.
+                      입력이 이미 reranker 적합도 순이므로 단순 슬라이스.
     """
     if not excerpts:
         return "(검색된 근거가 없습니다.)"
 
     if max_excerpts is not None:
-        excerpts = _cross_source_rerank(query or "", excerpts, k=max_excerpts)
+        excerpts = excerpts[:max_excerpts]
 
     blocks: list[str] = []
     used = 0
@@ -176,4 +182,4 @@ def build(
     return "\n\n".join(blocks)
 
 
-__all__ = ["build", "DEFAULT_MAX_CHARS", "DEFAULT_MAX_EXCERPTS"]
+__all__ = ["build", "cross_source_rerank", "DEFAULT_MAX_CHARS", "DEFAULT_MAX_EXCERPTS"]

src/kpaa/server.py

@@ -556,6 +556,19 @@ def create_app() -> FastAPI:
     @app.get("/", response_class=HTMLResponse)
     async def index() -> str:
         # 루트 = Open WebUI + 참고자료 분할 화면. 백엔드 정보 페이지는 /info.
+        # 페이지 진입(리로드 포함) 시 우측 참고자료 서버 상태를 비움 — 이전 세션
+        # 잔여 _last_refs 가 폴링에 의해 즉시 렌더되는 것을 방지. HF 백엔드의
+        # _split_handler 와 동일 정책.
+        _last_refs.update({
+            "ts": time.time(),
+            "query": "",
+            "intents": [],
+            "jo_targets": [],
+            "elapsed_ms": 0,
+            "excerpts": [],
+            "llm_excerpt_citations": [],
+            "geungeo_indices_in_answer": [],
+        })
         return _SPLIT_HTML
 
     @app.get("/info", response_class=HTMLResponse)
@@ -819,6 +832,9 @@ _SPLIT_HTML = """<!doctype html>
     --interp-bg: #6633bb;
     --prec-bg: #b03060;
     --admin-bg: #555555;
+    --const-bg: #8b1e3f;       /* 헌재 — 짙은 와인색 */
+    --oldnew-bg: #4a5568;      /* 구·신 비교 — 슬레이트 그레이 */
+    --history-bg: #6b4c00;     /* 조문 변천 — 다크 골드 */
   }
   /* ─ 다크 변수 (OS 자동 — 토글 없음). 컴포넌트 룰은 CSS 끝의 별도 @media 참고. */
   @media (prefers-color-scheme: dark) {
@@ -842,6 +858,9 @@ _SPLIT_HTML = """<!doctype html>
       --interp-bg: #8b5cf6;
       --prec-bg: #db2777;
       --admin-bg: #6b7280;
+      --const-bg: #c2456a;
+      --oldnew-bg: #94a3b8;
+      --history-bg: #d4a017;
     }
   }
 
@@ -879,6 +898,9 @@ _SPLIT_HTML = """<!doctype html>
   .badge.interpretation { background: var(--interp-bg); }
   .badge.precedent { background: var(--prec-bg); }
   .badge.admin_rule { background: var(--admin-bg); }
+  .badge.constitutional { background: var(--const-bg); }
+  .badge.oldnew { background: var(--oldnew-bg); }
+  .badge.article_history { background: var(--history-bg); }
   .ref .citation { font-weight: 600; font-size: 0.9em; color: var(--text); }
   .ref .title { color: var(--muted); font-size: 0.86em; margin-bottom: 6px; }
   .ref .content { font-size: 0.84em; line-height: 1.55; color: var(--text); background: var(--content-bg); padding: 8px 10px; border-radius: 6px; white-space: pre-wrap; max-height: 240px; overflow-y: auto; border: 1px solid var(--border-soft); }
@@ -924,7 +946,7 @@ _SPLIT_HTML = """<!doctype html>
 // 테마는 OS prefers-color-scheme 자동 — 별도 토글 없음.
 
 // ─ references polling ─
-const LABEL = { case: "상담사례", guide: "안내서", law: "법조문", related_law: "관련 법령", pipc: "PIPC 결정", interpretation: "법령해석례", precedent: "판례", admin_rule: "행정규칙" };
+const LABEL = { case: "상담사례", guide: "안내서", law: "법조문", related_law: "관련 법령", pipc: "PIPC 결정", interpretation: "법령해석례", precedent: "판례", admin_rule: "행정규칙", constitutional: "헌법재판소", oldnew: "구·신 비교", article_history: "조문 변천" };
 const refsEl = document.getElementById("refs");
 const refsCountEl = document.getElementById("refs-count");
 const metaEl = document.getElementById("meta");
@@ -939,19 +961,9 @@ function render(payload) {
   const geungeoSet = new Set(payload.geungeo_indices_in_answer || []);  // 답변 본문 (근거N) 의 N
   const llmCount = rawExcerpts.filter(e => llmSet.has((e.citation || "").trim())).length;
 
-  // 카드별 *원본 LLM 입력 순서* (1-based) 보존 — 정렬 후에도 유지되도록 미리 부여.
-  // 이 순서가 답변 본문의 (근거N) 의 N 과 일치 (context_builder 가 같은 순서로 [근거N] 박음).
-  const indexed = rawExcerpts.map((e, i) => ({ ...e, _idx: i + 1 }));
-
-  // 3-tier 정렬: LLM 명시 인용(근거N)(0) → LLM 전달(1) → 검색만(2). stable.
-  // (근거N) chip 카드를 위로 올려 사용자가 명시 인용된 카드 빨리 찾을 수 있게.
-  const tier = (e) => {
-    const passed = llmSet.has((e.citation || "").trim());
-    if (passed && geungeoSet.has(e._idx)) return 0;
-    if (passed) return 1;
-    return 2;
-  };
-  const excerpts = [...indexed].sort((a, b) => tier(a) - tier(b));
+  // pipeline 의 cross-source reranker 가 매긴 적합도 순 그대로 표시.
+  // 1-based 인덱스가 답변 본문 (근거N) 의 N 과 일치 (context_builder 가 같은 순서로 [근거N] 박음).
+  const excerpts = rawExcerpts.map((e, i) => ({ ...e, _idx: i + 1 }));
 
   // 헤더 — "8건 · LLM 전달 7건"
   if (rawExcerpts.length) {
@@ -1133,7 +1145,7 @@ _CHAT_HTML = """<!doctype html>
   </section>
 </div>
 <script>
-const LABEL = { case: "상담사례", guide: "안내서", law: "법조문", related_law: "관련 법령", pipc: "PIPC 결정", interpretation: "법령해석례", precedent: "판례", admin_rule: "행정규칙" };
+const LABEL = { case: "상담사례", guide: "안내서", law: "법조문", related_law: "관련 법령", pipc: "PIPC 결정", interpretation: "법령해석례", precedent: "판례", admin_rule: "행정규칙", constitutional: "헌법재판소", oldnew: "구·신 비교", article_history: "조문 변천" };
 const messagesEl = document.getElementById("messages");
 const refsEl = document.getElementById("refs");
 const refsCountEl = document.getElementById("refs-count");

src/kpaa/ui/gradio.py

@@ -60,6 +60,9 @@ _BADGE_COLOR = {
     "interpretation": "#6633bb",
     "precedent": "#b03060",
     "admin_rule": "#555",
+    "constitutional": "#8b1e3f",
+    "oldnew": "#4a5568",
+    "article_history": "#6b4c00",
 }
 
 _EXAMPLE_QUESTIONS = [
@@ -79,16 +82,15 @@ def _render_references_html(
 ) -> str:
     """우측 패널 HTML 카드 묶음 — server.py 분할 화면과 동일 정책.
 
-    표시 단계 (2-tier):
-      - LLM 전달 (llm_passed_citations): 좌측 회색 표지 + 회색 "LLM 전달" 배지.
-        그 N건 *전부* 가 LLM 이 본 후보 (의미 매칭 추적은 안 함).
-      - 검색만: 표시 없음.
-    + 답변 본문에 (근거N) 으로 *명시* 등장한 카드는 추가로 "근거N" outline chip.
-      (LLM 이 명시적으로 라벨링한 신호이고, 명시 안 된 청크도 답변에 영향 줬을 수
-      있으므로 별도 "채택" 강조 색상은 두지 않음.)
+    카드 순서: pipeline 의 cross-source reranker 가 매긴 적합도 순 (=
+    `excerpts` 입력 순서) 그대로. UI 단계에서 별도 정렬 ✗.
+
+    배지:
+      - "LLM 전달" (llm_passed_citations 매칭): 회색 좌측 표지 + 회색 배지.
+      - "근거N" (geungeo_indices 매칭): 답변 본문에 (근거N) 으로 명시 등장한 카드.
 
     Args:
-        excerpts: 검색된 전체 (ranker 정렬 순서). 1-based 위치 = (근거N) N.
+        excerpts: pipeline reranker 적합도 순. 1-based 위치 = (근거N) N.
         elapsed_ms: 검색 시간.
         llm_passed_citations: LLM 입력으로 전달된 상위 N건 citation set.
         geungeo_indices: 답변에 (근거N) 으로 등장한 N 들 (1-based).
@@ -104,20 +106,8 @@ def _render_references_html(
 
     llm_count = sum(1 for e in excerpts if (e.citation or "").strip() in llm_set)
 
-    # 카드별 원본 LLM 입력 순서(1-based) 보존 — 정렬 후에도 (근거N) 매핑 유지.
-    indexed: list[tuple[int, Excerpt]] = list(enumerate(excerpts, 1))
-
-    # 3-tier 정렬 (stable): LLM 명시 인용(근거N) → LLM 전달 → 나머지.
-    def _tier(item: tuple[int, Excerpt]) -> int:
-        idx, e = item
-        passed = (e.citation or "").strip() in llm_set
-        if passed and idx in geungeo_set:
-            return 0
-        if passed:
-            return 1
-        return 2
-
-    sorted_items = sorted(indexed, key=_tier)
+    # reranker 가 매긴 순서를 그대로 표시. 1-based 인덱스가 (근거N) 의 N 과 일치.
+    indexed_items: list[tuple[int, Excerpt]] = list(enumerate(excerpts, 1))
 
     # 헤더 요약
     summary_parts = [f"총 {len(excerpts)}건 · 검색 {elapsed_ms}ms"]
@@ -130,7 +120,7 @@ def _render_references_html(
         f'<div style="padding:8px 12px;color:#888;font-size:0.82em;">{summary}</div>'
     ]
 
-    for idx, e in sorted_items:
+    for idx, e in indexed_items:
         label = _SOURCE_LABEL.get(e.source_type, e.source_type)
         color = _BADGE_COLOR.get(e.source_type, "#666")
         url = (e.metadata or {}).get("url", "").strip()