Merge pull request #1 from Shaan-alpha/showcase-readiness-fixes

Showcase-readiness hardening: offline UI, reliable install, upload safety, screenshots

Author: Shaan-alpha

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -16,7 +16,7 @@ body:
       options:
         - label: I have verified that OpenCV ONNX models (`face_detection_yunet_2023mar.onnx` and `face_recognition_sface_2021dec.onnx`) are present in `models/`.
           required: true
-        - label: I am using Python 3.8 or higher.
+        - label: I am using Python 3.11 or higher.
           required: true
   - type: dropdown
     id: os

.gitignore

@@ -11,6 +11,12 @@ __pycache__/
 
 # ── Data (local state) ───────────────────────────────────────
 data/
+instance/
+
+# ── Node / Tailwind build tooling ────────────────────────────
+node_modules/
+# NOTE: the compiled face_sort/app/static/css/tailwind.css IS committed so
+# Python-only users don't need Node; rebuild it with `npm run build:css`.
 
 # ── Secrets ───────────────────────────────────────────────────
 .env

.vscode/tasks.json

@@ -12,7 +12,7 @@
         {
             "label": "Face Sort Studio: Run",
             "type": "shell",
-            "command": "python",
+            "command": "${workspaceFolder}\\venv\\Scripts\\python.exe",
             "args": ["run.py"],
             "group": "build",
             "presentation": { "reveal": "always", "panel": "new" },
@@ -22,7 +22,7 @@
         {
             "label": "Face Sort Studio: Test",
             "type": "shell",
-            "command": "python",
+            "command": "${workspaceFolder}\\venv\\Scripts\\python.exe",
             "args": ["-m", "pytest", "tests/", "-v"],
             "group": "test",
             "presentation": { "reveal": "always", "panel": "new" }

MANIFEST.in

@@ -1,3 +1,4 @@
 include VERSION
+include requirements.txt
 recursive-include face_sort/app/static *
 recursive-include face_sort/app/templates *

README.md

@@ -4,6 +4,16 @@
 
 **Local deep-learning photo organization — powered by face recognition.**
 
+<p align="center">
+  <img src="docs/assets/ui-create-light.png" alt="Face Sort Studio — start a sorting job" width="760" />
+</p>
+<p align="center">
+  <img src="docs/assets/ui-create-dark.png" alt="Dark mode" width="380" />
+  <img src="docs/assets/ui-dashboard-light.png" alt="Analytics dashboard" width="380" />
+  <br />
+  <em>Polished, fully offline browser UI — with a built-in dark mode and an analytics dashboard.</em>
+</p>
+
 Face Sort Studio is a privacy-first tool that scans your photo gallery and automatically organizes images into folders based on the people in them. Using high-performance deep learning models, it detects every face and creates unique identity embeddings to match targets with precision—all while remaining 100% offline.
 
 Everything runs locally on your hardware. No cloud uploads, no API keys, and no data leaves your machine.
@@ -63,6 +73,21 @@ If you want to run the app without installing Python or any libraries, you can b
 
 ## 🚀 Quick Start (Local Setup)
 
+**Windows, in three steps** (full setup options are in [Setup](#setup) below):
+
+```powershell
+git clone https://github.com/Shaan-alpha/face-sort-studio.git
+cd face-sort-studio
+powershell -ExecutionPolicy Bypass -File .\scripts\setup.ps1   # creates a venv + downloads models
+powershell -ExecutionPolicy Bypass -File .\scripts\run.ps1     # starts the app + opens your browser
+```
+
+> **First run downloads ~37 MB of AI models** (a one-time step). After that, everything runs fully offline.
+
+**macOS / Linux:** the Flask core is pure Python — see the cross-platform steps in [Setup → Option C](#setup).
+
+---
+
 ## Project Structure
 
 ```
@@ -105,8 +130,7 @@ face-sort-studio/
 │
 └── .vscode/
     ├── tasks.json                  # Setup / Run / Test tasks
-    ├── launch.json                 # Debug profile
-    └── settings.json               # Python interpreter config
+    └── launch.json                 # Debug profile
 ```
 
 ---
@@ -180,7 +204,7 @@ Photos are copied (never moved) into the output folders.
 ## Prerequisites
 
 - **Python 3.11+** — [python.org](https://python.org/downloads)
-- **Windows** — scripts are PowerShell; the core app runs on any OS
+- **Primary support: Windows** — the automation scripts and portable EXE are Windows-only. The Flask core is pure Python and runs on macOS/Linux via the manual steps ([Option C](#setup)); the system-tray + auto-open-browser launcher (`run.py`) is a Windows-desktop convenience, while `face-sort` is the cross-platform headless command.
 - **Tailscale** (optional) — only needed for the public sharing flow
 
 ---
@@ -353,7 +377,6 @@ These are planned or suggested improvements for future versions:
 - **Person renaming** — rename "Person_01" to actual names in the UI
 - **Face bounding box preview** — overlay detected faces on image thumbnails
 - **Batch operations** — re-run a previous job with different settings
-- **Dark mode** — toggle between light and dark themes
 
 ### Medium-Term
 - **TensorFlow integration** — swap OpenCV models for TensorFlow-based detection/recognition for improved accuracy on challenging photos
@@ -377,7 +400,7 @@ These are planned or suggested improvements for future versions:
 Flask's synchronous model is simpler to reason about for a local desktop-style app. Background jobs run in threads. The template engine (Jinja2) is built in. For a single-user local tool, Flask is the right balance of simplicity and power.
 
 **Why OpenCV DNN instead of TensorFlow?**
-The OpenCV models (YuNet + SFace) are tiny ONNX files (~2 MB total) that run on CPU without CUDA. They provide excellent accuracy for face detection and recognition. TensorFlow integration is on the roadmap for users who want to push accuracy further on difficult photos.
+The OpenCV models (YuNet + SFace) are compact ONNX files (~37 MB total, downloaded once on first run) that run on CPU without CUDA. They provide excellent accuracy for face detection and recognition. TensorFlow integration is on the roadmap for users who want to push accuracy further on difficult photos.
 
 **Why SQLite?**
 Zero configuration, no separate database server, single file. Perfect for a local app. The SQLAlchemy ORM means swapping to PostgreSQL or Azure SQL later requires only changing the connection string in `config.py`.

docs/assets/ui-create-dark.png

@@ -13,16 +13,22 @@
 <body>
     <div class="page-shell">
         <header class="hero">
-            <p class="eyebrow">v2.1.1 Release</p>
+            <p class="eyebrow">v2.1.4 Release</p>
             <h1>Face Sort Studio</h1>
             <p class="hero-copy">
-                Professional local photo organization. Sort galleries by face with 
+                Professional local photo organization. Sort galleries by face with
                 high-performance deep learning models and a polished browser UI—all 100% offline.
             </p>
             <div class="hero-actions">
-                <a class="button button-primary" href="#setup">Local Setup</a>
+                <a class="button button-primary" href="https://github.com/Shaan-alpha/face-sort-studio">View on GitHub</a>
+                <a class="button button-secondary" href="#setup">Local Setup</a>
                 <a class="button button-secondary" href="#hosting">Hosting Notes</a>
             </div>
+            <img
+                src="./assets/ui-create-light.png"
+                alt="Face Sort Studio browser interface"
+                style="margin-top:2rem;width:100%;max-width:880px;height:auto;border-radius:16px;box-shadow:0 12px 40px rgba(0,0,0,0.18);"
+            />
         </header>
 
         <main>
@@ -76,7 +82,7 @@ <h2>Why Pages Still Helps</h2>
             <section id="setup" class="card card-wide">
                 <h2>Run It Locally</h2>
                 <ol>
-                    <li>Install Python 3.13 or newer.</li>
+                    <li>Install Python 3.11 or newer.</li>
                     <li>Install dependencies with <code>python -m pip install -r requirements.txt</code>.</li>
                     <li>Create the data folders or run <code>scripts/setup.ps1</code>.</li>
                     <li>Start the app with <code>python run.py</code> or <code>scripts/run.ps1</code>.</li>

docs/assets/ui-create-light.png

@@ -3,6 +3,10 @@
 ==============================
 Downloads YuNet and SFace ONNX models from the OpenCV zoo
 if they aren't already present in data/models/.
+
+Downloads are written to a temporary ``*.part`` file and only renamed into
+place once they pass a minimum-size check, so an interrupted download can
+never leave a truncated file that later fails to load.
 """
 
 import os
@@ -20,21 +24,63 @@
     ),
 }
 
+# Minimum expected sizes (bytes) — used to detect truncated/partial files.
+# Actual sizes: YuNet ~0.23 MB, SFace ~36.9 MB. Floors are set well below
+# the real sizes so a complete file always passes but a truncated one fails.
+MODEL_MIN_BYTES = {
+    "face_detection_yunet_2023mar.onnx": 150_000,
+    "face_recognition_sface_2021dec.onnx": 30_000_000,
+}
+
+
+def _is_complete(path: str, filename: str) -> bool:
+    """A model file is considered complete only if it meets its size floor."""
+    if not os.path.exists(path):
+        return False
+    min_bytes = MODEL_MIN_BYTES.get(filename, 1)
+    return os.path.getsize(path) >= min_bytes
+
 
 def ensure_models_exist(models_dir: str) -> None:
-    """Download any missing model files into *models_dir*."""
+    """Download any missing or incomplete model files into *models_dir*."""
     os.makedirs(models_dir, exist_ok=True)
 
     for filename, url in MODEL_URLS.items():
         dest = os.path.join(models_dir, filename)
-        if os.path.exists(dest):
+
+        if _is_complete(dest, filename):
             continue
+
+        # Remove a stale/truncated file left by a previous interrupted run.
+        if os.path.exists(dest):
+            print(
+                f"[bootstrap] {filename} looks incomplete — re-downloading …",
+                file=sys.stderr,
+            )
+            try:
+                os.remove(dest)
+            except OSError:
+                pass
+
+        tmp = dest + ".part"
         print(f"[bootstrap] Downloading {filename} …")
         try:
-            urllib.request.urlretrieve(url, dest)
+            urllib.request.urlretrieve(url, tmp)
+            if not _is_complete(tmp, filename):
+                raise IOError(
+                    f"downloaded file is smaller than expected "
+                    f"({os.path.getsize(tmp)} bytes)"
+                )
+            os.replace(tmp, dest)  # atomic rename — only a complete file lands
             size_mb = os.path.getsize(dest) / (1024 * 1024)
             print(f"[bootstrap] Saved {filename} ({size_mb:.1f} MB)")
         except Exception as exc:
+            # Clean up the partial download so the next run retries cleanly.
+            if os.path.exists(tmp):
+                try:
+                    os.remove(tmp)
+                except OSError:
+                    pass
             print(
                 f"[bootstrap] WARNING — could not download {filename}: {exc}",
                 file=sys.stderr,