Deploy DeepFashion text search demo

.dockerignore

@@ -0,0 +1,4 @@
+demo_data/
+__pycache__/
+*.pyc
+.DS_Store

.hyperview/extensions/fashion-search-readout/extension.toml

@@ -0,0 +1,8 @@
+name = "fashion-search-readout"
+description = "DeepFashion CLIP vs Hyper3-CLIP text-search readout"
+
+[[panels]]
+id = "fashion-comparison"
+title = "Fashion Search Readout"
+position = "right"
+file = "panel.js"

.hyperview/extensions/fashion-search-readout/panel.js

@@ -0,0 +1,637 @@
+import { rankedResults } from "./ranked_results.js";
+
+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 {
+  usePanelClient,
+  usePanelSelection,
+  usePanelSamples,
+  usePanelCommands,
+  usePanelProps,
+} = hooks;
+
+const colors = {
+  panelBg: "#111827",
+  cardBg: "#161f2d",
+  buttonBg: "#1f2937",
+  border: "#334155",
+  text: "#e5e7eb",
+  strongText: "#f8fafc",
+  mutedText: "#9ca3af",
+  bodyText: "#cbd5e1",
+  accent: "#93c5fd",
+  success: "#86efac",
+  warningBg: "#3b2f12",
+  warningBorder: "#92400e",
+  warningText: "#fde68a",
+  error: "#fca5a5",
+};
+
+function Section({ title, children }) {
+  return React.createElement(
+    "section",
+    { style: { display: "flex", flexDirection: "column", gap: 8 } },
+    React.createElement(
+      "h3",
+      {
+        style: {
+          margin: 0,
+          color: colors.strongText,
+          fontSize: 13,
+          fontWeight: 700,
+        },
+      },
+      title,
+    ),
+    children,
+  );
+}
+
+function TextBlock({ children }) {
+  return React.createElement(
+    "div",
+    { style: { color: colors.bodyText, fontSize: 12, lineHeight: 1.45 } },
+    children,
+  );
+}
+
+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,
+      spaceKey: model.spaceKey || model.space_key || null,
+    }))
+    .filter((model) => model.layoutKey);
+}
+
+function getSummary(item, modelKey) {
+  return item.summaries?.[modelKey] || item.modelSummaries?.[modelKey] || {};
+}
+
+function rankLabel(rank) {
+  return rank === 0 || rank ? `#${rank}` : "-";
+}
+
+function pct(value) {
+  if (typeof value !== "number") return "-";
+  return `${(value * 100).toFixed(1)}%`;
+}
+
+function metricValue(value, kind = "pct") {
+  if (typeof value !== "number") return "-";
+  if (kind === "decimal") return value.toFixed(3);
+  return pct(value);
+}
+
+function modelAccent(model) {
+  return model.key === "candidate" ? colors.success : colors.bodyText;
+}
+
+function modelBorder(model) {
+  return model.key === "candidate" ? "#3f6f5b" : colors.border;
+}
+
+function MetricGrid({ rows }) {
+  return React.createElement(
+    "div",
+    {
+      style: {
+        display: "grid",
+        gridTemplateColumns: "1.5fr 1fr 1fr",
+        border: `1px solid ${colors.border}`,
+        borderRadius: 6,
+        overflow: "hidden",
+        fontSize: 11,
+      },
+    },
+    React.createElement("div", { style: headerCellStyle() }, "Metric"),
+    React.createElement("div", { style: headerCellStyle() }, "Hyper3"),
+    React.createElement("div", { style: headerCellStyle() }, "CLIP"),
+    rows.flatMap((row) => [
+      React.createElement("div", { key: `${row.label}-label`, style: bodyCellStyle() }, row.label),
+      React.createElement(
+        "div",
+        { key: `${row.label}-h`, style: bodyCellStyle(colors.success) },
+        metricValue(row.hyper3, row.kind),
+      ),
+      React.createElement(
+        "div",
+        { key: `${row.label}-c`, style: bodyCellStyle() },
+        metricValue(row.clip, row.kind),
+      ),
+    ]),
+  );
+}
+
+function headerCellStyle() {
+  return {
+    background: "#0f172a",
+    borderBottom: `1px solid ${colors.border}`,
+    color: colors.strongText,
+    fontWeight: 700,
+    padding: 7,
+  };
+}
+
+function bodyCellStyle(color = colors.bodyText) {
+  return {
+    borderTop: `1px solid ${colors.border}`,
+    color,
+    padding: 7,
+  };
+}
+
+function ExampleChooser({ examples, selectedId, onSelect }) {
+  return React.createElement(
+    "div",
+    { style: { display: "grid", gridTemplateColumns: "1fr", gap: 6 } },
+    examples.map((item) => {
+      const active = item.id === selectedId;
+      return React.createElement(
+        "button",
+        {
+          key: item.id,
+          type: "button",
+          onClick: () => onSelect(item.id),
+          style: {
+            border: `1px solid ${active ? colors.accent : colors.border}`,
+            background: active ? "rgba(147, 197, 253, 0.08)" : colors.cardBg,
+            color: colors.text,
+            borderRadius: 5,
+            padding: "7px 8px",
+            textAlign: "left",
+            cursor: "pointer",
+          },
+        },
+        React.createElement(
+          "div",
+          { style: { color: colors.strongText, fontSize: 12, fontWeight: 700, marginBottom: 2 } },
+          item.title,
+        ),
+        React.createElement(
+          "div",
+          {
+            style: {
+              color: colors.bodyText,
+              fontSize: 10,
+              lineHeight: 1.3,
+              overflow: "hidden",
+              textOverflow: "ellipsis",
+              whiteSpace: "nowrap",
+            },
+          },
+          item.query,
+        ),
+      );
+    }),
+  );
+}
+
+function ResultCard({ result, model, loadingKey, onSelectResult }) {
+  const choiceKey = `${result.sampleId}:${model.key}:ranked-result`;
+  return React.createElement(
+    "button",
+    {
+      type: "button",
+      onClick: () => onSelectResult(result, model),
+      disabled: loadingKey === choiceKey,
+      title: `Select rank ${result.rank} in ${model.displayName}`,
+      style: {
+        width: 82,
+        flex: "0 0 82px",
+        border: `1px solid ${result.isTarget ? colors.success : colors.border}`,
+        background: result.isTarget ? "rgba(134, 239, 172, 0.06)" : "#0f172a",
+        color: colors.text,
+        borderRadius: 5,
+        padding: 4,
+        textAlign: "left",
+        cursor: loadingKey === choiceKey ? "default" : "pointer",
+        opacity: loadingKey === choiceKey ? 0.65 : 1,
+      },
+    },
+    React.createElement(
+      "div",
+      {
+        style: {
+          display: "flex",
+          justifyContent: "space-between",
+          alignItems: "center",
+          gap: 4,
+          marginBottom: 4,
+        },
+      },
+      React.createElement(
+        "span",
+        { style: { color: colors.strongText, fontSize: 10, fontWeight: 700 } },
+        `#${result.rank}`,
+      ),
+      result.isTarget
+        ? React.createElement(
+            "span",
+            { style: { color: colors.success, fontSize: 8, fontWeight: 700 } },
+            "target",
+          )
+        : null,
+    ),
+    React.createElement("img", {
+      src: result.image,
+      alt: `${model.displayName} rank ${result.rank}`,
+      style: {
+        width: "100%",
+        height: 90,
+        objectFit: "cover",
+        borderRadius: 3,
+        background: "#ffffff",
+        display: "block",
+        marginBottom: 4,
+      },
+    }),
+    React.createElement(
+      "div",
+      {
+        style: {
+          color: colors.mutedText,
+          fontSize: 8,
+          lineHeight: 1.2,
+          overflow: "hidden",
+          display: "-webkit-box",
+          WebkitLineClamp: 2,
+          WebkitBoxOrient: "vertical",
+        },
+      },
+      `${result.color || "unknown"} ${result.category || ""}`.trim(),
+    ),
+  );
+}
+
+function RankedResultStrip({ item, model, rows, targetRank, loadingKey, onSelectResult }) {
+  return React.createElement(
+    "div",
+    {
+      style: {
+        border: `1px solid ${modelBorder(model)}`,
+        borderRadius: 6,
+        background: colors.cardBg,
+        padding: 7,
+        display: "flex",
+        flexDirection: "column",
+        gap: 6,
+      },
+    },
+    React.createElement(
+      "div",
+      { style: { display: "flex", justifyContent: "space-between", gap: 8, alignItems: "baseline" } },
+      React.createElement(
+        "div",
+        { style: { color: colors.strongText, fontSize: 12, fontWeight: 700 } },
+        model.displayName,
+      ),
+      React.createElement(
+        "div",
+        { style: { color: modelAccent(model), fontSize: 11, fontWeight: 700 } },
+        `exact target ${rankLabel(targetRank)}`,
+      ),
+    ),
+    React.createElement(
+      "div",
+      { style: { display: "flex", gap: 7, overflowX: "auto", paddingBottom: 2 } },
+      rows.map((result) =>
+        React.createElement(ResultCard, {
+          key: `${item.id}-${model.key}-${result.rank}-${result.itemId}`,
+          result,
+          model,
+          loadingKey,
+          onSelectResult,
+        }),
+      ),
+    ),
+  );
+}
+
+function SearchResultComparison({ item, models, loadingKey, onSelectResult }) {
+  const proof = rankedResults[item.id];
+  if (!proof) {
+    return React.createElement(
+      "div",
+      { style: { color: colors.bodyText, fontSize: 12, lineHeight: 1.45 } },
+      "Ranked results are not configured for this query.",
+    );
+  }
+
+  return React.createElement(
+    "div",
+    { style: { display: "flex", flexDirection: "column", gap: 7 } },
+    React.createElement(
+      "div",
+      {
+        style: {
+          border: `1px solid ${colors.border}`,
+          borderRadius: 5,
+          background: "#0f172a",
+          padding: 7,
+          color: colors.bodyText,
+          fontSize: 11,
+          lineHeight: 1.35,
+        },
+      },
+      React.createElement("strong", { style: { color: colors.strongText } }, "Selected query: "),
+      item.query,
+      React.createElement(
+        "div",
+        { style: { color: colors.mutedText, fontSize: 10, marginTop: 3 } },
+        "Green card = exact product. Click any card to select it in the map.",
+      ),
+    ),
+    models.map((model) =>
+      React.createElement(RankedResultStrip, {
+        key: `${item.id}-${model.key}-ranked-results`,
+        item,
+        model,
+        rows: proof.results?.[model.key] || [],
+        targetRank: proof.targetRanks?.[model.key],
+        loadingKey,
+        onSelectResult,
+      }),
+    ),
+  );
+}
+
+function ExactTargetActions({ item, models, loadingKey, onSelectQuery }) {
+  const gridColumns = models.length > 1 ? "repeat(2, minmax(0, 1fr))" : "1fr";
+
+  return React.createElement(
+    "div",
+    { style: { display: "grid", gridTemplateColumns: gridColumns, gap: 7 } },
+      models.map((model) => {
+        const summary = getSummary(item, model.key);
+        const isCandidate = model.key === "candidate";
+        const targetRank = rankLabel(summary.rank);
+        const neighborLine =
+          typeof summary.categoryHits === "number"
+            ? `${summary.categoryHits}/${summary.total || 10} same-category image neighbors`
+            : "Open the map to inspect image neighbors";
+        const choiceKey = `${item.queryId}:${model.key}`;
+        return React.createElement(
+          "button",
+          {
+            key: model.key,
+            type: "button",
+            onClick: () => onSelectQuery(item, model),
+            disabled: loadingKey === choiceKey,
+            title: `Select target item and inspect ${model.displayName} image neighbors`,
+            style: {
+              border: `1px solid ${modelBorder(model)}`,
+              borderRadius: 5,
+              padding: 8,
+              background: isCandidate ? "rgba(134, 239, 172, 0.06)" : "transparent",
+              color: colors.text,
+              textAlign: "left",
+              cursor: loadingKey === choiceKey ? "default" : "pointer",
+              opacity: loadingKey === choiceKey ? 0.65 : 1,
+            },
+          },
+          React.createElement(
+            "div",
+            { style: { display: "flex", justifyContent: "space-between", gap: 8, marginBottom: 4 } },
+            React.createElement(
+              "span",
+              { style: { color: colors.strongText, fontSize: 12, fontWeight: 700 } },
+              model.displayName,
+            ),
+            React.createElement(
+              "span",
+              { style: { color: modelAccent(model), fontSize: 11, fontWeight: 700 } },
+              `target ${targetRank}`,
+            ),
+          ),
+          React.createElement(
+            "div",
+            { style: { color: isCandidate ? colors.success : colors.bodyText, fontSize: 11, lineHeight: 1.35 } },
+            summary.text || "",
+          ),
+          React.createElement(
+            "div",
+            { style: { color: colors.mutedText, fontSize: 10, lineHeight: 1.35, marginTop: 5 } },
+            loadingKey === choiceKey ? "Loading map selection..." : neighborLine,
+          ),
+        );
+      }),
+  );
+}
+
+export default function FashionSearchComparisonPanel() {
+  const client = usePanelClient();
+  const selection = usePanelSelection();
+  const samplesState = usePanelSamples();
+  const commands = usePanelCommands();
+  const panelProps = usePanelProps();
+  const [panelError, setPanelError] = React.useState(null);
+  const [loadingKey, setLoadingKey] = React.useState(null);
+  const [selectedExampleId, setSelectedExampleId] = React.useState(null);
+
+  const models = React.useMemo(() => normalizeModels(panelProps.models), [panelProps.models]);
+  const examples = Array.isArray(panelProps.examples) ? panelProps.examples : [];
+  const warnings = Array.isArray(panelProps.warnings) ? panelProps.warnings.filter(Boolean) : [];
+  const metrics = panelProps.metrics || {};
+  const selectedExample =
+    examples.find((item) => item.id === selectedExampleId) || examples[0] || null;
+  const typedMetricRows = [
+    { label: "Typed search Hit@1", hyper3: metrics.typedHit1Hyper3, clip: metrics.typedHit1Clip },
+    { label: "Typed search Hit@10", hyper3: metrics.typedHit10Hyper3, clip: metrics.typedHit10Clip },
+    {
+      label: "Typed category P@10",
+      hyper3: metrics.typedCategoryP10Hyper3,
+      clip: metrics.typedCategoryP10Clip,
+    },
+    { label: "Typed search MRR", hyper3: metrics.typedMrrHyper3, clip: metrics.typedMrrClip, kind: "decimal" },
+  ];
+  const imageMetricRows = [
+    { label: "Image-to-image mAP", hyper3: metrics.imageRetrievalMapHyper3, clip: metrics.imageRetrievalMapClip },
+  ];
+
+  const clearSelection = async () => {
+    if (commands.setLabelFilter) commands.setLabelFilter(null);
+    setPanelError(null);
+    await client.clearSimilarityQuery();
+    await commands.clearSelection();
+  };
+
+  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, { persist: false });
+      await commands.showSimilar({
+        sampleId: item.queryId,
+        layoutKey: model.layoutKey,
+        spaceKey: model.spaceKey,
+        k: 10,
+        source: `fashion-demo:${model.key}`,
+        focus: false,
+        persist: false,
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      setPanelError(`Could not select target item: ${message}`);
+    } finally {
+      setLoadingKey(null);
+    }
+  };
+
+  const selectRankedResult = async (result, model) => {
+    const key = `${result.sampleId}:${model.key}:ranked-result`;
+    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, { persist: false });
+      await commands.showSimilar({
+        sampleId: result.sampleId,
+        layoutKey: model.layoutKey,
+        spaceKey: model.spaceKey,
+        k: 10,
+        source: `fashion-ranked-result:${model.key}`,
+        focus: false,
+        persist: false,
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      setPanelError(`Could not select ranked result: ${message}`);
+    } finally {
+      setLoadingKey(null);
+    }
+  };
+
+  return React.createElement(
+    Panel,
+    { className: "h-full" },
+    React.createElement(PanelToolbar, {
+      items: [
+        { id: "dataset", label: "Data", value: "DeepFashion" },
+        { 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: 14,
+          background: colors.panelBg,
+        },
+      },
+      React.createElement(
+        Section,
+        { title: "Pick A Shopper Query" },
+        React.createElement(
+          TextBlock,
+          null,
+          "Choose a typed product search, then compare the ranked image results.",
+        ),
+        examples.length
+          ? React.createElement(ExampleChooser, {
+              examples,
+              selectedId: selectedExample?.id,
+              onSelect: setSelectedExampleId,
+            })
+          : React.createElement(
+              "div",
+              { style: { color: colors.bodyText, fontSize: 12, lineHeight: 1.45 } },
+              "Demo examples are not configured.",
+            ),
+        selectedExample && models.length
+          ? React.createElement(SearchResultComparison, {
+              item: selectedExample,
+              models,
+              loadingKey,
+              onSelectResult: selectRankedResult,
+            })
+          : null,
+      ),
+      React.createElement(
+        Section,
+        { title: "Inspect Exact Target" },
+        React.createElement(
+          TextBlock,
+          null,
+          `Select the same target product in the map: ${selectedExample?.targetTitle || "target product"}.`,
+        ),
+        selectedExample && models.length
+          ? React.createElement(ExactTargetActions, {
+              item: selectedExample,
+              models,
+              loadingKey,
+              onSelectQuery: selectModelQuery,
+            })
+          : React.createElement(
+              "div",
+              { style: { color: colors.bodyText, fontSize: 12, lineHeight: 1.45 } },
+              "Demo examples are not configured.",
+            ),
+      ),
+      warnings.length
+        ? React.createElement(
+            "div",
+            {
+              style: {
+                border: `1px solid ${colors.warningBorder}`,
+                borderRadius: 4,
+                background: colors.warningBg,
+                color: colors.warningText,
+                padding: 8,
+                fontSize: 11,
+                lineHeight: 1.35,
+              },
+            },
+            warnings[0],
+          )
+        : null,
+      React.createElement(
+        Section,
+        { title: "Benchmark Details" },
+        React.createElement(
+          TextBlock,
+          null,
+          "Bottom reference only. The result strips above are the main demo; these numbers keep the probe traceable.",
+        ),
+        React.createElement(MetricGrid, { rows: typedMetricRows }),
+        React.createElement(
+          TextBlock,
+          null,
+          "Separate image-to-image check, shown only for context because it is not the typed shopper search task.",
+        ),
+        React.createElement(MetricGrid, { rows: imageMetricRows }),
+      ),
+      panelError
+        ? React.createElement(
+            "div",
+            { style: { color: colors.error, fontSize: 11, lineHeight: 1.35 } },
+            panelError,
+          )
+        : null,
+    ),
+  );
+}

