SupportIQ API

A RAG-Based Customer Support API

An intelligent customer support system powered by Retrieval-Augmented Generation.
This repository contains the backend API for SupportIQ.

API Docs

---

About

SupportIQ's backend API allows customers to ask questions in natural language and receive answers built from an uploaded PDF knowledge base. Every response includes source references for full transparency. When the system isn't confident enough, conversations automatically escalate to human agents through a built-in ticketing system.

How the RAG Pipeline Works

A question is submitted via the API
       |
       v
  Embed query (sentence-transformers, all-MiniLM-L6-v2)
       |
       v
  Search Qdrant (top-5 similar chunks, cosine similarity)
       |
       v
  Build prompt (system prompt + retrieved chunks + query)
       |
       v
  Generate response (Ollama / Mistral LLM)
       |
       v
  Score confidence (average similarity of retrieved chunks)
       |
       +---> > 0.7  -->  Deliver response with sources
       +---> 0.4-0.7 -> Deliver + offer escalation
       +---> < 0.4  -->  Auto-escalate to human agent

---

Features

RAG-Powered Chat Semantic search across uploaded PDF documents Context-aware answers grounded in your knowledge base Confidence scoring on every response	Explainability & Transparency Source document references on every answer Page numbers, chunk text, and relevance scores Full audit trail of all queries and responses
Smart Escalation Auto-escalation when confidence is low Customer-initiated escalation option Ticketing system for human agents	Analytics & Reporting Query volume trends and confidence distribution Escalation rates and resolution metrics CSV and PDF report exports
Role-Based Access Control Customer -- Chat, view own conversations, escalate Agent -- Manage assigned tickets, respond to escalations Admin -- Full access: documents, analytics, reports	Document Management PDF upload with automatic text extraction Recursive text chunking and vector embedding Real-time ingestion status tracking

---

Architecture

+------------------+        +------------------+
|                  |  REST  |                  |
|   API Client     +------->+     FastAPI      +------->+   PostgreSQL     |
| (e.g. Postman)   |  API   |   (Python 3.12)  |  ORM   |   (Relational)   |
|                  |        |                  |        |                  |
+------------------+        +--------+---------+        +------------------+
                                     |
                                     |  RAG Pipeline
                                     |
                            +--------+---------+
                            |                  |
                            |  LangChain +     |        +------------------+
                            |  sentence-       +------->+     Qdrant       |
                            |  transformers    | Vector  |   (Vector DB)    |
                            |                  | Search  |                  |
                            +--------+---------+        +------------------+
                                     |
                                     | Prompt
                                     |
                            +--------+---------+
                            |                  |
                            |     Ollama       |
                            |    (Mistral)     |
                            |   Local LLM      |
                            |                  |
                            +------------------+

---

Tech Stack

Layer	Technology	Purpose
Backend	FastAPI, SQLAlchemy 2, Alembic, Pydantic 2	REST API, ORM, migrations, validation
Database	PostgreSQL 16	Users, conversations, tickets, query logs
Vector DB	Qdrant	Document embeddings storage and semantic search
Embeddings	sentence-transformers (all-MiniLM-L6-v2)	384-dim vector encoding of text chunks
LLM	Ollama + Mistral	Local language model for response generation
RAG	LangChain	Prompt templates, retrieval chains, orchestration
Auth	JWT (python-jose + passlib/bcrypt)	Stateless authentication with role-based access
PDF Parsing	PyMuPDF	Fast, reliable text extraction from PDF documents
Reports	ReportLab + Matplotlib	PDF report generation with embedded charts

---

API Overview

Method	Endpoint	Description	Auth
POST	/api/auth/register	Create account	Public
POST	/api/auth/login	Get JWT token	Public
GET	/api/auth/me	Current user info	Bearer
GET	/api/documents/	List documents	Admin
POST	/api/documents/	Upload PDF	Admin
DELETE	/api/documents/{id}	Remove document	Admin
POST	/api/chat/	New conversation	Customer
POST	/api/chat/{id}/message	Send message (triggers RAG)	Customer
GET	/api/chat/{id}/messages	Conversation history	Customer
GET	/api/tickets/	List tickets	Agent/Admin
PATCH	/api/tickets/{id}	Update ticket status	Agent
POST	/api/tickets/{id}/respond	Agent response	Agent
GET	/api/analytics/overview	Dashboard metrics	Admin
GET	/api/analytics/query-trends	Query volume over time	Admin
GET	/api/reports/query-logs?format=csv	Export query logs	Admin
GET	/api/reports/analytics?format=pdf	Export PDF report	Admin
GET	/api/health	Health check	Public

Full interactive documentation is available at /docs (Swagger UI) when the backend is running.

---

User Roles

Role	Permissions
Customer	Chat with the system, view own conversations, request escalation
Agent	View assigned tickets, respond to escalations, performance stats
Admin	Upload documents, view analytics, export reports, manage all data

---

Database

users ----< conversations ----< messages
  |                |
  |                +----< tickets
  |                         |
  +-------------------------+
  |
  +----< documents ----< document_chunks
  |
  +----< query_logs

7 tables managed through SQLAlchemy v2 with Alembic migrations.

---

Getting Started

Prerequisites

• Python 3.11+
• PostgreSQL 16+ (via Docker or local)
• Docker (for Qdrant)
• Ollama (local LLM server)

Setup

# Clone
git clone https://github.com/devshad-01/rag-customer-support.git
cd rag-customer-support

# Start PostgreSQL + Qdrant
docker compose up -d

# Pull the LLM model
ollama pull mistral

# Backend
cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env          # configure your credentials
alembic upgrade head
uvicorn app.main:app --reload --port 8000

Once running, verify at:

Service	URL
Backend API	http://localhost:8000/api/health
Swagger Docs	http://localhost:8000/docs

---

Testing

cd backend
source .venv/bin/activate
pytest -v

66 tests across 7 test modules covering authentication, documents, chat, tickets, analytics, reports, and health checks.

---

License

This project is for demonstration purposes only.

---

Built by devshad-01