Local LLM Chat Interface 🤖✨

A modern, feature-rich chat interface for interacting with local LLM backends like Ollama and LM Studio. Built with React, TypeScript, and FastAPI, featuring persistent chat sessions, MongoDB storage, RAG (Retrieval-Augmented Generation), web search, and a beautiful animated UI.

!Version
!License
!Python
!React
!MongoDB

✨ What This App Does

This is an intelligent chat application that lets you interact with powerful local AI models (like Llama, Gemma, Qwen) running on your own machine. Think ChatGPT, but completely private, customizable, and running locally.

$3

- 💬 Persistent Chat Sessions - ChatGPT-style interface with session management and smart auto-titles
- 📚 Knowledge Base (RAG) - Upload documents (PDF, DOCX, TXT) and ask questions with MongoDB persistence
- 🌐 Web Search - Get real-time information from the internet with citations
- 🎨 Beautiful UI - Smooth animations, gradient effects, file cards, and modern design
- 🔧 Full Control - Choose your AI model, toggle tools on/off, manage files per session
- 🔒 100% Private - Everything runs locally on your machine with MongoDB for data storage

🚀 Features

$3

- ChatGPT-Style Interface - Sidebar with session history organized by time (Today, Yesterday, This Week, Older)
- Smart Auto-Titles - AI generates 3-4 word titles after first exchange based on conversation context
- MongoDB Storage - All conversations, messages, and files persist across sessions
- Session Management - Create, view, delete sessions with full conversation history
- Session-Based File Uploads - Files are linked to specific chat sessions with metadata tracking

$3

- Ollama - Run models like Llama, Gemma, Qwen, DeepSeek locally
- LM Studio - Desktop LLM interface with OpenAI-compatible API
- Dynamic Model Selection - Interactive dropdowns to switch backends and models
- Auto-Discovery - Automatically detects available models from your LLM backend
- Unified Sidebar - Backend selector, model selector, and tools all in one place

$3

- Full Session History - Remembers entire conversation within a session
- Intelligent Context - Uses last 10 messages for AI context
- Message Persistence - All messages stored in MongoDB with timestamps
- Smart Title Generation - Asynchronous title generation using LLM after first exchange

$3

- 🔍 Web Search - Powered by Serper.dev (Google search API)
- 📚 RAG (Document Q&A) - Ask questions about uploaded documents with persistent storage
- 🧪 Deep Research - Multi-step iterative reasoning
- 📊 Real-time Stats - Token counting and latency tracking

$3

- File Cards Display - ChatGPT-style file cards showing uploaded documents in chat
- MongoDB Persistence - File chunks and embeddings stored in MongoDB for permanent access
- Session-Specific Files - Each session maintains its own file collection
- File Metadata - Track filename, size, upload time, embedding status, and chunk count
- Automatic Processing - Files are chunked, embedded, and stored automatically on upload
- Multi-Format Support - PDF, DOCX, TXT with intelligent text extraction
- Vector Search - Semantic search across uploaded documents using embeddings

$3

- ✨ Spring Animations - Smooth Framer Motion physics
- 🌈 Gradient Backgrounds - Dynamic color schemes for messages
- 💎 Glassmorphism Effects - Frosted glass aesthetics
- 📇 File Cards - Visual display of uploaded files with icons, size, and chunk info
- 🎭 Loading Indicators - Shows KB search, web search, and generation status
- 📱 Responsive Design - Works on desktop and mobile
- 🕒 Time-Based Grouping - Sessions organized by Today, Yesterday, This Week, Older

🚀 Quick Start

$3

We provide automated setup scripts for all platforms that install everything and launch the app automatically:

#### Windows (Batch Script)

