app.py

"""OPTCG Card Explorer - Gradio Space.

Semantic search over the published Qwen3-Embedding corpus of 4372 One
Piece Card Game cards plus an interactive UMAP scatter and a similar-
cards browser.

Data source: https://huggingface.co/datasets/t22000t/optcg-en-card-embeddings
"""

from __future__ import annotations

import logging
import os
from typing import Any

import gradio as gr

from spaceutil.cards import top_k_with_matrix
from spaceutil.data import load_corpus
from spaceutil.encoder import encode_query_via_optcg, get_encoder
from spaceutil.plot import build_cost_curve_figure, build_umap_figure
from spaceutil.synergy import recommend_synergy

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s")
logger = logging.getLogger("optcg-explorer")


# ----------------------------------------------------------------------------
# Startup - run once when the Space's container boots
# ----------------------------------------------------------------------------

logger.info("Loading corpus from HF Hub...")
CARDS, MATRIX, EMBED_PROV, ID_TO_IDX = load_corpus(token=os.environ.get("HF_TOKEN"))
logger.info("Corpus loaded: %d cards, matrix shape %s", len(CARDS), MATRIX.shape)

logger.info("Warming up encoder...")
get_encoder(EMBED_PROV)
logger.info("Encoder ready.")

DROPDOWN_CHOICES = sorted(f"{c['name']} ({c['id']})" for c in CARDS)
LEADER_CHOICES = sorted(
    f"{c['name']} ({c['id']})"
    for c in CARDS
    if c.get("card_type") == "Leader"
)

# Quick stats for the header card.
N_CARDS = len(CARDS)
N_SETS = len({c.get("set_code") for c in CARDS if c.get("set_code")})
N_LEADERS = sum(1 for c in CARDS if c.get("card_type") == "Leader")
LATEST_SET = max((c.get("set_code") or "" for c in CARDS), default="?")
EMBEDDING_DIM = MATRIX.shape[1]
MODEL_ID = EMBED_PROV.model_id


# ----------------------------------------------------------------------------
# Display helpers
# ----------------------------------------------------------------------------

# Fields rendered in card detail. Excludes any image/url field by
# construction (CLAUDE.md hard rule).
DETAIL_FIELDS = (
    ("card_type", "Type"),
    ("colors", "Colors"),
    ("cost", "Cost"),
    ("power", "Power"),
    ("counter", "Counter"),
    ("life", "Life"),
    ("attribute", "Attribute"),
    ("family", "Family"),
    ("rarity", "Rarity"),
    ("set_name", "Set"),
    ("effect_text", "Effect"),
    ("trigger_text", "Trigger"),
)


def _fmt_value(value: Any) -> str:
    if value is None or value == "":
        return "-"
    if isinstance(value, list):
        return ", ".join(str(v) for v in value) if value else "-"
    return str(value)


def format_card_detail(card: dict[str, Any]) -> str:
    lines = [f"### {card.get('name', '?')}\n`{card.get('id', '?')}`\n"]
    for key, label in DETAIL_FIELDS:
        lines.append(f"**{label}:** {_fmt_value(card.get(key))}")
    return "\n\n".join(lines)


RESULT_HEADERS = ["Rank", "ID", "Name", "Score", "Type", "Colors", "Set"]


def hits_to_rows(hits) -> list[list[Any]]:
    return [
        [
            h.rank,
            h.card_id,
            h.name,
            round(h.score, 4),
            (h.metadata or {}).get("card_type") or "",
            ", ".join((h.metadata or {}).get("colors") or []),
            (h.metadata or {}).get("set_code") or "",
        ]
        for h in hits
    ]


# ----------------------------------------------------------------------------
# Event handlers
# ----------------------------------------------------------------------------


def on_search(query: str, k: int):
    query = (query or "").strip()
    if not query:
        return build_umap_figure(CARDS, highlight_indices=None), []
    query_vec = encode_query_via_optcg(query, EMBED_PROV)
    hits = top_k_with_matrix(query_vec, MATRIX, CARDS, k=int(k))
    indices = [ID_TO_IDX[h.card_id] for h in hits if h.card_id in ID_TO_IDX]
    fig = build_umap_figure(CARDS, highlight_indices=indices)
    return fig, hits_to_rows(hits)


def _selection_to_idx(selection: str) -> int | None:
    if not selection:
        return None
    if "(" in selection and selection.endswith(")"):
        card_id = selection.rsplit("(", 1)[1][:-1]
    else:
        card_id = selection
    return ID_TO_IDX.get(card_id)


