Spaces:

Kuldeepmishra3
/

Kuldeep-AI

Sleeping

App Files Files Community

Kuldeep-AI / README.md

Kuldeepmishra3

feat: Kuldeep AI v1.0

f2eba97 about 2 months ago

preview code

Raw

History Blame Contribute Delete

8.67 kB

metadata

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 (free tier works great)

1. Clone and Setup

git clone <your-repo-url>
cd kuldeep-ai

2. Create Virtual Environment

python -m venv .venv

# Windows
.venv\Scripts\activate

# Mac/Linux
source .venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

4. Configure Environment

Copy .env.example to .env and fill in your values:

cp .env.example .env

Edit .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

# 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).