metadata

title: Visual Product Matcher
emoji: 🔍
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
pinned: false

Visual Product Search 🔍

An intelligent visual search engine that revolutionizes product discovery using state-of-the-art AI technology. This application combines CLIP (Contrastive Language-Image Pre-Training) with Qdrant vector database to enable semantic search across image collections, making it perfect for e-commerce, inventory management, and content discovery.

🌟 Key Features

🎯 Multi-Modal Search: Search using text descriptions, uploaded images, or image URLs
🖼️ Smart Indexing: Automatically indexes and monitors image folders with real-time updates
🔍 Semantic Understanding: Uses OpenAI's CLIP model for deep image-text comprehension
� Similarity Scoring: Provides percentage-based similarity scores for accurate results
⚡ Real-time Processing: WebSocket-powered live progress updates during indexing
🎨 Modern UI: Clean, responsive interface with advanced search capabilities
🌐 URL Support: Direct image search from web URLs
📱 Mobile Responsive: Works seamlessly across all devices

🧠 Technical Approach & Solution

Problem Statement

Traditional image search relies on metadata and filenames, which often fail to capture the actual visual content. Users struggle to find specific products or images without knowing exact file names or having perfect tagging systems.

Our Solution Architecture

1. Multi-Modal Embedding Generation

Text Query → CLIP Text Encoder → 512D Vector
Image Input → CLIP Vision Encoder → 512D Vector
URL Image → Download → CLIP Vision Encoder → 512D Vector

2. Vector Similarity Search

Database: Qdrant cloud vector database for scalable similarity search
Indexing: Real-time folder monitoring with automatic embedding generation
Storage: Hybrid approach - embeddings in Qdrant, metadata in SQLite

3. Semantic Matching Pipeline

User Input → Feature Extraction → Vector Search → Similarity Ranking → Results

�️ Architecture Components

Backend (FastAPI)

Image Processing: PIL + CLIP for feature extraction
Vector Operations: Qdrant client for similarity search
File Management: Automatic folder monitoring and indexing
API Endpoints: RESTful APIs for all search operations

Frontend (Modern Web UI)

Framework: Vanilla JavaScript with Bootstrap 5
Styling: Custom CSS with modern design principles
Real-time Updates: WebSocket connections for live progress
Responsive Design: Mobile-first approach

Database Layer

Vector Storage: Qdrant cloud for embeddings and similarity search
Metadata Storage: SQLite for image metadata and file information
Caching: Thumbnail generation and caching for performance

🚀 Quick Start

Prerequisites

Python 3.8+
CUDA-compatible GPU (optional, recommended for performance)
Qdrant Cloud account (free tier available)

Installation

Clone the repository:

git clone https://github.com/itsfuad/SnapSeek
cd SnapSeek

Create virtual environment:

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

Install dependencies:

pip install -r requirements.txt

Configure environment: Create a .env file:

QDRANT_API_KEY=your_qdrant_api_key
QDRANT_URL=your_qdrant_cluster_url

Launch the application:

python app.py

Access the interface: Open http://localhost:8000 in your browser

🎯 Usage Guide

1. Index Your Images

Click "Add Folder" to select image directories
Watch real-time indexing progress
Images are automatically monitored for changes

2. Search Methods

Text Search

"red sports car"
"woman wearing blue dress"
"modern kitchen design"

Image Upload Search

Click the image icon
Upload a reference image
Get visually similar results

URL Search

Click the link icon
Paste any image URL
Find similar images in your collection

3. Results & Insights

Similarity percentages for each match
High-resolution image previews
Metadata and file information

🏭 Production Deployment

Recommended Platforms

1. Railway (Recommended)

Why: Best for AI/ML applications with generous free tier
Resources: 512MB RAM, 1GB storage
Benefits: No sleep mode, automatic GitHub deployments

# Dockerfile
FROM python:3.9-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

2. Render

Resources: 512MB RAM, 1GB storage
Benefits: Free SSL, auto-deploy, no cold starts

3. Fly.io