def on_dropdown_pick(selection: str, k: int):
    idx = _selection_to_idx(selection)
    if idx is None:
        return "Pick a card to see its details and nearest neighbours.", []
    card = CARDS[idx]
    detail = format_card_detail(card)
    query_vec = MATRIX[idx]
    hits = top_k_with_matrix(query_vec, MATRIX, CARDS, k=int(k), exclude_idx=idx)
    return detail, hits_to_rows(hits)


SYNERGY_HEADERS = ["Rank", "ID", "Name", "Score", "Family match", "Type", "Cost", "Colors"]


def synergy_hits_to_rows(hits) -> list[list[Any]]:
    return [
        [
            h.rank,
            h.card_id,
            h.name,
            round(h.total_score, 4),
            "yes" if h.family_match else "no",
            h.card_type,
            h.cost if h.cost is not None else "-",
            ", ".join(h.colors),
        ]
        for h in hits
    ]


def on_leader_pick(selection: str, k: int):
    idx = _selection_to_idx(selection)
    if idx is None:
        return (
            "*Pick a Leader card above to see synergy recommendations.*",
            build_cost_curve_figure([]),
            [],
        )
    card = CARDS[idx]
    if card.get("card_type") != "Leader":
        return (
            f"**{card.get('name')}** is not a Leader. Pick one from the dropdown.",
            build_cost_curve_figure([]),
            [],
        )
    detail = format_card_detail(card)
    hits = recommend_synergy(idx, CARDS, MATRIX, k=int(k))
    return detail, build_cost_curve_figure(hits), synergy_hits_to_rows(hits)


# ----------------------------------------------------------------------------
# UI
# ----------------------------------------------------------------------------

CUSTOM_CSS = """
.gradio-container { max-width: 1280px !important; margin: 0 auto !important; }
#header-row h1 { margin-bottom: 0.25em; }
#header-row .subtitle { color: var(--body-text-color-subdued); margin-top: 0; }
.stats-pill {
  display: inline-block;
  padding: 4px 10px;
  margin: 2px 4px 2px 0;
  border-radius: 12px;
  background: var(--background-fill-secondary);
  border: 1px solid var(--border-color-primary);
  font-size: 0.85em;
}
.muted { color: var(--body-text-color-subdued); font-size: 0.9em; }
"""

EXAMPLE_QUERIES = [
    ["low cost red blocker with draw"],
    ["strong yellow leader with life manipulation"],
    ["purple rush attacker that uses DON"],
    ["card that returns characters to opponent's hand"],
    ["blue counter card with at least +2000"],
    ["green stage that activates on play"],
    ["leader that punishes wide boards"],
    ["event that draws cards and trashes from deck"],
]

INSTRUCTIONS_MD = """
**Three ways to explore:**

1. **Search by description** - type plain English describing the card you're imagining ("low cost red blocker with draw", "leader that punishes wide boards"). The query is encoded with the same Qwen3-Embedding model used on the corpus, then ranked by cosine similarity. Top-k results appear in the table and are highlighted on the map.

2. **Browse / find similar** - pick any card from the dropdown to see its full details and the 10 most mechanically similar cards in embedding space. Useful for finding swap candidates with comparable mechanics.

3. **Synergy inspector** - pick a **Leader** card to see recommendations that are color-legal under it, sorted by mechanical similarity with a bonus for cards in the leader's family/archetype. The cost curve shows the distribution of recommendations across costs - useful when sketching a deck shape.

**Tips**
- Search and browse rank by raw cosine similarity. Synergy adds OPTCG deckbuilding constraints on top: color legality (must share at least one color with the leader) and a +0.10 family bonus for archetype matches.
- Score is cosine similarity in [-1, 1]. Anything above ~0.55 is usually a strong match; below ~0.35 the model is reaching.
- Mix mechanical keywords (Blocker, Rush, Counter, On Play) with constraints (color, cost, power) for tighter search results.
- The UMAP is a 2-D projection of the same 1024-dim space - clusters tend to share color and card type.
"""

