django-chat-ui 0.1.0__py3-none-any.whl

django_chat_ui/__init__.py

@@ -0,0 +1,2 @@
+"""A reusable chat interface over one protocol (docs/protocol.md), and a
+Django backend for it."""

django_chat_ui/admin.py

@@ -0,0 +1,86 @@
+"""The conversations in the admin: to look at them, not to chat (changes
+made here reach no open interface; use the services or the chat).
+
+With models of a site's own (``CHAT_UI_CONVERSATION_MODEL``,
+``CHAT_UI_PARTICIPANT_MODEL``), register them with these classes, as one
+does with ``UserAdmin``:
+
+    @admin.register(Ticket)
+    class TicketAdmin(ConversationAdmin):
+        list_display = [*ConversationAdmin.list_display, "priority"]
+"""
+
+from django.contrib import admin
+
+from .models import (
+    Conversation,
+    Media,
+    Membership,
+    Participant,
+    RoomEvent,
+    StreamEntry,
+)
+
+
+class ParticipantAdmin(admin.ModelAdmin):
+    list_display = ["__str__", "kind", "handle", "user", "created"]
+    list_filter = ["kind"]
+    search_fields = ["name", "handle"]
+    raw_id_fields = ["user"]
+
+
+class MembershipInline(admin.TabularInline):
+    model = Membership
+    extra = 0
+    raw_id_fields = ["participant", "last_read"]
+
+
+class RoomEventInline(admin.TabularInline):
+    model = RoomEvent
+    fk_name = "conversation"
+    extra = 0
+    fields = ["created", "sender", "type", "content"]
+    readonly_fields = ["created", "sender", "type", "content"]
+    can_delete = False
+    show_change_link = True
+
+    def has_add_permission(self, request, obj=None):
+        return False
+
+
+class ConversationAdmin(admin.ModelAdmin):
+    list_display = ["__str__", "channel", "state", "updated"]
+    list_filter = ["channel", "state"]
+    search_fields = ["title"]
+    inlines = [MembershipInline, RoomEventInline]
+
+
+def register_models(site: admin.AdminSite) -> None:
+    """This package's models, unless a site swapped them for its own."""
+    if not Participant._meta.swapped:
+        site.register(Participant, ParticipantAdmin)
+    if not Conversation._meta.swapped:
+        site.register(Conversation, ConversationAdmin)
+
+
+register_models(admin.site)
+
+
+@admin.register(RoomEvent)
+class RoomEventAdmin(admin.ModelAdmin):
+    list_display = ["__str__", "type", "conversation", "sender", "created"]
+    list_filter = ["type", "conversation__channel"]
+    raw_id_fields = ["conversation", "sender", "relates_to", "redacted_by"]
+
+
+@admin.register(Media)
+class MediaAdmin(admin.ModelAdmin):
+    list_display = ["name", "conversation", "mime", "size", "created"]
+    raw_id_fields = ["conversation", "uploader"]
+
+
+@admin.register(StreamEntry)
+class StreamEntryAdmin(admin.ModelAdmin):
+    list_display = ["__str__", "kind", "type", "conversation", "recipient", "created"]
+    list_filter = ["kind"]
+    raw_id_fields = ["conversation", "recipient", "event"]

django_chat_ui/agui.py

