Metadata-Version: 2.4
Name: django-ai-sdk
Version: 0.1.2a10
Summary: Build AI agents in Django. Batteries included.
Author: terminalkitten
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/django-ai-sdk/django-ai-sdk
Project-URL: Repository, https://github.com/django-ai-sdk/django-ai-sdk
Project-URL: Issues, https://github.com/django-ai-sdk/django-ai-sdk/issues
Project-URL: Changelog, https://github.com/django-ai-sdk/django-ai-sdk/releases
Keywords: django,ai-agents,agentic-framework,multi-agent,llm-agents,workflow-automation,rag,llm,python
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiofiles>=25.1.0
Requires-Dist: cashews<9,>=7.5.0
Requires-Dist: django<6.1,>=5.2.6
Requires-Dist: haystack-ai>=3.0.0
Requires-Dist: django-tasks>=0.12.0
Requires-Dist: loguru>=0.7.3
Requires-Dist: puremagic>=2.2.0
Requires-Dist: pydantic>=2.13.4
Requires-Dist: tenacity>=9.1.4
Provides-Extra: all
Requires-Dist: django-ai-sdk[files,haystack,mcp,providers,rag,transformers]; extra == "all"
Provides-Extra: providers
Requires-Dist: django-ai-sdk[anthropic,huggingface,mistral,ollama,openrouter]; extra == "providers"
Provides-Extra: rag
Requires-Dist: django-ai-sdk[chroma,qdrant]; extra == "rag"
Provides-Extra: haystack
Requires-Dist: haystack-ai>=3.0.0; extra == "haystack"
Provides-Extra: mcp
Requires-Dist: mcp-haystack>=1.4.1; extra == "mcp"
Requires-Dist: authlib>=1.7.2; extra == "mcp"
Provides-Extra: files
Requires-Dist: firecrawl-anydoc>=0.2.4; extra == "files"
Requires-Dist: openpyxl>=3.1.5; extra == "files"
Requires-Dist: pdf-inspector>=1.20.0; extra == "files"
Requires-Dist: python-docx>=1.2.0; extra == "files"
Requires-Dist: python-pptx>=1.0.2; extra == "files"
Provides-Extra: embeddings
Requires-Dist: fastembed-haystack>=2.4.0; extra == "embeddings"
Requires-Dist: django-ai-sdk[haystack]; extra == "embeddings"
Provides-Extra: chroma
Requires-Dist: chroma-haystack>=4.4.0; extra == "chroma"
Requires-Dist: django-ai-sdk[embeddings]; extra == "chroma"
Provides-Extra: qdrant
Requires-Dist: qdrant-haystack>=10.4.0; extra == "qdrant"
Requires-Dist: django-ai-sdk[embeddings]; extra == "qdrant"
Provides-Extra: anthropic
Requires-Dist: anthropic-haystack>=5.17.0; extra == "anthropic"
Provides-Extra: huggingface
Requires-Dist: huggingface-api-haystack>=0.6.0; extra == "huggingface"
Provides-Extra: mistral
Requires-Dist: mistral-haystack>=1.5.0; extra == "mistral"
Provides-Extra: ollama
Requires-Dist: ollama-haystack>=6.8.0; extra == "ollama"
Provides-Extra: openrouter
Requires-Dist: openrouter-haystack>=1.2.0; extra == "openrouter"
Provides-Extra: transformers
Requires-Dist: transformers-haystack>=0.3.0; extra == "transformers"
Dynamic: license-file

# Django AI SDK

<div align="center">
  <img src="https://raw.githubusercontent.com/django-ai-sdk/django-ai-sdk/refs/heads/dev/public/logo.png" alt="Django AI SDK" width="150">
  <br />
  <i>Build AI agents in Django. Batteries included.</i>
</div>

## Project Status: Read This First

This is a **beta**. The API may still change as we find better patterns.
Here's what that means for you:

- **API may still evolve**: some interfaces will shift as we find better patterns.
- **Not for production yet**: use this for experimentation, prototypes, and side projects. Keep critical workloads elsewhere until we hit stable.
- **Watch the repo**: Things change quickly. Star & watch to stay in the loop.
- **Your feedback shapes the SDK**: Break things, open issues, tell us what hurts.

We'd love to have you along for the ride, just keep your seatbelt on.


## Install

```bash
pip install django-ai-sdk
```

Or with uv:

```bash
uv add django-ai-sdk
```

## Quick Start

### 1. Add to INSTALLED_APPS

```python
# settings.py
INSTALLED_APPS = [
    ...
    "django_ai_sdk",
]
```

Then run `python manage.py migrate`.

### 2. Define your agent

```python
# agents.py
from django_ai_sdk import Agent
from django_ai_sdk.adapters.base import Stream
from django_ai_sdk.generators import openai_responses_chat
from haystack import Pipeline


class HelpDeskAgent(Agent):
    name = "Help Desk"
    model = "gpt-5-mini"
    instructions = "You are a helpful support agent."
    llm = openai_responses_chat

    async def get_pipeline_adapter(self, thread_id=None, user=None):
        storage_adapter = await self.get_storage_adapter(thread_id)
        generator = self.get_llm()
        return Stream(
            pipeline=Pipeline(),
            generator=generator,
            storage_adapter=storage_adapter,
        )
```

For non-streaming tasks (title generation, structured output), use `Run` instead:

```python
from django_ai_sdk.adapters.base import Run

    async def get_run_adapter(self, thread_id=None, user=None):
        return Run(generator=self.get_llm())
```

### 3. Return a streaming response

```python
# views.py
from .agents import HelpDeskAgent

agent = HelpDeskAgent()


@router.post("/chat")
async def chat(request, payload: ChatRequest):
    return await agent.as_view(
        payload.messages,
        thread_id=payload.thread_id,
    )
```

## Features

- **Agents**: A Django `Agent` class you can run from a view, a task, or the API,
  streaming or not, with tool calling built in.
- **Workflows**: Multi-step, definition-driven runs with persisted steps and actions,
  so a process can span multiple agent calls with a record of what happened.
- **Subagents**: Agents can delegate to other agents as tools, so one agent can
  orchestrate specialists instead of doing everything itself.
- **Tool Calling**: MCP, memory, and custom tools, all managed by your Agent.
- **Streaming Responses**: Built-in SSE streaming. Works with Vercel AI SDK protocol.
- **Conversation Storage**: Automatic message persistence. Thread-based history out of the box.
- **RAG Pipelines**: BM25, ChromaDB, and Qdrant hybrid search with query expansion,
  for when an agent needs to ground itself in your documents.
- **Artifacts**: 16 structured UI types (tables, plans, approval cards, code blocks, and more)
  submitted by the LLM via tool calls.
- **File Processing**: Document upload with pipeline-based processing (text, CSV, JSON,
  DOCX, PPTX, XLSX. Extraction transforms for metadata embedding.
- **Integrations**: Third-party tools as self-registering Django apps, with caching,
  circuit breaking and OAuth built in.
- **Tracing**: Opt-in Haystack tracing persisted to the ORM, with per-thread and
  per-message token accounting.
- **Reindexing**: Hot-reload documents. Cached embeddings with simple refresh API.

## Documentation

Full documentation and examples: [github.com/django-ai-sdk/django-ai-sdk](https://github.com/django-ai-sdk/django-ai-sdk)
