featlens 0.1.0__tar.gz

featlens-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Turhan Can Kargın
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

featlens-0.1.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: featlens
+Version: 0.1.0
+Summary: Model-agnostic feature-map visualization: PCA-to-RGB feature maps from any vision model and any layer.
+Author: Turhan Can Kargın
+License: MIT
+Project-URL: Homepage, https://github.com/turhancan97/FeatLens
+Keywords: feature-maps,visualization,pca,vision-transformer,interpretability,dino,clip,vjepa
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=1.13
+Requires-Dist: torchvision>=0.14
+Requires-Dist: numpy>=1.21
+Requires-Dist: pillow>=9.0
+Requires-Dist: imageio>=2.20
+Requires-Dist: einops>=0.6
+Requires-Dist: matplotlib>=3.5
+Requires-Dist: pyyaml>=5.4
+Provides-Extra: timm
+Requires-Dist: timm>=0.9; extra == "timm"
+Provides-Extra: hf
+Requires-Dist: transformers>=4.30; extra == "hf"
+Provides-Extra: clip
+Requires-Dist: open_clip_torch>=2.20; extra == "clip"
+Provides-Extra: all
+Requires-Dist: timm>=0.9; extra == "all"
+Requires-Dist: transformers>=4.30; extra == "all"
+Requires-Dist: open_clip_torch>=2.20; extra == "all"
+Dynamic: license-file
+
+# FeatLens
+
+[![Tests](https://github.com/turhancan97/FeatLens/actions/workflows/test.yml/badge.svg)](https://github.com/turhancan97/FeatLens/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/featlens)](https://pypi.org/project/featlens/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**See what any vision model encodes.** FeatLens renders PCA-to-RGB **feature maps** for
+**any** vision model — DINO, DINOv2/v3, CLIP, SigLIP, MAE, DeiT, V-JEPA, CNNs, … — loaded from
+**any** source (timm, HuggingFace `transformers`, `torch.hub`, an external repo, or a model you
+built yourself), and from **any layer**, as a clean **model × layer** grid.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/turhancan97/FeatLens/main/examples/feat_cat.png" alt="DINO feature maps across layers" width="100%">
+</p>
+
+Most "DINO PCA" scripts are welded to one model. FeatLens separates **representation access**
+(a small adapter layer over the model zoo) from **visualization** (robust PCA → RGB), so you can
+point it at a new model in seconds and compare models/layers side by side.
+
+## Gallery
+
+All produced by `examples/quickstart.py` on the three bundled images. Sizes below are the
+**originals**; each image is resized to `img_size` (default 224) before the model.
+
+**`visualize(...)` — DINO ViT-B/16 feature maps across layers 2 / 5 / 8 / 11:**
+
+| Image (original size) | Source | Feature maps |
+|---|---|---|
+| `astronaut.jpg` · 512×512 | <img src="https://raw.githubusercontent.com/turhancan97/FeatLens/main/examples/images/astronaut.jpg" width="110"> | <img src="https://raw.githubusercontent.com/turhancan97/FeatLens/main/examples/feat_astronaut.png" width="430"> |
+| `cat.jpg` · 451×300 | <img src="https://raw.githubusercontent.com/turhancan97/FeatLens/main/examples/images/cat.jpg" width="110"> | <img src="https://raw.githubusercontent.com/turhancan97/FeatLens/main/examples/feat_cat.png" width="430"> |
+| `coffee.jpg` · 600×400 | <img src="https://raw.githubusercontent.com/turhancan97/FeatLens/main/examples/images/coffee.jpg" width="110"> | <img src="https://raw.githubusercontent.com/turhancan97/FeatLens/main/examples/feat_coffee.png" width="430"> |
+
+**`grid(...)` — model × layer, overlaid on the image** (DINO vs DINOv2 across layers 2/5/8/11):
+
+<p align="center"><img src="https://raw.githubusercontent.com/turhancan97/FeatLens/main/examples/grid_overlay.png" alt="model x layer grid overlay" width="100%"></p>
+
+**`compare(...)` — models at the final layer** &nbsp;|&nbsp; **`custom_adapter` — a ResNet-50 (CNN escape hatch)**
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/turhancan97/FeatLens/main/examples/compare_models.png" alt="compare models at last layer" height="320">
+  &nbsp;&nbsp;
+  <img src="https://raw.githubusercontent.com/turhancan97/FeatLens/main/examples/resnet50.png" alt="resnet50 feature map" height="320">
+</p>
+
+## Install
+
+```bash
+pip install -e ".[timm]"          # timm backend (DINO, CLIP, SigLIP, DeiT, ...)
+# extras: [hf] transformers · [clip] open_clip · [all]
+```
+
+Install PyTorch for your platform first (https://pytorch.org).
+
+## Quick start (Python)
+
+```python
+import featlens as ll
+
+# One model, scrub layers (shared PCA basis -> colors comparable across the row)
+ll.visualize("dinov2_vitb14", "img.jpg", layers=[2, 5, 8, 11], out="row.png")
+
+# Compare models at the final layer (per-tile basis)
+ll.compare(["dino_vitb16", "mae_vitb16", "clip_large_openai"], "img.jpg", layer=-1, out="cmp.png")
+
+# Full model x layer grid, overlaid on the image
+ll.grid(["dino_vitb16", "dinov2_vitb14"], "img.jpg", layers=[2, 5, 8, 11], overlay=True, out="grid.png")
+```
+
+## Quick start (CLI)
+
+```bash
+featlens --models dino_vitb16 clip_large_openai --layers 2 5 8 11 \
+    --images examples/images/cat.jpg --mode grid --out out/grid.png
+featlens --config configs/example.yaml --images examples/images/cat.jpg --out out/grid.png
+```
+
+## Image size & resizing
+
+Images are resized to a square **`img_size` × `img_size`** before the model (default **224**).
+`img_size` must be divisible by the model's patch size (multiples of 16 for patch-16 models,
+14 for patch-14). Larger sizes give a finer feature grid at more compute:
+
+```python
+ll.visualize("dinov2_vitb14", "img.jpg", layers=[2, 5, 8, 11], img_size=448)   # 32x32 grid
+```
+
+For **non-square images**, choose how aspect ratio is handled with `resize_mode`:
+
+| `resize_mode` | behavior |
+|---------------|----------|
+| `squash` (default) | resize straight to `img_size²` — may distort |
+| `crop` | resize shortest side to `img_size`, center-crop — aspect preserved |
+| `pad` | resize longest side to `img_size`, pad to square — keeps the whole image |
+
+```python
+ll.grid([...], "wide.jpg", resize_mode="crop")          # Python
+```
+
+```bash
+featlens --models dino_vitb16 --images wide.jpg --resize-mode pad --img-size 448 --out g.png
+```
+
+(`FeatureGrid(interpolation_size=…)` is separate — it only upscales the rendered tiles, not the
+model input.)
+
+## Model sources
+
+| Source | How to pass it | Needs |
+|--------|----------------|-------|
+| **timm** | friendly name (`dinov2_vitb14`) or raw id (`vit_base_patch16_224`) | `[timm]` |
+| **HuggingFace** | `hf:facebook/dinov2-base` | `[hf]` |
+| **torch.hub (V-JEPA)** | `vjepa2_vitl16` | network for weights |
+| **External repo** (VGGT/SPA/…) | `external_adapter.load(repo_dir, builder, hook_target=…)` | the cloned repo |
+| **Your own model** | `custom_adapter.load(model, feature_fn=…)` | — |
+
+Friendly names (see `featlens/registry.py`) cover DINO, DINOv2/v3, CLIP, SigLIP, MAE, DeiT,
+Perception Encoder and V-JEPA; any other timm id works directly.
+
+## Layers
+
+`layers=[2, 5, 8, 11]` selects **transformer block indices** (0-based, **negatives allowed**,
+`-1` = last). The same convention holds across backends — for HuggingFace models FeatLens maps
+block `i` to `hidden_states[i+1]` (skipping the embedding output) for you.
+
+## Bring your own model
+
+Anything that isn't built in works through the escape hatch — give a feature function or a hook
+target. CNNs work for free (their conv map is already spatial):
+
+```python
+import torch.nn as nn, torchvision
+from featlens import FeatureExtractor, FeatureGrid
+from featlens.adapters import custom_adapter
+
+resnet = torchvision.models.resnet50(weights="DEFAULT")
+trunk = nn.Sequential(*list(resnet.children())[:-2])           # -> [B, 2048, h, w]
+lm = custom_adapter.load(trunk, patch_size=32, feature_fn=lambda m, x: m(x), name="resnet50")
+FeatureGrid([FeatureExtractor(lm)]).render("img.jpg", out_path="resnet50.png")
+```
+
+For a model in its own repo, `external_adapter.load(repo_dir, builder, hook_target="blocks")`
+puts the repo on `sys.path`, builds the model, and hooks its blocks.
+
+## How it works
+
+1. **Adapters** resolve a spec → a `LoadedModel` and drive extraction in one of three modes:
+   forward **hooks** on per-block modules (ViTs/CNNs/V-JEPA), HF **`output_hidden_states`**, or a
+   user **callable**.
+2. `tokens_to_grid` normalizes whatever a layer emits (`[B,N,D]` tokens with optional
+   CLS/register prefixes, or `[B,D,h,w]` maps) into a dense `[B,D,h,w]` grid.
+3. **Robust PCA** (median-absolute-deviation outlier filtering) projects features to RGB;
+   `FeatureGrid` lays out the model × layer tiles with a per-tile or shared-per-model basis.
+
+The extraction core adapts the `FrozenBackbone` pattern; the PCA is adapted from the SpaRRTa
+feature-map script.
+
+## Releasing
+
+Releases publish to [PyPI](https://pypi.org/project/featlens/) automatically via
+`.github/workflows/publish.yml` (PyPI **Trusted Publishing** — no API token stored in the repo).
+
+One-time setup on PyPI: add a *trusted publisher* for the project (Account → Publishing) with
+owner `turhancan97`, repository `FeatLens`, workflow `publish.yml`, environment `pypi`. PyPI
+supports a *pending* publisher so the very first release can also go through Actions.
+
+Then cut a release by pushing a tag:
+
+```bash
+# bump the version in pyproject.toml first, then:
+git tag v0.1.0 && git push origin v0.1.0
+```
+
+The workflow builds the sdist + wheel, runs `twine check`, and uploads to PyPI.
+
+## License
+
+[MIT](LICENSE).

featlens-0.1.0/README.md

@@ -0,0 +1,177 @@
+# FeatLens
+
+[![Tests](https://github.com/turhancan97/FeatLens/actions/workflows/test.yml/badge.svg)](https://github.com/turhancan97/FeatLens/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/featlens)](https://pypi.org/project/featlens/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**See what any vision model encodes.** FeatLens renders PCA-to-RGB **feature maps** for
+**any** vision model — DINO, DINOv2/v3, CLIP, SigLIP, MAE, DeiT, V-JEPA, CNNs, … — loaded from
+**any** source (timm, HuggingFace `transformers`, `torch.hub`, an external repo, or a model you
+built yourself), and from **any layer**, as a clean **model × layer** grid.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/turhancan97/FeatLens/main/examples/feat_cat.png" alt="DINO feature maps across layers" width="100%">
+</p>
+
+Most "DINO PCA" scripts are welded to one model. FeatLens separates **representation access**
+(a small adapter layer over the model zoo) from **visualization** (robust PCA → RGB), so you can
+point it at a new model in seconds and compare models/layers side by side.
+
+## Gallery
+
+All produced by `examples/quickstart.py` on the three bundled images. Sizes below are the
+**originals**; each image is resized to `img_size` (default 224) before the model.
+
+**`visualize(...)` — DINO ViT-B/16 feature maps across layers 2 / 5 / 8 / 11:**
+
+| Image (original size) | Source | Feature maps |
+|---|---|---|
+| `astronaut.jpg` · 512×512 | <img src="https://raw.githubusercontent.com/turhancan97/FeatLens/main/examples/images/astronaut.jpg" width="110"> | <img src="https://raw.githubusercontent.com/turhancan97/FeatLens/main/examples/feat_astronaut.png" width="430"> |
+| `cat.jpg` · 451×300 | <img src="https://raw.githubusercontent.com/turhancan97/FeatLens/main/examples/images/cat.jpg" width="110"> | <img src="https://raw.githubusercontent.com/turhancan97/FeatLens/main/examples/feat_cat.png" width="430"> |
+| `coffee.jpg` · 600×400 | <img src="https://raw.githubusercontent.com/turhancan97/FeatLens/main/examples/images/coffee.jpg" width="110"> | <img src="https://raw.githubusercontent.com/turhancan97/FeatLens/main/examples/feat_coffee.png" width="430"> |
+
+**`grid(...)` — model × layer, overlaid on the image** (DINO vs DINOv2 across layers 2/5/8/11):
+
+<p align="center"><img src="https://raw.githubusercontent.com/turhancan97/FeatLens/main/examples/grid_overlay.png" alt="model x layer grid overlay" width="100%"></p>
+
+**`compare(...)` — models at the final layer** &nbsp;|&nbsp; **`custom_adapter` — a ResNet-50 (CNN escape hatch)**
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/turhancan97/FeatLens/main/examples/compare_models.png" alt="compare models at last layer" height="320">
+  &nbsp;&nbsp;
+  <img src="https://raw.githubusercontent.com/turhancan97/FeatLens/main/examples/resnet50.png" alt="resnet50 feature map" height="320">
+</p>
+
+## Install
+
+```bash
+pip install -e ".[timm]"          # timm backend (DINO, CLIP, SigLIP, DeiT, ...)
+# extras: [hf] transformers · [clip] open_clip · [all]
+```
+
+Install PyTorch for your platform first (https://pytorch.org).
+
+## Quick start (Python)
+
+```python
+import featlens as ll
+
+# One model, scrub layers (shared PCA basis -> colors comparable across the row)
+ll.visualize("dinov2_vitb14", "img.jpg", layers=[2, 5, 8, 11], out="row.png")
+
+# Compare models at the final layer (per-tile basis)
+ll.compare(["dino_vitb16", "mae_vitb16", "clip_large_openai"], "img.jpg", layer=-1, out="cmp.png")
+
+# Full model x layer grid, overlaid on the image
+ll.grid(["dino_vitb16", "dinov2_vitb14"], "img.jpg", layers=[2, 5, 8, 11], overlay=True, out="grid.png")
+```
+
+## Quick start (CLI)
+
+```bash
+featlens --models dino_vitb16 clip_large_openai --layers 2 5 8 11 \
+    --images examples/images/cat.jpg --mode grid --out out/grid.png
+featlens --config configs/example.yaml --images examples/images/cat.jpg --out out/grid.png
+```
+
+## Image size & resizing
+
+Images are resized to a square **`img_size` × `img_size`** before the model (default **224**).
+`img_size` must be divisible by the model's patch size (multiples of 16 for patch-16 models,
+14 for patch-14). Larger sizes give a finer feature grid at more compute:
+
+```python
+ll.visualize("dinov2_vitb14", "img.jpg", layers=[2, 5, 8, 11], img_size=448)   # 32x32 grid
+```
+
+For **non-square images**, choose how aspect ratio is handled with `resize_mode`:
+
+| `resize_mode` | behavior |
+|---------------|----------|
+| `squash` (default) | resize straight to `img_size²` — may distort |
+| `crop` | resize shortest side to `img_size`, center-crop — aspect preserved |
+| `pad` | resize longest side to `img_size`, pad to square — keeps the whole image |
+
+```python
+ll.grid([...], "wide.jpg", resize_mode="crop")          # Python
+```
+
+```bash
+featlens --models dino_vitb16 --images wide.jpg --resize-mode pad --img-size 448 --out g.png
+```
+
+(`FeatureGrid(interpolation_size=…)` is separate — it only upscales the rendered tiles, not the
+model input.)
+
+## Model sources
+
+| Source | How to pass it | Needs |
+|--------|----------------|-------|
+| **timm** | friendly name (`dinov2_vitb14`) or raw id (`vit_base_patch16_224`) | `[timm]` |
+| **HuggingFace** | `hf:facebook/dinov2-base` | `[hf]` |
+| **torch.hub (V-JEPA)** | `vjepa2_vitl16` | network for weights |
+| **External repo** (VGGT/SPA/…) | `external_adapter.load(repo_dir, builder, hook_target=…)` | the cloned repo |
+| **Your own model** | `custom_adapter.load(model, feature_fn=…)` | — |
+
+Friendly names (see `featlens/registry.py`) cover DINO, DINOv2/v3, CLIP, SigLIP, MAE, DeiT,
+Perception Encoder and V-JEPA; any other timm id works directly.
+
+## Layers
+
+`layers=[2, 5, 8, 11]` selects **transformer block indices** (0-based, **negatives allowed**,
+`-1` = last). The same convention holds across backends — for HuggingFace models FeatLens maps
+block `i` to `hidden_states[i+1]` (skipping the embedding output) for you.
+
+## Bring your own model
+
+Anything that isn't built in works through the escape hatch — give a feature function or a hook
+target. CNNs work for free (their conv map is already spatial):
+
+```python
+import torch.nn as nn, torchvision
+from featlens import FeatureExtractor, FeatureGrid
+from featlens.adapters import custom_adapter
+
+resnet = torchvision.models.resnet50(weights="DEFAULT")
+trunk = nn.Sequential(*list(resnet.children())[:-2])           # -> [B, 2048, h, w]
+lm = custom_adapter.load(trunk, patch_size=32, feature_fn=lambda m, x: m(x), name="resnet50")
+FeatureGrid([FeatureExtractor(lm)]).render("img.jpg", out_path="resnet50.png")
+```
+
+For a model in its own repo, `external_adapter.load(repo_dir, builder, hook_target="blocks")`
+puts the repo on `sys.path`, builds the model, and hooks its blocks.
+
+## How it works
+
+1. **Adapters** resolve a spec → a `LoadedModel` and drive extraction in one of three modes:
+   forward **hooks** on per-block modules (ViTs/CNNs/V-JEPA), HF **`output_hidden_states`**, or a
+   user **callable**.
+2. `tokens_to_grid` normalizes whatever a layer emits (`[B,N,D]` tokens with optional
+   CLS/register prefixes, or `[B,D,h,w]` maps) into a dense `[B,D,h,w]` grid.
+3. **Robust PCA** (median-absolute-deviation outlier filtering) projects features to RGB;
+   `FeatureGrid` lays out the model × layer tiles with a per-tile or shared-per-model basis.
+
+The extraction core adapts the `FrozenBackbone` pattern; the PCA is adapted from the SpaRRTa
+feature-map script.
+
+## Releasing
+
+Releases publish to [PyPI](https://pypi.org/project/featlens/) automatically via
+`.github/workflows/publish.yml` (PyPI **Trusted Publishing** — no API token stored in the repo).
+
+One-time setup on PyPI: add a *trusted publisher* for the project (Account → Publishing) with
+owner `turhancan97`, repository `FeatLens`, workflow `publish.yml`, environment `pypi`. PyPI
+supports a *pending* publisher so the very first release can also go through Actions.
+
+Then cut a release by pushing a tag:
+
+```bash
+# bump the version in pyproject.toml first, then:
+git tag v0.1.0 && git push origin v0.1.0
+```
+
+The workflow builds the sdist + wheel, runs `twine check`, and uploads to PyPI.
+
+## License
+
+[MIT](LICENSE).

featlens-0.1.0/featlens/__init__.py

@@ -0,0 +1,48 @@
+"""FeatLens — model-agnostic feature-map visualization.
+
+Load any vision model (timm / HuggingFace / torch.hub / external repo / your own) and render
+PCA-to-RGB feature maps from any layer, as a model × layer grid.
+
+Quick start::
+
+    import featlens as ll
+    ll.grid(["dino_vitb16", "clip_large_openai"], "img.jpg", layers=[2, 5, 8, 11], out="grid.png")
+    ll.visualize("dinov2_vitb14", "img.jpg", layers=[2, 5, 8, 11], out="row.png")   # scrub layers
+    ll.compare(["dino_vitb16", "mae_vitb16"], "img.jpg", layer=-1, out="cmp.png")    # compare models
+"""
+
+from typing import Optional, Sequence, Union
+from pathlib import Path
+
+from .extractor import FeatureExtractor
+from .grid import FeatureGrid
+
+__version__ = "0.1.0"
+__all__ = ["FeatureExtractor", "FeatureGrid", "grid", "visualize", "compare"]
+
+
+_RENDER_KEYS = ("overlay", "overlay_alpha", "figscale")
+
+
+def _split_kwargs(kwargs):
+    render_kw = {k: kwargs.pop(k) for k in list(kwargs) if k in _RENDER_KEYS}
+    return kwargs, render_kw
+
+
+def grid(models, images, layers=None, out=None, **kwargs):
+    """Render a full model × layer grid (per-tile PCA basis by default)."""
+    ctor_kw, render_kw = _split_kwargs(kwargs)
+    return FeatureGrid(models, layers=layers, **ctor_kw).render(images, out_path=out, **render_kw)
+
+
+def visualize(model, images, layers=None, out=None, **kwargs):
+    """One model across layers — uses a shared PCA basis so colors are comparable across the row."""
+    kwargs.setdefault("basis", "shared_per_model")
+    ctor_kw, render_kw = _split_kwargs(kwargs)
+    return FeatureGrid([model], layers=layers, **ctor_kw).render(images, out_path=out, **render_kw)
+
+
+def compare(models, images, layer: int = -1, out=None, **kwargs):
+    """Many models at a single layer (per-tile PCA basis)."""
+    ctor_kw, render_kw = _split_kwargs(kwargs)
+    return FeatureGrid(models, layers=[layer], **ctor_kw).render(images, out_path=out, **render_kw)

featlens-0.1.0/featlens/adapters/__init__.py

@@ -0,0 +1,42 @@
+"""Adapter registry + dispatch.
+
+``load_spec(spec, ...)`` resolves a string spec (via ``registry.resolve_spec``) to a
+``LoadedModel`` using the right backend. The ``custom`` and ``external`` backends are not
+string-dispatched — call ``custom_adapter.load(model, ...)`` /
+``external_adapter.load(repo_dir, builder, ...)`` directly (they need Python objects).
+"""
+
+from __future__ import annotations
+
+from .base import LoadedModel, infer_patch_size, real_index
+from . import timm_adapter, hf_adapter, torchhub_adapter, custom_adapter, external_adapter
+from ..registry import resolve_spec
+
+_STRING_BACKENDS = {
+    "timm": timm_adapter.load,
+    "hf": hf_adapter.load,
+    "hub": torchhub_adapter.load,
+}
+
+
+def load_spec(spec: str, img_size: int = 224, pretrained: bool = True, **kwargs) -> LoadedModel:
+    backend, ident = resolve_spec(spec)
+    if backend not in _STRING_BACKENDS:
+        raise ValueError(
+            f"Backend '{backend}' is not string-dispatchable. Use "
+            "custom_adapter.load(model, ...) or external_adapter.load(repo_dir, builder, ...)."
+        )
+    return _STRING_BACKENDS[backend](ident, img_size=img_size, pretrained=pretrained, **kwargs)
+
+
+__all__ = [
+    "LoadedModel",
+    "infer_patch_size",
+    "real_index",
+    "load_spec",
+    "timm_adapter",
+    "hf_adapter",
+    "torchhub_adapter",
+    "custom_adapter",
+    "external_adapter",
+]

featlens-0.1.0/featlens/adapters/base.py

@@ -0,0 +1,68 @@
+"""Adapter base types.
+
+Every backend (timm / hf / torchhub / external / custom) resolves a model spec into a
+``LoadedModel`` descriptor. The extractor then drives all of them uniformly via one of
+three modes:
+
+- ``"hook"``          : register forward hooks on per-block modules (ViTs, CNNs, V-JEPA).
+- ``"hidden_states"`` : run once with ``output_hidden_states=True`` and read the tuple (HF).
+- ``"callable"``      : call a user ``feature_fn(model, images)`` (the escape hatch).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable, Optional, Sequence
+
+import torch.nn as nn
+
+
+@dataclass
+class LoadedModel:
+    model: nn.Module
+    num_blocks: int
+    embed_dim: int
+    patch_size: int
+    mean: Sequence[float]
+    std: Sequence[float]
+    mode: str  # "hook" | "hidden_states" | "callable"
+    # mode="hook": maps (model, block_index) -> the submodule to hook.
+    hook_module_fn: Optional[Callable[[nn.Module, int], nn.Module]] = None
+    # mode="callable": feature_fn(model, images) -> [B, N, D] or [B, D, h, w].
+    feature_fn: Optional[Callable] = None
+    # mode="hidden_states": +1 offset so block index i -> hidden_states[i+1] (skip embeddings).
+    hidden_states_offset: int = 1
+    uses_temporal: bool = False  # V-JEPA 2.1 expects a time axis
+    name: str = "model"
+    extra: dict = field(default_factory=dict)
+
+
+def infer_patch_size(model: nn.Module) -> Optional[int]:
+    """Infer a square ViT patch size from a model's patch_embed, if present."""
+    patch_embed = getattr(model, "patch_embed", None)
+    if patch_embed is None:
+        return None
+    patch_size = getattr(patch_embed, "patch_size", None)
+    if patch_size is not None:
+        if isinstance(patch_size, (tuple, list)):
+            if len(patch_size) != 2 or patch_size[0] != patch_size[1]:
+                raise ValueError(f"Only square patch sizes are supported, got {patch_size}.")
+            return int(patch_size[0])
+        return int(patch_size)
+    proj = getattr(patch_embed, "proj", None)
+    kernel_size = getattr(proj, "kernel_size", None)
+    if kernel_size is not None:
+        if isinstance(kernel_size, (tuple, list)):
+            if len(kernel_size) != 2 or kernel_size[0] != kernel_size[1]:
+                raise ValueError(f"Only square patch sizes are supported, got {kernel_size}.")
+            return int(kernel_size[0])
+        return int(kernel_size)
+    return None
+
+
+def real_index(idx: int, num_blocks: int) -> int:
+    """Resolve a possibly-negative block index against the block count."""
+    r = idx if idx >= 0 else num_blocks + idx
+    if not (0 <= r < num_blocks):
+        raise ValueError(f"Layer index {idx} out of range for a model with {num_blocks} blocks.")
+    return r

featlens-0.1.0/featlens/adapters/custom_adapter.py

@@ -0,0 +1,67 @@
+"""Custom backend — the escape hatch for any model the built-in backends don't cover.
+
+Two ways to use it:
+
+1. **Hook target** — pass an already-built ``model`` plus ``hook_target``: either a callable
+   ``(model, block_idx) -> module`` or the name of a ``ModuleList`` attribute (e.g. ``"blocks"``)
+   whose elements are hooked.
+2. **feature_fn** — pass ``feature_fn(model, images) -> [B, N, D]`` (or ``[B, D, h, w]``) and
+   FeatLens skips hooks entirely. Best for exotic models / single-layer extraction.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Optional, Sequence, Union
+
+import torch.nn as nn
+
+from .base import LoadedModel, infer_patch_size, real_index
+from ..preprocess import IMAGENET_MEAN, IMAGENET_STD
+
+
+def load(
+    model: nn.Module,
+    *,
+    patch_size: Optional[int] = None,
+    hook_target: Optional[Union[str, Callable[[nn.Module, int], nn.Module]]] = None,
+    feature_fn: Optional[Callable] = None,
+    num_blocks: Optional[int] = None,
+    mean: Sequence[float] = IMAGENET_MEAN,
+    std: Sequence[float] = IMAGENET_STD,
+    name: str = "custom",
+) -> LoadedModel:
+    if (hook_target is None) == (feature_fn is None):
+        raise ValueError("Provide exactly one of `hook_target` or `feature_fn`.")
+
+    if patch_size is None:
+        patch_size = infer_patch_size(model)
+        if patch_size is None:
+            raise ValueError(
+                "Could not infer patch_size for the custom model; pass patch_size=... "
+                "(the stride/downsample factor between input pixels and the feature grid)."
+            )
+
+    if feature_fn is not None:
+        return LoadedModel(
+            model=model, num_blocks=num_blocks or 1, embed_dim=0, patch_size=int(patch_size),
+            mean=mean, std=std, mode="callable", feature_fn=feature_fn, name=name,
+        )
+
+    if callable(hook_target):
+        hook_fn = hook_target
+        nblocks = num_blocks or 0
+    else:
+        module_list = getattr(model, hook_target, None)
+        if module_list is None or not hasattr(module_list, "__getitem__"):
+            raise ValueError(
+                f"hook_target '{hook_target}' is not a ModuleList attribute on the model."
+            )
+        nblocks = len(module_list)
+
+        def hook_fn(m: nn.Module, idx: int) -> nn.Module:
+            return getattr(m, hook_target)[real_index(idx, nblocks)]
+
+    return LoadedModel(
+        model=model, num_blocks=nblocks or 1, embed_dim=0, patch_size=int(patch_size),
+        mean=mean, std=std, mode="hook", hook_module_fn=hook_fn, name=name,
+    )