@@ -0,0 +1,180 @@
+"""An AI agent of any framework that speaks AG-UI (https://docs.ag-ui.com:
+LangGraph, CrewAI, Mastra, Pydantic AI, Agno…) answering in a
+conversation, as it writes.
+
+    from django_chat_ui.agui import AgUiAgent
+
+    agent = AgUiAgent("https://agents.example.com/shop")
+
+    class Backend(ChatBackend):
+        hooks = "thread"
+
+        def on_message(self, request, message):
+            if message.sender and message.sender.kind != "bot":
+                agent.answer(message.conversation, bot)
+
+The conversation goes to the agent as a run (``RunAgentInput``: its
+messages, ``threadId`` the room's ID); each text message it streams back
+(``TEXT_MESSAGE_START`` / ``_CONTENT`` / ``_END``, or ``_CHUNK``) is a
+message of ``bot``, through ``services.stream_text()``. Other events reach
+``handle()``, to override (tool calls, state…).
+"""
+
+from __future__ import annotations
+
+import itertools
+import json
+import urllib.request
+import uuid
+from typing import TYPE_CHECKING, Any
+
+from . import services
+from .matrix import room_id
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterable, Iterator
+
+    from .models import AbstractConversation, AbstractParticipant, RoomEvent
+
+TEXT = {"TEXT_MESSAGE_CONTENT", "TEXT_MESSAGE_CHUNK"}
+
+
+class AgUiError(Exception):
+    """The agent's ``RUN_ERROR``."""
+
+    def __init__(self, message: str, code: str | None = None):
+        super().__init__(message)
+        self.code = code
+
+
+def sse(lines: Iterable[bytes]) -> Iterator[dict[str, Any]]:
+    """The events of a Server-Sent Events stream, as JSON objects."""
+    data: list[str] = []
+    for raw in lines:
+        line = raw.decode("utf-8").rstrip("\r\n")
+        if line.startswith("data:"):
+            data.append(line[5:].removeprefix(" "))
+        elif not line and data:
+            try:
+                event = json.loads("\n".join(data))
+            except ValueError:
+                event = None
+            data = []
+            if isinstance(event, dict):
+                yield event
+    if data:
+        try:
+            event = json.loads("\n".join(data))
+        except ValueError:
+            return
+        if isinstance(event, dict):
+            yield event
+
+
+class AgUiAgent:
+    """An AG-UI agent at ``url`` (``headers``: its authentication)."""
+
+    def __init__(
+        self,
+        url: str,
+        *,
+        headers: dict[str, str] | None = None,
+        timeout: float = 120,
+        opener: Callable[..., Any] = urllib.request.urlopen,
+    ):
+        self.url = url
+        self.headers = headers or {}
+        self.timeout = timeout
+        self.opener = opener
+
+    def messages(
+        self, conversation: AbstractConversation, bot: AbstractParticipant
+    ) -> list[dict[str, Any]]:
+        """The conversation as the agent takes it: the bot's messages are
+        the assistant's; anyone else's, the user's (system notices left out).
+        Edited messages, as they are now."""
+        edits = {
+            edit.relates_to_id: edit.content.get("m.new_content") or {}
+            for edit in conversation.messages.filter(rel_type="m.replace")
+        }
+        result = []
+        for message in conversation.messages.exclude(rel_type="m.replace").filter(
+            redacted_by=None
+        ):
+            if message.sender_id is None:
+                continue
+            body = str(edits.get(message.pk, message.content).get("body", ""))
+            if not body:
+                continue
+            role = "assistant" if message.sender_id == bot.pk else "user"
+            result.append({"id": message.event_id, "role": role, "content": body})
+        return result
+
+    def run_input(
+        self, conversation: AbstractConversation, bot: AbstractParticipant
+    ) -> dict[str, Any]:
+        """``RunAgentInput``: override it to give the agent tools, context or
+        state."""
+        return {
+            "threadId": room_id(conversation),
+            "runId": uuid.uuid4().hex,
+            "state": {},
+            "messages": self.messages(conversation, bot),
+            "tools": [],
+            "context": [],
+            "forwardedProps": {},
+        }
+
+    def events(self, payload: dict[str, Any]) -> Iterator[dict[str, Any]]:
+        """Run the agent: its events, as they come."""
+        request = urllib.request.Request(
+            self.url,
+            data=json.dumps(payload).encode(),
+            headers={
+                "Content-Type": "application/json",
+                "Accept": "text/event-stream",
+                **self.headers,
+            },
+            method="POST",
+        )
+        with self.opener(request, timeout=self.timeout) as response:
+            yield from sse(response)
+
+    def handle(self, event: dict[str, Any], conversation: AbstractConversation) -> None:
+        """An event that isn't text: ``RUN_STARTED``, tool calls, state…"""
+
+    def answer(
+        self, conversation: AbstractConversation, bot: AbstractParticipant
+    ) -> list[RoomEvent]:
+        """Run the agent on the conversation; its text messages, sent as
+        ``bot`` as they're written. A ``RUN_ERROR`` raises ``AgUiError``,
+        after sending what came."""
+        error: list[AgUiError] = []
+
+        def texts() -> Iterator[tuple[str, str]]:
+            current = ""
+            for event in self.events(self.run_input(conversation, bot)):
+                kind = event.get("type")
+                if kind == "TEXT_MESSAGE_START":
+                    current = str(event.get("messageId") or current)
+                elif kind in TEXT and isinstance(event.get("delta"), str):
+                    current = str(event.get("messageId") or current)
+                    yield current, event["delta"]
+                elif kind == "RUN_ERROR":
+                    error.append(
+                        AgUiError(str(event.get("message", "")), event.get("code"))
+                    )
+                    return
+                elif kind not in {"TEXT_MESSAGE_END"}:
+                    self.handle(event, conversation)
+
+        sent = []
+        for _message, chunks in itertools.groupby(texts(), key=lambda item: item[0]):
+            message = services.stream_text(
+                conversation, bot, (delta for _id, delta in chunks)
+            )
+            if message is not None:
+                sent.append(message)
+        if error:
+            raise error[0]
+        return sent

