README.md

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

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

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

### 2. Install dependencies

```bash
pip install -r requirements.txt
```

### 3. Configure environment variables

Copy the example environment file and add your API keys:

```bash
# 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)

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

Or using uvicorn directly:

```bash
swas
```

### Start the admin panel (port 9000)

In a separate terminal:

```bash
python -m app.admin
```

Or using uvicorn directly:

```bash
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`