README.md

---
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](https://huggingface.co/datasets/t22000t/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](https://github.com/timothy22000/optcg-cards) 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

```bash
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):

```bash
pytest -v
```

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

```bash
pytest -v -m model
```

## License

MIT. Card data is sourced from the official One Piece Card Game site via the [vegapull](https://github.com/Coko7/vegapull) scraper; see the source dataset for full attribution.