Upload deployment-ready Space app

.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+out/
+.venv/
+.env
+.DS_Store

Dockerfile

@@ -0,0 +1,25 @@
+FROM python:3.10-slim
+
+RUN useradd -m -u 1000 user
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ffmpeg \
+    git \
+    libgl1 \
+    libglib2.0-0 \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /home/user/app
+
+COPY --chown=user requirements.txt ./
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -r requirements.txt
+
+COPY --chown=user . .
+
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    PYTHONUNBUFFERED=1
+
+CMD ["python", "app.py"]

README.md

@@ -1,10 +1,64 @@
 ---
-title: FuzzyPSI Hamming
-emoji: 💻
-colorFrom: purple
-colorTo: pink
+title: FuzzyPSI-hamming
+emoji: 🔐
+colorFrom: indigo
+colorTo: blue
 sdk: docker
+app_port: 7860
 pinned: false
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# FuzzyPSI-hamming: Deployment-Oriented FPSI Demo
+
+This Hugging Face Space presents **FuzzyPSI-hamming** as a reviewer-facing, deployment-oriented demo for privacy-preserving fuzzy private set intersection over Hamming distance.
+
+## What this Space demonstrates
+
+- **Image-driven query workflow** for a public demo frontend
+- **Binary-code matching** derived from the Hamming-FPSI pipeline
+- **E-LSH candidate generation + exact verification story** exposed in a product-style interface
+- **Protocol metrics panels** showing threshold, communication, latency, and Gao-feasibility information
+- **Dual backend modes**:
+  - **Simulation mode** for robust public interaction
+  - **Optional full protocol mode** when native FPSI binaries are configured
+
+## Reviewer-facing positioning
+
+This Space is designed to show the engineering effort beyond the paper artifact:
+
+1. turning the protocol into an interactive web application;
+2. bridging uploaded images to binary-code matching;
+3. exposing system metrics and deployment status in a usable UI;
+4. organizing the project as an isolated Hugging Face deployment target.
+
+The current public release is **image-first**. The code layout also includes a path for short-video analysis, but the first deployment focuses on making the image path reliable.
+
+## Demo data policy
+
+The public demo uses a **fixed LFW-derived gallery** so reviewers can test the system in a stable and reproducible way. The deployment project is intentionally isolated from the main research artifact repository.
+
+## Repository structure
+
+```text
+.
+├── app.py
+├── Dockerfile
+├── requirements.txt
+├── src/
+│   ├── config.py
+│   ├── protocol/
+│   ├── pipeline/
+│   ├── data/
+│   └── ui/
+└── assets/
+    ├── gallery/
+    ├── examples/
+    └── videos/
+```
+
+## Notes
+
+- The protocol core is adapted into this Space as a separate deployment project.
+- Public demo mode prioritizes reliability and reviewer usability.
+- Full native protocol execution is exposed only when the deployment environment is provisioned for it.

app.py

@@ -0,0 +1,18 @@
+import os
+from pathlib import Path
+
+os.environ.setdefault("GRADIO_ANALYTICS_ENABLED", "False")
+
+from src.ui.components import build_app
+
+app = build_app()
+
+if __name__ == "__main__":
+    port = int(os.environ.get("GRADIO_SERVER_PORT", os.environ.get("PORT", "7860")))
+    project_root = Path(__file__).resolve().parent
+    app.launch(
+        server_name="0.0.0.0",
+        server_port=port,
+        allowed_paths=[str(project_root / "assets")],
+        show_api=True,
+    )

assets/examples/examples_manifest.json

@@ -0,0 +1,42 @@
+[
+  {
+    "person": "George_W_Bush",
+    "filename": "query_George_W_Bush_0002.jpg",
+    "path": "query_George_W_Bush_0002.jpg"
+  },
+  {
+    "person": "Colin_Powell",
+    "filename": "query_Colin_Powell_0002.jpg",
+    "path": "query_Colin_Powell_0002.jpg"
+  },
+  {
+    "person": "Tony_Blair",
+    "filename": "query_Tony_Blair_0002.jpg",
+    "path": "query_Tony_Blair_0002.jpg"
+  },
+  {
+    "person": "Donald_Rumsfeld",
+    "filename": "query_Donald_Rumsfeld_0002.jpg",
+    "path": "query_Donald_Rumsfeld_0002.jpg"
+  },
+  {
+    "person": "Gerhard_Schroeder",
+    "filename": "query_Gerhard_Schroeder_0002.jpg",
+    "path": "query_Gerhard_Schroeder_0002.jpg"
+  },
+  {
+    "person": "Ariel_Sharon",
+    "filename": "query_Ariel_Sharon_0002.jpg",
+    "path": "query_Ariel_Sharon_0002.jpg"
+  },
+  {
+    "person": "Hugo_Chavez",
+    "filename": "query_Hugo_Chavez_0002.jpg",
+    "path": "query_Hugo_Chavez_0002.jpg"
+  },
+  {
+    "person": "Junichiro_Koizumi",
+    "filename": "query_Junichiro_Koizumi_0002.jpg",
+    "path": "query_Junichiro_Koizumi_0002.jpg"
+  }
+]

