kumaoni 1.0.0__tar.gz

kumaoni-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Akshat Singh Bisht
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kumaoni-1.0.0/PKG-INFO

@@ -0,0 +1,463 @@
+Metadata-Version: 2.4
+Name: kumaoni
+Version: 1.0.0
+Summary: Kumaoni (कुमाऊँनी) Language Standard Library: 300,516+ Inflections, Voice AI, Speech Translation, and Himalayan Culture
+Home-page: https://github.com/infoakshatsinghbisht-eng/kumaoni-language-library
+Author: Akshat Singh Bisht
+Author-email: Akshat Singh Bisht <infoakshatsinghbisht@gmail.com>
+Maintainer: Akshat Singh Bisht
+Maintainer-email: Akshat Singh Bisht <infoakshatsinghbisht@gmail.com>
+Project-URL: Homepage, https://akshatsinghbisht.com/
+Project-URL: GitHub, https://github.com/infoakshatsinghbisht-eng/kumaoni-language-library
+Project-URL: LinkedIn, https://www.linkedin.com/in/akshat-singh-bisht-digital-performance-marketing-specialist/
+Project-URL: Amazon Author, https://www.amazon.com/stores/Akshat-Singh-Bisht/author/B0D5TYDT28
+Project-URL: ResearchGate, https://www.researchgate.net/profile/Akshat-Bisht-8
+Project-URL: Bug Tracker, https://github.com/infoakshatsinghbisht-eng/kumaoni-language-library/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: maintainer
+Dynamic: requires-python
+
+# Kumaoni (कुमाऊँनी) Language Library for Python
+
+[![Author & Creator](https://img.shields.io/badge/Author%20%26%20Creator-Akshat%20Singh%20Bisht-orange.svg?style=for-the-badge&logo=person)](https://akshatsinghbisht.com/)
+[![Website](https://img.shields.io/badge/Official%20Website-akshatsinghbisht.com-blue?style=for-the-badge&logo=googlechrome&logoColor=white)](https://akshatsinghbisht.com/)
+[![LinkedIn](https://img.shields.io/badge/LinkedIn-Connect-0A66C2?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/akshat-singh-bisht-digital-performance-marketing-specialist/)
+[![ResearchGate](https://img.shields.io/badge/ResearchGate-Publications-00CCBB?style=for-the-badge&logo=researchgate&logoColor=white)](https://www.researchgate.net/profile/Akshat-Bisht-8)
+[![Amazon Author](https://img.shields.io/badge/Amazon-Author%20Page-FF9900?style=for-the-badge&logo=amazon&logoColor=white)](https://www.amazon.com/stores/Akshat-Singh-Bisht/author/B0D5TYDT28?ref=sr_ntt_srch_lnk_1&qid=1789906571&sr=8-1&shoppingPortalEnabled=true)
+[![GitHub](https://img.shields.io/badge/GitHub-Profile-181717?style=for-the-badge&logo=github&logoColor=white)](https://github.com/infoakshatsinghbisht-eng)
+[![Lexicon Forms](https://img.shields.io/badge/Lexicon%20Forms-300%2C516%2B-success.svg?style=for-the-badge)](https://github.com/infoakshatsinghbisht-eng/kumaoni-language-library)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](LICENSE)
+
+A standard-library-style Python package for the **Kumaoni language** (कुमाऊँनी / Central Pahari). Designed to be as simple, fast, and comprehensive for Kumaoni as Python's built-in `math` library is for mathematics.
+
+This library empowers developers to build **web applications, mobile apps, educational tools, chatbots**, and perform **universal translation from any language of the world into Kumaoni**.
+
+> 📖 **Full Reference Manual**: Check out [DOCUMENTATION.md](file:///c:/Users/digit_lgfi273/OneDrive/Desktop/kumaoni%20language%20library/DOCUMENTATION.md) for the exhaustive guide, complete API references, grammatical rules, and application recipes.
+
+---
+
+## 🌟 Key Features
+
+1. **Universal Multi-Language Translator**
+   - Translate from **any world language** (English, French, Spanish, German, Japanese, Russian, Arabic, Hindi, Bengali, etc.) into Kumaoni.
+   - Multi-tiered architecture: Offline rule-based engine + Zero-key universal world language bridge + Neural AI adapter (Gemini / OpenAI).
+
+2. **Morphological Verb Conjugation Engine**
+   - Automatically conjugates regular and irregular Kumaoni verbs (e.g., `खाण` to eat, `जाण` to go, `करन` to do).
+   - Handles tenses (Present, Past, Future, Continuous), person (1st, 2nd, 3rd), gender (Masculine/Feminine), and honorific forms.
+   - Auxiliary substantive verb (`छ-` / to be) conjugation.
+
+3. **Kumaoni Numbers & Numerals**
+   - Converts any integer (0 to 1,000,000,000+) to Kumaoni words in Devanagari or Romanized script.
+   - Converts Kumaoni words back to numbers.
+   - Supports ordinals (1st `पैलो`, 2nd `दुसर`, 3rd `तेसर`...), customary fractions (`आधो`, `पाव`, `पौण`, `सवा`, `डेढ़`), and Devanagari numerals (`०१२३४५६७८९`).
+
+4. **100,000+ Words Morphological Paradigm Engine & Lemmatizer**
+   - Synthesizes and indexes **300,000+ unique authenticated Kumaoni word forms** across verbal paradigms (Present, Past, Future, Continuous, Imperatives, Causatives, Participles, Agentives), nominal declensions (Direct, Plural, Oblique, Case postpositions bound/spaced, Diminutives, Echo words), and adjectival agreements.
+   - Sub-millisecond `kumaoni.lemmatize()` and `kumaoni.analyze()` for inflected surface forms.
+   - Seamless dictionary lookups: querying inflected forms like `खान्छू`, `ग्यूँ`, `ईजा कणी`, or `घरबटि` resolves directly to their base lemmas and definitions.
+
+5. **Rich Lexicon & Dictionary (1,355+ Authenticated Base Lemmas)**
+   - Search across Kumaoni, English, and Hindi.
+   - Comprehensive vocabulary sourced from Grierson's *Linguistic Survey of India (Vol. IX, Part IV)*, Badri Datt Pande's *Kumaun ka Itihas (1937)*, Edwin T. Atkinson's *Himalayan Gazetteer*, Pt. Ganga Datt Upreti's *Hill Dialects of the Kumaun Division (1900)* & *Proverbs & Folklore of Kumaun (1894)*, Dr. Trilochan Pandey's *Kumaoni Bhasha Aur Sahitya (1977)* & *Kumaoni Lok-Sahitya ki Prushthbhoomi*, Dr. Gunanand Juyal's *Madhya Pahadi Bhasha (1967)*, and Hem Pant's *Ghughuti Basuti (2022)*.
+   - Categorized by historical governance & land tenure (`बूढ़ा`, `स्याणा`, `कामीन`, `थोकदार`, `थातवान`, `खायकर`, `सिरतान`, `गूठ`, `रौत`, `सिरती`, `बैकर`, `कटक`), shamanic & sacred rituals (`जागरिया`, `डांगरिया`, `थात`, `डौँर`, `हुड़का`, `आंछरी`, `मसाण`), alpine pastoralism & high valleys (`छानि`, `खर्क`, `बुग्याल`, `शौका`, `रंग-भंग`, `झूलाघाट`, `लाप्चा`, `हुणिया`, `पिरुल`, `लिसो`), seasonal dynamics & climate (`ह्यूंद`, `रूड़ि`, `चौमास`, `बशगाल`, `शरद`, `ब्वार`, `तुसार`, `कुइड़ो`), traditional cuisine, handicrafts & textiles (`थुलमा`, `चुटका`, `पंखी`, `दन`), and traditional measurements.
+   - Phonetic Latin transliteration and Devanagari script normalization.
+
+6. **Cultural Treasury (अखाण, आणा, लोकगीत, महागाथा & साहित्य)**
+   - **45+ Authentic Proverbs (*Akhaan*)**: Sourced from Pt. Ganga Datt Upreti's foundational compilation, Badri Datt Pande, Dr. Trilochan Pandey, and living hill tradition with literal, figurative, and parallel interpretations.
+   - **75+ Authentic Conversational & Folk Phrases**: Traditional greetings, blessings (`जीरये जागि रये`), lullabies, travel advice, and everyday idioms.
+   - **20+ Traditional Riddles (*Aan / Aana*)**: Engaging folk puzzles with hints and cultural context.
+   - **6 Monumental Folk Epics & Ballads**: *Malushahi-Rajula*, *Ajuva Bafaul ki Bhad*, *Golu Devta Jagar*, *Jiya Rani ki Gatha* (The Warrior Queen of Katyur), *Veer Balak Haru Singh Heet*, and *Amar Gopichand Yogi*.
+   - **6 Canonical Folk Poems & Songs**: *Bedu Pako Baro Masa*, *Malushahi Geet*, *Nyoli Lokgeet*, *Kalyug Varnan*, *Bajyaani Ka Dhur*, and *Ghughuti Basuti* (Traditional Lullaby & Nursery Rhymes).
+   - **15+ Canonical Authors & Scholars**: Profiles and canonical works for Badri Datt Pande (*Kumaun ka Itihas*), Gumani Pant, Gaurda, Krishna Pandey (*Kalyug Varnan*), Pt. Ganga Datt Upreti (*Proverbs & Folklore*, *Hill Dialects*), Dr. Trilochan Pandey (*Kumaoni Bhasha aur Uska Sahitya*), Dr. Gunanand Juyal (*Madhya Pahadi Bhasha*), Thakur Dewan Singh Bisht (*Deewani Vinod*), Chintamani Paliwal (*Kumaun ke Samrat*), Dr. Pramila Joshi (*Bajyaani Ka Dhur*), Girish Tiwari 'Girda', Heera Singh Rana, Kabootari Devi, Mohan Upreti, and Dr. Charu Chandra Pande.
+   - **Festivals & Almanac**: Traditional festivals (*Harela*, *Phool Dei*, *Ghughutiya*, *Olgia*, *Nanda Devi*, *Saatu-Aathu*, *Bhitauli*, *Khataduva*, *Bagwal*) and Kumaoni solar calendar months and seasons.
+
+7. **Interactive Developer Playground & CLI**
+   - Built-in command line interface (`kumaoni translate`, `kumaoni lookup`, `kumaoni number`).
+   - Modern glassmorphism web playground running locally with zero dependencies.
+
+---
+
+## 🚀 Installation
+
+Install via pip directly from PyPI:
+
+```bash
+pip install kumaoni
+```
+
+Or install from GitHub source in development mode:
+
+```bash
+git clone https://github.com/infoakshatsinghbisht-eng/kumaoni-language-library.git
+cd kumaoni-language-library
+pip install -e .
+```
+
+---
+
+## 📖 Quickstart Guide
+
+### 1. Universal Translation
+
+```python
+import kumaoni
+
+# Translate from English to Kumaoni
+result = kumaoni.translate("Where is the hospital?", source="en")
+print(result)            # Output: अस्पताल कतुक दूर छ?
+print(result.romanized)  # Output: Aspataal katuk door chha?
+
+# Translate from any world language (e.g., French, Spanish, Hindi)
+fr_result = kumaoni.translate("Comment allez-vous?", source="fr")
+print(fr_result)         # Output: कस छू तुम?
+
+hi_result = kumaoni.translate("मुझे पानी चाहिए।", source="hi")
+print(hi_result)         # Output: मैंकणी पाणि चाही।
+```
+
+### 2. Verb Conjugator
+
+```python
+import kumaoni
+from kumaoni.constants import Tense, Gender
+
+# Conjugate 'जाण' (to go) in the past tense for 1st person
+past_form = kumaoni.conjugate("जाण", tense=Tense.PAST, person=1, gender=Gender.MASCULINE)
+print(past_form)  # Output: 'ग्यूँ' (I went)
+
+# Conjugate 'खाण' (to eat) in the future tense
+future_form = kumaoni.conjugate("खाण", tense=Tense.FUTURE, person=1)
+print(future_form)  # Output: 'खालूँ' (I will eat)
+
+# Auxiliary verb 'to be' (छ-)
+is_form = kumaoni.conjugate_to_be(tense=Tense.PRESENT, person=3)
+print(is_form)  # Output: 'छ' (is)
+
+# Morphological Participles & Agent Nouns
+print(kumaoni.conjunctive_participle("खाण"))  # 'खाईबेर' (having eaten)
+print(kumaoni.agent_noun("गाण"))              # 'गाण्या' (singer)
+print(kumaoni.imperative("औण", polite=True))  # 'आया' (please come)
+
+# Causatives & Compound Verbs
+print(kumaoni.causative("करण", degree=1))     # 'करौण' (to make someone do)
+print(kumaoni.causative("खाण", degree=1))     # 'खिलाण' (to feed)
+print(kumaoni.compound_verb("खाण", "हाल्ण"))  # 'खाईहाल्ण' (to eat up completely)
+
+# Passive & Medio-Passive (Inability with -बटि)
+print(kumaoni.passive("करण"))                 # 'कर्यो जान्छ' (is done)
+print(kumaoni.medio_passive_inability("मैं", "हिंण")) # 'मैंबटि हिंड्यो नी जाँछ।'
+
+# SOV Sentence Builder & Conditionals
+sent = kumaoni.build_sentence(subject="राम", direct_object="भात", verb="खाण")
+print(sent)  # 'राम भात खान्छ।'
+
+cond = kumaoni.conditional("बरखा होली", "हम घर म रौला")
+print(cond)  # 'जै बरखा होली, त हम घर म रौला।'
+
+# Relative-Correlative Clauses (सम्बन्धवाचक रचना)
+print(kumaoni.relative_correlative("मेहनत करलो", "फल पालो", marker_type="who"))
+# Output: 'जो मेहनत करलो, सो फल पालो।'
+
+# Prohibitive Commands (निषेधात्मक आज्ञा - झनि)
+print(kumaoni.prohibitive("जाण", polite=True))  # 'झनि जाया' (Please do not go)
+print(kumaoni.prohibitive("रोण", polite=True))  # 'झनि रोया' (Please don't cry)
+
+# Modals: Ability, Obligation, and Desideratives
+print(kumaoni.modal_ability("मैं", "हिंण"))           # 'मैं हिंडि सकन्छू।' (I can walk)
+print(kumaoni.modal_obligation("तुम", "काम करण"))     # 'तुमकणी काम करण चाही।' (You should work)
+print(kumaoni.modal_obligation("मैं", "जाण", strong=True)) # 'मैंकणी जाण पडलो।' (I will have to go)
+print(kumaoni.modal_desiderative("मैं", "भात खाण"))  # 'मैं भात खाण चान्छू।' (I want to eat food)
+
+# Interrogative Questions (प्रश्नवाचक रचना)
+print(kumaoni.interrogative_sentence("कहाँ", subject="अस्पताल"))  # 'अस्पताल कहाँ छ?'
+print(kumaoni.interrogative_sentence("क्या", subject="तुमार नाम")) # 'तुमार नाम क्या छ?'
+```
+
+
+### 3. Numbers & Devanagari Numerals
+
+```python
+import kumaoni
+
+# Integer to Kumaoni words
+print(kumaoni.num_to_words(42))                     # 'बयालीस'
+print(kumaoni.num_to_words(108, script="latin"))     # 'ek sau aath'
+
+# Ordinals & fractions
+print(kumaoni.ordinal(1))                           # 'पैलो' (1st)
+print(kumaoni.ordinal(2))                           # 'दुसर' (2nd)
+print(kumaoni.fraction(1, 2))                       # 'आधो' (half)
+
+# Devanagari numerals
+print(kumaoni.to_devanagari_numerals(2026))         # '२०२६'
+print(kumaoni.from_devanagari_numerals("२०२६"))       # 2026
+
+# Words back to numbers
+print(kumaoni.words_to_num("बयालीस"))                 # 42
+```
+
+### 4. Dictionary & Lexicon Search
+
+```python
+import kumaoni
+
+# Exact lookup
+word = kumaoni.lookup("ईजा")
+print(f"{word.kumaoni} -> {word.english} ({word.hindi})")
+# Output: 'ईजा -> mother (माँ)'
+
+# Cross-language search
+results = kumaoni.search("water")
+for w in results:
+    print(f"{w.kumaoni} ({w.roman}): {w.english}")
+# Output: 'पाणि (paani): water'
+```
+
+### 5. Morphological Lemmatizer & Analyzer (200,000+ Words)
+
+```python
+import kumaoni
+
+# Check total synthesized and indexed full-form vocabulary
+print(kumaoni.total_word_forms())  # Output: 300,516+ words
+
+# Lemmatize inflected verb forms, case-marked nouns, or postpositions
+print(kumaoni.lemmatize("खान्छू"))    # 'खाण' (to eat)
+print(kumaoni.lemmatize("जाँला"))     # 'जाण' (to go)
+print(kumaoni.lemmatize("घरबटि"))     # 'घर' (house)
+print(kumaoni.lemmatize("ईजा कणी"))   # 'ईजा' (mother)
+
+# Deep morphological analysis (extracts tense, person, case, number, lemma)
+analyses = kumaoni.analyze("खान्छू")
+for a in analyses:
+    print(f"Lemma: {a.lemma}, POS: {a.pos}, Tense: {a.tense}, Person: {a.person}, Number: {a.number}")
+# Output: Lemma: खाण, POS: verb_finite, Tense: present, Person: 1, Number: sg
+
+# Seamless dictionary lookup on inflected words
+w = kumaoni.lookup("खान्छू")
+print(f"Resolved to: {w.kumaoni} -> {w.english}")  # Resolved to: खाण -> to eat
+```
+
+### 6. Script & Phonetics
+
+```python
+import kumaoni
+
+# Transliterate English phonetics to Devanagari
+print(kumaoni.transliterate("Jai Dev, dajyu kas chou?", to_script="devanagari"))
+# Output: 'जय देव, दाज्यू कस छौ?'
+
+# Transliterate Devanagari to Romanized
+print(kumaoni.transliterate("पैलाग भुली", to_script="latin"))
+# Output: 'pailag bhuli'
+```
+
+### 7. Cultural Heritage, Literature & Folklore
+
+```python
+import kumaoni
+
+# Access Folk Epics (Pauwada / Bhad)
+malushahi = kumaoni.literature.get_epic("malushahi")
+print(malushahi.title_kumaoni)        # 'राजुला मालूशाही'
+print(malushahi.synopsis)
+
+# Explore Traditional Valley Poetry (Nyoli / Jhora)
+bedu_pako = kumaoni.literature.poems()[0]
+print(bedu_pako.title_kumaoni)        # 'बेड़ू पाको बारह मासा'
+print(bedu_pako.verses_kumaoni[0])    # 'बेड़ू पाको बारह मासा, ओ नरण काफल पाको चैत, मेरी छैला!'
+
+# Canonical Kumaoni Authors & Poets (Gumani Pant, Gaurda, Dr. Charu Chandra Pande)
+gumani = kumaoni.literature.get_author("gumani_pant")
+print(f"{gumani.name_kumaoni} ({gumani.era}): {gumani.significance}")
+
+# Random proverb (Akhaan) & riddle (Aana)
+proverb = kumaoni.proverbs.random()
+print("Akhaan:", proverb["kumaoni"], "->", proverb["figurative_meaning"])
+
+riddle = kumaoni.riddles.random()
+print("Aana:", riddle["riddle"], "-> Answer:", riddle["answer_kumaoni"])
+
+# Traditional Kumaoni festival information
+harela = kumaoni.festivals.get("harela")
+print(harela.description)
+```
+
+---
+
+## 📋 Comprehensive API Function Reference
+
+All key functions are directly accessible via `import kumaoni`:
+
+| Category | Function / Property | Description |
+|---|---|---|
+| **Translation** | `kumaoni.translate(text, source='en', target='kumaoni')` | Translate from 100+ world languages into Kumaoni. |
+| **Voice & Speech** | `kumaoni.voice_translate(text, ...)` | Voice translation pipeline (text + IPA phonetic script + audio). |
+| | `kumaoni.voice.phrases()` | Get categorized authentic conversational phrases. |
+| **Dictionary & Search** | `kumaoni.lookup(word)` | Search base dictionary definitions (Kumaoni, Hindi, English). |
+| | `kumaoni.search(query)` | Multi-result search in vocabulary database. |
+| **Morphology (300k+ Forms)** | `kumaoni.lemmatize(word)` | Reduces inflected forms (`खान्छू`, `घरबटि`) to base dictionary lemma. |
+| | `kumaoni.analyze(word)` | Deep grammatical analysis (POS, tense, case, gender, person). |
+| | `kumaoni.total_word_forms()` | Count of indexed morphological forms (300,000+). |
+| **Verb Conjugation** | `kumaoni.conjugate(verb, tense, person, ...)` | Conjugates verbs across Present, Past, Future, Continuous. |
+| | `kumaoni.conjugate_to_be(tense, person, ...)`| Conjugates auxiliary substantive verb (`छ-` / to be). |
+| | `kumaoni.imperative(verb, honorific=...)` | Forms imperative commands (`खा`, `खाओ`, `खाइये`). |
+| | `kumaoni.causative(verb, degree=1)` | Forms 1st and 2nd degree causative verbs (`खवाण`, `खववाण`). |
+| | `kumaoni.passive(verb, tense=...)` | Forms passive voice constructions. |
+| | `kumaoni.conjunctive_participle(verb)` | Conjunctive participle 'having done' (`खाईकन`, `जाईकन`). |
+| | `kumaoni.agent_noun(verb)` | Agentive noun 'the one who does' (`खन्या`, `जन्या`). |
+| | `kumaoni.compound_verb(main, vector, ...)` | Aspectual compound verbs (`खा ल्हियो`). |
+| | `kumaoni.prohibitive(verb, honorific=...)` | Negative prohibitive commands (`झन् खा`). |
+| | `kumaoni.modal_ability(verb, subject=...)` | Modal ability 'can do' (`सकण`). |
+| | `kumaoni.modal_obligation(verb, subject=...)`| Modal obligation 'must / should do' (`पड़ण`). |
+| | `kumaoni.modal_desiderative(verb, ...)` | Modal desiderative 'wants to do' (`चाण`). |
+| **Grammar & Syntax** | `kumaoni.build_sentence(sub, verb, obj, ...)`| Generates grammatically aligned SOV sentences. |
+| | `kumaoni.conditional(cond, conseq)` | Conditional sentences (`अगर... तब...`). |
+| | `kumaoni.relative_correlative(rel, corr)` | Relative-correlative clauses (`जो... सो...`). |
+| | `kumaoni.interrogative_sentence(sub, ...)` | Question sentences (`कहाँ`, `कबे`, `क्योँ`, `को`). |
+| | `kumaoni.echo_word(word)` | Reduplicative echo words (`भात-व़ात`, `किताब-सिताब`). |
+| **Nouns & Declension** | `kumaoni.pluralize(noun, gender=...)` | Pluralizes nouns by declension class. |
+| | `kumaoni.decline_noun(noun, case, ...)` | Declines nouns into grammatical cases. |
+| | `kumaoni.to_oblique(noun, ...)` | Oblique stem for postpositions. |
+| | `kumaoni.attach_case(noun, case, ...)` | Attaches vibhakti case markers to noun. |
+| | `kumaoni.get_marker(case)` | Returns case marker postposition (`-ले`, `-कणी`, `-बटि`, `-म`). |
+| | `kumaoni.get_pronoun(person, case, ...)` | Resolves personal pronouns across cases. |
+| | `kumaoni.to_feminine(word)` / `to_masculine` | Converts gender forms of nouns/adjectives. |
+| | `kumaoni.make_diminutive(noun)` | Diminutive affection forms (`गाड़` ➔ `गड्यूल`). |
+| **Numbers & Fractions** | `kumaoni.num_to_words(number)` | Integer to Kumaoni words (`108` ➔ `'एक सौ आठ'`). |
+| | `kumaoni.words_to_num(words)` | Kumaoni number words to integer. |
+| | `kumaoni.to_devanagari_numerals(n)` | Converts number to Devanagari numerals (`२०२६`). |
+| | `kumaoni.from_devanagari_numerals(s)` | Devanagari numerals back to integer. |
+| | `kumaoni.ordinal(n)` | Ordinals (`पैलो`, `दुसर`, `तेसर`, `चौथ`). |
+| | `kumaoni.fraction(val)` | Fractions (`आधो`, `पाव`, `सवा`, `डेढ़`, `ढाई`). |
+| **Phonetics & Script** | `kumaoni.transliterate(text, to_script=...)`| Two-way Devanagari ↔ Latin/Roman transliteration. |
+| | `kumaoni.devanagari_to_latin(text)` | Transliterates Devanagari into Latin phonetic script. |
+| | `kumaoni.latin_to_devanagari(text)` | Converts Romanized Kumaoni input to Devanagari. |
+| | `kumaoni.normalize(text)` | Normalizes Devanagari diacritics and nuktas. |
+| | `kumaoni.detect_script(text)` | Detects `'devanagari'`, `'latin'`, or `'mixed'`. |
+| | `kumaoni.tokenize(text)` / `syllables(text)`| Tokenizes words and splits phonetic syllables. |
+| **Culture & Literature** | `kumaoni.proverbs.all()` / `.random()` | 45+ Proverbs (*Akhaan*) with literal & cultural meanings. |
+| | `kumaoni.riddles.all()` / `.random()` | 20+ Traditional Riddles (*Aana*) with hints & answers. |
+| | `kumaoni.phrases.all()` / `.random()` | 75+ Conversational phrases, idioms & blessings. |
+| | `kumaoni.festivals.list()` / `.get(name)` | Festivals (*Harela*, *Phool Dei*, *Ghughutiya*, *Nanda Devi*). |
+| | `kumaoni.literature.epics()` / `.get_epic(id)`| 6 Folk Epics (*Malushahi-Rajula*, *Jiya Rani*, *Golu Devta*). |
+| | `kumaoni.literature.poems()` | Canonical Kumaoni poems & folk songs. |
+| | `kumaoni.literature.authors()` / `.get_author(id)` | Biographies of 15+ canonical scholars & poets. |
+| | `kumaoni.get_months()` / `get_seasons()` | Kumaoni solar calendar months & 6 traditional seasons. |
+| | `kumaoni.get_current_season()` | Calculates active season for today's date. |
+
+For exhaustive explanations and parameter details, see [DOCUMENTATION.md](file:///c:/Users/digit_lgfi273/OneDrive/Desktop/kumaoni%20language%20library/DOCUMENTATION.md).
+
+---
+
+## 💻 Command-Line Interface (CLI)
+
+The library provides a CLI tool `kumaoni`:
+
+```bash
+# Translate text
+kumaoni translate "Where does this road go?" --source en
+
+# Dictionary lookup
+kumaoni lookup "काफल"
+kumaoni lookup "पिछौड़ा"
+
+# Number to words
+kumaoni number 108
+
+# Verb conjugation
+kumaoni conjugate "जाण" --tense past --person 1
+
+# Random proverb / riddle
+kumaoni proverb
+kumaoni riddle
+```
+
+---
+
+## 🖥️ Interactive Web Playground
+
+Launch the interactive local web playground to test translation and explore the language in a browser:
+
+```bash
+python -m kumaoni.web.app 8080
+```
+Open [http://localhost:8080](http://localhost:8080) in your browser.
+
+---
+
+## 📂 Project Architecture
+
+```
+kumaoni/
+├── __init__.py           # Unified top-level namespace (kumaoni.translate, literature, etc.)
+├── constants.py          # Dialects, grammatical constants, solar calendar
+├── phonetics.py          # Script transliteration, Devanagari normalizer
+├── grammar/
+│   ├── verbs.py          # Verb root extraction & conjugation engine
+│   ├── nouns.py          # Noun morphology, pluralization, case declensions
+│   ├── pronouns.py       # Pronoun tables across person, number, and case
+│   └── postpositions.py  # Karaka markers (-ले, -कणी, -बटि, -म, etc.)
+├── numbers/
+│   └── converter.py      # Integer to words, ordinals, fractions, numerals
+├── lexicon/
+│   ├── dictionary.py     # Fast search across Devanagari, English, and Hindi
+│   └── data/             # Curated JSON datasets (370+ words, phrases, Akhaan, Aana)
+├── translator/
+│   ├── engine.py         # Unified translation orchestrator
+│   ├── rule_based.py     # Rule-based linguistic transfer & dialogue patterns
+│   ├── pivot.py          # Universal multi-language bridge (Any Language -> Kumaoni)
+│   └── llm_adapter.py    # Native Gemini/OpenAI neural integration
+├── culture/
+│   ├── festivals.py      # Cultural documentation (Harela, Phooldei, etc.)
+│   ├── calendar.py       # Kumaoni solar months & seasons
+│   └── literature.py     # Folk Epics (Malushahi, Bafaul), Nyoli, Jhora, Authors
+├── cli.py                # Command-line interface
+└── web/                  # Interactive developer playground
+```
+
+---
+
+## 📚 Data Sources & Acknowledgments
+
+This library synthesizes datasets and oral cultural heritage from:
+- **eUttaranchal** (*Learn Kumaoni* linguistic lessons 1–3)
+- **SpeakKumaoni** & **PahadiLingo** (Himalayan vocabulary & phonetic guides)
+- **Kumauni Archives** & **Kumauni Culture** (Oral literature, e-books, e-magazines)
+- **Linguistic Research**: Works of Dr. D.D. Sharma (*Linguistic Geography of Kumaun Himalayas*), Dr. Charu Chandra Pande, G.A. Grierson (*LSI*), Saraswati Kohli (*Kumaoni Kahavatein*), Gumani Pant, and Gaurda.
+
+---
+
+## 📜 License
+
+MIT License &copy; 2026 Kumaoni Language Initiative. Open-source and free for all developers, linguists, and researchers.
+
+---
+
+## 👤 Author & Creator Profile
+
+* **Creator & Author**: **Akshat Singh Bisht**
+* **Official Website**: [https://akshatsinghbisht.com/](https://akshatsinghbisht.com/)
+* **Email**: [infoakshatsinghbisht@gmail.com](mailto:infoakshatsinghbisht@gmail.com)
+* **LinkedIn**: [Akshat Singh Bisht on LinkedIn](https://www.linkedin.com/in/akshat-singh-bisht-digital-performance-marketing-specialist/)
+* **Amazon Author Profile**: [Akshat Singh Bisht on Amazon](https://www.amazon.com/stores/Akshat-Singh-Bisht/author/B0D5TYDT28?ref=sr_ntt_srch_lnk_1&qid=1789906571&sr=8-1&shoppingPortalEnabled=true)
+* **ResearchGate**: [Akshat Bisht on ResearchGate](https://www.researchgate.net/profile/Akshat-Bisht-8)
+* **GitHub**: [@infoakshatsinghbisht-eng](https://github.com/infoakshatsinghbisht-eng)
+* **Kumaoni Repository**: [https://github.com/infoakshatsinghbisht-eng/kumaoni-language-library](https://github.com/infoakshatsinghbisht-eng/kumaoni-language-library)
+* **Garhwali Repository**: [https://github.com/infoakshatsinghbisht-eng/garhwali-language-library](https://github.com/infoakshatsinghbisht-eng/garhwali-language-library)
+* **Garhwali PyPI**: [https://pypi.org/project/garhwali/](https://pypi.org/project/garhwali/)
+
+---
+
+## 📄 License
+This project is licensed under the **MIT License** — dedicated to the computational preservation, linguistic research, and cultural advancement of the Himalayan languages of Uttarakhand.