Metadata-Version: 2.4
Name: django-ai-command
Version: 1.0.1
Summary: Query your Django database in natural language from the terminal or Django Admin.
Author-email: Sebastián Martín Artaza Saade <martin.artaza@gmail.com>
License: MIT
Project-URL: Homepage, https://www.sebastianartaza.com
Project-URL: Repository, https://github.com/martinartaza/django-ai-command
Project-URL: Bug Tracker, https://github.com/martinartaza/django-ai-command/issues
Project-URL: LinkedIn, https://www.linkedin.com/in/sebastian-martin-artaza-saade-7b482123/
Keywords: django,ai,llm,orm,admin,natural language,chatbot
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.0
Classifier: Framework :: Django :: 4.1
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: django>=4.0
Requires-Dist: langchain-core>=0.2
Provides-Extra: gemini
Requires-Dist: langchain-google-genai>=1.0; extra == "gemini"
Provides-Extra: openai
Requires-Dist: langchain-openai>=0.1; extra == "openai"
Provides-Extra: groq
Requires-Dist: langchain-openai>=0.1; extra == "groq"
Provides-Extra: deepseek
Requires-Dist: langchain-openai>=0.1; extra == "deepseek"
Provides-Extra: anthropic
Requires-Dist: langchain-anthropic>=0.1; extra == "anthropic"
Provides-Extra: all
Requires-Dist: langchain-google-genai>=1.0; extra == "all"
Requires-Dist: langchain-openai>=0.1; extra == "all"
Requires-Dist: langchain-anthropic>=0.1; extra == "all"
Dynamic: license-file

# django-ai-command

Query your Django database in natural language — from the terminal or directly inside the Django Admin.

Powered by LangChain, compatible with Gemini, Groq, DeepSeek, OpenAI, and Anthropic.

---

## How it works

`django-ai-command` introspects your Django models automatically, sends the schema + your question to an LLM, generates safe read-only ORM code, executes it, and returns the result.

No manual tool configuration. No hardcoded models. Just install, configure your API key, and ask.

---

## Features

- Natural language queries from the **terminal**
- **Floating chat widget** embedded in the Django Admin (available on every admin page)
- **Full-page chat view** at `/your-admin-prefix/ai-assistant/`
- Multi-provider support via LangChain (Groq, Gemini, DeepSeek, OpenAI, Anthropic)
- Safe mode: blocks all write operations by default
- Automatic model introspection — no setup required per model
- Designed to become a standalone PyPI package

---

## Screenshots

