Simple Chatbot with RAG

A real-time Django-based chatbot application with OpenAI integration and RAG (Retrieval-Augmented Generation) capabilities, supporting both text and voice chat functionality. Built with Django Channels for WebSocket communication and Celery for asynchronous task processing.

Features

• 🤖 AI-Powered Conversations: Integration with OpenAI GPT models for intelligent responses
• 📚 RAG Implementation: Retrieval-Augmented Generation for context-aware responses using vector database
• 💬 Real-time Chat: WebSocket-based communication for instant messaging
• 🎤 Voice Chat: Speech-to-text and text-to-speech functionality
• 📄 Document Management: Upload and index documents for knowledge base
• 🔍 Semantic Search: Vector-based similarity search for relevant content retrieval
• ☁️ S3 Integration: Cloud storage for document management
• 📱 Responsive UI: Clean, mobile-friendly interface built with Tailwind CSS
• ⚡ Asynchronous Processing: Celery-based background task handling
• 🗄️ Database Management: PostgreSQL with Django ORM
• 📊 Admin Interface: Django admin for managing bots, profiles, conversations, and documents
• 🔧 Configurable Bots: Multiple LLM providers and model configurations with RAG parameters
• 📈 Chat History: Persistent conversation storage and retrieval

Tech Stack

• Backend: Django 5.2.4, Django Channels, Django REST Framework
• Database: PostgreSQL
• Vector Database: External vector database service for RAG
• Storage: AWS S3 (via django-s3-storage)
• Message Broker: Redis
• Task Queue: Celery
• AI Integration: OpenAI API
• Frontend: HTML, JavaScript, Tailwind CSS
• WebSockets: Django Channels with Redis channel layer

Prerequisites

Before running this application, ensure you have the following installed:

• Python 3.8+
• PostgreSQL
• Redis Server
• OpenAI API Key
• Vector Database Service (for RAG functionality)
• AWS S3 Bucket (for document storage)

Installing Redis on Windows

For Windows users, you have several options:

1. WSL (Windows Subsystem for Linux) - Recommended
   • Install WSL2 and Ubuntu from Microsoft Store
   • Run sudo apt-get install redis-server in WSL
2. Redis for Windows (Community Edition)
   • Download from: https://github.com/microsoftarchive/redis/releases
   • Or use Memurai (Redis-compatible): https://www.memurai.com/

Installation

1. Clone the Repository

Unix/Linux/Mac:

git clone <repository-url>
cd simple_chatbot

Windows (Command Prompt/PowerShell):

git clone <repository-url>
cd simple_chatbot

2. Create Virtual Environment

Unix/Linux/Mac:

python -m venv venv
source venv/bin/activate

Windows (Command Prompt):

python -m venv venv
venv\Scripts\activate

Windows (PowerShell):

python -m venv venv
venv\Scripts\Activate.ps1

Note: If you encounter execution policy error in PowerShell, run:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

3. Install Dependencies

All Platforms:

pip install -r requirements.txt

4. Environment Configuration

Create a .env file in the root directory using the provided sample.env:

Unix/Linux/Mac:

cp sample.env .env

Windows (Command Prompt/PowerShell):

copy sample.env .env

Edit the .env file with your configuration:

# Database Configuration
DATABASE_NAME='your_database_name'
DATABASE_USER='your_database_user'
DATABASE_PASSWORD='your_database_password'
DATABASE_HOST='localhost'
DATABASE_PORT='5432'

# Django Settings
SETTINGS_DEBUG='True'
DJANGO_SETTINGS_MODULE='simple_chatbot.settings'
DEFAULT_LOG_LEVEL='INFO'

# OpenAI Configuration
OPENAI_API_KEY='your_openai_api_key'

# RAG & Vector Database Configuration
VECTOR_DB_BASE_URL='http://your-vector-db-url:port'
DATABASE_INTERFACE_BEARER_TOKEN='your_vector_db_auth_token'

# AWS S3 Configuration (for document storage)
S3_BASE_URL='https://your-bucket.s3.region.amazonaws.com/'
AWS_REGION='your-aws-region'
AWS_ACCESS_KEY_ID='your-aws-access-key'
AWS_SECRET_ACCESS_KEY='your-aws-secret-key'

5. Database Setup

Create a PostgreSQL database and run migrations:

All Platforms:

python manage.py makemigrations
python manage.py migrate

6. Create Superuser (Optional)

All Platforms:

python manage.py createsuperuser

7. Load Initial Data

Create initial profiles for the chatbot system:

All Platforms:

python manage.py shell

Then in the Python shell:

from chatbot.models import Profile, Bot

# Create AI profile (required - ID must be 1)
ai_profile = Profile.objects.create(
    id=1,
    first_name="AI Assistant",
    email="[email protected]",
    profile_type="MODERATOR"
)