assets/gallery/README.txt

@@ -0,0 +1 @@
+This directory stores the fixed LFW-derived reviewer gallery used by the public Hugging Face demo. The packaged gallery is intentionally small, explicit, and deployment-friendly.

assets/gallery/gallery_manifest.json

@@ -0,0 +1,58 @@
+[
+  {
+    "person": "George_W_Bush",
+    "gallery_filename": "George_W_Bush_0001.jpg",
+    "query_filename": "query_George_W_Bush_0002.jpg",
+    "gallery_path": "George_W_Bush_0001.jpg",
+    "query_path": "query_George_W_Bush_0002.jpg"
+  },
+  {
+    "person": "Colin_Powell",
+    "gallery_filename": "Colin_Powell_0001.jpg",
+    "query_filename": "query_Colin_Powell_0002.jpg",
+    "gallery_path": "Colin_Powell_0001.jpg",
+    "query_path": "query_Colin_Powell_0002.jpg"
+  },
+  {
+    "person": "Tony_Blair",
+    "gallery_filename": "Tony_Blair_0001.jpg",
+    "query_filename": "query_Tony_Blair_0002.jpg",
+    "gallery_path": "Tony_Blair_0001.jpg",
+    "query_path": "query_Tony_Blair_0002.jpg"
+  },
+  {
+    "person": "Donald_Rumsfeld",
+    "gallery_filename": "Donald_Rumsfeld_0001.jpg",
+    "query_filename": "query_Donald_Rumsfeld_0002.jpg",
+    "gallery_path": "Donald_Rumsfeld_0001.jpg",
+    "query_path": "query_Donald_Rumsfeld_0002.jpg"
+  },
+  {
+    "person": "Gerhard_Schroeder",
+    "gallery_filename": "Gerhard_Schroeder_0001.jpg",
+    "query_filename": "query_Gerhard_Schroeder_0002.jpg",
+    "gallery_path": "Gerhard_Schroeder_0001.jpg",
+    "query_path": "query_Gerhard_Schroeder_0002.jpg"
+  },
+  {
+    "person": "Ariel_Sharon",
+    "gallery_filename": "Ariel_Sharon_0001.jpg",
+    "query_filename": "query_Ariel_Sharon_0002.jpg",
+    "gallery_path": "Ariel_Sharon_0001.jpg",
+    "query_path": "query_Ariel_Sharon_0002.jpg"
+  },
+  {
+    "person": "Hugo_Chavez",
+    "gallery_filename": "Hugo_Chavez_0001.jpg",
+    "query_filename": "query_Hugo_Chavez_0002.jpg",
+    "gallery_path": "Hugo_Chavez_0001.jpg",
+    "query_path": "query_Hugo_Chavez_0002.jpg"
+  },
+  {
+    "person": "Junichiro_Koizumi",
+    "gallery_filename": "Junichiro_Koizumi_0001.jpg",
+    "query_filename": "query_Junichiro_Koizumi_0002.jpg",
+    "gallery_path": "Junichiro_Koizumi_0001.jpg",
+    "query_path": "query_Junichiro_Koizumi_0002.jpg"
+  }
+]

assets/gallery/lfw_demo_calibration.npz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f2311f8e9eaefc33c921a9df7d3110038fe8c94b63eead35cda248985fd9b726
+size 152062

assets/gallery/lfw_demo_gallery.npz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5e812c24e8c5c1ca3f2e026223736e95c8f74ba01273388d82a332b695cc2a90
+size 18526

assets/videos/README.txt

@@ -0,0 +1 @@
+Short uploaded video analysis is planned in the code layout but not enabled as the primary reviewer path in the first deployment. Place approved short demo clips in this directory if the video tab is activated later.

requirements.txt

@@ -0,0 +1,10 @@
+gradio>=4.44.0
+numpy>=1.24.0
+pandas>=2.0.0
+scikit-learn>=1.3.0
+Pillow>=10.0.0
+opencv-python-headless>=4.9.0.80
+facenet-pytorch>=2.6.0
+torch>=2.1.0
+torchvision>=0.16.0
+matplotlib>=3.7.0

src/__init__.py

@@ -0,0 +1 @@
+"""FuzzyPSI-hamming Hugging Face deployment package."""