``cmd
setup-and-run.bat
`

- Double-click setup-and-run.bat or run in Command Prompt
- Automatically installs: MongoDB, Node.js, Python 3.11, Ollama
- Sets up backend and frontend dependencies
- Launches all services in separate windows

#### Windows/Linux/macOS (PowerShell)

`powershell
pwsh setup-and-run.ps1
`

- Cross-platform PowerShell script
- Works on Windows, Linux, macOS
- Same functionality as batch script
- Requires PowerShell 7+ (pre-installed on Windows 10+)

#### Linux/macOS (Bash Script)

`bash
chmod +x setup-and-run.sh
./setup-and-run.sh
`

- Native bash script for Unix systems
- Automatically detects Ubuntu/Debian/CentOS/macOS
- Uses system package managers (apt, yum, brew)
- Starts all services automatically

What the scripts do:

1. ✅ Check if MongoDB, Node.js, Python, Ollama are installed
2. ✅ Install missing prerequisites automatically
3. ✅ Create Python virtual environment
4. ✅ Install all dependencies (pip, npm)
5. ✅ Create .env from example if missing
6. ✅ Start MongoDB service
7. ✅ Start Ollama service
8. ✅ Pull default model (gemma2:2b)
9. ✅ Launch backend (FastAPI) in new terminal
10. ✅ Launch frontend (Vite) in new terminal
11. ✅ Log everything to logs/ directory

After running: Just wait ~30 seconds and open http://localhost:5173

---

$3

If you prefer to install everything manually, follow the detailed instructions below.

$3

Before you begin, make sure you have:

1. Node.js 18+ - Download here
2. Python 3.11+ - Download here
3. MongoDB 7.0+ - Download here
- Or use MongoDB Atlas (free cloud tier) - Sign up here
4. Ollama (recommended) - Download here
- Or LM Studio - Download here
5. Git - Download here

$3

#### Option 1: Local MongoDB (Recommended for Development)

Windows:

`bash


Download MongoDB Community Server from mongodb.com

Install with default settings

MongoDB will run as a Windows service automatically

Verify it's running

mongosh

You should see: "Connected to: mongodb://127.0.0.1:27017"

`

macOS (using Homebrew):

`bash


Install MongoDB

brew tap mongodb/brew
brew install mongodb-community@7.0

Start MongoDB service

brew services start mongodb-community@7.0

Verify it's running

mongosh
`

Linux (Ubuntu/Debian):

`bash


Import MongoDB public key

wget -qO - https://www.mongodb.org/static/pgp/server-7.0.asc | sudo apt-key add -

Add MongoDB repository

echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/7.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list

Install MongoDB

sudo apt-get update
sudo apt-get install -y mongodb-org

Start MongoDB service

sudo systemctl start mongod
sudo systemctl enable mongod

Verify it's running

mongosh
`

#### Option 2: MongoDB Atlas (Cloud - Free Tier)

1. Sign up at mongodb.com/cloud/atlas/register
2. Create a free cluster (M0 tier - no credit card required)
3. Create a database user with read/write permissions
4. Whitelist your IP or use 0.0.0.0/0 for development
5. Get connection string from "Connect" → "Connect your application"
6. Copy the connection string (looks like: mongodb+srv://user:password@cluster.mongodb.net/)

#### Verify MongoDB Installation

`bash


Test local MongoDB connection

mongosh

Or test with connection string

mongosh "mongodb://127.0.0.1:27017"

Should see:

Current Mongosh Log ID: ...

Connecting to: mongodb://127.0.0.1:27017

Using MongoDB: 7.0.x

`

$3

#### 1. Clone the Repository

`bash
git clone https://github.com/lebiraja/plugin.git
cd plugin
`

#### 2. Set Up the Backend

`bash


Navigate to backend folder

cd backend

Create a virtual environment

python -m venv venv

Activate virtual environment

On Windows:

.\venv\Scripts\activate

On macOS/Linux:

source venv/bin/activate

Install dependencies (using uv for faster installs, or use pip)

pip install uv
uv pip install -r requirements.txt

Or with regular pip:

pip install -r requirements.txt
`

#### 3. Configure Environment Variables

`bash


Copy the example .env file

cp .env.example .env

Edit .env and configure MongoDB and other settings

`

Your backend/.env should look like:

`env


MongoDB Configuration

MONGODB_URL=mongodb://127.0.0.1:27017 # Local MongoDB

Or for MongoDB Atlas:

MONGODB_URL=mongodb+srv://username:password@cluster.mongodb.net/?retryWrites=true&w=majority

