khamyang 1.0.0__py3-none-any.whl

khamyang/__init__.py

@@ -0,0 +1,75 @@
+"""
+Tai Khamyang (ksu) Language Library
+===================================
+A comprehensive Python library for the revitalization, documentation,
+and computational processing of the critically endangered Tai Khamyang
+language (ISO 639-3: ksu, Glottolog: kham1282) spoken in Assam, India.
+"""
+
+from khamyang.version import __version__, __author__, __license__
+from khamyang.lexicon.dictionary import KhamyangDictionary, get_dictionary
+from khamyang.phonology.tones import ToneSystem, KhamyangTone, gedney_lookup
+from khamyang.transliteration.converter import (
+    transliterate,
+    roman_to_liktai,
+    liktai_to_roman,
+    roman_to_assamese,
+    assamese_to_roman,
+    roman_to_ipa,
+)
+from khamyang.grammar.classifiers import ClassifierEngine
+from khamyang.grammar.naming import get_birth_name, list_birth_names
+from khamyang.grammar.numerals import num_to_khamyang, khamyang_to_num
+from khamyang.phrases.phrasebook import KhamyangPhrasebook, get_phrasebook
+from khamyang.corpus.texts import KhamyangCorpus, get_corpus
+from khamyang.corpus.igt import InterlinearGloss
+from khamyang.corpus.songs import SongEngine
+from khamyang.grammar.kinship import KinshipEngine, CLANS
+from khamyang.scraper.downloader import BibliographyManager
+from khamyang.facade import Khamyang
+from khamyang.nlp import (
+    normalize,
+    tokenize,
+    detokenize,
+    pos_tag,
+    detect_language,
+)
+
+__all__ = [
+    "__version__",
+    "__author__",
+    "__license__",
+    "Khamyang",
+    "KhamyangDictionary",
+    "get_dictionary",
+    "ToneSystem",
+    "KhamyangTone",
+    "gedney_lookup",
+    "transliterate",
+    "roman_to_liktai",
+    "liktai_to_roman",
+    "roman_to_assamese",
+    "assamese_to_roman",
+    "roman_to_ipa",
+    "ClassifierEngine",
+    "get_birth_name",
+    "list_birth_names",
+    "num_to_khamyang",
+    "khamyang_to_num",
+    "KhamyangPhrasebook",
+    "get_phrasebook",
+    "KhamyangCorpus",
+    "get_corpus",
+    "InterlinearGloss",
+    "SongEngine",
+    "KinshipEngine",
+    "CLANS",
+    "BibliographyManager",
+    "normalize",
+    "tokenize",
+    "detokenize",
+    "pos_tag",
+    "detect_language",
+]
+
+

khamyang/cli.py

