kolossus-chat-django 1.3.0__tar.gz

kolossus_chat_django-1.3.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Kolossus AI
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

kolossus_chat_django-1.3.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md LICENSE runtests.py
+recursive-include kolossus_chat/templates *.html
+# Present only in copies downloaded from the Kolossus dashboard.
+include kolossus_chat/kolossus-config.json
+recursive-include tests *.py
+global-exclude __pycache__ *.py[cod]

kolossus_chat_django-1.3.0/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: kolossus-chat-django
+Version: 1.3.0
+Summary: Add a KolossusAI chat assistant to your Django site with one command.
+Author: Kolossus AI
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://kolossus.ai
+Keywords: django,chatbot,ai,chat,assistant,kolossus
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Django>=4.2
+Dynamic: license-file
+
+# KolossusAI Chat for Django
+
+Add a Kolossus AI assistant to your Django site, as a chat bubble on every page or as
+a button wherever you place a template tag.
+
+* Set up with one command: the chat bubble then shows on every page, with no
+  template changes.
+* Or chat buttons only where you want them, with a template tag.
+* Bubble, sidebar or bottom-bar layout, light / dark / automatic theme and accent
+  colour: set in your Kolossus dashboard, or overridden in settings.
+* Bubble on the bottom right or left, its distance from the edges, and its size.
+* What happens on page load: remember each visitor's last state, always open, or
+  start minimized.
+* Optional: logged-in users chat under their own name with their history kept. The
+  widget secret stays on your server; only an HMAC signature reaches the browser.
+
+You need a Kolossus account and a widget created in the Kolossus dashboard.
+
+## Install with one command
+
+In Kolossus, open your widget's **Plugins → Django → Copy command**. Then, in your
+project folder (the one with `manage.py`) and with your project's virtualenv active,
+paste and run it. It looks like this, with your own widget token:
+
+```sh
+pip install kolossus-chat-django && kolossus-chat-setup wt_YOUR_WIDGET_TOKEN
+```
+
+Restart your site, and the chat bubble shows on every page. (In Windows PowerShell 5,
+which has no `&&`, run the two commands one after the other.)
+
+The Host URL defaults to the Kolossus cloud (`https://engine.kolossus.ai`). For another
+Kolossus server, add `--host https://your-kolossus-server`; the copied command already
+has it when you need it.
+
+You can also download the plugin as a zip from the same Plugins sheet; it holds your
+Host URL and widget token, so there the command is
+`pip install kolossus-chat-django.zip && kolossus-chat-setup`.
+
+`kolossus-chat-setup` (also `python -m kolossus_chat`) never changes your existing
+lines. It saves a backup (`settings.py.kolossus-backup`) and adds one marked block to
+the end of your settings file:
+
+* `kolossus_chat` in `INSTALLED_APPS` and `KolossusChatMiddleware` in `MIDDLEWARE`,
+  each only if missing;
+* your Host URL and widget token in `KOLOSSUS_CHAT`, so they are kept when you later
+  upgrade (`pip install -U kolossus-chat-django`). Values you set yourself win,
+  except empty ones.
+
+Running it again changes nothing, except with another widget token or host (or a newer
+zip from the dashboard): then it updates the Host URL and widget token in the block.
+`kolossus-chat-setup --undo` removes the block. If
+your project keeps settings in several files (for example `settings/prod.py`), run it
+for each one: `kolossus-chat-setup --settings mysite.settings.prod`.
+
+The middleware adds the chat just before `</body>` of every full HTML page. It leaves
+alone Django admin sites, the Django REST framework browsable API, API docs pages
+(drf-spectacular, drf-yasg, django-ninja), non-HTML responses (JSON, files,
+downloads), error pages, and any page that already uses a `kolossus_chat` template
+tag or has a `data-kolossus` element or the widget script. To leave out more pages,
+list their URL prefixes in `"EXCLUDE_PATHS"`, for example `["/checkout/"]`. To turn
+the site-wide bubble off and place the chat only with template tags, set
+`"SITEWIDE": False`.
+
+## Install by hand
+
+```sh
+pip install kolossus-chat-django
+```
+
+Add the app and make sure the `request` context processor is enabled (it is in
+Django's default project template). Add the middleware for a bubble on every page, or
+leave it out and use the template tags below:
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "kolossus_chat",
+]
+
+MIDDLEWARE = [
+    # ...
+    "kolossus_chat.middleware.KolossusChatMiddleware",  # optional: bubble on every page
+]
+
+TEMPLATES = [
+    {
+        "BACKEND": "django.template.backends.django.DjangoTemplates",
+        "APP_DIRS": True,
+        "OPTIONS": {
+            "context_processors": [
+                "django.template.context_processors.request",
+                # ...
+            ],
+        },
+    },
+]
+```
+
+## Settings
+
+1. In your Kolossus dashboard, create a widget for your assistant and add your site's
+   domain (for example `example.org`) to its **allowed domains**.
+2. Add its Host URL and public widget token to `settings.py`:
+
+```python
+KOLOSSUS_CHAT = {
+    "HOST_URL": "https://app.kolossus.ai",  # your Kolossus server; https:// only
+    "WIDGET_TOKEN": "wt_...",               # the public token, starts with wt_
+
+    # Optional
+    "WIDGET_SECRET": os.environ.get("KOLOSSUS_WIDGET_SECRET", ""),  # ws_..., verified chat
+    "THEME": "",              # "" = follow the visitor's device, "light", "dark"
+    "PRIMARY_COLOR": "",      # "" = dashboard colour, or "#rrggbb"
+    "LAYOUT": "",             # "" = dashboard layout, "bubble", "sidebar", "bottom_bar"
+    "OPEN_ON_LOAD": "remember",  # "remember", "open", "closed"
+    "SITEWIDE": True,         # False = the middleware adds nothing; use the template tags
+    "EXCLUDE_PATHS": [],      # URL prefixes without the bubble, e.g. ["/checkout/"]
+    "POSITION": "",           # bubble corner: "" = bottom right, "right", "left"
+    "OFFSET_X": "",           # bubble distance from the side edge, 0-1000 px ("" = 24)
+    "OFFSET_Y": "",           # bubble distance from the bottom edge, 0-1000 px ("" = 24)
+    "BUBBLE_SIZE": "",        # "" = medium, "small", "medium", "large"
+}
+```
+
+Anything left empty uses the look set for the widget in your Kolossus dashboard.
+`POSITION`, `OFFSET_X`, `OFFSET_Y` and `BUBBLE_SIZE` apply to the bubble layout.
+`http://` is accepted only for a Kolossus server on `localhost` (local testing).
+Invalid values are ignored with a logged warning, and `manage.py check` reports them
+(`kolossus_chat.W001` to `W015`).
+
+| `OPEN_ON_LOAD` | On page load or refresh |
+|---|---|
+| `remember` (default) | As the visitor last left it (open or minimized); open on a first visit |
+| `open` | Always open |
+| `closed` | Only the bubble or tab shows until the visitor clicks it |
+
+Clicking a chat button always opens the chat.
+
+### The widget secret
+
+`WIDGET_SECRET` is optional. When it is set, each logged-in user's email is signed
+with it (HMAC-SHA256) and the signature is passed to the chat. Kolossus checks the
+signature, so those users get a verified chat under their own name and keep their
+history. Visitors who are not logged in chat anonymously.
+
+Keep the secret on the server: load it from an environment variable, never commit
+it, and never put it in a template or `WIDGET_TOKEN`. The tags only ever output the
+public token and the signature.
+
+## Use in templates
+
+Not needed with the middleware. Use them to place the chat yourself:
+
+```django
+{% load kolossus_chat %}
+
+{# Chat bubble: put it in your base template, before </body> #}
+{% kolossus_chat_widget %}
+
+{# A button that opens the chat #}
+{% kolossus_chat_button "Ask our assistant" class="btn btn-primary" %}
+
+{# Only the widget script, if you write your own data-kolossus trigger elements #}
+{% kolossus_chat_script %}
+```
+
+The widget script is output once per request, however many tags a page uses. Without
+a valid `HOST_URL` and `WIDGET_TOKEN` the tags output nothing.
+
+To hide the bubble on some pages, list them in `"EXCLUDE_PATHS"`. Or set
+`"SITEWIDE": False` and leave `{% kolossus_chat_widget %}` out of those templates (for
+example with a `{% block %}` that the page overrides).
+
+## Content Security Policy
+
+If your site sends a CSP header, allow your Kolossus host in `script-src` and in
+`connect-src`, both `https://` and `wss://` (the chat uses a WebSocket):
+
+```
+script-src 'self' https://app.kolossus.ai;
+connect-src 'self' https://app.kolossus.ai wss://app.kolossus.ai;
+```
+
+## Privacy
+
+This package connects your site to the Kolossus service. The chat script
+(`widget.js`) loads from your Kolossus Host URL. When the page loads, the visitor's
+browser sends your widget token to load the chat settings. When the visitor chats, it
+sends their messages, any files they attach, their IP address and approximate
+location (city and country) to the Kolossus server so the assistant can reply. With
+`WIDGET_SECRET` set, logged-in users' email, name and signature are sent too. Answers
+are generated by AI and may be inaccurate. Mention this in your privacy policy.
+
+Kolossus terms of service: https://kolossus.ai/terms. Privacy policy:
+https://kolossus.ai/privacy.
+
+## Development
+
+```sh
+python runtests.py
+```
+
+## Licence
+
+BSD 3-Clause. See `LICENSE`.

