RAG (Retrieval-Augmented Generation) chatbot – Enterprise internal Support AI Assistant. Answers support questions via REST API using hybrid retrieval (BM25 + vector search) over your knowledge base. Combines web-crawled data, manually curated sample conversations, and continuous learning from highly-rated conversations.

🔍 Keywords: RAG chatbot, LLM support assistant, WHMCS ticket crawler, vector search, knowledge base AI, customer support automation

• Data Sources & Continuous Learning
• Features
• Tech Stack
• Quick Start
• Usage Guide
• Authentication
• API Endpoints
• Configuration
• Project Structure

The knowledge base is built from three sources and improves continuously through a feedback loop:

• WHMCS tickets: Crawl support tickets from WHMCS (via Playwright, login with cookies or credentials)
• Documents from URL: Fetch webpage content (policies, FAQ, docs) via /documents/fetch-from-url API
• Website crawl: Crawl entire site via /documents/crawl-website
• Source JSON: Ingest from multiple formats – pages (url, title, text), articles, plans, sales_kb, etc.
• WHMCS SQL dump: Import tickets from source/*.sql via make import-whmcs

• sample_conversations.json: Add high-quality sample conversations directly (real Q&A)
• sample_docs.json: Pre-prepared static documents (web pages, articles)
• custom_docs.json: Documents created from admin panel, synced back to file

• Crawled tickets are manually reviewed (approve/reject). Only approved tickets are added to the knowledge base
• Export approved tickets → sample_conversations.json via POST /v1/admin/ingest-tickets-to-file
• Re-run ingest so new sample conversations are embedded and indexed into OpenSearch/Qdrant
• Loop: Crawl → Review (approve) → Export → Ingest lets the system learn more from real high-quality conversations

• RAG: BM25 (OpenSearch) + vector (Qdrant) + reranking
• Conversations: CRUD, chat sync/stream, linked to ticket/livechat
• Tickets: List from DB, approval workflow (pending/approved/rejected)
• Documents: CRUD, fetch from URL, crawl website, re-crawl, upload
• WHMCS Crawler: Crawl tickets via Playwright, save cookies, check session
• Admin: Ingest docs/tickets, config (prompts, intents, doc-types, LLM, archi), branding
• Auth: JWT login, API tokens (sk_*), user management
• Frontend: React + Vite – Login, Conversations, Sample conversations, Documents, Crawl, Dashboard, Intents, Doc Types, Settings, API Tokens, API Reference

• API: FastAPI + Pydantic v2 + Uvicorn
• DB: PostgreSQL 15+
• Cache/Queue: Redis + Celery
• Search: OpenSearch (BM25), Qdrant (vector)
• Embeddings/LLM: OpenAI (pluggable)
• Crawler: Playwright (Chromium)
• Frontend: React 19, Vite 7, Tailwind CSS

• Docker & docker-compose
• OpenAI API key

cp .env.example .env
# Edit .env: OPENAI_API_KEY, JWT_SECRET (production), ADMIN_API_KEY, API_KEY

docker-compose up -d

• API: http://localhost:8000
• Frontend: http://localhost:5174
• MinIO: http://localhost:9000 (console: 9001)

With Nginx gateway (API on port 80):

docker-compose --profile full up -d

# Inside container
docker-compose exec api alembic upgrade head
docker-compose exec api python -m scripts.create_admin_user   # Create admin (after migration 011)
docker-compose exec api python scripts/ingest_from_source.py
docker-compose exec api python scripts/ingest_tickets_from_source.py

# Or local (with services running)
make init-db
make create-admin
make ingest

Source files in source/:

• sample_docs.json – documents (pages: url, title, text)
• sample_conversations.json – tickets/conversations (from WHMCS crawl or manual)
• custom_docs.json – documents created from admin panel
• *.sql – WHMCS SQL dumps for make import-whmcs

See app/services/source_loaders.py for supported formats.

1. Start PostgreSQL, Redis, OpenSearch, Qdrant (or use docker-compose for infra only)
2. pip install -r requirements.txt
3. uvicorn app.main:app --reload
4. Worker: celery -A worker.celery_app worker --loglevel=info
5. alembic upgrade head
6. make create-admin (create first admin user)

1. Start services: docker-compose up -d
2. Run migrations: docker-compose exec api alembic upgrade head
3. Create admin: docker-compose exec api python -m scripts.create_admin_user (enter username/password when prompted)
4. Login to frontend: Open http://localhost:5174 → Login with the account you just created
5. Add knowledge base data (choose one or more methods below)

Prepare source/sample_docs.json or source/sample_conversations.json:

// sample_docs.json - documents (web pages, policy, FAQ)
{
  "pages": [
    {"url": "https://example.com/refund-policy", "title": "Refund Policy", "text": "Full content..."}
  ]
}

// sample_conversations.json - Q&A from tickets (requires external_id, subject, description)
{
  "source": "whmcs",
  "conversations": [
    {
      "external_id": "12345",
      "subject": "Refund question",
      "description": "User: How do I request a refund?\nStaff: You can request a refund within 30 days...",
      "status": "Closed",
      "priority": "Medium"
    }
  ]
}

Run ingest:

make ingest                                    # Ingest documents
python scripts/ingest_tickets_from_source.py   # Ingest sample conversations

• Single URL: Use API POST /v1/documents/fetch-from-url with {"url": "https://..."} or via frontend Documents → Add → Fetch from URL
• Entire website: Use API POST /v1/documents/crawl-website with {"base_url": "https://example.com", "max_pages": 50} or via frontend Documents → Crawl website

1. Go to Crawl (sidebar)
2. Enter Base URL (e.g. https://billing.example.com)
3. Login to WHMCS:
   • Option A (Cookies): Login to WHMCS in browser → DevTools → Application → Cookies → Copy JSON → Paste into "Session cookies" field → Save cookies
   • Option B (Credentials): Enter username, password (and TOTP if applicable) → Click "Login & Crawl"
4. Check connection → If OK, click Crawl tickets
5. Go to Sample conversations (Tickets) → Review each ticket → Approve high-quality tickets
6. Export approved → POST /v1/admin/ingest-tickets-to-file (or corresponding button) to write to sample_conversations.json
7. Run python scripts/ingest_tickets_from_source.py to embed and index

If you have a WHMCS dump file (e.g. source/greenvps_whmcs.sql):

make import-whmcs-dry   # Validate parse first
make import-whmcs       # Run actual import

This project improves chatbot performance through structured evaluation, prompt optimization, and continuous feedback loops.

Powered by OptyxStack AI Optimization to enhance accuracy, relevance, and reliability at scale.

Then approve tickets in Sample conversations and ingest as in steps 6–7 of Method 3.

1. Create conversation:

   curl -X POST http://localhost:8000/v1/conversations \
     -H "Authorization: Bearer YOUR_JWT" \
     -H "Content-Type: application/json" \
     -d '{"source_type": "ticket", "source_id": "TKT-123"}'

2. Send message (sync or stream):

   curl -X POST http://localhost:8000/v1/conversations/{CONV_ID}/messages \
     -H "Authorization: Bearer YOUR_JWT" \
     -H "Content-Type: application/json" \
     -d '{"content": "What is your refund policy?"}'

3. Response contains answer (RAG-generated) and debug_metadata (retrieval, evidence).

• Suggested reply (platform-agnostic): Call POST /v1/reply/generate with query = ticket/chat content. No conversation creation required. Use for WHMCS, Zendesk, livechat, or any helpdesk.
• Livechat / Ticket system (chat flow): Call POST /v1/conversations with source_type: "livechat" or "ticket", source_id = ID from your system. When user sends a message, call POST /v1/conversations/{id}/messages and use answer to display to the user.
• Webhook: You can wrap the API in your webhook endpoint to receive requests from livechat/ticket platforms.

API accepts three auth methods:

1. Bearer JWT – from POST /v1/auth/login (username/password)
2. X-API-Key – env API_KEY or DB API token (sk_*)
3. X-Admin-API-Key – for admin endpoints (env ADMIN_API_KEY or JWT with role=admin)

Create admin user (after migration 011):

make create-admin
# Or: python -m scripts.create_admin_user

API tokens (sk_*): Create via POST /v1/auth/tokens (requires Bearer JWT). Tokens are stored in DB and can be revoked.

curl -X POST http://localhost:8000/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "your-password"}'

curl -X POST http://localhost:8000/v1/conversations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT" \
  -d '{"source_type": "ticket", "source_id": "TKT-12345", "metadata": {}}'

curl -X POST http://localhost:8000/v1/conversations/{CONV_ID}/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "X-External-User-Id: user-123" \
  -d '{"content": "What is your refund policy?"}'

curl -X POST http://localhost:8000/v1/reply/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT" \
  -d '{
    "query": "What is your refund policy? I want to cancel my order.",
    "source_type": "ticket",
    "source_id": "TKT-12345"
  }'

Response: { "answer": "...", "decision": "PASS"|"ASK_USER"|"ESCALATE", "followup_questions": [], "citations": [...], "confidence": 0.9 }

curl -X POST http://localhost:8000/v1/admin/ingest \
  -H "Content-Type: application/json" \
  -H "X-Admin-API-Key: admin-key" \
  -d '{
    "documents": [
      {
        "url": "https://example.com/refund-policy",
        "title": "Refund Policy",
        "raw_text": "Full refund within 30 days...",
        "doc_type": "policy"
      }
    ]
  }'

make init-db       # Run migrations
make create-admin  # Create admin user
make ingest        # Ingest docs from source/
make ingest-dry    # Dry run: load docs without ingesting
make import-whmcs  # Import WHMCS tickets from source/*.sql
make import-whmcs-dry  # Dry run: validate SQL parsing

cd frontend && npm install && npm run dev
# http://localhost:5173

Or use Docker: docker-compose up -d frontend → http://localhost:5174

Main pages: Login, Conversations, Sample conversations (tickets), Documents, Crawl (WHMCS), Dashboard, Intents, Doc Types, Settings, API Tokens, API Reference.

app/
  main.py              # FastAPI app
  api/routes/          # auth, conversations, reply, tickets, documents, admin, health, dashboard
  services/            # retrieval, LLM, ingestion, ticket_db, ticket_loaders, source_loaders
  search/              # OpenSearch, Qdrant, reranker, embeddings
  crawlers/            # WHMCS crawler (Playwright)
  db/                  # Models, session
  core/                # Config, auth, logging, rate limit, tracing, gateway
worker/
  celery_app.py
  tasks.py             # Ingestion tasks
frontend/              # React + Vite (CRUD, chat, crawl UI)
alembic/              # Migrations
scripts/               # init_db, create_admin_user, ingest_from_source, ingest_tickets_from_source, import_whmcs_sql_dump_to_tickets, crawl_whmcs_tickets, whmcs_login_browser
source/                # sample_docs.json, sample_conversations.json, custom_docs.json, *.sql

pip install -e ".[dev]"
pytest tests/ -v