README.md

metadata

title: Sinhala Chatbot
emoji: 🎙️
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false

Sinhala Chatbot

A voice-enabled Sinhala/English chatbot that uses speech recognition, translation, RAG, and text-to-speech.

Features

• Voice recording in Sinhala or English
• Speech-to-text using Whisper ASR (seniruk/whisper-small-si)
• Translation to English before querying RAG
• RAG from uploaded PDFs (FAISS + embeddings)
• AI fallback (Gemini or Hugging Face)
• Text-to-speech with Google TTS

Project Structure

chatbot-project-python/
  app/
    __init__.py
    main.py
    admin.py
    rag.py
    static/
      css/style.css
      js/script.js
    templates/
      index.html
      admin.html
  rag_data/
  .env
  .env.example
  requirements.txt
  README.md

Prerequisites

• Python 3.9+
• A modern browser (Chrome, Edge, Firefox)
• Microphone access
• Gemini API key (optional but recommended)
• Hugging Face API token (optional fallback)

Installation

1. Create a virtual environment

# Windows
python -m venv venv
venv\Scripts\activate

# macOS/Linux
python3 -m venv venv
source venv/bin/activate

2. Install dependencies

pip install -r requirements.txt

3. Configure environment variables

Copy the example environment file and add your API keys:

# Windows
copy .env.example .env

# macOS/Linux
cp .env.example .env

Edit .env and add:

GEMINI_API_KEY=your_gemini_key_here
HF_API_TOKEN=your_huggingface_token_here

If you do not provide a Gemini key, the app will fall back to the free Hugging Face API.

Running the Application

Start the main chatbot (port 8000)

# From the project root
python -m app.main
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Or using uvicorn directly:

swas

Start the admin panel (port 9000)

In a separate terminal:

python -m app.admin

Or using uvicorn directly:

uvicorn app.admin:admin_app --reload --host 0.0.0.0 --port 9000

Access the applications

• Chatbot UI: http://localhost:8000
• Admin panel (PDF upload): http://localhost:9000

Usage

1. Upload PDFs using the admin panel (port 9000)
2. Open the chatbot UI (port 8000)
3. Click the microphone and speak in Sinhala or English
4. The app transcribes, translates to English, then queries RAG
5. The response is shown in text and can be played via TTS

Troubleshooting

• If RAG answers are always from AI, upload at least one PDF and verify RAG status.
• If you see a missing API key error, check .env and restart the server.
• If model loading is slow, the first run downloads Whisper and embeddings.
• If PDFs already exist under rag_data/, the app now rebuilds/loads RAG at startup automatically.
• You can manually rebuild from all PDFs with POST /api/rag/rebuild.

Deploy on Hugging Face Spaces (Docker)

This project can be deployed with UI on Hugging Face Spaces using Docker.

1. Create a new Space

• Go to Hugging Face Spaces and create a new Space.
• Set SDK to Docker.
• Upload/push this project files to that Space repository.

2. Add Space secrets

In Space settings, add these secrets:

• GEMINI_API_KEY (optional)
• HF_API_TOKEN (optional fallback)

3. Build and run

The provided Dockerfile starts:

• Main UI at /
• Admin UI at /admin

When Space build completes, open:

• https://<your-space>.hf.space/
• https://<your-space>.hf.space/admin