src/config.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from pathlib import Path
+import os
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+ASSETS_DIR = PROJECT_ROOT / "assets"
+GALLERY_DIR = ASSETS_DIR / "gallery"
+EXAMPLES_DIR = ASSETS_DIR / "examples"
+VIDEOS_DIR = ASSETS_DIR / "videos"
+OUTPUT_DIR = PROJECT_ROOT / "out"
+OUTPUT_DIR.mkdir(exist_ok=True)
+
+SPACE_TITLE = "FuzzyPSI-hamming"
+SPACE_SUBTITLE = "Deployment-oriented demo for privacy-preserving fuzzy private set intersection over Hamming distance"
+
+DEFAULT_MODE = os.environ.get("FPSI_DEMO_MODE", "simulation")
+SUPPORTED_MODES = ("simulation", "full")
+
+DEFAULT_DIMENSIONS = (128, 256, 512)
+DEFAULT_DIM = 128
+DEFAULT_SECURITY_LAMBDA = 40
+DEFAULT_N_SENDER = 512
+DEFAULT_N_RECEIVER = 100
+DEFAULT_FRAME_SAMPLE_LIMIT = 8
+DEFAULT_VIDEO_SECONDS = 12
+
+LFW_FEATURES_PATH = os.environ.get("LFW_FEATURES_PATH", str(GALLERY_DIR / "lfw_demo_gallery.npz"))
+LFW_IMAGE_ROOT = os.environ.get("LFW_IMAGE_ROOT", "")
+
+FULL_PROTOCOL_ENABLED = os.environ.get("FPSI_ENABLE_FULL_PROTOCOL", "0") == "1"
+FULL_PROTOCOL_DIR = Path(os.environ.get("FPSI_PROTOCOL_ROOT", str(PROJECT_ROOT / "runtime")))
+FULL_PROTOCOL_BUILD_DIR = Path(os.environ.get("FPSI_PROTOCOL_BUILD_DIR", str(FULL_PROTOCOL_DIR / "build")))
+
+FACE_MODEL_DEVICE = os.environ.get("FPSI_FACE_DEVICE", "cpu")
+MATCH_THRESHOLD_MARGIN = float(os.environ.get("FPSI_THRESHOLD_MARGIN", "0.0"))

src/data/__init__.py

@@ -0,0 +1 @@
+"""Gallery and packaged asset loaders."""

src/data/gallery_store.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+from PIL import Image
+
+from src import config
+
+
+@dataclass
+class GalleryRecord:
+    person: str
+    gallery_filename: str
+    query_filename: str
+    gallery_path: str
+    query_path: str
+
+
+class DemoGallery:
+    def __init__(self) -> None:
+        gallery_npz = config.GALLERY_DIR / 'lfw_demo_gallery.npz'
+        manifest_path = config.GALLERY_DIR / 'gallery_manifest.json'
+        example_manifest_path = config.EXAMPLES_DIR / 'examples_manifest.json'
+
+        data = np.load(gallery_npz, allow_pickle=True)
+        self.features = data['features'].astype(np.float32)
+        self.people = data['persons']
+        self.filenames = data['filenames']
+
+        calibration_npz = config.GALLERY_DIR / 'lfw_demo_calibration.npz'
+        calibration = np.load(calibration_npz, allow_pickle=True)
+        self.calibration_features = calibration['features'].astype(np.float32)
+        self.calibration_people = calibration['persons']
+        self.calibration_filenames = calibration['filenames']
+
+        with open(manifest_path) as fh:
+            self.records = [GalleryRecord(**row) for row in json.load(fh)]
+        with open(example_manifest_path) as fh:
+            self.examples = json.load(fh)
+
+    def summary(self) -> dict[str, object]:
+        return {
+            'gallery_size': int(len(self.people)),
+            'calibration_size': int(len(self.calibration_people)),
+            'people': [str(x.person) for x in self.records],
+            'dimensions': int(self.features.shape[1]),
+        }
+
+    def example_choices(self) -> list[tuple[str, str]]:
+        return [(item['person'], str(config.EXAMPLES_DIR / item['filename'])) for item in self.examples]
+
+    def load_example_image(self, filename: str) -> Image.Image:
+        return Image.open(config.EXAMPLES_DIR / filename).convert('RGB')
+
+    def gallery_image_path(self, gallery_filename: str) -> Path:
+        return config.GALLERY_DIR / gallery_filename

src/pipeline/__init__.py

@@ -0,0 +1 @@
+"""Media preprocessing and embedding extraction."""

src/pipeline/image_pipeline.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+from PIL import Image, ImageOps, ImageStat
+import torch
+from facenet_pytorch import MTCNN, InceptionResnetV1
+
+from src import config
+
+
+@dataclass
+class ImageAnalysis:
+    face_detected: bool
+    embedding: np.ndarray
+    preview: Image.Image
+    notes: list[str]
+
+
+class ImagePipeline:
+    def __init__(self) -> None:
+        self.device = torch.device(config.FACE_MODEL_DEVICE if torch.cuda.is_available() and config.FACE_MODEL_DEVICE == 'cuda' else 'cpu')
+        self.mtcnn = MTCNN(image_size=160, margin=16, post_process=True, device=self.device)
+        self.resnet = InceptionResnetV1(pretrained='vggface2').eval().to(self.device)
+
+    def analyze(self, image: Image.Image | np.ndarray | str | Path) -> ImageAnalysis:
+        pil = self._to_pil(image)
+        pil = ImageOps.exif_transpose(pil).convert('RGB')
+        notes: list[str] = []
+
+        face = self.mtcnn(pil)
+        if face is None:
+            notes.append('No face detected; falling back to center crop for demo continuity.')
+            preview = ImageOps.fit(pil, (220, 220))
+            face = self.mtcnn(preview)
+            if face is None:
+                face = self._fallback_tensor(preview)
+                notes.append('Used RGB center-crop fallback embedding path.')
+                face_detected = False
+            else:
+                face_detected = True
+        else:
+            preview = ImageOps.fit(pil, (220, 220))
+            face_detected = True
+
+        with torch.no_grad():
+            embedding = self.resnet(face.unsqueeze(0).to(self.device)).cpu().numpy()[0].astype(np.float32)
+
+        brightness = float(sum(ImageStat.Stat(preview).mean) / 3.0)
+        notes.append(f'Average preview brightness: {brightness:.1f}')
+        notes.append(f'Embedding device: {self.device.type}')
+        return ImageAnalysis(face_detected=face_detected, embedding=embedding, preview=preview, notes=notes)
+
+    def _to_pil(self, image: Image.Image | np.ndarray | str | Path) -> Image.Image:
+        if isinstance(image, Image.Image):
+            return image
+        if isinstance(image, np.ndarray):
+            return Image.fromarray(image.astype(np.uint8))
+        return Image.open(image)
+
+    def _fallback_tensor(self, image: Image.Image) -> torch.Tensor:
+        array = np.asarray(ImageOps.fit(image, (160, 160))).astype(np.float32) / 255.0
+        tensor = torch.from_numpy(array).permute(2, 0, 1)
+        tensor = (tensor - 0.5) / 0.5
+        return tensor

