Sync visual safety demo assets and startup build

.dockerignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.DS_Store
+.env
+.env.*
+demo_data/datasets/
+demo_data/media/
+demo_data/openimages_cache/
+demo_data/providers.json

.gitattributes

@@ -33,3 +33,15 @@ saved_model/**/* 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
+demo_assets/images/01b9021aa05e6e46.jpg filter=lfs diff=lfs merge=lfs -text
+demo_assets/images/34ec1592f40cdfaa.jpg filter=lfs diff=lfs merge=lfs -text
+demo_assets/images/499cfd3e29e31662.jpg filter=lfs diff=lfs merge=lfs -text
+demo_assets/images/4b00a3af27c5b2c6.jpg filter=lfs diff=lfs merge=lfs -text
+demo_assets/images/92a7c03c939944a3.jpg filter=lfs diff=lfs merge=lfs -text
+demo_assets/images/ab93a8b5592ce5bd.jpg filter=lfs diff=lfs merge=lfs -text
+demo_assets/images/c97b0813480f1f26.jpg filter=lfs diff=lfs merge=lfs -text
+demo_assets/images/d7bf42f6b20e96c2.jpg filter=lfs diff=lfs merge=lfs -text
+demo_assets/images/dbe3012525cc3fec.jpg filter=lfs diff=lfs merge=lfs -text
+demo_assets/images/ea39fa9dc50811b0.jpg filter=lfs diff=lfs merge=lfs -text
+demo_assets/images/eeed1e944c331791.jpg filter=lfs diff=lfs merge=lfs -text
+vendor/hyperview-0.6.2-py3-none-any.whl filter=lfs diff=lfs merge=lfs -text

.hyperview/extensions/safety-readout/extension.toml

@@ -0,0 +1,8 @@
+name = "safety-readout"
+description = "Visual safety CLIP vs hyper3-clip moderation readout"
+
+[[panels]]
+id = "safety-comparison"
+title = "Safety Review Readout"
+position = "right"
+file = "panel.js"

.hyperview/extensions/safety-readout/panel.js

