django-db-chat-widget 0.1.0__tar.gz

django_db_chat_widget-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        django-version: ["4.2", "5.0"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install db-chat-widget (core) from GitHub
+        run: pip install "db-chat-widget @ git+https://github.com/krak225/db-chat-widget.git"
+
+      - name: Install package with dev extras
+        run: pip install -e ".[dev]"
+
+      - name: Install pinned Django version
+        run: pip install "django~=${{ matrix.django-version }}.0"
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Test
+        run: pytest -v

django_db_chat_widget-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+.pytest_cache/
+.ruff_cache/
+*.db
+*.sqlite3
+.coverage
+htmlcov/
+.idea/
+.vscode/
+example_project/db.sqlite3

django_db_chat_widget-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Armand Kouassi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_db_chat_widget-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: django-db-chat-widget
+Version: 0.1.0
+Summary: Django integration for db-chat-widget: a natural-language database chatbot widget for Django templates.
+Project-URL: Homepage, https://github.com/krak225/django-db-chat-widget
+Project-URL: Issues, https://github.com/krak225/django-db-chat-widget/issues
+Author: Armand Kouassi
+License-Expression: MIT
+License-File: LICENSE
+Keywords: chatbot,database,django,llm,nl2sql,sql,widget
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: db-chat-widget>=0.1.0
+Requires-Dist: django>=4.2
+Provides-Extra: dev
+Requires-Dist: pytest-django>=4.8; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# django-db-chat-widget
+
+Django integration for [db-chat-widget](https://github.com/krak225/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](https://github.com/krak225/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
+
+```bash
+pip install django-db-chat-widget
+```
+
+This pulls in [`db-chat-widget`](https://github.com/krak225/db-chat-widget)
+(the framework-agnostic core: LLM providers, SQL safety checks, query
+execution) as a dependency.
+
+Add the app and its URLs:
+
+```python
+# 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",
+}
+```
+
+```python
+# 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:
+
+```html
+{% 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/`](example_project) for a complete, runnable
+Django project demonstrating this end to end.
+
+## Template tag options
+
+```html
+{% 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](https://github.com/krak225/db-chat-widget#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
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+## License
+
+MIT

django_db_chat_widget-0.1.0/README.md

@@ -0,0 +1,124 @@
+# django-db-chat-widget
+
+Django integration for [db-chat-widget](https://github.com/krak225/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](https://github.com/krak225/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
+
+```bash
+pip install django-db-chat-widget
+```
+
+This pulls in [`db-chat-widget`](https://github.com/krak225/db-chat-widget)
+(the framework-agnostic core: LLM providers, SQL safety checks, query
+execution) as a dependency.
+
+Add the app and its URLs:
+
+```python
+# 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",
+}
+```
+
+```python
+# 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:
+
+```html
+{% 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/`](example_project) for a complete, runnable
+Django project demonstrating this end to end.
+
+## Template tag options
+
+```html
+{% 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](https://github.com/krak225/db-chat-widget#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
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+## License
+
+MIT

django_db_chat_widget-0.1.0/example_project/example_project/settings.py

@@ -0,0 +1,61 @@
+import os
+from pathlib import Path
+
+BASE_DIR = Path(__file__).resolve().parent.parent
+
+SECRET_KEY = "example-secret-key-not-for-production"
+DEBUG = True
+ALLOWED_HOSTS = ["*"]
+
+INSTALLED_APPS = [
+    "django.contrib.contenttypes",
+    "django.contrib.auth",
+    "django.contrib.sessions",
+    "django.contrib.staticfiles",
+    "django_db_chat_widget",
+]
+
+MIDDLEWARE = [
+    "django.middleware.security.SecurityMiddleware",
+    "django.contrib.sessions.middleware.SessionMiddleware",
+    "django.middleware.common.CommonMiddleware",
+    "django.middleware.csrf.CsrfViewMiddleware",
+]
+
+ROOT_URLCONF = "example_project.urls"
+
+TEMPLATES = [
+    {
+        "BACKEND": "django.template.backends.django.DjangoTemplates",
+        "DIRS": [BASE_DIR / "templates"],
+        "APP_DIRS": True,
+        "OPTIONS": {
+            "context_processors": [
+                "django.template.context_processors.request",
+            ],
+        },
+    },
+]
+
+WSGI_APPLICATION = "example_project.wsgi.application"
+
+# This is also the database that the chatbot answers questions about — see
+# DB_CHAT_WIDGET below, which reuses this same connection by default.
+DATABASES = {
+    "default": {
+        "ENGINE": "django.db.backends.sqlite3",
+        "NAME": BASE_DIR / "db.sqlite3",
+    }
+}
+
+STATIC_URL = "/static/"
+
+USE_TZ = True
+DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"
+
+DB_CHAT_WIDGET = {
+    "DB_ALIAS": "default",
+    "LLM_PROVIDER": os.environ.get("DB_CHAT_LLM_PROVIDER", "groq"),
+    "LLM_API_KEY": os.environ.get("DB_CHAT_LLM_API_KEY"),
+    "TITLE": "Ask about our data",
+}

django_db_chat_widget-0.1.0/example_project/example_project/urls.py

@@ -0,0 +1,7 @@
+from django.urls import include, path
+from django.views.generic import TemplateView
+
+urlpatterns = [
+    path("db-chat/", include("django_db_chat_widget.urls")),
+    path("", TemplateView.as_view(template_name="home.html"), name="home"),
+]

django_db_chat_widget-0.1.0/example_project/example_project/wsgi.py

@@ -0,0 +1,7 @@
+import os
+
+from django.core.wsgi import get_wsgi_application
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "example_project.settings")
+
+application = get_wsgi_application()

django_db_chat_widget-0.1.0/example_project/manage.py

@@ -0,0 +1,19 @@
+#!/usr/bin/env python
+import os
+import sys
+
+
+def main():
+    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "example_project.settings")
+    try:
+        from django.core.management import execute_from_command_line
+    except ImportError as exc:
+        raise ImportError(
+            "Couldn't import Django. Make sure it's installed and available on "
+            "your PYTHONPATH environment variable."
+        ) from exc
+    execute_from_command_line(sys.argv)
+
+
+if __name__ == "__main__":
+    main()

django_db_chat_widget-0.1.0/example_project/seed_db.py

@@ -0,0 +1,49 @@
+"""Seed example_project/db.sqlite3 with a couple of demo tables.
+
+Run once before `python manage.py runserver`:
+
+    python seed_db.py
+"""
+
+import sqlite3
+from pathlib import Path
+
+DB_PATH = Path(__file__).parent / "db.sqlite3"
+
+
+def main() -> None:
+    conn = sqlite3.connect(DB_PATH)
+    try:
+        conn.execute("DROP TABLE IF EXISTS customers")
+        conn.execute("DROP TABLE IF EXISTS orders")
+        conn.execute(
+            "CREATE TABLE customers (id INTEGER PRIMARY KEY, name TEXT, country TEXT)"
+        )
+        conn.execute(
+            "CREATE TABLE orders (id INTEGER PRIMARY KEY, customer_id INTEGER, "
+            "amount REAL, status TEXT)"
+        )
+        conn.executemany(
+            "INSERT INTO customers (id, name, country) VALUES (?, ?, ?)",
+            [
+                (1, "Awa Diallo", "Senegal"),
+                (2, "Kofi Mensah", "Ghana"),
+                (3, "Amina Traore", "Cote d'Ivoire"),
+            ],
+        )
+        conn.executemany(
+            "INSERT INTO orders (id, customer_id, amount, status) VALUES (?, ?, ?, ?)",
+            [
+                (1, 1, 120.0, "paid"),
+                (2, 1, 45.5, "pending"),
+                (3, 2, 300.0, "paid"),
+            ],
+        )
+        conn.commit()
+    finally:
+        conn.close()
+    print(f"Seeded {DB_PATH}")
+
+
+if __name__ == "__main__":
+    main()

django_db_chat_widget-0.1.0/example_project/templates/home.html

@@ -0,0 +1,32 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <title>My Django site</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <style>
+    body {
+      margin: 0;
+      min-height: 100vh;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      background: #f5f5f7;
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+    }
+    .card { max-width: 480px; text-align: center; padding: 0 16px; color: #374151; }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <h1>My existing Django site</h1>
+    <p>
+      This template is otherwise unchanged — only the two lines at the bottom
+      were added to get a floating chat bubble in the corner.
+    </p>
+  </div>
+
+  {% load db_chat_widget %}
+  {% db_chat_widget %}
+</body>
+</html>

django_db_chat_widget-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "django-db-chat-widget"
+version = "0.1.0"
+description = "Django integration for db-chat-widget: a natural-language database chatbot widget for Django templates."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    { name = "Armand Kouassi" },
+]
+keywords = ["django", "chatbot", "sql", "database", "llm", "nl2sql", "widget"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: Django",
+    "Framework :: Django :: 4.2",
+    "Framework :: Django :: 5.0",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Database",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+dependencies = [
+    "django>=4.2",
+    "db-chat-widget>=0.1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-django>=4.8",
+    "ruff>=0.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/krak225/django-db-chat-widget"
+Issues = "https://github.com/krak225/django-db-chat-widget/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/django_db_chat_widget"]
+
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "tests.settings"
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

django_db_chat_widget-0.1.0/src/django_db_chat_widget/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

django_db_chat_widget-0.1.0/src/django_db_chat_widget/apps.py

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class DjangoDbChatWidgetConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "django_db_chat_widget"
+    verbose_name = "DB Chat Widget"