README.md

metadata

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:

   cd 9jalingo_bot
   

2. Install dependencies:

   uv sync
   

3. Configure environment variables in .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:

   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

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

API Endpoints

Health

GET /health

Chat

POST /chat

Request body:

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

Stream

POST /stream

Project Structure

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:

   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:

   uv tool install hf
   

3. (Optional) Verify/download Space files:

   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:

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