File size: 5,355 Bytes
9643483 974f31e 9643483 974f31e 9643483 974f31e d110c29 974f31e d110c29 974f31e | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 | ---
title: "HyperView: Jaguar Embedding Geometry Comparison"
emoji: 🐆
colorFrom: green
colorTo: yellow
sdk: docker
app_port: 7860
pinned: false
---
# HyperView Jaguar Core Claims Demo
This Space compares the top core-claims-set families in three geometric panels:
1. Euclidean: `triplet:T0:msv3` (seed 43)
2. Hyperspherical view: `arcface:O0:msv3` (seed 44)
3. Hyperbolic (Poincare) view: `lorentz:O1:msv3` (seed 44)
The app loads train + validation-tagged samples from a resized Hugging Face dataset and injects precomputed embedding assets generated offline on GPU.
## Contracts
Runtime environment variables:
- `HF_DATASET_REPO` (default: `hyper3labs/jaguar-hyperview-demo`)
- `HF_DATASET_CONFIG` (default: `default`)
- `HF_DATASET_SPLIT` (default: `train`)
- `EMBEDDING_ASSET_DIR` (default: `./assets`)
- `EMBEDDING_ASSET_MANIFEST` (default: `${EMBEDDING_ASSET_DIR}/manifest.json`)
- `HYPERVIEW_STARTUP_MODE` (default: `serve_fast`; choices: `serve_fast|blocking`)
- `HYPERVIEW_WARMUP_STATUS_PATH` (default: `/tmp/hyperview_warmup_status.json`)
- `HYPERVIEW_WARMUP_FAILURE_POLICY` (default: `exit`; choices: `exit|warn`)
- `HYPERVIEW_BATCH_INSERT_SIZE` (default: `500`; controls sample-batch insertion chunk size)
- `HYPERVIEW_DEFAULT_PANEL` (default: `spherical3d`; enables Sphere 3D as initial scatter panel)
- `HYPERVIEW_LAYOUT_CACHE_VERSION` (default: `v6`; bumps dock layout localStorage key to invalidate stale cached panel state)
- `HYPERVIEW_BIND_HOST` (preferred bind host; optional)
- `SPACE_HOST` (compat input only; used for bind only if local: `0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`)
- `SPACE_PORT` (primary port source)
- `PORT` (fallback port source when `SPACE_PORT` is unset)
Port precedence: `SPACE_PORT` > `PORT` > `7860`.
On Hugging Face Spaces, `SPACE_HOST` may be injected as `<space-subdomain>.hf.space`. That domain must not be used as a local bind socket, so the runtime falls back to `0.0.0.0` unless `HYPERVIEW_BIND_HOST` is explicitly set.
The runtime also patches HyperView's dock-layout cache key from legacy `hyperview:dockview-layout:v5` to `hyperview:dockview-layout:${HYPERVIEW_LAYOUT_CACHE_VERSION}` to force migration away from stale panel layouts after UI/layout changes. For future migrations, increment `HYPERVIEW_LAYOUT_CACHE_VERSION` (for example, `v7`) without changing code.
## Startup and Warmup Semantics
- `HYPERVIEW_STARTUP_MODE=serve_fast` (default):
- Starts the HyperView server immediately.
- Runs dataset warmup asynchronously in a background thread.
- Warmup phases are persisted as JSON: `ingest -> spaces -> layouts -> ready`.
- `HYPERVIEW_STARTUP_MODE=blocking`:
- Performs warmup synchronously before serving traffic.
Warmup status JSON fields include:
- `status` (`starting|running|ready|failed`)
- `phase` (`boot|ingest|spaces|layouts|ready|failed`)
- `counts` (sample/space/layout counters and ingestion stats)
- `error` (exception payload when warmup fails)
- `timestamps` (`started_at`, `updated_at`, plus terminal timestamps)
Failure policy behavior:
- `HYPERVIEW_WARMUP_FAILURE_POLICY=exit` (default): process exits on warmup failure.
- `HYPERVIEW_WARMUP_FAILURE_POLICY=warn`: process stays up and records failure in warmup status JSON.
Healthcheck semantics:
- Container health (`/__hyperview__/health`) indicates server liveness only.
- Data readiness (dataset/spaces/layouts completed) is indicated by warmup status JSON (`status=ready`).
## Important Note
HyperView similarity search currently uses cosine distance in storage backends. The Lorentz panel in this Space is intended for embedding-space visualization and geometry-aware comparison rather than canonical Lorentz-distance retrieval scoring.
## Reproducibility Commands
Run from this folder (`HyperViewDemoHuggingFaceSpace/`).
### 1) Build embedding assets (GPU required)
```bash
source .venv/bin/activate
python3 scripts/build_hyperview_demo_assets.py \
--model_manifest config/model_manifest.json \
--dataset_root ../kaggle_jaguar_dataset_v2 \
--coreset_csv ../data/validation_coreset.csv \
--output_dir ./assets \
--device cuda \
--batch_size 64 \
--num_workers 4
```
### 2) Publish resized demo dataset
```bash
source .venv/bin/activate
python3 scripts/publish_hyperview_demo_dataset.py \
--dataset_root ../kaggle_jaguar_dataset_v2 \
--coreset_csv ../data/validation_coreset.csv \
--output_dir ./dataset_build \
--repo_id hyper3labs/jaguar-hyperview-demo \
--config_name default
```
Use `--no_push` for local dry-runs.
### 3) Local Docker smoke run
```bash
docker build -t jaguar-hyperview .
docker run --rm -p 7860:7860 \
-e HF_DATASET_REPO=hyper3labs/jaguar-hyperview-demo \
-e EMBEDDING_ASSET_DIR=/home/user/app/assets \
jaguar-hyperview
```
Open `http://127.0.0.1:7860`.
### 4) Optional H100 batch export on HPI
```bash
sbatch remote_setup/build_hyperview_demo_assets_h100.slurm
```
Override defaults at submit time if needed:
```bash
MODEL_MANIFEST=config/model_manifest.json \
OUTPUT_DIR=./assets \
sbatch remote_setup/build_hyperview_demo_assets_h100.slurm
```
## Provenance
Model manifest: `config/model_manifest.json`
Ranking and source-of-truth anchors:
- `reports/summaries_of_findings/core_claims_axis12_paper_facing_tables_2026_03_16_102311/axis1_primary_ranking.csv`
- `paper_draft/second_draft/sources_of_truth.md`
|