README.md

---

title: JanSahayak
emoji: 🙏
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
---


# 🙏 JanSahayak - AI-Powered Government Schemes & Exams Assistant

> Your personal AI assistant for discovering government schemes and competitive exam opportunities in India

[![Hugging Face Spaces](https://img.shields.io/badge/🤗-Hugging%20Face-yellow)](https://huggingface.co/spaces)
[![Flask](https://img.shields.io/badge/Flask-2.3+-green)](https://flask.palletsprojects.com/)
[![LangChain](https://img.shields.io/badge/LangChain-Latest-blue)](https://www.langchain.com/)

---

## 🌟 Features

### 🤖 Multi-Agent AI System
- **Profiling Agent**: Extracts structured user information
- **Scheme Agent**: Recommends relevant government schemes  
- **Exam Agent**: Suggests competitive exams based on qualifications
- **RAG Agent**: Retrieves information from curated document database

### 💡 Intelligent Capabilities
- ✅ Natural language understanding of user profiles
- ✅ Smart recommendations based on eligibility criteria
- ✅ RAG (Retrieval-Augmented Generation) with FAISS vectorstore
- ✅ Real-time web search via Tavily API
- ✅ PDF generation for saving recommendations
- ✅ Beautiful web interface with modern UI

---

## 🚀 Deploy to Hugging Face Spaces (Recommended)

### Why Hugging Face Spaces?
- ✅ **16GB RAM for FREE** (perfect for RAG apps!)
- ✅ Built for ML/AI applications
- ✅ Git-based deployment
- ✅ Public URL instantly
- ✅ Persistent storage

### Quick Deploy Steps:

**Method 1: Using HF CLI (Easiest)**

```bash

# Install HF CLI

pip install huggingface_hub[cli]



# Login

huggingface-cli login



# Create Space and push

huggingface-cli repo create jansahayak --type space --space_sdk gradio

git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/jansahayak

git push hf main

```

**Method 2: Manual Setup**

1. **Create Space** on [huggingface.co/spaces](https://huggingface.co/spaces)
   - Click "Create new Space"
   - Name: `jansahayak`
   - SDK: Select "Gradio" (works with Flask)
   - Hardware: CPU basic (Free - 16GB RAM!)
   - License: MIT

2. **Clone YOUR Space repo** (not GitHub!)
   ```bash

   git clone https://huggingface.co/spaces/YOUR_USERNAME/jansahayak

   cd jansahayak

   ```

3. **Copy your project files**
   ```bash

   # Copy all files from your JanSahayak folder to the cloned space folder

   cp -r /path/to/JanSahayak/* .

   ```

4. **Add Environment Variables** (Space Settings → Variables and secrets)
   ```

   GROQ_API_KEY=your_groq_key

   TAVILY_API_KEY=your_tavily_key  

   HF_TOKEN=your_hf_token (optional)

   SKIP_VECTORSTORES=false

   ```

5. **Push to Space**
   ```bash

   git add .

   git commit -m "Initial commit"

   git push

   ```

Your app will be live at: `https://huggingface.co/spaces/YOUR_USERNAME/jansahayak`

### Important Notes:
- HF Spaces uses its own Git repo (not GitHub directly)
- App runs on port 7860 by default (Flask uses 5000, update if needed)
- First deployment may take 5-10 minutes to install dependencies
- Check Space logs if deployment fails

---

## 🛠️ Local Development

```bash

# Clone and setup

git clone https://github.com/YOUR_USERNAME/JanSahayak.git

cd JanSahayak



# Create virtual environment

python -m venv .venv

source .venv/bin/activate  # Linux/Mac

.venv\Scripts\activate     # Windows



# Install dependencies

pip install -r requirements.txt



# Configure API keys

cp .env.example .env

# Edit .env with your keys



# Build vectorstores (optional - if you have PDFs)

python init_embeddings.py



# Run app

python app.py

# or use launcher scripts: start_web.bat (Windows) / ./start_web.sh (Linux/Mac)

```

Visit `http://localhost:5000`

---

## 🔑 Get API Keys

| Service | URL | Free Tier | Used For |
|---------|-----|-----------|----------|
| **Groq** | [console.groq.com](https://console.groq.com) | ✅ Yes | LLM Inference |
| **Tavily** | [tavily.com](https://tavily.com) | 1000 searches/mo | Web Search |
| **HuggingFace** | [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) | ✅ Yes | Model Downloads |

---

## 💾 Adding Custom Documents

### Government Schemes PDFs
1. Place PDFs in `data/schemes_pdfs/`
2. Run `python init_embeddings.py`
3. Restart app

### Exam Information PDFs
1. Place PDFs in `data/exams_pdfs/`
2. Run `python init_embeddings.py`
3. Restart app

Automatically indexed and searchable via RAG!

---

## 🧪 Technology Stack

- **Backend**: Flask
- **AI**: LangChain + LangGraph  
- **LLM**: Groq (Llama 3.3 70B)
- **Embeddings**: sentence-transformers/all-MiniLM-L6-v2
- **Vector DB**: FAISS (local)
- **Search**: Tavily API
- **Frontend**: HTML5 + CSS3 + JavaScript

---

## 📁 Project Structure

```

JanSahayak/

├── app.py                    # Flask web app

├── main.py                   # CLI interface

├── agents/                   # AI agents

│   ├── profiling_agent.py

│   ├── scheme_agent.py

│   ├── exam_agent.py

│   └── rag_agent.py

├── rag/                      # RAG components

│   ├── embeddings.py

│   ├── scheme_vectorstore.py

│   └── exam_vectorstore.py

├── data/                     # Documents

│   ├── schemes_pdfs/

│   └── exams_pdfs/

├── templates/                # HTML templates

└── static/                   # CSS/JS

```

---

## 🐛 Troubleshooting

**Memory issues on local machine?**
```env

# Set in .env

SKIP_VECTORSTORES=true

```
Uses web search only (no embeddings needed)

**Vectorstore errors?**
```bash

rm -rf rag/scheme_index rag/exam_index

python init_embeddings.py

```

---

## 🤝 Contributing

Contributions welcome! Fork → Create branch → Submit PR

---

## 📜 License

MIT License

---

## 🙏 Acknowledgments

Built with [LangChain](https://www.langchain.com/), [Groq](https://groq.com/), [Tavily](https://tavily.com/), and ❤️

---

Made for the people of India 🇮🇳