# Create default user profile (ID must be 2)
user_profile = Profile.objects.create(
    id=2,
    first_name="User",
    email="[email protected]",
    profile_type="USER"
)

# Create a sample bot with RAG configuration
bot = Bot.objects.create(
    name="RAG Assistant",
    route="/",
    context="You are a helpful AI assistant with access to a knowledge base.",
    llm_model="gpt-4o-mini",
    top_k=3,  # Number of documents to retrieve
    filter_score=0.8,  # Minimum relevance score for documents
    bot_temperature=0.7,
    max_token=2048
)

# Exit the shell
exit()

Running the Application

1. Start Redis Server

Unix/Linux/Mac:

redis-server

Windows (if using WSL):

# In WSL terminal
sudo service redis-server start
# Or
redis-server

Windows (if using Redis for Windows):

# Navigate to Redis installation directory
redis-server.exe

2. Start Celery Worker

Open a new terminal/command prompt and activate virtual environment:

Unix/Linux/Mac:

source venv/bin/activate
celery -A simple_chatbot worker --loglevel=info --pool=solo

Windows (Command Prompt):

venv\Scripts\activate
celery -A simple_chatbot worker --loglevel=info --pool=solo

Windows (PowerShell):

venv\Scripts\Activate.ps1
celery -A simple_chatbot worker --loglevel=info --pool=solo

Note: The --pool=solo flag is important for Windows compatibility

3. Start Django Development Server

Open another new terminal/command prompt and activate virtual environment:

Unix/Linux/Mac:

source venv/bin/activate
python manage.py runserver 0.0.0.0:9000

Windows (Command Prompt):

venv\Scripts\activate
python manage.py runserver 0.0.0.0:9000

Windows (PowerShell):

venv\Scripts\Activate.ps1
python manage.py runserver 0.0.0.0:9000

The application will be available at http://localhost:9000

Usage

Text Chat with RAG

1. Navigate to http://localhost:9000/chat/
2. Enter your context/instructions in the right panel
3. Type your message and press Enter or click Send
4. The AI will respond using both its training and relevant documents from the knowledge base

Voice Chat

1. Navigate to http://localhost:9000/voice-chat/
2. Enter your context/instructions in the right panel
3. Click the "Speak" button and speak your message
4. The AI will respond with both text and speech

Document Management (RAG)

1. Access the Django admin at http://localhost:9000/admin/
2. Navigate to the Media section
3. Upload documents (PDF or TXT files)
4. Documents are automatically:
   • Stored in S3
   • Indexed in the vector database
   • Available for RAG queries

Admin Interface

Access the Django admin at http://localhost:9000/admin/ to:

• Bot Management: Configure bots with RAG parameters
  • top_k: Number of documents to retrieve
  • filter_score: Minimum relevance score (0-1)
  • context: System prompt for the bot
• Media Management: Upload and manage documents for the knowledge base
• Chat History: View all conversations
• Profile Management: Manage user profiles

RAG (Retrieval-Augmented Generation) System

How It Works

1. Document Upload: Documents are uploaded through the Media model
2. Storage: Files are stored in S3 with metadata
3. Indexing: Documents are automatically indexed in the vector database
4. Query Processing: User questions trigger semantic search
5. Context Retrieval: Relevant document chunks are retrieved
6. Response Generation: ChatGPT generates responses using retrieved context

Key RAG Components

• Media Model: Manages document storage and metadata
• MediaVector Model: Tracks vector database IDs
• KeyValue Model: Stores document metadata (author, category, etc.)
• Vector Database Integration: Semantic search and retrieval
• S3 Storage: Reliable document storage

RAG Configuration

Configure RAG behavior through Bot model settings:

bot = Bot.objects.create(
    name="Knowledge Bot",
    top_k=5,  # Retrieve top 5 relevant documents
    filter_score=0.75,  # Only use documents with >75% relevance
    context="Answer based on the provided documents only.",
    # ... other settings
)

Project Structure

simple_chatbot/
├── chatbot/                    # Main application
│   ├── admin.py               # Django admin configuration
│   ├── apps.py                # App configuration
│   ├── models/                # Database models
│   │   ├── __init__.py
│   │   ├── base_models.py     # Core models (Bot, Profile, Chat, Media)
│   │   └── enums.py           # Model choices and enums
│   ├── consumers/             # WebSocket consumers
│   │   ├── chat_consumers.py  # Basic chat consumer
│   │   └── company_chat_consumers.py  # RAG-enabled chat consumer
│   ├── celery_tasks/          # Background tasks
│   │   ├── chat_tasks.py      # Basic chat response processing
│   │   └── company_chat_tasks.py  # RAG-enhanced response processing
│   ├── utils/                 # Utility functions
│   │   └── chat_utils.py      # RAG utilities (vector DB operations)
│   ├── templates/             # HTML templates
│   │   ├── base.html
│   │   └── chat/
│   │       ├── chat.html      # Text chat interface
│   │       └── voice_demo.html # Voice chat interface
│   ├── migrations/            # Database migrations
│   ├── routing.py             # WebSocket URL routing
│   ├── urls.py                # HTTP URL patterns
│   └── views.py               # Django views
├── simple_chatbot/            # Project settings
│   ├── __init__.py
│   ├── asgi.py                # ASGI configuration
│   ├── celery.py              # Celery configuration
│   ├── settings.py            # Django settings
│   ├── urls.py                # Main URL configuration
│   └── wsgi.py                # WSGI configuration
├── manage.py                  # Django management script
├── requirements.txt           # Python dependencies
├── .gitignore                # Git ignore rules
└── sample.env                # Environment variables template

