wren11ws/sunup

🏭 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)

.\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

# 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: 350/350
• train loss (avg): 2.5573558807373047
• examples: 2000

Load with vanilla Transformers — no custom auto_map:

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:

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