CLAUDE.md

# 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 |
| `hf-space/` | HuggingFace Space | Search API endpoint |
| `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, free)
- **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
cd hf-space
# Push to HuggingFace
```

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