Skip to content

Commit 13b0870

Browse files
mnm-matinmnm-matin
committed
feat: upgrade all Spaces to hyperview==0.3.1 from PyPI, remove vendoring
- Imagenette: bump from hyperview==0.2.0 to 0.3.1, simplify demo.py - Jaguar Re-ID: replace vendored source with hyperview[ml]==0.3.1 (timm-image provider and spherical 3D layout now in released package) - Add Jaguar deploy workflow with pypi-release dispatch trigger - Update READMEs: remove vendoring references, document community reuse flow - Both demos verified locally against isolated PyPI installs
1 parent 6dda472 commit 13b0870

10 files changed

Lines changed: 419 additions & 146 deletions

File tree

‎.github/workflows/deploy-hf-space-jaguar-reid.yml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
name: Deploy HF Space - Jaguar Re-ID MegaDescriptor
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- spaces/jaguar-reid-megadescriptor-spherical/**
8+
- .github/workflows/deploy-hf-space-jaguar-reid.yml
9+
- .github/workflows/deploy-hf-space-reusable.yml
10+
repository_dispatch:
11+
types: [pypi-release]
12+
workflow_dispatch:
13+
14+
concurrency:
15+
group: deploy-hf-space-jaguar-reid
16+
cancel-in-progress: false
17+
18+
jobs:
19+
deploy:
20+
uses: ./.github/workflows/deploy-hf-space-reusable.yml
21+
with:
22+
source_dir: spaces/jaguar-reid-megadescriptor-spherical
23+
space_id: hyper3labs/HyperView-Jaguar-ReID
24+
secrets: inherit

‎README.md‎

Lines changed: 77 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,13 +12,89 @@ Recommended GitHub repository name:
1212
- Reuse one template pattern for multiple Space demos
1313
- Deploy each demo folder to a different Hugging Face Space via GitHub Actions
1414

15+
## Intended reuse flow
16+
17+
This repo is meant to be easy to hand to an external coding agent.
18+
19+
The happy path is:
20+
21+
1. Copy one folder from `spaces/`
22+
2. Edit the constants block at the top of that folder's `demo.py`
23+
3. Update the Space `README.md`
24+
4. Add or retarget one deploy workflow
25+
26+
Both official examples install released packages from PyPI. Keep custom Space
27+
logic in `demo.py` and Space-local files so contributors can copy a folder,
28+
change their dataset settings, and open a PR without carrying an internal
29+
source snapshot.
30+
31+
The current Imagenette example is intentionally simple and keeps the editable
32+
dataset/model choices in one place so agents do not need to coordinate Docker
33+
args, runtime environment variables, and Python script flags.
34+
35+
## Create Your Own Hugging Face Space
36+
37+
Use the Imagenette example as a copyable starter.
38+
39+
1. Create a new Space at https://huggingface.co/new-space.
40+
2. Choose a distinct Space name such as `yourproject-HyperView` or `HyperView-yourproject`.
41+
3. Select `Docker` as the Space SDK.
42+
4. Create the Space. Hugging Face will initialize it as a git-backed Docker Space with `sdk: docker` in `README.md`.
43+
5. In this repository, copy `spaces/imagenette-clip-hycoclip` to a new folder such as `spaces/yourproject-hyperview`.
44+
6. Edit `spaces/yourproject-hyperview/demo.py` and change the constants block at the top of the file.
45+
7. Edit `spaces/yourproject-hyperview/README.md` and rename the copied example from `HyperView` to your own project name.
46+
8. Keep the Space name consistent across the Hugging Face Space ID, the README frontmatter `title`, and the Markdown H1. Good patterns are `yourproject-HyperView` and `HyperView-yourproject`.
47+
9. Copy `.github/workflows/deploy-hf-space-imagenette.yml` to a new workflow file and update `name`, `concurrency`, `paths`, `source_dir`, and `space_id`.
48+
10. Configure the GitHub Actions secrets `HF_USERNAME` and `HF_TOKEN`. The token must have write access to the target Hugging Face Space.
49+
11. Push to `main` or run the workflow manually with `workflow_dispatch`.
50+
12. Keep the Dockerfile on released PyPI packages such as `hyperview==0.3.1` or `hyperview[ml]==0.3.1` instead of vendoring `hyperview` into the Space folder.
51+
13. Check the Hugging Face Space logs to confirm the Docker image built and the container started on port `7860`.
52+
53+
### Optional Local Test
54+
55+
From the `hyperview-spaces` repository root:
56+
57+
```bash
58+
docker build -t yourproject-hyperview spaces/yourproject-hyperview
59+
docker run --rm -p 7860:7860 yourproject-hyperview
60+
```
61+
62+
Then open `http://127.0.0.1:7860`.
63+
64+
## Contribute Your Space Back
65+
66+
If you want your Space to appear in this repository as a community example:
67+
68+
1. Fork this repository or create a branch if you already have write access.
69+
2. Add your Space folder under `spaces/<your-slug>`.
70+
3. Rename the copied `HyperView` title and heading to your own project name such as `yourproject-HyperView` or `HyperView-yourproject`.
71+
4. Add or update a deploy workflow for your folder if this repository should deploy it.
72+
5. Add a row for your Space in the community table below.
73+
6. Open a pull request describing the Hugging Face Space ID, dataset source, embedding models, and whether the deploy workflow is expected to run from this repository.
74+
75+
Important: deployment workflows in this repository use the shared `HF_USERNAME` and `HF_TOKEN` GitHub secrets. A contributed workflow will only deploy successfully if that token has write access to the target Space.
76+
77+
## Community Contributed Spaces
78+
79+
Add one row here when you contribute a new Space.
80+
81+
| Space | Hugging Face Space ID | Folder | Maintainer | Status | Notes |
82+
| --- | --- | --- | --- | --- | --- |
83+
| HyperView - Imagenette | `hyper3labs/HyperView` | `spaces/imagenette-clip-hycoclip` | Hyper3Labs | Official example | Copyable starter template |
84+
| HyperView - Jaguar Re-ID | `hyper3labs/HyperView-Jaguar-ReID` | `spaces/jaguar-reid-megadescriptor-spherical` | Hyper3Labs | Official example | Advanced `timm-image` + spherical example using released `hyperview[ml]` |
85+
1586
## Repository layout
1687

1788
```text
1889
.
1990
├── .github/workflows/
2091
├── spaces/
2192
│ ├── README.md
93+
│ ├── jaguar-reid-megadescriptor-spherical/
94+
│ │ ├── README.md
95+
│ │ ├── Dockerfile
96+
│ │ ├── .dockerignore
97+
│ │ └── demo.py
2298
│ └── imagenette-clip-hycoclip/
2399
│ ├── README.md
24100
│ ├── Dockerfile
@@ -32,7 +108,7 @@ Recommended GitHub repository name:
32108
Yes, you can ship precomputed LanceDB artifacts with the image. There are two valid options:
33109

34110
1. **Build-time precompute** (current default)
35-
- `RUN python demo.py --precompute`
111+
- `RUN python -c "from demo import build_dataset; build_dataset()"`
36112
- Artifacts are baked into the Docker image layers
37113
2. **Commit precomputed artifacts into this repo**
38114
- Useful when startup determinism is critical

‎spaces/README.md‎

Lines changed: 57 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -16,10 +16,53 @@ spaces/
1616
Dockerfile
1717
.dockerignore
1818
demo.py
19+
jaguar-reid-megadescriptor-spherical/
20+
README.md
21+
Dockerfile
22+
.dockerignore
23+
demo.py
1924
```
2025

2126
Each subfolder is a **Space root** (must contain at least `README.md` + `Dockerfile`).
2227

28+
## Agent-friendly pattern
29+
30+
The example folders are meant to be easy for external coding agents to edit.
31+
The intended workflow is:
32+
33+
1. Copy `spaces/imagenette-clip-hycoclip` to a new slug.
34+
2. Edit the constants block at the top of the new `demo.py`.
35+
3. Update the new folder's `README.md` frontmatter and title.
36+
4. Copy and retarget the matching deploy workflow.
37+
38+
The template deliberately avoids environment-variable configuration inside
39+
`demo.py` so agents only need one obvious edit surface.
40+
41+
Both official examples install released PyPI packages. Keep Space-specific code
42+
inside the copied folder and update the pinned HyperView version after a PyPI
43+
release instead of vendoring `hyperview` into the Space.
44+
45+
## Exact Steps
46+
47+
1. Create a new Hugging Face Space at https://huggingface.co/new-space.
48+
2. Name it something distinct like `yourproject-HyperView` or `HyperView-yourproject`.
49+
3. Choose `Docker` as the SDK.
50+
4. Copy `spaces/imagenette-clip-hycoclip` to `spaces/yourproject-hyperview`.
51+
5. Edit the constants block in `spaces/yourproject-hyperview/demo.py`.
52+
6. Edit `spaces/yourproject-hyperview/README.md` and rename the copied `HyperView` title and H1 to your own project name.
53+
7. Copy `.github/workflows/deploy-hf-space-imagenette.yml` to a new workflow file and update `space_id`, `source_dir`, `paths`, `name`, and `concurrency`.
54+
8. Make sure the GitHub Actions secrets `HF_USERNAME` and `HF_TOKEN` can push to your target Space.
55+
9. Keep the Dockerfile on released packages such as `hyperview==0.3.1` or `hyperview[ml]==0.3.1`.
56+
10. Push to `main` or trigger `workflow_dispatch`.
57+
11. Verify the Space build logs on Hugging Face.
58+
59+
### Local Docker Smoke Test
60+
61+
```bash
62+
docker build -t yourproject-hyperview spaces/yourproject-hyperview
63+
docker run --rm -p 7860:7860 yourproject-hyperview
64+
```
65+
2366
## CI deployment model
2467

2568
- Reusable workflow: `.github/workflows/deploy-hf-space-reusable.yml`
@@ -29,7 +72,7 @@ Each per-space workflow:
2972
1. Watches one space folder
3073
2. Calls the reusable workflow with:
3174
- `space_id` (e.g. `hyper3labs/HyperView`)
32-
- `source_dir` (e.g. `spaces/imagenette-clip-hycoclip`)
75+
- `source_dir` (e.g. `spaces/imagenette-clip-hycoclip`)
3376

3477
## Required GitHub secrets
3578

@@ -39,6 +82,16 @@ Each per-space workflow:
3982
## Add a new Space
4083

4184
1. Copy `spaces/imagenette-clip-hycoclip` to a new slug
42-
2. Edit the new folder's `README.md` YAML frontmatter and `demo.py`
43-
3. Copy `.github/workflows/deploy-hf-space-imagenette.yml` to a new workflow file
44-
4. Update `space_id`, `paths`, and `source_dir` in the new workflow
85+
2. Edit the constants block in the new `demo.py`
86+
3. Rename the copied `HyperView` title to your own project name such as `yourproject-HyperView` or `HyperView-yourproject`
87+
4. Edit the new folder's `README.md` YAML frontmatter and title
88+
5. Copy `.github/workflows/deploy-hf-space-imagenette.yml` to a new workflow file
89+
6. Update `space_id`, `paths`, and `source_dir` in the new workflow
90+
91+
## Contributing Back
92+
93+
If you open a PR with a new Space folder, also:
94+
95+
1. Add a row to the community table in the root `README.md`
96+
2. State the Hugging Face Space ID in the PR description
97+
3. State whether this repository should deploy the Space or just host the example folder

‎spaces/imagenette-clip-hycoclip/Dockerfile‎

Lines changed: 3 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ WORKDIR $HOME/app
2121

2222
RUN pip install --upgrade pip
2323

24-
ARG HYPERVIEW_VERSION=0.2.0
24+
ARG HYPERVIEW_VERSION=0.3.1
2525
ARG HYPER_MODELS_VERSION=0.1.0
2626

2727
# Pin package versions so Docker cache cannot silently hold an older PyPI release.
@@ -30,17 +30,11 @@ RUN pip install "hyper-models==${HYPER_MODELS_VERSION}" && python -c "import hyp
3030

3131
COPY --chown=user demo.py ./demo.py
3232

33-
ARG DEMO_SAMPLES=300
34-
3533
ENV HYPERVIEW_DATASETS_DIR=/home/user/app/demo_data/datasets \
36-
HYPERVIEW_MEDIA_DIR=/home/user/app/demo_data/media \
37-
DEMO_SAMPLES=${DEMO_SAMPLES}
34+
HYPERVIEW_MEDIA_DIR=/home/user/app/demo_data/media
3835

3936
# Precompute at build time so the Space starts fast.
40-
RUN python demo.py --precompute
41-
42-
ENV HOST=0.0.0.0 \
43-
PORT=7860
37+
RUN python -c "from demo import build_dataset; build_dataset()"
4438

4539
EXPOSE 7860
4640

‎spaces/imagenette-clip-hycoclip/README.md‎

Lines changed: 39 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -10,25 +10,52 @@ pinned: false
1010

1111
# HyperView — Imagenette (CLIP + HyCoCLIP)
1212

13-
This Hugging Face Space runs HyperView with:
13+
This folder is the simplest copyable HyperView Space example in this repo.
14+
It keeps all dataset-specific settings in the constants block at the top of
15+
[demo.py](demo.py), so a coding agent can usually adapt it by editing one file.
16+
17+
This example runs HyperView with:
1418

1519
- CLIP embeddings (`openai/clip-vit-base-patch32`) for Euclidean layout
1620
- HyCoCLIP embeddings (`hycoclip-vit-s`) for Poincaré layout
1721

18-
The Docker image installs the **latest HyperView from PyPI** and precomputes
19-
embeddings/layouts during build for fast runtime startup.
22+
The Docker image installs released HyperView packages from PyPI and precomputes
23+
the dataset, embeddings, and layouts during build for fast runtime startup.
24+
25+
## Reuse This Template
26+
27+
When you copy this folder for your own dataset, change these parts first:
28+
29+
1. Edit the constants block in [demo.py](demo.py).
30+
2. Rename the copied Space from `HyperView` to your own project name such as `yourproject-HyperView` or `HyperView-yourproject`.
31+
3. Update this README frontmatter, title, and H1.
32+
4. Point a deploy workflow at your new folder.
33+
34+
This starter currently installs `hyperview==0.3.1` and `hyper-models==0.1.0`.
35+
36+
The defaults in [demo.py](demo.py) are:
37+
38+
- Hugging Face dataset: `Multimodal-Fatima/Imagenette_validation`
39+
- Split: `validation`
40+
- Image field: `image`
41+
- Label field: `label`
42+
- Sample count: `300`
43+
- Layouts: CLIP + Euclidean, HyCoCLIP + Poincaré
44+
45+
If you only want one model in your own Space, keep a single entry in
46+
`EMBEDDING_LAYOUTS` and delete the rest.
47+
48+
When contributing your own Space back to this repository, add a row to the
49+
community table in the root `README.md` and include your Hugging Face Space ID
50+
in the pull request description.
2051

21-
## Configuration
52+
## Build Model
2253

23-
Environment variables:
54+
The Dockerfile runs `build_dataset()` during image build. That means:
2455

25-
- `DEMO_HF_DATASET` (default: `Multimodal-Fatima/Imagenette_validation`)
26-
- `DEMO_HF_SPLIT` (default: `validation`)
27-
- `DEMO_HF_IMAGE_KEY` (default: `image`)
28-
- `DEMO_HF_LABEL_KEY` (default: `label`)
29-
- `DEMO_SAMPLES` (default: `300`)
30-
- `DEMO_CLIP_MODEL` (default: `openai/clip-vit-base-patch32`)
31-
- `DEMO_HYPER_MODEL` (default: `hycoclip-vit-s`)
56+
- the first expensive download/embedding pass happens at build time
57+
- the runtime container mostly just launches HyperView
58+
- there is no extra runtime configuration path to keep in sync
3259

3360
## Deploy source
3461

0 commit comments

Comments
 (0)