MONGODB_DB_NAME=chat_app # Database name (will be created automatically)

Backend Configuration

OLLAMA_URL=http://127.0.0.1:11434
LMSTUDIO_URL=http://localhost:1234

Web Search API (100 free searches/month)

SERPER_API_KEY=your_serper_api_key_here

Vector Database (ChromaDB - local storage)

VECTOR_DB_PATH=./vector_db

File Upload

UPLOAD_DIR=./uploads
MAX_FILE_SIZE=10485760 # 10MB in bytes

CORS

CORS_ORIGINS=http://localhost:3000,http://localhost:5173

Server

HOST=0.0.0.0
PORT=8000
`

Important MongoDB Notes:

- For local MongoDB: Use mongodb://127.0.0.1:27017
- For MongoDB Atlas: Use your connection string from Atlas dashboard
- The database (chat_app) and collections will be created automatically
- Indexes are created automatically on first startup

#### 4. Set Up the Frontend

`bash


Go back to project root

cd ..

Install frontend dependencies

npm install
`

#### 5. Install and Configure Ollama

`bash


Download Ollama from https://ollama.ai/

Pull some models (examples)

ollama pull gemma2:2b # Small, fast model
ollama pull llama3.1:8b # Balanced model
ollama pull qwen2.5-coder:3b # Great for coding

Start Ollama (it usually runs automatically)

ollama serve
`

$3

#### Method 1: Separate Terminals (Recommended for Development)

Terminal 1 - Start MongoDB (if using local):

`bash


Windows (if not running as service)

"C:\Program Files\MongoDB\Server\7.0\bin\mongod.exe" --dbpath="C:\data\db"

macOS/Linux (if not running as service)

sudo systemctl start mongod # Linux

or

brew services start mongodb-community@7.0 # macOS
`

Terminal 2 - Backend:

`bash
cd backend
.\venv\Scripts\activate # Windows


or

source venv/bin/activate # macOS/Linux

Start backend server with auto-reload

uvicorn main:app --reload --host 0.0.0.0 --port 8000

You should see:

INFO: Connected to MongoDB: chat_app

INFO: Application startup complete

`

Terminal 3 - Frontend:

`bash


From project root

npm run dev

You should see:

VITE v5.4.x ready in xxx ms

➜ Local: http://localhost:5173/

`

#### Method 2: Production Mode

`bash


Build frontend

npm run build

Start backend (serves both API and static frontend)

cd backend
python main.py
`

$3

Open your browser and go to:

`
http://localhost:5173 # Development mode


or


http://localhost:8000 # Production mode
`

📖 How to Use

$3

1. Start MongoDB - Make sure MongoDB is running (locally or Atlas connection)
2. Start Backend - Run uvicorn main:app --reload from backend/ directory
3. Start Frontend - Run npm run dev from project root
4. Open the app - Navigate to http://localhost:5173
5. Select Backend - Click backend dropdown in the left sidebar and choose "Ollama" or "LM Studio"
6. Choose Model - Select a model from the model dropdown (auto-populates from your LLM backend)
7. Start Chatting! - Type a message and press Enter

$3

The app now features persistent chat sessions similar to ChatGPT:

Creating Sessions:

- Click "+ New Chat" button to start a fresh conversation
- Each session gets a unique ID and is stored in MongoDB
- Sessions automatically get smart titles after the first exchange

Session History:

- Left sidebar shows all your chat sessions organized by time:
- Today - Sessions created today
- Yesterday - Sessions from yesterday
- This Week - Sessions from the past 7 days
- Older - Sessions older than a week
- Click any session to load its full conversation history

Smart Auto-Titles:

- After your first message and AI response, the session automatically gets a 3-4 word title
- Title is generated by the AI based on the conversation context
- Example: "Python Programming Help" or "Database Design Questions"

Session Management:

- Hover over a session to see the delete button
- Delete unwanted sessions (permanently removes from MongoDB)
- Sessions persist across browser refreshes and app restarts

$3

The app automatically remembers your conversation:

`
You: My name is Alex and I love Python programming.
AI: Nice to meet you, Alex! Python is a great language...

