django-db-chat-widget 0.1.0

Django integration for db-chat-widget: a natural-language database chatbot widget for Django templates.

django-db-chat-widget

Django integration for db-chat-widget: drop a natural-language database chatbot into any Django template as a floating popup (or inline panel), backed by your existing Django database connection.

• Reuses your existing Django database connection — no separate credentials to configure; the SQLAlchemy URL is derived automatically from settings.DATABASES (PostgreSQL, MySQL, SQLite).
• Pluggable LLM backend: Anthropic Claude, OpenAI, Groq, or a local Ollama model (via db-chat-widget).
• Read-only by default: generated SQL is parsed and only SELECT statements are allowed unless you explicitly opt into write access.
• One template tag: {% db_chat_widget %} renders a floating chat bubble (or an inline panel) — no extra views or URLs to wire up yourself.
• Proper CSRF handling: works with Django's CSRF protection out of the box, no csrf_exempt required.

Install

pip install django-db-chat-widget

This pulls in db-chat-widget (the framework-agnostic core: LLM providers, SQL safety checks, query execution) as a dependency.

Add the app and its URLs:

# settings.py
INSTALLED_APPS = [
    ...,
    "django.contrib.staticfiles",
    "django_db_chat_widget",
]

TEMPLATES = [
    {
        ...,
        "OPTIONS": {
            "context_processors": [
                ...,
                "django.template.context_processors.request",  # required
            ],
        },
    },
]

DB_CHAT_WIDGET = {
    "DB_ALIAS": "default",           # which DATABASES entry to query
    "LLM_PROVIDER": "groq",          # "anthropic" | "openai" | "groq" | "ollama"
    "LLM_API_KEY": "gsk_...",        # or read from os.environ
    "READ_ONLY": True,               # default: only SELECT statements allowed
    "MAX_ROWS": 200,
    "ALLOWED_TABLES": None,          # e.g. ["orders", "customers"] to scope access
    "TITLE": "Ask your database",
}

# urls.py
from django.urls import include, path

urlpatterns = [
    ...,
    path("db-chat/", include("django_db_chat_widget.urls")),
]

Then drop the tag into any template:

{% load db_chat_widget %}
{% db_chat_widget %}

That's it — a floating chat bubble now appears in the bottom-right corner of that page. See example_project/ for a complete, runnable Django project demonstrating this end to end.

Template tag options

{% db_chat_widget %}                                {# popup, bottom-right #}
{% db_chat_widget position="bottom-left" %}          {# popup, bottom-left #}
{% db_chat_widget target="#my-chat-div" %}           {# inline instead of popup #}
{% db_chat_widget title="Ask HR" placeholder="..." %}

Multiple databases / explicit connection

If your Django project has several DATABASES entries, point DB_CHAT_WIDGET["DB_ALIAS"] at the one to query. To bypass Django's DATABASES entirely (e.g. a read replica not declared there), set DB_CHAT_WIDGET["DB_URL"] to an explicit SQLAlchemy URL instead — it takes precedence over DB_ALIAS.

Safety notes

• READ_ONLY=True (the default) is enforced by parsing the generated SQL with sqlglot, not just by prompting the model — treat it as the actual security boundary. See db-chat-widget's safety notes for details.
• Use ALLOWED_TABLES to scope the chatbot away from sensitive tables (e.g. Django's own auth_user / session tables).
• The /db-chat/chat/ endpoint is a normal Django view protected by Django's CSRF middleware; the template tag ensures the CSRF cookie is set on any page that renders it.

Development

pip install -e ".[dev]"
pytest
ruff check .

License

MIT