### Terminal command
![Terminal command](https://raw.githubusercontent.com/martinartaza/django-ai-command/main/docs/img_01.png)

### Floating modal in Django Admin
![Floating modal](https://raw.githubusercontent.com/martinartaza/django-ai-command/main/docs/img_02.png)

### Full-page chat view
![Full page](https://raw.githubusercontent.com/martinartaza/django-ai-command/main/docs/img_03.png)

---

## Installation

For now, copy the `django_ai_command/` folder into your project root.

Install dependencies:

```bash
pip install langchain langchain-core langchain-openai langchain-google-genai
```

Add to `INSTALLED_APPS` — **must be before `django.contrib.admin`**:

```python
INSTALLED_APPS = ['django_ai_command'] + CORE_APPS + EXTERNAL_APPS + LOCAL_APPS
```

---

## Configuration

Add `DJANGO_AI_COMMAND` to your `settings.py`:

```python
DJANGO_AI_COMMAND = {
    "provider": "groq",             # LLM provider (see options below)
    "api_key": env("GROQ_API_KEY"), # API key for the selected provider
    "safe_mode": True,              # Block write operations (recommended)
    "admin_prefix": "admin",        # Your admin URL prefix (see note below)
}
```

### `admin_prefix`

If you changed the default Django admin URL for security reasons (recommended), set `admin_prefix` to match. For example, if your admin is at `/15_admin_27/`, set:

```python
"admin_prefix": "15_admin_27",
```

This ensures the chat widget inside the Admin points to the correct endpoint. If you use the default `/admin/` URL, you can omit this field.

---

## Provider examples

### Groq (free, recommended for development)

Get your API key at [console.groq.com](https://console.groq.com).

```python
DJANGO_AI_COMMAND = {
    "provider": "groq",
    "api_key": env("GROQ_API_KEY"),
    "safe_mode": True,
    "admin_prefix": "admin",
}
```

---

### Gemini (Google)

Get your API key at [aistudio.google.com](https://aistudio.google.com).

```python
DJANGO_AI_COMMAND = {
    "provider": "gemini",
    "api_key": env("GEMINI_API_KEY"),
    "safe_mode": True,
    "admin_prefix": "admin",
}
```

---

### DeepSeek

Get your API key at [platform.deepseek.com](https://platform.deepseek.com).

```python
DJANGO_AI_COMMAND = {
    "provider": "deepseek",
    "api_key": env("DEEPSEEK_API_KEY"),
    "base_url": "https://api.deepseek.com",
    "safe_mode": True,
    "admin_prefix": "admin",
}
```

---

### OpenAI

```python
DJANGO_AI_COMMAND = {
    "provider": "openai",
    "api_key": env("OPENAI_API_KEY"),
    "safe_mode": True,
    "admin_prefix": "admin",
}
```

---

### Anthropic (Claude)

```python
DJANGO_AI_COMMAND = {
    "provider": "anthropic",
    "api_key": env("ANTHROPIC_API_KEY"),
    "safe_mode": True,
    "admin_prefix": "admin",
}
```

---

## Usage

### Terminal

```bash
python manage.py ai "How many users registered this week?"
python manage.py ai "List the 5 products with the most stock"
python manage.py ai "Which orders have been pending for more than 3 days?"
python manage.py ai "¿Cuántos usuarios hay registrados?"
```

### Django Admin — floating button

A floating 🤖 button appears on every page of the Django Admin. Click it to open the chat modal and ask questions without leaving your current page.

### Django Admin — full page

Navigate to:

```
/your-admin-prefix/ai-assistant/
```

Example: `https://yourdomain.com/admin/ai-assistant/`

---

## Safe mode

When `safe_mode` is `True` (default), the following ORM operations are blocked:

`delete`, `update`, `save`, `create`, `bulk_create`, `bulk_update`, `raw`, `extra`, `execute`

The LLM is also instructed via prompt to only generate read operations. Safe mode provides two layers of protection: prompt-level and AST-level validation before execution.

---

## Project structure

```
django_ai_command/
├── admin.py            # Injects routes and context into Django Admin
├── apps.py             # AppConfig — loads admin.py via ready()
├── executor.py         # Executes ORM code safely (AST validation)
├── introspection.py    # Reads all registered Django models automatically
├── llm.py              # LangChain wrapper — multi-provider support
├── urls.py             # URL definitions for chat views
├── utils.py
├── views.py            # AiChatView (full page) and AiAskView (POST endpoint)
├── management/
│   └── commands/
│       └── ai.py       # Management command: python manage.py ai "question"
├── templates/
│   ├── admin/
│   │   └── base_site.html          # Injects floating button into all admin pages
│   └── django_ai_command/
│       └── ai_chat.html            # Full-page chat view template
└── docs/
    ├── img_01.png      # Terminal command screenshot
    ├── img_02.png      # Floating modal screenshot
    └── img_03.png      # Full-page view screenshot
```

---

## Roadmap

| Version | Description |
|---------|-------------|
| v1.0 | Terminal command + Gemini |
| v2.0 | Terminal command + multi-provider via LangChain ✅ |
| v3.0 | Chat widget in Django Admin ✅ |
| v4.0 | LLM-suggested charts rendered in the Admin |

---

## License

MIT

---

## Author

**Sebastián Martín Artaza Saade**

- 🌐 [sebastianartaza.com](https://www.sebastianartaza.com)
- 💼 [LinkedIn](https://www.linkedin.com/in/sebastian-martin-artaza-saade-7b482123/)
- 🐙 [GitHub](https://github.com/martinartaza)
- ✉️ martin.artaza@gmail.com