@@ -0,0 +1,416 @@
+"""
+Tai Khamyang Command-Line Interface
+===================================
+Interactive CLI for developers, linguists, and researchers.
+"""
+
+import sys
+import os
+import click
+from rich.console import Console
+from rich.table import Table
+from rich.panel import Panel
+from rich.text import Text
+
+import khamyang
+from khamyang.phonology.tones import ToneSystem, TONES
+from khamyang.grammar.naming import list_birth_names, generate_full_name, KHAMYANG_CLANS
+from khamyang.grammar.classifiers import ClassifierEngine
+from khamyang.corpus.igt import InterlinearGloss
+
+console = Console()
+
+
+@click.group()
+@click.version_option(version=khamyang.__version__, prog_name="khamyang")
+def cli():
+    """Tai Khamyang (ksu) Language Revitalization & Linguistic Toolkit."""
+    pass
+
+
+@cli.command("lookup")
+@click.argument("term")
+def lookup_cmd(term: str):
+    """Search for a word in Tai Khamyang (by Roman, Lik Tai, Assamese, or English)."""
+    d = khamyang.get_dictionary()
+    results = d.lookup(term)
+
+    if not results:
+        console.print(f"[bold red]No entries found for:[/bold red] '{term}'")
+        return
+
+    for w in results[:5]:
+        tone_obj = TONES.get(w.tone)
+        tone_str = f"Tone {w.tone} ({tone_obj.name if tone_obj else ''}) [chao: {tone_obj.pitch_chao if tone_obj else ''}]"
+
+        panel_content = Text()
+        panel_content.append(f"Lik Tai:     ", style="bold cyan")
+        panel_content.append(f"{w.lik_tai}\n", style="bold yellow")
+        panel_content.append(f"Romanized:   ", style="bold cyan")
+        panel_content.append(f"{w.roman}\n", style="bold green")
+        panel_content.append(f"Assamese:    ", style="bold cyan")
+        panel_content.append(f"{w.assamese}\n", style="bold magenta")
+        panel_content.append(f"IPA:         ", style="bold cyan")
+        panel_content.append(f"{w.ipa}\n", style="italic")
+        panel_content.append(f"Part of Speech: ", style="bold cyan")
+        panel_content.append(f"{w.pos}\n")
+        panel_content.append(f"Tone:        ", style="bold cyan")
+        panel_content.append(f"{tone_str}\n", style="bold blue")
+        panel_content.append(f"English:     ", style="bold cyan")
+        panel_content.append(f"{w.gloss_en}\n", style="bold white")
+        panel_content.append(f"Assamese:    ", style="bold cyan")
+        panel_content.append(f"{w.gloss_as}\n", style="bold white")
+        panel_content.append(f"Category:    ", style="bold cyan")
+        panel_content.append(f"{w.category}\n")
+
+        if w.cognates:
+            cogs = ", ".join(f"{k}: {v}" for k, v in w.cognates.items())
+            panel_content.append(f"Cognates:    ", style="bold cyan")
+            panel_content.append(f"{cogs}\n", style="dim")
+
+        console.print(Panel(panel_content, title=f"[bold]Tai Khamyang: {w.roman}[/bold]", border_style="cyan"))
+
+
+@cli.command("search")
+@click.argument("query")
+@click.option("--category", "-c", default=None, help="Filter by category (e.g. nature, body, food, kinship)")
+@click.option("--tone", "-t", default=None, type=int, help="Filter by tone (1 to 6)")
+@click.option("--limit", "-n", default=20, help="Max number of results")
+def search_cmd(query: str, category: str, tone: int, limit: int):
+    """Full-text search across dictionary meanings and transcriptions."""
+    d = khamyang.get_dictionary()
+    results = d.search(query, category=category, tone=tone, limit=limit)
+
+    if not results:
+        console.print(f"[yellow]No matches found for query:[/yellow] '{query}'")
+        return
+
+    table = Table(title=f"Khamyang Search Results: '{query}' ({len(results)} found)")
+    table.add_column("Lik Tai", style="yellow")
+    table.add_column("Roman", style="bold green")
+    table.add_column("Assamese", style="magenta")
+    table.add_column("Tone", style="cyan")
+    table.add_column("IPA", style="dim")
+    table.add_column("POS", style="italic")
+    table.add_column("English", style="bold white")
+    table.add_column("Assamese Gloss", style="white")
+
+    for w in results:
+        table.add_row(
+            w.lik_tai,
+            w.roman,
+            w.assamese,
+            str(w.tone),
+            w.ipa,
+            w.pos,
+            w.gloss_en,
+            w.gloss_as,
+        )
+
+    console.print(table)
+
+
+@cli.command("transliterate")
+@click.argument("text")
+@click.option("--to", "target", default="liktai", type=click.Choice(["liktai", "assamese", "roman", "ipa"], case_sensitive=False))
+@click.option("--from", "source", default="roman", type=click.Choice(["roman", "liktai", "assamese"], case_sensitive=False))
+def transliterate_cmd(text: str, target: str, source: str):
+    """Convert text between Romanization, Lik Tai, Assamese, and IPA."""
+    out = khamyang.transliterate(text, source_script=source, target_script=target)
+    console.print(f"[bold cyan]Input ({source}):[/bold cyan]  {text}")
+    console.print(f"[bold yellow]Output ({target}):[/bold yellow] {out}")
+
+
+@cli.command("tone")
+@click.argument("tone_or_syllable")
+def tone_cmd(tone_or_syllable: str):
+    """Explain one of the 6 tones or analyze a syllable's pitch."""
+    if tone_or_syllable.isdigit():
+        t_num = int(tone_or_syllable)
+    else:
+        t_num = ToneSystem.extract_tone(tone_or_syllable) or 1
+
+    t_info = ToneSystem.explain_tone(t_num)
+    p = Text()
+    p.append(f"Tone Number:     ", style="bold")
+    p.append(f"{t_info['number']}\n", style="bold yellow")
+    p.append(f"Linguistic Name: ", style="bold")
+    p.append(f"{t_info['name']}\n", style="bold green")
+    p.append(f"Chao Contour:    ", style="bold")
+    p.append(f"{t_info['pitch_contour']}\n", style="bold cyan")
+    p.append(f"IPA Symbol:      ", style="bold")
+    p.append(f"{t_info['ipa']}\n", style="bold magenta")
+    p.append(f"Creaky Voice:    ", style="bold")
+    p.append(f"{t_info['creaky_voice']}\n")
+    p.append(f"Glottal Stop:    ", style="bold")
+    p.append(f"{t_info['glottal_stop']}\n")
+    p.append(f"Gedney Box:      ", style="bold")
+    p.append(f"{t_info['gedney_origin']}\n", style="dim")
+    p.append(f"Description:     ", style="bold")
+    p.append(f"{t_info['description']}\n")
+
+    console.print(Panel(p, title=f"Tone {t_num} Analysis", border_style="blue"))
+
+
+@cli.command("phrase")
+@click.option("--category", "-c", default=None, help="Category (fieldwork, greeting, daily, food, identity, culture)")
+@click.option("--search", "-s", default=None, help="Search text in phrases")
+def phrase_cmd(category: str, search: str):
+    """Browse the conversational phrasebook and fieldwork elicitation sentences."""
+    pb = khamyang.get_phrasebook()
+    if search:
+        phrases = pb.search(search)
+    elif category:
+        phrases = pb.get_by_category(category)
+    else:
+        phrases = pb.get_all()
+
+    table = Table(title=f"Khamyang Phrasebook ({len(phrases)} phrases)")
+    table.add_column("Lik Tai", style="yellow")
+    table.add_column("Roman", style="bold green")
+    table.add_column("Assamese", style="magenta")
+    table.add_column("English Meaning", style="bold white")
+    table.add_column("Assamese Meaning", style="cyan")
+
+    for p in phrases[:25]:
+        table.add_row(
+            p.lik_tai,
+            p.roman,
+            p.assamese,
+            p.english,
+            p.assamese_trans,
+        )
+
+    console.print(table)
+
+
+@cli.command("num")
+@click.argument("number", type=int)
+@click.option("--script", default="roman", type=click.Choice(["roman", "liktai", "assamese"]))
+def num_cmd(number: int, script: str):
+    """Convert an integer (0 to 1,000,000) into Tai Khamyang words."""
+    result = khamyang.num_to_khamyang(number, script=script)
+    console.print(f"[bold cyan]Number {number}:[/bold cyan] [bold yellow]{result}[/bold yellow]")
+
+
+@cli.command("name")
+@click.option("--gender", "-g", default="m", type=click.Choice(["m", "f", "male", "female"]))
+@click.option("--order", "-o", default=1, type=int, help="Birth order (1 to 8)")
+@click.option("--personal", "-p", default="", help="Optional personal name")
+@click.option("--clan", default="Thomung", help="Clan surname (Thomung, Chowlik, Chaohai, Pangyok, Wailong)")
+def name_cmd(gender: str, order: int, personal: str, clan: str):
+    """Generate or look up traditional Tai Khamyang birth-order names."""
+    full = generate_full_name(order, gender, personal_name=personal, clan=clan)
+    p = Text()
+    p.append(f"Full Name:        ", style="bold")
+    p.append(f"{full['full_roman']}\n", style="bold yellow")
+    p.append(f"Birth Order Name: ", style="bold")
+    p.append(f"{full['birth_order_name']}\n", style="bold green")
+    p.append(f"Clan Surname:     ", style="bold")
+    p.append(f"{full['clan']}\n", style="bold cyan")
+    p.append(f"Significance:     ", style="bold")
+    p.append(f"{full['meaning']}\n", style="white")
+
+    console.print(Panel(p, title=f"Khamyang Birth-Order Name ({gender.upper()} #{order})", border_style="green"))
+
+
+@cli.command("stats")
+def stats_cmd():
+    """Display comprehensive linguistic metrics of the Khamyang language library."""
+    d = khamyang.get_dictionary()
+    st = d.statistics()
+
+    table = Table(title="Tai Khamyang Linguistic Database Metrics")
+    table.add_column("Metric", style="bold cyan")
+    table.add_column("Value", style="bold yellow")
+
+    table.add_row("Total Lexical Entries", str(st["total_words"]))
+    table.add_row("Total Categories", str(st["total_categories"]))
+    for t_num, count in st["tones_distribution"].items():
+        table.add_row(f"  • Tone {t_num} words", str(count))
+
+    console.print(table)
+
+
+@cli.command("export")
+@click.option("--format", "-f", default="csv", type=click.Choice(["csv", "anki", "html"]))
+@click.option("--output", "-o", required=True, help="Output destination file path")
+def export_cmd(format: str, output: str):
+    """Export dictionary to CSV, Anki flashcard TSV, or interactive HTML."""
+    from khamyang.export.exporter import export_to_csv, export_to_anki_tsv, export_to_html
+    if format == "csv":
+        export_to_csv(output)
+    elif format == "anki":
+        export_to_anki_tsv(output)
+    elif format == "html":
+        export_to_html(output)
+    console.print(f"[bold green]Successfully exported dictionary ({format}) to:[/bold green] {output}")
+
+
+@cli.command("web")
+@click.option("--port", "-p", default=8000, help="Web server port (default: 8000)")
+@click.option("--host", "-h", default="127.0.0.1", help="Host address (default: 127.0.0.1)")
+def web_cmd(port: int, host: str):
+    """Start the interactive Tai Khamyang web revitalization interface."""
+    from khamyang.web.server import run_server
+    console.print(f"[bold green]Starting Tai Khamyang Web Platform at[/bold green] [bold cyan]http://{host}:{port}[/bold cyan]")
+    run_server(host=host, port=port)
+
+
+@cli.command("song")
+@click.argument("action", default="list", type=click.Choice(["list", "show", "search"]))
+@click.argument("query", required=False, default="")
+def song_cmd(action: str, query: str):
+    """Browse, view lyrics, and search authentic Tai Khamyang traditional songs."""
+    from khamyang.corpus.songs import SongEngine
+
+    if action == "list":
+        songs = SongEngine.all_songs()
+        table = Table(title="Tai Khamyang Traditional Songs & Ballads (Fɯn)")
+        table.add_column("ID", style="bold cyan")
+        table.add_column("Title (Khamyang)", style="bold yellow")
+        table.add_column("English Title", style="bold green")
+        table.add_column("Genre", style="magenta")
+        table.add_column("Informant / Origin", style="white")
+
+        for s in songs:
+            table.add_row(s["id"], s["title_khamyang"], s["title_english"], s["genre"], s["informant"])
+        console.print(table)
+        console.print("\n[italic dim]Use 'khamyang song show <id>' to read complete lyrics, glosses, and cultural context.[/italic dim]")
+
+    elif action == "show":
+        if not query:
+            console.print("[bold red]Please specify a song ID, e.g.:[/bold red] 'khamyang song show song_001'")
+            return
+        s = SongEngine.get_song(query)
+        if not s:
+            console.print(f"[bold red]Song not found:[/bold red] '{query}'")
+            return
+        text = SongEngine.format_song_text(s)
+        console.print(Panel(text, title=f"🎵 {s['title_khamyang']} ({s['title_english']})", border_style="yellow"))
+
+    elif action == "search":
+        if not query:
+            console.print("[bold red]Please provide a search term.[/bold red]")
+            return
+        res = SongEngine.search(query)
+        if not res:
+            console.print(f"[bold red]No songs found matching:[/bold red] '{query}'")
+            return
+        for s in res:
+            console.print(f"[bold yellow]{s['id']}[/bold yellow] - [bold cyan]{s['title_khamyang']}[/bold cyan] ({s['title_english']}): {s['description']}")
+
+
+@cli.command("kinship")
+@click.argument("action", default="resolve", type=click.Choice(["resolve", "search", "generation", "clans"]))
+@click.argument("query", required=False, default="")
+def kinship_cmd(action: str, query: str):
+    """Solve and inspect Tai Khamyang kinship relations, terms, and clan lineages."""
+    from khamyang.grammar.kinship import KinshipEngine
+
+    if action == "resolve":
+        if not query:
+            console.print("[bold cyan]Common codes:[/bold cyan] Fa (father), Mo (mother), FaFa (paternal grandfather), MoMo (maternal grandmother), FaElBr (elder paternal uncle), YoBr (younger brother), So (son), DaHu (son-in-law)")
+            query = "FaElBr"
+        res = KinshipEngine.resolve(query)
+        if not res:
+            console.print(f"[bold red]Could not resolve code:[/bold red] '{query}'")
+            return
+        explanation = KinshipEngine.explain_relationship(query)
+        console.print(Panel(explanation, title=f"👨‍👩‍👧‍👦 Kinship Term: {res['khamyang_roman']}", border_style="cyan"))
+
+    elif action == "search":
+        if not query:
+            console.print("[bold red]Please provide a search term (e.g. 'uncle', 'grandmother', 'lung1').[/bold red]")
+            return
+        matches = KinshipEngine.lookup(query)
+        if not matches:
+            console.print(f"[bold red]No kinship terms matching:[/bold red] '{query}'")
+            return
+        table = Table(title=f"Kinship Search Results for '{query}'")
+        table.add_column("Roman", style="bold cyan")
+        table.add_column("Lik Tai", style="yellow")
+        table.add_column("Assamese", style="magenta")
+        table.add_column("English", style="green")
+        table.add_column("Generation", style="blue")
+        for m in matches:
+            table.add_row(m["khamyang_roman"], m["lik_tai"], m["assamese_script"], m["english"], str(m["generation"]))
+        console.print(table)
+
+    elif action == "generation":
+        gen = int(query) if query.lstrip("-").isdigit() else 1
+        terms = KinshipEngine.list_by_generation(gen)
+        table = Table(title=f"Generation {gen} Relatives ({'Ancestors' if gen > 0 else 'Descendants' if gen < 0 else 'Ego Generation'})")
+        table.add_column("Roman", style="bold cyan")
+        table.add_column("Lik Tai", style="yellow")
+        table.add_column("English", style="green")
+        table.add_column("Assamese", style="magenta")
+        table.add_column("Relation Codes", style="dim")
+        for t in terms:
+            table.add_row(t["khamyang_roman"], t["lik_tai"], t["english"], t["assamese"], ", ".join(t.get("relation_codes", [])))
+        console.print(table)
+
+    elif action == "clans":
+        clans = KinshipEngine.list_clans()
+        table = Table(title="Tai Khamyang Historical Clans (Khɯa1)")
+        table.add_column("Clan Name", style="bold yellow")
+        table.add_column("Lik Tai", style="bold cyan")
+        table.add_column("Meaning", style="bold green")
+        table.add_column("Traditional Hereditary Role", style="white")
+        for c in clans:
+            table.add_row(c["name_tai"], c["lik_tai"], c["meaning"], c["role"])
+        console.print(table)
+
+
+@cli.command("biblio")
+@click.argument("action", default="list", type=click.Choice(["list", "search", "bibtex", "markdown"]))
+@click.argument("query", required=False, default="")
+@click.option("--output", "-o", default="", help="Optional output file destination")
+def biblio_cmd(action: str, query: str, output: str):
+    """Browse scholarly literature, books, articles, and export BibTeX citations."""
+    from khamyang.scraper.downloader import BibliographyManager
+
+    if action == "list":
+        entries = BibliographyManager.all_entries()
+        table = Table(title="Tai Khamyang Scholarly Bibliography & Resource Archive")
+        table.add_column("ID", style="bold cyan")
+        table.add_column("Year", style="bold yellow")
+        table.add_column("Type", style="magenta")
+        table.add_column("Author(s)", style="green")
+        table.add_column("Title", style="white")
+
+        for e in entries:
+            authors = ", ".join(e.get("authors", []))
+            table.add_row(e["id"], str(e.get("year", "")), e.get("entry_type", ""), authors[:28], e["title"][:48])
+        console.print(table)
+
+    elif action == "search":
+        if not query:
+            console.print("[bold red]Please enter search term (e.g. 'Morey', 'songs', 'tones', 'Nath').[/bold red]")
+            return
+        matches = BibliographyManager.search(query)
+        if not matches:
+            console.print(f"[bold red]No entries found matching:[/bold red] '{query}'")
+            return
+        for m in matches:
+            apa = BibliographyManager.format_apa(m)
+            console.print(f"• [bold cyan]{m['id']}[/bold cyan] ({m['entry_type']}):\n  {apa}\n  [dim]{m.get('description', '')}[/dim]\n")
+
+    elif action == "bibtex":
+        content = BibliographyManager.export_all_bibtex()
+        if output:
+            with open(output, "w", encoding="utf-8") as f:
+                f.write(content)
+            console.print(f"[bold green]BibTeX citations successfully saved to:[/bold green] {output}")
+        else:
+            console.print(content)
+
+    elif action == "markdown":
+        out = output or "BIBLIOGRAPHY.md"
+        BibliographyManager.save_markdown_file(out)
+        console.print(f"[bold green]Markdown bibliography saved to:[/bold green] {out}")
+
+
+if __name__ == "__main__":
+    cli()
+

