crudkit 0.4.0__tar.gz → 0.6.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (169) hide show
  1. {crudkit-0.4.0 → crudkit-0.6.0}/.gitignore +1 -0
  2. crudkit-0.6.0/CHANGELOG.md +318 -0
  3. {crudkit-0.4.0 → crudkit-0.6.0}/PKG-INFO +86 -10
  4. {crudkit-0.4.0 → crudkit-0.6.0}/README.md +79 -8
  5. {crudkit-0.4.0 → crudkit-0.6.0}/pyproject.toml +7 -3
  6. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/ai_backend.py +7 -3
  7. crudkit-0.6.0/src/crudkit/audit.py +63 -0
  8. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/authorization.py +25 -3
  9. crudkit-0.6.0/src/crudkit/decorators.py +12 -0
  10. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/llm.py +34 -0
  11. crudkit-0.6.0/src/crudkit/migrations/0004_changelog_audit.py +94 -0
  12. crudkit-0.6.0/src/crudkit/migrations/0005_aicontext.py +86 -0
  13. crudkit-0.6.0/src/crudkit/migrations/0006_changelog_audit_indexes.py +58 -0
  14. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/models.py +190 -42
  15. crudkit-0.6.0/src/crudkit/realtime.py +37 -0
  16. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/signals.py +33 -2
  17. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/tasks.py +1 -1
  18. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/tests/test_ai_backend.py +7 -1
  19. crudkit-0.6.0/src/crudkit/tests/test_ai_context.py +79 -0
  20. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/tests/test_ai_tasks.py +1 -0
  21. crudkit-0.6.0/src/crudkit/tests/test_audit.py +400 -0
  22. crudkit-0.6.0/src/crudkit/tests/test_hardening.py +178 -0
  23. crudkit-0.6.0/src/crudkit/tests/test_view_filters.py +62 -0
  24. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_api/authentication.py +5 -0
  25. crudkit-0.6.0/src/crudkit_api/consumers.py +71 -0
  26. crudkit-0.6.0/src/crudkit_api/filters.py +85 -0
  27. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_api/metadata.py +10 -2
  28. crudkit-0.6.0/src/crudkit_api/records.py +333 -0
  29. crudkit-0.6.0/src/crudkit_api/routing.py +8 -0
  30. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_api/serializers.py +19 -5
  31. crudkit-0.6.0/src/crudkit_api/services.py +529 -0
  32. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_api/tests/test_authorization.py +2 -1
  33. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_api/tests/test_metadata.py +10 -1
  34. crudkit-0.6.0/src/crudkit_api/tests/test_realtime.py +121 -0
  35. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_api/tests/test_user_profile.py +9 -0
  36. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_api/urls.py +2 -1
  37. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_api/views.py +108 -8
  38. crudkit-0.6.0/src/crudkit_api/ws_auth.py +116 -0
  39. crudkit-0.6.0/src/crudkit_assistant/admin.py +36 -0
  40. crudkit-0.6.0/src/crudkit_assistant/agent.py +198 -0
  41. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_assistant/apps.py +3 -0
  42. crudkit-0.6.0/src/crudkit_assistant/background.py +327 -0
  43. crudkit-0.6.0/src/crudkit_assistant/consumers.py +362 -0
  44. crudkit-0.6.0/src/crudkit_assistant/deps.py +29 -0
  45. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_assistant/execution.py +25 -2
  46. crudkit-0.6.0/src/crudkit_assistant/migrations/0002_assistantconversation.py +76 -0
  47. crudkit-0.6.0/src/crudkit_assistant/migrations/0003_proposal_revert.py +25 -0
  48. crudkit-0.6.0/src/crudkit_assistant/migrations/0004_proposal_sources.py +83 -0
  49. crudkit-0.6.0/src/crudkit_assistant/migrations/0005_agent_agentrun.py +269 -0
  50. crudkit-0.6.0/src/crudkit_assistant/models.py +480 -0
  51. crudkit-0.6.0/src/crudkit_assistant/proposals.py +45 -0
  52. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_assistant/routing.py +2 -0
  53. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_assistant/runner.py +126 -47
  54. crudkit-0.6.0/src/crudkit_assistant/screen.py +123 -0
  55. crudkit-0.6.0/src/crudkit_assistant/signals.py +18 -0
  56. crudkit-0.6.0/src/crudkit_assistant/tasks.py +16 -0
  57. crudkit-0.6.0/src/crudkit_assistant/tests/test_agents.py +411 -0
  58. crudkit-0.6.0/src/crudkit_assistant/tests/test_approvals.py +184 -0
  59. crudkit-0.6.0/src/crudkit_assistant/tests/test_hardening.py +413 -0
  60. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_assistant/tests/test_proposals.py +52 -6
  61. crudkit-0.6.0/src/crudkit_assistant/tests/test_sidebar.py +483 -0
  62. crudkit-0.6.0/src/crudkit_assistant/tools.py +583 -0
  63. crudkit-0.6.0/src/crudkit_assistant/utils.py +12 -0
  64. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_frontend/context_processors.py +6 -1
  65. crudkit-0.6.0/src/crudkit_frontend/static/crudkit_frontend/assets/index-BEOWlk3y.css +1 -0
  66. crudkit-0.6.0/src/crudkit_frontend/static/crudkit_frontend/assets/index-BJRt310o.js +1625 -0
  67. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_frontend/templates/crudkit_frontend/index.html +2 -2
  68. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_frontend/tests/test_frontend.py +2 -1
  69. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_mcp/apps.py +2 -0
  70. crudkit-0.6.0/src/crudkit_mcp/checks.py +27 -0
  71. crudkit-0.6.0/src/crudkit_mcp/conf.py +54 -0
  72. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_mcp/oauth.py +18 -5
  73. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_mcp/server.py +35 -2
  74. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_mcp/templates/crudkit_mcp/authorize.html +11 -5
  75. crudkit-0.6.0/src/crudkit_mcp/tests/test_hardening.py +75 -0
  76. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_mcp/tests/test_mcp.py +290 -9
  77. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_mcp/tests/test_oauth.py +49 -11
  78. crudkit-0.6.0/src/crudkit_mcp/tools.py +323 -0
  79. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_mcp/views.py +1 -1
  80. {crudkit-0.4.0 → crudkit-0.6.0}/tests/settings.py +3 -0
  81. crudkit-0.6.0/tests/testapp/migrations/0003_ticket_watchers.py +20 -0
  82. {crudkit-0.4.0 → crudkit-0.6.0}/tests/testapp/models.py +1 -0
  83. crudkit-0.4.0/CHANGELOG.md +0 -107
  84. crudkit-0.4.0/src/crudkit/decorators.py +0 -9
  85. crudkit-0.4.0/src/crudkit_api/filters.py +0 -117
  86. crudkit-0.4.0/src/crudkit_api/services.py +0 -235
  87. crudkit-0.4.0/src/crudkit_assistant/admin.py +0 -27
  88. crudkit-0.4.0/src/crudkit_assistant/agent.py +0 -133
  89. crudkit-0.4.0/src/crudkit_assistant/consumers.py +0 -296
  90. crudkit-0.4.0/src/crudkit_assistant/deps.py +0 -11
  91. crudkit-0.4.0/src/crudkit_assistant/models.py +0 -87
  92. crudkit-0.4.0/src/crudkit_assistant/tools.py +0 -264
  93. crudkit-0.4.0/src/crudkit_assistant/utils.py +0 -28
  94. crudkit-0.4.0/src/crudkit_frontend/static/crudkit_frontend/assets/index-CU-EhJ5W.js +0 -1604
  95. crudkit-0.4.0/src/crudkit_frontend/static/crudkit_frontend/assets/index-D_4ufdxB.css +0 -1
  96. crudkit-0.4.0/src/crudkit_mcp/conf.py +0 -21
  97. crudkit-0.4.0/src/crudkit_mcp/tools.py +0 -457
  98. {crudkit-0.4.0 → crudkit-0.6.0}/manage.py +0 -0
  99. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/__init__.py +0 -0
  100. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/admin.py +0 -0
  101. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/apps.py +0 -0
  102. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/checks.py +0 -0
  103. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/fields.py +0 -0
  104. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/management/__init__.py +0 -0
  105. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/management/commands/__init__.py +0 -0
  106. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/management/commands/add_default_exchange_rates.py +0 -0
  107. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/management/commands/backfill_ai_fields.py +0 -0
  108. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/management/commands/set_exchange_rate.py +0 -0
  109. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/migrations/0001_squashed.py +0 -0
  110. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/migrations/0002_workspace.py +0 -0
  111. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/migrations/0003_enforce_data_invariants.py +0 -0
  112. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/migrations/__init__.py +0 -0
  113. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/profile.py +0 -0
  114. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/templatetags/__init__.py +0 -0
  115. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/templatetags/crm_forms.py +0 -0
  116. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/templatetags/crm_time.py +0 -0
  117. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/templatetags/gravatar.py +0 -0
  118. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/templatetags/model_magic.py +0 -0
  119. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/tests/__init__.py +0 -0
  120. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/tests/test_ai_fields.py +0 -0
  121. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/tests/test_authorization.py +0 -0
  122. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/tests/test_backfill_command.py +0 -0
  123. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/tests/test_fields.py +0 -0
  124. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/tests/test_integrity.py +0 -0
  125. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/tests/test_llm.py +0 -0
  126. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/tests/test_money.py +0 -0
  127. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/tests/test_tasks.py +0 -0
  128. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/tests/test_workspace.py +0 -0
  129. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/utils.py +0 -0
  130. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit/widgets.py +0 -0
  131. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_api/__init__.py +0 -0
  132. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_api/pagination.py +0 -0
  133. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_api/permissions.py +0 -0
  134. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_api/tests/__init__.py +0 -0
  135. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_api/tests/test_email_id_serialization.py +0 -0
  136. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_api/tests/test_filters.py +0 -0
  137. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_api/tests/test_list_serialization.py +0 -0
  138. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_api/tests/test_merge.py +0 -0
  139. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_assistant/__init__.py +0 -0
  140. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_assistant/migrations/0001_initial.py +0 -0
  141. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_assistant/migrations/__init__.py +0 -0
  142. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_assistant/tests/__init__.py +0 -0
  143. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_frontend/__init__.py +0 -0
  144. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_frontend/apps.py +0 -0
  145. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_frontend/static/crudkit_frontend/assets/favicon-Cit_9t8D.svg +0 -0
  146. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_frontend/tests/__init__.py +0 -0
  147. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_frontend/tests/templates/crudkit_frontend/index.html +0 -0
  148. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_frontend/tests/urls.py +0 -0
  149. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_frontend/urls.py +0 -0
  150. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_frontend/views.py +0 -0
  151. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_mcp/__init__.py +0 -0
  152. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_mcp/admin.py +0 -0
  153. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_mcp/authentication.py +0 -0
  154. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_mcp/migrations/0001_initial.py +0 -0
  155. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_mcp/migrations/__init__.py +0 -0
  156. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_mcp/models.py +0 -0
  157. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_mcp/tests/__init__.py +0 -0
  158. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_mcp/urls.py +0 -0
  159. {crudkit-0.4.0 → crudkit-0.6.0}/src/crudkit_mcp/well_known_urls.py +0 -0
  160. {crudkit-0.4.0 → crudkit-0.6.0}/tests/__init__.py +0 -0
  161. {crudkit-0.4.0 → crudkit-0.6.0}/tests/celery.py +0 -0
  162. {crudkit-0.4.0 → crudkit-0.6.0}/tests/testapp/__init__.py +0 -0
  163. {crudkit-0.4.0 → crudkit-0.6.0}/tests/testapp/adapters.py +0 -0
  164. {crudkit-0.4.0 → crudkit-0.6.0}/tests/testapp/ai.py +0 -0
  165. {crudkit-0.4.0 → crudkit-0.6.0}/tests/testapp/apps.py +0 -0
  166. {crudkit-0.4.0 → crudkit-0.6.0}/tests/testapp/migrations/0001_initial.py +0 -0
  167. {crudkit-0.4.0 → crudkit-0.6.0}/tests/testapp/migrations/0002_customer_currency.py +0 -0
  168. {crudkit-0.4.0 → crudkit-0.6.0}/tests/testapp/migrations/__init__.py +0 -0
  169. {crudkit-0.4.0 → crudkit-0.6.0}/tests/urls.py +0 -0