You: What's my name?
AI: Your name is Alex!

You: What language did I mention?
AI: You mentioned that you love Python programming!
`

- Full Session History - All messages in a session are stored in MongoDB
- Intelligent Context - AI uses last 10 messages for generating responses
- Persistent Storage - Conversations survive server restarts and browser refreshes

$3

In the left sidebar, click the tool buttons to enable/disable:

- RAG - For uploaded document Q&A (blue when active)
- Web Search - For current information (blue when active)
- Deep Research - For complex multi-step reasoning (blue when active)

Tools are session-specific and persist with your session settings.

$3

Upload Files:

1. Click paperclip icon 📎 in the chat input area
2. Select files - PDF, DOCX, or TXT (max 10MB per file)
3. Files are processed - Automatically chunked, embedded, and stored in MongoDB
4. File cards appear - See your uploaded files displayed as cards in the chat

File Cards Display:

- Each uploaded file shows as a card with:
- 📄 File icon (color-coded by type)
- 📝 Filename
- 📊 File size (formatted in KB/MB)
- 🧩 Chunk count (number of text chunks created)
- Files are organized in a "Knowledge Base" section above the chat input

Query Documents:

1. Enable RAG - Click the RAG button in left sidebar (turns blue)
2. Ask questions - "What are the main points in the document?"
3. Get contextualized answers - AI uses relevant chunks from your files
4. See sources - Citations show which file chunks were used

File Persistence:

- Files are linked to specific chat sessions
- File metadata and embeddings stored in MongoDB
- Files persist across sessions and app restarts
- Each session has its own file collection

$3

1. Get Serper API Key - Free 100 searches/month at serper.dev
2. Add to .env - Put key in backend/.env as SERPER_API_KEY
3. Enable Tool - Click "Web Search" button in left sidebar (turns blue)
4. Ask Current Events - "What's the latest news about AI?"
5. See Citations - Sources shown in right sidebar

$3

Right sidebar shows session statistics:

- 📊 Message count - Total messages in current session
- 📝 Token usage - Estimated tokens used
- 📁 Files uploaded - Number of files in knowledge base
- 🔗 Context sources - Citations from RAG/web search
- 🕒 Session created - Timestamp of session creation

🏗️ Architecture

$3

- React 18.3 - Modern UI library with hooks
- TypeScript 5.5 - Type-safe JavaScript
- Vite 5.4 - Lightning-fast build tool
- Framer Motion 11.5 - Smooth spring animations
- Zustand 4.5 - Lightweight state management
- Axios - HTTP client for API calls
- React Markdown - Beautiful markdown rendering with syntax highlighting
- React Router - Session-based routing (/chat/:sessionId)

$3

- FastAPI 0.115 - High-performance async Python API
- MongoDB (Motor 3.6) - Async MongoDB driver for Python
- Collections: chat_sessions (sessions & messages), knowledge_base (RAG chunks)
- Indexes: Optimized for session_id, file_id, timestamps
- ChromaDB 0.5.15 - Vector database for embeddings (local storage)
- sentence-transformers 3.0 - nomic-ai/nomic-embed-text-v1.5 (547MB)
- httpx 0.27 - Async HTTP client
- pypdf, python-docx - Document processing (PDF, DOCX, TXT)
- duckduckgo-search - Fallback web search
- Serper.dev - Primary web search (Google results)

$3

- Ollama API - Local model serving (127.0.0.1:11434)
- LM Studio - OpenAI-compatible API (localhost:1234)
- Custom backends - Bring your own API

$3

MongoDB Collections:

`javascript
// chat_sessions collection
{
session_id: string (UUID),
title: string (auto-generated),
backend: string,
model: string,
created_at: datetime,
updated_at: datetime,
messages: [
{
role: "user" | "assistant",
content: string,
timestamp: datetime,
tokens: number (optional),
sources: array (optional)
}
],
files: [
{
file_id: string (UUID),
filename: string,
file_path: string,
size: number,
uploaded_at: datetime,
embedded: boolean,
chunks: number
}
],
config: {
temperature: float,
topP: float,
maxTokens: int
}
}