ABOUT_MD = f"""
### How it works

Each of the {N_CARDS} cards is encoded as a single vector by **`{MODEL_ID}`** ({EMBEDDING_DIM}-dim, L2-normalized). The encoding strategy follows the proven `minimaxir/mtg-embeddings` recipe: serialize the mechanically-relevant fields as a prettified JSON document, replace the card's own name with `~` to neutralize self-references, then prepend a task instruction string so the model knows what kind of similarity matters (gameplay mechanics, not flavor text).

When you submit a query, the same instruction wrapper is applied and the resulting vector is compared by dot product against the precomputed corpus matrix. UMAP coordinates are precomputed in the dataset and just rendered here.

The task instruction comes from the dataset's `provenance.json` rather than being hardcoded, so the Space stays in sync if the upstream embedding ever changes.

### Dataset

[`t22000t/optcg-en-card-embeddings`](https://huggingface.co/datasets/t22000t/optcg-en-card-embeddings) - {N_CARDS} cards across {N_SETS} sets, latest pack `{LATEST_SET}`. Sister dataset [`t22000t/optcg-en-cards`](https://huggingface.co/datasets/t22000t/optcg-en-cards) carries the structured fields without the embedding column.

### What this Space deliberately does not show

No card images. The Space is text and structured-data only. See the [parent project README](https://github.com/timothy22000/optcg-cards) for the IP rationale.

### Source

Card data comes from the official One Piece Card Game site via the [vegapull](https://github.com/Coko7/vegapull) scraper. Pipeline code is at [github.com/timothy22000/optcg-cards](https://github.com/timothy22000/optcg-cards). This Space is at [github.com/timothy22000/optcg-cards](https://github.com/timothy22000/optcg-cards) (sibling repo `optcg-explorer-space`).
"""


