README.md

---
language:
- en
- te
license: apache-2.0
tags:
- carnatic-music
- konakol
- solkattu
- swara
- tala
- rhythmic-patterns
- indian-classical-music
- music-generation
- fine-tuned
- unsloth
- llama
- lora
base_model: unsloth/llama-3.2-3B-bnb-4bit
pipeline_tag: text-generation
---

# KonakolSwara LLM

**A domain-specialized generative language model for Carnatic rhythmic composition (Konakol/Solkattu) and melodic Swara sequence generation — trained to produce creative, grammatically authentic patterns in the Telugu script tradition of South Indian classical music.**

---

## Overview

South Indian (Carnatic) classical music is built upon two interlocking theoretical pillars: **Tala** (rhythm) and **Raga** (melody). While much of music AI focuses on audio synthesis, this model addresses the *compositional notation* layer — the articulation of rhythmic and melodic ideas through the symbolic vocabulary that Carnatic musicians have used for centuries.

**Konakol** (also called *Solkattu* in Telugu/Tamil) is the art of vocal percussion — the recitation of codified rhythmic syllables (such as *తకిట, తరికిట, తకధిమి*) that correspond precisely to strokes on the Mridangam (the double-headed barrel drum that anchors Carnatic rhythm). Konakol is simultaneously a theoretical notation system, a pedagogical tool, and a performance art in its own right.

**Swara sequence composition** involves the creative arrangement of the seven swaras (Sa Ri Ga Ma Pa Da Ni — సా రి గ మ ప ద ని) into melodic phrases, scale exercises (*Varisai*), and improvisational patterns (*Kalpana Swara*).

*KonakolSwara LLM* is trained to generate both categories of musical text with structural fidelity to Carnatic theory — producing compositions that are not merely plausible-looking character sequences, but reflect the internal logic of Tala cycles, Nadai (rhythmic subdivision), syllable families, and scalar grammar.

---

## Musical Background

### Konakol: Vocal Percussion

Konakol syllables are derived from Sanskrit and Tamil phonemes and map to specific Mridangam strokes. The syllable families, organized by beat duration, include:

| Duration | Telugu Syllables | Transliteration |
|---|---|---|
| 1 beat | తా, తోమ్, తహ, ధిన్ | tā, tom, tah, dhin |
| 2 beats | తక, ధిమి, జిమి, ధిత్తై, గిన | taka, dhimi, jimi, dhittai, gina |
| 3 beats | తకిట, తరికిట, తక్కిట, తనన | takita, tarikita, takkita, tanana |
| 4 beats | తకధిమి, తకజిమి, తకజను, తరిగిన | takadhimi, takajimi, takajanu, tarigina |

These syllables are combined to fill **Tala cycles** — rhythmic loops of fixed length. The most common Tala is **Adi Tala** (8 beats). The **Nadai** (gait) subdivides each beat: Chatusra (4 subdivisions), Tisra (3), Khanda (5), Misra (7).

A **Korvai** is a rhythmic cadence — a phrase stated exactly three times that resolves to the first beat (Sam) of the Tala cycle, providing musical closure.

### Swara Sequences

The seven swaras (Sa Ri Ga Ma Pa Da Ni), their komal/tivra variants, and their arrangements form the basis of Carnatic melodic pedagogy. Standard compositional exercises include:

- **Sarali Varisai** — straight ascending/descending scale patterns in groups of four
- **Janta Varisai** — doubled-note exercises (Sa Sa Ri Ri Ga Ga...)
- **Alankara** — structured patterns in different speeds and Nadais
- **Kalpana Swara** — free melodic improvisation within a raga's grammatical constraints

---

## Capabilities

This model can:

- **Generate complete Konakol compositions** in a specified Tala and Nadai, using authentic syllable combinations
- **Compose Korvai patterns** — three-fold resolution phrases with correct Sam landing
- **Generate Swara sequence compositions** in ascending, descending, zigzag, and raga-specific patterns
- **Demonstrate Kuraippu** (gradual reduction technique where phrases shorten over successive repetitions)
- **Demonstrate Nadai Bheda** (switching rhythmic gait within a single composition)
- **Explain Konakol theory** — syllable families, beat values, Tala structures, Nadai theory
- **Explain Swara theory** — Varisai types, Alankara, Kalai (speed), Kalpana Swara
- **Generate combined Konakol + Swara compositions** that pair rhythmic and melodic notation

---

## How to Use

