Deploy 9jaLingo bot Docker Space

.dockerignore

@@ -0,0 +1,14 @@
+*.pyc
+*.pyo
+*.pyd
+.Python
+env
+venv
+.venv
+.env
+.git
+.gitignore
+.pytest_cache
+.coverage
+__pycache__
+data/chroma_db/

.gitignore

@@ -0,0 +1,51 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environment
+venv/
+env/
+ENV/
+
+# Environment Variables
+.env
+.env.local
+.env.*.local
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Logs
+*.log
+logs/
+chroma_operations.log
+
+# Operating System
+.DS_Store
+Thumbs.db
+
+# Project-specific
+test.ipynb
+.ipynb_checkpoints/
+data/chroma_db/

Dockerfile

@@ -0,0 +1,27 @@
+FROM python:3.12-slim
+
+# Hugging Face Spaces runs nicely with uid 1000
+RUN useradd -m -u 1000 user
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PATH="/home/user/.local/bin:$PATH"
+
+WORKDIR /app
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --chown=user requirements.txt /app/requirements.txt
+
+USER user
+RUN pip install --user --upgrade pip \
+    && pip install --user -r /app/requirements.txt
+
+COPY --chown=user . /app
+
+# Docker Spaces must listen on 7860
+EXPOSE 7860
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,11 +1,174 @@
----
-title: Chatbot
-emoji: 🌍
-colorFrom: purple
-colorTo: pink
-sdk: docker
-pinned: false
-short_description: A RAG-based customer support assistant for the 9jaLingoAI
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 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 kept in-process and keyed by `thread_id`.
+
+## 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`).

data/faq.json