Models

Bot

Configurable AI bot with LLM provider settings, context management, response parameters, and RAG configuration.

Key RAG Fields:

• top_k: Number of documents to retrieve from vector database
• filter_score: Minimum relevance score for document inclusion
• context: System prompt with instructions for using retrieved documents

Profile

User profiles supporting different types (USER, MODERATOR, PROSPECT).

Chat

Chat message storage with sender/receiver relationships and session management.

Media

Document management for RAG system:

• File storage in S3
• Automatic vector database indexing
• Metadata support through KeyValue pairs

MediaVector

Tracks vector database IDs for indexed documents.

KeyValue

Flexible metadata storage for documents (author, category, tags, etc.).

API Endpoints

HTTP Endpoints

• /chat/ - Text chat interface
• /voice-chat/ - Voice chat interface
• /admin/ - Django admin interface

WebSocket Endpoints

• ws/chat/ - Basic WebSocket chat connection
• ws/chat/company/ - RAG-enabled WebSocket chat connection

Development

Adding New Features

1. Create new models in chatbot/models/
2. Add WebSocket consumers in chatbot/consumers/
3. Implement background tasks in chatbot/celery_tasks/
4. Create templates in chatbot/templates/
5. Add URL patterns in chatbot/urls.py

Working with RAG

To add documents to the knowledge base programmatically:

from chatbot.models import Media, KeyValue

# Upload a document
media = Media.objects.create(
    name="Product Documentation",
    media_type="application/pdf",
    file=your_file_object,
    description="Product user manual"
)

# Add metadata
KeyValue.objects.create(
    media=media,
    key="category",
    value="documentation"
)

# Document is automatically indexed in vector database

Database Migrations

After model changes:

All Platforms:

python manage.py makemigrations
python manage.py migrate

Testing

Run Django tests:

All Platforms:

python manage.py test

Troubleshooting

Common Issues

1. WebSocket Connection Failed

   • Ensure Redis server is running
   • Check CHANNEL_LAYERS configuration in settings.py
   • On Windows, ensure Redis is properly installed (WSL or Windows version)

2. Celery Tasks Not Processing

   • Verify Celery worker is running with --pool=solo flag on Windows
   • Check Redis connection
   • Ensure OPENAI_API_KEY is set

3. Database Connection Error

   • Verify PostgreSQL server is running
   • Check database credentials in .env file
   • Ensure database exists

4. OpenAI API Errors

   • Verify API key is valid and has sufficient credits
   • Check rate limits and usage quotas

5. Vector Database Issues

   • Verify VECTOR_DB_BASE_URL is correct
   • Check DATABASE_INTERFACE_BEARER_TOKEN is valid
   • Ensure vector database service is running

6. S3 Upload Errors

   • Verify AWS credentials in .env
   • Check S3 bucket permissions
   • Ensure bucket exists in specified region

7. Windows-Specific Issues

   • PowerShell Execution Policy: Run Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
   • Path Issues: Use forward slashes (/) in .env file paths even on Windows
   • Celery: Always use --pool=solo flag on Windows

Logs

• Django logs: Check console output
• Celery logs: Available in Celery worker terminal
• Redis logs: Check Redis server logs (WSL or Windows Redis logs)
• Vector DB logs: Check vector database service logs

Production Deployment

For production deployment:

1. Set DEBUG=False in settings
2. Configure proper database settings
3. Use a production ASGI server (e.g., Daphne, Uvicorn)
4. Set up Redis with proper persistence
5. Configure Celery with supervisor (Linux) or Task Scheduler (Windows)
6. Use environment variables for sensitive settings
7. Set up proper logging and monitoring
8. Configure S3 bucket with appropriate security policies
9. Ensure vector database has proper scaling and backup

RAG Performance Optimization

• Indexing: Ensure documents are properly chunked before indexing
• Relevance Tuning: Adjust filter_score based on your use case
• Retrieval Count: Balance top_k between context quality and response time
• Caching: Consider caching frequent queries
• Document Quality: Ensure uploaded documents are clean and well-structured