README.md

metadata

title: OPTCG Card Explorer
colorFrom: red
colorTo: blue
sdk: gradio
sdk_version: 5.49.1
python_version: '3.12'
app_file: app.py
pinned: false
license: mit
short_description: Semantic search over One Piece TCG cards

OPTCG Card Explorer

Interactive demo over the optcg-en-card-embeddings dataset: 4372 One Piece Card Game cards embedded with Qwen/Qwen3-Embedding-0.6B (1024-dim, L2-normalized) and projected to 2-D with UMAP.

What it does

• Semantic search - type a free-text query ("low cost red blocker with draw", "leader that punishes wide boards") and get the top-k cards by cosine similarity.
• Interactive UMAP - the full 4372-point cloud is rendered as a Plotly scatter. Search results draw on top in a contrasting overlay.
• Similar cards - click any point on the map (or pick a card from the dropdown) to see its 10 nearest neighbours in embedding space.

No card images are shown. This is a text/structured-data demo by design - see the parent project README for the rationale.

Configuration

• HF_TOKEN (Space secret) - required only while the source dataset repo is private. Read-only access is sufficient.

How it works

The Space pulls cards_with_embeddings.parquet and provenance.json from the dataset repo at startup, stacks the embedding column into a (4372, 1024) float32 matrix once, and reuses the optcg-cards library functions for query encoding and ranking. The task instruction is read from the published provenance, not hardcoded, so query encodings stay comparable to the corpus.

Cold start (model download + parquet pull + warmup): roughly 60-90 s on a free CPU Space. Subsequent queries are sub-second once the model is cached.

Development

git clone <this repo>
cd optcg-explorer-space
pip install -r requirements.txt
export HF_TOKEN=hf_...   # only if the source dataset is private
python app.py

Run the test suite (hermetic by default):

pytest -v

Run the model-backed tests (downloads ~1.2 GB on first use):

pytest -v -m model

License

MIT. Card data is sourced from the official One Piece Card Game site via the vegapull scraper; see the source dataset for full attribution.