@@ -6,6 +6,7 @@ build/
6
6
  *.egg-info/
7
7
  .DS_Store
8
8
  db.sqlite3
9
+ .env
9
10
  node_modules/
10
11
  frontend/dist/
11
12
  uv.lock
@@ -0,0 +1,318 @@
1
+ # Changelog
2
+
3
+ ## 0.6.0 (2026-09-29)
4
+
5
+ - Hardening of proposals, undo and agents (#58):
6
+ - A filed `AssistantProposal` can't be edited (its `clean()` refuses, so a REST PATCH
7
+ returns 400), and Confirm checks that both the confirming user and the proposal's creator
8
+ may make the change. Previously a user could rewrite their own pending proposal to target
9
+ any record and have a superuser confirm it.
10
+ - Confirm and Skip are atomic: two at once apply a proposal once; the second gets 409.
11
+ - Generic relation fields (`target`, `parent_object`, `related_object`) only accept records
12
+ the requesting user can view, and answer 400 (not 500) for unknown ids.
13
+ - Undoing a change set that touches an approval field or an approval-required action needs
14
+ approval: MCP `undo` with the `write` scope proposes it, and agents leave it pending
15
+ (`crudkit_api.services.revert_requires_approval`).
16
+ - Only superusers may change what an agent that runs as another user does (its owner may
17
+ still disable it); edits, merges and reverts all run the check. Agents may only be pointed
18
+ at types exposed to the assistant (not CrudKit's bookkeeping; `CRUDKIT_MCP_MODELS` limits
19
+ MCP only).
20
+ - "Run now", "Dry run" and "Revert this run" are `requires_approval`, so agents and MCP
21
+ clients can't start agents. Agent runs no longer load a model's `assistant_tools`.
22
+ - `AIContext` fields are `approval_fields` (and `AIC` is `ai_exposed`); only the sidebar,
23
+ not agents, is asked to propose edits to it. `model_types` must list known TYPE_IDs, and
24
+ the rendered context is capped at `CRUDKIT_AI_CONTEXT_MAX_CHARS` (default 20000).
25
+ - Proposal tools check foreign keys (the target must exist and be visible) and refuse
26
+ read-only fields, instead of the serializer silently storing None or ignoring them;
27
+ numeric choices are validated too. Proposals can't target CrudKit's own bookkeeping.
28
+ - A record's change history needs `view_changelog` as well as seeing the record: the History
29
+ tab, MCP `get_record`'s `changelog` and the assistant's `get_changelog`.
30
+ - Robustness (#58):
31
+ - Many-to-many changes are logged (the sorted related ids before and after, in the current
32
+ change set), shown in History, revertible with the usual conflict check, and matched by
33
+ agents' `watch_fields`. Changes from the reverse side aren't logged.
34
+ - Starting agent runs locks the agent's row, so concurrent triggers can't exceed
35
+ `max_runs_per_day`.
36
+ - `source`/`client` are documented as attribution only: an API client can present itself as
37
+ the UI, so nothing authorizes on them (only `agent`, which no request can claim, changes
38
+ behaviour).
39
+ - The change log indexes from `crudkit 0004` are built by the new `crudkit 0006`, outside a
40
+ transaction and `CONCURRENTLY` on PostgreSQL, so large change logs aren't locked for writes.
41
+ - Agent triggers run as robust on-commit callbacks: a broken agent is logged and no longer
42
+ fails the write that triggered it. A record with a queued run isn't queued again (runs
43
+ stuck for over an hour don't count).
44
+ - Scheduled agents are claimed atomically (overlapping beat ticks start them once), capped
45
+ runs take the least recently worked-on records first, and the daily cap works with
46
+ `USE_TZ = False`. Re-enabling an agent resets its failure count.
47
+ - `update_or_create_external` logs only when something changed.
48
+ - The MCP write limit no longer fails every write on a cache that stores nothing, and system
49
+ checks report an invalid `CRUDKIT_MCP_WRITE_RATE` (`crudkit_mcp.E001`) and, with
50
+ `CRUDKIT_MCP_WRITE_ENABLED`, a per-process cache (`crudkit_mcp.W001`).
51
+ - Reverts run the model's `clean()` and report database errors as 400; concurrent reverts of
52
+ one change set can't both pass; an action that deleted its record is logged as a delete;
53
+ an action renamed since can't be undone (it can't be permission-checked).
54
+
55
+ - Background agents (`crudkit_assistant`, migration `crudkit_assistant 0005`). An `Agent`
56
+ (TYPE_ID `AGT`) is saved instructions the assistant carries out without a person: when a
57
+ record of its `model_type` is created or changed (optionally only when `watch_fields`
58
+ changed, and only for records in its saved `view`), on an hourly/daily/weekly schedule, or on
59
+ "Run now". By default it proposes changes for the Inbox; in auto mode it applies those that
60
+ need no approval, as `run_as`. Each run is an `AgentRun` (`AGR`) with the summary, the
61
+ proposals (the preview) and the change set it applied, which "Revert this run" undoes.
62
+ "Dry run on latest matching record" shows what it would propose without saving anything.
63
+ Guards: `max_records_per_run`, `max_runs_per_day`, and auto-disable after 3 failed runs in a
64
+ row (noted on the agent's feed). Agents are triggered by ChangeLog entries, so plain ORM saves
65
+ and changes made by agents don't trigger agents. Users see and edit their own agents and runs;
66
+ `run_as` defaults to the creator and only superusers can change it. (#57)
67
+ - Hosts add `crudkit_assistant.tasks.run_scheduled_agents` to `CELERY_BEAT_SCHEDULE` (every 5
68
+ minutes) for scheduled agents.
69
+ - The assistant has a new `propose_create` tool, so the sidebar can create records, agents
70
+ included ("every Monday, flag at-risk customers"). `AssistantDeps` gains `source`, `client`,
71
+ `agent_instructions` and `dry_run`; `AssistantProposal.apply()` takes an optional
72
+ `change_set`, and `needs_approval()` tells whether a proposal needs a person.
73
+ - New `CrudKitSettings.default_inlines`: inlines the detail page shows when no Layout exists
74
+ (REST metadata `default_inlines`). New `CrudKitSettings.ai_exposed` lists one of CrudKit's own
75
+ models in the MCP and assistant type listings (`Agent` sets it).
76
+ - Notes added through the services layer (the assistant, MCP `add_note`, agents) are now logged
77
+ as a ChangeLog create on the note, so undoing their change set removes the note.
78
+ - SPA: agent runs show their summary and proposals; proposals and history entries from agents
79
+ read "Agent: <name>".
80
+
81
+ - SPA: the "+" in a kanban column header opens the inline create modal, prefilled with the
82
+ column's value; the modal is larger. (#55)
83
+ - Approvals. Models declare which changes need a person's approval:
84
+ `@crm_action(..., requires_approval=True)` (the new keyword is optional) and
85
+ `CrudKitSettings.approval_fields`; `crudkit.authorization.requires_approval(model, action, fields)`
86
+ checks them. The rule binds MCP clients and agents; people in the UI and REST API are the
87
+ approvers. REST metadata actions carry `requires_approval`, and the SPA shows a shield on them. (#54)
88
+ - `crudkit_mcp`: a new `propose` OAuth scope (offered when `crudkit_assistant` is installed).
89
+ The consent page is now a choice of Read only / Propose changes / Write directly (the last
90
+ only with `CRUDKIT_MCP_WRITE_ENABLED`); the form field is `access` instead of the `write`
91
+ checkbox, and tokens are granted `read`, `read propose` or `read write`. With `propose`, the
92
+ write tools validate as before, then file a proposal and return
93
+ `{"status": "pending_approval", "proposal": "ASP12"}`; `undo` proposes a revert. With `write`,
94
+ approval-required actions and writes touching `approval_fields` are proposed too.
95
+ `CRUDKIT_MCP_EXTRA_TOOLS` write tools need `write`. `describe_types` now reports `actions` as
96
+ `{name: {"label", "requires_approval"}}` plus the type's `approval_fields`.
97
+ - `crudkit_assistant`: `AssistantProposal` gets kind `create` (payload `{type, fields}`; the
98
+ target is set once created), `source` (assistant, mcp, agent) and `client`; `session_key` may
99
+ be blank (migration `crudkit_assistant 0004`). Confirm and Skip are `@crm_action`s
100
+ (`POST /api/v1/ASP/<pk>/action/`), shared with the sidebar. A confirmed proposal is its own
101
+ change set, logged with the proposal's source and client. Users see only their own proposals
102
+ (superusers see all). `AssistantProposal.skip(user)` is now `mark_skipped(user)`. New
103
+ `crudkit_assistant.proposals.create_proposal()`.
104
+ - New `CrudKitSettings.owner_access`: signed-in users may view and change the rows they
105
+ created without the Django model permission. `AssistantProposal` uses it.
106
+ - `GET /api/v1/user/me/` reports `assistant.proposals`. New service `check_action()`.
107
+ - SPA: a Proposals tab in the Inbox lists pending proposals from the sidebar and MCP clients,
108
+ with Confirm and Skip; the Inbox menu item shows the pending count.
109
+ - AI context. New `AIContext` model (TYPE_ID `AIC`, migration `crudkit 0005`): markdown
110
+ documents users maintain in the UI (ideal customer, why customers buy, tone of voice,
111
+ playbooks), global or scoped to model types via `model_types`, with `active` and `order`.
112
+ `crudkit.llm.ai_context(type_id)` renders the active ones, and every LLM feature reads it:
113
+ the assistant's instructions carry the global documents and the ones for the type on
114
+ screen, and AI fields get a "Company context" section in their prompt
115
+ (`crudkit.ai_backend.process()` takes an optional `type_id`). The assistant proposes edits to
116
+ these documents when the user teaches it something durable about the company. (#53)
117
+ - SPA: after a password login the SPA loads the full user profile, so the assistant appears
118
+ without a reload. (#53)
119
+ - Undo and history. Every ChangeLog entry now records who made it and how: `action`
120
+ (create/update/delete/restore/action/merge/revert), `source` (ui, api, mcp, assistant,
121
+ agent, revert or system), `client` (the API `Client-Id` or MCP OAuth client), a `change_set`
122
+ UUID shared by everything one request, tool call or confirmed proposal changed, and a
123
+ `label`. Entry points set this with the new `crudkit.audit.audit()` context manager;
124
+ outside one, entries are `system`. New ChangeLog fields and an index on the related object
125
+ (migration `crudkit 0004`). (#52)
126
+ - Deletes snapshot the deleted record's values and record the user who deleted it (it was
127
+ the record's creator). `@crm_action` runs (REST and `services.run_action`), merges and
128
+ `update_or_create_external` are now logged. File and image fields log correctly.
129
+ - `ChangeLog.objects.create_from_objects()` takes optional `user`, `action` and `label`.
130
+ - `GET /api/v1/<TYPE>/<pk>/history/` lists a record's changes grouped by change set;
131
+ `POST /api/v1/changesets/<uuid>/revert/` undoes a change set (409 with the conflicts if
132
+ the records changed since, unless `{"force": true}`; merges can't be reverted);
133
+ `POST /api/v1/<TYPE>/<pk>/restore/` brings back a deleted record. Write responses carry
134
+ the change set in `X-CrudKit-Change-Set`. New services `revert_change_set`,
135
+ `restore_object`, `get_history`, `perform_action`.
136
+ - SPA: a History tab on every record with per-change Revert, Undo in the toast after save
137
+ and delete, and a Restore banner on deleted records.
138
+ - `crudkit_mcp`: write tools return their `change_set`; a new `undo` tool reverts one;
139
+ writes are limited per token by `CRUDKIT_MCP_WRITE_RATE` (default `"60/min"`).
140
+ - `crudkit_assistant`: `get_changelog` returns each entry's change set; new
141
+ `propose_revert` tool (a Confirm card, proposal kind `revert`, migration
142
+ `crudkit_assistant 0003`); confirmed proposals can be undone from their card.
143
+ - `crudkit_assistant`: new `propose_bulk_patch` tool — one call drafts the same field change on
144
+ up to 100 records, still one Confirm/Skip card (and permission check) per record, skipping
145
+ records that already have the values. The prompt no longer asks for `get_object`, `get_feed`
146
+ and `describe_object` on every record of a bulk change: the model reads the rows on screen (or
147
+ `list_records`) and `describe_types(type)` once, so "set all of these to high priority" takes
148
+ a few tool calls instead of three per record. (#51)
149
+ - `crudkit_assistant`: `describe_object` no longer fails on models with lazily translated
150
+ `help_text`. (#50)
151
+ - Packaging: require `pydantic-ai-slim>=2.51` (the tested version); 1.x is incompatible with the
152
+ assistant. (#49)
153
+
154
+ ## 0.5.0 (2026-09-27)
155
+
156
+ - `crudkit_assistant`: the assistant is now a sidebar available on every page (toggle in the
157
+ topbar or ⌘J / Ctrl+J), replacing the per-record floating window. The SPA reports what is on
158
+ screen — open record and tab, or list type, saved view, search, filters, visible and
159
+ selected rows — and each turn starts with a `[Screen]` block describing it; ids are re-read
160
+ through the user's permissions. New read tools `search`, `describe_types`, `list_records`,
161
+ `get_record`, `get_screen_rows`; record and propose tools take an optional `id` and default
162
+ to the record on screen, so proposals can target any record the user may change.
163
+ Conversations are saved (`AssistantConversation`, ASC, migration `0002`) and resume after a
164
+ reload. The automatic briefing on connect is gone; the sidebar offers suggestions instead.
165
+ Turns stream: the model's reasoning and reply appear as they are generated, and each tool
166
+ call shows as a step ("Reading RDG3", "Drafting a change to RDG3") with a running timer,
167
+ collapsing to "N steps · 38s" afterwards. Confirm/Skip apply immediately, also while a
168
+ turn is running, and no longer start a model turn: the outcome is passed to the agent with
169
+ the next message. "Confirm all / Skip all" resolves every waiting card (`confirm` takes
170
+ `ids`).
171
+ New WebSocket route `ws/assistant/` (the per-record route still works).
172
+ **Breaking for custom `assistant_tools`:** `AssistantDeps` is now `user_id`, `session_key`,
173
+ `screen`; `object_type_id`/`object_pk` remain as read-only properties derived from the open
174
+ record. The user profile's `assistant` gains `enabled` — true only when `crudkit_assistant`
175
+ is installed and an AI model is configured (`CRUDKIT_AI_MODEL` /
176
+ `CRUDKIT_AI_MODEL_FACTORY`); the SPA hides the assistant otherwise. (#47)
177
+ - `crudkit_api`: new `crudkit_api.records` with the type descriptions, listing, saved-view and
178
+ record reads the MCP tools used, now shared with the assistant. (#47)
179
+ - Demo: installs `crudkit_assistant` next to the realtime socket; set `DEMO_AI_MODEL` to a
180
+ pydantic-ai model name to try the assistant. (#47)
181
+ - `crudkit_mcp`: `list_records` takes a saved `view` (VIW CK-ID) and returns its rows with the
182
+ view's filters, ordering and columns applied; `describe_types` lists a type's views. Access
183
+ follows the REST API's `_view`: the view must be public or the user's own, and the user must
184
+ be able to view its type. (#42)
185
+ - `crudkit_api`: saved-view ordering moved out of `BasicFilter` into `get_order_fields` and
186
+ `order_queryset` in `crudkit_api.filters`. (#42)
187
+ - `crudkit_frontend`: saved views get a visual filter editor instead of the raw JSON
188
+ textarea — per-field value pickers (choices, yes/no, numbers, dates, related records),
189
+ variables like "Current user" (`${user}`), and invalid filters highlighted in red and
190
+ editable instead of breaking the form. (#43)
191
+ - `crudkit`: `View.clean()` rejects unknown filter comparators and entries that aren't
192
+ exactly `[field, comparator, value]`, so they fail on save (400) instead of when the view
193
+ is applied (500). (#43)
194
+ - `crudkit_frontend`: the sidebar shows the installed crudkit version (`crudkit vX.Y.Z`)
195
+ at the bottom; exposed to the SPA as `crudkit_version` in the frontend config. (#41)
196
+ - `crudkit_frontend`: the command palette labels result groups with the type's name
197
+ (`Companies (CMP)`) and adds a "Show all <type>" row when a type has more matches than
198
+ shown, linking to its list filtered by the query. The search endpoint now returns one extra
199
+ row per type (6, or 21 for a `CMP:` scoped search) so the palette can tell. (#44)
200
+ - Realtime change hints (new extra `crudkit[realtime]`; `crudkit[assistant]` now includes
201
+ it): every save/delete of a TYPE_ID model sends `{model, id, action, by}` after commit to
202
+ a new `ws/changes/` socket (saves only to users who may view that row; deletes without
203
+ `id`/`by`), and the SPA invalidates the affected lists, details, menu,
204
+ badges and worklog instead of polling. Polling and focus refetches only run while the
205
+ socket is down. **Upgrade:** add `crudkit_api.routing.websocket_urlpatterns` to the
206
+ project's ASGI `URLRouter`; it needs a shared `CHANNEL_LAYERS` (e.g. Redis) when running
207
+ more than one process. Without a channel layer the socket closes (4503), and without the
208
+ route the SPA gives up after three attempts; either way it keeps polling as before. (#45)
209
+ - `crudkit_api`: `crudkit_api.ws_auth.AuthenticatedConsumer` — the session-or-JWT-first-frame
210
+ WebSocket auth, extracted from the assistant consumer. (#45)
211
+ - `crudkit_frontend`: the edit form no longer overwrites typed values when the record is
212
+ refetched; it shows a "changed elsewhere — Reload" banner instead. (#45)
213
+
214
+ ## 0.4.0 (2026-09-24)
215
+
216
+ - `crudkit_mcp` (new app, `crudkit[mcp]`): remote MCP server + OAuth 2.1 provider, moved from
217
+ fenerum-crm. A fixed, type-parameterised tool set addressing records by TYPE_ID/CK-ID —
218
+ `describe_types`, `search`, `list_records`, `get_record`, and — with
219
+ `CRUDKIT_MCP_WRITE_ENABLED` and the `write` scope — `create_record`, `update_record`,
220
+ `run_action`, `add_note`; all respecting model/row/action permissions. New settings `CRUDKIT_MCP_SERVER_NAME`, `CRUDKIT_MCP_WRITE_ENABLED`,
221
+ `CRUDKIT_MCP_EXTRA_TOOLS`, `CRUDKIT_MCP_MODELS`, `CRUDKIT_MCP_BASE_URL`; new
222
+ `CrudKitSettings.mcp_exclude`. The consent page always grants `read` and offers `write`
223
+ as a checkbox. (#39)
224
+ - `crudkit`: `get_authorized_instance` moved from `crudkit_assistant.utils` to
225
+ `crudkit.authorization`. (#39)
226
+ - `crudkit_api`: new `crudkit_api.services` with the search, feed, change log and mutation
227
+ helpers shared by the REST API, the assistant and the MCP server. (#39)
228
+
229
+ ## 0.3.1 (2026-09-22)
230
+
231
+ - `crudkit_frontend`: feed items whose related object isn't an email (chat messages, calls,
232
+ meetings, ...) show the feed item's `body` instead of an empty frame. (#36)
233
+ - `crudkit_frontend`: views only appear in menus (sidebar, workspace tabs, command palette)
234
+ when `show_in_menu` is set. The shared Workspace section and workspace tabs only list public
235
+ views; per-type view tabs, the default-view pick and the command palette only list public or
236
+ own views, so superusers no longer see other users' private views there. (#37)
237
+
238
+ ## 0.3.0 (2026-09-21)
239
+
240
+ - `crudkit_frontend`: related-record pickers offer `+ Create <model> "<typed text>"`, which
241
+ opens the target's create form in a modal (prefilled from the first `search_fields` entry)
242
+ and selects the new record without leaving the form. Modals nest; Esc/Enter only affect the
243
+ topmost one. (#34)
244
+ - `crudkit_api`: the metadata endpoint also returns `search_fields`, `can_create` (add
245
+ permission for the requesting user) and `inline_create`. `build_model_metadata` takes an
246
+ optional `user`. (#34)
247
+ - `crudkit`: new `CrudKitSettings.inline_create` (default `True`); set `False` to hide the
248
+ inline create option for a model. (#34)
249
+ - `crudkit_frontend`: a failed Kanban/Swimlane drop shows the server's validation error
250
+ instead of a generic message. (#31)
251
+ - `crudkit_frontend`: inline email images are hidden behind a toggle; image attachments
252
+ preview on hover. (#32)
253
+
254
+ ## 0.2.3 (2026-09-21)
255
+
256
+ - `crudkit_api`: `GET /api/v1/` no longer returns 403 under `CrudKitModelPermissions`.
257
+ `has_permission` checks authentication first and honours DRF's
258
+ `_ignore_model_permissions`; the API root (`CrudKitRouter`/`CrudKitAPIRootView`) now lists
259
+ only the models the user may view. (#25)
260
+ - `crudkit_frontend`: the detail view wraps long (over 60 characters) and multiline text,
261
+ with a Show more/less toggle when it overflows, instead of a single ellipsised line. (#26)
262
+ - `crudkit_api`: fix a 500 when listing FeedItem or ExternalObject rows; generic relations
263
+ are no longer included in the list prefetch. (#27)
264
+ - `crudkit`: multi-table-inheritance children are reachable by their own CK-ID again; the
265
+ parent's `CrudKitIDField` accepts the TYPE_IDs of its descendants. (#28)
266
+
267
+ ## 0.2.2 (2026-09-19)
268
+
269
+ - `crudkit_api`: list endpoints no longer build a serializer per row. `GenericViewSet.list`
270
+ reuses one serializer for the whole page, `GenericSerializer.build_nested_field` caches the
271
+ generated nested field classes per (related model, depth), and the nested serializer behind a
272
+ forward FK is built once per field instead of once per value. A 500-row page of a model with
273
+ 11 FKs went from a 216 MB to a 15 MB peak downstream (72 MB to 8.5 MB in the test suite's
274
+ smaller fixtures) and serializes ~2.6x faster; the JSON is unchanged. Worker RSS on gunicorn
275
+ no longer climbs from refetching kanban/swimlane views, which request `page_size=500`.
276
+
277
+ - Workspaces: new `Workspace` model (TYPE_ID `WSP`) — switchable sidebar
278
+ apps that pin an ordered set of saved views as tabs, picked from a switcher
279
+ in the sidebar header. Purely additive: deployments with no Workspace rows
280
+ render exactly as before.
281
+
282
+ ## 0.2.1 (2026-08-11)
283
+
284
+ - `crudkit_frontend`: asset URLs are no longer hardcoded to `/static/`. The
285
+ SPA shell references its assets via `{% static %}` tags (so
286
+ `ManifestStaticFilesStorage` users also get hashed, cache-busted URLs), and
287
+ the JS bundle builds asset/chunk URLs at runtime from Django's
288
+ `STATIC_URL`, exposed by the shell as `window.__CRUDKIT_STATIC_URL__` via
289
+ the `crudkit_config` context processor. Projects with a custom
290
+ `STATIC_URL` (e.g. `assets/`) now work out of the box.
291
+
292
+ - The distribution is published on PyPI as **`crudkit`** (the planned
293
+ `django-crudkit` name was rejected as too similar to an existing project).
294
+ The importable packages (`crudkit`, `crudkit_api`, `crudkit_assistant`,
295
+ `crudkit_frontend`) are unchanged.
296
+ - `crudkit_frontend`: new Django app that ships the built CrudKit web SPA
297
+ inside the wheel. The Vite build emits hashed assets into
298
+ `crudkit_frontend/static/` and the SPA shell into
299
+ `crudkit_frontend/templates/crudkit_frontend/index.html`, which is served
300
+ by a catch-all `spa` view (include `crudkit_frontend.urls` last in your
301
+ urlconf). Branding/configuration is injected at runtime via the
302
+ `crudkit_config` context processor from the `CRUDKIT_FRONTEND_CONFIG`
303
+ setting; set `CRUDKIT_FRONTEND_LOGIN_REQUIRED = True` to redirect
304
+ anonymous users to `LOGIN_URL`.
305
+ - The React SPA source now lives in `frontend/` in this repository.
306
+
307
+ ## 0.1.0 (unreleased)
308
+
309
+ Initial extraction of CrudKit from the Fenerum CRM monolith:
310
+
311
+ - `crudkit`: `BaseCrudKitModel` with typed CK-IDs, audit columns, soft delete,
312
+ merge; `ChangeLog`, `FeedItem`, `ExternalObject`, `View`, `Layout`,
313
+ `WorkLog`, `ExchangeRate`, `Snippet`; `MoneyField`/`CurrencyField`; AI
314
+ fields with Celery processing; dashboard widget base classes.
315
+ - `crudkit_api`: generic DRF serializer/viewset/router over the `TYPE_ID`
316
+ registry, metadata endpoints, saved-view filtering, pagination, JWT auth.
317
+ - `crudkit_assistant`: per-object AI assistant over Channels WebSockets with
318
+ a Confirm-gated proposal flow.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: crudkit
3
- Version: 0.4.0
3
+ Version: 0.6.0
4
4
  Summary: A metadata-driven CRUD framework for Django: typed object IDs, soft delete, merge, change log, activity feed, saved views, AI fields and a generic REST API.
5
5
  Project-URL: Homepage, https://github.com/fenerum/crudkit
6
6
  Project-URL: Changelog, https://github.com/fenerum/crudkit/blob/main/backend/CHANGELOG.md
@@ -18,7 +18,7 @@ Requires-Python: >=3.12
18
18
  Requires-Dist: celery>=5.3
19
19
  Requires-Dist: django-phonenumber-field[phonenumberslite]>=8.0
20
20
  Requires-Dist: django>=5.1
21
- Requires-Dist: pydantic-ai-slim>=1.39
21
+ Requires-Dist: pydantic-ai-slim>=2.51
22
22
  Requires-Dist: pydantic>=2.11
23
23
  Requires-Dist: pyjwt>=2.9
24
24
  Provides-Extra: api
@@ -34,6 +34,11 @@ Provides-Extra: mcp
34
34
  Requires-Dist: djangorestframework-simplejwt>=5.4; extra == 'mcp'
35
35
  Requires-Dist: djangorestframework>=3.15; extra == 'mcp'
36
36
  Requires-Dist: drf-extra-fields>=3.7; extra == 'mcp'
37
+ Provides-Extra: realtime
38
+ Requires-Dist: channels>=4.1; extra == 'realtime'
39
+ Requires-Dist: djangorestframework-simplejwt>=5.4; extra == 'realtime'
40
+ Requires-Dist: djangorestframework>=3.15; extra == 'realtime'
41
+ Requires-Dist: drf-extra-fields>=3.7; extra == 'realtime'
37
42
  Description-Content-Type: text/markdown
38
43
 
39
44
  # crudkit
@@ -72,7 +77,7 @@ fields (`AISummaryField`, `AICategoryField`, `AIBooleanField`, `AITagsField`,
72
77
 
73
78
  ```
74
79
  pip install crudkit[api] # REST API included
75
- pip install crudkit[assistant] # + per-object AI assistant (Channels)
80
+ pip install crudkit[assistant] # + AI assistant sidebar (Channels)
76
81
  pip install crudkit[mcp] # + remote MCP server with OAuth (e.g. a Claude connector)
77
82
  ```
78
83
 
@@ -97,6 +102,36 @@ REST_FRAMEWORK = {
97
102
  urlpatterns = [path("api/v1/", include("crudkit_api.urls"))]
98
103
  ```
99
104
 
105
+ The assistant sidebar talks over a WebSocket at `ws/assistant/`, next to the
106
+ realtime `ws/changes/` socket; route both in your ASGI application (see
107
+ `examples/demo/demo/asgi.py`):
108
+
109
+ ```python
110
+ application = ProtocolTypeRouter({
111
+ "http": get_asgi_application(),
112
+ "websocket": URLRouter(
113
+ crudkit_api.routing.websocket_urlpatterns + crudkit_assistant.routing.websocket_urlpatterns
114
+ ),
115
+ })
116
+ ```
117
+
118
+ The sidebar sees what the user has on screen — the open record, or the list
119
+ with its saved view, search, filters, visible and selected rows — and can
120
+ search and read across record types. It only *proposes* changes (to any record
121
+ the user may change); each one waits for Confirm. Conversations are stored
122
+ per user (`AssistantConversation`, ASC) and resume after a reload. The SPA
123
+ only shows the assistant when an AI model is configured (`CRUDKIT_AI_MODEL` or
124
+ `CRUDKIT_AI_MODEL_FACTORY`).
125
+
126
+ Company knowledge for the AI lives in **AI context** documents (`AIContext`,
127
+ AIC), which users edit in the UI at `/AIC` (add a saved view to the menu to link it).
128
+ Active documents without `model_types` go into the assistant's instructions,
129
+ joined by documents scoped to a type while a record or list of that type is
130
+ open; AI fields get both in a "Company context" section
131
+ of their prompt. Code can render them with `crudkit.llm.ai_context(type_id)`.
132
+ The assistant proposes edits to these documents when the user teaches it
133
+ something durable about the company.
134
+
100
135
  CrudKit requires the standard Django model permissions for every API and
101
136
  assistant operation. Projects that need row-level rules can override
102
137
  `CrudKitSettings.get_authorized_queryset(user, queryset, action)`; `action`
@@ -119,7 +154,9 @@ permission and can be narrowed further with
119
154
  | `CRUDKIT_FRONTEND_CONFIG` | dict injected into the bundled SPA at runtime (`app_name`, `logo_url`, ...) |
120
155
  | `CRUDKIT_FRONTEND_LOGIN_REQUIRED` | redirect anonymous users of the SPA view to `LOGIN_URL` |
121
156
  | `CRUDKIT_MCP_SERVER_NAME` | `serverInfo.name` reported by the MCP server (default `"crudkit"`) |
122
- | `CRUDKIT_MCP_WRITE_ENABLED` | offer the `write` OAuth scope and the create/update/action/note tools (default `False`) |
157
+ | `CRUDKIT_MCP_WRITE_ENABLED` | offer the `write` OAuth scope: the create/update/action/note/undo tools write directly (default `False`) |
158
+ | `CRUDKIT_MCP_WRITE_RATE` | write tool calls allowed per token, as `"<count>/<second\|minute\|hour\|day>"` (default `"60/min"`; `None` for no limit). Counted in the default Django cache: use a shared one (Redis, Memcached, database) with several processes; with `CRUDKIT_MCP_WRITE_ENABLED`, system check `crudkit_mcp.W001` warns otherwise |
159
+ | `CRUDKIT_AI_CONTEXT_MAX_CHARS` | cap on the AI context text sent with every assistant step and AI-field run (default 20000) |
123
160
  | `CRUDKIT_MCP_MODELS` | list of TYPE_IDs to expose over MCP (default: every project model) |
124
161
  | `CRUDKIT_MCP_EXTRA_TOOLS` | dotted paths to `crudkit_mcp.tools.Tool` instances; added to, or replacing, the generated tools |
125
162
  | `CRUDKIT_MCP_BASE_URL` | public origin for OAuth metadata URLs when the request's host/scheme is wrong (e.g. behind a proxy) |
@@ -147,20 +184,59 @@ same tools serve any project:
147
184
 
148
185
  | Tool | |
149
186
  |---|---|
150
- | `describe_types` | the record types; for one `type`, its filters, writable fields, actions and permissions |
187
+ | `describe_types` | the record types; for one `type`, its filters, writable fields, actions, permissions and saved views |
151
188
  | `search` | free-text search across types, returning `{id, label}` |
152
- | `list_records` | one `type`, a `filters` object (keys from `describe_types`), `query`, `order_by`, `limit`, `offset` |
189
+ | `list_records` | one `type` or saved `view` (its filters, ordering and columns), a `filters` object (keys from `describe_types`), `query`, `order_by`, `limit`, `offset` |
153
190
  | `get_record` | one record by ID, with its feed, change log and available actions |
154
191
 
155
- With `CRUDKIT_MCP_WRITE_ENABLED` and a token granted the `write` scope, four
156
- more: `create_record`, `update_record`, `run_action` and `add_note`.
192
+ Five more tools change data: `create_record`, `update_record`, `run_action`,
193
+ `add_note` and `undo`. On the consent page the user picks what the client may
194
+ do:
195
+
196
+ - **Read only** — the `read` scope; no write tools.
197
+ - **Propose changes** — the `propose` scope, offered when `crudkit_assistant`
198
+ is installed. The write tools validate their input as usual but change
199
+ nothing: each files a proposal and returns
200
+ `{"status": "pending_approval", "proposal": "ASP12"}`. The user confirms or
201
+ skips it in the Inbox's Proposals tab.
202
+ - **Write directly** — the `write` scope, only with
203
+ `CRUDKIT_MCP_WRITE_ENABLED`. Each write returns the `change_set` it made;
204
+ `undo` reverts one. Actions and fields that require approval (see
205
+ `docs/concepts.md`) are still only proposed.
206
+
207
+ Writes and proposals are recorded as made over MCP by the token's OAuth
208
+ client, and limited by `CRUDKIT_MCP_WRITE_RATE`.
157
209
 
158
210
  Every call is filtered through the token user's model, row and action
159
211
  permissions, so a type the user can't view isn't listed and can't be read.
160
- CrudKit's own models and Django's (including `User`) are never exposed;
161
- narrow the rest with `CRUDKIT_MCP_MODELS = ["CMP", "PER", ...]` or opt a
212
+ CrudKit's own models and Django's (including `User`) are not exposed, except
213
+ background agents (`AGT`), which clients can propose; narrow the rest with `CRUDKIT_MCP_MODELS = ["CMP", "PER", ...]` or opt a
162
214
  single model out with `CrudKitSettings.mcp_exclude = True`.
163
215
 
216
+ ## Background agents
217
+
218
+ With `crudkit_assistant` installed, users can save **agents** (TYPE_ID `AGT`):
219
+ instructions the assistant carries out on its own, on a record that was just
220
+ created or changed, on the records of a saved view on a schedule, or when
221
+ someone clicks Run now. Each go is an `AgentRun` (`AGR`) with the agent's
222
+ summary and the proposals it made. See `docs/concepts.md` for the details.
223
+
224
+ Runs are Celery tasks (`crudkit_assistant.tasks.run_agent`). For scheduled
225
+ agents, add the scheduler task to Celery beat:
226
+
227
+ ```python
228
+ CELERY_BEAT_SCHEDULE = {
229
+ "crudkit-scheduled-agents": {
230
+ "task": "crudkit_assistant.tasks.run_scheduled_agents",
231
+ "schedule": 300, # every 5 minutes; each agent runs when its interval has passed
232
+ },
233
+ }
234
+ ```
235
+
236
+ Agents start from logged changes (the REST API, MCP, the assistant, actions),
237
+ so plain ORM saves in project code do not trigger them. The enabled agents per
238
+ type are cached in the Django cache for up to a minute.
239
+
164
240
  ## Bundled frontend
165
241
 
166
242
  The wheel ships the built CrudKit web SPA. To serve it, add the app, the
@@ -34,7 +34,7 @@ fields (`AISummaryField`, `AICategoryField`, `AIBooleanField`, `AITagsField`,
34
34
 
35
35
  ```
36
36
  pip install crudkit[api] # REST API included
37
- pip install crudkit[assistant] # + per-object AI assistant (Channels)
37
+ pip install crudkit[assistant] # + AI assistant sidebar (Channels)
38
38
  pip install crudkit[mcp] # + remote MCP server with OAuth (e.g. a Claude connector)
39
39
  ```
40
40
 
@@ -59,6 +59,36 @@ REST_FRAMEWORK = {
59
59
  urlpatterns = [path("api/v1/", include("crudkit_api.urls"))]
60
60
  ```
61
61
 
62
+ The assistant sidebar talks over a WebSocket at `ws/assistant/`, next to the
63
+ realtime `ws/changes/` socket; route both in your ASGI application (see
64
+ `examples/demo/demo/asgi.py`):
65
+
66
+ ```python
67
+ application = ProtocolTypeRouter({
68
+ "http": get_asgi_application(),
69
+ "websocket": URLRouter(
70
+ crudkit_api.routing.websocket_urlpatterns + crudkit_assistant.routing.websocket_urlpatterns
71
+ ),
72
+ })
73
+ ```
74
+
75
+ The sidebar sees what the user has on screen — the open record, or the list
76
+ with its saved view, search, filters, visible and selected rows — and can
77
+ search and read across record types. It only *proposes* changes (to any record
78
+ the user may change); each one waits for Confirm. Conversations are stored
79
+ per user (`AssistantConversation`, ASC) and resume after a reload. The SPA
80
+ only shows the assistant when an AI model is configured (`CRUDKIT_AI_MODEL` or
81
+ `CRUDKIT_AI_MODEL_FACTORY`).
82
+
83
+ Company knowledge for the AI lives in **AI context** documents (`AIContext`,
84
+ AIC), which users edit in the UI at `/AIC` (add a saved view to the menu to link it).
85
+ Active documents without `model_types` go into the assistant's instructions,
86
+ joined by documents scoped to a type while a record or list of that type is
87
+ open; AI fields get both in a "Company context" section
88
+ of their prompt. Code can render them with `crudkit.llm.ai_context(type_id)`.
89
+ The assistant proposes edits to these documents when the user teaches it
90
+ something durable about the company.
91
+
62
92
  CrudKit requires the standard Django model permissions for every API and
63
93
  assistant operation. Projects that need row-level rules can override
64
94
  `CrudKitSettings.get_authorized_queryset(user, queryset, action)`; `action`
@@ -81,7 +111,9 @@ permission and can be narrowed further with
81
111
  | `CRUDKIT_FRONTEND_CONFIG` | dict injected into the bundled SPA at runtime (`app_name`, `logo_url`, ...) |
82
112
  | `CRUDKIT_FRONTEND_LOGIN_REQUIRED` | redirect anonymous users of the SPA view to `LOGIN_URL` |
83
113
  | `CRUDKIT_MCP_SERVER_NAME` | `serverInfo.name` reported by the MCP server (default `"crudkit"`) |
84
- | `CRUDKIT_MCP_WRITE_ENABLED` | offer the `write` OAuth scope and the create/update/action/note tools (default `False`) |
114
+ | `CRUDKIT_MCP_WRITE_ENABLED` | offer the `write` OAuth scope: the create/update/action/note/undo tools write directly (default `False`) |
115
+ | `CRUDKIT_MCP_WRITE_RATE` | write tool calls allowed per token, as `"<count>/<second\|minute\|hour\|day>"` (default `"60/min"`; `None` for no limit). Counted in the default Django cache: use a shared one (Redis, Memcached, database) with several processes; with `CRUDKIT_MCP_WRITE_ENABLED`, system check `crudkit_mcp.W001` warns otherwise |
116
+ | `CRUDKIT_AI_CONTEXT_MAX_CHARS` | cap on the AI context text sent with every assistant step and AI-field run (default 20000) |
85
117
  | `CRUDKIT_MCP_MODELS` | list of TYPE_IDs to expose over MCP (default: every project model) |
86
118
  | `CRUDKIT_MCP_EXTRA_TOOLS` | dotted paths to `crudkit_mcp.tools.Tool` instances; added to, or replacing, the generated tools |
87
119
  | `CRUDKIT_MCP_BASE_URL` | public origin for OAuth metadata URLs when the request's host/scheme is wrong (e.g. behind a proxy) |
@@ -109,20 +141,59 @@ same tools serve any project:
109
141
 
110
142
  | Tool | |
111
143
  |---|---|
112
- | `describe_types` | the record types; for one `type`, its filters, writable fields, actions and permissions |
144
+ | `describe_types` | the record types; for one `type`, its filters, writable fields, actions, permissions and saved views |
113
145
  | `search` | free-text search across types, returning `{id, label}` |
114
- | `list_records` | one `type`, a `filters` object (keys from `describe_types`), `query`, `order_by`, `limit`, `offset` |
146
+ | `list_records` | one `type` or saved `view` (its filters, ordering and columns), a `filters` object (keys from `describe_types`), `query`, `order_by`, `limit`, `offset` |
115
147
  | `get_record` | one record by ID, with its feed, change log and available actions |
116
148
 
117
- With `CRUDKIT_MCP_WRITE_ENABLED` and a token granted the `write` scope, four
118
- more: `create_record`, `update_record`, `run_action` and `add_note`.
149
+ Five more tools change data: `create_record`, `update_record`, `run_action`,
150
+ `add_note` and `undo`. On the consent page the user picks what the client may
151
+ do:
152
+
153
+ - **Read only** — the `read` scope; no write tools.
154
+ - **Propose changes** — the `propose` scope, offered when `crudkit_assistant`
155
+ is installed. The write tools validate their input as usual but change
156
+ nothing: each files a proposal and returns
157
+ `{"status": "pending_approval", "proposal": "ASP12"}`. The user confirms or
158
+ skips it in the Inbox's Proposals tab.
159
+ - **Write directly** — the `write` scope, only with
160
+ `CRUDKIT_MCP_WRITE_ENABLED`. Each write returns the `change_set` it made;
161
+ `undo` reverts one. Actions and fields that require approval (see
162
+ `docs/concepts.md`) are still only proposed.
163
+
164
+ Writes and proposals are recorded as made over MCP by the token's OAuth
165
+ client, and limited by `CRUDKIT_MCP_WRITE_RATE`.
119
166
 
120
167
  Every call is filtered through the token user's model, row and action
121
168
  permissions, so a type the user can't view isn't listed and can't be read.
122
- CrudKit's own models and Django's (including `User`) are never exposed;
123
- narrow the rest with `CRUDKIT_MCP_MODELS = ["CMP", "PER", ...]` or opt a
169
+ CrudKit's own models and Django's (including `User`) are not exposed, except
170
+ background agents (`AGT`), which clients can propose; narrow the rest with `CRUDKIT_MCP_MODELS = ["CMP", "PER", ...]` or opt a
124
171
  single model out with `CrudKitSettings.mcp_exclude = True`.
125
172
 
173
+ ## Background agents
174
+
175
+ With `crudkit_assistant` installed, users can save **agents** (TYPE_ID `AGT`):
176
+ instructions the assistant carries out on its own, on a record that was just
177
+ created or changed, on the records of a saved view on a schedule, or when
178
+ someone clicks Run now. Each go is an `AgentRun` (`AGR`) with the agent's
179
+ summary and the proposals it made. See `docs/concepts.md` for the details.
180
+
181
+ Runs are Celery tasks (`crudkit_assistant.tasks.run_agent`). For scheduled
182
+ agents, add the scheduler task to Celery beat:
183
+
184
+ ```python
185
+ CELERY_BEAT_SCHEDULE = {
186
+ "crudkit-scheduled-agents": {
187
+ "task": "crudkit_assistant.tasks.run_scheduled_agents",
188
+ "schedule": 300, # every 5 minutes; each agent runs when its interval has passed
189
+ },
190
+ }
191
+ ```
192
+
193
+ Agents start from logged changes (the REST API, MCP, the assistant, actions),
194
+ so plain ORM saves in project code do not trigger them. The enabled agents per
195
+ type are cached in the Django cache for up to a minute.
196
+
126
197
  ## Bundled frontend
127
198
 
128
199
  The wheel ships the built CrudKit web SPA. To serve it, add the app, the
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "crudkit"
3
- version = "0.4.0"
3
+ version = "0.6.0"
4
4
  description = "A metadata-driven CRUD framework for Django: typed object IDs, soft delete, merge, change log, activity feed, saved views, AI fields and a generic REST API."
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -20,7 +20,7 @@ dependencies = [
20
20
  "Django>=5.1",
21
21
  "celery>=5.3",
22
22
  "pydantic>=2.11",
23
- "pydantic-ai-slim>=1.39",
23
+ "pydantic-ai-slim>=2.51",
24
24
  "pyjwt>=2.9",
25
25
  "django-phonenumber-field[phonenumberslite]>=8.0",
26
26
  ]
@@ -31,10 +31,13 @@ api = [
31
31
  "djangorestframework-simplejwt>=5.4",
32
32
  "drf-extra-fields>=3.7",
33
33
  ]
34
- assistant = [
34
+ realtime = [
35
35
  "crudkit[api]",
36
36
  "channels>=4.1",
37
37
  ]
38
+ assistant = [
39
+ "crudkit[realtime]",
40
+ ]
38
41
  mcp = [
39
42
  "crudkit[api]",
40
43
  ]
@@ -57,6 +60,7 @@ artifacts = ["src/crudkit_frontend/static", "src/crudkit_frontend/templates"]
57
60
 
58
61
  [dependency-groups]
59
62
  dev = [
63
+ "daphne>=4.1",
60
64
  "psycopg2-binary>=2.9",
61
65
  "ruff>=0.7.0",
62
66
  ]