django-db-chat-widget 0.1.0__py3-none-any.whl

django_db_chat_widget/__init__.py

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

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"

django_db_chat_widget/conf.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote_plus
+
+from db_chat_widget import ChatEngine
+from db_chat_widget import Settings as ChatSettings
+from django.conf import settings as django_settings
+from django.core.exceptions import ImproperlyConfigured
+
+DEFAULTS: dict[str, Any] = {
+    # Which entry of Django's DATABASES to introspect/query, unless DB_URL is set.
+    "DB_ALIAS": "default",
+    # Explicit SQLAlchemy URL; overrides DB_ALIAS-based derivation when set.
+    "DB_URL": None,
+    "LLM_PROVIDER": "groq",
+    "LLM_MODEL": None,
+    "LLM_API_KEY": None,
+    "LLM_BASE_URL": None,
+    "READ_ONLY": True,
+    "MAX_ROWS": 200,
+    "ALLOWED_TABLES": None,
+    "TITLE": "Ask your database",
+}
+
+_ENGINE_TO_DIALECT = {
+    "django.db.backends.postgresql": "postgresql+psycopg2",
+    "django.db.backends.postgresql_psycopg2": "postgresql+psycopg2",
+    "django.contrib.gis.db.backends.postgis": "postgresql+psycopg2",
+    "django.db.backends.mysql": "mysql+pymysql",
+    "django.db.backends.sqlite3": "sqlite",
+}
+
+_engine_cache: ChatEngine | None = None
+
+
+def get_config() -> dict[str, Any]:
+    user_config = getattr(django_settings, "DB_CHAT_WIDGET", {})
+    return {**DEFAULTS, **user_config}
+
+
+def build_db_url_from_alias(alias: str) -> str:
+    """Translate a Django DATABASES[alias] entry into a SQLAlchemy connection URL.
+
+    Lets django-db-chat-widget reuse the host project's existing database
+    connection instead of duplicating credentials in a second place.
+    """
+    try:
+        db = django_settings.DATABASES[alias]
+    except KeyError as exc:
+        raise ImproperlyConfigured(
+            f"DB_CHAT_WIDGET['DB_ALIAS'] refers to unknown DATABASES alias '{alias}'."
+        ) from exc
+
+    engine = db.get("ENGINE", "")
+    dialect = _ENGINE_TO_DIALECT.get(engine)
+    if dialect is None:
+        raise ImproperlyConfigured(
+            f"db-chat-widget doesn't support the Django database engine '{engine}'. "
+            "Set DB_CHAT_WIDGET['DB_URL'] to an explicit SQLAlchemy URL instead."
+        )
+
+    if dialect == "sqlite":
+        return f"sqlite:///{db['NAME']}"
+
+    user = quote_plus(str(db.get("USER") or ""))
+    password = quote_plus(str(db.get("PASSWORD") or ""))
+    host = db.get("HOST") or "localhost"
+    port = db.get("PORT") or ""
+    name = db["NAME"]
+
+    auth = f"{user}:{password}@" if user else ""
+    port_part = f":{port}" if port else ""
+    return f"{dialect}://{auth}{host}{port_part}/{name}"
+
+
+def get_chat_engine() -> ChatEngine:
+    """Return a process-wide cached ChatEngine built from Django settings."""
+    global _engine_cache
+    if _engine_cache is not None:
+        return _engine_cache
+
+    config = get_config()
+    db_url = config["DB_URL"] or build_db_url_from_alias(config["DB_ALIAS"])
+
+    settings = ChatSettings(
+        db_url=db_url,
+        llm_provider=config["LLM_PROVIDER"],
+        llm_model=config["LLM_MODEL"],
+        llm_api_key=config["LLM_API_KEY"],
+        llm_base_url=config["LLM_BASE_URL"],
+        read_only=config["READ_ONLY"],
+        max_rows=config["MAX_ROWS"],
+        allowed_tables=config["ALLOWED_TABLES"],
+    )
+    _engine_cache = ChatEngine(settings)
+    return _engine_cache
+
+
+def reset_chat_engine_cache() -> None:
+    """Drop the cached ChatEngine, forcing it to be rebuilt on next use.
+
+    Mainly useful in tests, or after changing DB_CHAT_WIDGET settings at runtime.
+    """
+    global _engine_cache
+    _engine_cache = None

