django-admin-agent 0.1.0__py3-none-any.whl

django_admin_agent/__init__.py

@@ -0,0 +1,19 @@
+"""An always-present chat-agent sidebar in the Django admin."""
+
+from django_admin_agent.tools.introspect.register import register_introspect_tools
+from django_admin_agent.tools.register import (
+    build_default_registry,
+    register_admin_tools,
+)
+from django_admin_agent.tools.shell.register import register_shell_tools
+from django_admin_agent.urls import get_urls
+from django_admin_agent.version import __version__
+
+__all__ = [
+    "__version__",
+    "build_default_registry",
+    "get_urls",
+    "register_admin_tools",
+    "register_introspect_tools",
+    "register_shell_tools",
+]

django_admin_agent/admin/build_route_map.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from typing import Any
+
+from django.contrib import admin
+from django.urls import NoReverseMatch, reverse
+
+
+def build_route_map() -> list[dict[str, Any]]:
+    """Build the agent's navigable-route manifest from the admin registry.
+
+    One changelist route (and one add route, when available) per registered
+    model, shaped for the Web Component's ``routeMap`` — ``{id, path, title,
+    group}``. The agent calls ``list_routes`` to discover destinations and
+    ``navigate_to_route`` to jump to one, instead of guessing admin URLs.
+    """
+    routes: list[dict[str, Any]] = []
+    for model_cls in admin.site._registry:
+        meta = model_cls._meta
+        changelist = _admin_url(meta, "changelist")
+        if changelist is not None:
+            routes.append(
+                {
+                    "id": f"{meta.app_label}.{meta.model_name}.changelist",
+                    "path": changelist,
+                    "title": str(meta.verbose_name_plural),
+                    "group": meta.app_label,
+                },
+            )
+        add = _admin_url(meta, "add")
+        if add is not None:
+            routes.append(
+                {
+                    "id": f"{meta.app_label}.{meta.model_name}.add",
+                    "path": add,
+                    "title": f"Add {meta.verbose_name}",
+                    "group": meta.app_label,
+                },
+            )
+    return routes
+
+
+def _admin_url(meta: Any, action: str) -> str | None:
+    try:
+        return reverse(f"admin:{meta.app_label}_{meta.model_name}_{action}")
+    except NoReverseMatch:
+        return None
+
+
+__all__ = ["build_route_map"]

django_admin_agent/admin/build_sidebar_context.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from typing import Any
+
+from django.templatetags.static import static
+from django.urls import NoReverseMatch, reverse
+
+from django_admin_agent.admin.build_route_map import build_route_map
+from django_admin_agent.conf import get_settings
+
+_BUNDLE_PATH = "django_admin_agent/admin_agent.js"
+
+
+def build_sidebar_context() -> dict[str, Any]:
+    """Build the context the sidebar template needs.
+
+    Reverses the AG-UI endpoint URL, resolves the bootstrap module's static
+    URL, reads the title / auto-confirm flag from settings, and resolves the
+    admin index URL so the frontend ``nav.*`` tools can build changelist /
+    changeform URLs without reversing named routes in the browser. Shared by
+    the ``{% django_admin_agent_sidebar %}`` template tag and the
+    :class:`~django_admin_agent.admin.sidebar_admin_site.SidebarAdminSite`
+    ``each_context`` hook.
+    """
+    config = get_settings()
+    return {
+        "endpoint": reverse(config.endpoint_url_name),
+        "title": config.title,
+        "auto_confirm": config.auto_confirm,
+        "bootstrap_url": static(_BUNDLE_PATH),
+        "admin_base_url": _admin_base_url(),
+        "route_map": build_route_map(),
+    }
+
+
+def _admin_base_url() -> str:
+    """Resolve the admin index URL (e.g. ``/admin/``), or ``/`` if unmounted."""
+    try:
+        return reverse("admin:index")
+    except NoReverseMatch:
+        return "/"
+
+
+__all__ = ["build_sidebar_context"]

