A modern, extensible Python chatbot that generates context-aware, dynamic responses. It ships with two interchangeable backends and three ready-to-use interfaces — no external services are required to get started.
| Mode | When active | What it uses |
|---|---|---|
| LLM | OPENAI_API_KEY is set | OpenAI Chat Completions (GPT-3.5 / GPT-4o) |
| Pattern Matching | No API key present | Offline CSV dialog dataset |
Three interfaces are included out of the box:
| Interface | Entry point | Default URL |
|---|---|---|
| Streamlit web app | streamlit run web_demo.py | http://localhost:8501 |
| FastAPI REST API | uvicorn api:app --reload | http://localhost:8000/docs |
| Tkinter desktop GUI | python ai_chatbot.py | (native window) |
- Key Features
- Quick Start
- Prerequisites
- Installation
- Configuration
- Running the Chatbot
- Docker
- API Reference
- Testing
- CI/CD
- Project Structure
- Architecture
- Contributing
- 🤖 LLM backend — connects to OpenAI's API for intelligent, context-aware responses
- 📋 Offline fallback — pattern matching on a dialog dataset; works without internet/API key
- 🌐 Streamlit web UI — chat from any browser with streaming token output (LLM mode)
- 🔌 FastAPI REST API —
/chatand/trainendpoints; per-session conversation memory - 🖥️ Tkinter desktop GUI — original GUI updated to show backend mode
- 🧠 Conversation memory — recent exchanges are passed to the LLM for follow-up questions
- 🐳 Docker support — single image supports both web and API modes via
MODEbuild arg - ✅ Tests — pytest suite covering core logic and API endpoints
- 🔄 CI/CD — GitHub Actions workflow: lint → test → Docker build
git clone https://github.com/joshuvavinith/AI_ChatBot.git
cd AI_ChatBot
pip install -r requirements.txt
# (optional) enable LLM modeecho"OPENAI_API_KEY=sk-..."> .env
# Start the web UI
streamlit run web_demo.py- Python 3.10 or later (tested on 3.10, 3.11, and 3.12)
- pip (included with Python)
- (Optional) An OpenAI API key to enable LLM mode
- (Optional)Docker for containerised deployment
git clone https://github.com/joshuvavinith/AI_ChatBot.git
cd AI_ChatBot
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txtCreate a .env file in the project root:
OPENAI_API_KEY=sk-your-key-hereOr export it as an environment variable:
export OPENAI_API_KEY=sk-your-key-hereWithout an API key the bot automatically falls back to offline pattern matching.
| Variable | Default | Description |
|---|---|---|
OPENAI_API_KEY | (unset) | Enables LLM mode when present |
The pattern-matching bot can use a richer Kaggle dialog dataset.
To enable it, place kaggle.json in ~/.kaggle/ (or set KAGGLE_USERNAME / KAGGLE_KEY).
If unavailable, the bot falls back to dialog.csv.
python ai_chatbot.pystreamlit run web_demo.pyOpen your browser at http://localhost:8501.
Features:
- Full conversation history
- Streaming token output in LLM mode (looks like ChatGPT)
- "Clear conversation" button in the sidebar
uvicorn api:app --reloadInteractive docs available at http://localhost:8000/docs.
# Web UI (default)
docker build -t ai-chatbot:web .# API mode
docker build --build-arg MODE=api -t ai-chatbot:api .# Web UI — visit http://localhost:8501
docker run -p 8501:8501 -e OPENAI_API_KEY=sk-... ai-chatbot:web
# REST API — visit http://localhost:8000/docs
docker run -p 8000:8000 -e OPENAI_API_KEY=sk-... ai-chatbot:apiSend a message and get a reply. Omit session_id to start a new session.
// Request
{ "message": "Hello!", "session_id": "optional-uuid" }
// Response
{
"reply": "Hi there! How can I help you?",
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"mode": "pattern"
}Reset (delete) a conversation session.
Reload pattern-matching data from a CSV file on the server.
// Request
{ "dialog_file": "/path/to/dialog.csv" }
// Response
{ "status": "retrained", "patterns_loaded": 42 }{ "status": "ok" }pytest test_chatbot.py -vThe test suite covers:
SimpleBot— training, exact/partial matching, defaults, missing fileChatBot— offline mode, history management, streaming, history cap, retraining- FastAPI — all endpoints (health, chat, delete session, train)
GitHub Actions runs on every push and pull request to main:
- Lint —
flake8checks for syntax errors and undefined names - Test —
pytestfull suite with coverage, across Python 3.10, 3.11, and 3.12 - Docker build — both
webandapiimages are built to verify the Dockerfile
Coverage reports are uploaded as build artifacts for each Python version.
AI_ChatBot/
├── ai_chatbot.py # Core module: SimpleBot, LLMBot, ChatBot facade, Tkinter GUI
├── api.py # FastAPI REST backend
├── web_demo.py # Streamlit web interface
├── dialog.csv # Default offline dialog dataset
├── test_chatbot.py # Pytest test suite (SimpleBot, ChatBot, FastAPI)
├── requirements.txt # Python dependencies
├── Dockerfile # Multi-mode Docker image (web / api)
├── LICENSE # MIT License
└── .github/
└── workflows/
└── ci.yml # CI pipeline: lint → test → Docker build
+------------------+ +------------------+ +------------------+
| Streamlit Web | | FastAPI REST | | Tkinter Desktop |
| (web_demo.py) | | (api.py) | | (ai_chatbot.py) |
+--------+---------+ +--------+---------+ +--------+---------+
| | |
+------------------------+-------------------------+
|
+--------v---------+
| ChatBot | ← ai_chatbot.py
| (facade) |
+--+----------+----+
| |
+------------+ +------------+
| |
+--------v---------+ +-----------v------+
| LLMBot | | SimpleBot |
| (OpenAI API) | | (CSV patterns) |
+------------------+ +------------------+
- Fork this repository
- Create a feature branch:
git checkout -b feature/my-feature - Make your changes and run
pytest test_chatbot.py -v - Commit and push:
git push origin feature/my-feature - Open a pull request
Please follow PEP 8 and include tests for any new logic.
To extend the offline pattern-matching bot, add rows to dialog.csv.
Each question/answer pair uses two rows sharing the same dialog_id:
dialog_id,line_id,text8,1,What is Python?8,2,Python is a popular programming language!line_id1 = the user question (matched case-insensitively)line_id2 = the bot response