toto-lang 0.1.0__tar.gz

toto_lang-0.1.0/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: toto-lang
+Version: 0.1.0
+Summary: English-to-Toto translation engine with LLM-powered morphological analysis and Unicode 14.0 script support.
+Author: Toto Documentation Initiative
+License: MIT
+Project-URL: Homepage, https://github.com/toto-lang/toto-python
+Keywords: toto,translation,nlp,endangered-language,sino-tibetan,unicode
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: openai>=1.0
+Requires-Dist: flask>=3.0
+
+# toto
+
+A Python library for the Toto language — a critically endangered Sino-Tibetan language spoken in Totopara, Alipurduar, West Bengal, India.
+
+Provides LLM-powered English-to-Toto translation with morphemic analysis, Unicode 14.0 script transliteration, an offline dictionary of ~7,000 verified entries, and a local web interface.
+
+---
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+Or install dependencies separately:
+
+```bash
+pip install openai>=1.0 flask>=3.0
+```
+
+---
+
+## Setup
+
+The library needs an API key for the translation model. By default it uses [Ollama Cloud](https://ollama.com) with the `nemotron-3-super:cloud` model.
+
+### 1. Create a `.env` file
+
+Create a `.env` file **in your project root** (the directory where your script runs):
+
+```
+TOTO_API_KEY=your-api-key-here
+```
+
+The library also recognises these variable names (checked in order):
+
+| Variable | Source |
+|---|---|
+| `TOTO_API_KEY` | Recommended |
+| `TOTO_API` | Alternative |
+| `OLLAMA_API_KEY` | Ollama Cloud |
+| `HF_TOKEN` | HuggingFace |
+
+### 2. Or configure programmatically
+
+```python
+import toto
+
+toto.configure(api_key="your-key-here")
+# Or load from a specific .env file:
+toto.configure(env_path="/path/to/your/.env")
+# Or override the endpoint entirely:
+toto.configure(
+    api_key="your-key",
+    base_url="https://your-endpoint/v1",
+    model="your-model-name"
+)
+```
+
+### Optional: Custom endpoint
+
+Set these in your `.env` to override defaults:
+
+```
+TOTO_BASE_URL=https://your-endpoint/v1
+TOTO_MODEL=your-model-name
+```
+
+---
+
+## Usage
+
+### Translate
+
+```python
+from toto import totoagent
+
+result = totoagent.translate("They should not stay outside", lang="en")
+
+print(result)            # Romanized Toto (str)
+print(result.script)     # Native Toto script (Unicode 14.0)
+print(result.roman)      # Same as str(result)
+print(result.gloss)      # Interlinear morpheme breakdown
+print(result.notes)      # Grammatical synthesis explanation
+print(result.reasoning)  # Full chain-of-thought reasoning trace
+```
+
+### Serialise results
+
+```python
+result.to_dict()   # -> dict
+result.to_json()   # -> JSON string
+```
+
+### Unicode transliteration (no API key needed)
+
+```python
+from toto import roman_to_toto, toto_to_roman
+
+script = roman_to_toto("ka ti da-ro")
+print(script)  # 𞊔𞊭 𞊒𞊡 𞊓𞊭-𞊟𞊪
+
+roman = toto_to_roman(script)
+print(roman)   # ka ti da-ro
+```
+
+### Offline dictionary lookup (no API key needed)
+
+```python
+from toto import get_lexicon
+
+lex = get_lexicon()
+results = lex.lookup("water")
+for entry in results:
+    print(f"{entry['english']} -> {entry['toto']}")
+```
+
+### Web interface
+
+```python
+from toto import webagent
+
+webagent.run(port=5001)
+# Open http://127.0.0.1:5001 in your browser
+```
+
+### Access bundled documentation
+
+```python
+import toto
+
+docs = toto.get_documents()
+for path in docs:
+    print(path)
+# -> .../Guha_et_al_2025_Morphological_Analysis_Toto.pdf
+# -> .../Toby_Anderson_2017_Toto_English_Dictionary.pdf
+```
+
+### Create a dedicated agent instance
+
+```python
+from toto import TotoAgent
+
+agent = TotoAgent(
+    api_key="your-key",
+    base_url="https://ollama.com/v1",
+    model="nemotron-3-super:cloud"
+)
+result = agent.translate("Good morning")
+```
+
+---
+
+## Error Handling
+
+The library raises descriptive exceptions with actionable guidance:
+
+```python
+from toto import totoagent, MissingApiKeyError, ModelConnectionError, TranslationError
+
+try:
+    result = totoagent.translate("Hello")
+except MissingApiKeyError:
+    print("No API key found — check your .env file")
+except ModelConnectionError:
+    print("Cannot reach the translation API")
+except TranslationError as e:
+    print(f"Translation failed: {e}")
+    print(f"Raw content: {e.raw_content}")
+```
+
+---
+
+## Project Structure
+
+```
+toto-python/
+├── pyproject.toml
+├── setup.py
+├── README.md
+├── requirements.txt
+├── toto/
+│   ├── __init__.py          # Public API
+│   ├── config.py            # .env auto-discovery
+│   ├── exceptions.py        # Exception classes
+│   ├── agent.py             # TotoAgent + TranslationResult
+│   ├── unicode.py           # Script transliteration
+│   ├── lexicon.py           # Offline dictionary
+│   ├── web.py               # Web interface
+│   ├── resources/
+│   │   ├── data/            # Bundled JSONL lexicon
+│   │   ├── grammar/         # Grammar specification
+│   │   └── docs/            # Research PDFs
+│   ├── templates/           # HTML templates
+│   └── static/              # CSS & JS
+└── tests/
+    └── test_library.py
+```
+
+---
+
+## References
+
+- Toby Anderson, *Toto–English Dictionary*, Totopara Community, 2017.
+- Guha et al., *Morphological Analysis of Toto*, Adamas University, 2025.
+- Unicode 14.0 Toto Block (U+1E290 – U+1E2BF), September 2021.
+- Script created by Padma Shri Dhaniram Toto, 2015.
+
+---
+
+## License
+
+MIT

toto_lang-0.1.0/README.md

@@ -0,0 +1,213 @@
+# toto
+
+A Python library for the Toto language — a critically endangered Sino-Tibetan language spoken in Totopara, Alipurduar, West Bengal, India.
+
+Provides LLM-powered English-to-Toto translation with morphemic analysis, Unicode 14.0 script transliteration, an offline dictionary of ~7,000 verified entries, and a local web interface.
+
+---
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+Or install dependencies separately:
+
+```bash
+pip install openai>=1.0 flask>=3.0
+```
+
+---
+
+## Setup
+
+The library needs an API key for the translation model. By default it uses [Ollama Cloud](https://ollama.com) with the `nemotron-3-super:cloud` model.
+
+### 1. Create a `.env` file
+
+Create a `.env` file **in your project root** (the directory where your script runs):
+
+```
+TOTO_API_KEY=your-api-key-here
+```
+
+The library also recognises these variable names (checked in order):
+
+| Variable | Source |
+|---|---|
+| `TOTO_API_KEY` | Recommended |
+| `TOTO_API` | Alternative |
+| `OLLAMA_API_KEY` | Ollama Cloud |
+| `HF_TOKEN` | HuggingFace |
+
+### 2. Or configure programmatically
+
+```python
+import toto
+
+toto.configure(api_key="your-key-here")
+# Or load from a specific .env file:
+toto.configure(env_path="/path/to/your/.env")
+# Or override the endpoint entirely:
+toto.configure(
+    api_key="your-key",
+    base_url="https://your-endpoint/v1",
+    model="your-model-name"
+)
+```
+
+### Optional: Custom endpoint
+
+Set these in your `.env` to override defaults:
+
+```
+TOTO_BASE_URL=https://your-endpoint/v1
+TOTO_MODEL=your-model-name
+```
+
+---
+
+## Usage
+
+### Translate
+
+```python
+from toto import totoagent
+
+result = totoagent.translate("They should not stay outside", lang="en")
+
+print(result)            # Romanized Toto (str)
+print(result.script)     # Native Toto script (Unicode 14.0)
+print(result.roman)      # Same as str(result)
+print(result.gloss)      # Interlinear morpheme breakdown
+print(result.notes)      # Grammatical synthesis explanation
+print(result.reasoning)  # Full chain-of-thought reasoning trace
+```
+
+### Serialise results
+
+```python
+result.to_dict()   # -> dict
+result.to_json()   # -> JSON string
+```
+
+### Unicode transliteration (no API key needed)
+
+```python
+from toto import roman_to_toto, toto_to_roman
+
+script = roman_to_toto("ka ti da-ro")
+print(script)  # 𞊔𞊭 𞊒𞊡 𞊓𞊭-𞊟𞊪
+
+roman = toto_to_roman(script)
+print(roman)   # ka ti da-ro
+```
+
+### Offline dictionary lookup (no API key needed)
+
+```python
+from toto import get_lexicon
+
+lex = get_lexicon()
+results = lex.lookup("water")
+for entry in results:
+    print(f"{entry['english']} -> {entry['toto']}")
+```
+
+### Web interface
+
+```python
+from toto import webagent
+
+webagent.run(port=5001)
+# Open http://127.0.0.1:5001 in your browser
+```
+
+### Access bundled documentation
+
+```python
+import toto
+
+docs = toto.get_documents()
+for path in docs:
+    print(path)
+# -> .../Guha_et_al_2025_Morphological_Analysis_Toto.pdf
+# -> .../Toby_Anderson_2017_Toto_English_Dictionary.pdf
+```
+
+### Create a dedicated agent instance
+
+```python
+from toto import TotoAgent
+
+agent = TotoAgent(
+    api_key="your-key",
+    base_url="https://ollama.com/v1",
+    model="nemotron-3-super:cloud"
+)
+result = agent.translate("Good morning")
+```
+
+---
+
+## Error Handling
+
+The library raises descriptive exceptions with actionable guidance:
+
+```python
+from toto import totoagent, MissingApiKeyError, ModelConnectionError, TranslationError
+
+try:
+    result = totoagent.translate("Hello")
+except MissingApiKeyError:
+    print("No API key found — check your .env file")
+except ModelConnectionError:
+    print("Cannot reach the translation API")
+except TranslationError as e:
+    print(f"Translation failed: {e}")
+    print(f"Raw content: {e.raw_content}")
+```
+
+---
+
+## Project Structure
+
+```
+toto-python/
+├── pyproject.toml
+├── setup.py
+├── README.md
+├── requirements.txt
+├── toto/
+│   ├── __init__.py          # Public API
+│   ├── config.py            # .env auto-discovery
+│   ├── exceptions.py        # Exception classes
+│   ├── agent.py             # TotoAgent + TranslationResult
+│   ├── unicode.py           # Script transliteration
+│   ├── lexicon.py           # Offline dictionary
+│   ├── web.py               # Web interface
+│   ├── resources/
+│   │   ├── data/            # Bundled JSONL lexicon
+│   │   ├── grammar/         # Grammar specification
+│   │   └── docs/            # Research PDFs
+│   ├── templates/           # HTML templates
+│   └── static/              # CSS & JS
+└── tests/
+    └── test_library.py
+```
+
+---
+
+## References
+
+- Toby Anderson, *Toto–English Dictionary*, Totopara Community, 2017.
+- Guha et al., *Morphological Analysis of Toto*, Adamas University, 2025.
+- Unicode 14.0 Toto Block (U+1E290 – U+1E2BF), September 2021.
+- Script created by Padma Shri Dhaniram Toto, 2015.
+
+---
+
+## License
+
+MIT

toto_lang-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "toto-lang"
+version = "0.1.0"
+description = "English-to-Toto translation engine with LLM-powered morphological analysis and Unicode 14.0 script support."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Toto Documentation Initiative"},
+]
+keywords = ["toto", "translation", "nlp", "endangered-language", "sino-tibetan", "unicode"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Text Processing :: Linguistic",
+]
+dependencies = [
+    "openai>=1.0",
+    "flask>=3.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/toto-lang/toto-python"
+
+[tool.setuptools.packages.find]
+include = ["toto*"]
+
+[tool.setuptools.package-data]
+toto = [
+    "resources/data/*.jsonl",
+    "resources/grammar/*.md",
+    "resources/docs/*.pdf",
+    "templates/*.html",
+    "static/css/*.css",
+    "static/js/*.js",
+]

toto_lang-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

toto_lang-0.1.0/setup.py

@@ -0,0 +1,5 @@
+"""Backwards-compatible setup script. See pyproject.toml for metadata."""
+from setuptools import setup
+
+if __name__ == "__main__":
+    setup()