kolossus_chat_django-1.3.0/README.md

@@ -0,0 +1,206 @@
+# KolossusAI Chat for Django
+
+Add a Kolossus AI assistant to your Django site, as a chat bubble on every page or as
+a button wherever you place a template tag.
+
+* Set up with one command: the chat bubble then shows on every page, with no
+  template changes.
+* Or chat buttons only where you want them, with a template tag.
+* Bubble, sidebar or bottom-bar layout, light / dark / automatic theme and accent
+  colour: set in your Kolossus dashboard, or overridden in settings.
+* Bubble on the bottom right or left, its distance from the edges, and its size.
+* What happens on page load: remember each visitor's last state, always open, or
+  start minimized.
+* Optional: logged-in users chat under their own name with their history kept. The
+  widget secret stays on your server; only an HMAC signature reaches the browser.
+
+You need a Kolossus account and a widget created in the Kolossus dashboard.
+
+## Install with one command
+
+In Kolossus, open your widget's **Plugins → Django → Copy command**. Then, in your
+project folder (the one with `manage.py`) and with your project's virtualenv active,
+paste and run it. It looks like this, with your own widget token:
+
+```sh
+pip install kolossus-chat-django && kolossus-chat-setup wt_YOUR_WIDGET_TOKEN
+```
+
+Restart your site, and the chat bubble shows on every page. (In Windows PowerShell 5,
+which has no `&&`, run the two commands one after the other.)
+
+The Host URL defaults to the Kolossus cloud (`https://engine.kolossus.ai`). For another
+Kolossus server, add `--host https://your-kolossus-server`; the copied command already
+has it when you need it.
+
+You can also download the plugin as a zip from the same Plugins sheet; it holds your
+Host URL and widget token, so there the command is
+`pip install kolossus-chat-django.zip && kolossus-chat-setup`.
+
+`kolossus-chat-setup` (also `python -m kolossus_chat`) never changes your existing
+lines. It saves a backup (`settings.py.kolossus-backup`) and adds one marked block to
+the end of your settings file:
+
+* `kolossus_chat` in `INSTALLED_APPS` and `KolossusChatMiddleware` in `MIDDLEWARE`,
+  each only if missing;
+* your Host URL and widget token in `KOLOSSUS_CHAT`, so they are kept when you later
+  upgrade (`pip install -U kolossus-chat-django`). Values you set yourself win,
+  except empty ones.
+
+Running it again changes nothing, except with another widget token or host (or a newer
+zip from the dashboard): then it updates the Host URL and widget token in the block.
+`kolossus-chat-setup --undo` removes the block. If
+your project keeps settings in several files (for example `settings/prod.py`), run it
+for each one: `kolossus-chat-setup --settings mysite.settings.prod`.
+
+The middleware adds the chat just before `</body>` of every full HTML page. It leaves
+alone Django admin sites, the Django REST framework browsable API, API docs pages
+(drf-spectacular, drf-yasg, django-ninja), non-HTML responses (JSON, files,
+downloads), error pages, and any page that already uses a `kolossus_chat` template
+tag or has a `data-kolossus` element or the widget script. To leave out more pages,
+list their URL prefixes in `"EXCLUDE_PATHS"`, for example `["/checkout/"]`. To turn
+the site-wide bubble off and place the chat only with template tags, set
+`"SITEWIDE": False`.
+
+## Install by hand
+
+```sh
+pip install kolossus-chat-django
+```
+
+Add the app and make sure the `request` context processor is enabled (it is in
+Django's default project template). Add the middleware for a bubble on every page, or
+leave it out and use the template tags below:
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "kolossus_chat",
+]
+
+MIDDLEWARE = [
+    # ...
+    "kolossus_chat.middleware.KolossusChatMiddleware",  # optional: bubble on every page
+]
+
+TEMPLATES = [
+    {
+        "BACKEND": "django.template.backends.django.DjangoTemplates",
+        "APP_DIRS": True,
+        "OPTIONS": {
+            "context_processors": [
+                "django.template.context_processors.request",
+                # ...
+            ],
+        },
+    },
+]
+```
+
+## Settings
+
+1. In your Kolossus dashboard, create a widget for your assistant and add your site's
+   domain (for example `example.org`) to its **allowed domains**.
+2. Add its Host URL and public widget token to `settings.py`:
+
+```python
+KOLOSSUS_CHAT = {
+    "HOST_URL": "https://app.kolossus.ai",  # your Kolossus server; https:// only
+    "WIDGET_TOKEN": "wt_...",               # the public token, starts with wt_
+
+    # Optional
+    "WIDGET_SECRET": os.environ.get("KOLOSSUS_WIDGET_SECRET", ""),  # ws_..., verified chat
+    "THEME": "",              # "" = follow the visitor's device, "light", "dark"
+    "PRIMARY_COLOR": "",      # "" = dashboard colour, or "#rrggbb"
+    "LAYOUT": "",             # "" = dashboard layout, "bubble", "sidebar", "bottom_bar"
+    "OPEN_ON_LOAD": "remember",  # "remember", "open", "closed"
+    "SITEWIDE": True,         # False = the middleware adds nothing; use the template tags
+    "EXCLUDE_PATHS": [],      # URL prefixes without the bubble, e.g. ["/checkout/"]
+    "POSITION": "",           # bubble corner: "" = bottom right, "right", "left"
+    "OFFSET_X": "",           # bubble distance from the side edge, 0-1000 px ("" = 24)
+    "OFFSET_Y": "",           # bubble distance from the bottom edge, 0-1000 px ("" = 24)
+    "BUBBLE_SIZE": "",        # "" = medium, "small", "medium", "large"
+}
+```
+
+Anything left empty uses the look set for the widget in your Kolossus dashboard.
+`POSITION`, `OFFSET_X`, `OFFSET_Y` and `BUBBLE_SIZE` apply to the bubble layout.
+`http://` is accepted only for a Kolossus server on `localhost` (local testing).
+Invalid values are ignored with a logged warning, and `manage.py check` reports them
+(`kolossus_chat.W001` to `W015`).
+
+| `OPEN_ON_LOAD` | On page load or refresh |
+|---|---|
+| `remember` (default) | As the visitor last left it (open or minimized); open on a first visit |
+| `open` | Always open |
+| `closed` | Only the bubble or tab shows until the visitor clicks it |
+
+Clicking a chat button always opens the chat.
+
+### The widget secret
+
+`WIDGET_SECRET` is optional. When it is set, each logged-in user's email is signed
+with it (HMAC-SHA256) and the signature is passed to the chat. Kolossus checks the
+signature, so those users get a verified chat under their own name and keep their
+history. Visitors who are not logged in chat anonymously.
+
+Keep the secret on the server: load it from an environment variable, never commit
+it, and never put it in a template or `WIDGET_TOKEN`. The tags only ever output the
+public token and the signature.
+
+## Use in templates
+
+Not needed with the middleware. Use them to place the chat yourself:
+
+```django
+{% load kolossus_chat %}
+
+{# Chat bubble: put it in your base template, before </body> #}
+{% kolossus_chat_widget %}
+
+{# A button that opens the chat #}
+{% kolossus_chat_button "Ask our assistant" class="btn btn-primary" %}
+
+{# Only the widget script, if you write your own data-kolossus trigger elements #}
+{% kolossus_chat_script %}
+```
+
+The widget script is output once per request, however many tags a page uses. Without
+a valid `HOST_URL` and `WIDGET_TOKEN` the tags output nothing.
+
+To hide the bubble on some pages, list them in `"EXCLUDE_PATHS"`. Or set
+`"SITEWIDE": False` and leave `{% kolossus_chat_widget %}` out of those templates (for
+example with a `{% block %}` that the page overrides).
+
+## Content Security Policy
+
+If your site sends a CSP header, allow your Kolossus host in `script-src` and in
+`connect-src`, both `https://` and `wss://` (the chat uses a WebSocket):
+
+```
+script-src 'self' https://app.kolossus.ai;
+connect-src 'self' https://app.kolossus.ai wss://app.kolossus.ai;
+```
+
+## Privacy
+
+This package connects your site to the Kolossus service. The chat script
+(`widget.js`) loads from your Kolossus Host URL. When the page loads, the visitor's
+browser sends your widget token to load the chat settings. When the visitor chats, it
+sends their messages, any files they attach, their IP address and approximate
+location (city and country) to the Kolossus server so the assistant can reply. With
+`WIDGET_SECRET` set, logged-in users' email, name and signature are sent too. Answers
+are generated by AI and may be inaccurate. Mention this in your privacy policy.
+
+Kolossus terms of service: https://kolossus.ai/terms. Privacy policy:
+https://kolossus.ai/privacy.
+
+## Development
+
+```sh
+python runtests.py
+```
+
+## Licence
+
+BSD 3-Clause. See `LICENSE`.

