---
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`