// knowledge_base collection
{
file_id: string,
session_id: string,
chunk_text: string,
chunk_index: number,
embedding: array,
metadata: {
source: string,
chunk_index: number,
total_chunks: number
},
created_at: datetime
}
`

Indexes:

- chat_sessions: session_id, created_at, updated_at
- knowledge_base: file_id, session_id, created_at, compound(session_id + file_id)

📁 Project Structure

`
plugin/
├── src/ # Frontend source
│ ├── components/
│ │ ├── ChatInterface.tsx # Main chat with session management & file cards
│ │ ├── SessionSidebar.tsx # Unified sidebar (history, backend, model, tools)
│ │ ├── RightSidebar.tsx # Stats & session info
│ │ ├── MessageList.tsx # Animated message display
│ │ ├── FileCard.tsx # File card component (NEW!)
│ │ └── FileUpload.tsx # Drag & drop file upload
│ ├── store/
│ │ ├── chatStore.ts # Conversation state
│ │ └── settingsStore.ts # App configuration
│ ├── api/
│ │ ├── chat.ts # Chat API (legacy)
│ │ ├── sessions.ts # Session management API (NEW!)
│ │ ├── models.ts # Model fetching
│ │ └── files.ts # File upload/delete
│ └── index.css # Global styles & animations
├── backend/
│ ├── routers/
│ │ ├── sessions.py # Session CRUD & messaging (NEW!)
│ │ ├── chat.py # Legacy chat endpoint
│ │ ├── models.py # Model listing (Ollama/LM Studio)
│ │ ├── files.py # File upload/delete/list
│ │ └── tools.py # RAG & web search endpoints
│ ├── services/
│ │ ├── session_service.py # Session business logic (NEW!)
│ │ ├── database_service.py # MongoDB connection & schema (NEW!)
│ │ ├── llm_service.py # LLM backend abstraction with memory
│ │ ├── search_service.py # Serper.dev + DuckDuckGo fallback
│ │ ├── rag_service.py # Vector search & MongoDB storage (UPDATED!)
│ │ └── document_processor.py # File parsing & embedding
│ ├── main.py # FastAPI app with CORS & MongoDB startup
│ ├── requirements.txt # Python dependencies
│ ├── .env.example # Environment template
│ └── .env # Your config (not committed)
├── public/ # Static assets
├── package.json # Node dependencies
└── README.md # This file
`

⚙️ Configuration Files

$3

Located in backend/.env (create from .env.example):

`env


MongoDB Configuration (Required)

MONGODB_URL=mongodb://127.0.0.1:27017

For MongoDB Atlas cloud:

MONGODB_URL=mongodb+srv://username:password@cluster.mongodb.net/?retryWrites=true&w=majority

MONGODB_DB_NAME=chat_app # Database name (auto-created)

LLM Backend URLs

OLLAMA_URL=http://127.0.0.1:11434
LMSTUDIO_URL=http://localhost:1234

Web Search API (Required for web search tool)

Get free key at: https://serper.dev/api-keys

SERPER_API_KEY=your_serper_api_key_here

Vector Database (ChromaDB - local file storage)

VECTOR_DB_PATH=./vector_db

File Upload

UPLOAD_DIR=./uploads
MAX_FILE_SIZE=10485760 # 10MB in bytes

CORS (frontend URLs)

CORS_ORIGINS=http://localhost:3000,http://localhost:5173

Server

HOST=0.0.0.0
PORT=8000
`

$3

All settings are now stored in MongoDB per session:

- Selected backend and model (per session)
- Tool toggles (RAG, web search, deep research)
- Conversation history (messages array)
- File list (session-specific files)
- Session metadata (title, timestamps)

To reset: Delete sessions via UI or MongoDB directly

🔧 Advanced Usage

$3

The backend exposes a RESTful API for session management:

#### Session Endpoints

`bash


Create new session

POST /api/sessions
Body: {
"backend": "ollama",
"model": "gemma2:2b",
"config": {
"temperature": 0.7,
"topP": 0.9,
"maxTokens": 2048
}
}

Get all sessions (with time grouping)

GET /api/sessions

Get specific session