```python
from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

model_id = "sgattup/KonakolSwaraLLM"
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    torch_dtype=torch.float16,
    device_map="auto"
)

PROMPT = """You are an expert in Carnatic classical music, specializing in Konakol (Solkattu) — the vocal recitation of rhythmic syllables — and Swara sequence composition. You can explain Tala theory, compose creative Konakol patterns, generate melodic Swara sequences, and teach the grammar of South Indian rhythm and melody.

### Question:
{}

### Answer:
"""

def ask(question, max_tokens=800):
    prompt = PROMPT.format(question)
    inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
    outputs = model.generate(
        **inputs,
        max_new_tokens=max_tokens,
        temperature=0.8,
        do_sample=True
    )
    response = tokenizer.decode(outputs[0], skip_special_tokens=True)
    return response.split("### Answer:")[-1].strip()

# Generate a Konakol composition
print(ask("Compose a Konakol pattern in Adi Tala using takita and tarikita combinations."))

# Generate swara sequences
print(ask("Generate a creative swara composition with all seven notes in Telugu notation."))

# Ask about theory
print(ask("What is a Korvai and how is it constructed?"))

# Generate a Korvai
print(ask("Create a Korvai — a three-fold resolution pattern that lands on Sam in Adi Tala."))
```

---

## Illustrative Outputs

**Q: Compose a Konakol pattern in Adi Tala, Chatusra Nadai:**

> తకిట తరికిట తకిట తరికిట
> తక్కిట తక్కిట తోమ్ తా
> తకధిమి తకజిమి తోమ్ తోమ్
> తరిగిన తకజను తా
> ధిత్తై తహ తకిట తహ
> ధిమితక జిమితక తోమ్ తా

**Q: Generate a Sarali Varisai swara pattern:**

> సా రి గ మ / ప ద ని సా / సా ని ద ప / మ గ రి సా
> రి గ మ ప / ద ని సా రి / రి సా ని ద / ప మ గ రి
> గ మ ప ద / ని సా రి గ / గ రి సా ని / ద ప మ గ...

**Q: What is Kuraippu?**

> Kuraippu (from Tamil/Telugu కురైప్పు) is a rhythmic device in Carnatic Konakol and Mridangam solos where a phrase is stated in full, then restated in progressively shorter versions — each iteration trimming syllables from the beginning or end while maintaining the rhythmic alignment with the Tala cycle. The effect is one of musical intensification and condensation: the pattern feels like it is being compressed toward a point of culmination. A Kuraippu typically concludes on Sam (the first beat), making it a variant of the Korvai principle...

---

## Model Specifications

| Parameter | Value |
|---|---|
| Base Model | LLaMA 3.2 3B (`unsloth/llama-3.2-3B-bnb-4bit`) |
| Fine-tuning Method | QLoRA via Unsloth |
| Quantization | 4-bit NF4 with double quantization |
| LoRA Rank | 16 |
| LoRA Alpha | 32 |
| Training Epochs | 3 |
| Learning Rate | 2e-4 |
| Training Hardware | Google Colab T4 GPU (free tier) |
| Dataset | 25+ Konakol compositions + 15+ Swara compositions + 15+ theory pairs |
| Script Languages | Telugu (తెలుగు) and English |
| License | Apache 2.0 |

---

## Limitations

- **Tala mathematics:** The model generates syllable patterns that are structurally authentic in style; however, beat-count precision is not mathematically guaranteed. A practicing musician should verify rhythmic sums before performance use.
- **Raga specificity:** Swara sequences are generated based on general scalar logic. For raga-specific composition, pair this model with [RagaLakshanaLLM](https://huggingface.co/sgattup/RagaLakshanaLLM).
- **Telugu script rendering:** Proper display requires Telugu Unicode font support in the rendering environment.
- **Creative vs. canonical:** Generated Konakol compositions are creative/novel, not transcriptions of traditional compositions.

---

## Companion Models

- **[sgattup/RagaLakshanaLLM](https://huggingface.co/sgattup/RagaLakshanaLLM)** — Raga theory, Lakshana, Thaat/Melakarta classification
- **[sgattup/IndianCultureLLM](https://huggingface.co/sgattup/IndianCultureLLM)** — Broad Indian culture, history, philosophy, and arts

---

## Training Code

[github.com/sai-educ/indian-culture-llm](https://github.com/sai-educ/indian-culture-llm)

---

## Citation

```bibtex
@misc{KonakolSwaraLLM2026,
  author       = {sgattup},
  title        = {KonakolSwara LLM: A Generative Model for Carnatic Rhythmic and Melodic Composition},
  year         = {2026},
  publisher    = {HuggingFace},
  howpublished = {\url{https://huggingface.co/sgattup/KonakolSwaraLLM}}
}
```

---

*This model is part of a series of specialized AI models for Indian classical music and culture, developed to make the theoretical and creative vocabulary of Indian traditions more accessible through natural language interfaces.*