README.md

---
title: ShutterSearch
emoji: 📷
colorFrom: indigo
colorTo: purple
sdk: gradio
sdk_version: 6.18.0
python_version: 3.13.3
app_file: app.py
pinned: false
license: apache-2.0
tags:
  - track:backyard-ai
  - sponsor:openbmb
  - sponsor:modal-labs
  - sponsor:minicpm
  
short_description: Local-first photo search powered by MiniCPM-V-4.6
fullWidth: true
---
# 📷 ShutterSearch — Intelligent Photo Archive

ShutterSearch is a local-first, privacy-preserving semantic search and photography archive manager. It turns unstructured folders of raw photographs into organized, natural-language searchable catalogs without uploading your private master files to any third-party cloud.

---

## 🏆 Hackathon Submission Details

This project was built for the **Hugging Face [Build Small](https://huggingface.co/build-small) Hackathon** under the following tracks:

* **Primary Track:** Backyard AI (Local-first / Offline track)
* **Sponsor Award Compatibility:**
  * **OpenBMB Awards:** Powered by the flagship lightweight visual-understanding model **MiniCPM-V-4.6** (≤7B params) for high-performance visual scene parsing.
  * **Modal Labs Awards:** Seamlessly integrates with **Modal Labs** serverless GPU compute infrastructure to scale visual ingestion pipelines off-site, returning detailed annotations back to your local cache.

---

## 👥 The Team

* **Subash-Lamichhane** ([@Subash-Lamichhane](https://huggingface.co/Subash-Lamichhane))
* **najus** ([@najus](https://huggingface.co/najus))
* **Swikar Gautam** ([@SwikarG](https://huggingface.co/SwikarG))

---

## ✅ Pre-Flight Validation Checklist

This section verifies compliance with the submission requirements of the *Build Small* Hackathon:

- [x] **Stay under 32B:** The core Vision Language Model used is **MiniCPM-V-4.6** (8B/7B class model), and the text embedding model is **all-MiniLM-L6-v2** (22M parameters). Combined, the total parameter footprint is less than 9B parameters, safely under the 32B limit.
- [x] **Ship a Gradio App:** Fully deployed as a native Gradio Application Space within the official Build Small organization on Hugging Face.
- [x] **Record a Demo:** A visual walkthrough demonstrating local indexing, search, selection, and download is linked below.
- [x] **Post It:** A public showcase of ShutterSearch has been published on social media.
- [x] **Mind the GPU Limit:** Fully self-contained. Local execution relies on local memory and GPU resources, while our offloaded inference operates within standard boundaries.

---

## 📹 Presentation & Links

* **Demo Video:** *https://www.youtube.com/watch?v=aTLrOBhSRwU&feature=youtu.be*
* **Social Media Post:** *https://x.com/SUJANKOIRA96725/status/2066583761597436253*

---

## 💡 The Problem & The Backyard Solution

Photographers manage massive directories of RAW/JPEG images across external drives. Managing them typically requires sacrificing ownership by uploading them to third-party image hosts, manually tagging files, or enduring slow loading speeds when viewing high-resolution imagery.

**ShutterSearch solves this on your terms:**
* **Local Caching & Privacy:** Your original master image files never leave your machine.
* **Dual-Inference Pipeline (Local & Modal Labs):** Run inference fully offline on your own local GPU, or scale up your pipeline using **Modal Labs** serverless containers to process large batches on cloud-based H100s, caching the resulting semantic captions back locally.
* **On-the-Fly WebP Thumbnails:** Avoid high-resolution display lag. ShutterSearch caches images as lightweight WebP thumbnails (300px max, 70% quality) for smooth, lag-free visual scrolling.
* **Multi-Select Bulk Export:** Select multiple images (indicated visually by inline `✅` overlay badges) across Search results or Collections to package and download high-resolution originals in a structured ZIP.

---

## 🛠️ Tech Stack & Model Selection

| Component | Technology | Role |
|-----------|------------|------|
| **Core VLM** | `openbmb/MiniCPM-V-4.6` | Scene parsing, composition classification, and tagging |
| **Semantic Search** | `all-MiniLM-L6-v2` | High-dimensional text-to-image semantic index maps |
| **Inference Scaling** | `Modal Labs` (Optional) | Serverless GPU execution for scalable batch parsing |
| **Frontend UI** | Gradio | Dark-workspace layout and interface state engine |
| **Thumbnail Optimizer** | `Pillow` (PIL) | Compresses files to WebP (300px, 70% quality) |
| **Local Database** | Flat JSON Storage | No bulky setups; simple, human-readable data mapping |

### Why MiniCPM-V-4.6?
We chose OpenBMB’s MiniCPM-V-4.6 because it matches or outperforms larger models (like Claude 3 Opus and GPT-4V) in optical character recognition (OCR), layout understanding, and fine-grained visual reasoning while remaining compact enough to run on standard consumer-grade workstations.

---

## 📦 Setting Up Locally

### Prerequisites
Make sure your environment has Python 3.10+ and a GPU with at least 8GB VRAM (or a configured CPU environment).

1. **Clone the repository:**
   ```bash
   git clone https://huggingface.co/spaces/build-small-hackathon/ShutterSearch
   cd ShutterSearch
   ```

2. **Set up a virtual environment and activate it:**
   ```bash
   python -m venv venv
   # On Windows:
   .\venv\Scripts\activate
   # On macOS/Linux:
   source venv/bin/activate
   ```

3. **Install dependencies:**
   ```bash
   pip install -r requirements.txt
   ```
4. ***Setup modal***
    ```bash
    modal setup
    modal deploy modal_caption.py
    ```
5. **Launch the application:**
   ```bash
   python app.py
   ```

---

## 🏆 Hackathon Details
Developed for the Hugging Face "Build Small" Hackathon (Backyard AI / OpenBMB Tracks). Focused on model-efficiency, local UI caching pipelines, high-fidelity source protection, and a professional workspace interface.