django_db_chat_widget/static/django_db_chat_widget/widget.css

@@ -0,0 +1,253 @@
+.dcw-widget {
+  --dcw-bg: #ffffff;
+  --dcw-fg: #1a1a1a;
+  --dcw-muted: #6b7280;
+  --dcw-border: #e5e7eb;
+  --dcw-accent: #2563eb;
+  --dcw-accent-fg: #ffffff;
+  --dcw-bubble-bot: #f3f4f6;
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  max-width: 480px;
+  height: 560px;
+  border: 1px solid var(--dcw-border);
+  border-radius: 12px;
+  background: var(--dcw-bg);
+  color: var(--dcw-fg);
+  overflow: hidden;
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.08);
+}
+
+@media (prefers-color-scheme: dark) {
+  .dcw-widget {
+    --dcw-bg: #17181c;
+    --dcw-fg: #e8e9ec;
+    --dcw-muted: #9ca3af;
+    --dcw-border: #2b2d33;
+    --dcw-bubble-bot: #24262c;
+  }
+}
+
+.dcw-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  padding: 12px 16px;
+  border-bottom: 1px solid var(--dcw-border);
+  font-weight: 600;
+  font-size: 14px;
+}
+
+.dcw-header-title {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.dcw-panel-close {
+  display: none;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  width: 28px;
+  height: 28px;
+  border: none;
+  border-radius: 6px;
+  background: transparent;
+  color: var(--dcw-fg);
+  cursor: pointer;
+}
+
+.dcw-panel-close:hover {
+  background: var(--dcw-bubble-bot);
+}
+
+.dcw-messages {
+  flex: 1;
+  overflow-y: auto;
+  padding: 12px;
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.dcw-bubble {
+  max-width: 88%;
+  padding: 8px 12px;
+  border-radius: 10px;
+  font-size: 14px;
+  line-height: 1.4;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.dcw-bubble.dcw-user {
+  align-self: flex-end;
+  background: var(--dcw-accent);
+  color: var(--dcw-accent-fg);
+}
+
+.dcw-bubble.dcw-bot {
+  align-self: flex-start;
+  background: var(--dcw-bubble-bot);
+}
+
+.dcw-bubble.dcw-error {
+  align-self: flex-start;
+  background: #fee2e2;
+  color: #991b1b;
+}
+
+.dcw-sql {
+  margin-top: 6px;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 12px;
+  color: var(--dcw-muted);
+  background: rgba(0, 0, 0, 0.04);
+  padding: 6px 8px;
+  border-radius: 6px;
+  overflow-x: auto;
+}
+
+.dcw-table-wrap {
+  margin-top: 8px;
+  overflow-x: auto;
+  max-height: 220px;
+  border: 1px solid var(--dcw-border);
+  border-radius: 6px;
+}
+
+.dcw-table {
+  border-collapse: collapse;
+  width: 100%;
+  font-size: 12px;
+}
+
+.dcw-table th, .dcw-table td {
+  padding: 6px 8px;
+  border-bottom: 1px solid var(--dcw-border);
+  text-align: left;
+  white-space: nowrap;
+}
+
+.dcw-table th {
+  position: sticky;
+  top: 0;
+  background: var(--dcw-bubble-bot);
+}
+
+.dcw-form {
+  display: flex;
+  gap: 8px;
+  padding: 12px;
+  border-top: 1px solid var(--dcw-border);
+}
+
+.dcw-input {
+  flex: 1;
+  padding: 8px 10px;
+  border: 1px solid var(--dcw-border);
+  border-radius: 8px;
+  background: var(--dcw-bg);
+  color: var(--dcw-fg);
+  font-size: 14px;
+}
+
+.dcw-send {
+  padding: 8px 14px;
+  border: none;
+  border-radius: 8px;
+  background: var(--dcw-accent);
+  color: var(--dcw-accent-fg);
+  font-size: 14px;
+  cursor: pointer;
+}
+
+.dcw-send:disabled {
+  opacity: 0.6;
+  cursor: default;
+}
+
+.dcw-typing {
+  align-self: flex-start;
+  color: var(--dcw-muted);
+  font-size: 13px;
+  font-style: italic;
+}
+
+/* Floating launcher (popup) mode */
+
+.dcw-launcher-btn {
+  position: fixed;
+  right: 20px;
+  bottom: 20px;
+  width: 56px;
+  height: 56px;
+  padding: 0;
+  border: none;
+  border-radius: 50%;
+  background: var(--dcw-accent);
+  color: var(--dcw-accent-fg);
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.25);
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 2147483000;
+  transition: transform 0.15s ease;
+}
+
+.dcw-launcher-btn:hover {
+  transform: scale(1.06);
+}
+
+.dcw-launcher-btn.dcw-pos-left {
+  right: auto;
+  left: 20px;
+}
+
+.dcw-launcher-panel {
+  position: fixed;
+  right: 20px;
+  bottom: 88px;
+  z-index: 2147483000;
+  transform-origin: bottom right;
+  transition: opacity 0.15s ease, transform 0.15s ease;
+  opacity: 1;
+  transform: scale(1) translateY(0);
+}
+
+.dcw-launcher-panel.dcw-pos-left {
+  right: auto;
+  left: 20px;
+  transform-origin: bottom left;
+}
+
+.dcw-launcher-panel.dcw-hidden {
+  opacity: 0;
+  transform: scale(0.95) translateY(8px);
+  pointer-events: none;
+  visibility: hidden;
+}
+
+.dcw-launcher-panel .dcw-panel-close {
+  display: flex;
+}
+
+@media (max-width: 520px) {
+  .dcw-launcher-panel {
+    right: 12px;
+    left: 12px;
+    bottom: 88px;
+    width: auto;
+    max-width: none;
+    height: min(70vh, 560px);
+  }
+
+  .dcw-launcher-panel.dcw-pos-left {
+    left: 12px;
+  }
+}

django_db_chat_widget/static/django_db_chat_widget/widget.js

@@ -0,0 +1,233 @@
+(function (global) {
+  "use strict";
+
+  // Captured synchronously while this <script> tag is executing — must not be
+  // read lazily inside an async callback, since document.currentScript is only
+  // valid during the script's own top-level execution.
+  const scriptEl = document.currentScript;
+
+  const CHAT_ICON =
+    '<svg viewBox="0 0 24 24" width="26" height="26" fill="none" stroke="currentColor" ' +
+    'stroke-width="2" stroke-linecap="round" stroke-linejoin="round">' +
+    '<path d="M21 11.5a8.38 8.38 0 0 1-.9 3.8 8.5 8.5 0 0 1-7.6 4.7 8.38 8.38 0 0 1-3.8-.9L3 21l1.9-5.7a8.38 8.38 0 0 1-.9-3.8 8.5 8.5 0 0 1 4.7-7.6 8.38 8.38 0 0 1 3.8-.9h.5a8.48 8.48 0 0 1 8 8v.5z"/>' +
+    "</svg>";
+
+  const CLOSE_ICON =
+    '<svg viewBox="0 0 24 24" width="22" height="22" fill="none" stroke="currentColor" ' +
+    'stroke-width="2" stroke-linecap="round" stroke-linejoin="round">' +
+    '<line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/>' +
+    "</svg>";
+
+  function el(tag, attrs, children) {
+    const node = document.createElement(tag);
+    if (attrs) {
+      Object.keys(attrs).forEach((key) => {
+        const value = attrs[key];
+        if (value === undefined || value === null) return;
+        if (key === "class") node.className = value;
+        else node.setAttribute(key, value);
+      });
+    }
+    (children || []).forEach((child) => {
+      if (child == null) return;
+      node.appendChild(typeof child === "string" ? document.createTextNode(child) : child);
+    });
+    return node;
+  }
+
+  function iconButton(svgMarkup, attrs) {
+    const btn = el("button", attrs);
+    btn.innerHTML = svgMarkup; // static, trusted markup defined above — not user input
+    return btn;
+  }
+
+  function getCookie(name) {
+    const match = document.cookie.match("(?:^|; )" + name + "=([^;]*)");
+    return match ? decodeURIComponent(match[1]) : null;
+  }
+
+  function renderTable(columns, rows) {
+    const thead = el("thead", null, [
+      el("tr", null, columns.map((c) => el("th", null, [c]))),
+    ]);
+    const tbody = el(
+      "tbody",
+      null,
+      rows.map((row) =>
+        el(
+          "tr",
+          null,
+          columns.map((c) => el("td", null, [row[c] === null || row[c] === undefined ? "" : String(row[c])]))
+        )
+      )
+    );
+    return el("div", { class: "dcw-table-wrap" }, [el("table", { class: "dcw-table" }, [thead, tbody])]);
+  }
+
+  function buildChatPanel(opts, headerExtras) {
+    const messages = el("div", { class: "dcw-messages" });
+    const input = el("input", { class: "dcw-input", type: "text", placeholder: opts.placeholder });
+    const sendBtn = el("button", { class: "dcw-send", type: "submit" }, ["Send"]);
+    const form = el("form", { class: "dcw-form" }, [input, sendBtn]);
+
+    const header = el("div", { class: "dcw-header" }, [
+      el("span", { class: "dcw-header-title" }, [opts.title]),
+      ...(headerExtras || []),
+    ]);
+
+    const widget = el("div", { class: "dcw-widget" }, [header, messages, form]);
+
+    function addBubble(text, kind) {
+      const bubble = el("div", { class: "dcw-bubble dcw-" + kind }, [text]);
+      messages.appendChild(bubble);
+      messages.scrollTop = messages.scrollHeight;
+      return bubble;
+    }
+
+    async function ask(question) {
+      addBubble(question, "user");
+      const typing = el("div", { class: "dcw-typing" }, ["Thinking..."]);
+      messages.appendChild(typing);
+      messages.scrollTop = messages.scrollHeight;
+
+      input.disabled = true;
+      sendBtn.disabled = true;
+
+      try {
+        const csrfToken = getCookie(opts.csrfCookieName);
+        const headers = { "Content-Type": "application/json" };
+        if (csrfToken) headers["X-CSRFToken"] = csrfToken;
+
+        const response = await fetch(opts.apiUrl, {
+          method: "POST",
+          headers,
+          credentials: "same-origin",
+          body: JSON.stringify({ question }),
+        });
+        const data = await response.json();
+        typing.remove();
+
+        if (!response.ok) {
+          addBubble(data.detail || "Request failed.", "error");
+          return;
+        }
+
+        if (data.error) {
+          addBubble(data.answer || "Something went wrong.", "error");
+          return;
+        }
+
+        const botBubble = addBubble(data.answer || "", "bot");
+        if (opts.showSql && data.sql) {
+          botBubble.appendChild(el("div", { class: "dcw-sql" }, [data.sql]));
+        }
+        if (data.rows && data.rows.length) {
+          botBubble.appendChild(renderTable(data.columns, data.rows));
+        }
+        messages.scrollTop = messages.scrollHeight;
+      } catch (err) {
+        typing.remove();
+        addBubble("Network error: could not reach the chat API.", "error");
+      } finally {
+        input.disabled = false;
+        sendBtn.disabled = false;
+        input.focus();
+      }
+    }
+
+    form.addEventListener("submit", (event) => {
+      event.preventDefault();
+      const question = input.value.trim();
+      if (!question) return;
+      input.value = "";
+      ask(question);
+    });
+
+    return { ask, element: widget, focusInput: () => input.focus() };
+  }
+
+  function createInlineWidget(opts) {
+    const target = typeof opts.target === "string" ? document.querySelector(opts.target) : opts.target;
+    if (!target) {
+      console.error("db-chat-widget: target element not found:", opts.target);
+      return null;
+    }
+    const panel = buildChatPanel(opts);
+    target.innerHTML = "";
+    target.appendChild(panel.element);
+    return panel;
+  }
+
+  function createLauncherWidget(opts) {
+    let open = false;
+
+    const closeBtn = iconButton(CLOSE_ICON, { class: "dcw-panel-close", type: "button", "aria-label": "Close chat" });
+    const panel = buildChatPanel(opts, [closeBtn]);
+    panel.element.classList.add("dcw-launcher-panel", "dcw-hidden");
+    if (opts.position === "bottom-left") panel.element.classList.add("dcw-pos-left");
+
+    const launcherBtn = iconButton(CHAT_ICON, { class: "dcw-launcher-btn", type: "button", "aria-label": "Open chat" });
+    if (opts.position === "bottom-left") launcherBtn.classList.add("dcw-pos-left");
+
+    function setOpen(next) {
+      open = next;
+      panel.element.classList.toggle("dcw-hidden", !open);
+      launcherBtn.innerHTML = open ? CLOSE_ICON : CHAT_ICON;
+      launcherBtn.setAttribute("aria-label", open ? "Close chat" : "Open chat");
+      if (open) panel.focusInput();
+    }
+
+    launcherBtn.addEventListener("click", () => setOpen(!open));
+    closeBtn.addEventListener("click", () => setOpen(false));
+
+    document.body.appendChild(panel.element);
+    document.body.appendChild(launcherBtn);
+
+    return { ask: panel.ask, element: panel.element, open: () => setOpen(true), close: () => setOpen(false) };
+  }
+
+  function createWidget(options) {
+    const opts = Object.assign(
+      {
+        apiUrl: "/api/chat",
+        title: "Ask your database",
+        placeholder: "Ask a question about your data...",
+        showSql: true,
+        mode: options && options.target ? "inline" : "bubble",
+        position: "bottom-right",
+        csrfCookieName: "csrftoken",
+      },
+      options
+    );
+
+    return opts.mode === "bubble" ? createLauncherWidget(opts) : createInlineWidget(opts);
+  }
+
+  const DBChatWidget = { init: createWidget };
+  global.DBChatWidget = DBChatWidget;
+
+  function autoInit() {
+    if (!scriptEl || !scriptEl.dataset) return;
+    const ds = scriptEl.dataset;
+    if (!ds.target && !ds.mode) return; // nothing declared on the tag, skip auto-init
+
+    // Only include keys that were actually set on the tag — Object.assign (used by
+    // createWidget to merge in defaults) treats an explicit `undefined` value as
+    // present, so passing it here would wipe out the corresponding default.
+    const options = { apiUrl: ds.apiUrl || "/api/chat", showSql: ds.showSql !== "false" };
+    if (ds.target) options.target = ds.target;
+    if (ds.title) options.title = ds.title;
+    if (ds.placeholder) options.placeholder = ds.placeholder;
+    if (ds.mode) options.mode = ds.mode;
+    if (ds.position) options.position = ds.position;
+    if (ds.csrfCookieName) options.csrfCookieName = ds.csrfCookieName;
+
+    createWidget(options);
+  }
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", autoInit);
+  } else {
+    autoInit();
+  }
+})(window);

django_db_chat_widget/templatetags/db_chat_widget.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from django import template
+from django.middleware.csrf import get_token
+from django.templatetags.static import static
+from django.urls import reverse
+from django.utils.html import format_html, format_html_join
+from django.utils.safestring import SafeString
+
+from ..conf import get_config
+
+register = template.Library()
+
+
+@register.simple_tag(takes_context=True)
+def db_chat_widget(
+    context: template.Context,
+    mode: str | None = None,
+    title: str | None = None,
+    position: str | None = None,
+    placeholder: str | None = None,
+    target: str | None = None,
+) -> SafeString:
+    """Render the <link>/<script> tags that embed the db-chat-widget.
+
+    Usage in a template:
+
+        {% load db_chat_widget %}
+        {% db_chat_widget %}                      {# floating popup, bottom-right #}
+        {% db_chat_widget position="bottom-left" %}
+        {% db_chat_widget target="#my-chat-div" %} {# inline mode instead of popup #}
+
+    Requires 'django.template.context_processors.request' in TEMPLATES so the
+    tag can access the current request to set the CSRF cookie the widget needs.
+    """
+    request = context.get("request")
+    if request is not None:
+        # Force the csrftoken cookie to be set on this response, even if no
+        # {% csrf_token %} is rendered elsewhere on the page.
+        get_token(request)
+
+    config = get_config()
+    api_url = reverse("db_chat_widget:chat")
+
+    data_attrs = {
+        "data-mode": mode or ("inline" if target else "bubble"),
+        "data-api-url": api_url,
+        "data-title": title or config["TITLE"],
+    }
+    if position:
+        data_attrs["data-position"] = position
+    if placeholder:
+        data_attrs["data-placeholder"] = placeholder
+    if target:
+        data_attrs["data-target"] = target
+
+    attrs_html = format_html_join(" ", '{}="{}"', data_attrs.items())
+
+    return format_html(
+        '<link rel="stylesheet" href="{}">\n<script src="{}" {}></script>',
+        static("django_db_chat_widget/widget.css"),
+        static("django_db_chat_widget/widget.js"),
+        attrs_html,
+    )

django_db_chat_widget/urls.py

@@ -0,0 +1,10 @@
+from django.urls import path
+
+from . import views
+
+app_name = "db_chat_widget"
+
+urlpatterns = [
+    path("chat/", views.chat, name="chat"),
+    path("health/", views.health, name="health"),
+]

django_db_chat_widget/views.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import json
+
+from django.http import HttpRequest, HttpResponseBadRequest, JsonResponse
+from django.views.decorators.http import require_GET, require_POST
+
+from .conf import get_chat_engine
+
+
+@require_GET
+def health(request: HttpRequest) -> JsonResponse:
+    return JsonResponse({"status": "ok"})
+
+
+@require_POST
+def chat(request: HttpRequest) -> JsonResponse:
+    """Answer a natural-language question about the database.
+
+    Relies on Django's normal CSRF protection (the request must carry a valid
+    X-CSRFToken header/cookie pair) — see the `db_chat_widget` template tag,
+    which ensures the CSRF cookie is set on the page that embeds the widget.
+    """
+    try:
+        payload = json.loads(request.body or b"{}")
+    except json.JSONDecodeError:
+        return HttpResponseBadRequest("Invalid JSON body")
+
+    question = str(payload.get("question") or "").strip()
+    if not question:
+        return HttpResponseBadRequest("question must not be empty")
+
+    engine = get_chat_engine()
+    result = engine.ask(question)
+    return JsonResponse(result.to_dict())

django_db_chat_widget-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+django_db_chat_widget/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+django_db_chat_widget/apps.py,sha256=jy9IElALPg0N62hfR--Rsm3EjTtbs86WrPRE4Yak_NU,207
+django_db_chat_widget/conf.py,sha256=G8piI17bFj9J6eQU5d4Kh5Yh0h0IEtKyYQ1Ta5jWTSg,3477
+django_db_chat_widget/urls.py,sha256=WJoXwVgMACFpWgsDdWG4hSy_qNGmyf4511nqRaK3sBE,192
+django_db_chat_widget/views.py,sha256=1lyHYDnoAcgUt2jHQgjWrbV3zPE-VfCK-rKT4tTj6wQ,1110
+django_db_chat_widget/static/django_db_chat_widget/widget.css,sha256=Hz3WJl5Vzke_951wMvkoxbnFFo4d9UeCYbRGahfvOg0,4597
+django_db_chat_widget/static/django_db_chat_widget/widget.js,sha256=fz4Cftw2ivS7Q5-weNqZGcKytwcRk3FPxabSMBjhU-Y,8330
+django_db_chat_widget/templatetags/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_db_chat_widget/templatetags/db_chat_widget.py,sha256=m9IWFkxJWJzIaagkPFujokqlugHl9z1rGOqP0aWN1Zk,2117
+django_db_chat_widget-0.1.0.dist-info/METADATA,sha256=RReSfUf7jAQWEeExiXSuRflZckeNsu-blAT1V8UpdMM,5236
+django_db_chat_widget-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+django_db_chat_widget-0.1.0.dist-info/licenses/LICENSE,sha256=oAyChCkTJwAuvSVkMD9o5yvn7UpAfk8FrC3mmFE6Pbw,1071
+django_db_chat_widget-0.1.0.dist-info/RECORD,,

django_db_chat_widget-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

django_db_chat_widget-0.1.0.dist-info/licenses/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.