Merge github code to hugging face

.gitattributes

@@ -1,36 +1,36 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
-public/heroImage.png filter=lfs diff=lfs merge=lfs -text
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text
+public/heroImage.png filter=lfs diff=lfs merge=lfs -text

README.md

@@ -1,57 +1,132 @@
----
-title: Photographer's Archive
-emoji: 📷
-colorFrom: indigo
-colorTo: purple
-sdk: gradio
-sdk_version: 6.18.0
-python_version: '3.12'
-app_file: app.py
-pinned: false
-license: apache-2.0
-tags:
-- backyard-ai
-- build-small
-- vision-language-model
-- image-search
-- local-first
-short_description: Local-first photo search powered by MiniCPM-V-4.6
----
+---
+title: ShutterSearch
+emoji: 📷
+colorFrom: indigo
+colorTo: purple
+sdk: gradio
+sdk_version: 6.18.0
+python_version: '3.12'
+app_file: app.py
+pinned: false
+license: apache-2.0
+tags:
+  - backyard-ai
+  - openbmb
+  - modal-labs
+  - minicpm
+  - build-small
+  - vision-language-model
+  - image-search
+short_description: Local-first photo search powered by MiniCPM-V-4.6
+fullWidth: true
+---
+# 📷 ShutterSearch — Intelligent Photo Archive
 
-# Photographer's 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.
 