Dockerfile

@@ -0,0 +1,56 @@
+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 HYPERVIEW_VERSION=0.6.1
+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
+RUN echo "Installing hyperview==${HYPERVIEW_VERSION}" \
+    && pip install "hyperview==${HYPERVIEW_VERSION}" \
+    && python - <<'PY'
+import inspect
+import hyperview as hv
+
+print("hyperview", hv.__version__, inspect.signature(hv.launch))
+PY
+RUN pip install \
+    "hyper-models[ml]==${HYPER_MODELS_VERSION}" \
+    "datasets>=4.5.0" \
+    "Pillow>=12.0.0"
+
+COPY --chown=user . .
+
+ENV HYPERVIEW_HOST=0.0.0.0 \
+    HYPERVIEW_PORT=7860 \
+    HYPERVIEW_WORKSPACE_ID=fashion-deepfashion-text-search \
+    HYPERVIEW_DATASETS_DIR=/home/user/app/demo_data/datasets \
+    HYPERVIEW_MEDIA_DIR=/home/user/app/demo_data/media \
+    HF_HUB_ETAG_TIMEOUT=30 \
+    HF_HUB_DOWNLOAD_TIMEOUT=120
+
+EXPOSE 7860
+
+HEALTHCHECK --interval=30s --timeout=10s --start-period=2700s --retries=3 \
+    CMD curl -f http://localhost:7860/__hyperview__/health || exit 1
+
+CMD ["python", "demo.py"]

