features/research/summary.py

"""토픽 인텔리전스 Feature 요약 카드."""
import streamlit as st


def render_summary(clusters: list, frame: str = "all"):
    """토픽 인텔리전스 요약 메트릭.

    Args:
        clusters: List of cluster dicts.
        frame: "demand" (ChatGPT), "supply" (Gemini), or "all".
    """
    scored = [c for c in clusters if c.get("opportunity_score") is not None]

    # Frame-specific labels
    if frame == "demand":
        count_label = "Demand 토픽"
        volume_label = "총 Fanout"
        volume_help = "ChatGPT가 사용자 질문을 분해한 세부 질문의 총 수"
        attn_help = "각 토픽이 전체 ChatGPT 질의에서 차지하는 비중의 평균"
        top_help = "ChatGPT에서 관심도는 높지만 경쟁이 낮아 콘텐츠 기회가 가장 큰 토픽"
    elif frame == "supply":
        count_label = "Supply 토픽"
        volume_label = "총 Citation"
        volume_help = "Gemini가 답변에서 인용한 문구의 총 수"
        attn_help = "각 토픽이 전체 Gemini 인용에서 차지하는 비중의 평균"
        top_help = "Gemini에서 인용 빈도는 높지만 경쟁이 낮아 콘텐츠 기회가 가장 큰 토픽"
    else:
        count_label = "총 클러스터"
        volume_label = "총 Fanout"
        volume_help = "AI가 사용자 질문을 조사하기 위해 생성한 세부 질문의 총 수"
        attn_help = "각 토픽이 전체 질의에서 차지하는 비중의 평균"
        top_help = "AI 관심도는 높지만 경쟁이 낮아 콘텐츠 기회가 가장 큰 토픽"

    col1, col2, col3, col4 = st.columns(4)
    with col1:
        st.metric(
            count_label, len(clusters),
            help="유사한 AI 질문/인용들을 묶은 토픽 그룹 수",
        )
    with col2:
        total_fanouts = sum(c.get("fanout_count", 0) for c in clusters)
        st.metric(volume_label, f"{total_fanouts:,}", help=volume_help)
    with col3:
        avg_attn = sum(float(c.get("attention_score", 0) or 0) for c in scored) / len(scored) if scored else 0
        st.metric("평균 Attention", f"{avg_attn:.4f}", help=attn_help)
    with col4:
        top_label = scored[0].get("cluster_label", "N/A") if scored else "N/A"
        st.metric("Top Opportunity", top_label[:20], help=top_help)