GET /api/sessions/{session_id}

Delete session (removes all messages and files)

DELETE /api/sessions/{session_id}

Send message to session

POST /api/sessions/{session_id}/message
Body: {
"message": "Hello, how are you?",
"config": { ... } # Optional
}

Upload file to session

POST /api/sessions/{session_id}/upload
Body: multipart/form-data with file

Get session files

GET /api/sessions/{session_id}/files
`

#### Model Endpoints

`bash


List Ollama models

GET /api/models/ollama

List LM Studio models

GET /api/models/lmstudio
`

$3

Accessing data directly:

`javascript
// Connect to MongoDB
mongosh "mongodb://127.0.0.1:27017"

// Switch to chat database
use chat_app

// List all sessions
db.chat_sessions.find({})

// Find session by ID
db.chat_sessions.findOne({session_id: "your-session-id"})

// Count total messages across all sessions
db.chat_sessions.aggregate([
{$unwind: "$messages"},
{$count: "total_messages"}
])

// Find sessions created today
db.chat_sessions.find({
created_at: {
$gte: new Date(new Date().setHours(0,0,0,0))
}
})

// Get all file chunks for a session
db.knowledge_base.find({session_id: "your-session-id"})

// Count total chunks
db.knowledge_base.countDocuments()

// Delete old sessions (older than 30 days)
db.chat_sessions.deleteMany({
created_at: {
$lt: new Date(Date.now() - 302460601000)
}
})
`

$3

Models use these default parameters (can be modified per message):

`typescript
{
temperature: 0.7, // Creativity (0.0 = focused, 1.0 = creative)
topP: 0.9, // Nucleus sampling
maxTokens: 2048, // Maximum response length
frequencyPenalty: 0.0, // Reduce repetition
presencePenalty: 0.0 // Encourage new topics
}
`

$3

Edit src/store/settingsStore.ts:

`typescript
backends: [
{
id: "ollama",
name: "Ollama",
url: "http://127.0.0.1:11434",
type: "ollama",
isActive: true,
},
{
id: "custom",
name: "My Custom Backend",
url: "https://my-api.example.com",
type: "openai", // Use OpenAI-compatible format
apiKey: "optional-key",
isActive: true,
},
];
`

$3

The app uses nomic-ai/nomic-embed-text-v1.5 (547MB, excellent quality).

To use a different model, edit backend/services/document_processor.py:

`python
from sentence_transformers import SentenceTransformer

self.embedding_model = SentenceTransformer('your-model-name')
`

🎨 UI Customization

$3

Edit src/components/MessageList.tsx:

`typescript
animate={{ opacity: 1, y: 0 }}
transition={{
type: "spring",
stiffness: 100, // Lower = slower bounce
damping: 15 // Higher = less bounce
}}
`

$3

Edit src/index.css:

`css
.assistant-message {
background: linear-gradient(
135deg,
rgba(59, 130, 246, 0.1),
/ Adjust colors / rgba(147, 51, 234, 0.1)
);
}
`

🐛 Troubleshooting

$3

#### Script execution disabled (PowerShell)

Problem: setup-and-run.ps1 cannot be loaded because running scripts is disabled

Solution:

`powershell


Run PowerShell as Administrator

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

Then run the script again

pwsh setup-and-run.ps1
`

#### Permission denied (Linux/macOS)

Problem: bash: ./setup-and-run.sh: Permission denied

Solution:

`bash
chmod +x setup-and-run.sh
./setup-and-run.sh
`

#### Script hangs during installation

Problem: Script appears stuck during MongoDB/Ollama installation

Solution:

- Check logs/setup_*.log for detailed error messages
- Ensure you have internet connection
- Run with administrator/sudo privileges if needed
- Manually install the stuck component and rerun script

#### Services won't start

Problem: MongoDB or Ollama service fails to start

Solution:

`bash


Check if ports are already in use

Windows:

netstat -ano | findstr :27017
netstat -ano | findstr :11434

Linux/macOS:

lsof -i :27017
lsof -i :11434

Kill processes using the ports if needed

`

$3

Problem: Failed to connect to MongoDB error on startup

Solution:

`bash


