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
make setup      # runtime + demo extras only
make setup-all  # every extra, including the torch-based transformers stack

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, ToolAgent + subagent engine
├── protocols/            # Vercel + OpenAI handlers
├── storage/              # memory + db adapters, ThreadService
├── rags/                 # BM25, ChromaDB, Qdrant hybrid, provider
├── integrations/         # mcp, github, linear, notion, weather
├── conversation/         # Thread + Message models
├── memories/             # MemoryService, Entry, documents
├── files/                # processors, transforms, pipelines
├── workflows/            # definitions, executor, hooks
├── artifacts/            # ArtifactSchema
├── citations/            # CitationRegistry, formatter
├── suggestions/          # DefaultSuggestionGenerator
├── tracing/              # opt-in Haystack spans persisted to the ORM
└── management/commands/  # warmup_rag