---
title: Kuldeep AI
emoji: ๐
colorFrom: red
colorTo: green
sdk: docker
pinned: false
license: mit
---
Kuldeep AI โ Personal AI Assistant
A humanized, multi-agent AI chatbot powered by an advanced RAG knowledge base
Built by Kuldeep Kumar Mishra ยท AI Engineer ยท IIIT Lucknow
---
## ๐ What is Kuldeep AI?
**Kuldeep AI** is my personal AI assistant that anyone can talk to and learn about me โ my background, projects, skills, achievements, and more. Instead of a static portfolio, this is a **living, conversational AI** that knows everything about me from a carefully curated knowledge base.
It's not just a chatbot. It's a **multi-agent system** with five specialized agents working under the hood, an **advanced RAG pipeline** that retrieves and reasons over my personal knowledge base, and a **clean, beautiful UI** that feels premium and modern.
> *"The goal isn't to build models. The goal is to build intelligence that matters."*
> โ Kuldeep Kumar Mishra
---
## โจ Key Features
### ๐ง Advanced RAG System
- **Hybrid Retrieval** โ BM25 keyword search + semantic vector search combined
- **Reciprocal Rank Fusion (RRF)** โ intelligently merges results from both retrieval methods
- **Cross-Encoder Re-ranking** โ uses `ms-marco-MiniLM-L-6-v2` for precise relevance scoring
- **Anti-Hallucination** โ answers only from the knowledge base; declines gracefully if info is unavailable
- **Persistent ChromaDB** โ vector store survives server restarts; auto-indexed on startup
### ๐ค Multi-Agent Architecture (LangGraph)
The system intelligently routes every message to the right specialist:
| Agent | Handles |
|-------|---------|
| ๐ **Router Agent** | Classifies the query and routes it to the right agent |
| ๐ **RAG Agent** | Answers from Kuldeep's personal knowledge base |
| ๐งฎ **Math Agent** | Solves calculations and equations |
| ๐ง **Memory Agent** | Recalls earlier parts of the conversation |
| ๐ **Search Agent** | Fetches real-time information from the web |
| ๐ฌ **General Agent** | Handles greetings and general knowledge |
### ๐ Admin Panel (Private)
- Upload PDFs and TXT files to expand the knowledge base
- View, edit, and delete documents directly in the browser
- Force re-index all documents with one click
- Protected by a secret key โ hidden from public users
### ๐จ Beautiful UI
- **Light mode default** โ clean white/blue design inspired by modern AI interfaces
- **Dark mode toggle** โ switches to a sleek dark theme
- Word-by-word streaming responses
- Responsive design for mobile and desktop
---
## ๐๏ธ Project Architecture
```
kuldeep-ai/
โ
โโโ app.py # App entry point
โโโ config.py # Centralized configuration
โโโ requirements.txt # Python dependencies
โโโ run.bat # One-click local startup (Windows)
โ
โโโ agents/ # All AI agents
โ โโโ router_agent.py # Routes queries to the right agent
โ โโโ rag_agent.py # Knowledge base Q&A (anti-hallucination)
โ โโโ math_agent.py # Math & calculations
โ โโโ memory_agent.py # Conversation memory recall
โ โโโ search_agent.py # Real-time web search
โ โโโ general_agent.py # General chat & greetings
โ
โโโ rag/ # RAG pipeline
โ โโโ document_loader.py # PDF & TXT chunking
โ โโโ vector_store.py # ChromaDB wrapper (CRUD)
โ โโโ retriever.py # Hybrid BM25 + semantic + RRF
โ โโโ reranker.py # Cross-encoder re-ranking
โ
โโโ orchestrator/
โ โโโ graph.py # LangGraph state machine
โ
โโโ api/
โ โโโ index.py # Flask routes (chat, admin, docs)
โ
โโโ memory/
โ โโโ sqlite_memory.py # Conversation history (SQLite)
โ
โโโ templates/ # HTML pages
โ โโโ index.html # Public chat UI
โ โโโ admin.html # Admin dashboard
โ โโโ admin_denied.html # 403 access denied
โ
โโโ static/ # Frontend assets
โ โโโ style.css # All styles (light + dark theme)
โ โโโ script.js # Chat logic, streaming, theme
โ โโโ ai-avatar.png # Bot avatar image
โ
โโโ data/
โ โโโ knowledge/ # ๐ Private: .txt/.pdf knowledge files
โ โโโ uploads/ # ๐ Private: admin-uploaded files
โ โโโ chroma_db/ # ๐ Auto-generated: vector embeddings
โ
โโโ utils/
โโโ logger.py # Structured logging
```
---
## ๐ Getting Started
### Prerequisites
- Python 3.10+
- A [Groq API key](https://console.groq.com/) (free tier works great)
### 1. Clone and Setup
```bash
git clone
cd kuldeep-ai
```
### 2. Create Virtual Environment
```bash
python -m venv .venv
# Windows
.venv\Scripts\activate
# Mac/Linux
source .venv/bin/activate
```
### 3. Install Dependencies
```bash
pip install -r requirements.txt
```
### 4. Configure Environment
Copy `.env.example` to `.env` and fill in your values:
```bash
cp .env.example .env
```
Edit `.env`:
```env
GROQ_API_KEY=your_groq_api_key_here
ADMIN_SECRET_KEY=your-secret-admin-key
```
### 5. Add Your Knowledge Base
Place your `.txt` or `.pdf` files in `data/knowledge/`. These are auto-indexed on every server start.
```
data/knowledge/
โโโ about.txt
โโโ projects.txt
โโโ skills.txt
โโโ work_experience.txt
โโโ achievements.txt
โโโ social_links.txt
โโโ faq.txt
```
### 6. Run the App
```bash
# Windows (double-click or run):
run.bat
# Or manually:
python app.py
```
Open your browser at: **http://127.0.0.1:10000**
---
## ๐ Admin Panel
Access the admin dashboard at:
```
http://127.0.0.1:10000/admin?key=YOUR_ADMIN_SECRET_KEY
```
From the admin panel you can:
- ๐ค Upload new PDF or TXT files
- ๐๏ธ View any document's content
- โ๏ธ Edit TXT files directly in the browser
- ๐๏ธ Delete documents (also removes from vector store)
- ๐ Force re-index all files
---
## โ๏ธ Configuration Reference
All settings live in `.env`:
| Variable | Default | Description |
|----------|---------|-------------|
| `GROQ_API_KEY` | โ | Your Groq API key |
| `GROQ_MODEL_NAME` | `llama-3.1-8b-instant` | LLM model to use |
| `EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | Local embedding model |
| `ADMIN_SECRET_KEY` | โ | Password for admin panel |
| `CHUNK_SIZE` | `600` | Characters per document chunk |
| `CHUNK_OVERLAP` | `80` | Overlap between chunks |
| `TOP_K_RETRIEVAL` | `5` | Final chunks sent to LLM |
| `TOP_K_CANDIDATES` | `8` | Candidates before re-ranking |
| `ENABLE_RERANKING` | `true` | Cross-encoder re-ranking |
| `ENABLE_QUERY_EXPANSION` | `false` | Query expansion (slower) |
---
## ๐ ๏ธ Tech Stack
| Layer | Technology |
|-------|-----------|
| **LLM** | Groq (Llama 3.1 8B Instant) |
| **Embeddings** | `sentence-transformers/all-MiniLM-L6-v2` |
| **Re-ranker** | `cross-encoder/ms-marco-MiniLM-L-6-v2` |
| **Vector Store** | ChromaDB (persistent) |
| **Retrieval** | BM25 + Semantic + RRF + Cross-Encoder |
| **Orchestration** | LangGraph (state machine) |
| **Backend** | Flask 3.x |
| **Memory** | SQLite (conversation history) |
| **Frontend** | Vanilla HTML/CSS/JS |
| **Fonts** | Google Fonts (Inter + Outfit) |
---
## ๐จโ๐ป About the Author
**Kuldeep Kumar Mishra** is an AI Engineer specializing in Generative AI, LLMs, RAG systems, Agentic AI, and Machine Learning. Currently pursuing M.Sc. Data Science at IIIT Lucknow (secured AIR 1180 in IIT JAM Mathematics 2024).
- ๐ [LinkedIn](https://linkedin.com/in/kuldeep-kumar-mishra)
- ๐ [GitHub](https://github.com/kuldeepkumar)
- ๐ค [Hugging Face](https://huggingface.co/kuldeep)
- ๐บ [YouTube โ AI Simplified](https://youtube.com/@aisimplified)
---
## ๐ License
This is a personal project. All rights reserved ยฉ 2025 Kuldeep Kumar Mishra.