A reusable Django AI chat widget powered by OpenAI and JSON knowledge bases.
Project description
Django ChatWidget
Django ChatWidget is a reusable, pip-installable AI-powered chat widget for Django projects. It allows you to drop an OpenAI-powered assistant into any Django site, trained on your custom .json knowledge base files.
🚀 Features
- Floating chat UI that integrates with your site
- Powered by OpenAI's GPT models (configurable)
- Loads context from
.jsonfiles you provide - No external database dependencies required
- Works with any Django app via
{% include %} - MIT licensed
📦 Installation
pip install django-chatwidget
Add chatwidget to your INSTALLED_APPS:
INSTALLED_APPS = [
...
'chatwidget',
]
Include the widget in your base.html:
{% load static %}
{% include "chatwidget/widget.html" %}
Include the URLs in your root urls.py:
from django.urls import include, path
urlpatterns = [
...
path("chatwidget/", include("chatwidget.urls")),
]
🔑 Set Your OpenAI API Key
Add to your .env file or settings.py:
export OPENAI_API_KEY=your-openai-key
Or in settings.py:
import os
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
🧠 How to Train the Chatbot
Add .json files inside chatwidget/data/. Each should have:
[
{
"title": "About Us",
"content": "We are a nonprofit organization providing support..."
},
{
"title": "Contact",
"content": "Email us at support@example.com."
}
]
These files will be automatically loaded into the system prompt and used by the assistant.
🎨 Required CSS Framework
This widget uses Bootstrap 5 classes such as form-control and btn. You must include Bootstrap 5 in your base template for correct styling:
<!-- Add to your base.html <head> -->
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet">
🧪 Example Project Setup
To test:
python manage.py runserver
Visit http://localhost:8000/chatwidget/ or wherever you embed the widget.
📁 File Structure
chatwidget/
├── data/ # Your custom knowledge base files
├── static/chatwidget/ # CSS & JS for chat
├── templates/chatwidget/ # Contains widget.html
├── views.py # Handles OpenAI requests
├── urls.py # Exposes POST endpoint
├── openai_utils.py # Loads knowledge + handles API
📃 License
MIT License © 2025 Matthew Raynor
🧠 Attribution / Shout Out
Built by Matthew Raynor, a quadriplegic full-stack developer turning his creativity into independence — follow for more tools that empower and inspire.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file django_chatwidget-0.1.0.tar.gz.
File metadata
- Download URL: django_chatwidget-0.1.0.tar.gz
- Upload date:
- Size: 4.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.12.8
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
7bceaf617ae8f4399e504f7dd5498b1acf0a01775fb6654ca037251fcc3ac4c7
|
|
| MD5 |
3d135e51d3ebb5248bbef9dc0579174d
|
|
| BLAKE2b-256 |
32ceb8d06813663b994c0f1f770bb2a239a14737f5080222eae241b7d950bb66
|
File details
Details for the file django_chatwidget-0.1.0-py3-none-any.whl.
File metadata
- Download URL: django_chatwidget-0.1.0-py3-none-any.whl
- Upload date:
- Size: 5.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.12.8
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ac5b313a086e8566192414584d49d9b6128843f4c40505a80269c3f53bdc0b49
|
|
| MD5 |
a0e8f004c380f88dbe614939aaf6a145
|
|
| BLAKE2b-256 |
371a343836fdc5c3ba84ab1a8afe735993e5bc3d472d5f350a72c646b3c11c4e
|