khamyang/core/__init__.py

@@ -0,0 +1,19 @@
+"""Core module initialization."""
+
+from khamyang.core.models import (
+    Word,
+    Phrase,
+    ExampleSentence,
+    InterlinearUnit,
+    FolkText,
+    GlossUnit,
+)
+
+__all__ = [
+    "Word",
+    "Phrase",
+    "ExampleSentence",
+    "InterlinearUnit",
+    "FolkText",
+    "GlossUnit",
+]

khamyang/core/models.py

@@ -0,0 +1,130 @@
+"""Core data models for Tai Khamyang language entities."""
+
+from dataclasses import dataclass, field, asdict
+from typing import List, Dict, Optional, Any
+
+
+@dataclass
+class ExampleSentence:
+    """An example sentence demonstrating word usage."""
+    khamyang_roman: str
+    lik_tai: str = ""
+    assamese_script: str = ""
+    english: str = ""
+    assamese_meaning: str = ""
+    literal_gloss: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class Word:
+    """Lexical item in Tai Khamyang."""
+    id: str
+    roman: str
+    gloss_en: str
+    pos: str
+    tone: int
+    lik_tai: str = ""
+    assamese: str = ""
+    ipa: str = ""
+    definition_en: str = ""
+    gloss_as: str = ""
+    definition_as: str = ""
+    category: str = "general"
+    gedney_box: str = ""
+    cognates: Dict[str, str] = field(default_factory=dict)
+    examples: List[ExampleSentence] = field(default_factory=list)
+    notes: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        res = asdict(self)
+        res["examples"] = [ex.to_dict() if isinstance(ex, ExampleSentence) else ex for ex in self.examples]
+        return res
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Word":
+        examples = []
+        for ex in data.get("examples", []):
+            if isinstance(ex, dict):
+                examples.append(ExampleSentence(**ex))
+            elif isinstance(ex, ExampleSentence):
+                examples.append(ex)
+        data_copy = dict(data)
+        data_copy["examples"] = examples
+        return cls(**data_copy)
+
+
+@dataclass
+class Phrase:
+    """Conversational phrase or fieldwork elicitation expression."""
+    id: str
+    roman: str
+    english: str
+    category: str
+    lik_tai: str = ""
+    assamese: str = ""
+    ipa: str = ""
+    assamese_trans: str = ""
+    literal: str = ""
+    context: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Phrase":
+        return cls(**data)
+
+
+@dataclass
+class GlossUnit:
+    """Morpheme and its linguistic gloss."""
+    morpheme: str
+    gloss: str
+
+
+@dataclass
+class InterlinearUnit:
+    """A sentence with interlinear glossing for linguistic research."""
+    id: str
+    text_roman: str
+    lik_tai: str
+    assamese_script: str
+    morphemes: List[str]
+    glosses: List[str]
+    free_translation_en: str
+    free_translation_as: str
+    speaker: str = "Traditional / Elder"
+    location: str = "Powaimukh, Assam"
+    audio_ref: str = ""
+    notes: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class FolkText:
+    """A cultural narrative, folktale, or chant in Khamyang."""
+    id: str
+    title_khamyang: str
+    title_english: str
+    genre: str  # folktale, migration_history, buddhist_chant, oral_history
+    informant: str
+    village: str
+    sentences: List[InterlinearUnit] = field(default_factory=list)
+    description: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "id": self.id,
+            "title_khamyang": self.title_khamyang,
+            "title_english": self.title_english,
+            "genre": self.genre,
+            "informant": self.informant,
+            "village": self.village,
+            "description": self.description,
+            "sentences": [s.to_dict() for s in self.sentences],
+        }

