Upgrade geospatial demo to HyperView 0.6.2

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

@@ -62,9 +62,9 @@ function Section({ title, children }) {
 
 function Walkthrough() {
   const steps = [
-    ["Pick", "Choose a ranked query."],
-    ["Baseline", "Show CLIP neighbors."],
-    ["Compare", "Switch to Hyper3-CLIP and count the top 10."],
+    ["Pick", "Start from a failing scene query."],
+    ["Compare", "Show CLIP, then Hyper3-CLIP."],
+    ["Audit", "Check exact scene and parent group."],
   ];
 
   return React.createElement(
@@ -104,6 +104,33 @@ function Walkthrough() {
   );
 }
 
+function BusinessCase() {
+  return React.createElement(
+    "div",
+    {
+      style: {
+        border: `1px solid ${colors.border}`,
+        borderRadius: 4,
+        background: colors.cardBg,
+        padding: 10,
+        display: "flex",
+        flexDirection: "column",
+        gap: 6,
+      },
+    },
+    React.createElement(
+      "div",
+      { style: { color: colors.strongText, fontSize: 13, fontWeight: 800, lineHeight: 1.25 } },
+      "Retrieval audit for aerial image libraries",
+    ),
+    React.createElement(
+      "div",
+      { style: { color: colors.bodyText, fontSize: 11, lineHeight: 1.35 } },
+      "When an analyst asks for more scenes like this, the top results should stay in the right scene class and operational group. This demo shows where CLIP drifts and where Hyper3-CLIP keeps the neighborhood cleaner.",
+    ),
+  );
+}
+
 function BenchmarkTable({ benchmark }) {
   if (!benchmark || !Array.isArray(benchmark.rows)) return null;
   return React.createElement(
@@ -132,7 +159,7 @@ function BenchmarkTable({ benchmark }) {
         React.createElement(
           "tr",
           { style: { background: colors.cardBgSoft } },
-          ["Metric", "CLIP", "Hyper3", "Delta"].map((heading) =>
+          ["Metric", "CLIP", "Hyper3-CLIP", "Delta"].map((heading) =>
             React.createElement(
               "th",
               {
@@ -428,6 +455,21 @@ function ExampleCard({
       ),
       deltaLine(item),
     ),
+    item.insight
+      ? React.createElement(
+          "div",
+          {
+            style: {
+              color: colors.bodyText,
+              fontSize: 11,
+              lineHeight: 1.35,
+              borderLeft: `2px solid ${colors.accent}`,
+              paddingLeft: 8,
+            },
+          },
+          item.insight,
+        )
+      : null,
     React.createElement(ModelCompareTable, { item, models, loadingKey, onSelectQuery }),
   );
 }
@@ -512,7 +554,12 @@ export default function GeospatialComparisonPanel() {
       },
       React.createElement(
         Section,
-        { title: "How to read it" },
+        { title: "Business case" },
+        React.createElement(BusinessCase, null),
+      ),
+      React.createElement(
+        Section,
+        { title: "What to do" },
         React.createElement(Walkthrough, null),
       ),
       warnings.length
@@ -534,7 +581,7 @@ export default function GeospatialComparisonPanel() {
         : null,
       React.createElement(
         Section,
-        { title: "Best live examples" },
+        { title: "Queries to inspect" },
         examples.length && models.length
           ? React.createElement(
               "div",
@@ -564,7 +611,7 @@ export default function GeospatialComparisonPanel() {
         : null,
       React.createElement(
         Section,
-        { title: "Benchmark table" },
+        { title: "Benchmark context" },
         React.createElement(BenchmarkTable, { benchmark: panelProps.benchmark }),
       ),
     ),

Dockerfile

@@ -20,7 +20,8 @@ WORKDIR $HOME/app
 
 RUN pip install --upgrade pip
 
-ARG HYPERVIEW_VERSION=0.6.1
+ARG HYPERVIEW_VERSION=0.6.2
+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
@@ -33,6 +34,7 @@ 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" \
     "timm>=1.0.0" \

README.md

@@ -24,7 +24,7 @@ This demo builds a balanced NWPU-RESISC45 remote-sensing subset and opens
 HyperView with two pinned scatter panels plus a compact scene-retrieval readout:
 
 - CLIP ViT-B/32 in a Euclidean 2D layout
-- Hyper3-CLIP `hyper3labs/hyper3-clip-v0.5` in a Poincare 2D layout
+- Hyper3-CLIP `hyper3-clip-v0.5` from `hyper-models` in a Poincare 2D layout
 
 The readout panel ranks live query examples by where Hyper3-CLIP improves the
 top-10 neighborhood over CLIP. The demo is designed around remote-sensing review
@@ -79,9 +79,9 @@ remote-sensing model.
 This folder is intended to deploy to `hyper3labs/HyperView-EuroSAT-Geospatial`
 from the `hyperview-spaces` deployment repository.
 
-Hyper3-CLIP weights are loaded from the gated
-`hyper3labs/hyper3-clip-v0.5` model repository at runtime. The Space needs an
-`HF_TOKEN` secret with access to that model.
+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 or lacks gated-model access, the Space starts with a
 clearly labeled CLIP fallback for the Hyper3-CLIP panel instead of exiting

demo.py

@@ -208,12 +208,12 @@ MODEL_SPECS = [
             "Inspect Hyper3-CLIP neighbors",
         ),
         "provider": env_value(
-            "GEOSPATIAL_CANDIDATE_PROVIDER", "EUROSAT_CANDIDATE_PROVIDER", "hyper3-clip"
+            "GEOSPATIAL_CANDIDATE_PROVIDER", "EUROSAT_CANDIDATE_PROVIDER", "hyper-models"
         ),
         "model": env_value(
             "GEOSPATIAL_CANDIDATE_MODEL",
             "EUROSAT_CANDIDATE_MODEL",
-            "hyper3labs/hyper3-clip-v0.5",
+            "hyper3-clip-v0.5",
         ),
         "layout": env_value(
             "GEOSPATIAL_CANDIDATE_LAYOUT", "EUROSAT_CANDIDATE_LAYOUT", "poincare:2d"
@@ -267,6 +267,37 @@ def readable_group(label: str) -> str:
     return label.replace("_", " ").replace("-", " ").title()
 
 
+def example_insight(
+    label: str,
+    clip_summary: dict[str, Any],
+    candidate_summary: dict[str, Any],
+) -> str:
+    clip_same = clip_summary["sameClassHits"]
+    clip_parent = clip_summary["parentHits"]
+    candidate_same = candidate_summary["sameClassHits"]
+    candidate_parent = candidate_summary["parentHits"]
+    total = candidate_summary.get("total", 10)
+    if label == "airplane":
+        return (
+            f"Transport audit: Hyper3-CLIP raises the neighborhood from {clip_parent}/{total} "
+            f"to {candidate_parent}/{total} transport scenes and finds {candidate_same}/{total} exact airplanes."
+        )
+    if label == "meadow":
+        return (
+            f"Land-cover QA: Hyper3-CLIP keeps {candidate_parent}/{total} neighbors in agriculture/vegetation "
+            f"versus CLIP's {clip_parent}/{total}, with {candidate_same}/{total} exact meadows."
+        )
+    if label == "runway":
+        return (
+            f"Infrastructure search: Hyper3-CLIP finds {candidate_same}/{total} exact runways versus "
+            f"CLIP's {clip_same}/{total}, while doubling the transport-group neighborhood."
+        )
+    return (
+        f"Hyper3-CLIP improves exact scene hits from {clip_same}/{total} to {candidate_same}/{total} "
+        f"and parent-group hits from {clip_parent}/{total} to {candidate_parent}/{total}."
+    )
+
+
 def save_image(image: Image.Image, destination: Path) -> None:
     if (
         destination.exists()
@@ -559,6 +590,7 @@ def build_examples(
                 "score": score,
                 "classDelta": class_delta,
                 "parentDelta": parent_delta,
+                "insight": example_insight(label, clip_summary, candidate_summary),
                 "summaries": {
                     "clip": clip_summary,
                     "candidate": candidate_summary,
@@ -609,31 +641,58 @@ def aggregate_metrics(
     return metrics
 
 
-def register_hyper3_clip_provider() -> None:
-    from hyperview.runtime import ProviderRegistry
-
-    ProviderRegistry().register_python(
-        "hyper3-clip",
-        "hyper3_clip_provider:Hyper3ClipEmbeddings",
-        description="Hyper3-CLIP v0.5 image embeddings from hyper3labs/hyper3-clip-v0.5",
-        overwrite=True,
-    )
-
-
 def build_demo_view(dataset: hv.Dataset, layouts: dict[str, str]) -> hv.ui.View:
     summaries = collect_neighbor_summaries(dataset)
-    scatter_panels = [
-        hv.ui.Scatter(
-            id=f"{spec['key']}-geospatial-map",
-            title=spec["panel_title"],
-            layout_key=layouts[spec["key"]],
-            geometry=spec["geometry"],
-            layout_dimension=spec["layout_dimension"],
-        )
-        for spec in MODEL_SPECS
-    ]
+    clip_spec = MODEL_SPECS[0]
+    candidate_spec = MODEL_SPECS[1]
+    samples_panel_id = "grid"
+    clip_panel_id = "clip-geospatial-map"
+    candidate_panel_id = "candidate-geospatial-map"
     return hv.ui.View(
-        hv.ui.Horizontal(*scatter_panels),
+        hv.ui.Samples(
+            id=samples_panel_id,
+            title="Samples",
+            position="center",
+            props={
+                "dockview": {
+                    "minimumHeight": 220,
+                    "minimumWidth": 360,
+                },
+            },
+        ),
+        hv.ui.Scatter(
+            id=clip_panel_id,
+            title=clip_spec["panel_title"],
+            layout_key=layouts[clip_spec["key"]],
+            position="center",
+            reference_panel_id=samples_panel_id,
+            direction="below",
+            geometry=clip_spec["geometry"],
+            layout_dimension=clip_spec["layout_dimension"],
+            props={
+                "dockview": {
+                    "initialHeight": 260,
+                    "minimumHeight": 190,
+                    "minimumWidth": 280,
+                },
+            },
+        ),
+        hv.ui.Scatter(
+            id=candidate_panel_id,
+            title=candidate_spec["panel_title"],
+            layout_key=layouts[candidate_spec["key"]],
+            position="center",
+            reference_panel_id=clip_panel_id,
+            direction="right",
+            geometry=candidate_spec["geometry"],
+            layout_dimension=candidate_spec["layout_dimension"],
+            props={
+                "dockview": {
+                    "minimumHeight": 190,
+                    "minimumWidth": 280,
+                },
+            },
+        ),
         hv.ui.ExtensionPanel(
             id="geospatial-retrieval-readout",
             extension="geospatial-readout",
@@ -649,6 +708,10 @@ def build_demo_view(dataset: hv.Dataset, layouts: dict[str, str]) -> hv.ui.View:
                 "models": model_panel_props(layouts),
                 "examples": build_examples(dataset, summaries),
                 "warnings": RUNTIME_WARNINGS,
+                "dockview": {
+                    "initialWidth": 330,
+                    "minimumWidth": 290,
+                },
             },
         ),
     )
@@ -673,7 +736,6 @@ def launch_demo(dataset: hv.Dataset, layouts: dict[str, str]) -> hv.Session:
 
 
 def main() -> None:
-    register_hyper3_clip_provider()
     dataset, layouts = build_dataset()
     print("Layouts:", flush=True)
     for spec in MODEL_SPECS: