graphcore-kernel 0.1.0__py3-none-any.whl

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 (343) hide show
  1. graphcore/__init__.py +5 -0
  2. graphcore/agent_frontend/__init__.py +8 -0
  3. graphcore/agent_frontend/api.py +69 -0
  4. graphcore/agent_frontend/base/__init__.py +11 -0
  5. graphcore/agent_frontend/base/views.py +167 -0
  6. graphcore/agent_frontend/client.py +31 -0
  7. graphcore/agent_frontend/context.py +157 -0
  8. graphcore/agent_frontend/errors.py +12 -0
  9. graphcore/agent_frontend/loading.py +54 -0
  10. graphcore/agent_frontend/registry.py +42 -0
  11. graphcore/agent_frontend/render.py +207 -0
  12. graphcore/agent_frontend/server.py +103 -0
  13. graphcore/agent_frontend/signatures.py +35 -0
  14. graphcore/agent_frontend/testing.py +45 -0
  15. graphcore/agent_frontend/tests/__init__.py +0 -0
  16. graphcore/agent_frontend/tests/fakes.py +114 -0
  17. graphcore/agent_frontend/tests/test_frontend.py +447 -0
  18. graphcore/agent_frontend/tests/test_loading.py +83 -0
  19. graphcore/agent_frontend/tests/test_server.py +109 -0
  20. graphcore/agent_frontend/tools.py +137 -0
  21. graphcore/api/__init__.py +4 -0
  22. graphcore/api/graph_api.py +378 -0
  23. graphcore/api/predicate_codec.py +81 -0
  24. graphcore/api/tests/__init__.py +0 -0
  25. graphcore/api/tests/test_changed_entities.py +109 -0
  26. graphcore/api/tests/test_graph_api.py +290 -0
  27. graphcore/api/tests/test_graph_api_access.py +94 -0
  28. graphcore/api/tests/test_graph_api_grants.py +90 -0
  29. graphcore/api/tests/test_predicate_codec.py +83 -0
  30. graphcore/api/tests/test_subtree_query.py +79 -0
  31. graphcore/apps.py +71 -0
  32. graphcore/auth/__init__.py +1 -0
  33. graphcore/auth/authn/README.md +178 -0
  34. graphcore/auth/authn/__init__.py +3 -0
  35. graphcore/auth/authn/authenticator.py +120 -0
  36. graphcore/auth/authn/onboarding.py +105 -0
  37. graphcore/auth/authn/principals.py +20 -0
  38. graphcore/auth/authn/resource_metadata.py +43 -0
  39. graphcore/auth/authn/service_accounts.py +96 -0
  40. graphcore/auth/authn/testing.py +96 -0
  41. graphcore/auth/authn/tests/__init__.py +0 -0
  42. graphcore/auth/authn/tests/test_authenticator.py +145 -0
  43. graphcore/auth/authn/tests/test_onboarding.py +145 -0
  44. graphcore/auth/authn/tests/test_service_accounts.py +180 -0
  45. graphcore/auth/authn/users.py +59 -0
  46. graphcore/auth/authz/__init__.py +0 -0
  47. graphcore/auth/authz/access_port.py +120 -0
  48. graphcore/auth/authz/adapter/__init__.py +0 -0
  49. graphcore/auth/authz/adapter/default_access_adapter.py +556 -0
  50. graphcore/auth/authz/adapter/tests/__init__.py +0 -0
  51. graphcore/auth/authz/adapter/tests/test_default_adapter.py +543 -0
  52. graphcore/auth/authz/adapter/tests/test_entity_write_hooks.py +207 -0
  53. graphcore/auth/authz/adapter/tests/test_group_types.py +70 -0
  54. graphcore/auth/authz/adapter/tests/test_sync_support.py +209 -0
  55. graphcore/auth/authz/defaults.py +26 -0
  56. graphcore/auth/authz/kernel_policy.py +191 -0
  57. graphcore/auth/authz/kernel_writes.py +31 -0
  58. graphcore/auth/authz/lookups.py +25 -0
  59. graphcore/auth/authz/policy.py +403 -0
  60. graphcore/auth/authz/tests/__init__.py +0 -0
  61. graphcore/auth/authz/tests/test_can_contain.py +150 -0
  62. graphcore/auth/authz/tests/test_contained_by.py +167 -0
  63. graphcore/auth/authz/tests/test_creation.py +391 -0
  64. graphcore/auth/authz/tests/test_delete_permission.py +82 -0
  65. graphcore/auth/authz/tests/test_granted_to_me.py +160 -0
  66. graphcore/auth/authz/tests/test_integration.py +637 -0
  67. graphcore/auth/authz/tests/test_invites.py +184 -0
  68. graphcore/auth/authz/tests/test_kernel_policy.py +140 -0
  69. graphcore/auth/authz/tests/test_lockout.py +132 -0
  70. graphcore/auth/authz/tests/test_policy.py +329 -0
  71. graphcore/auth/authz/tests/test_primitives.py +73 -0
  72. graphcore/auth/authz/tests/test_principal_creation.py +62 -0
  73. graphcore/bootstrap/__init__.py +0 -0
  74. graphcore/bootstrap/deployment.py +67 -0
  75. graphcore/bootstrap/signals.py +16 -0
  76. graphcore/bootstrap/tests/__init__.py +0 -0
  77. graphcore/bootstrap/tests/test_deployment_seed.py +154 -0
  78. graphcore/broadcast/__init__.py +4 -0
  79. graphcore/broadcast/broadcaster.py +201 -0
  80. graphcore/broadcast/channels.py +56 -0
  81. graphcore/broadcast/tests/__init__.py +0 -0
  82. graphcore/broadcast/tests/test_broadcaster.py +444 -0
  83. graphcore/celery.py +14 -0
  84. graphcore/docs/AGENT_FRONTEND_TDD.md +389 -0
  85. graphcore/docs/ARCHITECTURE_PRINCIPLES.md +152 -0
  86. graphcore/docs/AUTHORIZATION_TECHNICAL_TDD.md +1379 -0
  87. graphcore/docs/ENTITY_REFERENCE_TDD.md +561 -0
  88. graphcore/docs/GRAPHAPI_FRONT_DOOR.md +173 -0
  89. graphcore/docs/RUNTIME.md +90 -0
  90. graphcore/docs/SCHEDULING_TDD.md +244 -0
  91. graphcore/docs/STRATEGY_EXECUTION_TDD.md +1043 -0
  92. graphcore/docs/VIEW_ENTITY_TDD.md +522 -0
  93. graphcore/docs/VIEW_SYSTEM_TDD.md +307 -0
  94. graphcore/docs/__init__.py +0 -0
  95. graphcore/docs/doc_topics.py +97 -0
  96. graphcore/docs/docs_discovery.py +64 -0
  97. graphcore/docs/public_api.py +56 -0
  98. graphcore/domain/__init__.py +0 -0
  99. graphcore/domain/entity/Entity.py +204 -0
  100. graphcore/domain/entity/__init__.py +0 -0
  101. graphcore/domain/entity/deployment/Deployment.py +25 -0
  102. graphcore/domain/entity/deployment/__init__.py +0 -0
  103. graphcore/domain/entity/grant/Grant.py +31 -0
  104. graphcore/domain/entity/grant/__init__.py +0 -0
  105. graphcore/domain/entity/group/Group.py +48 -0
  106. graphcore/domain/entity/group/README.md +88 -0
  107. graphcore/domain/entity/group/__init__.py +0 -0
  108. graphcore/domain/entity/invite/Invite.py +31 -0
  109. graphcore/domain/entity/invite/__init__.py +0 -0
  110. graphcore/domain/entity/request_template/RequestTemplate.py +48 -0
  111. graphcore/domain/entity/request_template/__init__.py +0 -0
  112. graphcore/domain/entity/request_template/tests/__init__.py +0 -0
  113. graphcore/domain/entity/request_template/tests/test_request_template.py +52 -0
  114. graphcore/domain/entity/service_account/ServiceAccount.py +41 -0
  115. graphcore/domain/entity/service_account/__init__.py +0 -0
  116. graphcore/domain/entity/strategy_request/StrategyRequest.py +61 -0
  117. graphcore/domain/entity/strategy_request/__init__.py +0 -0
  118. graphcore/domain/entity/strategy_request/tests/__init__.py +0 -0
  119. graphcore/domain/entity/strategy_request/tests/test_strategy_request_entity.py +35 -0
  120. graphcore/domain/entity/tests/__init__.py +0 -0
  121. graphcore/domain/entity/tests/test_entity.py +227 -0
  122. graphcore/domain/entity/tests/test_grant_group_entities.py +36 -0
  123. graphcore/domain/entity/tests/test_write_once_fields.py +98 -0
  124. graphcore/domain/entity/user/User.py +39 -0
  125. graphcore/domain/entity/user/__init__.py +0 -0
  126. graphcore/domain/entity/user/tests/__init__.py +0 -0
  127. graphcore/domain/entity/user/tests/test_user_entity.py +33 -0
  128. graphcore/domain/entity/view/View.py +37 -0
  129. graphcore/domain/entity/view/__init__.py +0 -0
  130. graphcore/domain/entity/view/position.py +78 -0
  131. graphcore/domain/entity/view/tests/__init__.py +0 -0
  132. graphcore/domain/entity/view/tests/test_position.py +71 -0
  133. graphcore/domain/entity/view/tests/test_view_entity.py +134 -0
  134. graphcore/domain/strategy/BaseStrategy.py +759 -0
  135. graphcore/domain/strategy/DeploymentStrategies.py +55 -0
  136. graphcore/domain/strategy/GrantStrategies.py +189 -0
  137. graphcore/domain/strategy/GroupStrategies.py +193 -0
  138. graphcore/domain/strategy/InviteStrategies.py +84 -0
  139. graphcore/domain/strategy/RequestTemplateStrategies.py +126 -0
  140. graphcore/domain/strategy/ViewStrategies.py +219 -0
  141. graphcore/domain/strategy/__init__.py +0 -0
  142. graphcore/domain/strategy/runner.py +84 -0
  143. graphcore/domain/strategy/session.py +56 -0
  144. graphcore/domain/strategy/tests/BaseStrategyTest.py +167 -0
  145. graphcore/domain/strategy/tests/__init__.py +0 -0
  146. graphcore/domain/strategy/tests/test_BaseStrategies.py +870 -0
  147. graphcore/domain/strategy/tests/test_grant_strategies.py +245 -0
  148. graphcore/domain/strategy/tests/test_group_strategies.py +99 -0
  149. graphcore/domain/strategy/tests/test_runner.py +220 -0
  150. graphcore/domain/strategy/tests/test_strategy_locks.py +446 -0
  151. graphcore/domain/strategy/tests/test_utils.py +95 -0
  152. graphcore/domain/strategy/tests/test_view_strategies.py +436 -0
  153. graphcore/errors.py +145 -0
  154. graphcore/execution/README.md +97 -0
  155. graphcore/execution/StrategyExecutorService.py +333 -0
  156. graphcore/execution/__init__.py +0 -0
  157. graphcore/execution/dispatcher.py +19 -0
  158. graphcore/execution/environments/__init__.py +0 -0
  159. graphcore/execution/environments/celery.py +59 -0
  160. graphcore/execution/environments/in_process.py +55 -0
  161. graphcore/execution/local_session.py +117 -0
  162. graphcore/execution/redis_run_events.py +74 -0
  163. graphcore/execution/requests.py +22 -0
  164. graphcore/execution/run_events.py +85 -0
  165. graphcore/execution/strategy_context.py +54 -0
  166. graphcore/execution/tasks.py +34 -0
  167. graphcore/execution/tests/__init__.py +5 -0
  168. graphcore/execution/tests/contract.py +171 -0
  169. graphcore/execution/tests/support.py +310 -0
  170. graphcore/execution/tests/test_dispatchers.py +76 -0
  171. graphcore/execution/tests/test_executor.py +368 -0
  172. graphcore/execution/tests/test_local_session.py +95 -0
  173. graphcore/execution/tests/test_reconcile_runs.py +134 -0
  174. graphcore/execution/tests/test_run_events.py +106 -0
  175. graphcore/execution/tests/test_strategy_context.py +62 -0
  176. graphcore/gateway/__init__.py +1 -0
  177. graphcore/gateway/remote.py +35 -0
  178. graphcore/gateway/tests/__init__.py +0 -0
  179. graphcore/gateway/tests/test_remote.py +30 -0
  180. graphcore/graph/EntityService.py +710 -0
  181. graphcore/graph/__init__.py +0 -0
  182. graphcore/graph/entity_cache.py +152 -0
  183. graphcore/graph/tests/__init__.py +4 -0
  184. graphcore/graph/tests/test_EntityService.py +908 -0
  185. graphcore/graph/tests/test_EntityService_list.py +170 -0
  186. graphcore/graph/tests/test_EntityService_model_resolution.py +339 -0
  187. graphcore/graph/tests/test_EntityService_referrers.py +236 -0
  188. graphcore/graph/tests/test_EntityService_routing.py +119 -0
  189. graphcore/graph/tests/test_dependent_on.py +141 -0
  190. graphcore/graph/tests/test_engine_is_type_agnostic.py +25 -0
  191. graphcore/graph/tests/test_engine_resolves_read_permission.py +93 -0
  192. graphcore/graph/tests/test_entity_cache.py +159 -0
  193. graphcore/graph/tests/test_null_entity_cache.py +12 -0
  194. graphcore/management/__init__.py +0 -0
  195. graphcore/management/commands/__init__.py +0 -0
  196. graphcore/management/commands/dev_reset.py +18 -0
  197. graphcore/management/commands/graphcore_createadmin.py +65 -0
  198. graphcore/management/commands/graphcore_policy.py +59 -0
  199. graphcore/management/commands/graphcore_status.py +98 -0
  200. graphcore/management/tests/__init__.py +0 -0
  201. graphcore/management/tests/test_createadmin.py +78 -0
  202. graphcore/management/tests/test_policy_command.py +46 -0
  203. graphcore/management/tests/test_status_command.py +85 -0
  204. graphcore/migrations/0001_initial.py +186 -0
  205. graphcore/migrations/0002_invite.py +26 -0
  206. graphcore/migrations/__init__.py +0 -0
  207. graphcore/models.py +11 -0
  208. graphcore/persistence/ENTITY_REPOSITORY_TECHNICAL_TDD.md +396 -0
  209. graphcore/persistence/__init__.py +6 -0
  210. graphcore/persistence/django/__init__.py +0 -0
  211. graphcore/persistence/django/backends.py +43 -0
  212. graphcore/persistence/django/bindings.py +28 -0
  213. graphcore/persistence/django/cache.py +38 -0
  214. graphcore/persistence/django/compiler.py +214 -0
  215. graphcore/persistence/django/identity.py +18 -0
  216. graphcore/persistence/django/models.py +252 -0
  217. graphcore/persistence/django/repository.py +525 -0
  218. graphcore/persistence/django/tests/__init__.py +0 -0
  219. graphcore/persistence/django/tests/test_backends.py +68 -0
  220. graphcore/persistence/django/tests/test_compiler.py +269 -0
  221. graphcore/persistence/django/tests/test_repository.py +472 -0
  222. graphcore/persistence/django/tests/test_shared_column.py +120 -0
  223. graphcore/persistence/django/tests/test_threads.py +50 -0
  224. graphcore/persistence/django/tests/test_update_shape.py +175 -0
  225. graphcore/persistence/django/threads.py +38 -0
  226. graphcore/persistence/repository.py +172 -0
  227. graphcore/persistence/tests/__init__.py +0 -0
  228. graphcore/persistence/tests/contract.py +688 -0
  229. graphcore/persistence/tests/evaluate.py +51 -0
  230. graphcore/persistence/tests/fixtures.py +32 -0
  231. graphcore/persistence/tests/memory.py +263 -0
  232. graphcore/persistence/tests/test_memory_repository.py +10 -0
  233. graphcore/persistence/tests/test_query_types.py +127 -0
  234. graphcore/public/__init__.py +9 -0
  235. graphcore/public/api.py +9 -0
  236. graphcore/public/apps.py +10 -0
  237. graphcore/public/auth/__init__.py +1 -0
  238. graphcore/public/auth/grants.py +7 -0
  239. graphcore/public/auth/onboarding.py +8 -0
  240. graphcore/public/auth/perms.py +7 -0
  241. graphcore/public/auth/policy.py +10 -0
  242. graphcore/public/auth/roles.py +8 -0
  243. graphcore/public/auth/subjects.py +7 -0
  244. graphcore/public/entities/__init__.py +32 -0
  245. graphcore/public/errors.py +19 -0
  246. graphcore/public/persistence/__init__.py +44 -0
  247. graphcore/public/persistence/django.py +24 -0
  248. graphcore/public/scheduling.py +23 -0
  249. graphcore/public/strategies/__init__.py +85 -0
  250. graphcore/public/test_settings.py +16 -0
  251. graphcore/public/testing.py +47 -0
  252. graphcore/registry/EntityDirectory.py +246 -0
  253. graphcore/registry/README.md +147 -0
  254. graphcore/registry/StrategyDirectory.py +308 -0
  255. graphcore/registry/TYPE_METADATA_PLACEMENT.md +66 -0
  256. graphcore/registry/__init__.py +0 -0
  257. graphcore/registry/app_discovery.py +108 -0
  258. graphcore/registry/decorators.py +77 -0
  259. graphcore/registry/discovery.py +111 -0
  260. graphcore/registry/registry.py +79 -0
  261. graphcore/registry/tests/__init__.py +0 -0
  262. graphcore/registry/tests/test_agent_frontend_discovery.py +56 -0
  263. graphcore/registry/tests/test_app_config.py +36 -0
  264. graphcore/registry/tests/test_discovery.py +147 -0
  265. graphcore/registry/tests/test_entity_directory_storage.py +73 -0
  266. graphcore/registry/tests/test_import_package.py +87 -0
  267. graphcore/registry/tests/test_principal_flag.py +67 -0
  268. graphcore/registry/tests/test_strategy_directory.py +29 -0
  269. graphcore/routes/__init__.py +116 -0
  270. graphcore/routes/tests/__init__.py +0 -0
  271. graphcore/routes/tests/test_routes.py +90 -0
  272. graphcore/runtime.py +243 -0
  273. graphcore/scheduling/__init__.py +0 -0
  274. graphcore/scheduling/beat_scheduler.py +164 -0
  275. graphcore/scheduling/beat_tasks.py +63 -0
  276. graphcore/scheduling/scheduler.py +37 -0
  277. graphcore/scheduling/tests/__init__.py +0 -0
  278. graphcore/scheduling/tests/contract.py +136 -0
  279. graphcore/scheduling/tests/memory.py +42 -0
  280. graphcore/scheduling/tests/test_beat_scheduler.py +87 -0
  281. graphcore/scheduling/tests/test_memory_scheduler.py +15 -0
  282. graphcore/scheduling/tests/test_ticks.py +143 -0
  283. graphcore/tasks.py +9 -0
  284. graphcore/test_settings.py +78 -0
  285. graphcore/testing/__init__.py +0 -0
  286. graphcore/testing/case.py +112 -0
  287. graphcore/testing/runner.py +32 -0
  288. graphcore/testing/settings.py +26 -0
  289. graphcore/testing/tests/__init__.py +0 -0
  290. graphcore/testing/tests/agent_view_fixture.py +19 -0
  291. graphcore/testing/tests/test_case_and_runner.py +219 -0
  292. graphcore/testing/tests/test_settings_for_apps.py +50 -0
  293. graphcore/tests/__init__.py +0 -0
  294. graphcore/tests/ids.py +14 -0
  295. graphcore/tests/public_api_manifest.py +102 -0
  296. graphcore/tests/runs.py +7 -0
  297. graphcore/tests/test_app_discovery.py +90 -0
  298. graphcore/tests/test_composition_boundaries.py +231 -0
  299. graphcore/tests/test_docs_discovery.py +108 -0
  300. graphcore/tests/test_no_print.py +70 -0
  301. graphcore/tests/test_packaging.py +64 -0
  302. graphcore/tests/test_public_api_boundaries.py +229 -0
  303. graphcore/tests/test_public_api_contract.py +62 -0
  304. graphcore/tests/test_public_api_docs.py +28 -0
  305. graphcore/tests/test_runtime.py +42 -0
  306. graphcore/tests/test_shared_type_boundaries.py +128 -0
  307. graphcore/tests/test_shared_types.py +144 -0
  308. graphcore/tests/test_test_settings.py +45 -0
  309. graphcore/transport/__init__.py +0 -0
  310. graphcore/transport/agent_asgi.py +68 -0
  311. graphcore/transport/agent_client.py +85 -0
  312. graphcore/transport/channel_layer.py +68 -0
  313. graphcore/transport/consumers.py +507 -0
  314. graphcore/transport/routing.py +6 -0
  315. graphcore/transport/tests/__init__.py +0 -0
  316. graphcore/transport/tests/test_agent_client.py +31 -0
  317. graphcore/transport/tests/test_api_views.py +733 -0
  318. graphcore/transport/tests/test_channel_layer.py +96 -0
  319. graphcore/transport/tests/test_consumers.py +963 -0
  320. graphcore/transport/tests/test_resource_metadata.py +67 -0
  321. graphcore/transport/urls.py +29 -0
  322. graphcore/transport/views.py +358 -0
  323. graphcore/types/__init__.py +4 -0
  324. graphcore/types/access.py +114 -0
  325. graphcore/types/api.py +76 -0
  326. graphcore/types/entities.py +100 -0
  327. graphcore/types/entity_id.py +85 -0
  328. graphcore/types/execution.py +41 -0
  329. graphcore/types/identity.py +20 -0
  330. graphcore/types/onboarding.py +20 -0
  331. graphcore/types/query.py +116 -0
  332. graphcore/types/schedules.py +91 -0
  333. graphcore/types/strategy.py +73 -0
  334. graphcore/types/tests/__init__.py +0 -0
  335. graphcore/types/tests/test_entity_id.py +50 -0
  336. graphcore/urls.py +5 -0
  337. graphcore_kernel-0.1.0.dist-info/METADATA +94 -0
  338. graphcore_kernel-0.1.0.dist-info/RECORD +343 -0
  339. graphcore_kernel-0.1.0.dist-info/WHEEL +5 -0
  340. graphcore_kernel-0.1.0.dist-info/entry_points.txt +2 -0
  341. graphcore_kernel-0.1.0.dist-info/licenses/LICENSE +202 -0
  342. graphcore_kernel-0.1.0.dist-info/licenses/NOTICE +2 -0
  343. graphcore_kernel-0.1.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,307 @@