Resources: 256MB RAM, 3GB storage volume
Benefits: Global edge deployment, persistent volumes

Environment Variables for Production

QDRANT_API_KEY=your_production_key
QDRANT_URL=your_production_cluster
PORT=8000
DATA_DIR=/app/data

🛠️ Development & Testing

Project Structure

SnapSeek/
├── app.py                 # FastAPI application
├── image_indexer.py       # Image processing and indexing
├── image_search.py        # Search logic and CLIP integration
├── image_database.py      # Database operations
├── folder_manager.py      # Folder monitoring and management
├── qdrant_singleton.py    # Qdrant client management
├── requirements.txt       # Dependencies
├── .env                   # Environment configuration
├── templates/
│   └── index.html        # Main UI template
├── static/
│   ├── js/
│   │   └── script.js     # Frontend JavaScript
│   └── image.png         # Application icon
├── config/
│   └── folders.json      # Folder configuration
└── tests/
    └── test_*.py         # Test files

Running Tests

pip install -r requirements-test.txt
pytest tests/ -v

Development Setup

# Install development dependencies
pip install -r requirements-test.txt

# Run with auto-reload
uvicorn app:app --reload --host 0.0.0.0 --port 8000

🔧 Performance Optimization

Model Selection

# For production (smaller, faster)
MODEL_NAME = "openai/clip-vit-base-patch16"

# For development (balance)
MODEL_NAME = "openai/clip-vit-base-patch32"

Hardware Recommendations

CPU: 4+ cores for concurrent processing
RAM: 8GB+ for model loading and image processing
Storage: SSD recommended for faster I/O
GPU: Optional, CUDA-compatible for faster inference

Scaling Considerations

Batch Processing: Process multiple images simultaneously
Caching: Implement Redis for frequent queries
Load Balancing: Use multiple instances for high traffic
Database Sharding: Split collections by categories

🐛 Troubleshooting

Common Issues

1. Model Loading Errors

# Clear cache and reinstall
pip uninstall torch torchvision transformers
pip install torch torchvision transformers --no-cache-dir

2. Qdrant Connection Issues

Verify API key and URL in .env
Check network connectivity
Ensure Qdrant cluster is active

3. Memory Issues

Reduce batch size in processing
Use CPU-only mode: device="cpu"
Close unused applications

4. Slow Performance

Enable GPU acceleration
Optimize image sizes
Implement result caching

Performance Monitoring

# Add logging for performance tracking
import time
import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

# Time search operations
start_time = time.time()
results = await searcher.search_by_text(query)
logger.info(f"Search completed in {time.time() - start_time:.2f}s")

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature-name
Make your changes and add tests
Run tests: pytest tests/
Commit changes: git commit -m "Add feature"
Push to branch: git push origin feature-name
Create a Pull Request

Code Standards

Follow PEP 8 style guidelines
Add docstrings to all functions
Include type hints where appropriate
Write tests for new features

📊 Use Cases & Applications

E-commerce

Product recommendation systems
Visual search for online stores
Inventory management
Duplicate product detection

Content Management

Digital asset organization
Stock photo searching
Brand consistency checking
Content moderation

Research & Education

Academic image databases
Scientific data analysis
Historical archive searches
Educational content discovery

🔮 Future Enhancements

Multi-language Support: Extend text search to multiple languages
Advanced Filters: Add size, color, and metadata filters
Batch Operations: Upload and search multiple images at once
API Integration: RESTful API for external applications
Machine Learning: Custom fine-tuned models for specific domains
Analytics Dashboard: Search metrics and usage statistics
Mobile App: Native mobile applications
Cloud Storage: Integration with AWS S3, Google Drive, etc.

📄 License

This project is licensed under the Mozilla Public License 2.0 - see the LICENSE file for details.

🙏 Acknowledgments

OpenAI: For the CLIP model and research
Qdrant: For the excellent vector database
FastAPI: For the modern web framework
Transformers: For the model implementation
Bootstrap: For the UI components

📞 Support & Contact

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: Wiki

Made with ❤️ by itsfuad

Revolutionizing visual search with AI technology