django-ask-ai

Let people ask your Django app questions in plain language — without giving AI a database cursor, your source code, or the power to change anything.

Staff, support, and product people already live in Django admin and your product UI. They want answers like “how many open invoices this month?” or “what do the status values mean?” Engineers want that too — but not by wiring ChatGPT to SQL, pasting the schema into a vendor chat, or letting an agent “just run tools” against production.

django-ask-ai is the drop-in middle path:

The LLM only translates. Django validates, scopes, executes read-only, logs, and caches. Your Groups decide who sees what.

Invoice.objects.ask("how many open invoices this month?", user=request.user)
# → Group scope → allowlisted ORM → aggregate → plain-language answer

$ python manage.py ask_ai "what do the status values mean on Invoice?"
$ python manage.py ask_ai --doctor

Who is this for?

Real use case: a support lead opens Invoice admin, types “how many overdue?”, gets a number under their Group’s visible models and excluded fields. A manager with aggregates_only never gets raw customer rows. “Delete all unpaid orders” is refused and logged. The same question works from manage.py ask_ai or a DRF client when a product UI needs “talk to your data” over HTTP.

Why this exists (and why not “just an AI agent”?)

One sentence: The LLM is a translator. Django is the executor. Your Groups are the permission system.

Out of the box

No custom agent framework. After install + mixin:

Optional (5 minutes): teach your words in ask_context.py. The engine stays domain-agnostic — shop, library, billing, HR all plug in the same way.

Quickstart

pip install django-ask-ai

INSTALLED_APPS = [..., "django_ask_ai"]

from django_ask_ai import AskMixin

class Invoice(AskMixin, models.Model):
    ask_exclude = ["internal_notes"]
    ask_business = "An invoice is overdue if due_at < today and status != paid."

# admin.py — plug and play per model
from django.contrib import admin
from django_ask_ai import AskAdminMixin

@admin.register(Invoice)
class InvoiceAdmin(AskAdminMixin, admin.ModelAdmin):
    list_display = ("id", "status", "total")

Local (Ollama) or cloud (OpenRouter / OpenAI / …)

# settings.py — Ollama (default, offline)
ASK_AI = {
    "BACKENDS": {
        "default": {
            "PROVIDER": "ollama",
            "MODEL": "llama3.1",
            "BASE_URL": "http://localhost:11434",
        },
    },
    "SCOPES": {
        "support": {
            "schema": ["billing.Subscription", "billing.Invoice"],
            "exclude": ["customer__email"],
        },
        "managers": {"schema": ["billing"], "data": "aggregates_only"},
    },
    # "CACHE_ALIAS": "default",  # point at Redis in production
}

# OpenRouter (or any OpenAI-compatible gateway) — same provider, different BASE_URL
ASK_AI = {
    "BACKENDS": {
        "default": {
            "PROVIDER": "openai",
            "MODEL": "openai/gpt-4o-mini",
            "API_KEY": "…",
            "BASE_URL": "https://openrouter.ai/api/v1",
        },
    },
}

python manage.py migrate
python manage.py ask_ai --doctor
python manage.py ask_ai "how many open invoices?"

{% load ask_ai %}
{% ask_console %}   {# or {% ask_widget %} #}

Teach weekly questions (optional, high value)

# myapp/ask_context.py — autodiscovered
ASK_CONTEXT = {
    "glossary": {"ARR": "billing.Subscription"},
    "rules": ["Trial accounts are excluded from ARR."],
    "metrics": {
        "arr": {
            "description": "Monthly recurring revenue from active subscriptions",
            "expression": (
                'Subscription.objects.filter(status="active")'
                '.aggregate(v=Sum("mrr"))'
            ),
            "aliases": ["ARR", "monthly recurring revenue"],
            "model": "billing.Subscription",
        },
    },
}

How a question is answered

question
   │
   ├─► scope (Django Groups) ──► intent (data|knowledge|decision|structure)
   │
   ├─► aggregate cache hit? ──► return + AskLog
   │
   ├─► library? (metric / certified / temporal / breakdown) ──► 0 tokens
   │
   ├─► structure / definition from host metadata
   │
   └─► LLM translate → AST validate → cost gate → execute → format
              → cache aggregates → follow_ups + citations + AskLog

• Logging: AskLog records user, scope, surface, question, expression, tokens, duration, block stage — admin changelist included.
• Caching: repeated aggregate answers and API session turns live in Django’s cache framework — no package-owned chat tables.
• Safety: 150+ hostile-expression corpus in CI. Full threat model: docs/security-model.md.

Surfaces (same safe pipeline)

Providers (pluggable)

Ollama (default) · OpenAI · OpenRouter (via OpenAI-compatible BASE_URL) · Anthropic · Gemini · Groq · Mistral · Cohere · Together · Azure OpenAI · Bedrock — routing, fallbacks, mock_llm() for CI. Django is the only hard dependency.

Offline demo in under 5 minutes (Ollama + SQLite)

No cloud keys. Stage-safe.

ollama pull llama3.1
cd example_project
pip install -e "..[dev,drf]"
unset ASK_AI_PROVIDER ASK_AI_API_KEY ASK_AI_BASE_URL OPENROUTER_API_KEY
python manage.py migrate && python manage.py seed_demo
python manage.py ask_ai --doctor          # backend ollama: ok
python manage.py ask_ai "orders by status"
python manage.py runserver                # admin → Order → Ask AI

Full talk script: example_project/OFFLINE_DEMO.md.

Example hosts

example_project/ is a shop dogfood host. A second library/loans host proves the engine is not shop-specific.

Production

Safe by default. Valuable when taught. Freeze weekly asks as metrics or certified questions; run ask_eval before demos; put CACHE_ALIAS on Redis. Playbook: docs/production.md.

Docs

License

MIT