@@ -0,0 +1,646 @@
+[
+  {
+    "question": "What is 9jaLingo platform?",
+    "answer": "9jaLingo is a voice AI platform for African language speech products, including Text-to-Speech (TTS), Speech-to-Text (STT), voice cloning, and voice-over workflows."
+  },
+  {
+    "question": "Who is 9jaLingo built for?",
+    "answer": "9jaLingo is built for developers, content creators, businesses, and teams that need realistic, localized voice experiences."
+  },
+  {
+    "question": "Which languages does 9jaLingo support?",
+    "answer": "9jaLingo supports voices across Hausa, Igbo, Yoruba, Nigerian Pidgin, and Nigerian English, with continued expansion."
+  },
+  {
+    "question": "Can I use 9jaLingo for production workloads?",
+    "answer": "Yes. 9jaLingo is designed for production use cases with API access, scalable workflows, and support options."
+  },
+  {
+    "question": "What core services are available on 9jaLingo?",
+    "answer": "Core services include Text-to-Speech, Speech-to-Text, voice cloning, and voice-over generation for media and product teams."
+  },
+  {
+    "question": "What is Text-to-Speech on 9jaLingo?",
+    "answer": "Text-to-Speech converts input text into natural-sounding speech using selected speakers, accents, and style settings."
+  },
+  {
+    "question": "Can I choose different speakers for TTS?",
+    "answer": "Yes. You can choose from many speakers and test which voice fits your brand story, app tone, or campaign style."
+  },
+  {
+    "question": "Can I generate Yoruba TTS audio?",
+    "answer": "Yes. You can generate Yoruba speech where supported by choosing a matching voice and submitting your text."
+  },
+  {
+    "question": "What audio formats does TTS support?",
+    "answer": "TTS output can be exported in WAV, PCM, MP3, FLAC, AAC, ALAC, and OGG, depending on endpoint and configuration."
+  },
+  {
+    "question": "Is TTS good for IVR and call prompts?",
+    "answer": "Yes. Many teams use 9jaLingo TTS for IVR prompts, virtual agents, onboarding flows, and customer help lines."
+  },
+  {
+    "question": "How do I optimize TTS output quality?",
+    "answer": "Use clean punctuation, shorter sentence blocks, language-appropriate text, and test multiple voices before final export."
+  },
+  {
+    "question": "Is there a TTS API for developers?",
+    "answer": "Yes. 9jaLingo provides API endpoints so developers can generate speech from text in automated pipelines."
+  },
+  {
+    "question": "Can I stream TTS audio in real time?",
+    "answer": "Streaming support depends on endpoint configuration and your plan, but low-latency responses are supported in many flows."
+  },
+  {
+    "question": "How do I authenticate TTS API requests?",
+    "answer": "Authenticate requests with your API key or token according to the platform docs, and keep credentials secure."
+  },
+  {
+    "question": "Can I batch-generate many TTS files?",
+    "answer": "Yes. You can queue batch text inputs and generate multiple files for campaigns, lessons, narration, and customer messaging."
+  },
+  {
+    "question": "Can TTS be integrated with microservices?",
+    "answer": "Yes. TTS can be integrated with microservices through standard HTTP API calls and background job handling."
+  },
+  {
+    "question": "What is best practice for TTS retries?",
+    "answer": "Use idempotent request design, retries with backoff, and request IDs so your app can recover without duplicate side effects."
+  },
+  {
+    "question": "What is Speech-to-Text on 9jaLingo?",
+    "answer": "Speech-to-Text converts spoken audio into written text for search, analytics, support, and workflow automation."
+  },
+  {
+    "question": "Can STT transcribe Igbo?",
+    "answer": "STT supports multiple local language scenarios. Select the closest language profile for best performance."
+  },
+  {
+    "question": "What file types are accepted for STT?",
+    "answer": "Common audio formats such as WAV, MP3, and M4A are generally supported, depending on endpoint settings."
+  },
+  {
+    "question": "Can STT handle long recordings?",
+    "answer": "Yes. Long recordings can be processed with chunking, async jobs, and post-merge strategies for reliability."
+  },
+  {
+    "question": "Can I use STT for call center recordings?",
+    "answer": "Yes. STT is commonly used to transcribe support calls and power QA, search, and customer insight analysis."
+  },
+  {
+    "question": "How do I improve STT transcription quality?",
+    "answer": "Use clear audio, reduce background noise, choose the correct language setting, and normalize volume before upload."
+  },
+  {
+    "question": "Can STT output timestamps?",
+    "answer": "Timestamp support may be available by endpoint and is useful for subtitles, editing, and media indexing workflows."
+  },
+  {
+    "question": "Can I build subtitles with 9jaLingo STT?",
+    "answer": "Yes. STT transcripts can be transformed into subtitle files for video publishing and accessibility."
+  },
+  {
+    "question": "Can STT detect multiple speakers?",
+    "answer": "Speaker handling capabilities vary by model flow and may require post-processing for best diarization output."
+  },
+  {
+    "question": "Can I process STT in near real time?",
+    "answer": "Yes. Near-real-time patterns are possible with streaming ingestion and incremental transcript handling."
+  },
+  {
+    "question": "Can STT be used for meeting notes?",
+    "answer": "Yes. Teams use STT to capture meetings, generate summaries, and improve documentation speed."
+  },
+  {
+    "question": "How should I store STT transcripts?",
+    "answer": "Store transcripts with metadata such as language, source ID, and timestamp, then index them for search and audit needs."
+  },
+  {
+    "question": "What is voice cloning on 9jaLingo?",
+    "answer": "Voice cloning creates a synthetic voice that matches a target speaker's tone, style, and cadence from approved sample audio."
+  },
+  {
+    "question": "Who can use voice cloning?",
+    "answer": "Creators, studios, brands, and product teams can use voice cloning after meeting consent and policy requirements."
+  },
+  {
+    "question": "Do I need permission to clone a voice?",
+    "answer": "Yes. Explicit rights and consent are required before cloning any voice, and unauthorized use is not allowed."
+  },
+  {
+    "question": "How much audio is needed for cloning?",
+    "answer": "Higher-quality and longer clean recordings usually improve clone quality, while short noisy samples reduce accuracy."
+  },
+  {
+    "question": "Can cloned voices be used for ads?",
+    "answer": "Yes. When licensing and consent terms are satisfied, cloned voices can be used in campaigns and branded content."
+  },
+  {
+    "question": "How do I get better clone quality?",
+    "answer": "Use studio-quality recordings, stable microphone distance, low noise, and consistent speaking pace in source material."
+  },
+  {
+    "question": "What is 9jaLingo voice-over service?",
+    "answer": "Voice-over service helps creators and teams produce polished narration for videos, ads, podcasts, explainers, and product content."
+  },
+  {
+    "question": "Can content creators use 9jaLingo for social videos?",
+    "answer": "Yes. Creators can generate consistent voice-overs quickly for shorts, reels, tutorials, and educational content."
+  },
+  {
+    "question": "Can agencies produce multilingual voice campaigns?",
+    "answer": "Yes. Agencies can produce voice tracks across supported languages and test voice options for each market."
+  },
+  {
+    "question": "Can I update script lines without re-recording everything?",
+    "answer": "Yes. You can regenerate only changed lines and keep production workflows fast and cost-efficient."
+  },
+  {
+    "question": "Can I build brand voice identity with 9jaLingo?",
+    "answer": "Yes. Teams can select or clone voices to maintain a consistent audio brand across channels."
+  },
+  {
+    "question": "Does 9jaLingo provide developer API access?",
+    "answer": "Yes. 9jaLingo offers developer APIs for TTS, STT, voice cloning, and related voice workflows."
+  },
+  {
+    "question": "Can I call 9jaLingo from Node.js?",
+    "answer": "Yes. You can call endpoints from Node.js environments using standard authentication and JSON payloads."
+  },
+  {
+    "question": "How do I protect my API key?",
+    "answer": "Store keys in secure environment variables, rotate regularly, and never expose secrets in client-side code."
+  },
+  {
+    "question": "Are webhooks available for async jobs?",
+    "answer": "Webhook-style completion patterns can be implemented for long-running tasks to improve app responsiveness."
+  },
+  {
+    "question": "Can I test endpoints before production?",
+    "answer": "Yes. Validate in staging with representative payloads and monitor response times before full rollout."
+  },
+  {
+    "question": "What API reliability practice is recommended?",
+    "answer": "Use retries, timeout controls, request IDs, monitoring, and fallback responses to keep user experience stable."
+  },
+  {
+    "question": "How does 9jaLingo pricing generally work?",
+    "answer": "Pricing depends on workload type, such as character count, audio duration, model usage, and selected service tier."
+  },
+  {
+    "question": "Can I track usage for cost control?",
+    "answer": "Yes. Usage tracking and reporting help teams monitor spend and optimize request patterns."
+  },
+  {
+    "question": "Are there limits on API requests?",
+    "answer": "Rate limits may apply by plan and help protect service reliability for all platform users."
+  },
+  {
+    "question": "Can I upgrade plans when usage grows?",
+    "answer": "Yes. Plans can be adjusted as product adoption increases or enterprise requirements expand."
+  },
+  {
+    "question": "Does 9jaLingo support enterprise security expectations?",
+    "answer": "Enterprise security practices are supported through secure access controls, operational monitoring, and policy-based workflows."
+  },
+  {
+    "question": "What governance checks should teams do before launch?",
+    "answer": "Teams should verify consent rights, data handling, retention policy, access control, and audit requirements before go-live."
+  },
+  {
+    "question": "How do I contact 9jaLingo support?",
+    "answer": "Use the official support channels on the product website or contact email to open a ticket."
+  },
+  {
+    "question": "What information should I send in a support ticket?",
+    "answer": "Include request ID, timestamp, endpoint, payload summary, expected output, and the exact error message."
+  },
+  {
+    "question": "Why is my audio generation taking longer than expected?",
+    "answer": "Long text, high concurrency, or temporary load can increase latency, so use async flow and retries."
+  },
+  {
+    "question": "What should I do when STT output is inaccurate?",
+    "answer": "Check audio quality, language setting, and speaking clarity, then retry with improved input audio."
+  },
+  {
+    "question": "What should I do when voice clone quality is weak?",
+    "answer": "Upload cleaner source audio with less noise and more consistent speech, then retrain or regenerate."
+  },
+  {
+    "question": "Can support help with integration debugging?",
+    "answer": "Yes. Support can guide endpoint usage, auth setup, and request validation for faster integration fixes."
+  },
+  {
+    "question": "How do I report a bug on the platform?",
+    "answer": "Submit reproducible steps, environment details, and logs so the team can investigate quickly."
+  },
+  {
+    "question": "Can I request a new language or voice?",
+    "answer": "Yes. You can submit feature requests and the team can review demand and roadmap fit."
+  },
+  {
+    "question": "Does 9jaLingo provide onboarding help for teams?",
+    "answer": "Yes. Onboarding support can include setup guidance, API walkthroughs, and best-practice recommendations."
+  },
+  {
+    "question": "Can I get help choosing between TTS, STT, and voice cloning?",
+    "answer": "Yes. Support can map your use case to the best workflow and propose phased implementation."
+  },
+  {
+    "question": "What is the credit system in 9jaLingo?",
+    "answer": "9jaLingo uses a credit-based system where $1 USD equals 1,000 credits, and 1 credit is worth $0.001."
+  },
+  {
+    "question": "How much does standard TTS cost per character?",
+    "answer": "Standard TTS costs 0.05 credits per character, which equals $0.05 per 1,000 characters."
+  },
+  {
+    "question": "What are the available subscription tiers?",
+    "answer": "There are three tiers: Starter (free), PAYG Lite at $10/month, and PAYG Pro at $50/month."
+  },
+  {
+    "question": "How many credits does the free Starter plan include?",
+    "answer": "The Starter plan includes 2,000 credits per month at no cost."
+  },
+  {
+    "question": "How many credits does the Lite plan include?",
+    "answer": "The PAYG Lite plan at $10/month includes 10,000 credits."
+  },
+  {
+    "question": "How many credits does the Pro plan include?",
+    "answer": "The PAYG Pro plan at $50/month includes 60,000 credits, which is 6 times more than Lite for only 5 times the price."
+  },
+  {
+    "question": "What is the credit-to-USD conversion rate?",
+    "answer": "1 credit = $0.001 USD, and $1 USD = 1,000 credits."
+  },
+  {
+    "question": "How are credits deducted for TTS generation?",
+    "answer": "Credits are deducted using the formula: credits_charged = character_count \u00d7 rate_per_char. Deduction happens before synthesis begins."
+  },
+  {
+    "question": "What happens if a user runs out of credits mid-request?",
+    "answer": "The API returns an HTTP 402 error if the user's balance is insufficient before synthesis starts."
+  },
+  {
+    "question": "Are top-up packages available and at what rate?",
+    "answer": "Yes, top-up packages are available at a uniform rate of $1 = 1,000 credits across all tiers, from $2 up to $100."
+  },
+  {
+    "question": "Do Pro plan users get a better top-up rate?",
+    "answer": "No, top-up packages use the same uniform rate for all plan tiers. Pro users benefit from their larger monthly credit allocation instead."
+  },
+  {
+    "question": "What is the credit rollover policy per plan?",
+    "answer": "Starter credits roll over for 30 days, Lite for 60 days, and Pro for 90 days. Top-up credits inherit the active plan's expiry window."
+  },
+  {
+    "question": "What are the API rate limits per plan?",
+    "answer": "Starter is limited to 5 requests per hour, Lite to 60 per hour, and Pro to 300 per hour."
+  },
+  {
+    "question": "How is TTS pricing exposed in the API versus the dashboard?",
+    "answer": "TTS is billed per character internally but exposed as tokens to API developers, where 1 NLP token equals approximately 4 characters. Both metrics appear in the dashboard."
+  },
+  {
+    "question": "What is the token rate for standard TTS in API terms?",
+    "answer": "Standard TTS costs 0.20 credits per token, which equals $0.20 per 1,000 tokens."
+  },
+  {
+    "question": "How much does it cost to generate a 2-minute news bulletin?",
+    "answer": "A 2-minute news bulletin is approximately 1,800 characters, costing 90 credits or $0.09 using standard TTS."
+  },
+  {
+    "question": "What does generating a full 10-hour audiobook cost?",
+    "answer": "A 10-hour audiobook is approximately 540,000 characters, costing around 27,000 credits or $27.00 using standard TTS."
+  },
+  {
+    "question": "Is the free Starter plan suitable for commercial use?",
+    "answer": "No. Free Starter plan audio output is watermarked and not licensed for commercial use. Upgrading to Lite or Pro removes the watermark and enables commercial rights."
+  },
+  {
+    "question": "What does voice cloning cost?",
+    "answer": "Voice cloning has a one-time training fee and an ongoing per-character generation rate charged each time the cloned voice is used for TTS."
+  },
+  {
+    "question": "Is voice cloning available on the Starter plan?",
+    "answer": "No, voice cloning is not available on the free Starter plan. It is available from the Lite plan upward."
+  },
+  {
+    "question": "How is audio processing for voice cloning charged?",
+    "answer": "A one-time non-refundable audio processing fee is charged at upload, ranging from free for audio under 30 seconds up to 80 credits for batches over 30 minutes."
+  },
+  {
+    "question": "What audio duration is free to process for voice cloning?",
+    "answer": "Audio up to 30 seconds is processed for free. Any audio longer than 30 seconds incurs a processing fee."
+  },
+  {
+    "question": "Are voice cloning processing fees refundable?",
+    "answer": "No, audio processing fees are non-refundable once the upload begins. Users must be informed before uploading."
+  },
+  {
+    "question": "How should the dashboard display credit usage?",
+    "answer": "The dashboard must always display both credits and the USD equivalent side by side, for example showing '50 cr ($0.05 USD)'."
+  },
+  {
+    "question": "What is the per-request character limit to prevent abuse?",
+    "answer": "A hard cap of 50,000 characters per API request is recommended to prevent runaway credit drain from malformed calls."
+  },
+  {
+    "question": "How does 9jaLingo pricing compare to competitors for standard TTS?",
+    "answer": "At $50 per million characters, 9jaLingo is positioned as a competitive mid-tier option, above Google Basic at $4/M but in line with other quality providers."
+  },
+  {
+    "question": "What is the infrastructure cost basis for 9jaLingo pricing?",
+    "answer": "Infrastructure runs on RunPod RTX 6000 Ada at approximately $2.60\u2013$3.00 per million characters, with pricing set to achieve a 230\u2013400% margin over that cost."
+  },
+  {
+    "question": "How should credit top-ups for the $100 package be recorded?",
+    "answer": "A $100 top-up delivers 100,000 credits at $0.001 per credit. Credits expire according to the user's active plan rollover policy."
+  },
+  {
+    "question": "What response code should be returned when a rate limit is exceeded?",
+    "answer": "The API should return HTTP 429 with a Retry-After header indicating when the user can make their next request."
+  },
+  {
+    "question": "What are your support response hours?",
+    "answer": "Support response times depend on your plan and request priority. For urgent issues, include clear impact details and request IDs to speed up handling."
+  },
+  {
+    "question": "What is the fastest way to get technical help?",
+    "answer": "Open a support ticket with reproducible steps, request IDs, timestamps, and logs. This gives the team enough detail to diagnose quickly."
+  },
+  {
+    "question": "Can I contact support for billing questions?",
+    "answer": "Yes. Support can help with billing, credits, usage questions, and plan guidance."
+  },
+  {
+    "question": "How do I escalate a production incident?",
+    "answer": "Create a ticket marked as production-impacting and include service impact, error rate, affected endpoints, and recent deployment context."
+  },
+  {
+    "question": "Can support help with API integration reviews?",
+    "answer": "Yes. The team can review common integration issues such as authentication, retries, payload structure, and endpoint usage patterns."
+  },
+  {
+    "question": "What details should I include when reporting latency issues?",
+    "answer": "Include endpoint name, average and peak latency, timestamp range, region, payload size, and any retry behavior observed."
+  },
+  {
+    "question": "Can I contact support for feature requests?",
+    "answer": "Yes. You can submit feature requests for voices, languages, APIs, or dashboard improvements, and the team will evaluate roadmap fit."
+  },
+  {
+    "question": "Where should I contact 9jaLingo support?",
+    "answer": "Use the official contact and support channels listed on the 9jaLingo website and product dashboard."
+  },
+  {
+    "question": "What is the 9jaLingo Python SDK?",
+    "answer": "The 9jaLingo Python SDK is the official client library that simplifies API usage for TTS, streaming, speaker operations, and related workflows."
+  },
+  {
+    "question": "How do I install the 9jaLingo SDK?",
+    "answer": "Install the SDK with pip from PyPI, then configure your API key in environment variables or client initialization."
+  },
+  {
+    "question": "Does the SDK support streaming audio output?",
+    "answer": "Yes. The SDK supports streaming audio chunks so you can start playback before full generation completes."
+  },
+  {
+    "question": "Can I choose response formats through the SDK?",
+    "answer": "Yes. The SDK supports multiple output formats such as WAV, PCM, MP3, FLAC, AAC, ALAC, and OGG, depending on endpoint support."
+  },
+  {
+    "question": "Does the SDK support voice cloning workflows?",
+    "answer": "Yes. The SDK includes voice cloning operations where supported, including sending approved reference audio and generating cloned speech."
+  },
+  {
+    "question": "Which Python versions are recommended for the SDK?",
+    "answer": "Use a modern supported Python version as documented in the SDK README, and keep dependencies updated for best compatibility."
+  },
+  {
+    "question": "What is included in the voice-over service?",
+    "answer": "The voice-over service supports script-to-audio generation, speaker selection, language control, and export-ready narration for media workflows."
+  },
+  {
+    "question": "Can I generate voice-overs for ads and explainer videos?",
+    "answer": "Yes. Voice-over workflows are suitable for ads, explainers, social media clips, podcasts, and educational content."
+  },
+  {
+    "question": "Can I keep a consistent narrator voice across episodes?",
+    "answer": "Yes. You can reuse the same speaker profile and generation settings to maintain a consistent narration style across episodes or campaigns."
+  },
+  {
+    "question": "How do I improve voice-over script quality before generation?",
+    "answer": "Use clear punctuation, natural sentence breaks, and pronunciation-friendly wording, then test short samples before full export."
+  },
+  {
+    "question": "Can teams automate voice-over generation in pipelines?",
+    "answer": "Yes. Teams can automate voice-over production using API calls, batch jobs, and post-processing in their content pipelines."
+  },
+  {
+    "question": "Which export formats are best for voice-over delivery?",
+    "answer": "WAV is best for mastering and post-production, while MP3 or AAC are common for lightweight distribution and web playback."
+  },
+  {
+    "question": "Where can I read 9jaLingo Terms of Service?",
+    "answer": "You can read the Terms of Service on the platform website at the terms page."
+  },
+  {
+    "question": "What does accepting the Terms mean?",
+    "answer": "By using 9jaLingo, you agree to follow the platform rules and usage guidelines."
+  },
+  {
+    "question": "Can my account be terminated for misuse?",
+    "answer": "Yes. Accounts that violate the Terms or misuse platform services may be suspended or terminated."
+  },
+  {
+    "question": "Can 9jaLingo update its Terms of Service?",
+    "answer": "Yes. Terms may be updated from time to time, and continued use indicates acceptance of revised terms."
+  },
+  {
+    "question": "Does 9jaLingo require lawful platform use?",
+    "answer": "Yes. Users are expected to use all platform features only for lawful and responsible purposes."
+  },
+  {
+    "question": "Where can I read the 9jaLingo Privacy Policy?",
+    "answer": "You can read the Privacy Policy on the platform website at the privacy-policy page."
+  },
+  {
+    "question": "What personal data does 9jaLingo collect?",
+    "answer": "The platform may collect account and technical data such as name, email, device information, IP address, and usage activity."
+  },
+  {
+    "question": "Does 9jaLingo sell personal data?",
+    "answer": "No. The privacy policy states that 9jaLingo does not sell personal information to third parties."
+  },
+  {
+    "question": "Does 9jaLingo use cookies?",
+    "answer": "Yes. Cookies are used for login persistence, user preferences, and performance analytics."
+  },
+  {
+    "question": "Can I request account or data deletion?",
+    "answer": "Yes. Users can request account deletion or data removal according to platform policy."
+  },
+  {
+    "question": "Where is the API documentation page on the website?",
+    "answer": "The API documentation is available on the /api-documentation page."
+  },
+  {
+    "question": "Is the API OpenAI-compatible?",
+    "answer": "Yes. The documentation describes OpenAI-compatible endpoint patterns for speech generation workflows."
+  },
+  {
+    "question": "What is the main TTS endpoint in the API docs?",
+    "answer": "The primary endpoint for speech generation is /v1/audio/speech."
+  },
+  {
+    "question": "Is there a dedicated streaming endpoint in the API docs?",
+    "answer": "Yes. The streaming endpoint is /v1/audio/speech/stream for progressive audio output."
+  },
+  {
+    "question": "Which language codes are shown in the API docs?",
+    "answer": "The docs reference language codes such as ha, ig, yo, and pcm."
+  },
+  {
+    "question": "How do I authenticate API calls from the docs examples?",
+    "answer": "Examples use Bearer token authentication with your API key in the Authorization header."
+  },
+  {
+    "question": "Does the API docs section show code examples in multiple languages?",
+    "answer": "Yes. The docs include examples in Python, JavaScript, and cURL."
+  },
+  {
+    "question": "Is there an official JavaScript SDK listed in the docs?",
+    "answer": "The API docs indicate there is no official JavaScript SDK yet and recommend direct REST usage."
+  },
+  {
+    "question": "Can I set generation controls like temperature and top_p through the API?",
+    "answer": "Yes. The examples show optional generation controls such as temperature, top_p, and repetition_penalty."
+  },
+  {
+    "question": "Can I pass a specific speaker ID in API requests?",
+    "answer": "Yes. Speaker IDs can be supplied in supported requests to control voice identity."
+  },
+  {
+    "question": "Does the frontend support email verification during auth?",
+    "answer": "Yes. The auth flow includes account/code verification pages."
+  },
+  {
+    "question": "Does 9jaLingo support 2FA verification in login flow?",
+    "answer": "Yes. The frontend includes a verify-2fa flow where users submit a one-time code."
+  },
+  {
+    "question": "Can users reset forgotten passwords from the frontend?",
+    "answer": "Yes. Forgot-password and reset-password routes are available for account recovery."
+  },
+  {
+    "question": "Is social authentication supported in the frontend?",
+    "answer": "Yes. The frontend includes Google and GitHub auth routes."
+  },
+  {
+    "question": "Is there a login error route in the auth system?",
+    "answer": "Yes. The frontend has a dedicated login-error route to handle authentication failures."
+  },
+  {
+    "question": "Can existing accounts be linked after social login?",
+    "answer": "Yes. The frontend includes a link-account flow for account linking scenarios."
+  },
+  {
+    "question": "Does the dashboard include API key management?",
+    "answer": "Yes. The dashboard includes a dedicated API Keys section."
+  },
+  {
+    "question": "Does the dashboard include usage analytics?",
+    "answer": "Yes. Usage analytics is available as a dashboard section for monitoring activity."
+  },
+  {
+    "question": "Can users manage subscriptions from the dashboard?",
+    "answer": "Yes. Subscription management is available in the dashboard modules."
+  },
+  {
+    "question": "Is there a support section inside the dashboard?",
+    "answer": "Yes. The dashboard includes a Support section for help-related tasks."
+  },
+  {
+    "question": "Is there a Voice Library section in the frontend dashboard?",
+    "answer": "Yes. A Voice Library section is present in the dashboard feature modules."
+  },
+  {
+    "question": "Can users access Speech-to-Text from the dashboard UI?",
+    "answer": "Yes. The frontend includes a dedicated Speech-to-Text section in dashboard space."
+  },
+  {
+    "question": "Can users access Text-to-Speech from the dashboard UI?",
+    "answer": "Yes. The dashboard provides a Text-to-Speech feature area."
+  },
+  {
+    "question": "Can users access Voice Cloning from the dashboard UI?",
+    "answer": "Yes. The dashboard includes a Voice Cloning section."
+  },
+  {
+    "question": "Does the frontend include a contact page?",
+    "answer": "Yes. The website includes a public contact page for inquiries."
+  },
+  {
+    "question": "Does the frontend include dedicated Terms and Privacy pages?",
+    "answer": "Yes. The site has separate /terms-of-service and /privacy-policy pages."
+  },
+  {
+    "question": "Can users add payment cards from the frontend flow?",
+    "answer": "Yes. The payment callback flow verifies card transactions and saves a payment method."
+  },
+  {
+    "question": "Which payment provider appears in the frontend card callback flow?",
+    "answer": "The callback flow references Paystack for card verification and setup."
+  },
+  {
+    "question": "Does the payment callback redirect users back to a subscription section?",
+    "answer": "Yes. After card processing, users are redirected to the dashboard subscription section with status parameters."
+  },
+  {
+    "question": "Can the frontend show payment setup success or failure status?",
+    "answer": "Yes. The callback flow sets payment status messages for success or error outcomes."
+  },
+  {
+    "question": "Does 9jaLingo support a LiveKit voice agent integration?",
+    "answer": "Yes. 9jaLingo supports a LiveKit-based real-time voice AI agent integration using a custom 9jaLingo TTS plugin."
+  },
+  {
+    "question": "Which command starts the LiveKit agent in development mode?",
+    "answer": "Run 'uv run agent.py dev' to start the LiveKit agent in development mode."
+  },
+  {
+    "question": "Can I test the LiveKit agent locally from terminal?",
+    "answer": "Yes. You can run 'uv run agent.py console' to test the agent in console mode without a full LiveKit room workflow."
+  },
+  {
+    "question": "What command is used for production agent startup?",
+    "answer": "Use 'uv run agent.py start' for production mode startup."
+  },
+  {
+    "question": "Does the LiveKit agent support Nigerian-language TTS through 9jaLingo server?",
+    "answer": "Yes. The agent uses the custom NaijaLingo TTS plugin and calls the 9jaLingo server endpoint for synthesis."
+  },
+  {
+    "question": "Which environment variables are required for 9jaLingo TTS in the LiveKit agent?",
+    "answer": "Set NAIJALINGO_BASE_URL, NAIJALINGO_SPEAKER, and NAIJALINGO_LANGUAGE, plus your API key and LiveKit/OpenAI credentials."
+  },
+  {
+    "question": "Can the LiveKit agent use telephony-optimized noise cancellation?",
+    "answer": "Yes. For telephony scenarios, you can switch to BVCTelephony noise cancellation for improved call audio handling."
+  },
+  {
+    "question": "Does the LiveKit integration support multilingual turn detection?",
+    "answer": "Yes. The integration includes multilingual turn-detection support for more natural conversational turn-taking."
+  },
+  {
+    "question": "Can I deploy the LiveKit agent to LiveKit Cloud?",
+    "answer": "Yes. You can deploy with the LiveKit CLI, which helps generate required deployment files and register the agent in LiveKit Cloud."
+  },
+  {
+    "question": "How do I verify the 9jaLingo TTS server health for LiveKit integration?",
+    "answer": "You can call the health endpoint on your configured base URL, for example '/v1/health', to confirm the TTS server is available."
+  }
+]

