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
graphcore/__init__.py ADDED
@@ -0,0 +1,5 @@
1
+ """GraphCore platform kernel.
2
+
3
+ App authors import from ``graphcore.public.*``. This package init stays
4
+ free of Django model imports so ``DJANGO_SETTINGS_MODULE`` can load.
5
+ """
@@ -0,0 +1,8 @@
1
+ from graphcore.agent_frontend.api import AgentView, ToolSpec, agent_view, operation, strategy_tool
2
+ from graphcore.agent_frontend.context import Context
3
+ from graphcore.agent_frontend.errors import AgentError, RenderTooLarge
4
+
5
+ __all__ = [
6
+ 'AgentError', 'AgentView', 'Context', 'RenderTooLarge', 'ToolSpec',
7
+ 'agent_view', 'operation', 'strategy_tool',
8
+ ]
@@ -0,0 +1,69 @@
1
+ """What an app's agent frontend package imports."""
2
+ from __future__ import annotations
3
+
4
+ import re
5
+ from dataclasses import dataclass, field
6
+ from typing import Any, Callable, Optional, Sequence
7
+
8
+
9
+ def _tool_name(strategy: str) -> str:
10
+ base = strategy.removesuffix('Strategy')
11
+ return re.sub(r'(?<!^)(?=[A-Z])', '_', base).lower()
12
+
13
+
14
+ @dataclass(frozen=True)
15
+ class ToolSpec:
16
+ name: str
17
+ description: Optional[str] = None
18
+ strategy: Optional[str] = None
19
+ takes_target: bool = True
20
+ bind: Optional[str] = None
21
+ schema: Optional[dict] = None
22
+ fn: Optional[Callable] = None
23
+
24
+
25
+ def strategy_tool(
26
+ strategy: str, takes_target: bool = True, bind: Optional[str] = None,
27
+ name: Optional[str] = None, description: Optional[str] = None,
28
+ ) -> ToolSpec:
29
+ """A view tool that runs the registered strategy named `strategy`. The agent
30
+ supplies its target; `takes_target=False` runs it untargeted, and `bind`
31
+ fixes the target to an entity id."""
32
+ return ToolSpec(
33
+ name=name or _tool_name(strategy), description=description, strategy=strategy,
34
+ takes_target=takes_target, bind=bind,
35
+ )
36
+
37
+
38
+ def operation(name: str, description: str, schema: dict) -> Callable[[Callable], ToolSpec]:
39
+ """A view tool that is code: `async def fn(ctx, **params)`."""
40
+ def wrap(fn: Callable) -> ToolSpec:
41
+ return ToolSpec(name=name, description=description, schema=schema, fn=fn, takes_target=False)
42
+ return wrap
43
+
44
+
45
+ @dataclass(frozen=True)
46
+ class AgentView:
47
+ name: str
48
+ fn: Callable
49
+ default_for: tuple[str, ...] = ()
50
+ tools: Optional[Callable] = field(default=None, compare=False)
51
+
52
+
53
+ def agent_view(
54
+ name: str, default_for: Sequence[str] = (), tools: Optional[Callable] = None,
55
+ ) -> Callable[[Callable], Callable]:
56
+ """Declare `async def fn(ctx, entity)` (or `fn(ctx)` for a view with no entity) as the agent
57
+ view `name`; a module-level view in an agent frontend package is registered at startup.
58
+ `tools` is `async def (ctx, entity) -> list[ToolSpec]`, called on every render; `entity` is None
59
+ for a view with no entity."""
60
+ def wrap(fn: Callable) -> Callable:
61
+ fn.__agent_view__ = AgentView(name, fn, tuple(default_for), tools)
62
+ return fn
63
+ return wrap
64
+
65
+
66
+ def view_of(value: Any) -> Optional[AgentView]:
67
+ """The agent view `value` was declared as with `@agent_view`, if any."""
68
+ view = getattr(value, '__agent_view__', None)
69
+ return view if isinstance(view, AgentView) else None
@@ -0,0 +1,11 @@
1
+ """The base agent views, loaded below every app's. An app view of the same name, or claiming
2
+ the same `default_for` type, replaces the one here, and may reuse these parts."""
3
+ from graphcore.agent_frontend.base.views import (
4
+ children_section, deployment_tools, entity_fields, entity_summary, entity_view, grouped,
5
+ home_view, places, type_tools, view_tools, view_view,
6
+ )
7
+
8
+ __all__ = [
9
+ 'children_section', 'deployment_tools', 'entity_fields', 'entity_summary', 'entity_view',
10
+ 'grouped', 'home_view', 'places', 'type_tools', 'view_tools', 'view_view',
11
+ ]
@@ -0,0 +1,167 @@
1
+ """The base agent views: `home` at `/`, `entity` at `/e/{entity}`, and `view`, the default for view entities."""
2
+ from __future__ import annotations
3
+
4
+ import json
5
+ from collections import defaultdict
6
+ from typing import Any, Optional
7
+
8
+ from graphcore.agent_frontend import AgentView, Context, ToolSpec, agent_view, strategy_tool
9
+
10
+ # The base entity's own keys, rendered under `## Entity`; every other key is a field.
11
+ STRUCTURAL_KEYS = ('entity_id', 'entity_type_id', 'owner', 'parent_id', 'sibling_position', 'version')
12
+ MAX_FIELD_CHARS = 2000
13
+ VIEW_TYPE = 'graphcore.View'
14
+ _ENTITY_ID_PREFIX = 'gc://'
15
+
16
+
17
+ def _value(ctx: Context, value: Any) -> str:
18
+ """One line: strings bare unless empty or multi-line, everything else as JSON; an entity
19
+ id gains its address, and a long value is cut with its full length."""
20
+ if isinstance(value, str) and value and '\n' not in value:
21
+ text = value
22
+ else:
23
+ text = json.dumps(value, default=str, ensure_ascii=False)
24
+ if len(text) > MAX_FIELD_CHARS:
25
+ return f"{text[:MAX_FIELD_CHARS]}… (truncated; {len(text)} characters)"
26
+ if isinstance(value, str) and value.startswith(_ENTITY_ID_PREFIX):
27
+ return f"{text} · {ctx.place(value).address}"
28
+ return text
29
+
30
+
31
+ def entity_fields(ctx: Context, entity: Any) -> list[str]:
32
+ """`key: value` for every key of the entity that is not structural."""
33
+ return [
34
+ f"{key}: {_value(ctx, value)}"
35
+ for key, value in entity.to_dict().items() if key not in STRUCTURAL_KEYS
36
+ ]
37
+
38
+
39
+ async def entity_summary(ctx: Context, entity: Any) -> list[str]:
40
+ """The entity's structural keys, each said plainly: who owns it and where it sits."""
41
+ data = entity.to_dict()
42
+ owner = data.get('owner')
43
+ lines = [
44
+ f"id: {entity.entity_id}",
45
+ f"type: {entity.entity_type_id}",
46
+ f"owner: {owner} (you)" if owner == ctx.principal.principal_entity_id
47
+ else f"owner: {owner or 'none'}",
48
+ f"parent: {await _parent(ctx, data.get('parent_id'))}",
49
+ ]
50
+ lines += [f"{key}: {data[key]}" for key in ('version', 'sibling_position') if key in data]
51
+ return lines
52
+
53
+
54
+ async def _parent(ctx: Context, parent_id: Optional[str]) -> str:
55
+ if not parent_id:
56
+ return 'none (top level)'
57
+ parent = await ctx.get(parent_id)
58
+ if parent is None:
59
+ return f"{parent_id} (not readable)"
60
+ data = parent.to_dict()
61
+ label = next((str(data[k]) for k in ('name', 'title', 'slug') if data.get(k)), parent_id)
62
+ return f"{label} · {parent.entity_type_id} · {ctx.place(parent_id).address}"
63
+
64
+
65
+ async def children_section(ctx: Context, entity: Any, limit: int = 50) -> list:
66
+ """`## Children` and a compact placement per child, in sibling order."""
67
+ children = await ctx.children(entity, limit=limit)
68
+ if not children:
69
+ return ['## Children\nnone']
70
+ parts: list = [f"## Children ({len(children)}{', more exist' if ctx.more else ''})"]
71
+ parts.extend(ctx.place(child.entity_id) for child in children)
72
+ if ctx.more:
73
+ parts.append(f"Narrow with `find(type, {{\"parent_id\": \"{entity.entity_id}\"}})`.")
74
+ return parts
75
+
76
+
77
+ def grouped(ctx: Context, entities: list) -> list:
78
+ """Compact placements of `entities` under one heading per type."""
79
+ groups: dict[str, list] = defaultdict(list)
80
+ for entity in entities:
81
+ groups[entity.entity_type_id].append(entity)
82
+ parts: list = []
83
+ for type_id, members in sorted(groups.items()):
84
+ parts.append(f"### {type_id} ({len(members)})")
85
+ parts.extend(ctx.place(member.entity_id) for member in members)
86
+ if ctx.more:
87
+ parts.append("More exist than are shown; use `find` to narrow by type and field.")
88
+ return parts
89
+
90
+
91
+ async def type_tools(ctx: Context, entity: Any) -> list[ToolSpec]:
92
+ """Every strategy the entity's type offers, bound to the entity."""
93
+ return [
94
+ strategy_tool(s['name'], bind=entity.entity_id)
95
+ for s in ctx.type_strategies(entity.entity_type_id)
96
+ ]
97
+
98
+
99
+ async def deployment_tools(ctx: Context, entity: Optional[Any] = None) -> list[ToolSpec]:
100
+ """Every strategy on the deployment's allowlist, untargeted."""
101
+ return [strategy_tool(s['name'], takes_target=False) for s in ctx.deployment_strategies()]
102
+
103
+
104
+ def places(ctx: Context) -> list:
105
+ """`## Places` and a compact placement per route other than `/` that needs no entity."""
106
+ paths = [r['pattern'] for r in ctx.routes() if r['pattern'] != '/' and '{' not in r['pattern']]
107
+ return ['## Places', *(ctx.place(path) for path in paths)] if paths else []
108
+
109
+
110
+ @agent_view('home', tools=deployment_tools)
111
+ async def home_view(ctx: Context) -> list:
112
+ top_level = await ctx.find(frozenset(ctx.entity_types()), where={'parent_id': None})
113
+ return [
114
+ *places(ctx),
115
+ "## Top-level entities\nOpen one to see what it contains.",
116
+ *grouped(ctx, top_level),
117
+ ]
118
+
119
+
120
+ @agent_view('entity', tools=type_tools)
121
+ async def entity_view(ctx: Context, entity: Any) -> list:
122
+ fields = entity_fields(ctx, entity)
123
+ return [
124
+ '## Entity\n' + '\n'.join(await entity_summary(ctx, entity)),
125
+ '## Fields\n' + ('\n'.join(fields) if fields else 'none'),
126
+ *await children_section(ctx, entity),
127
+ ]
128
+
129
+
130
+ async def _component(ctx: Context, view: Any) -> tuple[Optional[AgentView], Any]:
131
+ """The agent view the view's `component` names, and the entity it renders (None for none);
132
+ sets `ctx.view_state` to the view's stored state for the component and its tools."""
133
+ data = view.to_dict()
134
+ ctx.view_state = data.get('state') or {}
135
+ component = ctx.view(data.get('component') or '')
136
+ if component is not None and VIEW_TYPE in component.default_for:
137
+ component = None # a view naming the view view would render itself forever
138
+ target = await ctx.get(data['renders']) if data.get('renders') else None
139
+ return component, target
140
+
141
+
142
+ async def view_tools(ctx: Context, view: Any) -> list[ToolSpec]:
143
+ """The component's tools, then the view entity's own."""
144
+ component, target = await _component(ctx, view)
145
+ own = await type_tools(ctx, view)
146
+ if component is None or component.tools is None:
147
+ return own
148
+ return [*await component.tools(ctx, target), *own]
149
+
150
+
151
+ @agent_view('view', default_for=[VIEW_TYPE], tools=view_tools)
152
+ async def view_view(ctx: Context, view: Any) -> list:
153
+ """A view renders as itself: the agent view its `component` names, over the entity it
154
+ renders. Without an agent view of that name it renders as an entity."""
155
+ data = view.to_dict()
156
+ component, target = await _component(ctx, view)
157
+ if component is None:
158
+ note = f"No agent view is named {data.get('component')!r}; showing the view as an entity."
159
+ return [note, *await entity_view(ctx, view)]
160
+ if data.get('renders') and target is None:
161
+ return [f"This view renders {data['renders']}, which does not exist or is not readable."]
162
+ shows = ctx.place(data['renders']).address if target is not None else 'no entity'
163
+ body = await (component.fn(ctx, target) if target is not None else component.fn(ctx))
164
+ return [
165
+ f"View `{component.name}` of {shows} · view entity {view.entity_id}",
166
+ *(body if isinstance(body, list) else [body]),
167
+ ]
@@ -0,0 +1,31 @@
1
+ """The only way the agent frontend reaches the kernel: a `GraphAPI` client."""
2
+ from __future__ import annotations
3
+
4
+ from typing import Any, Optional, Protocol
5
+
6
+ from graphcore.types.entities import EntityPage
7
+ from graphcore.types.identity import Principal
8
+ from graphcore.types.query import Predicate
9
+
10
+
11
+ class GraphClient(Protocol):
12
+ async def authenticate(self, token: str) -> Optional[Principal]: ...
13
+ async def get_entity(self, principal: Principal, entity_id: str) -> Any: ...
14
+ async def list_children(
15
+ self, principal: Principal, parent_id: str, type_ids: Optional[frozenset[str]] = None,
16
+ cursor: Optional[str] = None, limit: int = 25,
17
+ ) -> EntityPage: ...
18
+ async def list_entities(
19
+ self, principal: Principal, type_ids: frozenset[str], parent_id: Optional[str] = None,
20
+ where: Predicate | dict | None = None, cursor: Optional[str] = None, limit: int = 25,
21
+ granted_to_me: bool = False,
22
+ ) -> EntityPage: ...
23
+ async def execute(
24
+ self, principal: Principal, strategy_name: str, target_id: Optional[str], params: dict,
25
+ ) -> dict: ...
26
+ def resolve(self, address: str) -> dict: ...
27
+ def routes(self) -> list[dict]: ...
28
+ def entity_types(self) -> list[str]: ...
29
+ def type_strategies(self, entity_type_id: str) -> list[dict]: ...
30
+ def deployment_strategies(self) -> list[dict]: ...
31
+ def strategy_info(self) -> dict[str, dict]: ...
@@ -0,0 +1,157 @@
1
+ from __future__ import annotations
2
+
3
+ import hashlib
4
+ from dataclasses import dataclass, field
5
+ from typing import Any, Optional
6
+
7
+ from graphcore.agent_frontend.api import AgentView
8
+ from graphcore.agent_frontend.client import GraphClient
9
+ from graphcore.agent_frontend.errors import AgentError
10
+ from graphcore.agent_frontend.registry import AgentRegistry
11
+ from graphcore.types.entities import Tombstone
12
+ from graphcore.types.identity import Principal
13
+ from graphcore.types.query import Predicate
14
+
15
+ ID_PREFIX = 'gc://'
16
+ DEFAULT_QUERY_MAX = 1000
17
+ _QUERY_PAGE = 100
18
+
19
+
20
+ def entity_address(entity_id: str) -> str:
21
+ return '/e/' + entity_id.removeprefix(ID_PREFIX)
22
+
23
+
24
+ def to_address(target: str) -> str:
25
+ return entity_address(target) if target.startswith(ID_PREFIX) else target
26
+
27
+
28
+ def label_of(entity: Any) -> str:
29
+ data = entity.to_dict()
30
+ for key in ('name', 'title', 'slug'):
31
+ if data.get(key):
32
+ return str(data[key])
33
+ return entity.entity_id
34
+
35
+
36
+ @dataclass(frozen=True)
37
+ class Placement:
38
+ address: str
39
+ full: bool = False
40
+
41
+
42
+ @dataclass
43
+ class Reads:
44
+ """What one render read: the basis of its version."""
45
+
46
+ seen: dict[str, str] = field(default_factory=dict)
47
+ cache: dict[str, Any] = field(default_factory=dict)
48
+
49
+ def version(self) -> str:
50
+ lines = sorted(f"{entity_id}:{state}" for entity_id, state in self.seen.items())
51
+ return hashlib.sha256('\n'.join(lines).encode()).hexdigest()[:16]
52
+
53
+
54
+ class Context:
55
+ def __init__(
56
+ self, principal: Principal, address: str, entity: Any, client: GraphClient, reads: Reads,
57
+ registry: Optional[AgentRegistry] = None, query_max: int = DEFAULT_QUERY_MAX,
58
+ ):
59
+ self.principal = principal
60
+ self.address = address
61
+ self.entity = entity
62
+ # The stored `state` of the view entity being rendered, when there is one.
63
+ self.view_state: dict = {}
64
+ self.more = False
65
+ self._client = client
66
+ self._reads = reads
67
+ self._registry = registry
68
+ self._query_max = query_max
69
+
70
+ def _record(self, entity: Any) -> None:
71
+ self._reads.seen[entity.entity_id] = f"v{entity.version}"
72
+ self._reads.cache[entity.entity_id] = entity
73
+
74
+ async def get(self, entity_id: str) -> Optional[Any]:
75
+ if entity_id in self._reads.cache:
76
+ return self._reads.cache[entity_id]
77
+ result = await self._client.get_entity(self.principal, entity_id)
78
+ if isinstance(result, Tombstone):
79
+ self._reads.seen[entity_id] = result.cause
80
+ return None
81
+ self._record(result)
82
+ return result
83
+
84
+ async def children(self, parent: Any, type_id: Optional[str] = None, limit: int = 50) -> list:
85
+ parent_id = parent if isinstance(parent, str) else parent.entity_id
86
+ page = await self._client.list_children(
87
+ self.principal, parent_id, frozenset([type_id]) if type_id else None, limit=limit,
88
+ )
89
+ self.more = page.next_cursor is not None
90
+ for entity in page.entities:
91
+ self._record(entity)
92
+ return list(page.entities)
93
+
94
+ async def find(
95
+ self, types: str | frozenset, where: Optional[dict] = None, limit: int = 50,
96
+ granted_to_me: bool = False,
97
+ ) -> list:
98
+ type_ids = frozenset([types]) if isinstance(types, str) else frozenset(types)
99
+ page = await self._client.list_entities(
100
+ self.principal, type_ids, where=where, limit=limit, granted_to_me=granted_to_me,
101
+ )
102
+ self.more = page.next_cursor is not None
103
+ for entity in page.entities:
104
+ self._record(entity)
105
+ return list(page.entities)
106
+
107
+ async def query(
108
+ self, types: str | frozenset | list, *, parent_id: Optional[str] = None,
109
+ where: Predicate | dict | None = None, limit: Optional[int] = None,
110
+ ) -> list:
111
+ """Every readable entity of `types` (children of `parent_id`, matching
112
+ `where`), page by page, up to `limit` or `GRAPHCORE_AGENT_QUERY_MAX`;
113
+ `more` is set when it stopped before the last page."""
114
+ type_ids = frozenset([types]) if isinstance(types, str) else frozenset(types)
115
+ cap = self._query_max if limit is None else limit
116
+ found: list = []
117
+ cursor = None
118
+ while len(found) < cap:
119
+ page = await self._client.list_entities(
120
+ self.principal, type_ids, parent_id=parent_id, where=where, cursor=cursor,
121
+ limit=min(_QUERY_PAGE, cap - len(found)),
122
+ )
123
+ for entity in page.entities:
124
+ self._record(entity)
125
+ found.extend(page.entities)
126
+ cursor = page.next_cursor
127
+ if cursor is None:
128
+ break
129
+ self.more = cursor is not None
130
+ return found
131
+
132
+ def view(self, name: str) -> Optional[AgentView]:
133
+ """The agent view registered as `name`: an app's, else the base one."""
134
+ return self._registry.by_name(name) if self._registry and name else None
135
+
136
+ def routes(self) -> list[dict]:
137
+ return self._client.routes()
138
+
139
+ def entity_types(self) -> list[str]:
140
+ return self._client.entity_types()
141
+
142
+ def type_strategies(self, type_id: str) -> list[dict]:
143
+ return self._client.type_strategies(type_id)
144
+
145
+ def deployment_strategies(self) -> list[dict]:
146
+ return self._client.deployment_strategies()
147
+
148
+ async def execute(
149
+ self, strategy: str, target: Optional[str] = None, params: Optional[dict] = None,
150
+ ) -> dict:
151
+ outcome = await self._client.execute(self.principal, strategy, target, params or {})
152
+ if outcome.get('status') == 'failed':
153
+ raise AgentError('Refused', f"{strategy}: {outcome.get('error')}")
154
+ return outcome.get('ret_val') or {}
155
+
156
+ def place(self, target: str, full: bool = False) -> Placement:
157
+ return Placement(to_address(target), full)
@@ -0,0 +1,12 @@
1
+ class AgentError(Exception):
2
+ """A refusal reported to the agent as an error result."""
3
+
4
+ def __init__(self, code: str, message: str):
5
+ super().__init__(f"{code}: {message}")
6
+ self.code = code
7
+ self.message = message
8
+
9
+
10
+ class RenderTooLarge(AgentError):
11
+ def __init__(self, address: str, detail: str = ''):
12
+ super().__init__('RenderTooLarge', f"the render of {address} is too large{detail}")
@@ -0,0 +1,54 @@
1
+ """Builds the agent registry from the base views and every app's agent frontend package."""
2
+ from __future__ import annotations
3
+
4
+ import importlib
5
+ import pkgutil
6
+ from types import ModuleType
7
+ from typing import Iterable
8
+
9
+ from graphcore.agent_frontend.api import AgentView, view_of
10
+ from graphcore.agent_frontend.registry import AgentRegistry
11
+
12
+ BASE_VIEWS = 'graphcore.agent_frontend.base'
13
+
14
+
15
+ def _is_test_module(modname: str) -> bool:
16
+ return any(s in ('tests', 'test') or s.startswith('test_') for s in modname.split('.'))
17
+
18
+
19
+ def _modules(package: ModuleType) -> list[ModuleType]:
20
+ """The package and every non-test submodule, as kernel discovery does for `entities`."""
21
+ modules = [package]
22
+ if not hasattr(package, '__path__'):
23
+ return modules
24
+ for _, modname, _ in pkgutil.walk_packages(package.__path__, package.__name__ + '.'):
25
+ if _is_test_module(modname):
26
+ continue
27
+ try:
28
+ modules.append(importlib.import_module(modname))
29
+ except Exception as exc:
30
+ raise ImportError(f"Failed to import agent views module {modname!r}: {exc}") from exc
31
+ return modules
32
+
33
+
34
+ def views_in(package: ModuleType) -> list[AgentView]:
35
+ """The agent views defined in the package's modules; a view a module imports from elsewhere is not its own."""
36
+ found: dict[int, AgentView] = {}
37
+ for module in _modules(package):
38
+ for value in vars(module).values():
39
+ view = view_of(value)
40
+ if view is not None and view.fn.__module__ == module.__name__:
41
+ found.setdefault(id(view), view)
42
+ return list(found.values())
43
+
44
+
45
+ def load_registry(modules: Iterable[str], base: str = BASE_VIEWS) -> AgentRegistry:
46
+ """`modules` are the agent frontend packages to import, by module name.
47
+ The views in `base` form the lower layer, which an app view of the same name replaces."""
48
+ registry = AgentRegistry()
49
+ for view in views_in(importlib.import_module(base)):
50
+ registry.add(view, base=True)
51
+ for module in modules:
52
+ for view in views_in(importlib.import_module(module)):
53
+ registry.add(view)
54
+ return registry
@@ -0,0 +1,42 @@
1
+ from __future__ import annotations
2
+
3
+ from typing import Optional
4
+
5
+ from graphcore.agent_frontend.api import AgentView
6
+
7
+
8
+ class _Layer:
9
+ def __init__(self) -> None:
10
+ self.by_name: dict[str, AgentView] = {}
11
+ self.default_for: dict[str, AgentView] = {}
12
+
13
+ def add(self, view: AgentView) -> None:
14
+ if view.name in self.by_name:
15
+ raise ValueError(f"agent view {view.name!r} is registered twice")
16
+ for type_id in view.default_for:
17
+ if type_id in self.default_for:
18
+ raise ValueError(
19
+ f"agent views {self.default_for[type_id].name!r} and {view.name!r} "
20
+ f"are both the default for {type_id!r}"
21
+ )
22
+ self.by_name[view.name] = view
23
+ for type_id in view.default_for:
24
+ self.default_for[type_id] = view
25
+
26
+
27
+ class AgentRegistry:
28
+ """Agent views in two layers. An app view replaces the base view of the same name or
29
+ `default_for` type; within a layer, a name or type is claimed once."""
30
+
31
+ def __init__(self) -> None:
32
+ self._base = _Layer()
33
+ self._apps = _Layer()
34
+
35
+ def add(self, view: AgentView, base: bool = False) -> None:
36
+ (self._base if base else self._apps).add(view)
37
+
38
+ def by_name(self, name: str) -> Optional[AgentView]:
39
+ return self._apps.by_name.get(name) or self._base.by_name.get(name)
40
+
41
+ def default_for(self, type_id: str) -> Optional[AgentView]:
42
+ return self._apps.default_for.get(type_id) or self._base.default_for.get(type_id)