# Visual Search Project

## Overview
AI-powered visual product search for Shopify stores using Jina CLIP v2 embeddings.

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│  INDEXING (Local, one-time)                                 │
│  Local Jina CLIP v2 → embeddings → Pinecone                 │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│  SEARCH (HuggingFace Space, free)                           │
│  User image → HF Space (Jina CLIP v2) → Pinecone → Results  │
└─────────────────────────────────────────────────────────────┘
```

## Components

| Component | Location | Purpose |
|-----------|----------|---------|
| `indexer/` | Local script | Index products to Pinecone |
| `app.py` (repo root) | HuggingFace Space | Search API endpoint — the whole repo IS the Space; it runs the root `app.py`/`requirements.txt` (`app_file: app.py`) |
| `shopify/` | Theme integration | Frontend UI |

## Tech Stack
- **Model**: Jina CLIP v2 (jinaai/jina-clip-v2)
- **Vector DB**: Pinecone (free tier)
- **Search API**: HuggingFace Spaces (ZeroGPU — requires HF Pro; ~6s/call)
- **Frontend**: Shopify theme integration

## Environment Variables

### Indexer (.env)
```
SHOPIFY_STORE=25c0da-4
SHOPIFY_ADMIN_TOKEN=shpat_xxxxx
PINECONE_API_KEY=xxxxx
PINECONE_HOST=xxxxx.pinecone.io
```

### HF Space (Secrets)
```
PINECONE_API_KEY=xxxxx
PINECONE_HOST=xxxxx.pinecone.io
```

## Pinecone Index
- **Name**: products (or shopify-llm)
- **Dimensions**: 512
- **Metric**: cosine

## Future Plans
- Sales pattern analysis using visual embeddings
- Cluster similar products → correlate with sales
- Predict new product performance

## Commands

```bash
# Index products (run locally)
cd indexer
pip install -r requirements.txt
python index.py --clear

# Deploy HF Space (the repo root IS the Space — app.py at root)
# Edit app.py / requirements.txt at the repo root, commit, then:
git push hf master:main   # triggers a Space rebuild
```

## Related
- Theme repo: Kuwait-v6
- Store: https://25c0da-4.myshopify.com
- Store domain: https://alnasser.net