Update README.md

README.md

@@ -1,3 +1,53 @@
+
 ---
 license: apache-2.0
+library_name: pytorch
+tags:
+  - bioacoustics
+  - audio-classification
+  - bird-classification
+  - efficientnet
+  - transfer-learning
+  - perch
 ---
+
+# Perch v2 — PyTorch backbone weights
+
+PyTorch-converted backbone weights for Google's [Perch v2](https://www.kaggle.com/models/google/bird-vocalization-classifier) bioacoustic foundation model, for use with [`perch2-pytorch`](https://github.com/YOUR-USERNAME/perch2-pytorch) — a PyTorch port built for frozen-feature extraction, linear probing, and full deep fine-tuning (unlike the official [ONNX/tflite releases](https://huggingface.co/justinchuby/Perch-onnx), which are inference-only and have no autograd graph).
+
+## 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`.
+- **File:** `perch_v2_backbone_timm.pt` — backbone weights only (no classification head).
+
+## Known limitation
+
+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.
+
+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.
+
+## Usage
+
+```python
+from huggingface_hub import hf_hub_download
+from perch2_finetune import Perch2Embedder
+
+weights_path = hf_hub_download(
+    repo_id="bghani/perch2-pytorch-weights",
+    filename="perch_v2_backbone_timm.pt",
+)
+
+embedder = Perch2Embedder(weights_path=weights_path)
+embedder.eval()
+```
+
+See the [main repo](https://github.com/YOUR-USERNAME/perch2-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/YOUR-USERNAME/perch2-pytorch/blob/main/NOTICE) in the main repo for the full derivative-work attribution.
+
+## Citation
+
+If you use these weights in published work, please cite the original Perch v2 paper (arXiv:2508.04665) — check the [official repo](https://github.com/google-research/perch) for the current preferred citation — and note that these specific weights are a community PyTorch conversion.