README.md

@@ -1,10 +1,65 @@
 ---
 title: HyperView DeepFashion Text Search
-emoji: 😻
-colorFrom: green
-colorTo: purple
+emoji: 👖
+colorFrom: blue
+colorTo: indigo
 sdk: docker
+app_port: 7860
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# HyperView - DeepFashion Text Search Comparison
+
+This demo loads a curated DeepFashion In-Shop subset into HyperView and compares:
+
+- CLIP ViT-B/32 in a Euclidean 2D layout
+- Hyper3-CLIP `hyper3-clip-v0.5` in a Poincare 2D layout
+
+The main readout is built for a retail search buyer. It shows fixed text-to-image examples where a shopper-style query asks for a specific item and the exact target product appears much earlier under Hyper3-CLIP than under CLIP.
+
+## Business Story
+
+The demo is not "another embedding map." The buyer-facing story is:
+
+- Product search often fails by returning almost-right variants.
+- Fashion queries combine color, fit, fabric, cut, and construction details.
+- In the DeepFashion text-to-image probe, Hyper3-CLIP has a small aggregate edge and concrete examples where the exact item appears on the first screen while CLIP buries it.
+- The best example is a query for light denim leggings with skinny fit, zipper details, five-pocket construction, and pockets: Hyper3 ranks the exact target first; CLIP first surfaces it at rank 32.
+
+Use the ranked result strips first. Then use the compact map buttons to inspect the same target item under each embedding space. The text-search ranks are precomputed from the bounded DeepFashion probe; the maps provide visual neighborhood context for the same fashion items.
+
+## What Is In The Demo
+
+- Three shopper-style query examples with ranked CLIP vs Hyper3-CLIP image results.
+- Exact-target rank readouts for each model.
+- Clickable result cards that select the product in the active HyperView map.
+- A compact benchmark footer for traceability, with text-to-image numbers separated from the older image-to-image retrieval check.
+
+This is a demo probe, not a broad production benchmark. It is meant to show the failure mode: specific text-to-image product search where exact-item rank matters.
+
+## Run Locally
+
+From the HyperView repository:
+
+```bash
+uv run python hyperview-spaces/spaces/fashion-deepfashion-text-search-clip-hyper3clip/demo.py
+```
+
+Useful overrides:
+
+```bash
+HYPERVIEW_PORT=6265 DEEPFASHION_SAMPLES_PER_CATEGORY=30 \
+  uv run python hyperview-spaces/spaces/fashion-deepfashion-text-search-clip-hyper3clip/demo.py
+```
+
+## Benchmark Context
+
+Landing-page-safe wording:
+
+> On a bounded DeepFashion text-to-image probe, Hyper3-CLIP has a small aggregate top-10 edge over CLIP-B/32 and produces concrete typed-search wins. In one query for light denim leggings with specific construction details, Hyper3 ranks the target product first while CLIP does not surface it until rank 32.
+
+Do not present this as a broad claim against every modern multimodal embedding model. We have not yet added SigLIP, Jina-CLIP, NV-CLIP, or Gemini Embedding 2 to this demo.
+
+## Deploy Source
+
+This folder is intended to deploy to `hyper3labs/HyperView-DeepFashion-Text-Search` from the `hyperview-spaces` deployment repository.

