latent-inspector-py

Python successor to latent-inspector: inspect and compare latent representations from DINOv2, I-JEPA, V-JEPA 2, and EUPE with a research-grade experiment pipeline and paper-first artifact trail.

Status: release candidate.

Validated on 2026-04-13:

• make check passes
• make build passes
• make showcase passes
• 4-model parity runs against the Rust reference are available through Rust parity mode

Rust parity mode is the release path when exact cross-implementation alignment matters:

LATENT_INSPECTOR_RUNTIME_BACKEND=rust uv run lipy compare ...

North star

Build the Python version as the fast research workbench for the same core question as the Rust tool:

how do different training objectives shape the geometry, concentration, invariances, and downstream usefulness of latent world representations?

Scope of v1

• Same core model family as the Rust repo:
  • DINOv2
  • I-JEPA
  • V-JEPA 2
  • EUPE
• Python-first research stack:
  • PyTorch / torchvision / timm / transformers / huggingface_hub
  • ONNX Runtime for exported inference backends
  • numpy / scipy / scikit-learn / einops / pandas / polars
  • typer + rich CLI
  • pydantic config + result schemas
  • pytest for reproducible validation
• Dual mode execution:
  • native backend for EUPE via official weights
  • ONNX export + ONNX Runtime backend for DINOv2 / I-JEPA / V-JEPA 2
• Outputs:
  • inspect / compare / profile / drift / dataset study commands
  • parquet/json artifacts
  • plots and paper-ready tables
  • LaTeX-ready experiment summaries

Runtime modes

• Default runtime:
  • eupe-vit-b16 uses the native Python backend
  • ONNX-backed models use the Python runtime path and prefer the Rust bridge when available
• Rust parity mode:
  • force all supported models through the Rust reference bridge with LATENT_INSPECTOR_RUNTIME_BACKEND=rust
  • use this for release validation, parity studies, and cross-implementation comparisons

The model catalog exposes the active runtime metadata in JSON:

uv run lipy models --format json

Quickstart

make sync
make check
make showcase

Common commands:

uv run lipy models --format json
uv run lipy inspect artifacts/showcase/dataset/scene-01-orbit.png --model eupe-vit-b16 --format json
uv run lipy compare artifacts/showcase/dataset/scene-01-orbit.png --models eupe-vit-b16,dinov2-vit-l14 --format json
uv run lipy profile --model eupe-vit-b16 --dataset artifacts/showcase/dataset --format json
uv run lipy study run artifacts/showcase/study.yaml

Handy targets

• make sync: install locked dependencies with uv
• make check: format, lint, typecheck, and test
• make smoke: light CLI verification
• make showcase: generate demo assets and run the end-to-end showcase flow
• make build: build sdist and wheel with uv
• make publish-testpypi: publish to TestPyPI
• make publish: publish to PyPI

Release and publishing

Build locally:

make build

Publish with uv:

make publish-testpypi
make publish

Before publishing, run the release checklist in RELEASE_CHECKLIST.md.

Repo map

• docs/spec/ — product, research, contracts, schedule
• docs/rfcs/ — architecture decisions
• paper/ — paper draft, bib, figures, notes
• src/latent_inspector_py/ — implementation
• tests/ — unit + integration tests
• AUTONOMOUS-GRIND-2026-04-12/ — work queue and iteration log for today's 10-pass buildout