django_chat_ui/apps.py

@@ -0,0 +1,19 @@
+from django.apps import AppConfig
+from django.utils.translation import gettext_lazy as _
+
+
+class ChatUiConfig(AppConfig):
+    name = "django_chat_ui"
+    verbose_name = _("Chat")
+    default_auto_field = "django.db.models.BigAutoField"
+
+    def ready(self) -> None:
+        from django.conf import settings
+
+        from .models import DEFAULTS
+
+        # Always there, as AUTH_USER_MODEL is: migrations (this package's,
+        # and a site's pointing to its models) name them.
+        for name, default in DEFAULTS.items():
+            if not hasattr(settings, name):
+                setattr(settings, name, default)

django_chat_ui/backend.py

@@ -0,0 +1,269 @@
+"""What a site decides: who is chatting, what they see, what conversations
+they can start and what happens when someone writes. Subclass
+``ChatBackend`` and name it in the settings:
+
+    CHAT_UI = {"BACKEND": "myapp.chat.Backend"}
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from functools import cache
+from typing import TYPE_CHECKING, Any
+
+from django.conf import settings
+from django.contrib.auth import authenticate, get_user_model
+from django.db import connections, transaction
+from django.utils.module_loading import import_string
+from django.utils.translation import gettext_lazy as _
+
+from . import services
+from .models import (
+    AbstractConversation,
+    AbstractParticipant,
+    RoomEvent,
+    get_conversation_model,
+    get_participant_model,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from django.db.models import QuerySet
+    from django.http import HttpRequest
+
+SESSION_KEY = "django_chat_ui_participant"
+
+logger = logging.getLogger("django_chat_ui")
+
+
+class ChatBackend:
+    #: Whether visitors who aren't logged in can chat (the "contact us"
+    #: widget of a public site). Each gets a participant kept in their
+    #: session.
+    allow_anonymous = False
+
+    #: Where the hooks that react (``on_start``, ``on_message``,
+    #: ``on_action``, ``on_event``) run: ``"inline"``, inside the request
+    #: that caused them, or ``"thread"``, in a thread of their own once its
+    #: changes are committed, so it's answered at once (a bot that takes
+    #: seconds doesn't hold the sender's message). For a task queue,
+    #: override ``run_hook()``.
+    hooks = "inline"
+
+    #: The types of events of extensions that clients may send, besides
+    #: messages and reactions: namespaced (``com.acme.order.cancel``). Each
+    #: sent reaches ``on_event()``, after ``validate_content()``.
+    event_types: frozenset[str] | set[str] = frozenset()
+
+    #: Largest upload, in bytes, when a conversation's ``attachments`` don't
+    #: say.
+    max_upload_size = 5 * 1024 * 1024
+
+    # Who -------------------------------------------------------------------
+
+    def get_participant(self, request: HttpRequest) -> AbstractParticipant | None:
+        """The participant of this request, or None (403). Users get one on
+        their first request; staff are agents."""
+        user = request.user
+        if user.is_authenticated:
+            return self.participant_for_user(user)
+        if not self.allow_anonymous:
+            return None
+        pk = request.session.get(SESSION_KEY)
+        participant = get_participant_model().objects.filter(pk=pk, user=None).first()
+        if participant is None:
+            participant = get_participant_model().objects.create(
+                kind="contact", name=str(_("Visitor"))
+            )
+            request.session[SESSION_KEY] = participant.pk
+        return participant
+
+    def login(
+        self, request: HttpRequest, username: str, password: str
+    ) -> AbstractParticipant | None:
+        """The participant of a Matrix client logging in with a password
+        (``POST /login``): a user of the site's, with theirs."""
+        user = authenticate(request, username=username, password=password)
+        if user is None or not user.is_active:
+            return None
+        return self.participant_for_user(user)
+
+    def participant_for_user(self, user: Any) -> AbstractParticipant:
+        participant, _ = get_participant_model().objects.get_or_create(
+            user=user,
+            defaults={
+                "kind": "agent" if user.is_staff else "user",
+                "name": user.get_full_name() or user.get_username(),
+            },
+        )
+        return participant
+
+    # What they see ---------------------------------------------------------
+
+    def conversations(
+        self, participant: AbstractParticipant
+    ) -> QuerySet[AbstractConversation]:
+        """The conversations ``participant`` sees: those they take part in.
+        The stream only carries events of these."""
+        return get_conversation_model().objects.filter(
+            memberships__participant=participant
+        )
+
+    def serialize_participant(
+        self, participant: AbstractParticipant, data: dict[str, Any]
+    ) -> dict[str, Any]:
+        """This package's block of a participant's ``m.room.member`` (its
+        ``kind``, ``handle``, ``avatar`` and ``ext``): add what a site's
+        model has, under ``ext`` with your namespace (``{"com.acme": …}``)."""
+        return data
+
+    def serialize_conversation(
+        self, conversation: AbstractConversation, data: dict[str, Any]
+    ) -> dict[str, Any]:
+        """This package's state event of what a conversation is (its
+        ``channel``, ``state`` and ``ext``): add what a site's model has (its
+        priority, who it's assigned to…), under ``ext``."""
+        return data
+
+    # Starting conversations ------------------------------------------------
+
+    def can_start(
+        self,
+        participant: AbstractParticipant,
+        others: list[AbstractParticipant],
+        channel: str,
+    ) -> bool:
+        """Whether ``participant`` may start a conversation with ``others``.
+        Agents, with anyone; everybody else, only with the support team
+        (``others`` empty)."""
+        return participant.kind == "agent" or not others
+
+    def start(
+        self,
+        request: HttpRequest,
+        participant: AbstractParticipant,
+        others: list[AbstractParticipant],
+        channel: str,
+    ) -> AbstractConversation:
+        """A new conversation (``POST /createRoom``). Without ``others`` (the
+        "contact us" widget) it goes to ``support_team()`` and waits,
+        ``pending``, for one of them to answer."""
+        team = [] if others else self.support_team(channel)
+        conversation = services.create_conversation(
+            [participant, *others, *team],
+            channel=channel,
+            # The team's inbox names it after whoever wrote, not the team.
+            title="" if others else participant.name,
+            state="open" if others else "pending",
+            capabilities=self.new_capabilities(channel),
+            creator=participant,
+        )
+        self.run_hook(self.on_start, request, conversation, participant)
+        return conversation
+
+    def support_team(self, channel: str) -> list[AbstractParticipant]:
+        """Who receives conversations started without anyone: every active
+        staff user. Override it to route them (a queue, a bot first…)."""
+        users = get_user_model().objects.filter(is_staff=True, is_active=True)
+        return [self.participant_for_user(user) for user in users]
+
+    def new_capabilities(self, channel: str) -> dict[str, Any]:
+        """The capabilities of the conversations it starts (section 6.1)."""
+        return {
+            "typing": True,
+            "receipts": True,
+            "history": True,
+            "replies": True,
+            "attachments": {
+                "types": ["image", "file"],
+                "maxSize": self.max_upload_size,
+            },
+            "composer": {"mode": "free", "maxLength": 4096},
+        }
+
+    # What happens ----------------------------------------------------------
+
+    def run_hook(self, hook: Callable[..., Any], *args: Any) -> None:
+        """Run a hook that reacts to a command, as ``hooks`` says. Override
+        it to send them to a task queue (Celery, ``django.tasks``…)."""
+        if self.hooks == "thread":
+            transaction.on_commit(
+                lambda: threading.Thread(
+                    target=self.run_hook_now, args=(hook, *args), daemon=True
+                ).start()
+            )
+        else:
+            hook(*args)
+
+    def run_hook_now(self, hook: Callable[..., Any], *args: Any) -> None:
+        """Run a hook away from its request: its failure is logged, and its
+        thread's database connection closed."""
+        try:
+            hook(*args)
+        except Exception:
+            logger.exception("django-chat-ui: %s failed", hook.__name__)
+        finally:
+            connections.close_all()
+
+    def before_send(
+        self,
+        request: HttpRequest,
+        conversation: AbstractConversation,
+        participant: AbstractParticipant,
+        event_type: str,
+        content: dict[str, Any],
+    ) -> None:
+        """Just before a client's event is added (checked against what the
+        conversation allows): what must come first in the thread ("Ana
+        joined"), or a last refusal (raise ``MatrixError``). Always inline."""
+
+    def on_start(
+        self,
+        request: HttpRequest,
+        conversation: AbstractConversation,
+        participant: AbstractParticipant,
+    ) -> None:
+        """After a conversation is started: a greeting, a bot…"""
+
+    def on_message(self, request: HttpRequest, message: RoomEvent) -> None:
+        """After someone sent a message (not an edit, nor a button's
+        answer): a bot's answer, sending it on to WhatsApp… It runs as
+        ``hooks`` says."""
+
+    def on_action(
+        self,
+        request: HttpRequest,
+        participant: AbstractParticipant,
+        message: RoomEvent,
+        button: dict[str, Any],
+    ) -> None:
+        """After someone used a button of ``message``: their answer (the
+        button's label, as WhatsApp writes it) is in the thread already."""
+
+    def on_event(self, request: HttpRequest, event: RoomEvent) -> None:
+        """After a client sent an event of ``event_types``."""
+
+    def validate_content(
+        self,
+        conversation: AbstractConversation,
+        participant: AbstractParticipant,
+        event_type: str,
+        content: dict[str, Any],
+    ) -> None:
+        """Raise ``MatrixError`` for an event ``participant`` can't send.
+        What the conversation allows is checked already; messages of
+        extensions' types (namespaced ``msgtype``, with a ``body``) and
+        events of ``event_types`` get here, allowed."""
+
+
+@cache
+def _backend_class(path: str) -> type[ChatBackend]:
+    return import_string(path)
+
+
+def get_backend() -> ChatBackend:
+    config = getattr(settings, "CHAT_UI", {})
+    path = config.get("BACKEND", "django_chat_ui.backend.ChatBackend")
+    return _backend_class(path)()