Customer Support Agent

LankaTel AI Support Assistant

RAG-first support with voice, actions, and a modern UI.

A RAG-based AI customer support agent built with Azure OpenAI and ChromaDB. It includes a FastAPI backend, a Next.js UI, and chat + voice workflows with agentic account actions.

Scenario

LankaTel is a conceptual internet service provider in Sri Lanka. This project is its AI support product: a complete customer support stack with a RAG knowledge brain, action-ready backend, and a modern UI. It ships with realistic telecom knowledge, supports chat and voice, and can handle guided workflows like ticket creation or service changes. Use it as a drop-in reference only.

Features

Retrieval-augmented generation with source citations
Azure OpenAI chat and embedding deployments
ChromaDB local vector store with persistence
Token-aware chunking with tiktoken
CLI for ingest, query, chat, voice, and realtime voice
FastAPI backend API for the UI and external clients
Next.js UI with chat, voice, tools, and admin console
Agentic actions (tickets, subscriptions, balance) backed by MySQL
OTP verification with a shared session across chat + voice
Quick actions panel in chat and voice once verified
Voice UI (browser STT + backend Azure TTS) and realtime CLI voice (Azure Speech)
Single-container Docker image with nginx reverse proxy

Tech Stack

AI & RAG

Azure OpenAI (GPT-4o-mini, text-embedding-3-large)
ChromaDB vector store
tiktoken for chunking

Backend

Python 3.10+, FastAPI, Uvicorn
Pydantic v2 for validation
SQLAlchemy + PyMySQL for DB access

Frontend

Next.js 16, React 19, TypeScript
Tailwind CSS, PostCSS

Data & Storage

MySQL 8.x (actions, sessions, admin data)

Voice

Browser Web Speech API (UI STT)
Azure Speech Services (backend TTS + CLI realtime STT/TTS)

Email & Security

Zoho Mail SMTP for OTP/notifications
Cloudflare as DNS provider and security layer

Dev & Ops

Docker + nginx (single-container)
pytest, ESLint, Prettier

Architecture

[Next.js UI] --> /api --> [FastAPI backend]
                        |-> [RAG pipeline] -> [ChromaDB]
                        |-> [Azure OpenAI]
                        |-> [MySQL] (actions, sessions, admin)
                        |-> [Azure Speech] (voice + TTS)

Project Structure

Customer-Support-Agent/
  api_server.py              # FastAPI backend
  src/                       # Core pipeline, services, realtime voice
  ui/                        # Next.js frontend
  data/
    raw/                     # Raw JSONL knowledge files
    processed/               # Generated KB (gitignored)
  db/                        # MySQL schema + seed data
  docker/                    # Nginx + container entrypoint
  scripts/                   # Utilities (KB build, quota check)
  tests/                     # Pytest suite
  vectorstore/               # ChromaDB persistence (gitignored)

Quick Start

Prerequisites

Python 3.10+
Node.js 18+ (for the UI)
Azure OpenAI deployments:
- chat-model (GPT-4o-mini)
- embedding-model (text-embedding-3-large)
Optional: MySQL 8.x for actions/admin data
Optional: Azure Speech for voice features

Installation

Create a virtual environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install dependencies
```
pip install -r requirements.txt
```

Configure environment

cp .env.example .env
# Edit .env with your Azure OpenAI credentials

(Optional) Initialize MySQL data
```
mysql -u root -p < db/mysql_schema.sql
```
This creates the lankatel_demo database. Point DB_URL to it in .env.
Test configuration
```
python -m src.cli test
```

Basic Usage

Ingest documents

# Ingest the bundled Lankatel data (auto-builds a processed KB)
python -m src.cli ingest data/raw/lankatel

# Ingest a directory of documents
python -m src.cli ingest data/documents/ --recursive

Ask questions

python -m src.cli query "How do I reset my password?"
python -m src.cli query "What is my plan balance?" --stream

Interactive chat
```
python -m src.cli chat
```

Voice modes (optional)

python -m src.cli voice-chat
python -m src.cli realtime

Run the API Server and UI

Start the backend
```
python api_server.py
```

Start the UI

cd ui
cp .env.example .env.local
npm install
npm run dev

The UI will be available at http://localhost:3000 and the backend at http://localhost:8000.

Verification & Agentic Actions

Account actions require OTP verification (mobile number → code).
A verified session is shared across chat and voice in the UI.
Once verified, a quick actions panel appears with account shortcuts.
Action execution is done on non-streaming chat responses to keep tool calls deterministic.

Voice Modes

UI Voice (Web)

STT: Browser Web Speech API
TTS: Backend /api/tts (Azure Speech)
Supports agentic actions and OTP verification via voice