main.py

@@ -0,0 +1,118 @@
+from contextlib import asynccontextmanager
+from datetime import datetime
+from typing import Optional
+
+import uvicorn
+from fastapi import FastAPI, HTTPException, status
+from pydantic import BaseModel, Field
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import StreamingResponse
+
+from src.chat_service import chat_service
+
+class ChatRequest(BaseModel):
+    message: str = Field(..., min_length=1, max_length=4096, description="User input message")
+    thread_id: Optional[str] = Field(default="default", description="Conversation ID for memory tracking")
+
+class ChatResponse(BaseModel):
+    response: str = Field(..., description="Assistant's response")
+    thread_id: str = Field(..., description="Conversation ID used for memory tracking")
+    timestamp: datetime = Field(default_factory=datetime.now)
+
+class HealthResponse(BaseModel):
+    status: str = Field(..., description="Service status")
+    timestamp: datetime = Field(default_factory=datetime.now)
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup
+    print("Starting up the application...")
+    yield
+    # Shutdown
+    print("Shutting down the application...")
+
+app = FastAPI(
+    title="9jaLingo RAG Chat API",
+    description="RAG API for interacting with the 9jaLingo support chatbot",
+    version="1.0.0",
+    lifespan=lifespan
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+@app.get("/health", 
+         response_model=HealthResponse,
+         status_code=status.HTTP_200_OK,
+         tags=["Health"])
+async def health_check():
+    """
+    Endpoint to check if the service is running.
+    Returns a 200 OK response if the service is healthy.
+    """
+    try:
+        return HealthResponse(
+            status="healthy",
+            timestamp=datetime.now()
+        )
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Service health check failed: {str(e)}"
+        )
+
+@app.post("/chat", 
+          response_model=ChatResponse,
+          status_code=status.HTTP_200_OK,
+          tags=["Chat"])
+async def chat_endpoint(request: ChatRequest):
+    try:
+        thread_id = request.thread_id or "default"
+        response = chat_service.chat(request.message, thread_id)
+
+        return ChatResponse(
+            response=response,
+            thread_id=thread_id,
+            timestamp=datetime.now()
+        )
+
+    except ValueError as ve:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail=str(ve)
+        )
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Error processing chat request: {str(e)}"
+        )
+
+
+@app.post("/stream", tags=["Chat"])
+async def stream_endpoint(request: ChatRequest):
+    try:
+        thread_id = request.thread_id or "default"
+
+        def generate():
+            yield from chat_service.stream(request.message, thread_id)
+
+        return StreamingResponse(generate(), media_type="text/plain")
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Error streaming chat response: {str(e)}"
+        )
+
+if __name__ == "__main__":
+    uvicorn.run(
+        "main:app",
+        host="0.0.0.0",
+        port=8000,
+        reload=True,
+        workers=1
+    )

pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "9jalingo-bot"
+version = "0.1.0"
+description = "RAG/FastAPI support assistant for 9jaLingo"
+readme = "Readme.md"
+requires-python = ">=3.12"
+dependencies = [
+  "langchain",
+  "langchain-core",
+  "python-dotenv",
+  "langchain-chroma",
+  "chromadb",
+  "fastapi[standard]",
+  "langchain-ollama",
+]
+
+[build-system]
+requires = ["hatchling>=1.25.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src"]
+
+[tool.uv]
+package = true

requirements.txt

@@ -0,0 +1,7 @@
+fastapi[standard]
+langchain
+langchain-core
+langchain-chroma
+chromadb
+langchain-ollama
+python-dotenv

src/chat_service.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import os
+from collections import defaultdict, deque
+from collections.abc import Generator
+from dataclasses import dataclass
+
+from langchain_core.messages import BaseMessage, HumanMessage, SystemMessage
+from langchain_ollama import ChatOllama
+
+from src.ingest import get_or_build_vectorstore
+
+
+MAX_MEMORY_TURNS = int(os.getenv("RAG_MEMORY_TURNS", "6"))
+LLM_MODEL = os.getenv("LLM_MODEL", "hf.co/LiquidAI/LFM2-1.2B-RAG-GGUF:Q5_K_M")
+
+
+@dataclass
+class MemoryTurn:
+    user_message: str
+    assistant_message: str
+
+
+class ConversationMemory:
+    def __init__(self, max_turns: int = MAX_MEMORY_TURNS) -> None:
+        self._max_turns = max_turns
+        self._store: dict[str, deque[MemoryTurn]] = defaultdict(lambda: deque(maxlen=self._max_turns))
+
+    def append(self, conversation_id: str, user_message: str, assistant_message: str) -> None:
+        self._store[conversation_id].append(
+            MemoryTurn(user_message=user_message, assistant_message=assistant_message)
+        )
+
+    def format_history(self, conversation_id: str) -> str:
+        history = self._store.get(conversation_id)
+        if not history:
+            return "No previous conversation."
+
+        lines: list[str] = []
+        for turn in history:
+            lines.append(f"User: {turn.user_message}")
+            lines.append(f"Assistant: {turn.assistant_message}")
+        return "\n".join(lines)
+
+
+class RagChatService:
+    def __init__(self, k: int = 4) -> None:
+        self._k = k
+        self._vectorstore = None
+        self._retriever = None
+        self._llm = None
+        self._memory = ConversationMemory()
+
+    def _get_retriever(self):
+        if self._retriever is None:
+            self._vectorstore = get_or_build_vectorstore()
+            self._retriever = self._vectorstore.as_retriever(search_kwargs={"k": self._k})
+        return self._retriever
+
+    def _get_llm(self) -> ChatOllama:
+        if self._llm is None:
+            self._llm = ChatOllama(model=LLM_MODEL, temperature=0.2)
+        return self._llm
+
+    def _format_context(self, question: str) -> str:
+        docs = self._get_retriever().invoke(question)
+        if not docs:
+            return "No relevant FAQ context found."
+        return "\n\n".join(doc.page_content for doc in docs)
+
+    def _build_messages(self, question: str, conversation_id: str) -> list[BaseMessage]:
+        history = self._memory.format_history(conversation_id)
+        context = self._format_context(question)
+        system_prompt = (
+            "You are a concise and helpful support assistant for 9jaLingo, a voice AI platform. "
+            "Use only the provided FAQ context and recent conversation history. "
+            "If the answer is not in the context, say that clearly and direct the user to official support.\n\n"
+            f"Conversation history:\n{history}\n\n"
+            f"FAQ context:\n{context}"
+        )
+        return [
+            SystemMessage(content=system_prompt),
+            HumanMessage(content=question),
+        ]
+
+    def chat(self, question: str, conversation_id: str) -> str:
+        messages = self._build_messages(question, conversation_id)
+        response = self._get_llm().invoke(messages)
+        answer = response.content if isinstance(response.content, str) else str(response.content)
+        self._memory.append(conversation_id, question, answer)
+        return answer
+
+    def stream(self, question: str, conversation_id: str) -> Generator[str, None, None]:
+        messages = self._build_messages(question, conversation_id)
+        parts: list[str] = []
+        for chunk in self._get_llm().stream(messages):
+            content = chunk.content if isinstance(chunk.content, str) else str(chunk.content)
+            if not content:
+                continue
+            parts.append(content)
+            yield content
+
+        self._memory.append(conversation_id, question, "".join(parts))
+
+
+chat_service = RagChatService()