@@ -0,0 +1,501 @@
+const sdk = globalThis.HyperViewPanelSDK;
+if (!sdk) throw new Error("HyperViewPanelSDK is not available on window.");
+
+const { React, components, hooks } = sdk;
+const { Panel, PanelToolbar, PanelToolbarButton } = components;
+const {
+  usePanelSelection,
+  usePanelSamples,
+  usePanelCommands,
+  usePanelProps,
+} = hooks;
+
+const colors = {
+  panelBg: "#0f172a",
+  cardBg: "#162032",
+  buttonBg: "#233047",
+  border: "#334155",
+  text: "#e5e7eb",
+  strongText: "#f8fafc",
+  mutedText: "#94a3b8",
+  bodyText: "#cbd5e1",
+  accent: "#38bdf8",
+  review: "#fbbf24",
+  safe: "#34d399",
+  error: "#fca5a5",
+};
+
+function normalizeModels(value) {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((model, index) => ({
+      key: String(model.key || `model-${index}`),
+      displayName: String(model.displayName || model.display_name || model.key || `Model ${index + 1}`),
+      buttonLabel: String(
+        model.buttonLabel || model.button_label || `${model.displayName || model.key || "Model"} query`,
+      ),
+      layoutKey: model.layoutKey || model.layout_key || null,
+    }))
+    .filter((model) => model.layoutKey);
+}
+
+function titleLabel(label) {
+  return String(label || "unlabeled")
+    .replaceAll("_", " ")
+    .toLowerCase()
+    .replace(/\b\w/g, (char) => char.toUpperCase());
+}
+
+function formatMetric(value) {
+  if (typeof value !== "number" || Number.isNaN(value)) return "-";
+  return value.toFixed(3);
+}
+
+function Button({ children, onClick, title, disabled }) {
+  return React.createElement(
+    "button",
+    {
+      type: "button",
+      onClick,
+      title,
+      disabled,
+      style: {
+        border: `1px solid ${colors.border}`,
+        background: colors.buttonBg,
+        color: colors.text,
+        borderRadius: 4,
+        padding: "8px 9px",
+        fontSize: 11,
+        lineHeight: 1.2,
+        cursor: disabled ? "default" : "pointer",
+        textAlign: "left",
+        opacity: disabled ? 0.65 : 1,
+      },
+    },
+    children,
+  );
+}
+
+function SectionTitle({ children }) {
+  return React.createElement(
+    "h3",
+    {
+      style: {
+        margin: 0,
+        color: colors.strongText,
+        fontSize: 13,
+        fontWeight: 700,
+      },
+    },
+    children,
+  );
+}
+
+function Hero({ bucketCounts }) {
+  return React.createElement(
+    "div",
+    {
+      style: {
+        border: `1px solid ${colors.border}`,
+        borderRadius: 6,
+        background: colors.cardBg,
+        padding: 12,
+        display: "flex",
+        flexDirection: "column",
+        gap: 8,
+      },
+    },
+    React.createElement(
+      "div",
+      { style: { color: colors.accent, fontSize: 11, fontWeight: 700, textTransform: "uppercase" } },
+      "Marketplace upload triage",
+    ),
+    React.createElement(
+      "div",
+      { style: { color: colors.strongText, fontSize: 15, fontWeight: 800, lineHeight: 1.25 } },
+      "Classify each new listing as safe or needs review before it goes live.",
+    ),
+    React.createElement(
+      "div",
+      { style: { color: colors.bodyText, fontSize: 12, lineHeight: 1.45 } },
+      "This public demo uses harmless Open Images examples to stand in for a marketplace upload stream: normal listings should pass, regulated or risky objects should enter the review queue.",
+    ),
+    React.createElement(
+      "div",
+      { style: { display: "grid", gridTemplateColumns: "1fr 1fr", gap: 8 } },
+      React.createElement(StatChip, {
+        label: "Safe",
+        value: String(bucketCounts?.safe ?? 60),
+        color: colors.safe,
+      }),
+      React.createElement(StatChip, {
+        label: "Needs review",
+        value: String(bucketCounts?.needs_review ?? 60),
+        color: colors.review,
+      }),
+    ),
+  );
+}
+
+function StatChip({ label, value, color }) {
+  return React.createElement(
+    "div",
+    {
+      style: {
+        border: `1px solid ${colors.border}`,
+        borderRadius: 4,
+        padding: "7px 8px",
+        background: "#101827",
+      },
+    },
+    React.createElement("div", { style: { color, fontSize: 16, fontWeight: 800 } }, value),
+    React.createElement("div", { style: { color: colors.mutedText, fontSize: 11 } }, label),
+  );
+}
+
+function ScenarioCard({ item, models, loadingKey, onSelectQuery }) {
+  const isReview = item.bucket === "needs_review";
+  const chipColor = isReview ? colors.review : colors.safe;
+  const gridColumns = models.length > 1 ? "repeat(2, minmax(0, 1fr))" : "1fr";
+
+  return React.createElement(
+    "div",
+    {
+      style: {
+        border: `1px solid ${colors.border}`,
+        borderRadius: 6,
+        background: colors.cardBg,
+        padding: 10,
+        display: "flex",
+        flexDirection: "column",
+        gap: 8,
+      },
+    },
+    React.createElement(
+      "div",
+      { style: { display: "flex", alignItems: "center", justifyContent: "space-between", gap: 8 } },
+      React.createElement(
+        "div",
+        { style: { display: "flex", alignItems: "center", gap: 8 } },
+        React.createElement(
+          "div",
+          {
+            style: {
+              width: 22,
+              height: 22,
+              borderRadius: 4,
+              border: `1px solid ${colors.border}`,
+              display: "flex",
+              alignItems: "center",
+              justifyContent: "center",
+              color: colors.accent,
+              fontSize: 12,
+              fontWeight: 800,
+            },
+          },
+          item.step || "?",
+        ),
+        React.createElement(
+          "div",
+          { style: { color: colors.strongText, fontSize: 13, fontWeight: 800 } },
+          item.title,
+        ),
+      ),
+      React.createElement(
+        "div",
+        {
+          style: {
+            border: `1px solid ${chipColor}`,
+            color: chipColor,
+            borderRadius: 4,
+            padding: "2px 5px",
+            fontSize: 10,
+            whiteSpace: "nowrap",
+          },
+        },
+        item.family,
+      ),
+    ),
+    React.createElement(
+      "div",
+      {
+        style: {
+          display: "grid",
+          gridTemplateColumns: "74px 1fr",
+          gap: 8,
+          color: colors.bodyText,
+          fontSize: 11,
+          lineHeight: 1.35,
+        },
+      },
+      React.createElement("div", { style: { color: colors.accent, fontWeight: 700 } }, "Decision"),
+      React.createElement("div", null, item.decision),
+      React.createElement("div", { style: { color: colors.accent, fontWeight: 700 } }, "Value"),
+      React.createElement("div", null, item.businessValue),
+      React.createElement("div", { style: { color: colors.accent, fontWeight: 700 } }, "Inspect"),
+      React.createElement("div", null, item.inspect),
+    ),
+    React.createElement(
+      "div",
+      { style: { color: colors.mutedText, fontSize: 10, lineHeight: 1.3 } },
+      `Dataset labels: ${(item.labels || []).map(titleLabel).join(", ")}`,
+    ),
+    React.createElement(
+      "div",
+      { style: { display: "grid", gridTemplateColumns: gridColumns, gap: 6 } },
+      models.map((model) => {
+        const choiceKey = `${item.queryId}:${model.key}`;
+        return React.createElement(
+          Button,
+          {
+            key: model.key,
+            onClick: () => onSelectQuery(item, model),
+            disabled: loadingKey === choiceKey,
+            title: `Show ${model.displayName} neighbors for this upload`,
+          },
+          loadingKey === choiceKey ? "Loading..." : model.buttonLabel,
+        );
+      }),
+    ),
+  );
+}
+
+function MetricTable({ metrics }) {
+  const rows = [
+    ["Accuracy", "accuracy"],
+    ["AUROC", "auroc"],
+    ["AP, review class", "apReview"],
+    ["F1, review class", "f1Review"],
+    ["Review recall", "reviewRecall"],
+    ["Review precision", "reviewPrecision"],
+    ["Safe recall", "safeRecall"],
+  ];
+
+  return React.createElement(
+    "table",
+    {
+      style: {
+        width: "100%",
+        borderCollapse: "collapse",
+        color: colors.bodyText,
+        fontSize: 11,
+      },
+    },
+    React.createElement(
+      "thead",
+      null,
+      React.createElement(
+        "tr",
+        null,
+        ["Metric", "CLIP", "hyper3-clip"].map((header) =>
+          React.createElement(
+            "th",
+            {
+              key: header,
+              style: {
+                padding: "6px 8px",
+                textAlign: header === "Metric" ? "left" : "right",
+                color: colors.strongText,
+                borderBottom: `1px solid ${colors.border}`,
+              },
+            },
+            header,
+          ),
+        ),
+      ),
+    ),
+    React.createElement(
+      "tbody",
+      null,
+      rows.map(([label, key]) =>
+        React.createElement(
+          "tr",
+          { key },
+          React.createElement("td", { style: { padding: "5px 8px" } }, label),
+          React.createElement(
+            "td",
+            { style: { padding: "5px 8px", textAlign: "right" } },
+            formatMetric(metrics?.clip?.[key]),
+          ),
+          React.createElement(
+            "td",
+            { style: { padding: "5px 8px", textAlign: "right" } },
+            formatMetric(metrics?.candidate?.[key]),
+          ),
+        ),
+      ),
+    ),
+  );
+}
+
+function Details({ title, children }) {
+  return React.createElement(
+    "details",
+    {
+      style: {
+        border: `1px solid ${colors.border}`,
+        borderRadius: 6,
+        background: colors.cardBg,
+        padding: 10,
+      },
+    },
+    React.createElement(
+      "summary",
+      {
+        style: {
+          color: colors.strongText,
+          fontSize: 12,
+          fontWeight: 700,
+          cursor: "pointer",
+        },
+      },
+      title,
+    ),
+    React.createElement(
+      "div",
+      { style: { marginTop: 8, display: "flex", flexDirection: "column", gap: 8 } },
+      children,
+    ),
+  );
+}
+
+export default function SafetyComparisonPanel() {
+  const selection = usePanelSelection();
+  const samplesState = usePanelSamples();
+  const commands = usePanelCommands();
+  const panelProps = usePanelProps();
+  const didRequestInitialReset = React.useRef(false);
+  const [panelError, setPanelError] = React.useState(null);
+  const [loadingKey, setLoadingKey] = React.useState(null);
+
+  const models = React.useMemo(() => normalizeModels(panelProps.models), [panelProps.models]);
+  const examples = Array.isArray(panelProps.examples) ? panelProps.examples : [];
+  const metrics = panelProps.metrics || {};
+  const bucketCounts = panelProps.bucketCounts || {};
+
+  React.useEffect(() => {
+    if (!models.length) return undefined;
+    const resetKey = "openimages-safety-demo:initial-reset:v5";
+    const storage = typeof window !== "undefined" ? window.sessionStorage : null;
+    if (didRequestInitialReset.current || storage?.getItem(resetKey) === "1") {
+      return undefined;
+    }
+    didRequestInitialReset.current = true;
+
+    let cancelled = false;
+    const resetInitialState = async () => {
+      try {
+        if (commands.setLabelFilter) commands.setLabelFilter(null);
+        await commands.clearQueryContext({ persist: true });
+        if (!cancelled) storage?.setItem(resetKey, "1");
+      } catch (error) {
+        didRequestInitialReset.current = false;
+        if (!cancelled) console.warn("Could not reset Open Images safety demo state:", error);
+      }
+    };
+
+    const timers = [0, 900, 2200].map((delay) => window.setTimeout(resetInitialState, delay));
+    return () => {
+      cancelled = true;
+      timers.forEach((timer) => window.clearTimeout(timer));
+    };
+  }, [commands, models.length]);
+
+  const clearSelection = async () => {
+    if (commands.setLabelFilter) commands.setLabelFilter(null);
+    setPanelError(null);
+    await commands.clearQueryContext({ persist: true });
+  };
+
+  const selectModelQuery = async (item, model) => {
+    const key = `${item.queryId}:${model.key}`;
+    setPanelError(null);
+
+    if (!model.layoutKey) {
+      setPanelError(`${model.displayName} layout is not ready yet. Try again in a moment.`);
+      return;
+    }
+
+    setLoadingKey(key);
+    try {
+      await commands.setActiveLayout(model.layoutKey);
+      await commands.showSimilar({
+        sampleId: item.queryId,
+        layoutKey: model.layoutKey,
+        k: 10,
+        source: `openimages-safety-demo:${model.key}`,
+        focus: "samples",
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      setPanelError(`Could not select query: ${message}`);
+    } finally {
+      setLoadingKey(null);
+    }
+  };
+
+  return React.createElement(
+    Panel,
+    { className: "h-full" },
+    React.createElement(PanelToolbar, {
+      items: [
+        { id: "dataset", label: "Data", value: "Open Images" },
+        { id: "samples", label: "Items", value: String(samplesState.totalSamples ?? "-") },
+        { id: "selected", label: "Selected", value: String(selection.selectedIds?.length ?? 0) },
+      ],
+      actions: React.createElement(PanelToolbarButton, { onClick: clearSelection }, "Reset"),
+    }),
+    React.createElement(
+      "div",
+      {
+        style: {
+          height: "100%",
+          overflow: "auto",
+          padding: 12,
+          display: "flex",
+          flexDirection: "column",
+          gap: 12,
+          background: colors.panelBg,
+        },
+      },
+      React.createElement(Hero, { bucketCounts }),
+      React.createElement(
+        "section",
+        { style: { display: "flex", flexDirection: "column", gap: 8 } },
+        React.createElement(SectionTitle, null, "Three upload decisions"),
+        examples.length && models.length
+          ? examples.map((item) =>
+              React.createElement(ScenarioCard, {
+                key: item.id,
+                item,
+                models,
+                loadingKey,
+                onSelectQuery: selectModelQuery,
+              }),
+            )
+          : React.createElement(
+              "div",
+              { style: { color: colors.bodyText, fontSize: 12, lineHeight: 1.45 } },
+              "Demo scenarios are not configured.",
+            ),
+      ),
+      React.createElement(
+        Details,
+        { title: "Benchmark details" },
+        React.createElement(
+          "div",
+          { style: { color: colors.bodyText, fontSize: 11, lineHeight: 1.4 } },
+          `${metrics.dataset || "Open Images proxy"}: ${metrics.classBalance || ""}. ${metrics.readout || ""}`,
+        ),
+        React.createElement(MetricTable, { metrics }),
+      ),
+      panelError
+        ? React.createElement(
+            "div",
+            { style: { color: colors.error, fontSize: 11, lineHeight: 1.35 } },
+            panelError,
+          )
+        : null,
+    ),
+  );
+}

Dockerfile

@@ -0,0 +1,62 @@
+FROM python:3.11-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    curl \
+    libssl-dev \
+    pkg-config \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN useradd -m -u 1000 user
+USER user
+
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    HF_HOME=/home/user/.cache/huggingface \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+WORKDIR $HOME/app
+
+RUN pip install --upgrade pip
+
+ARG HYPER_MODELS_VERSION=0.3.0
+
+# Install CPU-only PyTorch first so the Space does not pull the default CUDA bundle.
+RUN pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
+COPY --chown=user vendor/hyperview-*.whl /tmp/
+RUN echo "Installing vendored HyperView wheel" \
+    && pip install /tmp/hyperview-*.whl \
+    && python - <<'PY'
+import inspect
+import hyperview as hv
+
+print("hyperview", hv.__version__, inspect.signature(hv.launch))
+assert hasattr(hv.ui, "Samples"), "HyperView build must support explicit Samples panels"
+PY
+RUN pip install \
+    "hyper-models[ml]==${HYPER_MODELS_VERSION}" \
+    "datasets>=4.5.0" \
+    "Pillow>=12.0.0" \
+    "timm>=1.0.0" \
+    "transformers>=5.0.0,<6.0.0" \
+    "safetensors>=0.4.0" \
+    "pyyaml>=6.0.0" \
+    "sentencepiece>=0.2.0" \
+    "protobuf>=4.25.0"
+
+COPY --chown=user . .
+
+ENV HYPERVIEW_HOST=0.0.0.0 \
+    HYPERVIEW_PORT=7860 \
+    HYPERVIEW_WORKSPACE_ID=visual-safety-content-clip-hyper3clip \
+    HYPERVIEW_DATASETS_DIR=/home/user/.cache/hyperview/datasets \
+    HYPERVIEW_MEDIA_DIR=/home/user/.cache/hyperview/media \
+    SAFETY_ASSET_REPO_TYPE=space
+
+EXPOSE 7860
+
+HEALTHCHECK --interval=30s --timeout=10s --start-period=600s --retries=3 \
+    CMD curl -f http://localhost:7860/__hyperview__/health || exit 1
+
+CMD ["python", "demo.py"]

README.md

@@ -1,10 +1,72 @@
 ---
 title: HyperView Visual Safety
-emoji: 🚀
-colorFrom: blue
-colorTo: yellow
+emoji: 🛡️
+colorFrom: yellow
+colorTo: gray
 sdk: docker
+app_port: 7860
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# HyperView - Open Images Visual Safety Demo
+
+This demo shows a marketplace-style visual moderation workflow without showing
+explicit NSFW material.
+
+It loads a small curated Open Images V7 validation subset from the Space assets
+and builds the HyperView dataset at startup with two buckets:
+
+- **Safe**: ordinary marketplace/public-image objects such as clothing, shoes,
+  furniture, toys, books, fruit, laptops, and mobile phones.
+- **Needs review**: public-displayable but policy-relevant objects such as
+  alcohol, cigarettes, knives, and firearms-related labels.
+
+HyperView computes embeddings and opens two pinned maps at startup:
+
+- CLIP ViT-B/32 in a Euclidean 2D layout
+- hyper3-clip `hyper3-clip-v0.5` from `hyper-models` in a Poincare 2D layout
+
+The right-hand panel includes the measured 120-image zero-shot smoke test:
+CLIP is stronger overall on this first proxy, while hyper3-clip catches slightly
+more review-class items at the cost of more false positives.
+
+Run locally from the HyperView repo:
+
+```bash
+uv run python hyperview-spaces/spaces/visual-safety-content-clip-hyper3clip/demo.py
+```
+
+Useful overrides:
+
+```bash
+HYPERVIEW_PORT=6265 SAFETY_SAMPLES_PER_BUCKET=40 \
+  uv run python hyperview-spaces/spaces/visual-safety-content-clip-hyper3clip/demo.py
+```
+
+## Dataset And Rights
+
+The demo uses a checked-in public Open Images V7 validation subset under
+`demo_assets/`:
+
+- Dataset: https://storage.googleapis.com/openimages/web/index.html
+- Images are loaded through Hugging Face Hub asset resolution when the Space
+  runs on Hugging Face.
+- Individual source licenses are preserved in sample metadata.
+
+This is a public demo proxy for marketplace moderation triage, not a claim that
+either model is a production safety classifier.
+
+## Deploy Source
+
+This folder is intended to deploy to `mnm-matin/HyperView-Visual-Safety` from
+the `hyperview-spaces` deployment repository. The org Space
+`hyper3labs/HyperView-Visual-Safety` is kept commit-synced but paused.
+
+hyper3-clip weights are loaded through the `hyper-models` catalog entry for the
+gated `hyper3labs/hyper3-clip-v0.5` model repository at runtime. The Space needs
+an `HF_TOKEN` secret with access to that model.
+
+If that secret is missing, the Space starts in a clearly labeled fallback mode:
+the hyper3-clip panel reuses the CLIP layout and the readout shows a runtime
+warning. Set `HYPERVIEW_ALLOW_CANDIDATE_FALLBACK=0` to make missing hyper3-clip
+access fail loudly instead.

demo.py

@@ -0,0 +1,399 @@
+#!/usr/bin/env python
+"""Open Images visual safety moderation demo for CLIP vs hyper3-clip."""
+
+from __future__ import annotations
+
+import json
+import os
+from collections import Counter, defaultdict
+from pathlib import Path
+from typing import Any
+
+from huggingface_hub import hf_hub_download
+import hyperview as hv
+from hyperview.core.sample import Sample
+
+
+SPACE_DIR = Path(__file__).resolve().parent
+SPACE_HOST = os.environ.get("HYPERVIEW_HOST", "127.0.0.1")
+SPACE_PORT = int(os.environ.get("HYPERVIEW_PORT", "6262"))
+WORKSPACE_ID = os.environ.get("HYPERVIEW_WORKSPACE_ID", "visual-safety-content-clip-hyper3clip")
+DATASET_NAME = os.environ.get("HYPERVIEW_DATASET_NAME", "openimages_visual_safety_marketplace_triage_assets_v1")
+EXTENSION_DIR = SPACE_DIR / ".hyperview" / "extensions" / "safety-readout"
+SAMPLES_PER_BUCKET = int(os.environ.get("SAFETY_SAMPLES_PER_BUCKET", "60"))
+ASSET_MANIFEST_PATH = os.environ.get("SAFETY_ASSET_MANIFEST", "demo_assets/manifest.json")
+ASSET_REPO_ID = os.environ.get("SAFETY_ASSET_REPO_ID") or os.environ.get("SPACE_ID")
+ASSET_REPO_TYPE = os.environ.get("SAFETY_ASSET_REPO_TYPE", "space")
+ASSET_REVISION = os.environ.get("SAFETY_ASSET_REVISION") or None
+ASSET_LOCAL_ROOT = Path(os.environ.get("SAFETY_ASSET_LOCAL_ROOT", str(SPACE_DIR)))
+
+DEMO_SCENARIOS = (
+    {
+        "labels": ("Knife", "Kitchen knife"),
+        "title": "Kitchen knife upload",
+        "step": "1",
+        "decision": "Route to policy review",
+        "business_value": "Catches listings that may be allowed in some contexts but need marketplace policy checks before broad distribution.",
+        "inspect": "A useful model should pull nearby knives/tools into the same neighborhood instead of mixing them with ordinary kitchenware.",
+    },
+    {
+        "labels": ("Beer", "Wine", "Alcoholic beverage"),
+        "title": "Alcohol listing",
+        "step": "2",
+        "decision": "Restrict or age-gate",
+        "business_value": "Separates regulated goods from normal shopping content so the queue can apply the correct country and age policy.",
+        "inspect": "Look for alcohol examples grouped together, not scattered across safe food or glassware listings.",
+    },
+    {
+        "labels": ("Shoe", "Clothing", "Dress", "Toy", "Chair"),
+        "title": "Normal seller upload",
+        "step": "3",
+        "decision": "Approve without review",
+        "business_value": "Avoids false positives that slow down legitimate sellers and create unnecessary moderator load.",
+        "inspect": "A useful model keeps ordinary listings away from the needs-review neighborhood.",
+    },
+)
+
+SMOKE_METRICS = {
+    "dataset": "Open Images V7 validation safety proxy",
+    "nImages": 120,
+    "classBalance": "60 safe / 60 needs review",
+    "clip": {
+        "accuracy": 0.758,
+        "auroc": 0.865,
+        "apReview": 0.870,
+        "f1Review": 0.768,
+        "reviewRecall": 0.800,
+        "reviewPrecision": 0.738,
+        "safeRecall": 0.717,
+    },
+    "candidate": {
+        "accuracy": 0.725,
+        "auroc": 0.839,
+        "apReview": 0.812,
+        "f1Review": 0.752,
+        "reviewRecall": 0.833,
+        "reviewPrecision": 0.685,
+        "safeRecall": 0.617,
+    },
+    "readout": (
+        "CLIP is stronger overall on the first zero-shot smoke test. hyper3-clip catches slightly more "
+        "review items, which is useful for moderation triage but creates more false positives."
+    ),
+}
+
+MODEL_SPECS = [
+    {
+        "key": "clip",
+        "display_name": os.environ.get("SAFETY_BASELINE_DISPLAY_NAME", "CLIP-B/32"),
+        "button_label": os.environ.get("SAFETY_BASELINE_BUTTON_LABEL", "Inspect with CLIP"),
+        "provider": os.environ.get("SAFETY_BASELINE_PROVIDER", "embed-anything"),
+        "model": os.environ.get("SAFETY_BASELINE_MODEL", "openai/clip-vit-base-patch32"),
+        "layout": os.environ.get("SAFETY_BASELINE_LAYOUT", "euclidean:2d"),
+        "geometry": os.environ.get("SAFETY_BASELINE_GEOMETRY", "euclidean"),
+        "layout_dimension": int(os.environ.get("SAFETY_BASELINE_LAYOUT_DIMENSION", "2")),
+        "metric": os.environ.get("SAFETY_BASELINE_METRIC", "cosine"),
+        "panel_title": os.environ.get("SAFETY_BASELINE_PANEL_TITLE", "CLIP-B/32 - Safety Review Map"),
+    },
+    {
+        "key": "candidate",
+        "display_name": os.environ.get("SAFETY_CANDIDATE_DISPLAY_NAME", "hyper3-clip"),
+        "button_label": os.environ.get("SAFETY_CANDIDATE_BUTTON_LABEL", "Inspect with hyper3-clip"),
+        "provider": os.environ.get("SAFETY_CANDIDATE_PROVIDER", "hyper-models"),
+        "model": os.environ.get("SAFETY_CANDIDATE_MODEL", "hyper3-clip-v0.5"),
+        "layout": os.environ.get("SAFETY_CANDIDATE_LAYOUT", "poincare:2d"),
+        "geometry": os.environ.get("SAFETY_CANDIDATE_GEOMETRY", "poincare"),
+        "layout_dimension": int(os.environ.get("SAFETY_CANDIDATE_LAYOUT_DIMENSION", "2")),
+        "metric": os.environ.get("SAFETY_CANDIDATE_METRIC", "cosine"),
+        "panel_title": os.environ.get("SAFETY_CANDIDATE_PANEL_TITLE", "hyper3-clip - Safety Review Map"),
+    },
+]
+
+
+def resolve_asset(relative_path: str) -> Path:
+    if ASSET_REPO_ID:
+        return Path(
+            hf_hub_download(
+                repo_id=ASSET_REPO_ID,
+                repo_type=ASSET_REPO_TYPE,
+                revision=ASSET_REVISION,
+                filename=relative_path,
+            )
+        )
+
+    local_path = ASSET_LOCAL_ROOT / relative_path
+    if not local_path.exists():
+        raise FileNotFoundError(
+            f"Asset '{relative_path}' was not found locally and SAFETY_ASSET_REPO_ID/SPACE_ID is unset."
+        )
+    return local_path
+
+
+def safe_sample_id(record: dict[str, Any]) -> str:
+    return f"openimages_{record['index']:03d}_{record['bucket']}_{record['image_id']}"
+
+
+def choose_records() -> list[dict[str, Any]]:
+    manifest_path = resolve_asset(ASSET_MANIFEST_PATH)
+    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    records: list[dict[str, Any]] = []
+    for item in manifest.get("records", []):
+        bucket = item["bucket"]
+        if sum(1 for record in records if record["bucket"] == bucket) >= SAMPLES_PER_BUCKET:
+            continue
+        image_path = resolve_asset(item["asset_path"])
+        records.append(
+            {
+                "index": len(records),
+                "image_id": item["image_id"],
+                "bucket": bucket,
+                "label": item["label"],
+                "labels": item["labels"],
+                "path": image_path,
+                "source_url": item["source_url"],
+                "license": item.get("license", ""),
+                "title": item.get("title", ""),
+            }
+        )
+        if all(
+            sum(1 for record in records if record["bucket"] == bucket_name) >= SAMPLES_PER_BUCKET
+            for bucket_name in ("needs_review", "safe")
+        ):
+            break
+
+    if not records:
+        raise RuntimeError("No Open Images records could be prepared.")
+
+    records = order_records_for_demo(records)
+    for index, record in enumerate(records):
+        record["index"] = index
+    counts = Counter(record["bucket"] for record in records)
+    print(f"Prepared Open Images safety records: {dict(counts)}", flush=True)
+    source = f"Hugging Face {ASSET_REPO_TYPE} '{ASSET_REPO_ID}'" if ASSET_REPO_ID else "local demo_assets"
+    print(f"Loaded visual-safety assets from {source}.", flush=True)
+    return records
+
+
+def order_records_for_demo(records: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Put landing-page-friendly examples first in the Samples panel."""
+    used: set[str] = set()
+    ordered: list[dict[str, Any]] = []
+
+    def append_unique(items: list[dict[str, Any]]) -> None:
+        for item in items:
+            if item["image_id"] in used:
+                continue
+            used.add(item["image_id"])
+            ordered.append(item)
+
+    by_label: dict[str, list[dict[str, Any]]] = defaultdict(list)
+    for record in records:
+        by_label[record["label"]].append(record)
+
+    for scenario in DEMO_SCENARIOS:
+        record = next(
+            (
+                candidate
+                for label in scenario["labels"]
+                for candidate in by_label.get(label, [])
+                if candidate["image_id"] not in used
+            ),
+            None,
+        )
+        if record is None:
+            continue
+        append_unique([record])
+
+    append_unique(sorted(
+        (record for record in records if record["bucket"] == "safe" and record["image_id"] not in used),
+        key=lambda record: (record["label"], record["image_id"]),
+    ))
+    append_unique([record for record in records if record["bucket"] == "needs_review" and record["image_id"] not in used])
+    append_unique([record for record in records if record["image_id"] not in used])
+
+    return ordered
+
+
+def add_safety_samples(dataset: hv.Dataset) -> list[dict[str, Any]]:
+    existing_ids = {sample.id for sample in dataset.samples}
+    records = choose_records()
+    samples: list[Sample] = []
+    existing_selected_ids = set()
+
+    for record in records:
+        sample_id = safe_sample_id(record)
+        existing_selected_ids.add(sample_id)
+        metadata = {
+            "policy_bucket": record["bucket"],
+            "open_images_labels": record["labels"],
+            "primary_label": record["label"],
+            "source_dataset": "Open Images V7 validation",
+            "source_url": record["source_url"],
+            "license": record.get("license", ""),
+            "title": record.get("title", ""),
+            "business_use_case": "marketplace listing moderation triage",
+            "display_order": record["index"],
+        }
+
+        samples.append(
+            Sample(
+                id=sample_id,
+                filepath=str(record["path"]),
+                label=record["bucket"],
+                metadata=metadata,
+            )
+        )
+
+    added = len(existing_selected_ids - existing_ids)
+    updated = len(existing_selected_ids & existing_ids)
+    dataset.add_samples(samples, skip_existing=False)
+    print(f"Prepared Open Images safety samples ({added} added, {updated} updated).", flush=True)
+    return records
+
+
+def ensure_layouts(dataset: hv.Dataset) -> dict[str, str]:
+    layouts: dict[str, str] = {}
+    for spec in MODEL_SPECS:
+        print(f"Ensuring {spec['display_name']} embeddings...", flush=True)
+        space_key = dataset.compute_embeddings(
+            model=spec["model"],
+            provider=spec["provider"],
+            batch_size=32,
+            show_progress=True,
+        )
+        print(f"Ensuring {spec['display_name']} layout...", flush=True)
+        layouts[spec["key"]] = dataset.compute_visualization(
+            space_key=space_key,
+            layout=spec["layout"],
+            n_neighbors=20,
+            min_dist=0.08,
+            metric=spec["metric"],
+        )
+    return layouts
+
+
+def build_dataset() -> tuple[hv.Dataset, dict[str, str], list[dict[str, Any]]]:
+    dataset = hv.Dataset(DATASET_NAME)
+    records = add_safety_samples(dataset)
+    layouts = ensure_layouts(dataset)
+    return dataset, layouts, records
+
+
+def model_panel_props(layouts: dict[str, str]) -> list[dict[str, Any]]:
+    show_baseline = os.environ.get("SAFETY_SHOW_BASELINE_BUTTONS", "").lower() in {"1", "true", "yes"}
+    props = []
+    for spec in MODEL_SPECS:
+        if spec["key"] == "clip" and not show_baseline:
+            continue
+        props.append(
+            {
+                "key": spec["key"],
+                "displayName": spec["display_name"],
+                "buttonLabel": spec["button_label"],
+                "layoutKey": layouts[spec["key"]],
+            }
+        )
+    return props
+
+
+def build_examples(records: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    by_label: dict[str, dict[str, Any]] = {}
+    for record in records:
+        by_label.setdefault(record["label"], record)
+
+    examples = []
+    for scenario in DEMO_SCENARIOS:
+        record = next((by_label.get(label) for label in scenario["labels"] if label in by_label), None)
+        if record is None:
+            continue
+        bucket = record["bucket"]
+        examples.append(
+            {
+                "id": record["image_id"],
+                "step": scenario["step"],
+                "title": scenario["title"],
+                "family": "Needs review" if bucket == "needs_review" else "Safe listing",
+                "decision": scenario["decision"],
+                "businessValue": scenario["business_value"],
+                "inspect": scenario["inspect"],
+                "queryId": safe_sample_id(record),
+                "queryLabel": record["label"],
+                "bucket": bucket,
+                "labels": record["labels"],
+                "sourceUrl": record["source_url"],
+            }
+        )
+    return examples
+
+
+def build_demo_view(dataset: hv.Dataset, layouts: dict[str, str], records: list[dict[str, Any]]) -> hv.ui.View:
+    primary_spec = next(spec for spec in MODEL_SPECS if spec["key"] == "candidate")
+    samples_panel = hv.ui.Samples(
+        id="safety-samples",
+        title="Samples",
+        position="center",
+        layout=hv.ui.PanelLayout(min_height=420),
+    )
+    primary_scatter = hv.ui.Scatter(
+        id="hyper3-clip-safety-map-bottom",
+        title=primary_spec["panel_title"],
+        position="bottom",
+        reference_panel_id="safety-samples",
+        direction="below",
+        layout_key=layouts[primary_spec["key"]],
+        geometry=primary_spec["geometry"],
+        layout_dimension=primary_spec["layout_dimension"],
+        layout=hv.ui.PanelLayout(height=280, min_height=220),
+    )
+    readout_panel = hv.ui.ExtensionPanel(
+        id="visual-safety-readout",
+        extension="safety-readout",
+        panel="safety-comparison",
+        title="Safety triage",
+        reference_panel_id="safety-samples",
+        direction="right",
+        props={
+            "models": model_panel_props(layouts),
+            "examples": build_examples(records),
+            "metrics": SMOKE_METRICS,
+            "bucketCounts": dict(Counter(record["bucket"] for record in records)),
+        },
+        layout=hv.ui.PanelLayout(width=520, min_width=420),
+    )
+    return hv.ui.View(
+        samples_panel,
+        readout_panel,
+        primary_scatter,
+    )
+
+
+def launch_demo(dataset: hv.Dataset, layouts: dict[str, str], records: list[dict[str, Any]]) -> hv.Session:
+    session = hv.launch(
+        dataset,
+        host=SPACE_HOST,
+        port=SPACE_PORT,
+        open_browser=False,
+        workspace_id=WORKSPACE_ID,
+        block=False,
+    )
+    print("Installing Open Images visual-safety demo extension...", flush=True)
+    session.ui.add_extension(EXTENSION_DIR, workspace_id=WORKSPACE_ID)
+    print("Applying Open Images visual-safety triage demo view...", flush=True)
+    session.ui.apply_view(build_demo_view(dataset, layouts, records), workspace_id=WORKSPACE_ID)
+    session.ui.set_active_layout(layouts["candidate"], workspace_id=WORKSPACE_ID)
+    session.ui.set_selection([], workspace_id=WORKSPACE_ID)
+    print(f"\nHyperView Open Images visual-safety demo is running at {session.url}", flush=True)
+    return session
+
+
+def main() -> None:
+    dataset, layouts, records = build_dataset()
+    print("Layouts:", flush=True)
+    for spec in MODEL_SPECS:
+        print(f"  {spec['display_name']}: {layouts[spec['key']]}", flush=True)
+    session = launch_demo(dataset, layouts, records)
+    session.wait()
+
+
+if __name__ == "__main__":
+    main()