kolossus_chat_django-1.3.0/kolossus_chat/__init__.py

@@ -0,0 +1,3 @@
+"""KolossusAI Chat for Django: template tags that embed the Kolossus chat widget."""
+
+__version__ = "1.3.0"

kolossus_chat_django-1.3.0/kolossus_chat/__main__.py

@@ -0,0 +1,6 @@
+"""python -m kolossus_chat: the same as kolossus-chat-setup."""
+import sys
+
+from .setup_cli import main
+
+sys.exit(main())

kolossus_chat_django-1.3.0/kolossus_chat/apps.py

@@ -0,0 +1,10 @@
+from django.apps import AppConfig
+
+
+class KolossusChatConfig(AppConfig):
+    name = "kolossus_chat"
+    verbose_name = "KolossusAI Chat"
+
+    def ready(self):
+        # Registers the configuration system check.
+        from . import checks  # noqa: F401

kolossus_chat_django-1.3.0/kolossus_chat/checks.py

@@ -0,0 +1,20 @@
+from django.core.checks import Tags, Warning, register
+
+from .conf import W_NOT_CONFIGURED, load_config
+
+
+@register(Tags.templates)
+def check_kolossus_chat_settings(app_configs=None, **kwargs):
+    """Warn about a missing or invalid KOLOSSUS_CHAT setting."""
+    cfg = load_config()
+    messages = [
+        Warning(message, hint="See the KOLOSSUS_CHAT section of the kolossus-chat-django README.", id=f"kolossus_chat.{code}")
+        for code, message in cfg.problems
+    ]
+    if not cfg.configured:
+        messages.append(Warning(
+            "KolossusAI Chat is not showing yet: set KOLOSSUS_CHAT['HOST_URL'] and KOLOSSUS_CHAT['WIDGET_TOKEN'].",
+            hint="Copy both from the widget in your Kolossus dashboard.",
+            id=f"kolossus_chat.{W_NOT_CONFIGURED}",
+        ))
+    return messages