Update README.md

README.md

@@ -1,4 +1,3 @@
-
 ---
 license: apache-2.0
 library_name: pytorch
@@ -11,72 +10,58 @@ tags:
   - perch
 ---
 
-# Perch v2 — PyTorch backbone weights
+# ⚠️ Deprecated — see [`perchv2-pytorch`](https://github.com/bghani/perchv2-pytorch) instead
 
-Unofficial, community-converted PyTorch weights for Google's [Perch v2](https://www.kaggle.com/models/google/bird-vocalization-classifier) bioacoustic foundation model. Not produced or endorsed by Google. For use with [`perchv2-pytorch`](https://github.com/bghani/perchv2-pytorch) — a PyTorch port built for full deep fine-tuning, linear probing, and frozen-feature extraction (unlike the official [ONNX/tflite releases](https://huggingface.co/justinchuby/Perch-onnx), which are inference-only and have no autograd graph).
+**These weights are no longer the recommended way to use this project.** The main repo now provides a PyTorch backbone built by converting Google's actual released ONNX graph directly (via `onnx2torch`) — confirmed **1.00000000 cosine similarity** against `onnxruntime`'s own output, and fully differentiable. That approach needs the original `perch_v2.onnx` file (see the [main repo README](https://github.com/bghani/perchv2-pytorch#getting-the-weights)), not the weights hosted here.
 
+The weights on this page are kept only as `legacy/` in that repo, for reference — **not recommended for new use.** See why below.
 
 ## What this is
 
-- **Architecture:** stock `timm` `tf_efficientnet_b3`, single-channel input (`in_chans=1`), classification head stripped — returns a pooled **1536-dim** embedding.
-- **Source:** extracted from Google's original JAX/Flax SavedModel (`infer.graph.variables`) and converted into a PyTorch state dict compatible with `timm`'s `tf_efficientnet_b3`.
+Unofficial, community-converted PyTorch weights for Google's [Perch v2](https://www.kaggle.com/models/google/bird-vocalization-classifier) bioacoustic foundation model, built by hand-reconstructing the architecture in `timm`'s `tf_efficientnet_b3` and copying over weights converted from the original JAX/Flax SavedModel. Not produced or endorsed by Google.
+
+- **Architecture:** `timm` `tf_efficientnet_b3`, single-channel input (`in_chans=1`), classification head stripped — returns a pooled **1536-dim** embedding.
 - **File:** `perch_v2_backbone_timm.pt` — backbone weights only (no classification head).
 
-## Known limitation
+## Known limitation — why this is deprecated
+
+Earlier validation reported ~0.80 whole-network cosine similarity, attributed to numerical error accumulating across blocks. That explanation was incomplete. Further investigation found and fixed two real architectural bugs (a stem padding mismatch and a missing convolution bias, both confirmed directly against the ONNX graph), bringing cosine similarity up to **~0.97**.
 
-This is an **independent community conversion**, not an official release from Google. Per-block validation against the original (stem, expand blocks, residual blocks, head) showed 0.999+ cosine similarity, but whole-network cosine similarity plateaus around **~0.80**, likely from small numerical error accumulating across the 26 sequential MBConv blocks. Treat these weights as a strong pretrained initialization for fine-tuning, not a bit-exact reproduction of Google's model.
+That still wasn't the full picture. A later three-way comparison — real ONNX output, the `onnx2torch`-converted backbone, and this `timm` backbone — found this backbone sitting at a **relative L2 error of ~0.23–0.29** against the true model, despite the reassuring-looking ~0.97 cosine similarity. Cosine similarity measures an angle between vectors; it can look close to 1.0 while the actual magnitude of the error stays large. This showed up concretely: a linear probe trained on this backbone's frozen embeddings converged slower and to a lower accuracy than one trained on the ONNX-converted backbone's embeddings, on the same task.
 
-If you need bit-exact frozen embeddings rather than a trainable backbone, use the [official ONNX/tflite build](https://huggingface.co/justinchuby/Perch-onnx) instead.
+A further architectural bug was identified (blocks 5, 8, and 18 also use asymmetric padding, the same class of issue as the original stem bug) but attempting to fix it caused an unexplained regression, so it was left unfixed. Whether this is the source of the remaining L2 gap is an open question — full details in [`legacy/README.md`](https://github.com/bghani/perchv2-pytorch/blob/main/legacy/README.md).
 
-## Usage
+**If you need accurate, trainable embeddings, use the ONNX-converted backbone in the main repo instead — not these weights.**
 
-### 1. Frozen features
+## Usage (legacy — see the note above)
+
+`legacy` is not part of the installed `perchv2_pytorch` package — clone the [main repo](https://github.com/bghani/perchv2-pytorch) and add its root to `sys.path`:
 
 ```python
+import sys
+sys.path.insert(0, "/path/to/perchv2-pytorch")
+
 import torch
 from huggingface_hub import hf_hub_download
-from perchv2_pytorch import Perch2Embedder
+from legacy import PerchFrontend, Perch2Classifier, Perch2Embedder
 
 weights_path = hf_hub_download(repo_id="bghani/perch2-pytorch-weights", filename="perch_v2_backbone_timm.pt")
 
+# 1. Frozen features
 embedder = Perch2Embedder(weights_path=weights_path)
 embedder.eval()
-
 waveform = torch.zeros(4, 160_000)  # 5s clips @ 32kHz, batch of 4
 with torch.no_grad():
     embeddings = embedder(waveform)  # (4, 1536)
-```
-
-### 2. Linear probing
-
-```python
-from perchv2_pytorch import PerchFrontend, Perch2Classifier
 
+# 2. Linear probing
 mel = PerchFrontend()
-model = Perch2Classifier(
-    num_classes=42,
-    mel=mel,
-    weights_path=weights_path,
-    mode="linear_probe",   # backbone frozen, only the new head trains
-)
-```
-
-### 3. Full fine-tuning
+model = Perch2Classifier(num_classes=42, mel=mel, weights_path=weights_path, mode="linear_probe")
 
-```python
-from perchv2_pytorch import PerchFrontend, Perch2Classifier
-
-mel = PerchFrontend()
-model = Perch2Classifier(
-    num_classes=42,
-    mel=mel,
-    weights_path=weights_path,
-    mode="finetune",   # backbone unfrozen -- this is the whole point of this repo
-)
+# 3. Full fine-tuning
+model = Perch2Classifier(num_classes=42, mel=mel, weights_path=weights_path, mode="finetune")
 ```
 
-See the [main repo](https://github.com/bghani/perchv2-pytorch) for full usage — frozen embeddings, linear probing, and full fine-tuning, with runnable examples and a walkthrough notebook.
-
 ## License
 
 Apache 2.0, inherited from the original Perch v2 release. See [NOTICE](https://github.com/bghani/perchv2-pytorch/blob/main/NOTICE) in the main repo for the full derivative-work attribution.
@@ -84,25 +69,11 @@ Apache 2.0, inherited from the original Perch v2 release. See [NOTICE](https://g
 ## Citation
 
 If you use this in published work, please cite the original Perch v2 paper:
-
 ```
 @article{van2025perch,
-  title={Perch 2.0: The bittern lesson for bioacoustics},
-  author={van Merri{\"e}nboer, Bart and Dumoulin, Vincent and Hamer, Jenny and Harrell, Lauren and Burns, Andrea and Denton, Tom},
-  journal={arXiv preprint arXiv:2508.04665},
-  year={2025}
+title={Perch 2.0: The bittern lesson for bioacoustics},
+author={van Merri{"e}nboer, Bart and Dumoulin, Vincent and Hamer, Jenny and Harrell, Lauren and Burns, Andrea and Denton, Tom},
+journal={arXiv preprint arXiv:2508.04665},
+year={2025}
 }
 ```
-If you use this specific PyTorch conversion, please also cite [ChiroEcho](https://arxiv.org/abs/2608.18191), where it was first developed and applied (CV4Ecology - ECCV 2026):
-
-```
-@misc{ghani2026chiroechoextendingautomatedbat,
-title={ChiroEcho: extending automated bat vocalisation classification beyond the learned taxonomy},
-author={Burooj Ghani and Welmoed Eversteijn and Milan van Hirtum and Juan Sebastián Cañas and Vincent J. Kalkman and Dan Stowell and A. Leonie Baier},
-year={2026},
-eprint={2608.18191},
-archivePrefix={arXiv},
-primaryClass={cs.LG},
-url={https://arxiv.org/abs/2608.18191},
-}
-```