npm package: @lebiraja/plugintool
Description: Modern local LLM chat interface with Apple-inspired UI - React components for building AI chat applications
Author: lebiraja
Latest version: 1.0.0

# 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](https://img.shields.io/badge/version-2.0.0-blue.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)
![Python](https://img.shields.io/badge/python-3.11+-blue.svg)
![React](https://img.shields.io/badge/react-18.3+-61dafb.svg)
![MongoDB](https://img.shields.io/badge/mongodb-7.0+-47A248.svg)

## ✨ 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**.

### Key Capabilities:

- 💬 **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

### 💾 Persistent Chat Sessions (NEW!)

- **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

### 🤖 Multi-Backend LLM Support

- **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

### 🧠 Advanced Conversation Memory

- **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

### 🛠️ Powerful Tools (Toggle On/Off)

- 🔍 **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

### 📁 Enhanced Knowledge Base Management (NEW!)

- **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

### 🎨 Modern UI/UX

- ✨ **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

### 🎯 Automated Setup (Recommended!)

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

---

### Manual Setup (If you prefer step-by-step)

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

### Prerequisites

Before you begin, make sure you have:

1. **Node.js 18+** - [Download here](https://nodejs.org/)
2. **Python 3.11+** - [Download here](https://www.python.org/downloads/)
3. **MongoDB 7.0+** - [Download here](https://www.mongodb.com/try/download/community)
   - Or use **MongoDB Atlas** (free cloud tier) - [Sign up here](https://www.mongodb.com/cloud/atlas/register)
4. **Ollama** (recommended) - [Download here](https://ollama.ai/)
   - Or **LM Studio** - [Download here](https://lmstudio.ai/)
5. **Git** - [Download here](https://git-scm.com/)

### MongoDB Setup

#### 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](https://www.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
```

### Installation

#### 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
```

### Running the Application

#### 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
```

### Access the App

Open your browser and go to:

```
http://localhost:5173  # Development mode
# or
http://localhost:8000  # Production mode
```

## 📖 How to Use

### 1. First Time Setup

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

### 2. Chat Sessions (ChatGPT-Style)

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. Using Conversation Memory

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

### 4. Toggle Tools On/Off

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.

### 5. Upload and Query Documents (Enhanced with File Cards!)

**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

### 6. Web Search

1. **Get Serper API Key** - Free 100 searches/month at [serper.dev](https://serper.dev/api-keys)
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

### 7. View Statistics

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

### Frontend Stack

- **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`)

### Backend Stack

- **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)

### LLM Integrations

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

### Database Schema

**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<float>,
  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

### Backend `.env` Configuration

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
```

### Frontend Configuration

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

### API Endpoints

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
```

### MongoDB Collections

**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() - 30*24*60*60*1000)
  }
})
```

### Custom Model Parameters

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
}
```

### Adding More Backends

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,
  },
];
```

### Customizing Embeddings

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

### Animation Speeds

Edit `src/components/MessageList.tsx`:

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

### Color Schemes

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

### Automated Setup Script Issues

#### **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
```

### MongoDB connection failed

**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
```

### Backend won't start

**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
```

### No models showing up

**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

### Sessions not persisting

**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`

### File upload fails

**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

### RAG not working

**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

### Web search not working

**Problem:** "Web Search Unavailable" message

**Solution:**

1. Get free API key from [serper.dev](https://serper.dev/api-keys)
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

### File cards not showing

**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

### Conversation memory not working

**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

### Session titles not generating

**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

### Frontend shows old version

**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

### Run Backend Tests

```bash
cd backend
pytest
```

### Run Frontend in Dev Mode

```bash
npm run dev
```

### Build for Production

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

### Lint and Format

```bash
# Frontend
npm run lint

# Backend
cd backend
black .
flake8 .
```

### Hot Reload

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

### Development Guidelines

- 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](https://github.com/lebiraja/plugin/issues)
- **Discussions** - [GitHub Discussions](https://github.com/lebiraja/plugin/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

### Version 2.0.0 (November 2025) - Major Update 🎉

- ✅ **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

### Version 1.0.0 (October 2025)

- ✅ 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](https://github.com/lebiraja)**

_Star ⭐ this repo if you find it helpful!_