-A local-first, privacy-preserving photo search app for photographers. Built for the Hugging Face [Build Small](https://huggingface.co/build-small) hackathon — **Backyard AI** track.
+---
 
-## What it does
+## 🏆 Hackathon Submission Details
 
-1. **Ingest** — Point the app at a local folder of photos. A small Vision-Language Model (MiniCPM-V-4.6, ≤7B params) runs entirely on your machine and generates rich captions describing objects, lighting, mood, and composition.
-2. **Search** — Type a plain-English query (e.g. "golden hour portrait with soft bokeh") and instantly retrieve the most relevant photos ranked by semantic similarity.
+This project was built for the **Hugging Face [Build Small](https://huggingface.co/build-small) Hackathon** under the following tracks:
 
-No images are uploaded to any external service. Everything stays on your hardware.
+* **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.
 
-## Demo
+---
 
-> 📹 Demo video: _link TBD_  
-> 🐦 Social post: _link TBD_
+## 👥 The Team
 
-## Running locally
+* **Subash-Lamichhane** ([@Subash-Lamichhane](https://huggingface.co/Subash-Lamichhane))
+* **najus** ([@najus](https://huggingface.co/najus))
+* **Swikar Gautam** ([@SwikarG](https://huggingface.co/SwikarG))
 
-```bash
-pip install -r requirements.txt
-python app.py
-```
+---
 
-The first run will download MiniCPM-V-4.6 (~8 GB). Subsequent runs use cached weights and work fully offline.
+## ✅ Pre-Flight Validation Checklist
 
-## Tech stack
+This section verifies compliance with the submission requirements of the *Build Small* Hackathon:
 
-| Component | Library |
-|-----------|---------|
-| VLM | `openbmb/MiniCPM-V-4.6` via 🤗 Transformers |
-| Semantic search | `sentence-transformers/all-MiniLM-L6-v2` |
-| UI | Gradio 5 |
-| Caption store | Local `captions.json` |
+- [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.
 
-## Privacy
+---
 
-All model inference happens locally. No image pixels, captions, or metadata leave your machine.
+## 📹 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.

app.py

@@ -144,9 +144,9 @@ from ui.about import render_about
 with open("style.css", "r") as f:
     custom_css = f.read()
 
-with gr.Blocks(css=custom_css) as demo:
+with gr.Blocks(css=custom_css, title="ShutterSearch — Photo Archive", fill_height=False) as demo:
     # 1. Render Navigation Sidebar
-    nav_btns, stats_label = render_sidebar()
+    nav_btns = render_sidebar()
 
     # 2. Render Main Content Container Pages
     with gr.Column(elem_classes="main-content"):
@@ -215,9 +215,6 @@ with gr.Blocks(css=custom_css) as demo:
         fn=run_ingest, 
         inputs=[upload, coll_dropdown, use_new_coll, new_coll_name], 
         outputs=[ingest_status, caption_table, coll_dropdown]
-    ).then(
-        fn=lambda: f"Total Photos: {entry_count()}", 
-        outputs=stats_label
     )
 
     # --- Shared Selection Utility Functions ---

caption_store.py

@@ -48,6 +48,7 @@ def _try_parse_json(raw: str) -> dict | None:
 
 
 def flatten_metadata(meta: dict) -> str:
+    """Convert structured JSON metadata into a rich text string for embedding."""
     parts = []
 
     if meta.get("summary"):

compress_image.py

@@ -0,0 +1,91 @@
+import os
+from pathlib import Path
+from PIL import Image, ImageOps
+
+# --- CONFIGURATION ---
+INPUT_FOLDER = r"C:\Users\Dell\Desktop\gradio\weddingimages-hackathon\WeddingImagesHAck"   # Replace with your input folder path
+OUTPUT_FOLDER = r"C:\Users\Dell\Desktop\gradio\weddingimages-hackathon-compressed"   # Replace with where you want to save them
+MAX_DIMENSION = 2048                            # Maximum width or height in pixels
+QUALITY = 85                                    # Image quality (1-95). 85 is highly optimized
+# ---------------------
+
+SUPPORTED_EXTENSIONS = {'.jpg', '.jpeg', '.png', '.webp', '.tiff'}
+
+def compress_image(file_path: Path, output_path: Path, max_dim: int, quality: int):
+    try:
+        with Image.open(file_path) as img:
+            # 1. Correct image rotation from camera EXIF data automatically
+            img = ImageOps.exif_transpose(img)
+            
+            # 2. Calculate new dimensions preserving the aspect ratio
+            width, height = img.size
+            if max(width, height) > max_dim:
+                if width > height:
+                    new_width = max_dim
+                    new_height = int((max_dim / width) * height)
+                else:
+                    new_height = max_dim
+                    new_width = int((max_dim / height) * width)
+                
+                img = img.resize((new_width, new_height), Image.Resampling.LANCZOS)
+            
+            # 3. Handle transparency channels if saving formats change
+            ext = file_path.suffix.lower()
+            if ext in {'.jpg', '.jpeg'}:
+                # Force RGB conversion if image has an alpha channel (like transparent PNG to JPG conversion)
+                if img.mode in ('RGBA', 'LA'):
+                    img = img.convert('RGB')
+                img.save(output_path, "JPEG", quality=quality, optimize=True)
+            elif ext == '.webp':
+                img.save(output_path, "WEBP", quality=quality, optimize=True)
+            elif ext == '.png':
+                # PNG is lossless, so we compress the file storage space directly
+                img.save(output_path, "PNG", optimize=True)
+            else:
+                img.save(output_path, img.format, optimize=True)
+            
+            return True
+    except Exception as e:
+        print(f"Failed to process {file_path.name}: {e}")
+        return False
+
+def main():
+    input_path = Path(INPUT_FOLDER)
+    output_path = Path(OUTPUT_FOLDER)
+    
+    if not input_path.exists():
+        print(f"Error: The input folder '{INPUT_FOLDER}' does not exist.")
+        return
+        
+    output_path.mkdir(parents=True, exist_ok=True)
+    
+    files = [f for f in input_path.iterdir() if f.suffix.lower() in SUPPORTED_EXTENSIONS]
+    total_files = len(files)
+    
+    if total_files == 0:
+        print("No supported images found in the input folder.")
+        return
+        
+    print(f"Starting compression of {total_files} images...")
+    successful = 0
+    
+    for idx, file in enumerate(files, 1):
+        out_file = output_path / file.name
+        
+        # Check original file size
+        orig_size_mb = file.stat().st_size / (1024 * 1024)
+        
+        success = compress_image(file, out_file, MAX_DIMENSION, QUALITY)
+        
+        if success:
+            successful += 1
+            new_size_mb = out_file.stat().st_size / (1024 * 1024)
+            reduction = ((orig_size_mb - new_size_mb) / orig_size_mb) * 100
+            print(f"[{idx}/{total_files}] Compressed: {file.name} "
+                  f"({orig_size_mb:.2f}MB -> {new_size_mb:.2f}MB | -{reduction:.1f}%)")
+            
+    print(f"\nCompression complete! Successfully processed {successful}/{total_files} images.")
+    print(f"Your optimized files are located in: {OUTPUT_FOLDER}")
+
+if __name__ == "__main__":
+    main()

logic.py

@@ -318,17 +318,19 @@ def run_search(query: str, collection: str = "All"):
     
     col_filter = None if collection == "All" else collection
     results = search(query.strip(), collection=col_filter)
-    
-    if not results:
+
+    CUSTOM_THRESHOLD = 0.60 
+    filtered_results = [r for r in results if r.get("score", 0) >= CUSTOM_THRESHOLD]
+    if not filtered_results:
         return [], [], f"Zero matches in database for target {collection} (Threshold constraint: {MIN_RELEVANCE})."
         
-    original_paths = [r["path"] for r in results]
+    original_paths = [r["path"] for r in filtered_results]
     gallery_items = []
-    for r in results:
+    for r in filtered_results:
         thumb = get_thumbnail_path(r["path"])
         gallery_items.append((thumb, os.path.basename(r["path"])))
         
-    return gallery_items, original_paths, f"Found {len(results)} search matches."
+    return gallery_items, original_paths, f"Found {len(filtered_results)} search matches."
 
 
 def load_collections_view(collection_name):

requirements.txt

@@ -1,5 +1,86 @@
-gradio>=5.40.0
-sentence-transformers>=3.0.0
-modal>=0.73.0
-numpy
-Pillow
+aiohappyeyeballs==2.6.2
+aiohttp==3.14.1
+aiosignal==1.4.0
+annotated-doc==0.0.4
+annotated-types==0.7.0
+anyio==4.13.0
+attrs==26.1.0
+audioop-lts==0.2.2
+brotli==1.2.0
+cbor2==6.1.2
+certifi==2026.5.20
+click==8.4.1
+colorama==0.4.6
+fastapi==0.137.1
+filelock==3.29.4
+frozenlist==1.8.0
+fsspec==2026.4.0
+gradio==6.18.0
+gradio_client==2.5.0
+groovy==0.1.2
+grpclib==0.4.9
+h11==0.16.0
+h2==4.3.0
+hf-gradio==0.4.1
+hf-xet==1.5.1
+hpack==4.1.0
+httpcore==1.0.9
+httpx==0.28.1
+huggingface_hub==1.19.0
+hyperframe==6.1.0
+idna==3.18
+Jinja2==3.1.6
+joblib==1.5.3
+markdown-it-py==4.2.0
+MarkupSafe==3.0.3
+mdurl==0.1.2
+modal==1.5.0
+mpmath==1.3.0
+multidict==6.7.1
+narwhals==2.22.1
+networkx==3.6.1
+numpy==2.4.6
+orjson==3.11.9
+packaging==26.2
+pandas==3.0.3
+pillow==12.2.0
+propcache==0.5.2
+protobuf==6.33.6
+pydantic==2.13.4
+pydantic_core==2.46.4
+pydub==0.25.1
+Pygments==2.20.0
+python-dateutil==2.9.0.post0
+python-multipart==0.0.32
+pytz==2026.2
+PyYAML==6.0.3
+regex==2026.5.9
+rich==15.0.0
+safehttpx==0.1.7
+safetensors==0.8.0
+scikit-learn==1.9.0
+scipy==1.17.1
+semantic-version==2.10.0
+sentence-transformers==5.5.1
+setuptools==81.0.0
+shellingham==1.5.4
+six==1.17.0
+starlette==1.3.1
+sympy==1.14.0
+synchronicity==0.12.3
+threadpoolctl==3.6.0
+tokenizers==0.22.2
+toml==0.10.2
+tomlkit==0.14.0
+torch==2.12.0
+tqdm==4.68.2
+transformers==5.12.0
+typer==0.25.1
+types-certifi==2021.10.8.3
+types-toml==0.10.8.20260518
+typing-inspection==0.4.2
+typing_extensions==4.15.0
+tzdata==2026.2
+uvicorn==0.49.0
+watchfiles==1.2.0
+yarl==1.24.2

search.py

@@ -13,11 +13,11 @@ from caption_store import all_entries
 _embed_model: SentenceTransformer | None = None
 _MODEL_NAME = "BAAI/bge-base-en-v1.5"  # stronger than MiniLM
 
-MIN_RELEVANCE = 0.55
+MIN_RELEVANCE = 0.6
 TOP_K = 20
 
 # Weight given to keyword boost relative to semantic score (0–1 additive)
-KEYWORD_BOOST = 0.3
+KEYWORD_BOOST = 0.25
 
 
 def _get_embed_model() -> SentenceTransformer:
@@ -33,6 +33,10 @@ def _query_tokens(query: str) -> list[str]:
 
 
 def _keyword_score(query_tokens: list[str], search_text: str, raw_caption: str) -> float:
+    """
+    Boost score if query tokens appear in high-signal fields (attire, tags, summary).
+    Returns a value in [0, 1].
+    """
     if not query_tokens:
         return 0.0