{"id":31283071,"url":"https://github.com/hasnainmumtaz/imagemania","last_synced_at":"2026-05-06T02:39:30.558Z","repository":{"id":315643659,"uuid":"1020855998","full_name":"hasnainmumtaz/ImageMania","owner":"hasnainmumtaz","description":"Reverse Image Search for Shopify Products","archived":false,"fork":false,"pushed_at":"2025-09-19T20:46:39.000Z","size":63720,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-09-19T21:30:43.217Z","etag":null,"topics":["fastapi","image-embeddings","reverse-image-search","shopify","streamlit"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hasnainmumtaz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-16T13:52:33.000Z","updated_at":"2025-09-19T20:46:42.000Z","dependencies_parsed_at":"2025-09-19T21:30:46.057Z","dependency_job_id":"ee87711a-3678-44e5-aa26-54cc6f3b89ab","html_url":"https://github.com/hasnainmumtaz/ImageMania","commit_stats":null,"previous_names":["hasnainmumtaz/imagemania"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/hasnainmumtaz/ImageMania","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hasnainmumtaz%2FImageMania","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hasnainmumtaz%2FImageMania/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hasnainmumtaz%2FImageMania/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hasnainmumtaz%2FImageMania/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hasnainmumtaz","download_url":"https://codeload.github.com/hasnainmumtaz/ImageMania/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hasnainmumtaz%2FImageMania/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276689353,"owners_count":25686697,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-24T02:00:09.776Z","response_time":97,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastapi","image-embeddings","reverse-image-search","shopify","streamlit"],"created_at":"2025-09-24T04:07:49.314Z","updated_at":"2025-09-24T04:07:51.801Z","avatar_url":"https://github.com/hasnainmumtaz.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🛍️ Shopify Product Image Search with CLIP\r\n\r\nA powerful reverse image search application that connects to your Shopify store to find similar products using AI-powered image embeddings. Features a FastAPI backend with local storage for persistent caching and a modern Streamlit frontend.\r\n\r\n## ✨ Features\r\n\r\n- **Shopify Integration**: Directly fetch products and images from your Shopify store\r\n- **AI-Powered Search**: Uses OpenAI's CLIP model for accurate image similarity matching\r\n- **Real-time Results**: Upload any image and find similar products instantly\r\n- **Product Links**: Direct links to view products on your Shopify store\r\n- **Beautiful UI**: Modern Streamlit interface with progress tracking\r\n- **🆕 Local Storage**: Persistent disk caching for faster startup and reduced API calls\r\n- **🆕 Smart Caching**: Only embeds new or updated products using metadata hashing\r\n- **🆕 Multi-store Support**: Search across multiple Shopify stores simultaneously\r\n- **🆕 FastAPI Backend**: Scalable API server with comprehensive monitoring\r\n- **🆕 Dual Interface**: Both standalone Streamlit app and FastAPI + Streamlit combo\r\n- **🆕 Store Isolation**: Secure separation of embeddings between different stores\r\n- **🆕 Resource Monitoring**: Real-time memory, storage, and performance metrics\r\n\r\n## 🚀 Quick Start\r\n\r\n### 1. Clone the Repository\r\n\r\n```bash\r\ngit clone https://github.com/hasnainmumtaz/ImageMania\r\ncd ImageMania\r\n```\r\n\r\n### 2. Install Dependencies\r\n\r\n```bash\r\npip install -r requirements.txt\r\n```\r\n\r\n### 3. Set up Shopify API Access\r\n\r\n1. **Create a Private App in Shopify:**\r\n   - Go to your Shopify admin → Apps → Develop apps\r\n   - Click \"Create an app\"\r\n   - Give it a name (e.g., \"Image Search App\")\r\n   - Under \"Admin API access scopes\", enable:\r\n     - `read_products`\r\n     - `read_product_listings`\r\n   - Click **\"Save\"**\r\n   - Go to **\"API credentials\"** tab\r\n   - Click **\"Install app\"** to generate the access token\r\n   - Copy the **Admin API access token**\r\n\r\n2. **Get your credentials:**\r\n   - Shop URL (e.g., `your-store.myshopify.com`)\r\n   - Admin API access token (not the API key)\r\n\r\n3. **Test your credentials:**\r\n   ```bash\r\n   python test_shopify_auth.py\r\n   ```\r\n\r\n### 4. Run the Application\r\n\r\n#### Option A: FastAPI + Streamlit (Recommended)\r\n```bash\r\n# Terminal 1: Start API server\r\npython api_server.py\r\n\r\n# Terminal 2: Start Streamlit app\r\nstreamlit run streamlit_app.py\r\n```\r\n\r\n#### Option B: API Only (For Developers)\r\n```bash\r\n# Start the API server\r\npython api_server.py\r\n\r\n# In another terminal, run the client example\r\npython client_example.py\r\n\r\n# Or run the storage demo\r\npython storage_demo.py\r\n```\r\n\r\n### 5. Configure and Use\r\n\r\n1. Open the Streamlit app in your browser (usually `http://localhost:8501`)\r\n2. Enter your Shopify credentials\r\n3. Load products (embeddings are cached locally for faster subsequent runs)\r\n4. Upload an image to find similar products\r\n5. Browse results with similarity scores and direct product links\r\n\r\n## 🔧 How It Works\r\n\r\n1. **Product Fetching**: The app connects to your Shopify store via API and retrieves all products with images\r\n2. **Smart Caching**: Checks for existing embeddings on disk and only processes new/updated products\r\n3. **Image Embedding**: Each product image is processed through CLIP to create high-dimensional embeddings\r\n4. **Local Storage**: Embeddings are saved to disk for persistent caching across server restarts\r\n5. **Similarity Search**: When you upload a query image, it's embedded and compared against all product embeddings\r\n6. **Results Ranking**: Products are ranked by cosine similarity score and displayed with relevant information\r\n\r\n## 💾 Local Storage Features\r\n\r\n### **Smart Caching System**\r\n- **Persistent Storage**: Embeddings saved to `embeddings_cache/` directory\r\n- **Change Detection**: Only embeds new or updated products using metadata hashing\r\n- **Store Isolation**: Each store's embeddings are stored separately with secure token hashing\r\n- **Automatic Updates**: Detects product changes and updates embeddings incrementally\r\n\r\n### **Storage Management**\r\n- **Cache Info**: Monitor cache size, hit rates, and update frequency\r\n- **Storage Monitoring**: Track disk usage and file management\r\n- **Cache Clearing**: Clear specific store caches or all storage\r\n- **Performance Metrics**: Monitor processing time and memory usage\r\n\r\n### **Benefits**\r\n- ⚡ **Faster Startup**: No need to re-embed all products on restart\r\n- 🔄 **Reduced API Calls**: Only fetch new/updated products from Shopify\r\n- 💾 **Persistent Cache**: Survives server restarts and updates\r\n- 📊 **Efficient Updates**: Incremental embedding updates\r\n- 🏪 **Multi-store Support**: Isolated caching per store\r\n- 🔒 **Secure Isolation**: Store-specific token hashing prevents data leakage\r\n\r\n## 📋 Requirements\r\n\r\n- Python 3.7+\r\n- Shopify store with products\r\n- Shopify private app with API access\r\n- Internet connection for image processing\r\n\r\n## 🛠️ Technical Details\r\n\r\n- **CLIP Model**: ViT-B/32 for image embeddings\r\n- **Similarity Metric**: Cosine similarity\r\n- **Image Processing**: PIL for image handling\r\n- **API Integration**: Shopify Python API\r\n- **UI Framework**: Streamlit with custom styling\r\n- **Backend API**: FastAPI with async support and comprehensive endpoints\r\n- **Storage**: Pickle-based local storage with numpy array serialization\r\n- **Caching**: Smart change detection with MD5 hashing\r\n- **Concurrency**: ThreadPoolExecutor for parallel image processing\r\n- **Architecture**: Microservices with FastAPI backend + Streamlit frontend\r\n- **Monitoring**: Real-time resource usage and performance metrics\r\n\r\n## 🔒 Security\r\n\r\n- Access tokens are stored securely in session state\r\n- No credentials are saved to disk\r\n- HTTPS connections for all API calls\r\n- Store isolation with token hashing\r\n- Secure file naming for cache storage\r\n\r\n## 📝 Usage Tips\r\n\r\n- **Better Results**: Use high-quality, clear product images for queries\r\n- **Product Types**: The app works best with similar product categories\r\n- **Performance**: First run may take longer as it embeds all products\r\n- **Caching**: Results are cached for faster subsequent searches\r\n- **Storage Management**: Monitor cache size and clear old caches periodically\r\n- **Multi-store**: Use the API server for searching across multiple stores\r\n- **Cache Efficiency**: Check cache info to monitor embedding efficiency\r\n\r\n## 🚀 API Endpoints\r\n\r\n### Search Endpoints\r\n- `POST /search` - Search products in a specific store\r\n- `POST /search/multi-store` - Search across multiple stores\r\n\r\n### Cache Management\r\n- `GET /cache/{shop_url}/info` - Get cache information for a store\r\n- `DELETE /cache/{shop_url}` - Clear cache for a specific store\r\n- `POST /cache/{shop_url}/refresh` - Force refresh cache for a store\r\n- `GET /storage/info` - Get detailed storage information\r\n- `DELETE /storage/clear` - Clear all storage files\r\n\r\n### Monitoring \u0026 Health\r\n- `GET /health` - API health check\r\n- `GET /resources` - Resource usage information\r\n- `GET /stores/validate` - Validate store isolation\r\n- `GET /config` - Get API configuration\r\n\r\n## 📊 Performance Monitoring\r\n\r\nMonitor these key metrics:\r\n- **Cache Hit Rate**: Ratio of cached vs total products\r\n- **Processing Time**: Time to embed new/updated products\r\n- **Storage Usage**: Disk space used by cache files\r\n- **Memory Usage**: RAM usage during operations\r\n- **API Efficiency**: Number of Shopify API calls made\r\n- **Store Isolation**: Validation of secure data separation\r\n\r\n## 🧪 Testing \u0026 Examples\r\n\r\n### Test Shopify Credentials\r\n```bash\r\npython test_shopify_auth.py\r\n```\r\nTest your Shopify API credentials before using the main application.\r\n\r\n### Client Example\r\n```bash\r\npython client_example.py\r\n```\r\nDemonstrates API usage with example store configurations.\r\n\r\n### Storage Demo\r\n```bash\r\npython storage_demo.py\r\n```\r\nShows local storage features, cache management, and monitoring.\r\n\r\n## 🔧 Troubleshooting\r\n\r\n### Shopify API Authentication Issues\r\n\r\nIf you get a \"401: Invalid API key or access token\" error:\r\n\r\n1. **Verify App Type**: Make sure you created a **Private App**, not a Public App\r\n2. **Check Installation**: Ensure you clicked \"Install app\" after creating the app\r\n3. **Verify Permissions**: Confirm `read_products` and `read_product_listings` are enabled\r\n4. **Use Correct Token**: Use the **Admin API access token**, not the API key\r\n5. **Check Shop URL**: Use format `your-store.myshopify.com` (without https://)\r\n6. **Test Credentials**: Run `python test_shopify_auth.py` to verify your setup\r\n\r\n### Common Error Messages\r\n\r\n- **\"Invalid API key or access token\"**: Check your access token and app installation\r\n- **\"No product embeddings found\"**: Ensure your store has products with images\r\n- **\"Shopify API error\"**: Verify your shop URL format and permissions\r\n\r\n## 🤝 Contributing\r\n\r\nFeel free to submit issues and enhancement requests!\r\n\r\n## 📄 License\r\n\r\nThis project is open source and available under the MIT License. \r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhasnainmumtaz%2Fimagemania","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhasnainmumtaz%2Fimagemania","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhasnainmumtaz%2Fimagemania/lists"}