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
