crudkit

A metadata-driven CRUD framework for Django. Define models; get typed object IDs, soft delete, merge, change logging, an activity feed, saved views, AI-populated fields and a generic REST API — without writing per-model serializers, viewsets or routes.

Core concepts

Every CrudKit model inherits BaseCrudKitModel and declares a 3-letter TYPE_ID. Object IDs are rendered as <TYPE_ID><pk> (e.g. CUS42) across the API and UI.

from django.db import models
from crudkit.models import BaseCrudKitModel

class Customer(BaseCrudKitModel):
    TYPE_ID = "CUS"
    name = models.CharField(max_length=255)

    class CrudKitSettings(BaseCrudKitModel.CrudKitSettings):
        search_fields = ["name"]

Included with every model: created_by/updated_by/created_at/updated_at audit columns, a deleted soft-delete flag (soft_delete()), merge support (delete_and_merge_with()), a change log, an activity feed (FeedItem), external-system sync (ExternalObject), saved views/layouts, and optional AI fields (AISummaryField, AICategoryField, AIBooleanField, AITagsField, AIForeignKeyField) populated asynchronously via Celery and pydantic-ai.

Installation

pip install crudkit[api]          # REST API included
pip install crudkit[assistant]    # + AI assistant sidebar (Channels)
pip install crudkit[mcp]          # + remote MCP server with OAuth (e.g. a Claude connector)

INSTALLED_APPS = [
    ...,
    "rest_framework",
    "crudkit",
    "crudkit_assistant",  # optional
]

REST_FRAMEWORK = {
    "DEFAULT_PERMISSION_CLASSES": [
        "crudkit_api.permissions.CrudKitModelPermissions",
    ],
    "DEFAULT_PAGINATION_CLASS": "crudkit_api.pagination.CrudKitPagination",
    "DEFAULT_FILTER_BACKENDS": ["crudkit_api.filters.BasicFilter"],
    "PAGE_SIZE": 50,
}

# urls.py — one include registers a full CRUD API for every TYPE_ID model
urlpatterns = [path("api/v1/", include("crudkit_api.urls"))]

The assistant sidebar talks over a WebSocket at ws/assistant/, next to the realtime ws/changes/ socket; route both in your ASGI application (see examples/demo/demo/asgi.py):

application = ProtocolTypeRouter({
    "http": get_asgi_application(),
    "websocket": URLRouter(
        crudkit_api.routing.websocket_urlpatterns + crudkit_assistant.routing.websocket_urlpatterns
    ),
})

The sidebar sees what the user has on screen — the open record, or the list with its saved view, search, filters, visible and selected rows — and can search and read across record types. It only proposes changes (to any record the user may change); each one waits for Confirm. Conversations are stored per user (AssistantConversation, ASC) and resume after a reload. The SPA only shows the assistant when an AI model is configured (CRUDKIT_AI_MODEL or CRUDKIT_AI_MODEL_FACTORY).

Company knowledge for the AI lives in AI context documents (AIContext, AIC), which users edit in the UI at /AIC (add a saved view to the menu to link it). Active documents without model_types go into the assistant's instructions, joined by documents scoped to a type while a record or list of that type is open; AI fields get both in a "Company context" section of their prompt. Code can render them with crudkit.llm.ai_context(type_id). The assistant proposes edits to these documents when the user teaches it something durable about the company.

CrudKit requires the standard Django model permissions for every API and assistant operation. Projects that need row-level rules can override CrudKitSettings.get_authorized_queryset(user, queryset, action); action is one of view, add, change, or delete. Model actions require change permission and can be narrowed further with CrudKitSettings.has_action_permission(user, instance, action_name).

Settings

MCP server

crudkit_mcp exposes the models as a remote MCP server (streamable HTTP) with its own OAuth 2.1 authorization server (dynamic client registration, PKCE, rotating refresh tokens), so it can be added as e.g. a Claude connector by URL.

INSTALLED_APPS = [..., "crudkit_mcp"]
LOGIN_URL = "/login/"  # the OAuth consent page needs a session login

urlpatterns = [
    path("api/v1/", include("crudkit_mcp.urls")),       # /api/v1/mcp, /api/v1/oauth/...
    path("", include("crudkit_mcp.well_known_urls")),   # /.well-known/oauth-* (site root)
    ...,
]

The tool set is fixed — records are addressed by TYPE_ID and CK-ID, so the same tools serve any project:

Five more tools change data: create_record, update_record, run_action, add_note and undo. On the consent page the user picks what the client may do:

• Read only — the read scope; no write tools.
• Propose changes — the propose scope, offered when crudkit_assistant is installed. The write tools validate their input as usual but change nothing: each files a proposal and returns {"status": "pending_approval", "proposal": "ASP12"}. The user confirms or skips it in the Inbox's Proposals tab.
• Write directly — the write scope, only with CRUDKIT_MCP_WRITE_ENABLED. Each write returns the change_set it made; undo reverts one. Actions and fields that require approval (see docs/concepts.md) are still only proposed.

Writes and proposals are recorded as made over MCP by the token's OAuth client, and limited by CRUDKIT_MCP_WRITE_RATE.

Every call is filtered through the token user's model, row and action permissions, so a type the user can't view isn't listed and can't be read. CrudKit's own models and Django's (including User) are not exposed, except background agents (AGT), which clients can propose; narrow the rest with CRUDKIT_MCP_MODELS = ["CMP", "PER", ...] or opt a single model out with CrudKitSettings.mcp_exclude = True.

Background agents

With crudkit_assistant installed, users can save agents (TYPE_ID AGT): instructions the assistant carries out on its own, on a record that was just created or changed, on the records of a saved view on a schedule, or when someone clicks Run now. Each go is an AgentRun (AGR) with the agent's summary and the proposals it made. See docs/concepts.md for the details.

Runs are Celery tasks (crudkit_assistant.tasks.run_agent). For scheduled agents, add the scheduler task to Celery beat:

CELERY_BEAT_SCHEDULE = {
    "crudkit-scheduled-agents": {
        "task": "crudkit_assistant.tasks.run_scheduled_agents",
        "schedule": 300,  # every 5 minutes; each agent runs when its interval has passed
    },
}

Agents start from logged changes (the REST API, MCP, the assistant, actions), so plain ORM saves in project code do not trigger them. The enabled agents per type are cached in the Django cache for up to a minute.

Bundled frontend

The wheel ships the built CrudKit web SPA. To serve it, add the app, the context processor, a config dict, and a catch-all url include (last!):

INSTALLED_APPS = [..., "crudkit_frontend"]

TEMPLATES = [{
    ...,
    "OPTIONS": {"context_processors": [
        ...,
        "crudkit_frontend.context_processors.crudkit_config",
    ]},
}]

CRUDKIT_FRONTEND_CONFIG = {"app_name": "My App"}  # injected into the SPA at runtime
CRUDKIT_FRONTEND_LOGIN_REQUIRED = False  # True → redirect anonymous users to LOGIN_URL

# urls.py — must be the LAST pattern; everything unmatched serves the SPA
urlpatterns = [..., path("", include("crudkit_frontend.urls"))]

Static assets are served by django.contrib.staticfiles (or WhiteNoise et al.) from crudkit_frontend/static/, under whatever STATIC_URL the project uses — nothing assumes the default static/ prefix. Contributors hacking on the SPA itself run the Vite dev server from ../frontend against any CrudKit backend; npm run build there regenerates the bundled assets.

Running the tests

cd backend
uv sync --all-extras
uv run manage.py test crudkit crudkit_api crudkit_assistant crudkit_frontend crudkit_mcp tests

License

MIT