with gr.Blocks(
    title="OPTCG Card Explorer",
    theme=gr.themes.Soft(primary_hue="red", secondary_hue="blue"),
    css=CUSTOM_CSS,
) as demo:
    # ----- Header -----
    with gr.Row(elem_id="header-row"):
        gr.Markdown(
            f"""# OPTCG Card Explorer
<p class="subtitle">Semantic search and similarity browser for One Piece Card Game cards, powered by Qwen3-Embedding vectors.</p>

<div>
  <span class="stats-pill"><b>{N_CARDS}</b> cards</span>
  <span class="stats-pill"><b>{N_SETS}</b> sets</span>
  <span class="stats-pill"><b>{N_LEADERS}</b> leaders</span>
  <span class="stats-pill">latest <b>{LATEST_SET}</b></span>
  <span class="stats-pill">{EMBEDDING_DIM}-dim Qwen3</span>
</div>

<p class="muted">Dataset: <a href="https://huggingface.co/datasets/t22000t/optcg-en-card-embeddings" target="_blank">t22000t/optcg-en-card-embeddings</a> &nbsp;&middot;&nbsp; Code: <a href="https://github.com/timothy22000/optcg-cards" target="_blank">github.com/timothy22000/optcg-cards</a></p>
"""
        )

    # ----- Instructions -----
    with gr.Accordion("How to use this Space", open=True):
        gr.Markdown(INSTRUCTIONS_MD)

    # ----- Main tabs -----
    with gr.Tabs():
        # ============ SEARCH TAB ============
        with gr.Tab("Search by description"):
            with gr.Row():
                query_in = gr.Textbox(
                    label="Describe the card you're looking for",
                    placeholder="e.g. low cost red blocker with draw",
                    scale=4,
                    autofocus=True,
                )
                k_slider = gr.Slider(
                    minimum=5,
                    maximum=25,
                    value=10,
                    step=1,
                    label="Top-k results",
                    scale=1,
                )
                search_btn = gr.Button("Search", variant="primary", scale=1)

            gr.Examples(
                examples=EXAMPLE_QUERIES,
                inputs=[query_in],
                label="Try one of these",
            )

            with gr.Row():
                with gr.Column(scale=3):
                    umap_plot = gr.Plot(
                        value=build_umap_figure(CARDS, highlight_indices=None),
                        label="Embedding map (UMAP)",
                    )
                with gr.Column(scale=2):
                    results_df = gr.Dataframe(
                        headers=RESULT_HEADERS,
                        value=[],
                        label="Top matches",
                        interactive=False,
                        wrap=True,
                        column_widths=["8%", "16%", "30%", "12%", "14%", "12%", "8%"],
                    )

            gr.Markdown(
                "*The map shows all 4372 cards projected to 2-D. "
                "After a search, the top-k hits are drawn on top with larger black-bordered markers.*",
                elem_classes=["muted"],
            )

        # ============ BROWSE TAB ============
        with gr.Tab("Browse / find similar"):
            gr.Markdown(
                "Pick any card to see its full details and the cards that are closest to it in embedding space - "
                "useful when you want swap candidates with similar mechanics."
            )

            with gr.Row():
                card_picker = gr.Dropdown(
                    choices=DROPDOWN_CHOICES,
                    label="Card",
                    value=None,
                    allow_custom_value=False,
                    filterable=True,
                    info="Type to filter by name or card ID (e.g. OP01-001).",
                    scale=4,
                )
                k_slider_browse = gr.Slider(
                    minimum=5,
                    maximum=25,
                    value=10,
                    step=1,
                    label="Neighbours",
                    scale=1,
                )

            with gr.Row():
                with gr.Column(scale=2):
                    card_detail_md = gr.Markdown(
                        "*Pick a card above to see its details.*",
                        label="Card details",
                    )
                with gr.Column(scale=3):
                    similar_df = gr.Dataframe(
                        headers=RESULT_HEADERS,
                        value=[],
                        label="Similar cards",
                        interactive=False,
                        wrap=True,
                        column_widths=["8%", "16%", "30%", "12%", "14%", "12%", "8%"],
                    )

        # ============ SYNERGY TAB ============
        with gr.Tab("Synergy inspector"):
            gr.Markdown(
                "Pick a **Leader** card and see what fits in a deck around it. "
                "Recommendations are filtered to color-legal cards (must share at least one color with the leader) "
                "and ranked by `cosine_similarity(leader, card) + family_bonus`, where family bonus is "
                "+0.10 if the card and leader share at least one family/archetype. Other Leaders are excluded."
            )

            with gr.Row():
                leader_picker = gr.Dropdown(
                    choices=LEADER_CHOICES,
                    label="Leader",
                    value=None,
                    allow_custom_value=False,
                    filterable=True,
                    info=f"{N_LEADERS} leader cards in the corpus.",
                    scale=4,
                )
                k_slider_synergy = gr.Slider(
                    minimum=10,
                    maximum=60,
                    value=30,
                    step=5,
                    label="Recommendations",
                    scale=1,
                )

            with gr.Row():
                with gr.Column(scale=2):
                    leader_detail_md = gr.Markdown(
                        "*Pick a Leader above to see synergy recommendations.*",
                        label="Leader details",
                    )
                with gr.Column(scale=3):
                    cost_curve_plot = gr.Plot(
                        value=build_cost_curve_figure([]),
                        label="Cost curve of recommendations",
                    )

            synergy_df = gr.Dataframe(
                headers=SYNERGY_HEADERS,
                value=[],
                label="Recommended cards",
                interactive=False,
                wrap=True,
                column_widths=["6%", "13%", "27%", "10%", "10%", "12%", "7%", "15%"],
            )

            gr.Markdown(
                "*Score breakdown is `base_cosine + family_bonus`. "
                "A `Family match: yes` row got the +0.10 boost. "
                "Cost is shown for Characters/Events/Stages; Stages with no cost render as `-`.*",
                elem_classes=["muted"],
            )

    # ----- About / footer -----
    with gr.Accordion("About this Space", open=False):
        gr.Markdown(ABOUT_MD)

    gr.Markdown(
        '<div class="muted" style="text-align:center; padding:12px 0;">'
        'Built with <a href="https://gradio.app" target="_blank">Gradio</a>. '
        'Embeddings: Qwen/Qwen3-Embedding-0.6B. '
        'Card data via <a href="https://github.com/Coko7/vegapull" target="_blank">vegapull</a>. '
        'Not affiliated with Bandai or the One Piece Card Game.'
        '</div>'
    )

    # ----- Wiring -----
    search_btn.click(
        on_search,
        inputs=[query_in, k_slider],
        outputs=[umap_plot, results_df],
    )
    query_in.submit(
        on_search,
        inputs=[query_in, k_slider],
        outputs=[umap_plot, results_df],
    )
    card_picker.change(
        on_dropdown_pick,
        inputs=[card_picker, k_slider_browse],
        outputs=[card_detail_md, similar_df],
    )
    k_slider_browse.change(
        on_dropdown_pick,
        inputs=[card_picker, k_slider_browse],
        outputs=[card_detail_md, similar_df],
    )
    leader_picker.change(
        on_leader_pick,
        inputs=[leader_picker, k_slider_synergy],
        outputs=[leader_detail_md, cost_curve_plot, synergy_df],
    )
    k_slider_synergy.change(
        on_leader_pick,
        inputs=[leader_picker, k_slider_synergy],
        outputs=[leader_detail_md, cost_curve_plot, synergy_df],
    )


if __name__ == "__main__":
    demo.launch()