README.md

---
title: MathVision JEPA Explorer
emoji: 🔎
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
---

# MathVision Explorer

Typed Python-startpunt voor een **MathVision + JEPA** explorer. De eerste versie werkt
lokaal met MathVision-achtige JSONL-bestanden en een eenvoudige, testbare image embedder.
Daarna kun je de embedder vervangen door I-JEPA-features.

## Installatie

```powershell
uv sync --dev
```

Of via Make:

```bash
make sync
```

Met I-JEPA ondersteuning:

```powershell
make sync-ijepa
```

Alles klaarzetten, inclusief Streamlit, I-JEPA, demo-data, gallery en checks:

```bash
make ready
```

Met Streamlit UI:

```bash
make sync-app
```

## Verwacht JSONL-formaat

Elke regel is een probleem:

```json
{"id":"mv-001","question":"How many cubes are visible?","answer":"7","image":"images/mv-001.png","subject":"geometry","level":2}
```

Ondersteunde velden:

- `id` of `problem_id`
- `question`
- `answer`
- `image`
- `options`
- `subject`
- `level`
- `problem_type` (optioneel)
- `solution`

## Gebruik

Maak eerst een zichtbare mini-demo:

```bash
make demo
make gallery
make app
```

## I-JEPA integratie

De module `mathvision_explorer.embeddings` definieert een `ImageEmbedder` protocol. De
meegeleverde `ColorStatsEmbedder` is bewust simpel, zodat tests snel en offline draaien.
`IJepaImageEmbedder` gebruikt standaard `facebook/ijepa_vith14_1k` via Hugging Face
Transformers en poolt `last_hidden_state` naar een 1D embedding.

Voorbeeld (2 images -> cosine similarity):

```python
from pathlib import Path

from mathvision_explorer.embeddings import IJepaImageEmbedder
from mathvision_explorer.index import cosine_similarity

embedder = IJepaImageEmbedder()
v1 = embedder.embed_image(Path("data/demo/images/mv-001.png"))
v2 = embedder.embed_image(Path("data/demo/images/mv-002.png"))
print(cosine_similarity(v1, v2))
```

## Kwaliteit

```powershell
uv run pytest
uv run mypy
uv run ruff check .
```

Of:

```bash
make check
```

## Hugging Face Spaces

Deze repo is voorbereid als Docker Space. De hosted entrypoint is `app.py`; die maakt
demo-data aan en start daarna de Streamlit explorer. Dependencies staan in
`pyproject.toml`; Docker installeert met `pip install -e ".[app,ijepa]"`.

Belangrijk voor I-JEPA:

- Docker gebruikt CPU-only PyTorch wheels.
- Transformers is gepind op een stabiele 5.x release met I-JEPA support.
- De eerste keer dat `ijepa` gekozen wordt, downloadt de app het model.