src/chatbot.py

@@ -0,0 +1,58 @@
+"""
+chatbot.py — standalone RAG chain helpers for 9jaLingo FAQ chatbot.
+"""
+
+from __future__ import annotations
+
+import os
+from operator import itemgetter
+
+from langchain_core.output_parsers import StrOutputParser
+from langchain_core.prompts import ChatPromptTemplate
+from langchain_core.runnables import RunnableParallel
+from langchain_ollama import ChatOllama
+
+from src.ingest import get_or_build_vectorstore
+
+
+LLM_MODEL = os.getenv("LLM_MODEL", "hf.co/LiquidAI/LFM2-1.2B-RAG-GGUF:Q5_K_M")
+
+SYSTEM_PROMPT = """You are a friendly and knowledgeable support assistant for 9jaLingo,
+a voice AI platform for African language speech products.
+
+Answer the user's question using ONLY the context provided below.
+If the context does not contain enough information to answer, say so politely
+and suggest the user visit https://www.9jalingo.org or contact support.
+
+Context:
+{context}
+"""
+
+
+def _format_docs(docs) -> str:  # type: ignore[type-arg]
+    return "\n\n".join(doc.page_content for doc in docs)
+
+
+def build_rag_chain(k: int = 4):
+    vectorstore = get_or_build_vectorstore()
+    retriever = vectorstore.as_retriever(search_kwargs={"k": k})
+
+    llm = ChatOllama(model=LLM_MODEL, temperature=0.2)
+    prompt = ChatPromptTemplate.from_messages(
+        [
+            ("system", SYSTEM_PROMPT),
+            ("human", "{question}"),
+        ]
+    )
+
+    setup = RunnableParallel(
+        context=itemgetter("question") | retriever | _format_docs,
+        question=itemgetter("question"),
+    )
+
+    return setup | prompt | llm | StrOutputParser()
+
+
+def stream_rag_chain(question: str, k: int = 4):
+    chain = build_rag_chain(k=k)
+    yield from chain.stream({"question": question})

