README.md

metadata

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

uv sync --dev

Of via Make:

make sync

Met I-JEPA ondersteuning:

make sync-ijepa

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

make ready

Met Streamlit UI:

make sync-app

Verwacht JSONL-formaat

Elke regel is een probleem:

{"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:

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):

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

uv run pytest
uv run mypy
uv run ruff check .

Of:

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.