---
title: Sneaker Visual Search
emoji: 👟
colorFrom: indigo
colorTo: purple
sdk: docker
pinned: false
short_description: "Find your sneaker on StockX & GOAT by visual match"
---

# sneaker-visual-search

Cross-platform visual search for sneakers and streetwear. Upload a photo of a
sneaker and find visually similar listings for sale across resale marketplaces,
ranked by visual similarity, with size and budget filters and direct buy links.

**First MVP:** StockX + GOAT, new and used inventory. Goal: a deployed web app
tested by 10 friends.

## Status

See [`docs/workflow-status.md`](docs/workflow-status.md) for current progress.
Architecture lives in [`docs/architecture.md`](docs/architecture.md); decisions
are recorded in [`docs/adr/`](docs/adr/).

## Prerequisites

- Python 3.13 (Windows: install from python.org; use the `py` launcher)
- A SerpAPI key (Google Lens recall)
- A Hugging Face token (model downloads)

## Setup

```
py -m venv .venv
.venv\Scripts\activate
py -m pip install --upgrade pip
py -m pip install -e ".[dev]"

copy .env.example .env
# then open .env and fill in your keys
```

## Run

```
# run a single search end-to-end from the CLI
py scripts\test_query.py "C:\path\to\sneaker.png"

# run the web app
py -m streamlit run app\streamlit_app.py
```

## Project layout

- `src/sneaker_search/` — the package (config, models, embedding, search, platforms)
- `scripts/` — one-off runnable scripts (benchmark, CLI test)
- `app/` — the Streamlit UI
- `tests/` — tests
- `docs/` — PRD, architecture, living status, and decision records

## Development

- Format & lint: `ruff format . && ruff check --fix .`
- Tests: `py -m pytest`
- Work one story at a time from `docs/workflow-status.md`; keep `main` runnable.