src/ingest.py

@@ -0,0 +1,87 @@
+"""
+ingest.py — Load FAQ JSON, create LangChain Documents, and store
+embeddings in a local ChromaDB collection.
+
+Run directly to (re)build the vector store:
+    python -m src.ingest
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from langchain_core.documents import Document
+from langchain_chroma import Chroma
+from langchain_ollama import OllamaEmbeddings
+
+# Paths: keep knowledge data and vector store under rag/
+_HERE = Path(__file__).parent
+_RAG_DIR = _HERE.parent / "data"
+FAQ_PATH = _RAG_DIR / "faq.json"
+CHROMA_DIR = _RAG_DIR / "chroma_db"
+
+EMBED_MODEL = os.getenv("EMBED_MODEL", "embeddinggemma:latest")
+COLLECTION_NAME = "naijalingo_faq"
+
+
+def load_faq_documents(faq_path: Path = FAQ_PATH) -> list[Document]:
+    with open(faq_path, encoding="utf-8") as f:
+        items = json.load(f)
+
+    docs: list[Document] = []
+    for i, item in enumerate(items):
+        question = item.get("question", "").strip()
+        answer = item.get("answer", "").strip()
+        content = f"Question: {question}\nAnswer: {answer}"
+        docs.append(
+            Document(
+                page_content=content,
+                metadata={"source": "faq.json", "index": i, "question": question},
+            )
+        )
+    return docs
+
+
+def build_vectorstore(
+    faq_path: Path = FAQ_PATH,
+    chroma_dir: Path = CHROMA_DIR,
+    embed_model: str = EMBED_MODEL,
+) -> Chroma:
+    docs = load_faq_documents(faq_path)
+    embeddings = OllamaEmbeddings(model=embed_model)
+
+    chroma_dir.mkdir(parents=True, exist_ok=True)
+    vectorstore = Chroma.from_documents(
+        documents=docs,
+        embedding=embeddings,
+        collection_name=COLLECTION_NAME,
+        persist_directory=str(chroma_dir),
+    )
+    print(f"[ingest] Indexed {len(docs)} FAQ entries -> {chroma_dir}")
+    return vectorstore
+
+
+def load_vectorstore(
+    chroma_dir: Path = CHROMA_DIR,
+    embed_model: str = EMBED_MODEL,
+) -> Chroma:
+    embeddings = OllamaEmbeddings(model=embed_model)
+    return Chroma(
+        collection_name=COLLECTION_NAME,
+        embedding_function=embeddings,
+        persist_directory=str(chroma_dir),
+    )
+
+
+def get_or_build_vectorstore() -> Chroma:
+    if CHROMA_DIR.exists() and any(CHROMA_DIR.iterdir()):
+        print("[ingest] Loading existing vector store from disk...")
+        return load_vectorstore()
+    print("[ingest] Building vector store for the first time...")
+    return build_vectorstore()
+
+
+if __name__ == "__main__":
+    build_vectorstore()