Check if MongoDB is running

mongosh

Start MongoDB service

Windows:

net start MongoDB

macOS:

brew services start mongodb-community@7.0

Linux:

sudo systemctl start mongod

For MongoDB Atlas:

- Check connection string in .env

- Verify IP whitelist in Atlas dashboard

- Check username/password are correct

`

$3

Problem: ModuleNotFoundError or import errors

Solution:

`bash
cd backend
.\venv\Scripts\activate
pip install -r requirements.txt

If still failing, reinstall dependencies:


pip install --upgrade -r requirements.txt
`

$3

Problem: Model dropdown is empty

Solution:

1. Make sure Ollama is running: ollama serve
2. Pull at least one model: ollama pull gemma2:2b
3. Check Ollama URL in .env: OLLAMA_URL=http://127.0.0.1:11434
4. Click the refresh button (🔄) next to model selector
5. Check browser console for API errors

$3

Problem: Chat sessions disappear after refresh

Solution:

1. Verify MongoDB is running: mongosh
2. Check MONGODB_URL in backend/.env
3. Look for connection errors in backend logs
4. Test MongoDB connection: mongosh "mongodb://127.0.0.1:27017"
5. Check database exists: In mongosh, run show dbs

$3

Problem: Files don't upload or process

Solution:

1. Check file size (default max: 10MB)
2. Ensure backend/uploads/ directory exists
3. Check backend logs for errors
4. Supported formats: PDF, DOCX, TXT
5. Make sure session exists before uploading
6. Check MongoDB knowledge_base collection for chunks

$3

Problem: "what is in the file" doesn't use document content

Solution:

1. Ensure RAG toggle is ON (blue) in left sidebar
2. Check that file was uploaded successfully (file card appears)
3. Wait for embedding to complete (check embedded: true in file metadata)
4. Verify chunks were created in MongoDB:
`javascript
// In mongosh:
use chat_app
db.knowledge_base.find({session_id: "your-session-id"})
`
5. Check backend logs for RAG processing errors

$3

Problem: "Web Search Unavailable" message

Solution:

1. Get free API key from serper.dev
2. Add to backend/.env: SERPER_API_KEY=your_key_here
3. Restart backend server
4. Enable "Web Search" toggle in left sidebar (turns blue)
5. Check backend logs for API errors

$3

Problem: Uploaded files don't display as cards

Solution:

1. Check that file upload completed successfully
2. Verify session has files array in MongoDB:
`javascript
// In mongosh:
use chat_app
db.chat_sessions.findOne({session_id: "your-session-id"})
`
3. Refresh the chat session
4. Check browser console for React errors

$3

Problem: AI doesn't remember previous messages in session

Solution:

- This is built-in now! Uses full session history from MongoDB
- Make sure you're in the same session (check session_id in URL)
- Check MongoDB for messages: db.chat_sessions.findOne({session_id: "..."})
- Backend uses last 10 messages for context automatically
- Check browser console for errors

$3

Problem: Sessions show as "New Chat" instead of AI-generated titles

Solution:

1. Title generates after first message exchange (user + assistant)
2. Check backend logs for title generation errors
3. Make sure LLM backend is responding correctly
4. Title generation is async - may take a few seconds
5. Check MongoDB: db.chat_sessions.findOne({session_id: "..."}) for title field

$3

Problem: Changes don't appear after updates

Solution:

`bash


Hard refresh

Ctrl + F5 (Windows)
Cmd + Shift + R (Mac)

Or clear cache

Browser DevTools → Application → Clear storage

Or rebuild

npm run build
`

🛠️ Development

$3

`bash
cd backend
pytest
`

$3

`bash
npm run dev
`

$3

`bash
npm run build
cd backend
python main.py # Serves built frontend + API
`

$3

`bash


Frontend

npm run lint

Backend

