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

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:

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):

   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:

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

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

Example:

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

Response:

{
  "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.