khamyang/corpora/ai/instruction_dataset.jsonl

@@ -0,0 +1,5 @@
+{"id": "ai_inst_001", "task_type": "translation", "source_type": "human_verified", "data_level": "level_1_verified", "instruction": "Translate the following Tai Khamyang sentence into English and provide the grammatical breakdown.", "input": "pu5 yaa3 haw1 khao5 maa1 thaang1 doi1 pat4 kai1", "output": "Translation: 'Our ancestors crossed over and came along the path of the Patkai mountains.'\nMorphemes: pu5-yaa3 (ancestor/grandparents) haw1 (1PL/our) khao5 (3PL) maa1 (come) thaang1 (path/way) doi1 (mountain) pat4-kai1 (Patkai). Lik Tai: ပူႈယႃႈႁဝ်းၶဝ်မႃးထၢင်ႇလွႆပႅတ်ႇၵၢႆး."}
+{"id": "ai_inst_002", "task_type": "kinship_resolution", "source_type": "human_verified", "data_level": "level_1_verified", "instruction": "Identify the Tai Khamyang kinship term for a father's elder brother and explain the cultural address etiquette.", "input": "Relationship: Father's Elder Brother (FaElBr)", "output": "The Tai Khamyang term is 'lung1' (Lik Tai: လုင်, Assamese: লুং¹, IPA: /luŋ³³/ - Tone 1 Mid Level). He is addressed directly as 'Lung1'. In traditional Powaimukh village hierarchy, the lung1 holds the highest ceremonial authority in the patrilineage after the paternal grandfather."}
+{"id": "ai_inst_003", "task_type": "tone_identification", "source_type": "human_verified", "data_level": "level_1_verified", "instruction": "Analyze the tonal value, pitch contour, and Gedney tone box assignment for the Tai Khamyang word 'nam6' (water).", "input": "Word: nam6 (water / ၼမ်ႉ)", "output": "Word: nam6 (Lik Tai: ၼမ်ႉ, Assamese: নাম⁶).\nTone Number: Tone 6.\nPitch Contour: Level Rising (Chao pitch 35, IPA [nam˧˥]).\nGedney Tone Box: A2 (Proto-Tai voiced initial Proto-*n- with Proto-Tai tone *A).\nPhonetic note: In Tai Phake this cognate is pronounced with Tone 4 (nam4), showing regular Tai tone correspondence."}
+{"id": "ai_inst_004", "task_type": "cultural_qa", "source_type": "human_verified", "data_level": "level_1_verified", "instruction": "What is the historical meaning and geographical origin of the Tai Khamyang village name Powaimukh?", "input": "Topic: Etymology of Powaimukh", "output": "Powaimukh is the Assamese rendition of the authentic Tai Khamyang name 'Maan3 Paa1 Waai6' (Lik Tai: မၢၼ်ႈပႃႉဝၢႆး). It is composed of three morphemes: maan3 ('village') + paa1 ('estuary/river mouth') + waai6 ('rattan cane / Calamus rotang'). It literally means 'Village at the River-Mouth of Rattan', reflecting the abundance of wild rattan along the Buridihing river banks when the Nora ancestors settled there."}
+{"id": "ai_inst_005", "task_type": "classifier_syntax", "source_type": "human_verified", "data_level": "level_1_verified", "instruction": "Form a quantified nominal phrase in Tai Khamyang for 'two water buffaloes' following Southwestern Tai syntax.", "input": "Noun: kwaai1 (buffalo), Quantity: 2 (sɔŋ1)", "output": "In Tai Khamyang, numeral quantification strictly follows the Noun + Numeral + Classifier order: 'kwaai1 sɔŋ1 to1' (Lik Tai: ၵႂၢႆးသွင်တူဝ်). The classifier for animals and four-legged creatures is 'to1'."}