cd backend
black .
flake8 .
`

$3

Both frontend (Vite) and backend (uvicorn --reload) support hot reloading in development mode.

📊 Performance Tips

1. Use smaller models for speed - gemma2:2b is very fast
2. Limit conversation history - Uses last 10 messages for context (configurable)
3. Chunk large documents - Files are auto-chunked to 512 characters
4. Use RAG only when needed - Toggle off when not querying docs
5. Web search is rate-limited - Serper.dev offers 100 free searches/month
6. MongoDB indexes - Automatically created for optimal query performance
7. Clean old sessions - Periodically delete unused sessions to save space
8. Local MongoDB - Use local MongoDB for best performance vs Atlas cloud
9. File size limits - Keep files under 10MB for faster processing
10. GPU acceleration - RAG embedding uses GPU if available (CUDA)

🔒 Privacy & Security

- ✅ 100% Local Processing - All AI inference happens on your machine
- ✅ Local Data Storage - MongoDB can run locally, no cloud required
- ✅ No Data Sent to Cloud - Except web search queries (via Serper.dev) and if using MongoDB Atlas
- ✅ API Keys Protected - .env file not committed to Git
- ✅ CORS Configured - Only allows localhost origins
- ✅ Session Isolation - Each session has its own files and context
- ✅ No Analytics - No tracking or telemetry sent anywhere
- ⚠️ Development Mode - Not hardened for public deployment
- 💡 MongoDB Options:
- Local MongoDB: Complete privacy, all data on your machine
- MongoDB Atlas: Convenient cloud option, data encrypted at rest and in transit

🤝 Contributing

Contributions are welcome! Here's how:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature`
5. Open a Pull Request

$3

- Follow TypeScript/Python best practices
- Add comments for complex logic
- Test before submitting
- Update README if adding features

📄 License

This project is licensed under the MIT License - see LICENSE file for details.

🙏 Acknowledgments

- Ollama Team - Amazing local LLM runtime
- FastAPI - High-performance Python framework
- Framer Motion - Beautiful React animations
- ChromaDB - Excellent vector database
- Serper.dev - Reliable Google search API
- Nomic AI - High-quality embedding models
- Open Source Community - For all the incredible tools

📧 Support & Contact

- Issues - GitHub Issues
- Discussions - GitHub Discussions

🗺️ Roadmap

Future features planned:

- [ ] Multi-modal support (image input)
- [ ] Voice chat integration
- [ ] Custom prompt templates
- [ ] Conversation export/import (JSON, Markdown)
- [ ] Advanced RAG with re-ranking
- [x] Multiple conversation threads (✅ Implemented v2.0)
- [x] MongoDB persistent storage (✅ Implemented v2.0)
- [ ] Conversation search and filtering
- [ ] Session sharing and collaboration
- [ ] File version control in knowledge base
- [ ] Plugin system for extensions
- [ ] Mobile app (React Native)
- [ ] Batch file uploads
- [ ] Advanced analytics dashboard

📝 Changelog

$3

- ✅ Persistent Chat Sessions - MongoDB-backed session management
- ✅ ChatGPT-Style Interface - Session history sidebar with time-based grouping
- ✅ Smart Auto-Titles - AI generates 3-4 word titles after first exchange
- ✅ File Cards Display - ChatGPT-style file cards in chat interface
- ✅ MongoDB Knowledge Base - Persistent RAG chunks storage
- ✅ Session-Based Files - Files linked to specific sessions
- ✅ Unified Sidebar - Backend, model, and tools in one sidebar
- ✅ Enhanced RAG Service - MongoDB storage with automatic text extraction
- ✅ File Metadata Tracking - Track embedded status, chunk count, file size
- ✅ Async Title Generation - Non-blocking title creation
- ✅ Session CRUD API - Full REST API for session management
- ✅ Database Indexes - Optimized queries for sessions and files

$3

- ✅ Interactive model selector with auto-fetch
- ✅ Conversation memory (last 10 messages)
- ✅ Interactive tool toggle buttons
- ✅ Knowledge base file management with delete
- ✅ Enhanced UI with spring animations
- ✅ Web search via Serper.dev
- ✅ RAG with nomic-embed-text-v1.5
- ✅ Loading status indicators
- ✅ Glassmorphism design
- ✅ Gradient message backgrounds
- ✅ Citation display for sources

---

Made with ❤️ by lebiraja

_Star ⭐ this repo if you find it helpful!_