---
language:
  - en
license: apache-2.0
library_name: transformers
pipeline_tag: text-generation
base_model: distilgpt2
tags:
  - gpt2
  - lyrics
  - suno
  - music
  - scansion
  - text-generation
widget:
  - text: "Title: Heat Line\nIdea: A man scraping survival out of desert heat, stubborn will over panic.\nVerse:\n"
    example_title: Desert verse
  - text: "Title: As It Stays\nIdea: Driving the empty freeway after a fight you cannot unsay.\nChorus:\n"
    example_title: Night chorus
---

# 🏭 Scansion-LM Foundry

A high-performance causal language modeling harness that learns rhyme density, poetic scansion, and structured lyric progressions for Suno Custom Mode.

Fine-tuned from `distilgpt2` on clean, original lyric extracts. The model produces natural English rhythmic lines conforming to Suno Studio V6 scansion rules.

---

## ⚡ Quick Start

### 1. Launch Loopback HTTP Sidecar (Port 8099)
```powershell
.\run-engine.cmd
```
*Hosts the loopback server on `http://127.0.0.1:8099`, automatically connecting to Scansion Studio Web UI.*

### 2. Command Line Pipeline Operations
```powershell
# Extract meter, rhyme schemes, and sections
python -m scansion_lm extract 640

# Tokenize corpus using Hugging Face AutoTokenizer
python -m scansion_lm tokenize

# Fine-tune causal language model
python -m scansion_lm train 300 640

# Evaluate against gold standard metric sheet
python -m scansion_lm eval

# Verify weights and model card readiness
python -m scansion_lm check

# Export model bundle for Hugging Face Hub
python -m scansion_lm export
```

---

## 📡 Sidecar HTTP API Endpoints (Port 8099)

| Method | Endpoint | Description |
|---|---|---|
| `GET` | `/health` | Instant readiness and training state probe |
| `GET` | `/status` | Phase, step count, loss, and training process ID |
| `GET` | `/metrics` | Real-time training loss and validation progression |
| `GET` | `/trending` | Returns cached Suno trending metadata and tags |
| `POST` | `/ingest-batch` | Batch ingests new song lyrics into `user_extracts.jsonl` |
| `POST` | `/train` | Spawns background fine-tuning process |
| `POST` | `/infer` | Autoregressive lyric generation from idea/theme |
| `POST` | `/extract` | Scans input lyrics for feet, meter, and rhyme scheme |

---

## 🧠 Model Architecture

| Component | Specification |
|---|---|
| Base Architecture | `distilgpt2` (`GPT2LMHeadModel`) |
| Parameters | 81,912,576 (81.9M) |
| Vocabulary Size | 50,257 tokens (GPT-2 BPE) |
| Context Length | 1,024 tokens (256 training window) |
| Storage Format | `safetensors` (zero pickle vulnerability) |
| Checkpoint Size | ~327 MB |

---

## 📄 License

Licensed under the **Apache 2.0 License**. See `LICENSE` for details.


## Checkpoint

- architecture: `['GPT2LMHeadModel']`
- vocab_size: `50260`
- n_positions: `1024`
- n_layer / n_embd / n_head: `6 / 768 / 12`
- parameters: `81914880`
- steps: `300/300`
- train loss (avg): `4.009729862213135`
- examples: `3500`

Load with vanilla Transformers — no custom `auto_map`:

```python
from transformers import AutoModelForCausalLM, AutoTokenizer
tok = AutoTokenizer.from_pretrained("scansion-lm")
model = AutoModelForCausalLM.from_pretrained("scansion-lm")
prompt = """Title: Heat Line
Idea: A man scraping survival out of desert heat, stubborn will over panic.
Verse:
"""
ids = tok(prompt, return_tensors="pt")
out = model.generate(**ids, max_new_tokens=80, do_sample=True, temperature=0.85,
                    pad_token_id=tok.pad_token_id, eos_token_id=tok.eos_token_id)
print(tok.decode(out[0], skip_special_tokens=False))
```

Upload:

```bash
huggingface-cli upload ./export scansion-lm --repo-type model
```