django_admin_agent/admin/sidebar_admin_site.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import Any
+
+from django.contrib.admin import AdminSite
+from django.http import HttpRequest
+
+from django_admin_agent.admin.build_sidebar_context import build_sidebar_context
+
+
+class SidebarAdminSite(AdminSite):
+    """A drop-in ``AdminSite`` that exposes the sidebar config to every page.
+
+    Adds ``django_admin_agent`` (the sidebar context) to ``each_context`` so
+    a base template can render the chat without the template tag. Using the
+    ``{% django_admin_agent_sidebar %}`` tag in ``admin/base_site.html`` is
+    the more common path and does not require swapping the admin site.
+    """
+
+    def each_context(self, request: HttpRequest) -> dict[str, Any]:
+        context = super().each_context(request)
+        context["django_admin_agent"] = build_sidebar_context()
+        return context
+
+
+__all__ = ["SidebarAdminSite"]

django_admin_agent/conf.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from django.conf import settings
+
+_SETTING_NAME = "DJANGO_ADMIN_AGENT"
+
+
+@dataclass(frozen=True)
+class AdminAgentSettings:
+    """Snapshot of the user-configurable ``DJANGO_ADMIN_AGENT`` settings.
+
+    Built fresh on every read so test overrides take effect immediately.
+    The agent model itself is configured separately via ``django-ag-ui``'s
+    ``DJANGO_AG_UI["MODEL"]``.
+    """
+
+    title: str
+    """Header text shown on the sidebar chat panel."""
+
+    auto_confirm: bool
+    """When ``True``, destructive UI tools run without a confirmation modal.
+    Passed to the Web Component as ``autoConfirm``."""
+
+    endpoint_url_name: str
+    """URL name to reverse for the AG-UI endpoint. Mount it with
+    :func:`django_admin_agent.get_urls` (which names it
+    ``django_admin_agent_endpoint``)."""
+
+
+def get_settings() -> AdminAgentSettings:
+    """Read the active ``DJANGO_ADMIN_AGENT`` settings dict."""
+    raw: dict[str, Any] = getattr(settings, _SETTING_NAME, {}) or {}
+    return AdminAgentSettings(
+        title=raw.get("TITLE", "Admin Copilot"),
+        auto_confirm=bool(raw.get("AUTO_CONFIRM", False)),
+        endpoint_url_name=raw.get("ENDPOINT_URL_NAME", "django_admin_agent_endpoint"),
+    )
+
+
+__all__ = ["AdminAgentSettings", "get_settings"]

django_admin_agent/static/django_admin_agent/admin_agent.js

@@ -0,0 +1,50 @@
+// Bootstrap for the Django-admin chat sidebar. Loaded as an ES module from
+// the same static directory as the vendored web-component bundle, so it can
+// import the component by relative path.
+//
+// Responsibilities:
+//   - register the <ag-ui-chat> custom element
+//   - attach the CSRF header so the AG-UI endpoint accepts POSTs under the
+//     logged-in admin session
+//   - read the auto-confirm flag from the element's data attribute
+//   - register the admin-aware frontend tools (DOM driving) — see
+//     ./admin_tools.js
+import { defineAgUiChat } from "./ag-ui-web-component.bundle.js";
+import { registerAdminTools } from "./admin_tools.js";
+
+function readCsrfToken() {
+  const match = document.cookie.match(/(?:^|;\s*)csrftoken=([^;]+)/);
+  return match ? decodeURIComponent(match[1]) : "";
+}
+
+// The navigable route manifest the server embedded (admin changelists/add
+// pages), driving the component's list_routes / navigate_to_route tools.
+function readRouteMap() {
+  const node = document.getElementById("django-admin-agent-routes");
+  if (node === null) {
+    return [];
+  }
+  try {
+    return JSON.parse(node.textContent);
+  } catch {
+    return [];
+  }
+}
+
+function bootstrap() {
+  defineAgUiChat();
+  const el = document.querySelector("ag-ui-chat#django-admin-agent");
+  if (el === null) {
+    return;
+  }
+  el.headers = { "X-CSRFToken": readCsrfToken() };
+  el.autoConfirm = el.getAttribute("data-auto-confirm") === "true";
+  el.routeMap = readRouteMap();
+  registerAdminTools(el);
+}
+
+if (document.readyState === "loading") {
+  document.addEventListener("DOMContentLoaded", bootstrap);
+} else {
+  bootstrap();
+}