README.md

---
title: 9jaLingo Chatbot
emoji: "🎙️"
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
pinned: false
---

# 9jaLingo Bot

A minimal RAG-based customer support assistant for the 9jaLingo Voice AI platform, built with FastAPI, Chroma, and Ollama.

The bot is designed to answer user questions about 9jaLingo products and workflows, including Text-to-Speech (TTS), Speech-to-Text (STT), Voice Cloning, Voice Over production, API usage, and support operations.

## Features

- Intelligent support chat for 9jaLingo platform questions
- Retrieval-augmented responses using Chroma vector database
- Local embeddings with Ollama
- Conversation memory by `thread_id`
- FastAPI backend with `/chat` and `/stream` endpoints

## Core Platform Coverage

The support bot FAQ and retrieval context includes answers for:

- Product overview and account onboarding
- TTS voices, languages, and usage patterns
- STT transcription workflows and output formats
- Voice cloning requirements and best practices
- Voice over workflows for creators and agencies
- API authentication, request patterns, and integration guidance
- Billing, quotas, and usage troubleshooting
- Support and escalation guidance

## Prerequisites

- Python 3.12+
- uv (recommended package manager)
- Ollama installed locally
- Ollama model pulled locally:
  - `embeddinggemma`
- API keys:
   - Optional API keys only if your chosen Ollama setup requires them

## Installation

1. Clone repo and enter bot folder:
   ```bash
   cd 9jalingo_bot
   ```

2. Install dependencies:
   ```bash
   uv sync
   ```

3. Configure environment variables in `.env`:
   ```env
   GOOGLE_API_KEY=your_google_api_key
   TAVILY_API_KEY=your_tavily_api_key
   OLLAMA_BASE_URL=http://localhost:11434
   OLLAMA_EMBEDDING_MODEL=embeddinggemma
   ```

4. Confirm Ollama models are available:
   ```bash
   ollama list
   ```

## Build Vector Database

From the project root (`9jalingo_bot`), run your vector DB bootstrap flow (if needed) so `data/faq.json` is indexed into Chroma.

Chroma persists locally under:

- `data/chroma_db/`

## Run API

```bash
uv run uvicorn main:app --reload --host 0.0.0.0 --port 8000
```

## API Endpoints

### Health

```http
GET /health
```

### Chat

```http
POST /chat
```

Request body:

```json
{
  "message": "How do I start with voice cloning on 9jaLingo?",
   "thread_id": "support-user-42"
}
```

### Stream

```http
POST /stream
```

## Project Structure

```text
9jalingo_bot/
├── data/
│   └── faq.json
├── src/
│   ├── chat_service.py
│   ├── chatbot.py
│   └── ingest.py
├── rag/
│   ├── data/
│   └── chroma_db/
├── main.py
├── pyproject.toml
└── Readme.md
```

## Notes

- Embeddings and chat generation are handled through Ollama-backed components.
- The API uses the FAQ file in `data/faq.json` as the RAG knowledge source.
- Memory is keyed by `thread_id` and persisted to `data/conversation_memory.jsonl` by default.
- For Hugging Face persistent disk, set `RAG_MEMORY_FILE=/data/conversation_memory.jsonl` in Space variables.

## Deploy to Hugging Face (Docker Space)

This project is Docker-based and currently installs Python dependencies from `requirements.txt` in the Dockerfile.

1. Clone your Space repo:

   ```bash
   git clone https://huggingface.co/spaces/9jaLingo/chatbot
   cd chatbot
   ```

   When prompted for password, use a Hugging Face access token with write permission.

2. Install Hugging Face CLI with uv:

   ```bash
   uv tool install hf
   ```

3. (Optional) Verify/download Space files:

   ```bash
   hf download 9jaLingo/chatbot --repo-type=space
   ```

4. Copy this app into the Space repo root (important files):

   - `Dockerfile`
   - `requirements.txt`
   - `main.py`
   - `src/`
   - `data/`
   - `.dockerignore`

5. Commit and push:

   ```bash
   git add Dockerfile requirements.txt main.py src data .dockerignore Readme.md
   git commit -m "Deploy 9jaLingo bot Docker Space"
   git push
   ```

6. Hugging Face Docker Space requirement:

   - The app must listen on port `7860` (already set in `Dockerfile`).