1
+ # View System — Technical Design
2
+
3
+ ## Introduction
4
+
5
+ A GraphCore deployment is presented to people and programs by several
6
+ clients: the React frontend in a browser, mobile apps, and agents connected
7
+ over MCP. Each client renders the graph its own way, but they must agree on
8
+ where things are. For a place with a shared address, a user watching an
9
+ agent work can see, in the web client, the place the agent is looking at,
10
+ and a link copied from one client opens the same place in another.
11
+
12
+ The view system splits the two concerns. Each client owns **rendering**: it
13
+ registers its own renderers for the views an address names, with defaults
14
+ for anything it does not register. Clients share addresses, never rendering
15
+ code. Registering a route on the server is optional. An app that wants a
16
+ place to be linkable and mirrorable across clients declares it in the
17
+ **route table** the server builds at startup, which makes it a **shared
18
+ address**. A place that needs no such reach is a route the client defines
19
+ for itself.
20
+
21
+ This document covers what is common to every client. Two documents cover
22
+ the parts:
23
+
24
+ - `VIEW_ENTITY_TDD.md`: how view state is stored, found, and shared, and how
25
+ web view components are written.
26
+ - `AGENT_FRONTEND_TDD.md`: the agent client: its MCP surface, render format,
27
+ and agent views.
28
+
29
+ It does not cover authorization (`AUTHORIZATION_TECHNICAL_TDD.md`) or
30
+ identity (`IDENTITY.md`).
31
+
32
+ ## Definitions
33
+
34
+ - **Client**: a program that presents the graph to someone. Each client has
35
+ a name used in stored view state:
36
+ - `web`: the React frontend, rendering in the browser;
37
+ - `agent`: the agent frontend, an ASGI app separate from Django that
38
+ renders for language-model agents connected over MCP;
39
+ - mobile clients, when they exist, under their own names.
40
+ - **Address**: a path on the deployment, the same for every client:
41
+ `/`, `/e/<backend_id>/<local_id>`, `/stacks/review-queue`. The full form
42
+ is the deployment's base URL followed by the path. An address never names
43
+ a client.
44
+ - **Route**: a pattern in the route table that maps addresses to a **view
45
+ name** and, optionally, an entity: `/stacks/{entity}/history` →
46
+ `stacks.history`.
47
+ - **Route table**: every shared route on the deployment: the kernel's
48
+ routes and the routes apps declare. The server builds it at startup and
49
+ serves it through `GraphAPI`. An address the table matches is a **shared
50
+ address**.
51
+ - **Client route**: a route one client defines for itself, outside the
52
+ route table: the web client's `/admin`, a settings screen. Its places are
53
+ reachable only in that client.
54
+ - **View name**: the name a route resolves to. A client renders it with the
55
+ renderer it has registered under that name, or with its default.
56
+ - **Renderer**: a client's code for one view name: a React component in the
57
+ web client, a Python render function in the agent client.
58
+ - **Client registry**: one client's renderers, each with the entity types it
59
+ is the default for.
60
+ - **Default**: what a client renders for an address it has no renderer
61
+ for. Every client supplies one, so every shared address renders in every
62
+ client.
63
+ - **View state**: what a client remembers about a placement (collapsed
64
+ sections, chosen tab). Stored as a `View`, per client, under the
65
+ address; see `VIEW_ENTITY_TDD.md`.
66
+ - **Snapshot**: a render produced once and held by a client that receives no
67
+ live updates. A snapshot carries a **render version**.
68
+ - **Mirroring**: two clients showing the same address for the same user at
69
+ the same time.
70
+
71
+ ## Requirements
72
+
73
+ 1. **The server owns shared addresses.** A place that should be reachable
74
+ from more than one client (linked, mirrored, or opened by an agent) has
75
+ an address in the route table. A client may define its own routes for
76
+ places only it shows; those places cannot be linked from or mirrored in
77
+ another client.
78
+ 2. **Clients own rendering.** Each client renders with its own registry.
79
+ A consumer that cannot run our code (an agent host) is served by a
80
+ frontend on the server that renders for it, as a web server serves pages
81
+ to a browser.
82
+ 3. **Every shared address renders in every client.** A client with no renderer for
83
+ a view name renders its default.
84
+ 4. **Mirroring needs shared addresses, not shared rendering.** Two clients
85
+ may render one address differently. A client may match another's
86
+ rendering, and is not required to.
87
+ 5. **Clients depend on `GraphAPI` only.** No client reads kernel services,
88
+ storage, or another client's code.
89
+ 6. **No client confers authority.** Every read and write is checked by the
90
+ kernel as the user, whatever client makes it.
91
+ 7. **Stale writes are refused.** A client holding a snapshot states the
92
+ render version it acted on, and a write based on a changed snapshot is
93
+ refused.
94
+ 8. **Apps declare views the way they declare everything else.** Routes and
95
+ renderers are registered at startup through the app's config, alongside
96
+ entities, strategies, and policy.
97
+
98
+ ## Architecture
99
+
100
+ ### Layers
101
+
102
+ ```
103
+ browser ── web client (React) ─────────┐
104
+ phone ──── mobile client ──────────────┤
105
+ agent host ── MCP ── agent frontend ───┤
106
+ ▼
107
+ GraphAPI ── kernel services
108
+ ```
109
+
110
+ The web and mobile clients run on the user's device and call `GraphAPI`
111
+ over HTTP and WebSocket. The agent frontend is its own ASGI app, separate
112
+ from Django, served by the same uvicorn server. The deployment's ASGI entry
113
+ routes `/mcp` to the agent frontend and everything else to Django, so
114
+ `graphcore run` serves both on one port with no extra role or proxy.
115
+
116
+ The agent frontend reaches the kernel only through a `GraphAPI` client
117
+ interface. Its implementation calls `GraphAPI` in the same process, with
118
+ the user as the principal. An implementation over the backend's HTTP and
119
+ WebSocket transports would let the agent frontend run as its own server
120
+ without changing its code. It never imports Django or kernel services, and
121
+ the kernel never imports it.
122
+
123
+ ### Addresses and routes
124
+
125
+ The kernel declares two routes:
126
+
127
+ | Route | View name | Entity |
128
+ |---|---|---|
129
+ | `/` | `home` | none |
130
+ | `/e/{entity}` | `entity` | the entity |
131
+
132
+ `{entity}` matches an identifier `gc://<backend_id>/<local_id>` written as
133
+ `<backend_id>/<local_id>`. The `entity` view name means "the view this
134
+ client resolves for this entity" (see Resolution).
135
+
136
+ An app declares its own routes in a function named by its config:
137
+
138
+ ```python
139
+ class StacksConfig(GraphCoreAppConfig):
140
+ graphcore_app_id = 'stacks'
141
+ graphcore_routes = 'stacks.routes.configure'
142
+
143
+ # stacks/routes.py
144
+ def configure(routes):
145
+ routes.add('/stacks/review-queue', 'stacks.review_queue')
146
+ routes.add('/stacks/{entity}/history', 'stacks.history')
147
+ ```
148
+
149
+ - An app chooses its own paths.
150
+ - A route has at most one `{entity}` parameter.
151
+ - Startup fails when two routes, from any apps or the kernel, can match the
152
+ same address. The error names both routes and the apps that declared
153
+ them.
154
+
155
+ `GraphAPI.routes()` returns the table; `GraphAPI.resolve(address)` returns
156
+ the view name and entity identifier for an address, or `NotFound`. Clients
157
+ read the table from the server rather than building it in, so a client
158
+ follows the deployment it connects to.
159
+
160
+ A client mounts its own client routes beside the table. The server does not
161
+ know them and does not check them for collisions; where a client route and a
162
+ shared route match the same address, the client route wins in that client.
163
+
164
+ ### Client registries
165
+
166
+ | Client | Registered with | Where it runs | Documented in |
167
+ |---|---|---|---|
168
+ | `web` | `defineView(name, Component, options)` in the app's frontend entry | browser | `VIEW_ENTITY_TDD.md` |
169
+ | `agent` | `@agent_view(name, ...)` in the app's agent frontend package | deployment backend, beside Django | `AGENT_FRONTEND_TDD.md` |
170
+
171
+ Every registry takes the option `default_for` (entity types this renderer
172
+ is the client's default for). A view name is resolved only in the registry of the client
173
+ rendering it; two clients may register the same name, and nothing requires
174
+ them to.
175
+
176
+ ### Resolution
177
+
178
+ A client renders an address by:
179
+
180
+ 1. resolving it through the route table to a view name and an optional
181
+ entity, either by `GraphAPI.resolve` or by matching the patterns from
182
+ `GraphAPI.routes()` itself (the web client's router does the latter);
183
+ 2. choosing a renderer from its own registry:
184
+ - `/`: its renderer named `home`, or its default home;
185
+ - `entity`: for a client that stores view state, the renderer named by
186
+ the stored view's `component` when this client knows it;
187
+ then the renderer whose `default_for` includes the entity's type; then
188
+ its default entity renderer;
189
+ - any other name: its renderer under that name; without one, its
190
+ default entity renderer when the route has an entity, and otherwise a
191
+ placeholder naming the view and its address.
192
+
193
+ ### App bootstrap
194
+
195
+ An app ships one package per side, and each side discovers its own. The
196
+ layout is the same in a project's `apps/` and in a published app:
197
+
198
+ ```
199
+ apps/stacks/
200
+ backend/ pip package graphcore-stacks
201
+ pyproject.toml
202
+ stacks/ entities, strategies, policy, routes
203
+ stacks_agent_frontend/ @agent_view functions
204
+ agent_views.py
205
+ react_frontend/ npm package: defineView components
206
+ ```
207
+
208
+ - **Kernel backend**: `graphcore_routes` on the app's config is the dotted
209
+ path to its route function. The route table lives in `graphcore.routes`.
210
+ - **Web client**: the installed-apps codegen registers every `defineView`
211
+ export of each `react_frontend` entry.
212
+ - **Agent frontend**: at startup the ASGI entry finds every
213
+ `graphcore.agent_frontends` entry point and every
214
+ `apps/<name>/backend/<name>_agent_frontend` package (with
215
+ `apps/<name>/backend` on `sys.path`, as for the Django app). It imports each by module name, then every
216
+ module in them except tests, as kernel discovery does for `entities`, and
217
+ registers every `@agent_view`. There is no manifest.
218
+
219
+ The agent frontend is `graphcore.agent_frontend`, part of the same
220
+ `graphcore` package the kernel publishes. It is structured like a library:
221
+ it has its own public API, imports the `GraphAPI` client interface and the
222
+ public types, and never imports Django or the backend's modules. An app's
223
+ agent frontend package imports only that public API. Agent views name
224
+ entity types and strategies by their registry identifiers
225
+ (`'stacks.Stack'`, `'CreateDocument'`), as web views do.
226
+
227
+ ### View state
228
+
229
+ View state is stored per client under the address the client rendered:
230
+ Alice's web state for `/e/P` is her views with `client = web` and
231
+ `address = /e/P`, found in one query. A client never reads another client's
232
+ state. A client route holds view state the same way, under its own address;
233
+ since the route table does not match it, its view renders no entity. The
234
+ web client stores every page's state under its address without any
235
+ declaration; see `VIEW_ENTITY_TDD.md`. The agent client stores none.
236
+ Storage, lookup, and sharing are in `VIEW_ENTITY_TDD.md`.
237
+
238
+ A view's position is stored as plain fields (`client`, `address`, and the
239
+ view's own slot), so a client finds view state with ordinary entity
240
+ queries and never builds a key. An address is stored in one form: starting
241
+ with `/`, with no trailing `/` except `/` itself, and with no query or
242
+ fragment. The server refuses any other form, so a client normalizes the
243
+ address it sends.
244
+
245
+ ### Snapshots and versions
246
+
247
+ The web client keeps a live store fed by `entity_update`, so what it shows
248
+ does not go stale. A client without live updates holds snapshots:
249
+
250
+ - A **render version** is a hash of the `(id, version)` pairs of every
251
+ entity the render read, including the members of every list it read. A
252
+ changed entity, an added child, or a removed child changes it.
253
+ - A client acting on a snapshot sends the version with the write. The
254
+ server re-renders the address, compares, and refuses a mismatch with
255
+ `Stale`, returning the current version.
256
+ - Entities' own `version` field (optimistic locking) is unchanged; render
257
+ versions are built from it.
258
+
259
+ ### Mirroring
260
+
261
+ Mirroring is available, not required, and relies only on the shared
262
+ address. A client route cannot be mirrored.
263
+
264
+ The MCP Apps extension lets a tool result point to a `ui://` resource that
265
+ the agent host shows in a sandboxed frame. The agent frontend attaches one
266
+ to every `open` and `call` result: the web client's page for that address.
267
+ The user sees the GraphCore UI for the place the agent is working, inside
268
+ the agent host. It costs the agent no context, because the host shows the
269
+ frame to the user and does not pass it to the model.
270
+
271
+ ## Trade-offs
272
+
273
+ - **Shared addresses on the server, client routes allowed** rather than
274
+ every place in one table, or every client defining its own. Places in the
275
+ route table are reachable from every client, including ones written
276
+ later, and can be linked and mirrored. A client adds a place without a
277
+ server change as a client route, at the cost of that place being
278
+ unreachable from other clients. Because any address may hold view state,
279
+ a mistyped address stores state under the typo rather than failing.
280
+ - **Per-client rendering** rather than one rendering shared by all clients.
281
+ Each client presents a place in the form that suits it, at the cost of
282
+ writing a renderer per client where the default is not enough.
283
+ - **Server-side rendering for agents only.** The agent host cannot run our
284
+ code, so the agent frontend renders for it on the server. Every other
285
+ client renders itself.
286
+ - **One server, separated in code** rather than a separate server process.
287
+ The agent frontend shares uvicorn and calls `GraphAPI` in-process, so
288
+ there is no second port, no proxy, and no request per read. Its only
289
+ dependency is the `GraphAPI` client interface, so it cannot take a
290
+ private path, and moving it to its own server is a change of
291
+ implementation. The cost is no process isolation: a slow render or a
292
+ crash shares workers with Django, and the two cannot be scaled
293
+ separately.
294
+ - **Snapshots refused at write time** rather than kept current by
295
+ subscription. Reads may be stale; writes may not. This needs no
296
+ connection state and works with every agent host.
297
+
298
+ ## Open items
299
+
300
+ - **Routes with more than one entity**, or with non-entity parameters.
301
+ - **Mobile clients**: registry, defaults, and view state.
302
+ - **Re-render cost of version checks.** Checking a write's version
303
+ re-renders the address. Whether to cache render versions, and how to
304
+ invalidate them, is undecided.
305
+ - **MCP Apps details.** The frame's content and its access to the
306
+ deployment depend on the extension's current specification and on what
307
+ each host allows.
File without changes
@@ -0,0 +1,97 @@
1
+ """Doc topics contributed by the graphcore kernel (API reference).
2
+
3
+ Add an entry here whenever a kernel doc should be discoverable via
4
+ `graphcore docs`. The topic key is a public path within `kernel`; `path` is
5
+ relative to this package's own installed
6
+ directory (`graphcore/`), and must be covered by this package's
7
+ `package-data` in pyproject.toml (the `*/README.md` glob already covers
8
+ one level deep, so most subsystem docs need no further pyproject edits).
9
+
10
+ For frontend docs co-located in the React pair, register with
11
+ ``source=SOURCE_NPM`` and the npm package name; the markdown ships in the
12
+ npm package and is resolved from ``node_modules`` at read time.
13
+
14
+ For a generated topic, register with ``source=SOURCE_RENDER``; ``package`` is
15
+ the module and ``path`` is the callable name.
16
+ """
17
+
18
+ from graphcore.docs.docs_discovery import SOURCE_RENDER, Doc
19
+
20
+ TOPICS: dict[str, Doc] = {
21
+ "public-api": Doc(
22
+ "graphcore.docs.public_api",
23
+ "public_api_docs_renderer",
24
+ "App-author import surface",
25
+ source=SOURCE_RENDER,
26
+ ),
27
+ "architecture-principles": Doc(
28
+ "graphcore",
29
+ "docs/ARCHITECTURE_PRINCIPLES.md",
30
+ "Kernel design rules, package map, and conventions",
31
+ ),
32
+ "authentication": Doc(
33
+ "graphcore",
34
+ "auth/authn/README.md",
35
+ "Token verification, principal mapping, and what the kernel requires of an issuer",
36
+ ),
37
+ "authorization-technical-tdd": Doc(
38
+ "graphcore",
39
+ "docs/AUTHORIZATION_TECHNICAL_TDD.md",
40
+ "Target architecture for perms, roles, grants, and the AccessPort",
41
+ ),
42
+ "entity-reference-tdd": Doc(
43
+ "graphcore",
44
+ "docs/ENTITY_REFERENCE_TDD.md",
45
+ "Entity identifiers, references between entities, dependent references, remote resolution",
46
+ ),
47
+ "agent-frontend-tdd": Doc(
48
+ "graphcore",
49
+ "docs/AGENT_FRONTEND_TDD.md",
50
+ "The agent frontend: MCP tools, render format, agent views, resolution, view tools",
51
+ ),
52
+ "view-system-tdd": Doc(
53
+ "graphcore",
54
+ "docs/VIEW_SYSTEM_TDD.md",
55
+ "Views across clients: names, addresses and routes, web and agent views, resolution",
56
+ ),
57
+ "view-entity-tdd": Doc(
58
+ "graphcore",
59
+ "docs/VIEW_ENTITY_TDD.md",
60
+ "The View entity: how views are found and stored, who sees them, writing view components",
61
+ ),
62
+ "strategy-execution-tdd": Doc(
63
+ "graphcore",
64
+ "docs/STRATEGY_EXECUTION_TDD.md",
65
+ "How a strategy request runs: where it runs, the session it writes through, how it reports back",
66
+ ),
67
+ "scheduling-tdd": Doc(
68
+ "graphcore",
69
+ "docs/SCHEDULING_TDD.md",
70
+ "Scheduling: request templates and schedules that run strategies",
71
+ ),
72
+ "entity-repository-technical-tdd": Doc(
73
+ "graphcore",
74
+ "persistence/ENTITY_REPOSITORY_TECHNICAL_TDD.md",
75
+ "The storage seam: query vocabulary, repository contract, storage bindings",
76
+ ),
77
+ "registry": Doc(
78
+ "graphcore",
79
+ "registry/README.md",
80
+ "How types reach the kernel: app config, decorators vs configurators, startup, freeze",
81
+ ),
82
+ "execution": Doc(
83
+ "graphcore",
84
+ "execution/README.md",
85
+ "Strategy execution: authorization, routing, retries, callbacks, Celery, scheduling",
86
+ ),
87
+ "graphapi-front-door": Doc(
88
+ "graphcore",
89
+ "docs/GRAPHAPI_FRONT_DOOR.md",
90
+ "GraphAPI as sole mutation entry: composition, broadcast flows, migration",
91
+ ),
92
+ "runtime": Doc(
93
+ "graphcore",
94
+ "docs/RUNTIME.md",
95
+ "The composition root: Runtime, build_runtime, django_runtime, and how to override it",
96
+ ),
97
+ }
@@ -0,0 +1,64 @@
1
+ """Discover graphcore doc topics visible to this install."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import dataclass
6
+ from importlib import import_module, resources
7
+ from importlib.metadata import entry_points
8
+ from pathlib import Path
9
+
10
+ DOCS_GROUP = "graphcore.docs"
11
+
12
+ SOURCE_PY = "py"
13
+ SOURCE_NPM = "npm"
14
+ SOURCE_RENDER = "render"
15
+
16
+
17
+ @dataclass(frozen=True)
18
+ class Doc:
19
+ package: str # python / npm package, or the module holding a renderer
20
+ path: str # package-relative file, or callable name when source=render
21
+ description: str
22
+ source: str = SOURCE_PY # SOURCE_PY | SOURCE_NPM | SOURCE_RENDER
23
+
24
+
25
+ def _find_in_node_modules(package: str, path: str, *, start: Path | None = None) -> Path:
26
+ """Walk up from *start* (default: cwd) looking for ``node_modules/<package>/<path>``."""
27
+ cur = (start or Path.cwd()).resolve()
28
+ for directory in (cur, *cur.parents):
29
+ candidate = directory / "node_modules" / package / path
30
+ if candidate.is_file():
31
+ return candidate
32
+ raise FileNotFoundError(
33
+ f"npm doc not found: node_modules/{package}/{path} "
34
+ f"(searched from {cur}; run npm install in a project that depends on {package})"
35
+ )
36
+
37
+
38
+ def read_doc(doc: Doc) -> str:
39
+ if doc.source == SOURCE_NPM:
40
+ return _find_in_node_modules(doc.package, doc.path).read_text(encoding="utf-8")
41
+ if doc.source == SOURCE_RENDER:
42
+ return getattr(import_module(doc.package), doc.path)()
43
+ return resources.files(doc.package).joinpath(doc.path).read_text(encoding="utf-8")
44
+
45
+
46
+ def _load_group(eps, group: str) -> list:
47
+ return list(eps.select(group=group) if hasattr(eps, "select") else eps.get(group, []))
48
+
49
+
50
+ def discover_doc_topics() -> dict[str, Doc]:
51
+ """Merge package registries into ``package/topic`` ids.
52
+
53
+ The entry-point name is the package namespace. Registry keys are public
54
+ paths within that namespace and may contain arbitrary slash-separated
55
+ sections; ``Doc.path`` remains the independent packaged file location.
56
+ """
57
+ eps = entry_points()
58
+ topics: dict[str, Doc] = {}
59
+
60
+ for ep in sorted(_load_group(eps, DOCS_GROUP), key=lambda e: e.name):
61
+ for topic_id, doc in ep.load().TOPICS.items():
62
+ topics[f"{ep.name}/{topic_id}"] = doc
63
+
64
+ return topics
@@ -0,0 +1,56 @@
1
+ """Live index of ``graphcore.public`` for ``graphcore docs kernel/public-api``."""
2
+ from __future__ import annotations
3
+
4
+ import importlib
5
+ import inspect
6
+ import os
7
+ import pkgutil
8
+
9
+ import graphcore.public as public
10
+
11
+
12
+ def public_api_docs_renderer() -> str:
13
+ _ensure_django()
14
+ lines = [
15
+ "# graphcore public API",
16
+ "",
17
+ "Import these modules. `graphcore.public` is a namespace and re-exports nothing.",
18
+ "",
19
+ ]
20
+ for name in _modules():
21
+ mod = importlib.import_module(name)
22
+ names = getattr(mod, "__all__", ())
23
+ if not names:
24
+ continue
25
+ lines += [f"## {name}", ""]
26
+ summary = inspect.cleandoc(mod.__doc__ or "").strip()
27
+ if summary:
28
+ lines += [summary.split("\n\n", 1)[0], ""]
29
+ width = max(len(symbol) for symbol in names)
30
+ for symbol in names:
31
+ one = _one_liner(getattr(mod, symbol))
32
+ lines.append(f" {symbol.ljust(width)} {one}".rstrip())
33
+ lines.append("")
34
+ return "\n".join(lines) + "\n"
35
+
36
+
37
+ def _modules() -> list[str]:
38
+ return sorted(info.name for info in pkgutil.walk_packages(public.__path__, public.__name__ + "."))
39
+
40
+
41
+ def _one_liner(obj) -> str:
42
+ if not (inspect.isclass(obj) or inspect.isroutine(obj)) or not obj.__doc__:
43
+ return ""
44
+ text = " ".join(inspect.cleandoc(obj.__doc__).split("\n\n", 1)[0].split())
45
+ if inspect.isclass(obj) and text.startswith(obj.__name__ + "("):
46
+ return ""
47
+ return text
48
+
49
+
50
+ def _ensure_django() -> None:
51
+ from django.apps import apps
52
+ if apps.ready:
53
+ return
54
+ os.environ.setdefault("DJANGO_SETTINGS_MODULE", "graphcore.test_settings")
55
+ import django
56
+ django.setup()
File without changes