Metadata-Version: 2.4
Name: latent-inspector-py
Version: 0.1.0
Summary: Python successor to latent-inspector for latent geometry analysis
Requires-Python: >=3.11
Requires-Dist: einops>=0.8
Requires-Dist: huggingface-hub>=0.34
Requires-Dist: matplotlib>=3.10
Requires-Dist: numpy>=2.2
Requires-Dist: onnx>=1.18
Requires-Dist: onnxruntime>=1.22
Requires-Dist: pandas>=2.3
Requires-Dist: pillow>=11.2
Requires-Dist: polars>=1.31
Requires-Dist: pyarrow>=20.0
Requires-Dist: pydantic-settings>=2.8
Requires-Dist: pydantic>=2.11
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=14.0
Requires-Dist: scikit-learn>=1.7
Requires-Dist: scipy>=1.15
Requires-Dist: seaborn>=0.13
Requires-Dist: timm>=1.0
Requires-Dist: torch>=2.7
Requires-Dist: torchvision>=0.22
Requires-Dist: transformers>=4.54
Requires-Dist: typer>=0.16
Provides-Extra: dev
Requires-Dist: mypy>=1.17; extra == 'dev'
Requires-Dist: pytest-cov>=6.2; extra == 'dev'
Requires-Dist: pytest>=8.4; extra == 'dev'
Requires-Dist: ruff>=0.12; extra == 'dev'
Description-Content-Type: text/markdown

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

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

```bash
uv run lipy models --format json
```

## Quickstart

```bash
make sync
make check
make showcase
```

Common commands:

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

```bash
make build
```

Publish with `uv`:

```bash
make publish-testpypi
make publish
```

Before publishing, run the release checklist in [RELEASE_CHECKLIST.md](/Users/abdel/dev/me/world-models/latent-inspector-py/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
