Embedding Explorer: initial HuggingFace Space

Two-tab Gradio app for Lecture 7 (Embeddings & Transformers):
- Explore: 3D word visualization with click-to-show neighbors
- Vector Math: word arithmetic (king - man + woman ≈ queen)

GloVe 300d embeddings, Plotly 3D, configurable examples via env vars.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

README.md

@@ -0,0 +1,39 @@
+---
+title: Embedding Explorer
+emoji: 📐
+colorFrom: purple
+colorTo: indigo
+sdk: gradio
+sdk_version: "5.12.0"
+app_file: app.py
+pinned: false
+---
+
+# Embedding Explorer
+
+Interactive word vector visualization for the Responsible AI course at Huston-Tillotson University.
+
+## Features
+
+- **Explore** — Type words, see them in 3D space. Similar words cluster together. Click a word to see its nearest neighbors.
+- **Vector Math** — Word arithmetic like `king - man + woman ≈ queen`. Results reveal hidden relationships encoded in the vectors.
+
+## Configuration
+
+All examples are configurable via HuggingFace Space environment variables (no code changes needed):
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `EXPLORE_EXAMPLES` | `["dog cat fish car truck", ...]` | JSON list of word groups for Explore tab |
+| `ARITHMETIC_EXAMPLES` | `["king - man + woman", ...]` | JSON list of expressions for Vector Math tab |
+| `N_NEIGHBORS` | `8` | Number of nearest neighbors to show on click |
+
+## Model
+
+Uses [GloVe](https://nlp.stanford.edu/projects/glove/) (Global Vectors for Word Representation) trained on Wikipedia + Gigaword — 400K words, 300 dimensions. Downloaded automatically on first startup via gensim (~376 MB, cached for subsequent runs).
+
+## Course
+
+Responsible AI: Technology, Power, and Justice (COSC-2300A)
+Huston-Tillotson University, Spring 2026
+Instructor: Chris Hyams

app.py

@@ -0,0 +1,542 @@
+"""
+Embedding Explorer — Interactive word vector visualization
+Responsible AI: Technology, Power, and Justice
+Huston-Tillotson University
+
+Two modes:
+  Explore  — type words, see them in 3D, click to show nearest neighbors
+  Vector Math — word arithmetic (king - man + woman ≈ queen)
+
+Configuration (HuggingFace Space environment variables):
+  EXPLORE_EXAMPLES   — JSON list of space-separated word groups
+  ARITHMETIC_EXAMPLES — JSON list of arithmetic expressions
+  N_NEIGHBORS        — number of neighbors to show on click (default 8)
+"""
+
+import os
+import json
+import re
+
+import numpy as np
+import plotly.graph_objects as go
+from sklearn.decomposition import PCA
+import gradio as gr
+
+# ── Configuration (all changeable via HF Space env vars) ─────
+
+EXPLORE_EXAMPLES = json.loads(os.environ.get("EXPLORE_EXAMPLES", json.dumps([
+    "dog cat fish car truck",
+    "king queen man woman prince princess",
+    "paris france berlin germany tokyo japan",
+])))
+
+ARITHMETIC_EXAMPLES = json.loads(os.environ.get("ARITHMETIC_EXAMPLES", json.dumps([
+    "king - man + woman",
+    "paris - france + germany",
+    "germany - hitler + italy",
+])))
+
+N_NEIGHBORS = int(os.environ.get("N_NEIGHBORS", "8"))
+
+# ── Course design system colors ──────────────────────────────
+
+PURPLE = "#63348d"
+PURPLE_LIGHT = "#ded9f4"
+PURPLE_DARK = "#301848"
+GOLD = "#f0c040"
+PINK = "#de95a0"
+DARK = "#1a1a2e"
+GRAY = "#888888"
+BG = "#fafafa"
+
+# ── Load GloVe embeddings on startup ─────────────────────────
+
+print("=" * 60)
+print("Loading GloVe word vectors (glove-wiki-gigaword-300)...")
+print("First run downloads ~376 MB — subsequent starts use cache.")
+print("=" * 60)
+
+import gensim.downloader as api
+
+model = api.load("glove-wiki-gigaword-300")
+VOCAB = set(model.key_to_index.keys())
+DIMS = model.vector_size
+
+print(f"Ready: {len(VOCAB):,} words, {DIMS} dimensions each")
+
+
+# ── Helpers ──────────────────────────────────────────────────
+
+def tokenize(text):
+    """Split text into lowercase words, deduplicated, order preserved."""
+    words = re.split(r"[,\s]+", text.lower().strip())
+    seen = set()
+    out = []
+    for w in words:
+        w = w.strip()
+        if w and w not in seen:
+            seen.add(w)
+            out.append(w)
+    return out
+
+
+def parse_expression(expr):
+    """Parse 'king - man + woman' → (positives, negatives, ordered).
+
+    ordered is [(word, sign), ...] for display formatting.
+    """
+    tokens = re.findall(r"[a-z']+|[+-]", expr.lower())
+    pos, neg, ordered = [], [], []
+    sign = "+"
+    for t in tokens:
+        if t in "+-":
+            sign = t
+        elif t in VOCAB:
+            (pos if sign == "+" else neg).append(t)
+            ordered.append((t, sign))
+    return pos, neg, ordered
+
+
+def fit_pca_3d(vectors):
+    """PCA → 3D. Returns (coords, fitted_pca)."""
+    n = len(vectors)
+    nc = min(3, n, vectors.shape[1])
+    pca = PCA(n_components=nc)
+    coords = pca.fit_transform(vectors)
+    if nc < 3:
+        coords = np.hstack([coords, np.zeros((n, 3 - nc))])
+    return coords, pca
+
+
+def project_3d(pca, vectors):
+    """Project new vectors into an existing PCA space."""
+    coords = pca.transform(vectors)
+    if coords.shape[1] < 3:
+        coords = np.hstack([coords, np.zeros((len(vectors), 3 - coords.shape[1]))])
+    return coords
+
+
+def layout_3d(height=560):
+    """Shared Plotly 3D layout."""
+    return dict(
+        scene=dict(
+            xaxis=dict(visible=False),
+            yaxis=dict(visible=False),
+            zaxis=dict(visible=False),
+            bgcolor=BG,
+            camera=dict(eye=dict(x=1.5, y=1.5, z=1.2)),
+        ),
+        paper_bgcolor="white",
+        margin=dict(l=0, r=0, t=10, b=10),
+        showlegend=True,
+        legend=dict(
+            yanchor="top", y=0.99, xanchor="left", x=0.01,
+            bgcolor="rgba(255,255,255,0.85)",
+            font=dict(family="Inter, sans-serif", size=12),
+        ),
+        height=height,
+        font=dict(family="Inter, sans-serif"),
+    )
+
+
+def blank(msg):
+    """Empty placeholder figure with a centered message."""
+    fig = go.Figure()
+    fig.add_annotation(
+        text=msg, xref="paper", yref="paper", x=0.5, y=0.5,
+        showarrow=False,
+        font=dict(size=16, color=GRAY, family="Inter, sans-serif"),
+    )
+    fig.update_layout(
+        xaxis_visible=False, yaxis_visible=False,
+        height=560, paper_bgcolor="white", plot_bgcolor="white",
+        margin=dict(l=0, r=0, t=0, b=0),
+    )
+    return fig
+
+
+# ── Explore mode ─────────────────────────────────────────────
+
+def explore(words_text, selected):
+    """3D scatter of typed words; select a radio button to show neighbors."""
+
+    if not words_text or not words_text.strip():
+        return (
+            blank("Enter words above to visualize them in 3D"),
+            "",
+            gr.update(choices=[], value=None, visible=False),
+        )
+
+    all_words = tokenize(words_text)
+    valid = [w for w in all_words if w in VOCAB]
+    bad = [w for w in all_words if w not in VOCAB]
+
+    if len(valid) < 3:
+        msg = "Enter at least 3 valid words for 3D visualization."
+        if bad:
+            msg += f"<br>Not in vocabulary: {', '.join(bad)}"
+        return blank(msg), "", gr.update(choices=[], value=None, visible=False)
+
+    valid = valid[:12]  # cap to keep plot readable
+
+    # Main word vectors — PCA fitted on these only (stable positions)
+    vecs = np.array([model[w] for w in valid])
+    main_coords, pca = fit_pca_3d(vecs)
+
+    # Neighbors (projected into the same PCA space)
+    nbr_data, nbr_coords = [], None
+    if selected and selected != "(clear)" and selected in VOCAB and selected in valid:
+        nbrs = model.most_similar(selected, topn=N_NEIGHBORS)
+        nbr_data = [(w, s) for w, s in nbrs if w not in valid]
+        if nbr_data:
+            nv = np.array([model[w] for w, _ in nbr_data])
+            nbr_coords = project_3d(pca, nv)
+    else:
+        selected = None
+
+    # ── Build figure ──
+    fig = go.Figure()
+
+    # Main words
+    fig.add_trace(go.Scatter3d(
+        x=main_coords[:, 0].tolist(),
+        y=main_coords[:, 1].tolist(),
+        z=main_coords[:, 2].tolist(),
+        mode="markers+text",
+        text=valid,
+        textposition="top center",
+        textfont=dict(size=14, color=DARK),
+        marker=dict(
+            size=9, color=PURPLE, opacity=0.9,
+            line=dict(width=1, color="white"),
+        ),
+        name="Words",
+        hoverinfo="text",
+        hovertext=valid,
+    ))
+
+    # Neighbors + connection lines
+    if nbr_data and nbr_coords is not None:
+        fig.add_trace(go.Scatter3d(
+            x=nbr_coords[:, 0].tolist(),
+            y=nbr_coords[:, 1].tolist(),
+            z=nbr_coords[:, 2].tolist(),
+            mode="markers+text",
+            text=[w for w, _ in nbr_data],
+            textposition="top center",
+            textfont=dict(size=11, color=GRAY),
+            marker=dict(
+                size=5, color=PURPLE_LIGHT, opacity=0.8,
+                line=dict(width=1, color=PURPLE),
+            ),
+            name=f'Near "{selected}"',
+            hoverinfo="text",
+            hovertext=[f"{w} ({s:.3f})" for w, s in nbr_data],
+        ))
+
+        # Dotted lines from selected word to its neighbors
+        si = valid.index(selected)
+        for i in range(len(nbr_data)):
+            fig.add_trace(go.Scatter3d(
+                x=[main_coords[si, 0], nbr_coords[i, 0]],
+                y=[main_coords[si, 1], nbr_coords[i, 1]],
+                z=[main_coords[si, 2], nbr_coords[i, 2]],
+                mode="lines",
+                line=dict(color=PURPLE_LIGHT, width=2, dash="dot"),
+                showlegend=False, hoverinfo="none",
+            ))
+
+    fig.update_layout(**layout_3d())
+
+    # Status
+    status = f"**{len(valid)} words** in 3D"
+    if bad:
+        status += f" · Not found: {', '.join(bad)}"
+    if nbr_data:
+        status += f" · {len(nbr_data)} neighbors of **{selected}**"
+
+    choices = ["(clear)"] + valid
+    return (
+        fig,
+        status,
+        gr.update(choices=choices, value=selected or "(clear)", visible=True),
+    )
+
+
+# ── Arithmetic mode ──────────────────────────────────────────
+
+def arithmetic(expression):
+    """3D visualization of word vector arithmetic."""
+
+    if not expression or not expression.strip():
+        return blank("Enter an expression like: king - man + woman"), ""
+
+    pos, neg, ordered = parse_expression(expression)
+
+    if len(pos) + len(neg) < 2:
+        # Check for words not in vocab
+        all_tokens = re.findall(r"[a-z']+", expression.lower())
+        bad = [t for t in all_tokens if t not in VOCAB and t not in "+-"]
+        msg = "Need at least 2 valid words for arithmetic."
+        if bad:
+            msg += f"<br>Not in vocabulary: {', '.join(bad)}"
+        return blank(msg), ""
+
+    # Compute nearest words to result vector
+    try:
+        raw_results = model.most_similar(positive=pos, negative=neg, topn=10)
+    except Exception as e:
+        return blank(f"Error: {e}"), ""
+
+    # Filter results — exclude operands
+    operands = list(dict.fromkeys(pos + neg))  # dedupe, preserve order
+    result_entries = [(w, s) for w, s in raw_results if w not in operands][:5]
+
+    if not result_entries:
+        return blank("No results found (all matches were input words)"), ""
+
+    # Compute the actual result vector
+    rv = np.zeros(DIMS)
+    for w in pos:
+        rv += model[w]
+    for w in neg:
+        rv -= model[w]
+
+    # Collect all words for PCA
+    result_words = [w for w, _ in result_entries]
+    all_words = operands + result_words
+    all_vecs = np.array([model[w] for w in all_words])
+
+    # Include result vector in PCA fit for best view
+    combined = np.vstack([all_vecs, rv.reshape(1, -1)])
+    coords_all, _ = fit_pca_3d(combined)
+
+    rv_coord = coords_all[-1]
+    coords = coords_all[:-1]
+
+    n_op = len(operands)
+    top_result = result_entries[0]
+    other_results = result_entries[1:]
+
+    # ── Build figure ──
+    fig = go.Figure()
+
+    # Positive operands
+    pi = [i for i, w in enumerate(operands) if w in pos]
+    if pi:
+        fig.add_trace(go.Scatter3d(
+            x=[coords[i, 0] for i in pi],
+            y=[coords[i, 1] for i in pi],
+            z=[coords[i, 2] for i in pi],
+            mode="markers+text",
+            text=[operands[i] for i in pi],
+            textposition="top center",
+            textfont=dict(size=14, color=DARK),
+            marker=dict(size=10, color=PURPLE, opacity=0.9),
+            name="Positive (+)",
+            hoverinfo="text",
+            hovertext=[operands[i] for i in pi],
+        ))
+
+    # Negative operands
+    ni = [i for i, w in enumerate(operands) if w in neg]
+    if ni:
+        fig.add_trace(go.Scatter3d(
+            x=[coords[i, 0] for i in ni],
+            y=[coords[i, 1] for i in ni],
+            z=[coords[i, 2] for i in ni],
+            mode="markers+text",
+            text=[operands[i] for i in ni],
+            textposition="top center",
+            textfont=dict(size=14, color=DARK),
+            marker=dict(size=10, color=PINK, opacity=0.9),
+            name="Negative (−)",
+            hoverinfo="text",
+            hovertext=[operands[i] for i in ni],
+        ))
+
+    # Top result — gold diamond
+    ti = n_op  # index of first result word in coords
+    fig.add_trace(go.Scatter3d(
+        x=[coords[ti, 0]], y=[coords[ti, 1]], z=[coords[ti, 2]],
+        mode="markers+text",
+        text=[f"≈ {top_result[0]}"],
+        textposition="top center",
+        textfont=dict(size=16, color=PURPLE),
+        marker=dict(
+            size=14, color=GOLD, opacity=1.0, symbol="diamond",
+            line=dict(width=2, color=PURPLE),
+        ),
+        name=f"Result: {top_result[0]}",
+        hoverinfo="text",
+        hovertext=[f"{top_result[0]} (similarity: {top_result[1]:.3f})"],
+    ))
+
+    # Other result words — smaller
+    if other_results:
+        oi = list(range(n_op + 1, n_op + 1 + len(other_results)))
+        fig.add_trace(go.Scatter3d(
+            x=[coords[i, 0] for i in oi],
+            y=[coords[i, 1] for i in oi],
+            z=[coords[i, 2] for i in oi],
+            mode="markers+text",
+            text=[f"{w} ({s:.2f})" for w, s in other_results],
+            textposition="top center",
+            textfont=dict(size=11, color=GRAY),
+            marker=dict(size=5, color=PURPLE_LIGHT, opacity=0.7),
+            name="Other matches",
+            hoverinfo="text",
+            hovertext=[f"{w} ({s:.3f})" for w, s in other_results],
+        ))
+
+    # Computed result vector — faint cross marker
+    fig.add_trace(go.Scatter3d(
+        x=[rv_coord[0]], y=[rv_coord[1]], z=[rv_coord[2]],
+        mode="markers",
+        marker=dict(size=7, color=GOLD, opacity=0.4, symbol="cross"),
+        name="Computed point",
+        hoverinfo="text",
+        hovertext=["Exact result of vector arithmetic"],
+    ))
+
+    # Dashed lines: each operand → computed result (shows the path)
+    for i in range(n_op):
+        fig.add_trace(go.Scatter3d(
+            x=[coords[i, 0], rv_coord[0]],
+            y=[coords[i, 1], rv_coord[1]],
+            z=[coords[i, 2], rv_coord[2]],
+            mode="lines",
+            line=dict(color=PURPLE_LIGHT, width=2, dash="dot"),
+            showlegend=False, hoverinfo="none",
+        ))
+
+    fig.update_layout(**layout_3d())
+
+    # Status text
+    parts = []
+    for w, s in ordered:
+        if not parts:
+            parts.append(w)
+        elif s == "+":
+            parts.append(f"+ {w}")
+        else:
+            parts.append(f"− {w}")
+    expr_str = " ".join(parts)
+
+    status = f"**{expr_str} ≈ {top_result[0]}** (similarity: {top_result[1]:.3f})\n\n"
+    status += "Top 5: " + " · ".join(
+        f"**{w}** ({s:.2f})" for w, s in result_entries
+    )
+
+    return fig, status
+
+
+# ── Gradio UI ────────────────────────────────────────────────
+
+CSS = """
+.gradio-container { max-width: 1200px !important; }
+h1 { color: #63348d !important; }
+"""
+
+with gr.Blocks(
+    title="Embedding Explorer",
+    theme=gr.themes.Soft(
+        primary_hue="purple",
+        font=gr.themes.GoogleFont("Inter"),
+    ),
+    css=CSS,
+) as demo:
+
+    gr.Markdown(
+        "# Embedding Explorer\n"
+        "Words in AI models are stored as **vectors** — long lists of numbers "
+        "that encode meaning. Similar words have similar vectors. "
+        "This tool lets you explore these representations in 3D using "
+        "[GloVe](https://nlp.stanford.edu/projects/glove/) word vectors "
+        f"({len(VOCAB):,} words, {DIMS} dimensions)."
+    )
+
+    with gr.Tabs():
+
+        # ── Explore tab ──
+        with gr.Tab("Explore"):
+            gr.Markdown(
+                "*Enter words to see them in 3D space. "
+                "Similar words cluster together. "
+                "Click a word below the plot to see its nearest neighbors.*"
+            )
+            with gr.Row():
+                with gr.Column(scale=1):
+                    exp_in = gr.Textbox(
+                        label="Words (space-separated, min 3)",
+                        placeholder="dog cat fish car truck",
+                        lines=1,
+                    )
+                    exp_btn = gr.Button("Show in 3D", variant="primary")
+                    exp_status = gr.Markdown("")
+                    exp_radio = gr.Radio(
+                        label="Click to see nearest neighbors",
+                        choices=[], value=None,
+                        visible=False, interactive=True,
+                    )
+                    gr.Examples(
+                        examples=[[e] for e in EXPLORE_EXAMPLES],
+                        inputs=[exp_in],
+                        label="Try these",
+                    )
+                with gr.Column(scale=2):
+                    exp_plot = gr.Plot(label="Embedding Space")
+
+            # Events
+            exp_btn.click(
+                lambda w: explore(w, None),
+                inputs=[exp_in],
+                outputs=[exp_plot, exp_status, exp_radio],
+            )
+            exp_in.submit(
+                lambda w: explore(w, None),
+                inputs=[exp_in],
+                outputs=[exp_plot, exp_status, exp_radio],
+            )
+            exp_radio.change(
+                explore,
+                inputs=[exp_in, exp_radio],
+                outputs=[exp_plot, exp_status, exp_radio],
+            )
+
+        # ── Vector Math tab ──
+        with gr.Tab("Vector Math"):
+            gr.Markdown(
+                "*Word vectors can do math! "
+                "The results reveal hidden relationships between words.*"
+            )
+            with gr.Row():
+                with gr.Column(scale=1):
+                    math_in = gr.Textbox(
+                        label="Expression",
+                        placeholder="king - man + woman",
+                        lines=1,
+                    )
+                    math_btn = gr.Button("Compute", variant="primary")
+                    math_status = gr.Markdown("")
+                    gr.Examples(
+                        examples=[[e] for e in ARITHMETIC_EXAMPLES],
+                        inputs=[math_in],
+                        label="Try these",
+                    )
+                with gr.Column(scale=2):
+                    math_plot = gr.Plot(label="Vector Arithmetic")
+
+            # Events
+            math_btn.click(
+                arithmetic,
+                inputs=[math_in],
+                outputs=[math_plot, math_status],
+            )
+            math_in.submit(
+                arithmetic,
+                inputs=[math_in],
+                outputs=[math_plot, math_status],
+            )
+
+demo.launch()

requirements.txt

@@ -0,0 +1,5 @@
+gradio>=5.0
+gensim>=4.3.0
+scikit-learn>=1.3
+plotly>=5.18
+numpy>=1.24