Update fetcher.py

fetcher.py

@@ -1,206 +1,551 @@
 """
-fetcher.py — YouTube Data API v3 helpers
+charts.py — All Plotly chart builders. Pure functions, no Streamlit imports.
 """
 
-import re
-import requests
+from typing import Dict, List, Tuple, Optional
+import plotly.graph_objects as go
+import plotly.express as px
 import pandas as pd
-
-
-
-#  Video ID extraction
-
-
-def extract_video_id(url_or_id: str) -> str | None:
-    """Return an 11-char YouTube video ID, or None if not found."""
-    patterns = [
-        r"(?:youtube\.com/watch\?v=|youtu\.be/|youtube\.com/embed/|youtube\.com/shorts/)([a-zA-Z0-9_-]{11})",
-        r"^([a-zA-Z0-9_-]{11})$",
+import numpy as np
+
+#  Shared theme ─
+DARK_BG     = "#0d0f14"
+CARD_BG     = "#13161e"
+BORDER      = "#1e2330"
+TEXT_MAIN   = "#e8eaf0"
+TEXT_DIM    = "#5a6070"
+CYAN        = "#00d4ff"
+GREEN       = "#00e5a0"
+RED         = "#ff4757"
+AMBER       = "#ffb347"
+PURPLE      = "#b388ff"
+BLUE        = "#4a8eff"
+
+PLOTLY_LAYOUT = dict(
+    paper_bgcolor="rgba(0,0,0,0)",
+    plot_bgcolor="rgba(0,0,0,0)",
+    font=dict(family="'DM Mono', monospace", color=TEXT_MAIN, size=12),
+    margin=dict(l=20, r=20, t=40, b=20),
+)
+
+
+#  Misinformation Gauge 
+
+def misinfo_gauge(score: float, label: str) -> go.Figure:
+    """Gauge chart for misinformation confidence score (0–1)."""
+    pct = score * 100
+    if score < 0.35:
+        bar_color = GREEN
+    elif score < 0.65:
+        bar_color = AMBER
+    else:
+        bar_color = RED
+
+    fig = go.Figure(go.Indicator(
+        mode="gauge+number+delta",
+        value=pct,
+        number={"suffix": "%", "font": {"size": 32, "color": bar_color, "family": "'DM Mono', monospace"}},
+        delta={"reference": 50, "increasing": {"color": RED}, "decreasing": {"color": GREEN}},
+        title={"text": label, "font": {"size": 13, "color": TEXT_DIM}},
+        gauge={
+            "axis": {
+                "range": [0, 100],
+                "tickwidth": 1,
+                "tickcolor": BORDER,
+                "tickfont": {"color": TEXT_DIM, "size": 10},
+            },
+            "bar": {"color": bar_color, "thickness": 0.3},
+            "bgcolor": CARD_BG,
+            "borderwidth": 0,
+            "steps": [
+                {"range": [0, 35],  "color": "#0d1f18"},
+                {"range": [35, 65], "color": "#1f1a0d"},
+                {"range": [65, 100],"color": "#1f0d0d"},
+            ],
+            "threshold": {
+                "line": {"color": TEXT_MAIN, "width": 2},
+                "thickness": 0.75,
+                "value": pct,
+            },
+        },
+    ))
+    fig.update_layout(**PLOTLY_LAYOUT, height=260)
+    return fig
+
+
+#  Sentiment Donut ─
+
+def sentiment_donut(summary: Dict) -> go.Figure:
+    """Donut chart: Positive / Negative / Neutral breakdown."""
+    labels  = ["Positive", "Neutral", "Negative"]
+    values  = [summary["POSITIVE"], summary["NEUTRAL"], summary["NEGATIVE"]]
+    colors  = [GREEN, TEXT_DIM, RED]
+
+    fig = go.Figure(go.Pie(
+        labels=labels,
+        values=values,
+        hole=0.62,
+        marker=dict(colors=colors, line=dict(color=DARK_BG, width=3)),
+        textinfo="label+percent",
+        textfont=dict(family="'DM Mono', monospace", size=11, color=TEXT_MAIN),
+        hovertemplate="<b>%{label}</b><br>%{value} comments (%{percent})<extra></extra>",
+        rotation=90,
+    ))
+
+    # Centre annotation
+    avg = summary.get("avg_compound", 0)
+    overall = "😊 Positive" if avg > 0.05 else ("😟 Negative" if avg < -0.05 else "😐 Mixed")
+    fig.add_annotation(
+        text=f"<b>{overall}</b><br><span style='font-size:11px;color:{TEXT_DIM}'>{summary['total']} comments</span>",
+        x=0.5, y=0.5,
+        showarrow=False,
+        font=dict(size=13, color=TEXT_MAIN, family="'DM Mono', monospace"),
+        align="center",
+    )
+    fig.update_layout(**PLOTLY_LAYOUT, height=300,
+                      legend=dict(orientation="h", y=-0.08, font=dict(size=11)))
+    return fig
+
+
+#  Keyword Bar Chart ─
+
+def keyword_bar(
+    keywords: List[Tuple[str, float]],
+    title: str = "Top Keywords",
+    color: str = CYAN,
+) -> go.Figure:
+    if not keywords:
+        return _empty_fig(title)
+
+    words, weights = zip(*keywords[:15])
+    # Normalize to 0-100
+    max_w = max(weights) or 1
+    norm = [w / max_w * 100 for w in weights]
+
+    fig = go.Figure(go.Bar(
+        x=norm,
+        y=words,
+        orientation="h",
+        marker=dict(
+            color=norm,
+            colorscale=[[0, f"{color}33"], [1, color]],
+            line=dict(width=0),
+        ),
+        text=[f"{w:.0f}" for w in weights],
+        textposition="inside",
+        textfont=dict(size=10, color=DARK_BG),
+        hovertemplate="<b>%{y}</b><br>Weight: %{text}<extra></extra>",
+    ))
+    fig.update_layout(
+        **PLOTLY_LAYOUT,
+        title=dict(text=title, font=dict(size=13, color=TEXT_DIM), x=0),
+        height=380,
+        yaxis=dict(autorange="reversed", tickfont=dict(size=11), gridcolor=BORDER),
+        xaxis=dict(showticklabels=False, gridcolor=BORDER),
+        bargap=0.35,
+    )
+    return fig
+
+
+#  Stream Trust Bars ─
+
+def stream_trust_bars(stream_details: Dict) -> go.Figure:
+    """Horizontal bar chart for per-stream misinfo scores."""
+    labels = list(stream_details.keys())
+    values = [round(v * 100, 1) for v in stream_details.values()]
+    colors = [RED if v > 50 else (AMBER if v > 30 else GREEN) for v in values]
+
+    fig = go.Figure(go.Bar(
+        x=values,
+        y=[l.replace("_", " ").title() for l in labels],
+        orientation="h",
+        marker=dict(color=colors, line=dict(width=0)),
+        text=[f"{v}%" for v in values],
+        textposition="outside",
+        textfont=dict(size=11, color=TEXT_MAIN),
+        hovertemplate="<b>%{y}</b><br>Score: %{x}%<extra></extra>",
+    ))
+    fig.update_layout(
+        **PLOTLY_LAYOUT,
+        title=dict(text="Per-Stream Analysis", font=dict(size=13, color=TEXT_DIM), x=0),
+        height=220,
+        xaxis=dict(range=[0, 110], showticklabels=False, gridcolor=BORDER),
+        yaxis=dict(tickfont=dict(size=11)),
+        bargap=0.4,
+    )
+    return fig
+
+
+#  Modality Misinformation Distribution ─
+
+def modality_misinfo_distribution(modality_analysis: Dict) -> go.Figure:
+    """
+    Grouped bar chart — Misinformation Score vs Not-Misinformation Score per modality.
+
+    Bars are derived directly from the model's per-stream softmax probabilities
+    (values in ``modality_analysis[modality]["misinfo_pct"]`` /
+    ``modality_analysis[modality]["credible_pct"]``).
+    Each pair of bars sums to exactly 100 % because they are complementary
+    softmax outputs from the same binary classification head.
+
+    Parameters
+    ----------
+    modality_analysis : dict
+        Mapping  {"text": {...}, "audio": {...}, "video": {...}}  as returned by
+        ``analyzer._compute_modality_analysis()`` — one sub-dict per stream.
+    """
+    MODALITIES = ["Text", "Audio", "Video"]
+    KEYS       = ["text", "audio", "video"]
+
+    misinfo_pcts  = [modality_analysis.get(k, {}).get("misinfo_pct",  50.0) for k in KEYS]
+    credible_pcts = [modality_analysis.get(k, {}).get("credible_pct", 50.0) for k in KEYS]
+    logit_tips    = [
+        (f"logit_m={modality_analysis.get(k, {}).get('misinfo_logit', 0.0):+.4f} | "
+         f"logit_c={modality_analysis.get(k, {}).get('credible_logit', 0.0):+.4f}")
+        for k in KEYS
     ]
-    for pattern in patterns:
-        m = re.search(pattern, url_or_id)
-        if m:
-            return m.group(1)
-    return None
-
-
-
-#  Duration parser
-
-
-def _parse_duration(iso: str) -> str:
-    m = re.match(r"PT(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?", iso or "PT0S")
-    if not m:
-        return "0:00"
-    h, mn, s = (int(x or 0) for x in m.groups())
-    return f"{h}:{mn:02d}:{s:02d}" if h else f"{mn}:{s:02d}"
-
 
+    fig = go.Figure()
+
+    fig.add_trace(go.Bar(
+        name="Misinformation Score",
+        x=MODALITIES,
+        y=misinfo_pcts,
+        marker=dict(
+            color=[RED, RED, RED],
+            opacity=0.88,
+            line=dict(color=DARK_BG, width=1),
+        ),
+        text=[f"{v:.1f}%" for v in misinfo_pcts],
+        textposition="outside",
+        textfont=dict(size=11, color=RED),
+        customdata=logit_tips,
+        hovertemplate=(
+            "<b>%{x} — Misinformation</b><br>"
+            "Softmax: %{y:.2f}%<br>"
+            "%{customdata}<extra></extra>"
+        ),
+    ))
+
+    fig.add_trace(go.Bar(
+        name="Not Misinformation",
+        x=MODALITIES,
+        y=credible_pcts,
+        marker=dict(
+            color=[GREEN, GREEN, GREEN],
+            opacity=0.88,
+            line=dict(color=DARK_BG, width=1),
+        ),
+        text=[f"{v:.1f}%" for v in credible_pcts],
+        textposition="outside",
+        textfont=dict(size=11, color=GREEN),
+        customdata=logit_tips,
+        hovertemplate=(
+            "<b>%{x} — Credible</b><br>"
+            "Softmax: %{y:.2f}%<br>"
+            "%{customdata}<extra></extra>"
+        ),
+    ))
+
+    fig.update_layout(
+        **PLOTLY_LAYOUT,
+        title=dict(
+            text="Modality Misinformation Distribution",
+            font=dict(size=13, color=TEXT_DIM),
+            x=0,
+        ),
+        barmode="group",
+        height=280,
+        xaxis=dict(
+            title="Modality",
+            tickfont=dict(size=12),
+            gridcolor=BORDER,
+        ),
+        yaxis=dict(
+            title="Softmax Score (%)",
+            range=[0, 115],
+            gridcolor=BORDER,
+            ticksuffix="%",
+        ),
+        legend=dict(
+            orientation="h",
+            y=1.12,
+            font=dict(size=11),
+            bgcolor="rgba(0,0,0,0)",
+        ),
+        bargap=0.22,
+        bargroupgap=0.06,
+    )
+    return fig
+
+
+#  Trust Score by Modality ─
+
+def trust_score_by_modality(modality_analysis: Dict) -> go.Figure:
+    """
+    Vertical bar chart — model's reliability/trustworthiness coefficient per stream.
+
+    Trust is computed as a linear combination of model confidence (1 ��� Shannon entropy)
+    and content-richness, both derived from the actual inference pass, never fixed.
+
+    Parameters
+    ----------
+    modality_analysis : dict
+        Same structure as ``modality_misinfo_distribution``.
+    """
+    MODALITIES = ["Text", "Audio", "Video"]
+    KEYS       = ["text", "audio", "video"]
+
+    trust_vals = [modality_analysis.get(k, {}).get("trust_score", 0.0) for k in KEYS]
+    bar_colors = [
+        (GREEN if v >= 60 else (AMBER if v >= 35 else RED))
+        for v in trust_vals
+    ]
 
-#  Metadata
+    fig = go.Figure(go.Bar(
+        x=MODALITIES,
+        y=trust_vals,
+        marker=dict(
+            color=bar_colors,
+            opacity=0.88,
+            line=dict(color=DARK_BG, width=1),
+        ),
+        text=[f"{v:.1f}%" for v in trust_vals],
+        textposition="outside",
+        textfont=dict(size=11, color=TEXT_MAIN),
+        hovertemplate=(
+            "<b>%{x}</b><br>"
+            "Trust Level: %{y:.2f}%<br>"
+            "<i>Derived from (1 – H_entropy) × content_richness</i>"
+            "<extra></extra>"
+        ),
+    ))
+
+    # Reference lines
+    for level, label, color in [(80, "High Trust", GREEN), (50, "Threshold", AMBER)]:
+        fig.add_hline(
+            y=level,
+            line=dict(color=color, width=1, dash="dot"),
+            annotation_text=label,
+            annotation_position="right",
+            annotation_font=dict(size=9, color=color),
+        )
 
+    fig.update_layout(
+        **PLOTLY_LAYOUT,
+        title=dict(
+            text="Trust Score by Modality",
+            font=dict(size=13, color=TEXT_DIM),
+            x=0,
+        ),
+        height=280,
+        xaxis=dict(
+            title="Modality",
+            tickfont=dict(size=12),
+            gridcolor=BORDER,
+        ),
+        yaxis=dict(
+            title="Trust Level (%)",
+            range=[0, 115],
+            gridcolor=BORDER,
+            ticksuffix="%",
+        ),
+        bargap=0.38,
+    )
+    return fig
+
+
+#  Uncertainty Analysis 
+
+def uncertainty_analysis(modality_analysis: Dict) -> go.Figure:
+    """
+    Vertical bar chart — Shannon entropy of the model's softmax distribution per stream.
+
+    High entropy ( → 100 %) means the model is maximally unsure (uniform distribution).
+    Low entropy ( → 0 %) means the model is highly confident in its prediction.
+    Values come directly from H = –Σ p·log₂(p) over the two softmax outputs.
+
+    Parameters
+    ----------
+    modality_analysis : dict
+        Same structure as ``modality_misinfo_distribution``.
+    """
+    MODALITIES = ["Text", "Audio", "Video"]
+    KEYS       = ["text", "audio", "video"]
+
+    uncertainty_vals = [modality_analysis.get(k, {}).get("uncertainty", 100.0) for k in KEYS]
+    misinfo_pcts     = [modality_analysis.get(k, {}).get("misinfo_pct", 50.0)  for k in KEYS]
+
+    # Colour encodes confidence direction: red = uncertain, green = confident
+    bar_colors = [
+        (GREEN if v <= 35 else (AMBER if v <= 65 else RED))
+        for v in uncertainty_vals
+    ]
 
-def fetch_video_metadata(video_id: str, api_key: str) -> tuple[dict | None, str | None]:
-    """Return (meta_dict, error_string).  One will be None."""
-    try:
-        resp = requests.get(
-            "https://www.googleapis.com/youtube/v3/videos",
-            params={
-                "id": video_id,
-                "key": api_key,
-                "part": "snippet,statistics,contentDetails",
-            },
-            timeout=15,
-        )
-        data = resp.json()
-        if "error" in data:
-            return None, data["error"].get("message", "YouTube API error")
-
-        items = data.get("items", [])
-        if not items:
-            return None, "Video not found — check the ID or URL."
-
-        item = items[0]
-        sn = item.get("snippet", {})
-        st = item.get("statistics", {})
-        cd = item.get("contentDetails", {})
-
-        meta = {
-            "title":         sn.get("title", "Unknown"),
-            "description":   sn.get("description", ""),
-            "channel_title": sn.get("channelTitle", "Unknown"),
-            "published_at":  sn.get("publishedAt", "")[:10],
-            "tags":          sn.get("tags", []),
-            "thumbnail_url": (
-                sn.get("thumbnails", {}).get("high", {}).get("url", "")
-                or sn.get("thumbnails", {}).get("medium", {}).get("url", "")
+    fig = go.Figure(go.Bar(
+        x=MODALITIES,
+        y=uncertainty_vals,
+        marker=dict(
+            color=bar_colors,
+            opacity=0.88,
+            line=dict(color=DARK_BG, width=1),
+        ),
+        text=[f"{v:.1f}%" for v in uncertainty_vals],
+        textposition="outside",
+        textfont=dict(size=11, color=TEXT_MAIN),
+        customdata=[[f"p_misinfo={m:.1f}%"] for m in misinfo_pcts],
+        hovertemplate=(
+            "<b>%{x}</b><br>"
+            "Uncertainty (H): %{y:.2f}%<br>"
+            "%{customdata[0]}<br>"
+            "<i>H = –Σ p·log₂(p), normalised to %</i>"
+            "<extra></extra>"
+        ),
+    ))
+
+    # Max-entropy reference
+    fig.add_hline(
+        y=100,
+        line=dict(color=RED, width=1, dash="dot"),
+        annotation_text="Max Entropy (no signal)",
+        annotation_position="right",
+        annotation_font=dict(size=9, color=RED),
+    )
+    fig.add_hline(
+        y=50,
+        line=dict(color=AMBER, width=1, dash="dot"),
+        annotation_text="Mid Uncertainty",
+        annotation_position="right",
+        annotation_font=dict(size=9, color=AMBER),
+    )
+
+    fig.update_layout(
+        **PLOTLY_LAYOUT,
+        title=dict(
+            text="Uncertainty Analysis (Shannon Entropy)",
+            font=dict(size=13, color=TEXT_DIM),
+            x=0,
+        ),
+        height=280,
+        xaxis=dict(
+            title="Modality",
+            tickfont=dict(size=12),
+            gridcolor=BORDER,
+        ),
+        yaxis=dict(
+            title="Uncertainty (%)",
+            range=[0, 120],
+            gridcolor=BORDER,
+            ticksuffix="%",
+        ),
+        bargap=0.38,
+    )
+    return fig
+
+
+#  Comment Sentiment Timeline 
+
+def sentiment_timeline(comments_df: pd.DataFrame, sentiments: List[Dict]) -> go.Figure:
+    """Scatter: comment likes vs. sentiment compound score."""
+    if comments_df.empty:
+        return _empty_fig("Comment Sentiment Distribution")
+
+    df = comments_df.copy()
+    df["compound"] = [s.get("compound", 0) for s in sentiments]
+    df["label"]    = [s.get("label", "NEUTRAL") for s in sentiments]
+    df["color"]    = df["label"].map({"POSITIVE": GREEN, "NEGATIVE": RED, "NEUTRAL": AMBER})
+    df["text_short"] = df["text"].str[:80] + "…"
+
+    fig = go.Figure()
+    for lbl, clr in [("POSITIVE", GREEN), ("NEGATIVE", RED), ("NEUTRAL", AMBER)]:
+        sub = df[df["label"] == lbl]
+        if sub.empty:
+            continue
+        fig.add_trace(go.Scatter(
+            x=sub.index,
+            y=sub["compound"],
+            mode="markers",
+            name=lbl,
+            marker=dict(
+                size=np.clip(np.log1p(sub["likes"].fillna(0)) * 4 + 4, 4, 20),
+                color=clr,
+                opacity=0.75,
+                line=dict(width=0),
             ),
-            "view_count":    int(st.get("viewCount", 0)),
-            "like_count":    int(st.get("likeCount", 0)),
-            "comment_count": int(st.get("commentCount", 0)),
-            "duration":      _parse_duration(cd.get("duration", "PT0S")),
-        }
-        return meta, None
-
-    except requests.exceptions.Timeout:
-        return None, "Request timed out. Check your internet connection."
-    except Exception as exc:
-        return None, str(exc)
-
-
-
-#  Transcript
-
-
-def fetch_transcript(video_id: str) -> tuple[str, str]:
-    """Return (text, status_message)."""
-    try:
-        from youtube_transcript_api import YouTubeTranscriptApi, TranscriptsDisabled, NoTranscriptFound
-        segments = YouTubeTranscriptApi.get_transcript(video_id)
-        text = " ".join(s["text"] for s in segments)
-        return text, f" Transcript: {len(text.split())} words"
-    except Exception as exc:
-        short = str(exc)[:80]
-        return "", f" Transcript unavailable: {short}"
-
-
-
-#  Comments
-
-
-def fetch_comments(
-    video_id: str,
-    api_key: str,
-    max_comments: int = 150,
-) -> tuple[pd.DataFrame, str]:
-    """Return (DataFrame, status_message)."""
-    rows = []
-    next_token = None
-
-    try:
-        while len(rows) < max_comments:
-            want = min(100, max_comments - len(rows))
-            params = {
-                "videoId":    video_id,
-                "key":        api_key,
-                "part":       "snippet",
-                "maxResults": want,
-                "order":      "relevance",
-            }
-            if next_token:
-                params["pageToken"] = next_token
-
-            resp = requests.get(
-                "https://www.googleapis.com/youtube/v3/commentThreads",
-                params=params,
-                timeout=15,
-            )
-            data = resp.json()
-
-            if "error" in data:
-                msg = data["error"].get("message", "Comment API error")
-                break
-
-            for item in data.get("items", []):
-                c = item["snippet"]["topLevelComment"]["snippet"]
-                rows.append({
-                    "author":       c.get("authorDisplayName", ""),
-                    "text":         c.get("textDisplay", ""),
-                    "likes":        int(c.get("likeCount", 0)),
-                    "published_at": c.get("publishedAt", "")[:10],
-                })
-
-            next_token = data.get("nextPageToken")
-            if not next_token or not data.get("items"):
-                break
-
-        if not rows:
-            return pd.DataFrame(), " No comments fetched (comments may be disabled)"
-
-        df = pd.DataFrame(rows)
-        return df, f" Comments: {len(df)} fetched"
-
-    except requests.exceptions.Timeout:
-        return pd.DataFrame(), " Comments request timed out"
-    except Exception as exc:
-        return pd.DataFrame(), f" Comments error: {str(exc)[:80]}"
-
-
-
-#  Search by keyword
-
-
-def search_videos_by_title(
-    keyword: str,
-    api_key: str,
-    max_results: int = 5,
-) -> list[dict]:
-    try:
-        resp = requests.get(
-            "https://www.googleapis.com/youtube/v3/search",
-            params={
-                "q":          keyword,
-                "key":        api_key,
-                "part":       "snippet",
-                "type":       "video",
-                "maxResults": max_results,
-            },
-            timeout=15,
-        )
-        data = resp.json()
-        results = []
-        for item in data.get("items", []):
-            vid_id = item.get("id", {}).get("videoId", "")
-            sn = item.get("snippet", {})
-            if not vid_id:
-                continue
-            results.append({
-                "video_id":      vid_id,
-                "title":         sn.get("title", ""),
-                "channel_title": sn.get("channelTitle", ""),
-                "published_at":  sn.get("publishedAt", "")[:10],
-                "thumbnail_url": sn.get("thumbnails", {}).get("medium", {}).get("url", ""),
-            })
-        return results
-    except Exception:
-        return []
+            text=sub["text_short"],
+            hovertemplate="<b>%{text}</b><br>Sentiment: %{y:.2f}<br>Likes: %{marker.size}<extra></extra>",
+        ))
+
+    fig.add_hline(y=0, line=dict(color=BORDER, width=1, dash="dot"))
+    fig.update_layout(
+        **PLOTLY_LAYOUT,
+        title=dict(text="Comment Sentiment (size = likes)", font=dict(size=13, color=TEXT_DIM), x=0),
+        height=320,
+        xaxis=dict(title="Comment index", gridcolor=BORDER, showgrid=False),
+        yaxis=dict(title="Compound score", gridcolor=BORDER, range=[-1.1, 1.1]),
+        legend=dict(orientation="h", y=1.12, font=dict(size=11)),
+    )
+    return fig
+
+
+#  Positive vs Negative Keyword Comparison ─
+
+def keyword_comparison(
+    pos_kw: List[Tuple[str, float]],
+    neg_kw: List[Tuple[str, float]],
+) -> go.Figure:
+    """Diverging bar chart: positive keywords right, negative left."""
+    if not pos_kw and not neg_kw:
+        return _empty_fig("Sentiment Keywords")
+
+    top = 10
+    pos_kw = pos_kw[:top]
+    neg_kw = neg_kw[:top]
+
+    fig = go.Figure()
+
+    if pos_kw:
+        pw, pv = zip(*pos_kw)
+        max_p = max(pv) or 1
+        fig.add_trace(go.Bar(
+            name="Positive",
+            y=list(pw),
+            x=[v/max_p*100 for v in pv],
+            orientation="h",
+            marker_color=GREEN,
+            hovertemplate="<b>%{y}</b><br>Score: %{x:.1f}<extra></extra>",
+        ))
+
+    if neg_kw:
+        nw, nv = zip(*neg_kw)
+        max_n = max(nv) or 1
+        fig.add_trace(go.Bar(
+            name="Negative",
+            y=list(nw),
+            x=[-v/max_n*100 for v in nv],
+            orientation="h",
+            marker_color=RED,
+            hovertemplate="<b>%{y}</b><br>Score: %{x:.1f}<extra></extra>",
+        ))
+
+    fig.update_layout(
+        **PLOTLY_LAYOUT,
+        title=dict(text="Sentiment-Weighted Keywords", font=dict(size=13, color=TEXT_DIM), x=0),
+        height=360,
+        barmode="overlay",
+        xaxis=dict(title="← Negative  |  Positive →", gridcolor=BORDER, zeroline=True,
+                   zerolinecolor=BORDER, zerolinewidth=2),
+        yaxis=dict(tickfont=dict(size=10)),
+        legend=dict(orientation="h", y=1.1),
+    )
+    return fig
+
+
+#  Helpers ─
+
+def _empty_fig(title: str) -> go.Figure:
+    fig = go.Figure()
+    fig.add_annotation(text="No data available", x=0.5, y=0.5, showarrow=False,
+                       font=dict(size=14, color=TEXT_DIM))
+    fig.update_layout(**PLOTLY_LAYOUT, title=dict(text=title, x=0), height=250)
+    return fig