Metadata-Version: 2.4
Name: Tan_lang_chatbot
Version: 0.1.1
Summary: Tan_language local-language translation web chatbot.
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: fastapi==0.115.6
Requires-Dist: uvicorn[standard]==0.34.0
Requires-Dist: pydantic==2.10.4
Requires-Dist: python-dotenv==1.0.1
Requires-Dist: supabase==2.11.0

# Tan_lang_chatbot — FastAPI + Supabase + HTML/CSS/JS

Mtafsiri wa lugha za asili za Tanzania: **Sukuma · Kihaya (Ruhaya) · Kinyakyusa · Kiswahili**,
kwa **maandishi au sauti**, ukiwa na hali maalum ya **Daktari ↔ Mgonjwa**.

```
Tan_lang_chatbot/
├── backend/
│   ├── main.py               # FastAPI app (REST API + serves the frontend)
│   ├── load_to_supabase.py   # Seeds the Supabase table from the CSVs
│   ├── supabase_schema.sql   # Tables, grants, RLS policies, indexes
│   ├── requirements.txt
│   └── .env.example
├── model/
│   ├── __init__.py
│   └── translator.py         # Translation model (detect, exact, fuzzy, composed)
├── data/
│   ├── locallang_dataset_part1.csv   # dataset (part 1). Part 2 not included here
└── frontend/
    ├── index.html            # Conversation Mode UI
    ├── styles.css            # Clinical Teal theme
    └── app.js                # Speech-to-text, text-to-speech, API calls
```

## 1. Run it locally

```bash
cd LOCAL_LANGUAGE
python -m venv .venv
source .venv/bin/activate         # Windows: .venv\Scripts\activate
pip install -r backend/requirements.txt
cp backend/.env.example backend/.env  # optional — CSV mode works with no config
uvicorn backend.main:app --reload --port 8000
```

Open <http://localhost:8000>. The backend serves `frontend/index.html` automatically,
so no second server is needed. Use **Chrome or Edge** — speech recognition needs the
Web Speech API (Firefox does not support it; typing still works everywhere).

## Install as a package

The published web application installs its backend dependencies automatically:

```powershell
python -m pip install --upgrade Tan_lang_chatbot
tan-lang-chatbot
```

Then open <http://127.0.0.1:8000>. You do not need to install
`backend/requirements.txt` separately.

## 2. Optional: use Supabase instead of the CSVs

1. Create a project on supabase.com.
2. SQL Editor → paste and run `backend/supabase_schema.sql`.
3. In `.env` set:
   ```
   USE_SUPABASE=true
   SUPABASE_URL=https://xxxx.supabase.co
   SUPABASE_SERVICE_KEY=your-service-role-key
   ```
4. Seed the data (one-time, ~56k rows):
   ```bash
   python backend/load_to_supabase.py
   ```
5. Restart uvicorn. `GET /api/health` will report `"source": "supabase"`.

## 2b. Optional: enable online AI fallback

If a phrase is missing from the local CSV dataset, you can enable an external AI translation API as a fallback. This is useful for phrases that are not yet in the local lexicon, while still keeping the local dataset as the first source of truth.

Set these in `backend/.env`:

```env
AI_TRANSLATION_ENABLED=true
AI_API_URL=https://api.openai.com/v1
AI_API_KEY=your-api-key
AI_MODEL=gpt-4o-mini
AI_TEMPERATURE=0.1
```

This works with OpenAI-compatible endpoints too, including Azure OpenAI, DeepSeek, and OpenRouter. The app will only call the online API when the local dataset does not return a reliable translation.

## 3. API

| Method | Path | Body / Query | Purpose |
| --- | --- | --- | --- |
| GET | `/api/health` | — | Status, row count, data source |
| GET | `/api/languages` | — | Supported languages |
| POST | `/api/translate` | `{text, source_language, target_language}` | Main translation |
| POST | `/api/detect` | `{text}` | Language detection only |
| POST | `/api/compare` | `{text}` | Same word across all languages |
| GET | `/api/search` | `?q=maji&limit=20` | Dictionary lookup |
| POST | `/api/reload` | — | Reload dataset without restarting |

`source_language` may be `auto`, `Kiswahili`, `Sukuma`, `Ruhaya` (= Kihaya) or `Kinyakyusa`.

Example:

```bash
curl -X POST http://localhost:8000/api/translate \
  -H "Content-Type: application/json" \
  -d '{"text":"amezi","source_language":"auto","target_language":"Kiswahili"}'
```

Response:

```json
{
  "source_language": "Ruhaya",
  "target_language": "Kiswahili",
  "input": "amezi",
  "translation": "Maji",
  "category": "Health",
  "confidence": "high",
  "found_in_dataset": true,
  "match_type": "exact"
}
```

## 4. How the engine works

1. **Normalize** — lowercase, strip punctuation and accents.
2. **Detect** — token scoring against each language's vocabulary.
3. **Exact match** in the dataset → `confidence: high`.
4. **Fuzzy match** (trigram similarity ≥ 0.72) → `confidence: medium`, plus a
   “did you mean …” suggestion.
5. **Composed** — for sentences, translates word by word → `confidence: low`,
   marked for verification by a native speaker.
6. **No hallucination** — if nothing reliable is found the API says so instead of
   inventing a word.

## 5. Clinical conversation mode

- Choose the patient's language (Kihaya / Sukuma / Kinyakyusa) at the top.
- The patient's microphone translates **into Kiswahili** for the doctor.
- The doctor's microphone translates **back into the patient's language**.
- Each turn appears as a bubble with the original, the translation, a confidence
  badge, category and an example sentence when available.
- The voice toggle reads every translation aloud (`speechSynthesis`).
- The site language (Kiswahili / English) is switchable at top-right and remembered
  in `localStorage`.

## 6. Deploying

- Backend: any Python host (Render, Railway, Fly.io, a VPS with `uvicorn` behind nginx).
- Frontend: served by FastAPI by default; to host it separately set
  `window.LOCALLANG_API = "https://your-api-host"` before `app.js` loads and add that
  origin to `ALLOWED_ORIGINS` in `.env`.

> Medical disclaimer: translations marked *medium* or *low* confidence must be
> confirmed with a native speaker before being used in clinical decisions.
