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