demo.py

@@ -0,0 +1,443 @@
+#!/usr/bin/env python
+"""DeepFashion text-search comparison demo for CLIP vs Hyper3-CLIP in HyperView."""
+
+from __future__ import annotations
+
+import os
+import re
+from collections import Counter
+from pathlib import Path
+from typing import Any
+
+from datasets import load_dataset
+from PIL import Image, ImageOps
+
+import hyperview as hv
+
+
+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", "fashion-deepfashion-text-search")
+DATASET_NAME = os.environ.get("HYPERVIEW_DATASET_NAME", "deepfashion_text_search_clip_hyper3clip")
+EXTENSION_DIR = SPACE_DIR / ".hyperview" / "extensions" / "fashion-search-readout"
+
+HF_DATASET = os.environ.get("DEEPFASHION_HF_DATASET", "Marqo/deepfashion-inshop")
+HF_SPLIT = os.environ.get("DEEPFASHION_HF_SPLIT", "data")
+SAMPLES_PER_CATEGORY = int(os.environ.get("DEEPFASHION_SAMPLES_PER_CATEGORY", "45"))
+MAX_SAMPLES = int(os.environ.get("DEEPFASHION_MAX_SAMPLES", "700"))
+IMAGE_MAX_SIZE = (768, 768)
+FORCE_SAMPLE_REFRESH = os.environ.get("HYPERVIEW_DEEPFASHION_FORCE_REFRESH", "").lower() in {
+    "1",
+    "true",
+    "yes",
+}
+ALLOW_CANDIDATE_FALLBACK = os.environ.get("HYPERVIEW_ALLOW_CANDIDATE_FALLBACK", "1").lower() in {
+    "1",
+    "true",
+    "yes",
+}
+RUNTIME_WARNINGS: list[str] = []
+
+MODEL_SPECS = [
+    {
+        "key": "clip",
+        "display_name": os.environ.get("FASHION_BASELINE_DISPLAY_NAME", "CLIP"),
+        "button_label": os.environ.get("FASHION_BASELINE_BUTTON_LABEL", "Inspect CLIP neighbors"),
+        "provider": os.environ.get("FASHION_BASELINE_PROVIDER", "embed-anything"),
+        "model": os.environ.get("FASHION_BASELINE_MODEL", "openai/clip-vit-base-patch32"),
+        "layout": os.environ.get("FASHION_BASELINE_LAYOUT", "euclidean:2d"),
+        "geometry": os.environ.get("FASHION_BASELINE_GEOMETRY", "euclidean"),
+        "layout_dimension": int(os.environ.get("FASHION_BASELINE_LAYOUT_DIMENSION", "2")),
+        "metric": os.environ.get("FASHION_BASELINE_METRIC", "cosine"),
+        "panel_title": os.environ.get("FASHION_BASELINE_PANEL_TITLE", "CLIP - Fashion Catalog Map"),
+    },
+    {
+        "key": "candidate",
+        "display_name": os.environ.get("FASHION_CANDIDATE_DISPLAY_NAME", "Hyper3-CLIP"),
+        "button_label": os.environ.get("FASHION_CANDIDATE_BUTTON_LABEL", "Inspect Hyper3-CLIP neighbors"),
+        "provider": os.environ.get("FASHION_CANDIDATE_PROVIDER", "hyper-models"),
+        "model": os.environ.get("FASHION_CANDIDATE_MODEL", "hyper3-clip-v0.5"),
+        "layout": os.environ.get("FASHION_CANDIDATE_LAYOUT", "poincare:2d"),
+        "geometry": os.environ.get("FASHION_CANDIDATE_GEOMETRY", "poincare"),
+        "layout_dimension": int(os.environ.get("FASHION_CANDIDATE_LAYOUT_DIMENSION", "2")),
+        "metric": os.environ.get("FASHION_CANDIDATE_METRIC", "cosine"),
+        "panel_title": os.environ.get("FASHION_CANDIDATE_PANEL_TITLE", "Hyper3-CLIP - Fashion Catalog Map"),
+    },
+]
+
+TEXT_SEARCH_EXAMPLES = [
+    {
+        "id": "light-denim-leggings",
+        "title": "Light denim leggings",
+        "targetItemId": "WOMEN_Leggings_id_00001867_02_3_back",
+        "targetProduct": "WOMEN_Leggings_id_00001867_02",
+        "targetTitle": "women's light denim leggings",
+        "family": "Specific typed product search",
+        "query": "women's light denim leggings with skinny fit, zipper details, five-pocket construction, pockets",
+        "hyper3Rank": 1,
+        "clipRank": 32,
+        "hyper3Text": "Exact target is the first result.",
+        "clipText": "Top results drift to dark denim, black, and similar blue leggings before the exact item appears.",
+    },
+    {
+        "id": "olive-navy-pants",
+        "title": "Olive and navy drawstring pants",
+        "targetItemId": "MEN_Pants_id_00001468_03_6_flat",
+        "targetProduct": "MEN_Pants_id_00001468_03",
+        "targetTitle": "men's olive and navy drawstring pants",
+        "family": "Specific typed product search",
+        "query": "men's olive and navy pants with drawstring waist, pockets, striped pattern, knit fabric",
+        "hyper3Rank": 1,
+        "clipRank": 56,
+        "hyper3Text": "Exact target is the first result.",
+        "clipText": "CLIP ranks burgundy pants and visually similar pants before the requested product.",
+    },
+    {
+        "id": "cream-blue-halter-blouse",
+        "title": "Cream and blue halter blouse",
+        "targetItemId": "WOMEN_Blouses_Shirts_id_00007161_02_1_front",
+        "targetProduct": "WOMEN_Blouses_Shirts_id_00007161_02",
+        "targetTitle": "cream and blue halter blouse",
+        "family": "Attribute-heavy apparel search",
+        "query": "women's cream and blue blouse with halter neckline, floral pattern, striped pattern, tribal print",
+        "hyper3Rank": 4,
+        "clipRank": 33,
+        "hyper3Text": "Target views appear in the top 10.",
+        "clipText": "CLIP retrieves broadly similar tops but misses the exact blouse in the first screen.",
+    },
+]
+
+DEMO_RESULT_ITEM_IDS = {
+    "MEN_Pants_id_00001468_03_6_flat",
+    "MEN_Pants_id_00001468_04_6_flat",
+    "MEN_Pants_id_00004045_03_2_side",
+    "MEN_Pants_id_00004045_04_1_front",
+    "MEN_Pants_id_00004045_09_3_back",
+    "MEN_Pants_id_00004045_11_1_front",
+    "MEN_Pants_id_00004045_11_2_side",
+    "MEN_Pants_id_00004045_12_1_front",
+    "MEN_Pants_id_00004045_12_2_side",
+    "MEN_Pants_id_00004045_12_3_back",
+    "MEN_Pants_id_00004045_12_7_additional",
+    "MEN_Shirts_Polos_id_00007027_01_6_flat",
+    "MEN_Sweaters_id_00005177_03_2_side",
+    "MEN_Sweaters_id_00005177_03_3_back",
+    "MEN_Sweaters_id_00005177_03_4_full",
+    "WOMEN_Blouses_Shirts_id_00003641_01_1_front",
+    "WOMEN_Blouses_Shirts_id_00006345_01_7_additional",
+    "WOMEN_Blouses_Shirts_id_00007049_01_7_additional",
+    "WOMEN_Blouses_Shirts_id_00007161_02_1_front",
+    "WOMEN_Cardigans_id_00000521_02_3_back",
+    "WOMEN_Denim_id_00000152_04_1_front",
+    "WOMEN_Denim_id_00000152_04_2_side",
+    "WOMEN_Denim_id_00002338_02_7_additional",
+    "WOMEN_Denim_id_00002338_03_1_front",
+    "WOMEN_Denim_id_00002338_03_3_back",
+    "WOMEN_Denim_id_00002338_03_7_additional",
+    "WOMEN_Denim_id_00005673_02_3_back",
+    "WOMEN_Dresses_id_00006961_02_1_front",
+    "WOMEN_Leggings_id_00001412_01_2_side",
+    "WOMEN_Leggings_id_00001867_02_3_back",
+    "WOMEN_Leggings_id_00002130_02_2_side",
+    "WOMEN_Leggings_id_00003850_01_2_side",
+    "WOMEN_Leggings_id_00003908_07_2_side",
+    "WOMEN_Leggings_id_00003908_08_2_side",
+    "WOMEN_Leggings_id_00004562_01_3_back",
+    "WOMEN_Pants_id_00000053_02_1_front",
+    "WOMEN_Pants_id_00001574_02_3_back",
+    "WOMEN_Rompers_Jumpsuits_id_00004432_02_3_back",
+    "WOMEN_Rompers_Jumpsuits_id_00004653_02_2_side",
+    "WOMEN_Rompers_Jumpsuits_id_00005484_01_3_back",
+    "WOMEN_Sweaters_id_00003304_01_1_front",
+    "WOMEN_Sweaters_id_00003304_01_2_side",
+    "WOMEN_Tees_Tanks_id_00000676_01_1_front",
+    "WOMEN_Tees_Tanks_id_00000676_01_2_side",
+}
+
+
+def media_root() -> Path:
+    root = Path(os.environ.get("HYPERVIEW_MEDIA_DIR", str(SPACE_DIR / "demo_data" / "media")))
+    path = root / DATASET_NAME
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def product_key(item_id: str) -> str:
+    return re.sub(r"_\d+_[A-Za-z]+$", "", str(item_id))
+
+
+def safe_sample_id(item_id: str) -> str:
+    return re.sub(r"[^A-Za-z0-9_.-]+", "_", str(item_id)).strip("_")[:96]
+
+
+def readable(value: Any) -> str:
+    text = str(value or "").replace("_", " ").replace("-", " ")
+    return re.sub(r"\s+", " ", text).strip()
+
+
+def save_image(image: Image.Image, destination: Path) -> None:
+    if destination.exists() and destination.stat().st_size > 0 and not FORCE_SAMPLE_REFRESH:
+        return
+    tmp_path = destination.with_suffix(destination.suffix + ".tmp")
+    image = ImageOps.exif_transpose(image).convert("RGB")
+    image.thumbnail(IMAGE_MAX_SIZE, Image.Resampling.LANCZOS)
+    image.save(tmp_path, format="JPEG", quality=92, optimize=True)
+    tmp_path.replace(destination)
+
+
+def select_deepfashion_records() -> list[dict[str, Any]]:
+    print(f"Loading DeepFashion split {HF_SPLIT!r} from {HF_DATASET}...", flush=True)
+    source = load_dataset(HF_DATASET, split=HF_SPLIT)
+    required_products = {example["targetProduct"] for example in TEXT_SEARCH_EXAMPLES}
+    required_item_ids = {example["targetItemId"] for example in TEXT_SEARCH_EXAMPLES} | DEMO_RESULT_ITEM_IDS
+    selected: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    category_counts: Counter[str] = Counter()
+
+    for index, row in enumerate(source):
+        item_id = str(row["item_ID"])
+        category = str(row.get("category2") or "unknown")
+        product = product_key(item_id)
+        required = product in required_products or item_id in required_item_ids
+        balanced = category_counts[category] < SAMPLES_PER_CATEGORY and len(selected) < MAX_SAMPLES
+        if not required and not balanced:
+            continue
+        if item_id in seen:
+            continue
+        selected.append({"index": index, **row})
+        seen.add(item_id)
+        category_counts[category] += 1
+
+    missing = sorted(required_item_ids - seen)
+    if missing:
+        raise RuntimeError(f"Missing required demo items from DeepFashion: {missing}")
+    print(f"Selected {len(selected)} DeepFashion images: {dict(category_counts)}", flush=True)
+    return selected
+
+
+def add_deepfashion_samples(dataset: hv.Dataset) -> None:
+    existing_ids = {sample.id for sample in dataset.samples}
+    media_dir = media_root()
+    added = 0
+    updated = 0
+    records = select_deepfashion_records()
+
+    for record in records:
+        item_id = str(record["item_ID"])
+        sample_id = safe_sample_id(item_id)
+        destination = media_dir / f"{sample_id}.jpg"
+        save_image(record["image"], destination)
+        category = readable(record.get("category2") or "unknown").lower()
+        color = readable(record.get("color") or "unknown")
+        metadata = {
+            "item_id": item_id,
+            "product_key": product_key(item_id),
+            "gender": readable(record.get("category1") or "unknown"),
+            "category": category,
+            "subcategory": readable(record.get("category3") or "unknown"),
+            "color": color,
+            "description": readable(record.get("description") or ""),
+            "text": readable(record.get("text") or ""),
+            "source_dataset": HF_DATASET,
+            "split": HF_SPLIT,
+        }
+        existed = sample_id in existing_ids
+        dataset.add_image(str(destination), label=category, metadata=metadata, sample_id=sample_id)
+        if existed:
+            updated += 1
+        else:
+            existing_ids.add(sample_id)
+            added += 1
+    print(f"Prepared DeepFashion samples ({added} added, {updated} updated).", flush=True)
+
+
+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)
+        try:
+            space_key = dataset.compute_embeddings(
+                model=spec["model"],
+                provider=spec["provider"],
+                batch_size=32,
+                show_progress=True,
+            )
+        except Exception as exc:
+            if spec["key"] == "candidate" and ALLOW_CANDIDATE_FALLBACK and "clip" in layouts:
+                warning = (
+                    f"Hyper3-CLIP embeddings are unavailable ({type(exc).__name__}: {exc}). "
+                    "Showing the CLIP layout as a clearly labeled fallback so the Space can start."
+                )
+                print(warning, flush=True)
+                RUNTIME_WARNINGS.append(warning)
+                spec.update(
+                    {
+                        "display_name": "Hyper3-CLIP unavailable (CLIP fallback)",
+                        "button_label": "Inspect CLIP fallback neighbors",
+                        "geometry": MODEL_SPECS[0]["geometry"],
+                        "layout_dimension": MODEL_SPECS[0]["layout_dimension"],
+                        "panel_title": "Hyper3-CLIP unavailable - showing CLIP fallback",
+                        "fallback": True,
+                        "space_key": MODEL_SPECS[0].get("space_key"),
+                    }
+                )
+                layouts[spec["key"]] = layouts["clip"]
+                continue
+            raise
+        spec["space_key"] = space_key
+        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]]:
+    dataset = hv.Dataset(DATASET_NAME)
+    add_deepfashion_samples(dataset)
+    layouts = ensure_layouts(dataset)
+    return dataset, layouts
+
+
+def space_key_from_layout(layout_key: str) -> str:
+    return layout_key.split("__euclidean_umap", 1)[0].split("__poincare_umap", 1)[0]
+
+
+def model_panel_props(layouts: dict[str, str]) -> list[dict[str, Any]]:
+    props = []
+    for spec in MODEL_SPECS:
+        layout_key = layouts[spec["key"]]
+        props.append(
+            {
+                "key": spec["key"],
+                "displayName": spec["display_name"],
+                "buttonLabel": spec["button_label"],
+                "layoutKey": layout_key,
+                "spaceKey": spec.get("space_key") or space_key_from_layout(layout_key),
+            }
+        )
+    return props
+
+
+def neighbor_summary(dataset: hv.Dataset, sample_id: str, model_key: str) -> dict[str, Any]:
+    spec = next((item for item in MODEL_SPECS if item["key"] == model_key), None)
+    if spec is None:
+        return {}
+    query = dataset[sample_id]
+    space_key = spec.get("space_key")
+    if space_key is None:
+        return {}
+    neighbors = dataset.find_similar(sample_id, k=10, space_key=str(space_key))
+    query_product = query.metadata.get("product_key")
+    query_category = query.metadata.get("category")
+    product_hits = sum(1 for sample, _distance in neighbors if sample.metadata.get("product_key") == query_product)
+    category_hits = sum(1 for sample, _distance in neighbors if sample.metadata.get("category") == query_category)
+    return {"productHits": product_hits, "categoryHits": category_hits, "total": len(neighbors)}
+
+
+def build_examples(dataset: hv.Dataset) -> list[dict[str, Any]]:
+    examples = []
+    candidate_is_fallback = any(spec["key"] == "candidate" and spec.get("fallback") for spec in MODEL_SPECS)
+    for item in TEXT_SEARCH_EXAMPLES:
+        sample_id = safe_sample_id(item["targetItemId"])
+        if sample_id not in {sample.id for sample in dataset.samples}:
+            continue
+        candidate_text = (
+            "Hyper3-CLIP is unavailable in this runtime, so this button shows the CLIP fallback neighborhood."
+            if candidate_is_fallback
+            else item["hyper3Text"]
+        )
+        examples.append(
+            {
+                "id": item["id"],
+                "title": item["title"],
+                "family": item["family"],
+                "query": item["query"],
+                "queryId": sample_id,
+                "targetTitle": item["targetTitle"],
+                "summaries": {
+                    "clip": {
+                        "rank": item["clipRank"],
+                        "text": item["clipText"],
+                        **neighbor_summary(dataset, sample_id, "clip"),
+                    },
+                    "candidate": {
+                        "rank": item["hyper3Rank"],
+                        "text": candidate_text,
+                        **neighbor_summary(dataset, sample_id, "candidate"),
+                    },
+                },
+            }
+        )
+    return examples
+
+
+def build_demo_view(dataset: hv.Dataset, layouts: dict[str, str]) -> hv.ui.View:
+    readout_panel = hv.ui.ExtensionPanel(
+        id="fashion-text-search-readout",
+        title="Shopper Text Search Proof",
+        extension="fashion-search-readout",
+        panel="fashion-comparison",
+        position="center",
+        props={
+            "models": model_panel_props(layouts),
+            "examples": build_examples(dataset),
+            "warnings": RUNTIME_WARNINGS,
+            "metrics": {
+                "typedQueryCount": 180,
+                "typedCandidateImages": 1120,
+                "hit10Hyper3Only": 23,
+                "hit10ClipOnly": 19,
+                "strongHyper3Wins": 13,
+                "strongClipWins": 9,
+                "imageRetrievalMapHyper3": 0.407,
+                "imageRetrievalMapClip": 0.240,
+                "typedHit1Hyper3": 0.244,
+                "typedHit1Clip": 0.233,
+                "typedHit10Hyper3": 0.572,
+                "typedHit10Clip": 0.550,
+                "typedCategoryP10Hyper3": 0.594,
+                "typedCategoryP10Clip": 0.561,
+                "typedMrrHyper3": 0.358,
+                "typedMrrClip": 0.344,
+            },
+        },
+    )
+    return hv.ui.View(readout_panel)
+
+
+def launch_demo(dataset: hv.Dataset, layouts: dict[str, str]) -> hv.Session:
+    session = hv.launch(
+        dataset,
+        host=SPACE_HOST,
+        port=SPACE_PORT,
+        open_browser=False,
+        workspace_id=WORKSPACE_ID,
+        block=False,
+    )
+    print("Installing DeepFashion demo extension...", flush=True)
+    session.ui.add_extension(EXTENSION_DIR, workspace_id=WORKSPACE_ID)
+    print("Applying DeepFashion side-by-side demo view...", flush=True)
+    session.ui.apply_view(build_demo_view(dataset, layouts), workspace_id=WORKSPACE_ID)
+    session.ui.set_active_layout(None, workspace_id=WORKSPACE_ID)
+    session.ui.set_selection([], workspace_id=WORKSPACE_ID)
+    print(f"\nHyperView DeepFashion text-search demo is running at {session.url}", flush=True)
+    return session
+
+
+def main() -> None:
+    dataset, layouts = 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)
+    session.wait()
+
+
+if __name__ == "__main__":
+    main()