Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,158 @@
+---
+license: mit
+library_name: pytorch
+tags:
+- music
+- folk-music
+- irish-traditional-music
+- abc-notation
+- symbolic-music
+- representation-learning
+- self-supervised
+- transformer
+pipeline_tag: feature-extraction
+---
+
+# ABC2Vec: Self-Supervised Representation Learning for Irish Folk Music
+
+This is the official pre-trained ABC2Vec model from the paper:
+
+**"ABC2Vec: Self-Supervised Representation Learning for Irish Folk Music"**
+
+## Model Description
+
+ABC2Vec is a self-supervised Transformer encoder that learns dense, semantically meaningful embeddings from ABC notation (symbolic music format). It is specifically designed for Irish traditional folk music and trained on 211,524 tunes.
+
+### Key Features
+
+- 🎵 **Purpose-built for folk music** - Addresses transposition equivalence, modal tonality, and variant detection
+- 🔄 **Transposition Invariance** - Novel TI objective for pitch-invariant representations
+- 📊 **Bar-level Patchification** - 16× sequence length reduction for efficiency
+- 🎯 **Self-supervised** - No text annotations or audio required
+- ⚡ **Efficient** - Trained in 18 hours on Apple M4 Mac
+
+## Model Architecture
+
+- **Layers:** 6
+- **Hidden Size (d_model):** 256
+- **Attention Heads:** 8
+- **FFN Size (d_ff):** 1024
+- **Embedding Size:** 128
+- **Vocabulary Size:** 98
+- **Max Bars:** 64
+- **Max Bar Length:** 64
+- **Parameters:** ~5M
+
+## Training Details
+
+- **Dataset:** 211,524 Irish traditional tunes (IrishMAN corpus)
+- **Training Objectives:**
+  - Masked Music Modeling (MMM)
+  - Transposition Invariance (TI) contrastive learning
+- **Training Steps:** 40,000 steps (40 epochs)
+- **Final Validation Loss:** 2.36
+- **Hardware:** Apple M4 Mac (48GB unified memory)
+- **Training Time:** ~18 hours
+
+## Performance
+
+| Task | Accuracy | Notes |
+|------|----------|-------|
+| Tune Type Classification | 78.4% ± 1.2% | 6 classes (jig, reel, polka, etc.) |
+| Mode Classification | 78.8% ± 1.6% | 4 classes (major, minor, dorian, mixolydian) |
+| Key Root (Linear Probe) | 62.3% ± 0.9% | 8 most common keys |
+| Tune Length (Linear Probe) | 89.5% ± 0.7% | 3 classes (short, medium, long) |
+
+## Usage
+
+```python
+import torch
+import json
+from pathlib import Path
+
+# Load model configuration
+config_path = "model_config.json"
+with open(config_path) as f:
+    config_dict = json.load(f)
+
+# Initialize model (you'll need the ABC2Vec model code)
+from abc2vec.core.model import ABC2VecModel
+from abc2vec.core.model.encoder import ABC2VecConfig
+
+config = ABC2VecConfig(**config_dict)
+model = ABC2VecModel(config)
+
+# Load pre-trained weights
+checkpoint = torch.load("best_model.pt", map_location="cpu")
+model.load_state_dict(checkpoint["model_state_dict"])
+model.eval()
+
+# Load vocabulary for tokenization
+with open("vocab.json") as f:
+    vocab_data = json.load(f)
+
+# Extract embeddings for a tune
+from abc2vec.core.tokenizer import ABCVocabulary, BarPatchifier
+
+vocab = ABCVocabulary.load("vocab.json")
+patchifier = BarPatchifier(
+    vocab=vocab,
+    max_bars=config.max_bars,
+    max_bar_length=config.max_bar_length
+)
+
+# Example ABC tune
+abc_tune = "M:6/8\nK:D\n|:A2A ABc|ded cBA|A2A ABc|ded cAG|"
+patches = patchifier.patchify(abc_tune)
+
+# Get embedding
+with torch.no_grad():
+    bar_indices = patches["bar_indices"].unsqueeze(0)
+    char_mask = patches["char_mask"].unsqueeze(0)
+    bar_mask = patches["bar_mask"].unsqueeze(0)
+
+    embedding = model.get_embedding(bar_indices, char_mask, bar_mask)
+    # embedding shape: (1, 128)
+```
+
+## Code Repository
+
+Full training code, evaluation scripts, and usage examples:
+- **GitHub:** https://github.com/pianistprogrammer/ABC2VEC
+
+## Dataset
+
+The processed dataset with train/validation/test splits:
+- **HuggingFace:** https://huggingface.co/datasets/pianistprogrammer/abc2vec-irish-folk-dataset
+
+## Citation
+
+If you use this model, please cite:
+
+```bibtex
+@article{abc2vec2025,
+  title={ABC2Vec: Self-Supervised Representation Learning for Irish Folk Music},
+  author={[Your Name]},
+  journal={[Journal Name]},
+  year={2025},
+  note={Model: https://huggingface.co/pianistprogrammer/abc2vec-model}
+}
+```
+
+## License
+
+MIT License
+
+## Acknowledgements
+
+We thank The Session community for curating and maintaining the Irish traditional music archive that made this work possible.
+
+## Model Card Authors
+
+[Your Name]
+
+## Contact
+
+For questions or issues:
+- GitHub: https://github.com/pianistprogrammer/ABC2VEC
+- HuggingFace: https://huggingface.co/pianistprogrammer