CLI Voice

voice-chat: turn-based speech with Azure Speech
realtime: low-latency full-duplex voice with barge-in

CLI Reference

Command	Description
`ingest <path>`	Ingest documents from file or directory
`query <question>`	Ask a single question
`chat`	Start interactive chat session
`voice-chat`	Start turn-based voice chat
`realtime`	Start realtime full-duplex voice chat
`stats`	Show system statistics
`test`	Test system configuration
`clear`	Clear the vector store

Data Formats

Supported input formats:

Format	Extension	Description
Text	`.txt`	Plain text files
Markdown	`.md`	Markdown documents
JSON	`.json`	JSON with `text` or `content` field
JSON Lines	`.jsonl`	One JSON object per line

JSONL example:

{"id": "faq_001", "question": "How do I reset my password?", "answer": "Click 'Forgot Password'...", "category": "account"}
{"id": "faq_002", "question": "What payment methods?", "answer": "We accept Visa, MasterCard...", "category": "billing"}

To normalize the bundled Lankatel data manually:

python scripts/build_processed_kb.py

Configuration

All configuration is done via environment variables. See .env.example and ui/.env.example for the full list. Common settings:

# Azure OpenAI
AZURE_OPENAI_API_KEY=...
AZURE_OPENAI_ENDPOINT=...
AZURE_OPENAI_CHAT_DEPLOYMENT=chat-model
AZURE_OPENAI_EMBEDDING_DEPLOYMENT=embedding-model

# Vector store
VECTORSTORE_DIR=./vectorstore
VECTORSTORE_COLLECTION=support_docs

# Optional services
DB_URL=mysql+pymysql://user:password@localhost/lankatel_demo
AZURE_SPEECH_API_KEY=...
AZURE_SPEECH_REGION=eastus

# Email (Zoho SMTP)
EMAIL_ENABLED=true
EMAIL_SMTP_HOST=smtp.zoho.com
EMAIL_SMTP_PORT=587
EMAIL_SMTP_USERNAME=...
EMAIL_SMTP_PASSWORD=...
EMAIL_SENDER=...
EMAIL_USE_TLS=true

# Admin console
ADMIN_USERNAME=ltadmin
ADMIN_PASSWORD=change_me_strong
ADMIN_SECRET=change_me_secret

Cloudflare is used at the DNS and security layer during deployment; no app-level configuration is required.

Testing

pytest tests/ -v

Docker (Single-container frontend + backend)

This repository includes a Dockerfile that builds the Next.js UI and packages the Python backend into a single container. Nginx is used inside the container to reverse-proxy:

Requests under /api/ are forwarded to the Python backend (uvicorn) on port 8000
All other requests are forwarded to the Next.js server on port 3000

Build and run locally:

docker build -t customer-support-agent:latest .
docker run -p 80:80 customer-support-agent:latest

Notes on Azure deployment:

Push the image to a container registry (ACR or Docker Hub) and point your Azure Web App for Containers or Azure Container Instance to the image.
Azure expects a single HTTP port (80) to be served by the container; the image exposes port 80 and uses nginx as the entrypoint.

Contributing

Contributions are welcome. Please open a PR with a clear description of the change.

License

MIT. See LICENSE.

Acknowledgments

LangChain for RAG patterns
ChromaDB for vector storage
Azure OpenAI for LLMs and embeddings

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Customer Support Agent

Scenario

Features

Tech Stack

AI & RAG

Backend

Frontend

Data & Storage

Voice

Email & Security

Dev & Ops

Architecture

Project Structure

Quick Start

Prerequisites

Installation

Basic Usage

Run the API Server and UI

Verification & Agentic Actions

Voice Modes

UI Voice (Web)

CLI Voice

CLI Reference

Data Formats

Configuration

Testing

Docker (Single-container frontend + backend)

Contributing

License

Acknowledgments

About

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 34 Commits
assets		assets
data/raw		data/raw
db		db
docker		docker
scripts		scripts
src		src
tests		tests
ui		ui
.dockerignore		.dockerignore
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
api_server.py		api_server.py
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

License

KasunCSB/Customer-Support-Agent

Folders and files

Latest commit

History

Repository files navigation

Customer Support Agent

Scenario

Features

Tech Stack

AI & RAG

Backend

Frontend

Data & Storage

Voice

Email & Security

Dev & Ops

Architecture

Project Structure

Quick Start

Prerequisites

Installation

Basic Usage

Run the API Server and UI

Verification & Agentic Actions

Voice Modes

UI Voice (Web)

CLI Voice

CLI Reference

Data Formats

Configuration

Testing

Docker (Single-container frontend + backend)

Contributing

License

Acknowledgments

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Languages