A full-stack AI chatbot specialized in Indian culture and heritage. BharatKathaAI combines a sleek React-based web interface with a FastAPI backend, powered by Groq's openai/gpt-oss-120b model. It answers questions exclusively about Indian culture, traditions, history, philosophy, arts, and heritage — with responses streamed in real-time.
- 🤖 AI-powered chat using Groq's
openai/gpt-oss-120bmodel - 🇮🇳 Specialized knowledge restricted to Indian culture and heritage
- 🌐 Full-stack: React + Vite frontend, FastAPI backend
- 💬 Multi-session chat with persistent conversation history (SQLite)
- ⚡ Real-time streaming responses via Server-Sent Events (SSE)
- ✏️ Rename and 🗑️ delete individual chat sessions
- 🔍 Search across past sessions in the sidebar
- 📥 Export any chat session as a Markdown file
- 🎨 Dark glassmorphism UI with smooth Framer Motion animations
- 🔒 API key secured on the backend via
.env
- Prerequisites
- Installation
- Configuration
- Running the App
- How It Works
- Project Structure
- API Endpoints
- Dependencies
- Security Best Practices
- Troubleshooting
- FAQ
- Limitations
- Contributing
- Future Improvements
- License
- Python 3.8+ — for the backend
- Node.js 18+ & npm — for the frontend
- Groq API key — Get one here
- Stable internet connection
python --version
node --version
npm --versiongit clone <your-repository-url>
cd "Python chatbot"cd Backend
pip install -r requirements.txtcd ../frontend
npm installCreate a .env file inside the Backend/ directory with your Groq API key:
GROQ_API_KEY=your_actual_groq_api_key_hereThe backend loads this automatically via
python-dotenv. Never commit this file to version control.
- Visit Groq Console
- Sign up or log in to your account
- Navigate to API Keys → Create API Key
- Copy the key (shown only once)
You need two terminals running simultaneously:
cd Backend
python main.pyThe API will be available at: http://127.0.0.1:8000
cd frontend
npm run devThe app will be available at: http://localhost:5173 (Vite default)
Open your browser and navigate to http://localhost:5173 to start chatting.
- On load, the React frontend fetches all existing chat sessions from
GET /api/sessions - When a user sends a message, the frontend calls
POST /api/session/{id}/stream - The backend saves the user message to SQLite, builds the full message history, and calls the Groq API with streaming enabled
- Streamed response chunks arrive as Server-Sent Events (
text/event-stream) and are rendered token-by-token in the UI - Once streaming is complete, the final assistant reply is persisted to SQLite
- The session title is auto-generated from the first message (first 25 characters)
The backend enforces this system prompt for every request:
"You are an excellent Indian culture and heritage bot who has all the knowledge
about Indian culture and heritage only. You will not answer any questions outside
of Indian heritage, philosophy, history, geography, arts, and traditions.
Format responses using beautiful Markdown."
Python chatbot/
├── Backend/ # FastAPI backend
│ ├── main.py # API routes, SSE streaming, Groq integration
│ ├── database.py # SQLAlchemy models (ChatSession, ChatMessage) & SQLite engine
│ ├── bharatkatha.db # Auto-created SQLite database
│ ├── requirements.txt # Backend Python dependencies
│ └── .env # Environment variables (GROQ_API_KEY) — not committed
├── frontend/ # React + Vite frontend
│ ├── src/
│ │ ├── App.jsx # Main chat UI (sidebar, message thread, input, SSE reader)
│ │ ├── App.css # Component-level styles
│ │ ├── main.jsx # React 19 entry point
│ │ └── index.css # Global styles & Tailwind v4 imports
│ ├── public/
│ │ ├── favicon.svg # App favicon
│ │ └── icons.svg # Icon assets
│ ├── index.html # HTML entry point
│ ├── package.json # Node dependencies & scripts
│ ├── vite.config.js # Vite + @tailwindcss/vite + @vitejs/plugin-react
│ ├── eslint.config.js # ESLint flat config
│ └── .gitignore # Frontend-specific git ignore
├── apibot.py # Legacy CLI chatbot (original version)
├── requirements.txt # Root-level Python dependencies
├── README.md # Project documentation
└── .gitignore # Root git ignore
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/sessions |
Fetch all chat sessions ordered by newest first |
POST |
/api/sessions |
Create a new chat session { id, title } |
DELETE |
/api/session/{session_id} |
Delete a session and all its messages (cascade) |
POST |
/api/session/{session_id}/stream |
Send a message; streams AI response as SSE |
PUT |
/api/session/{session_id} |
Rename a session { title } |
Each chunk arrives as:
data:{"chunk": "...token..."}
| Package | Purpose |
|---|---|
fastapi |
Web framework for building the REST API |
uvicorn |
ASGI server to run FastAPI |
sqlalchemy |
ORM — manages ChatSession and ChatMessage tables in SQLite |
python-dotenv |
Loads GROQ_API_KEY from .env |
openai ≥ 1.0.0 |
OpenAI-compatible client for the Groq API |
pydantic |
Request/response data validation |
| Package | Version | Purpose |
|---|---|---|
react |
^19.2.6 | UI library |
react-dom |
^19.2.6 | React DOM renderer |
framer-motion |
^12.40.0 | Animations and motion transitions |
lucide-react |
^1.17.0 | Icon library |
tailwindcss |
^4.3.0 | Utility-first CSS framework (v4) |
@tailwindcss/vite |
^4.3.0 | Tailwind v4 Vite plugin |
vite |
^8.0.12 | Frontend build tool and dev server |
@vitejs/plugin-react |
^6.0.1 | React Fast Refresh support |
- Never commit your API key — keep it in
Backend/.envwhich is listed in.gitignore - Never put the API key in frontend code — all Groq calls are made server-side only
- Rotate your key if it is accidentally exposed; monitor usage in the Groq dashboard
# Environment variables
.env
*.env
# Python
__pycache__/
*.py[cod]
*.so
venv/
env/
ENV/
# SQLite database
*.db
# Node
node_modules/
dist/
pip install -r Backend/requirements.txt- Ensure the backend is running on port
8000 - Check the browser console for CORS errors
- CORS is configured as
allow_origins=["*"]inmain.pyby default
- Verify
GROQ_API_KEYis correct inBackend/.env - Ensure there are no extra spaces or quotes around the key
- Try regenerating the API key in the Groq Console
- The backend uses
llama-3.3-70b-versatile— verify this is available in your Groq account - Check Groq's model list for currently available models
cd frontend
npm install # reinstall dependencies
npm run dev- Check the Groq API Documentation
- Review error messages in both terminals
- Ensure Python ≥ 3.8 and Node.js ≥ 18 are installed
A: No — the system prompt strictly restricts the bot to Indian culture, heritage, history, philosophy, arts, and traditions. Questions outside this domain are declined.
A: Groq offers a free tier with usage limits. Check their pricing page for current rates and limits.
A: Yes — all chat sessions and messages are persisted in a local SQLite database (Backend/bharatkatha.db). They are restored on every page reload.
A: Click the Export MD button in the top-right of the chat panel. It downloads the active session as a .md Markdown file.
A: Yes — hover over any session in the sidebar to reveal ✏️ rename and 🗑️ delete action buttons.
A: Yes — edit the model field inside the event_generator function in Backend/main.py. Check Groq's docs for available models.
A: Python 3.8 or higher. Python 3.10+ is recommended for best compatibility.
- Focused domain only — restricted to Indian culture and heritage by design
- Local SQLite database — not suitable for multi-user cloud deployments without switching to PostgreSQL or similar
- No authentication — the app does not include user login or access control
- Internet required — the Groq API requires an active internet connection
- API rate limits — subject to Groq's rate limiting policies on the free tier
- Single-user local setup — designed for local development; production deployment requires additional configuration
Contributions are welcome! Here are some ways you can help:
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes
- Test thoroughly
- Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
- User authentication and profiles
- Cloud database support (PostgreSQL / Neon)
- Support for multiple Indian languages (Hindi, Tamil, etc.)
- Voice input/output support
- Mobile responsive PWA
- Unit and integration tests
- Multimodal support (image-based questions)
- Python: Follow PEP 8; use docstrings for functions
- JavaScript/React: Follow standard React patterns; use functional components and hooks
- Persistent conversation history (SQLite via SQLAlchemy)
- Streaming responses (Server-Sent Events)
- Multi-session management (create, rename, delete)
- Search across chat sessions
- Export chat as Markdown
- Web UI (React 19 + Vite + Tailwind v4)
- User authentication and access control
- Cloud database support (PostgreSQL / Neon)
- Configurable system prompts via UI
- Multi-language support (Hindi, Tamil, etc.)
- Voice input/output
- Deploy backend to Railway / Render
- Deploy frontend to Vercel / Netlify
- Mobile-first responsive layout improvements
This project is open source and available for personal and educational use.
- Built with Groq API
- Powered by
llama-3.3-70b-versatilemodel - Uses OpenAI Python Library (OpenAI-compatible client for Groq)
- Frontend built with React 19, Vite 8, Tailwind CSS v4, and Framer Motion
- Icons by Lucide
- Backend powered by FastAPI and SQLAlchemy
Made with ❤️ for preserving and sharing Indian culture and heritage
For questions, issues, or contributions, please open an issue on the repository.