src/pipeline/video_pipeline.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import cv2
+from PIL import Image
+
+from src import config
+
+
+@dataclass
+class VideoFrameSample:
+    timestamp_s: float
+    image: Image.Image
+
+
+class VideoPipeline:
+    def sample_frames(self, video_path: str | Path, max_frames: int | None = None) -> list[VideoFrameSample]:
+        max_frames = max_frames or config.DEFAULT_FRAME_SAMPLE_LIMIT
+        cap = cv2.VideoCapture(str(video_path))
+        if not cap.isOpened():
+            raise ValueError('Unable to open uploaded video.')
+
+        fps = cap.get(cv2.CAP_PROP_FPS) or 25.0
+        total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT) or 0)
+        if total_frames == 0:
+            raise ValueError('Uploaded video contains no readable frames.')
+
+        step = max(total_frames // max_frames, 1)
+        samples: list[VideoFrameSample] = []
+        frame_idx = 0
+        while len(samples) < max_frames:
+            cap.set(cv2.CAP_PROP_POS_FRAMES, frame_idx)
+            ok, frame = cap.read()
+            if not ok:
+                break
+            rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
+            samples.append(VideoFrameSample(timestamp_s=frame_idx / fps, image=Image.fromarray(rgb)))
+            frame_idx += step
+        cap.release()
+        return samples

src/protocol/__init__.py

@@ -0,0 +1 @@
+"""Protocol adapters and parameter helpers."""

src/protocol/elsh_params.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import math
+
+
+def collision_probability(d: int, delta: int, k: int) -> float:
+    denom = math.comb(d, k)
+    total = 0.0
+    for r in range(0, min(k, delta) + 1, 2):
+        total += math.comb(delta, r) * math.comb(d - delta, k - r) / denom
+    return total
+
+
+def recommended_params(d: int, delta: int, lam: int = 40) -> tuple[int, float, int]:
+    k = math.ceil(d / (delta + 1))
+    p_delta = collision_probability(d, delta, k)
+    p_delta = min(max(p_delta, 1e-9), 1.0 - 1e-9)
+    l_min = math.ceil(lam / (-math.log2(1.0 - p_delta)))
+    return k, p_delta, l_min

src/protocol/fpsi_adapter.py

@@ -0,0 +1,286 @@
+from __future__ import annotations
+
+import json
+import math
+import os
+import random
+import subprocess
+import time
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+from sklearn.decomposition import PCA
+from sklearn.preprocessing import normalize
+
+from src import config
+from src.protocol.elsh_params import recommended_params
+
+
+@dataclass
+class MatchResult:
+    person: str
+    filename: str
+    hamming_distance: int
+    matched: bool
+    score: float
+
+
+@dataclass
+class ProtocolSummary:
+    mode: str
+    dim: int
+    delta: int
+    L: int
+    k: int
+    p_delta: float
+    communication_mb: float
+    time_s: float
+    gao_feasible: bool
+    tar: float
+    far: float
+    accuracy: float
+    gallery_size: int
+    query_count: int
+    binary_density: float
+    notes: list[str]
+
+
+class FuzzyPSIAdapter:
+    def __init__(self, mode: str | None = None) -> None:
+        self.mode = mode or config.DEFAULT_MODE
+        if self.mode not in config.SUPPORTED_MODES:
+            self.mode = "simulation"
+
+    def binarize(self, features: np.ndarray, target_dim: int) -> tuple[np.ndarray, float]:
+        max_components = min(features.shape[0], features.shape[1])
+        if target_dim < features.shape[1] and target_dim <= max_components:
+            pca = PCA(n_components=target_dim, random_state=42)
+            projected = pca.fit_transform(features)
+            variance = float(pca.explained_variance_ratio_.sum())
+        elif target_dim < features.shape[1]:
+            projected = features[:, :target_dim]
+            variance = min(1.0, float(target_dim / features.shape[1]))
+        else:
+            projected = features[:, :target_dim]
+            variance = 1.0
+        projected = normalize(projected)
+        binary_codes = (projected > 0).astype(np.uint8)
+        return binary_codes, variance
+
+    def calibrate_threshold(self, binary_codes: np.ndarray, labels: np.ndarray) -> dict[str, float | int]:
+        rng = np.random.default_rng(42)
+        label_to_idx: dict[Any, list[int]] = {}
+        for i, label in enumerate(labels):
+            label_to_idx.setdefault(label, []).append(i)
+
+        multi_labels = [label for label, idx in label_to_idx.items() if len(idx) >= 2]
+        unique_labels = np.array(list(label_to_idx.keys()))
+
+        genuine_dists: list[int] = []
+        impostor_dists: list[int] = []
+        for label in multi_labels[:300]:
+            indices = label_to_idx[label]
+            for i in range(min(len(indices) - 1, 3)):
+                genuine_dists.append(int(np.sum(binary_codes[indices[i]] != binary_codes[indices[i + 1]])))
+
+        for _ in range(max(len(genuine_dists) * 2, 32)):
+            l1, l2 = rng.choice(unique_labels, 2, replace=False)
+            i1 = rng.choice(label_to_idx[l1])
+            i2 = rng.choice(label_to_idx[l2])
+            impostor_dists.append(int(np.sum(binary_codes[i1] != binary_codes[i2])))
+
+        genuine = np.array(genuine_dists if genuine_dists else [0])
+        impostor = np.array(impostor_dists if impostor_dists else [binary_codes.shape[1]])
+
+        best_delta = 0
+        best_acc = 0.0
+        best_tar = 0.0
+        best_far = 1.0
+        for delta in range(binary_codes.shape[1]):
+            tar = float(np.mean(genuine <= delta))
+            far = float(np.mean(impostor <= delta))
+            acc = (tar + (1.0 - far)) / 2.0
+            if acc > best_acc:
+                best_delta = delta
+                best_acc = acc
+                best_tar = tar
+                best_far = far
+
+        adjusted_delta = max(0, int(best_delta + config.MATCH_THRESHOLD_MARGIN))
+        return {
+            "delta": adjusted_delta,
+            "tar": best_tar,
+            "far": best_far,
+            "accuracy": best_acc,
+            "genuine_mean": float(genuine.mean()),
+            "impostor_mean": float(impostor.mean()),
+        }
+
+    def gao_feasible(self, dim: int, delta: int) -> bool:
+        return dim > 8 * delta + 8
+
+    def select_l(self, dim: int, delta: int) -> tuple[int, int, float]:
+        k, p_delta, l_min = recommended_params(dim, delta, config.DEFAULT_SECURITY_LAMBDA)
+        return l_min, k, p_delta
+
+    def query_against_gallery(
+        self,
+        query_feature: np.ndarray,
+        gallery_features: np.ndarray,
+        gallery_people: np.ndarray,
+        gallery_filenames: np.ndarray,
+        dim: int,
+        calibration_features: np.ndarray | None = None,
+        calibration_people: np.ndarray | None = None,
+    ) -> tuple[MatchResult, ProtocolSummary, dict[str, Any]]:
+        calibration_features = gallery_features if calibration_features is None else calibration_features
+        calibration_people = gallery_people if calibration_people is None else calibration_people
+
+        binarization_pool = np.vstack([query_feature.reshape(1, -1), calibration_features])
+        pool_binary, variance = self.binarize(binarization_pool, dim)
+        query_binary = pool_binary[0]
+        calibration_binary = pool_binary[1:]
+
+        gallery_pool = np.vstack([query_feature.reshape(1, -1), gallery_features])
+        gallery_binary = self.binarize(gallery_pool, dim)[0][1:]
+
+        labels = np.concatenate([np.array(["__query__"], dtype=object), calibration_people.astype(object)])
+        threshold_stats = self.calibrate_threshold(pool_binary, labels)
+        delta = int(threshold_stats["delta"])
+        L, k, p_delta = self.select_l(dim, delta)
+        distances = np.sum(gallery_binary != query_binary, axis=1)
+        best_idx = int(np.argmin(distances))
+        best_dist = int(distances[best_idx])
+        matched = best_dist <= delta
+        density = float(np.mean(query_binary))
+        score = 1.0 - (best_dist / max(dim, 1))
+
+        if self.mode == "full" and config.FULL_PROTOCOL_ENABLED:
+            communication_mb, protocol_time, full_notes = self._run_full_protocol(gallery_binary, query_binary, dim, delta, L)
+            notes = ["full protocol mode"] + full_notes
+        else:
+            communication_mb, protocol_time = self._simulate_protocol_metrics(gallery_binary, query_binary, dim, delta, L)
+            notes = ["simulation mode", "full protocol disabled or unavailable"]
+
+        summary = ProtocolSummary(
+            mode=self.mode if self.mode == "simulation" or config.FULL_PROTOCOL_ENABLED else "simulation",
+            dim=dim,
+            delta=delta,
+            L=L,
+            k=k,
+            p_delta=p_delta,
+            communication_mb=communication_mb,
+            time_s=protocol_time,
+            gao_feasible=self.gao_feasible(dim, delta),
+            tar=float(threshold_stats["tar"]),
+            far=float(threshold_stats["far"]),
+            accuracy=float(threshold_stats["accuracy"]),
+            gallery_size=int(len(gallery_features)),
+            query_count=1,
+            binary_density=density,
+            notes=notes,
+        )
+        match = MatchResult(
+            person=str(gallery_people[best_idx]),
+            filename=str(gallery_filenames[best_idx]),
+            hamming_distance=best_dist,
+            matched=matched,
+            score=score,
+        )
+        details = {
+            "variance_explained": variance,
+            "query_binary": query_binary.tolist(),
+            "best_index": best_idx,
+            "top5_distances": [int(x) for x in np.sort(distances)[:5]],
+            "calibration_size": int(len(calibration_binary)),
+        }
+        return match, summary, details
+
+    def _simulate_protocol_metrics(
+        self,
+        gallery_binary: np.ndarray,
+        query_binary: np.ndarray,
+        dim: int,
+        delta: int,
+        L: int,
+    ) -> tuple[float, float]:
+        gallery_size = len(gallery_binary)
+        hit_ratio = max(0.02, min(0.35, (delta + 1) / max(dim, 1) * 6.0))
+        candidate_count = max(1, int(gallery_size * hit_ratio))
+        communication_mb = (L * dim + candidate_count * 16 + 500000) / (1024.0 * 1024.0)
+        base_time = 0.05 + candidate_count * 0.0012 + L * 0.001
+        return float(communication_mb), float(base_time)
+
+    def _run_full_protocol(
+        self,
+        gallery_binary: np.ndarray,
+        query_binary: np.ndarray,
+        dim: int,
+        delta: int,
+        L: int,
+    ) -> tuple[float, float, list[str]]:
+        sender_path, receiver_path = self._write_binary_pair(gallery_binary, query_binary, dim)
+        build_dir = config.FULL_PROTOCOL_BUILD_DIR
+        receiver_bin = build_dir / "fpsi_receiver"
+        sender_bin = build_dir / "fpsi_sender"
+        if not receiver_bin.exists() or not sender_bin.exists():
+            communication_mb, protocol_time = self._simulate_protocol_metrics(gallery_binary, query_binary, dim, delta, L)
+            return communication_mb, protocol_time, ["native binaries missing; fell back to simulated metrics"]
+
+        port = 26000 + random.randint(0, 900)
+        recv_cmd = [str(receiver_bin), str(port), str(len(query_binary.reshape(1, -1))), str(dim), str(delta), str(L)]
+        send_cmd = [str(sender_bin), "127.0.0.1", str(port), str(len(gallery_binary)), str(dim), str(delta), str(L)]
+
+        recv_proc = subprocess.Popen(recv_cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+        time.sleep(1.0)
+        send_proc = subprocess.Popen(send_cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+        send_out, send_err = send_proc.communicate(timeout=300)
+        recv_out, recv_err = recv_proc.communicate(timeout=300)
+        comm_mb = 0.0
+        total_time = 0.0
+        for line in recv_out.splitlines():
+            if "Total:" in line:
+                parts = line.split()
+                for i, token in enumerate(parts):
+                    if token.endswith("s,"):
+                        total_time = float(token[:-2])
+                    elif token == "MB":
+                        comm_mb = float(parts[i - 1])
+        notes = []
+        if send_err.strip():
+            notes.append(f"sender stderr: {send_err.strip()[:200]}")
+        if recv_err.strip():
+            notes.append(f"receiver stderr: {recv_err.strip()[:200]}")
+        if comm_mb == 0.0 and total_time == 0.0:
+            sim_comm, sim_time = self._simulate_protocol_metrics(gallery_binary, query_binary, dim, delta, L)
+            return sim_comm, sim_time, notes + ["native run returned no parsable totals; using simulated metrics"]
+        return comm_mb, total_time, notes
+
+    def _write_binary_pair(self, gallery_binary: np.ndarray, query_binary: np.ndarray, dim: int) -> tuple[Path, Path]:
+        runtime_dir = config.OUTPUT_DIR / "runtime_inputs"
+        runtime_dir.mkdir(parents=True, exist_ok=True)
+        sender_path = runtime_dir / f"sender_d{dim}.bin"
+        receiver_path = runtime_dir / f"receiver_d{dim}.bin"
+
+        self._write_binary_dataset(sender_path, gallery_binary)
+        self._write_binary_dataset(receiver_path, query_binary.reshape(1, -1))
+        return sender_path, receiver_path
+
+    @staticmethod
+    def _write_binary_dataset(path: Path, vectors: np.ndarray) -> None:
+        vectors = np.asarray(vectors, dtype=np.uint8)
+        n, d = vectors.shape
+        with open(path, "wb") as fh:
+            fh.write(int(n).to_bytes(4, "little"))
+            fh.write(int(d).to_bytes(4, "little"))
+            fh.write(vectors.tobytes())
+
+    def export_summary(self, match: MatchResult, summary: ProtocolSummary, details: dict[str, Any]) -> str:
+        payload = {
+            "match": asdict(match),
+            "summary": asdict(summary),
+            "details": details,
+        }
+        return json.dumps(payload, indent=2)

src/protocol/runtime_stub.txt

@@ -0,0 +1 @@
+This deployment project defaults to simulation mode. Full native protocol mode can be enabled later by provisioning a built FPSI runtime under runtime/build and setting FPSI_ENABLE_FULL_PROTOCOL=1.

src/ui/__init__.py

@@ -0,0 +1 @@
+"""UI helpers for the Hugging Face demo."""

src/ui/components.py

@@ -0,0 +1,208 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import gradio as gr
+import pandas as pd
+from PIL import Image
+
+from src import config
+from src.data.gallery_store import DemoGallery
+from src.pipeline.image_pipeline import ImagePipeline
+from src.protocol.fpsi_adapter import FuzzyPSIAdapter
+
+
+gallery = DemoGallery()
+image_pipeline = ImagePipeline()
+adapter = FuzzyPSIAdapter(config.DEFAULT_MODE)
+
+CSS = """
+.hero {padding: 20px 24px; border-radius: 18px; background: linear-gradient(135deg, #102a43 0%, #243b53 50%, #334e68 100%); color: white;}
+.metric-card {padding: 14px 16px; border-radius: 14px; background: #f8fafc; border: 1px solid #d9e2ec;}
+.note-card {padding: 14px 16px; border-radius: 14px; background: #f4f7fb; border-left: 4px solid #486581;}
+.small-muted {color: #627d98; font-size: 0.95rem;}
+"""
+
+
+def _example_paths() -> list[list[str]]:
+    return [[path] for _, path in gallery.example_choices()]
+
+
+def _system_status() -> str:
+    summary = gallery.summary()
+    return json.dumps(
+        {
+            "mode": adapter.mode,
+            "full_protocol_enabled": config.FULL_PROTOCOL_ENABLED,
+            "gallery_size": summary["gallery_size"],
+            "gallery_feature_dim": summary["dimensions"],
+            "supported_dims": list(config.DEFAULT_DIMENSIONS),
+            "device": config.FACE_MODEL_DEVICE,
+        },
+        indent=2,
+    )
+
+
+def _protocol_story(dim: int, summary_json: str) -> pd.DataFrame:
+    payload = json.loads(summary_json)
+    summary = payload["summary"]
+    rows = [
+        ("1. Image frontend", "Uploaded face image is normalized and passed through the demo embedding stack."),
+        ("2. Binary projection", f"Embedding is binarized to d={dim} bits for Hamming-space matching."),
+        ("3. Candidate generation", f"E-LSH is parameterized with L={summary['L']} and k={summary['k']}."),
+        ("4. Exact verification", f"Final decision uses δ={summary['delta']} with backend mode={summary['mode']}."),
+        ("5. Reviewer metrics", f"Communication={summary['communication_mb']:.3f} MB, latency={summary['time_s']:.3f} s, Gao feasible={summary['gao_feasible']}."),
+    ]
+    return pd.DataFrame(rows, columns=["Stage", "Deployment-facing explanation"])
+
+
+def run_image_demo(image: Image.Image, dim: int, mode: str):
+    if image is None:
+        raise gr.Error("Please upload or capture a face image.")
+
+    adapter.mode = mode
+    analysis = image_pipeline.analyze(image)
+    match, summary, details = adapter.query_against_gallery(
+        analysis.embedding,
+        gallery.features,
+        gallery.people,
+        gallery.filenames,
+        dim,
+        calibration_features=gallery.calibration_features,
+        calibration_people=gallery.calibration_people,
+    )
+    gallery_image = Image.open(gallery.gallery_image_path(match.filename)).convert("RGB")
+    summary_json = adapter.export_summary(match, summary, details)
+    result_md = f"""
+### Match result
+- **Predicted identity:** {match.person}
+- **Matched gallery image:** `{match.filename}`
+- **Hamming distance:** {match.hamming_distance}
+- **Decision:** {'Match accepted' if match.matched else 'No match under current threshold'}
+- **Similarity-style score:** {match.score:.4f}
+
+### Protocol metrics
+- **Mode:** {summary.mode}
+- **Dimension:** {summary.dim}
+- **Threshold δ:** {summary.delta}
+- **E-LSH L:** {summary.L}
+- **Communication:** {summary.communication_mb:.3f} MB
+- **Latency:** {summary.time_s:.3f} s
+- **TAR / FAR / Acc:** {summary.tar:.4f} / {summary.far:.4f} / {summary.accuracy:.4f}
+- **Gao feasibility:** {'YES' if summary.gao_feasible else 'NO'}
+"""
+    notes = "\n".join(f"- {note}" for note in (analysis.notes + summary.notes))
+    metrics_df = pd.DataFrame([
+        ("binary_density", round(summary.binary_density, 4)),
+        ("variance_explained", round(details['variance_explained'], 4)),
+        ("top5_distances", ", ".join(map(str, details['top5_distances']))),
+        ("gallery_size", summary.gallery_size),
+    ], columns=["Metric", "Value"])
+    return result_md, analysis.preview, gallery_image, summary_json, notes, metrics_df, _protocol_story(dim, summary_json)
+
+
+def load_example(example_path: str):
+    return Image.open(example_path).convert("RGB")
+
+
+def build_app() -> gr.Blocks:
+    with gr.Blocks(title=config.SPACE_TITLE, css=CSS) as demo:
+        gr.HTML(
+            f"""
+            <div class='hero'>
+              <h1>{config.SPACE_TITLE}</h1>
+              <p>{config.SPACE_SUBTITLE}</p>
+              <p>This reviewer-facing demo shows how the research artifact can be surfaced as a deployment-oriented application with image upload, protocol metrics, and a fixed LFW-derived gallery.</p>
+            </div>
+            """
+        )
+
+        with gr.Row():
+            with gr.Column(scale=2):
+                gr.Markdown(
+                    """
+### Deployment focus
+- **Image-first MVP** with upload and webcam capture
+- **Dual backend modes**: simulation by default, optional full protocol mode
+- **Fixed LFW-derived reviewer gallery** for stable testing
+- **Protocol explanation panels** to highlight engineering and deployment effort
+                    """
+                )
+            with gr.Column(scale=1):
+                gr.Code(_system_status(), language="json", label="System status")
+
+        with gr.Tabs():
+            with gr.Tab("Image test"):
+                with gr.Row():
+                    with gr.Column(scale=1):
+                        image_input = gr.Image(label="Upload or capture a query face", type="pil", sources=["upload", "webcam"])
+                        dim_input = gr.Dropdown(choices=list(config.DEFAULT_DIMENSIONS), value=config.DEFAULT_DIM, label="Binary dimension")
+                        mode_input = gr.Dropdown(choices=list(config.SUPPORTED_MODES), value=config.DEFAULT_MODE, label="Backend mode")
+                        run_btn = gr.Button("Run FuzzyPSI-hamming demo", variant="primary")
+                        gr.Examples(examples=_example_paths(), inputs=[image_input], label="Reviewer examples")
+                    with gr.Column(scale=1):
+                        preview_output = gr.Image(label="Processed query preview")
+                        gallery_output = gr.Image(label="Best gallery match")
+                    with gr.Column(scale=1):
+                        result_output = gr.Markdown(label="Match result")
+                        notes_output = gr.Markdown(label="Execution notes")
+
+                with gr.Row():
+                    metrics_output = gr.Dataframe(label="Protocol metrics", interactive=False)
+                    story_output = gr.Dataframe(label="How the pipeline maps to deployment", interactive=False)
+                summary_output = gr.Code(label="Detailed JSON summary", language="json")
+
+                run_btn.click(
+                    run_image_demo,
+                    inputs=[image_input, dim_input, mode_input],
+                    outputs=[result_output, preview_output, gallery_output, summary_output, notes_output, metrics_output, story_output],
+                )
+
+            with gr.Tab("Protocol metrics"):
+                gr.Markdown(
+                    """
+### Reviewer-visible protocol story
+This deployment keeps the paper’s Hamming-FPSI logic visible through dimension, threshold, communication, latency, and Gao-feasibility metrics. The public Space defaults to simulation mode for reliability, while the project layout preserves a path for native protocol execution.
+                    """
+                )
+                metrics_seed = pd.DataFrame([
+                    (128, "adaptive", "reported after query", "public default", "best for reliable reviewer experience"),
+                    (256, "adaptive", "reported after query", "public default", "larger code space and stronger separation"),
+                    (512, "adaptive", "reported after query", "optional heavy mode", "closest to high-dimensional biometric features"),
+                ], columns=["d", "δ", "runtime metrics", "recommended mode", "deployment note"])
+                gr.Dataframe(value=metrics_seed, interactive=False)
+
+            with gr.Tab("How it works"):
+                gr.Markdown(
+                    """
+### End-to-end deployment path
+1. **Frontend intake**: upload or webcam image enters the Gradio service.
+2. **Face embedding**: a deployment-friendly embedding stack converts the image into a dense vector.
+3. **Binary projection**: the adapter ports the artifact’s binarization logic into an interactive service layer.
+4. **E-LSH candidate generation**: deployment metrics expose the recommended `k`, collision probability, and `L` values.
+5. **Exact verification**: the service returns the closest gallery identity together with thresholded Hamming-distance evidence.
+6. **Reviewer instrumentation**: UI cards surface latency, communication, threshold, and Gao infeasibility in the same run.
+                    """
+                )
+
+            with gr.Tab("Engineering story"):
+                gr.Markdown(
+                    """
+### Why this Space shows substantial engineering effort
+- The original release artifact is **script-first** and **feature-file-driven**.
+- This deployment adds a **new image ingestion layer**, **web interaction model**, **demo gallery packaging**, and **dual backend execution abstraction**.
+- The deployment project is isolated from the research artifact so the web stack can evolve independently.
+- The public interface is intentionally framed as a **factory-facing deployment prototype** rather than only a benchmark runner.
+                    """
+                )
+
+            with gr.Tab("Video path"):
+                gr.Markdown(
+                    """
+### Planned short-video support
+The current first release is image-first. The code layout already includes a video pipeline module so that short uploaded clip analysis can be enabled next without restructuring the app.
+                    """
+                )
+
+        return demo