Developer Manual

Internal documentation for contributors and advanced users: how the SDK works, its extension points, and how to test it.

If you’re building an application with the SDK, start with the Quick Start and Guides instead.

Dev Setup

Clone and install

git clone https://github.com/django-ai-sdk/django-ai-sdk.git
cd django-ai-sdk
uv sync --all-extras --group dev

Run tests

make test

Regenerate docs diagrams

make docs-graphs

Repository Layout

django_ai_sdk/
├── agent.py              # Agent coordinator class
├── common.py             # ChatMessage, StreamWriter, MessageChunk
├── events.py             # 13 normalized StreamEvent types
├── responses.py          # stream_response()
├── permissions.py        # BasePermission, built-ins, Operation enum
├── adapters/             # Stream, Run
├── agents/               # registry, services, runtime, config
├── protocols/            # Vercel + OpenAI handlers
├── storage/              # memory + db adapters, ThreadService
├── rags/                 # BM25, ChromaDB, Qdrant hybrid, provider
├── integrations/         # mcp, github, linear, notion, weather
├── pipelines/            # Haystack ToolAgent
├── conversation/         # Thread + Message models
├── memories/             # MemoryService, Entry, documents
├── files/                # processors, transforms, pipelines
├── workflows/            # definition, executor, actions
├── artifacts/            # ArtifactSchema
├── citations/            # CitationRegistry, formatter
├── suggestions/          # DefaultSuggestionGenerator
└── management/commands/  # warmup_rag