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.
- graphcore/__init__.py +5 -0
- graphcore/agent_frontend/__init__.py +8 -0
- graphcore/agent_frontend/api.py +69 -0
- graphcore/agent_frontend/base/__init__.py +11 -0
- graphcore/agent_frontend/base/views.py +167 -0
- graphcore/agent_frontend/client.py +31 -0
- graphcore/agent_frontend/context.py +157 -0
- graphcore/agent_frontend/errors.py +12 -0
- graphcore/agent_frontend/loading.py +54 -0
- graphcore/agent_frontend/registry.py +42 -0
- graphcore/agent_frontend/render.py +207 -0
- graphcore/agent_frontend/server.py +103 -0
- graphcore/agent_frontend/signatures.py +35 -0
- graphcore/agent_frontend/testing.py +45 -0
- graphcore/agent_frontend/tests/__init__.py +0 -0
- graphcore/agent_frontend/tests/fakes.py +114 -0
- graphcore/agent_frontend/tests/test_frontend.py +447 -0
- graphcore/agent_frontend/tests/test_loading.py +83 -0
- graphcore/agent_frontend/tests/test_server.py +109 -0
- graphcore/agent_frontend/tools.py +137 -0
- graphcore/api/__init__.py +4 -0
- graphcore/api/graph_api.py +378 -0
- graphcore/api/predicate_codec.py +81 -0
- graphcore/api/tests/__init__.py +0 -0
- graphcore/api/tests/test_changed_entities.py +109 -0
- graphcore/api/tests/test_graph_api.py +290 -0
- graphcore/api/tests/test_graph_api_access.py +94 -0
- graphcore/api/tests/test_graph_api_grants.py +90 -0
- graphcore/api/tests/test_predicate_codec.py +83 -0
- graphcore/api/tests/test_subtree_query.py +79 -0
- graphcore/apps.py +71 -0
- graphcore/auth/__init__.py +1 -0
- graphcore/auth/authn/README.md +178 -0
- graphcore/auth/authn/__init__.py +3 -0
- graphcore/auth/authn/authenticator.py +120 -0
- graphcore/auth/authn/onboarding.py +105 -0
- graphcore/auth/authn/principals.py +20 -0
- graphcore/auth/authn/resource_metadata.py +43 -0
- graphcore/auth/authn/service_accounts.py +96 -0
- graphcore/auth/authn/testing.py +96 -0
- graphcore/auth/authn/tests/__init__.py +0 -0
- graphcore/auth/authn/tests/test_authenticator.py +145 -0
- graphcore/auth/authn/tests/test_onboarding.py +145 -0
- graphcore/auth/authn/tests/test_service_accounts.py +180 -0
- graphcore/auth/authn/users.py +59 -0
- graphcore/auth/authz/__init__.py +0 -0
- graphcore/auth/authz/access_port.py +120 -0
- graphcore/auth/authz/adapter/__init__.py +0 -0
- graphcore/auth/authz/adapter/default_access_adapter.py +556 -0
- graphcore/auth/authz/adapter/tests/__init__.py +0 -0
- graphcore/auth/authz/adapter/tests/test_default_adapter.py +543 -0
- graphcore/auth/authz/adapter/tests/test_entity_write_hooks.py +207 -0
- graphcore/auth/authz/adapter/tests/test_group_types.py +70 -0
- graphcore/auth/authz/adapter/tests/test_sync_support.py +209 -0
- graphcore/auth/authz/defaults.py +26 -0
- graphcore/auth/authz/kernel_policy.py +191 -0
- graphcore/auth/authz/kernel_writes.py +31 -0
- graphcore/auth/authz/lookups.py +25 -0
- graphcore/auth/authz/policy.py +403 -0
- graphcore/auth/authz/tests/__init__.py +0 -0
- graphcore/auth/authz/tests/test_can_contain.py +150 -0
- graphcore/auth/authz/tests/test_contained_by.py +167 -0
- graphcore/auth/authz/tests/test_creation.py +391 -0
- graphcore/auth/authz/tests/test_delete_permission.py +82 -0
- graphcore/auth/authz/tests/test_granted_to_me.py +160 -0
- graphcore/auth/authz/tests/test_integration.py +637 -0
- graphcore/auth/authz/tests/test_invites.py +184 -0
- graphcore/auth/authz/tests/test_kernel_policy.py +140 -0
- graphcore/auth/authz/tests/test_lockout.py +132 -0
- graphcore/auth/authz/tests/test_policy.py +329 -0
- graphcore/auth/authz/tests/test_primitives.py +73 -0
- graphcore/auth/authz/tests/test_principal_creation.py +62 -0
- graphcore/bootstrap/__init__.py +0 -0
- graphcore/bootstrap/deployment.py +67 -0
- graphcore/bootstrap/signals.py +16 -0
- graphcore/bootstrap/tests/__init__.py +0 -0
- graphcore/bootstrap/tests/test_deployment_seed.py +154 -0
- graphcore/broadcast/__init__.py +4 -0
- graphcore/broadcast/broadcaster.py +201 -0
- graphcore/broadcast/channels.py +56 -0
- graphcore/broadcast/tests/__init__.py +0 -0
- graphcore/broadcast/tests/test_broadcaster.py +444 -0
- graphcore/celery.py +14 -0
- graphcore/docs/AGENT_FRONTEND_TDD.md +389 -0
- graphcore/docs/ARCHITECTURE_PRINCIPLES.md +152 -0
- graphcore/docs/AUTHORIZATION_TECHNICAL_TDD.md +1379 -0
- graphcore/docs/ENTITY_REFERENCE_TDD.md +561 -0
- graphcore/docs/GRAPHAPI_FRONT_DOOR.md +173 -0
- graphcore/docs/RUNTIME.md +90 -0
- graphcore/docs/SCHEDULING_TDD.md +244 -0
- graphcore/docs/STRATEGY_EXECUTION_TDD.md +1043 -0
- graphcore/docs/VIEW_ENTITY_TDD.md +522 -0
- graphcore/docs/VIEW_SYSTEM_TDD.md +307 -0
- graphcore/docs/__init__.py +0 -0
- graphcore/docs/doc_topics.py +97 -0
- graphcore/docs/docs_discovery.py +64 -0
- graphcore/docs/public_api.py +56 -0
- graphcore/domain/__init__.py +0 -0
- graphcore/domain/entity/Entity.py +204 -0
- graphcore/domain/entity/__init__.py +0 -0
- graphcore/domain/entity/deployment/Deployment.py +25 -0
- graphcore/domain/entity/deployment/__init__.py +0 -0
- graphcore/domain/entity/grant/Grant.py +31 -0
- graphcore/domain/entity/grant/__init__.py +0 -0
- graphcore/domain/entity/group/Group.py +48 -0
- graphcore/domain/entity/group/README.md +88 -0
- graphcore/domain/entity/group/__init__.py +0 -0
- graphcore/domain/entity/invite/Invite.py +31 -0
- graphcore/domain/entity/invite/__init__.py +0 -0
- graphcore/domain/entity/request_template/RequestTemplate.py +48 -0
- graphcore/domain/entity/request_template/__init__.py +0 -0
- graphcore/domain/entity/request_template/tests/__init__.py +0 -0
- graphcore/domain/entity/request_template/tests/test_request_template.py +52 -0
- graphcore/domain/entity/service_account/ServiceAccount.py +41 -0
- graphcore/domain/entity/service_account/__init__.py +0 -0
- graphcore/domain/entity/strategy_request/StrategyRequest.py +61 -0
- graphcore/domain/entity/strategy_request/__init__.py +0 -0
- graphcore/domain/entity/strategy_request/tests/__init__.py +0 -0
- graphcore/domain/entity/strategy_request/tests/test_strategy_request_entity.py +35 -0
- graphcore/domain/entity/tests/__init__.py +0 -0
- graphcore/domain/entity/tests/test_entity.py +227 -0
- graphcore/domain/entity/tests/test_grant_group_entities.py +36 -0
- graphcore/domain/entity/tests/test_write_once_fields.py +98 -0
- graphcore/domain/entity/user/User.py +39 -0
- graphcore/domain/entity/user/__init__.py +0 -0
- graphcore/domain/entity/user/tests/__init__.py +0 -0
- graphcore/domain/entity/user/tests/test_user_entity.py +33 -0
- graphcore/domain/entity/view/View.py +37 -0
- graphcore/domain/entity/view/__init__.py +0 -0
- graphcore/domain/entity/view/position.py +78 -0
- graphcore/domain/entity/view/tests/__init__.py +0 -0
- graphcore/domain/entity/view/tests/test_position.py +71 -0
- graphcore/domain/entity/view/tests/test_view_entity.py +134 -0
- graphcore/domain/strategy/BaseStrategy.py +759 -0
- graphcore/domain/strategy/DeploymentStrategies.py +55 -0
- graphcore/domain/strategy/GrantStrategies.py +189 -0
- graphcore/domain/strategy/GroupStrategies.py +193 -0
- graphcore/domain/strategy/InviteStrategies.py +84 -0
- graphcore/domain/strategy/RequestTemplateStrategies.py +126 -0
- graphcore/domain/strategy/ViewStrategies.py +219 -0
- graphcore/domain/strategy/__init__.py +0 -0
- graphcore/domain/strategy/runner.py +84 -0
- graphcore/domain/strategy/session.py +56 -0
- graphcore/domain/strategy/tests/BaseStrategyTest.py +167 -0
- graphcore/domain/strategy/tests/__init__.py +0 -0
- graphcore/domain/strategy/tests/test_BaseStrategies.py +870 -0
- graphcore/domain/strategy/tests/test_grant_strategies.py +245 -0
- graphcore/domain/strategy/tests/test_group_strategies.py +99 -0
- graphcore/domain/strategy/tests/test_runner.py +220 -0
- graphcore/domain/strategy/tests/test_strategy_locks.py +446 -0
- graphcore/domain/strategy/tests/test_utils.py +95 -0
- graphcore/domain/strategy/tests/test_view_strategies.py +436 -0
- graphcore/errors.py +145 -0
- graphcore/execution/README.md +97 -0
- graphcore/execution/StrategyExecutorService.py +333 -0
- graphcore/execution/__init__.py +0 -0
- graphcore/execution/dispatcher.py +19 -0
- graphcore/execution/environments/__init__.py +0 -0
- graphcore/execution/environments/celery.py +59 -0
- graphcore/execution/environments/in_process.py +55 -0
- graphcore/execution/local_session.py +117 -0
- graphcore/execution/redis_run_events.py +74 -0
- graphcore/execution/requests.py +22 -0
- graphcore/execution/run_events.py +85 -0
- graphcore/execution/strategy_context.py +54 -0
- graphcore/execution/tasks.py +34 -0
- graphcore/execution/tests/__init__.py +5 -0
- graphcore/execution/tests/contract.py +171 -0
- graphcore/execution/tests/support.py +310 -0
- graphcore/execution/tests/test_dispatchers.py +76 -0
- graphcore/execution/tests/test_executor.py +368 -0
- graphcore/execution/tests/test_local_session.py +95 -0
- graphcore/execution/tests/test_reconcile_runs.py +134 -0
- graphcore/execution/tests/test_run_events.py +106 -0
- graphcore/execution/tests/test_strategy_context.py +62 -0
- graphcore/gateway/__init__.py +1 -0
- graphcore/gateway/remote.py +35 -0
- graphcore/gateway/tests/__init__.py +0 -0
- graphcore/gateway/tests/test_remote.py +30 -0
- graphcore/graph/EntityService.py +710 -0
- graphcore/graph/__init__.py +0 -0
- graphcore/graph/entity_cache.py +152 -0
- graphcore/graph/tests/__init__.py +4 -0
- graphcore/graph/tests/test_EntityService.py +908 -0
- graphcore/graph/tests/test_EntityService_list.py +170 -0
- graphcore/graph/tests/test_EntityService_model_resolution.py +339 -0
- graphcore/graph/tests/test_EntityService_referrers.py +236 -0
- graphcore/graph/tests/test_EntityService_routing.py +119 -0
- graphcore/graph/tests/test_dependent_on.py +141 -0
- graphcore/graph/tests/test_engine_is_type_agnostic.py +25 -0
- graphcore/graph/tests/test_engine_resolves_read_permission.py +93 -0
- graphcore/graph/tests/test_entity_cache.py +159 -0
- graphcore/graph/tests/test_null_entity_cache.py +12 -0
- graphcore/management/__init__.py +0 -0
- graphcore/management/commands/__init__.py +0 -0
- graphcore/management/commands/dev_reset.py +18 -0
- graphcore/management/commands/graphcore_createadmin.py +65 -0
- graphcore/management/commands/graphcore_policy.py +59 -0
- graphcore/management/commands/graphcore_status.py +98 -0
- graphcore/management/tests/__init__.py +0 -0
- graphcore/management/tests/test_createadmin.py +78 -0
- graphcore/management/tests/test_policy_command.py +46 -0
- graphcore/management/tests/test_status_command.py +85 -0
- graphcore/migrations/0001_initial.py +186 -0
- graphcore/migrations/0002_invite.py +26 -0
- graphcore/migrations/__init__.py +0 -0
- graphcore/models.py +11 -0
- graphcore/persistence/ENTITY_REPOSITORY_TECHNICAL_TDD.md +396 -0
- graphcore/persistence/__init__.py +6 -0
- graphcore/persistence/django/__init__.py +0 -0
- graphcore/persistence/django/backends.py +43 -0
- graphcore/persistence/django/bindings.py +28 -0
- graphcore/persistence/django/cache.py +38 -0
- graphcore/persistence/django/compiler.py +214 -0
- graphcore/persistence/django/identity.py +18 -0
- graphcore/persistence/django/models.py +252 -0
- graphcore/persistence/django/repository.py +525 -0
- graphcore/persistence/django/tests/__init__.py +0 -0
- graphcore/persistence/django/tests/test_backends.py +68 -0
- graphcore/persistence/django/tests/test_compiler.py +269 -0
- graphcore/persistence/django/tests/test_repository.py +472 -0
- graphcore/persistence/django/tests/test_shared_column.py +120 -0
- graphcore/persistence/django/tests/test_threads.py +50 -0
- graphcore/persistence/django/tests/test_update_shape.py +175 -0
- graphcore/persistence/django/threads.py +38 -0
- graphcore/persistence/repository.py +172 -0
- graphcore/persistence/tests/__init__.py +0 -0
- graphcore/persistence/tests/contract.py +688 -0
- graphcore/persistence/tests/evaluate.py +51 -0
- graphcore/persistence/tests/fixtures.py +32 -0
- graphcore/persistence/tests/memory.py +263 -0
- graphcore/persistence/tests/test_memory_repository.py +10 -0
- graphcore/persistence/tests/test_query_types.py +127 -0
- graphcore/public/__init__.py +9 -0
- graphcore/public/api.py +9 -0
- graphcore/public/apps.py +10 -0
- graphcore/public/auth/__init__.py +1 -0
- graphcore/public/auth/grants.py +7 -0
- graphcore/public/auth/onboarding.py +8 -0
- graphcore/public/auth/perms.py +7 -0
- graphcore/public/auth/policy.py +10 -0
- graphcore/public/auth/roles.py +8 -0
- graphcore/public/auth/subjects.py +7 -0
- graphcore/public/entities/__init__.py +32 -0
- graphcore/public/errors.py +19 -0
- graphcore/public/persistence/__init__.py +44 -0
- graphcore/public/persistence/django.py +24 -0
- graphcore/public/scheduling.py +23 -0
- graphcore/public/strategies/__init__.py +85 -0
- graphcore/public/test_settings.py +16 -0
- graphcore/public/testing.py +47 -0
- graphcore/registry/EntityDirectory.py +246 -0
- graphcore/registry/README.md +147 -0
- graphcore/registry/StrategyDirectory.py +308 -0
- graphcore/registry/TYPE_METADATA_PLACEMENT.md +66 -0
- graphcore/registry/__init__.py +0 -0
- graphcore/registry/app_discovery.py +108 -0
- graphcore/registry/decorators.py +77 -0
- graphcore/registry/discovery.py +111 -0
- graphcore/registry/registry.py +79 -0
- graphcore/registry/tests/__init__.py +0 -0
- graphcore/registry/tests/test_agent_frontend_discovery.py +56 -0
- graphcore/registry/tests/test_app_config.py +36 -0
- graphcore/registry/tests/test_discovery.py +147 -0
- graphcore/registry/tests/test_entity_directory_storage.py +73 -0
- graphcore/registry/tests/test_import_package.py +87 -0
- graphcore/registry/tests/test_principal_flag.py +67 -0
- graphcore/registry/tests/test_strategy_directory.py +29 -0
- graphcore/routes/__init__.py +116 -0
- graphcore/routes/tests/__init__.py +0 -0
- graphcore/routes/tests/test_routes.py +90 -0
- graphcore/runtime.py +243 -0
- graphcore/scheduling/__init__.py +0 -0
- graphcore/scheduling/beat_scheduler.py +164 -0
- graphcore/scheduling/beat_tasks.py +63 -0
- graphcore/scheduling/scheduler.py +37 -0
- graphcore/scheduling/tests/__init__.py +0 -0
- graphcore/scheduling/tests/contract.py +136 -0
- graphcore/scheduling/tests/memory.py +42 -0
- graphcore/scheduling/tests/test_beat_scheduler.py +87 -0
- graphcore/scheduling/tests/test_memory_scheduler.py +15 -0
- graphcore/scheduling/tests/test_ticks.py +143 -0
- graphcore/tasks.py +9 -0
- graphcore/test_settings.py +78 -0
- graphcore/testing/__init__.py +0 -0
- graphcore/testing/case.py +112 -0
- graphcore/testing/runner.py +32 -0
- graphcore/testing/settings.py +26 -0
- graphcore/testing/tests/__init__.py +0 -0
- graphcore/testing/tests/agent_view_fixture.py +19 -0
- graphcore/testing/tests/test_case_and_runner.py +219 -0
- graphcore/testing/tests/test_settings_for_apps.py +50 -0
- graphcore/tests/__init__.py +0 -0
- graphcore/tests/ids.py +14 -0
- graphcore/tests/public_api_manifest.py +102 -0
- graphcore/tests/runs.py +7 -0
- graphcore/tests/test_app_discovery.py +90 -0
- graphcore/tests/test_composition_boundaries.py +231 -0
- graphcore/tests/test_docs_discovery.py +108 -0
- graphcore/tests/test_no_print.py +70 -0
- graphcore/tests/test_packaging.py +64 -0
- graphcore/tests/test_public_api_boundaries.py +229 -0
- graphcore/tests/test_public_api_contract.py +62 -0
- graphcore/tests/test_public_api_docs.py +28 -0
- graphcore/tests/test_runtime.py +42 -0
- graphcore/tests/test_shared_type_boundaries.py +128 -0
- graphcore/tests/test_shared_types.py +144 -0
- graphcore/tests/test_test_settings.py +45 -0
- graphcore/transport/__init__.py +0 -0
- graphcore/transport/agent_asgi.py +68 -0
- graphcore/transport/agent_client.py +85 -0
- graphcore/transport/channel_layer.py +68 -0
- graphcore/transport/consumers.py +507 -0
- graphcore/transport/routing.py +6 -0
- graphcore/transport/tests/__init__.py +0 -0
- graphcore/transport/tests/test_agent_client.py +31 -0
- graphcore/transport/tests/test_api_views.py +733 -0
- graphcore/transport/tests/test_channel_layer.py +96 -0
- graphcore/transport/tests/test_consumers.py +963 -0
- graphcore/transport/tests/test_resource_metadata.py +67 -0
- graphcore/transport/urls.py +29 -0
- graphcore/transport/views.py +358 -0
- graphcore/types/__init__.py +4 -0
- graphcore/types/access.py +114 -0
- graphcore/types/api.py +76 -0
- graphcore/types/entities.py +100 -0
- graphcore/types/entity_id.py +85 -0
- graphcore/types/execution.py +41 -0
- graphcore/types/identity.py +20 -0
- graphcore/types/onboarding.py +20 -0
- graphcore/types/query.py +116 -0
- graphcore/types/schedules.py +91 -0
- graphcore/types/strategy.py +73 -0
- graphcore/types/tests/__init__.py +0 -0
- graphcore/types/tests/test_entity_id.py +50 -0
- graphcore/urls.py +5 -0
- graphcore_kernel-0.1.0.dist-info/METADATA +94 -0
- graphcore_kernel-0.1.0.dist-info/RECORD +343 -0
- graphcore_kernel-0.1.0.dist-info/WHEEL +5 -0
- graphcore_kernel-0.1.0.dist-info/entry_points.txt +2 -0
- graphcore_kernel-0.1.0.dist-info/licenses/LICENSE +202 -0
- graphcore_kernel-0.1.0.dist-info/licenses/NOTICE +2 -0
- graphcore_kernel-0.1.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,389 @@
|
|
|
1
|
+
# Agent Frontend — Technical Design
|
|
2
|
+
|
|
3
|
+
## Introduction
|
|
4
|
+
|
|
5
|
+
An agent is a client of a GraphCore deployment, in the same position as the
|
|
6
|
+
web frontend: it acts for the user who connected it, reads what that user
|
|
7
|
+
may read, and acts through strategies. Unlike the web frontend, the agent
|
|
8
|
+
host (Claude, ChatGPT, an IDE agent) cannot run our code. The **agent
|
|
9
|
+
frontend** therefore renders for it on the server: an ASGI app, separate
|
|
10
|
+
from Django, that resolves addresses, renders them as text for a language
|
|
11
|
+
model, and exposes the result over MCP. It reaches the kernel only through
|
|
12
|
+
`GraphAPI`, as the web frontend does.
|
|
13
|
+
|
|
14
|
+
The problem it solves is entry and orientation. The entity graph has no
|
|
15
|
+
fixed shape an agent can memorize: containers nest, apps add types, and
|
|
16
|
+
access differs per user. The agent frontend gives an agent what the web
|
|
17
|
+
client gives a person: a home, addresses it can open, and actions that
|
|
18
|
+
depend on where it is. The surface is hypermedia: the agent holds renders
|
|
19
|
+
and verbs, never view logic or state.
|
|
20
|
+
|
|
21
|
+
It is also shaped by where its output goes. Every render the agent reads
|
|
22
|
+
stays in its context window for the rest of the conversation. Renders are
|
|
23
|
+
compact by default, tool definitions never change, and writes return small
|
|
24
|
+
results.
|
|
25
|
+
|
|
26
|
+
This document is part of the view system (`VIEW_SYSTEM_TDD.md`), which
|
|
27
|
+
defines addresses, the route table, client registries, render versions,
|
|
28
|
+
and mirroring. It does not cover authorization
|
|
29
|
+
(`AUTHORIZATION_TECHNICAL_TDD.md`) or identity (`IDENTITY.md`).
|
|
30
|
+
|
|
31
|
+
## Definitions
|
|
32
|
+
|
|
33
|
+
- **Agent**: a program, typically a language model with a tool-calling
|
|
34
|
+
loop, connected over MCP. An agent is not a principal. It forwards the
|
|
35
|
+
credentials of the user who connected it, and every read and write is
|
|
36
|
+
that user's.
|
|
37
|
+
- **Agent host**: the application running the agent and its MCP client:
|
|
38
|
+
Claude, Claude Code, ChatGPT.
|
|
39
|
+
- **Agent frontend**: the `agent` client: `graphcore.agent_frontend`, an
|
|
40
|
+
ASGI app served beside Django by the same server. It holds the agent
|
|
41
|
+
registry, renders addresses, and serves the MCP endpoint.
|
|
42
|
+
- **Address**: as in `VIEW_SYSTEM_TDD.md`. Every tool that reads or acts at
|
|
43
|
+
a place takes its address as `at`.
|
|
44
|
+
- **Agent view**: a render function registered with `@agent_view`. It
|
|
45
|
+
renders one view name and declares the view's tools.
|
|
46
|
+
- **Render**: Markdown produced for one address: a header, the view's
|
|
47
|
+
content, its child placements, and its tool signatures.
|
|
48
|
+
- **Placement**: another address placed inside a render, **full** (rendered
|
|
49
|
+
with its own agent view) or **compact** (one line: label, type, address).
|
|
50
|
+
- **View tool**: a tool an agent view offers at its address. Either a
|
|
51
|
+
**strategy tool**, which runs one registered strategy, or an
|
|
52
|
+
**operation**, which is view code that performs several reads and
|
|
53
|
+
strategy executions as one tool.
|
|
54
|
+
- **Tool signature**: a view tool written compactly in a render:
|
|
55
|
+
`review_document(doc: entity, verdict: approve|reject, note?: str)`.
|
|
56
|
+
- **Generic tools**: the four MCP tools the endpoint exposes: `open`,
|
|
57
|
+
`find`, `call`, `act`.
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
## Requirements
|
|
62
|
+
|
|
63
|
+
1. **Stable entry.** An agent starts at `/` and reaches any entity its user
|
|
64
|
+
may read with the generic tools alone, without prior knowledge of the
|
|
65
|
+
graph or app-specific tools.
|
|
66
|
+
2. **Location-dependent affordances.** The tools offered at an address are
|
|
67
|
+
the ones its view declares, decided in code by the app, as the web view
|
|
68
|
+
decides its controls.
|
|
69
|
+
3. **Parity with the web client.** The data an agent view renders is data
|
|
70
|
+
the web client shows at the same address, read through the same
|
|
71
|
+
`GraphAPI` calls.
|
|
72
|
+
4. **Composition.** A view places other addresses without knowing how they
|
|
73
|
+
render. Each placement is rendered by the agent view resolved for it,
|
|
74
|
+
registered or default.
|
|
75
|
+
5. **Curation without lock-in.** A view may show a subset and offer
|
|
76
|
+
operations; `find` and `act` still reach everything the user may read
|
|
77
|
+
and do.
|
|
78
|
+
6. **No new authority.** Agent views, operations, and defaults confer no
|
|
79
|
+
access. Every read and write passes through `GraphAPI` as the user.
|
|
80
|
+
7. **Stateless.** The server holds nothing between calls. Every call names
|
|
81
|
+
its address; no session, location, or subscription is kept.
|
|
82
|
+
8. **Fixed tool list.** The MCP tool list is the same for every user, every
|
|
83
|
+
address, and every call.
|
|
84
|
+
9. **Context economy.** Renders place children compactly unless the view
|
|
85
|
+
asks for more, tool signatures are compact, and writes return small
|
|
86
|
+
results.
|
|
87
|
+
10. **Stale writes are refused.** A write states the render version it was
|
|
88
|
+
based on; a changed address refuses it.
|
|
89
|
+
11. **Readable on its own.** A render is complete without view state,
|
|
90
|
+
layout, or an earlier render.
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
## Architecture
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
### Serving and transport
|
|
99
|
+
|
|
100
|
+
```
|
|
101
|
+
uvicorn (graphcore run, one port)
|
|
102
|
+
/mcp ← agent host (MCP) → agent frontend (ASGI) → GraphAPI client ┐
|
|
103
|
+
all else ← browser (HTTP/WS) → Django (ASGI) │ in-process
|
|
104
|
+
GraphAPI ◄──────┘
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
- The agent frontend is its own ASGI app, separate from Django. The
|
|
108
|
+
deployment's ASGI entry routes `/mcp` to it and everything else to
|
|
109
|
+
Django, so `graphcore run` serves both on one port. It is deployed and
|
|
110
|
+
launched with the rest of the backend and adds no role, port, or proxy.
|
|
111
|
+
- It calls `GraphAPI` through a client interface. The implementation in use
|
|
112
|
+
calls `GraphAPI` in the same process. An implementation over the
|
|
113
|
+
backend's HTTP and WebSocket transports would let the agent frontend run
|
|
114
|
+
as its own server without changing its code.
|
|
115
|
+
- Its code is `graphcore.agent_frontend`, in the `graphcore` package,
|
|
116
|
+
structured as a library: a public API for apps' agent views, depending
|
|
117
|
+
on the `GraphAPI` client interface and the public types and never on
|
|
118
|
+
Django or the backend's modules.
|
|
119
|
+
- At startup it reads the route table and the strategy registry's request
|
|
120
|
+
schemas from `GraphAPI`, and registers the agent views of every installed
|
|
121
|
+
app (`VIEW_SYSTEM_TDD.md`, App bootstrap).
|
|
122
|
+
- The MCP endpoint uses Streamable HTTP without a session identifier. Each
|
|
123
|
+
request is authenticated and answered on its own.
|
|
124
|
+
- The endpoint requires a bearer token on every request, authenticates it
|
|
125
|
+
through the `GraphAPI` client, and passes the user as the principal of
|
|
126
|
+
every `GraphAPI` call. A missing or invalid token gets a 401. Its
|
|
127
|
+
`WWW-Authenticate: Bearer resource_metadata="…"` points at
|
|
128
|
+
`/.well-known/oauth-protected-resource/mcp`, which names the issuer, so an
|
|
129
|
+
MCP host signs the user in at the issuer itself (dynamic client registration,
|
|
130
|
+
then code + PKCE) and never needs a pasted token. See
|
|
131
|
+
`kernel/backend/graphcore/auth/authn/README.md` (Telling clients where to
|
|
132
|
+
sign in).
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
### Generic tools
|
|
137
|
+
|
|
138
|
+
The endpoint exposes exactly these tools.
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
| Tool | Does | Authorization |
|
|
142
|
+
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
|
|
143
|
+
| `open(at, version?)` | Returns the render at `at`. With `version`, the render also states whether the address changed since that version. | Read on the address's entity, when it has one; every read the render makes. |
|
|
144
|
+
| `find(type, predicate?, limit?)` | Runs the access-scoped typed query. Returns matches compactly: label, type, address. | The kernel's read scoping of `list_entities`. |
|
|
145
|
+
| `call(at, tool, params, seen_version?)` | Resolves the view at `at`, checks that `tool` is one of its view tools, and runs it. | Each strategy execution, as the user. |
|
|
146
|
+
| `act(strategy, target?, params)` | Runs any registered strategy, outside any view. | The strategy's invocation and persistence checks. |
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
`open` and `find` read; `call` and `act` write. `call` is the curated path;
|
|
150
|
+
`act` is the escape hatch that keeps a view from locking the agent out of
|
|
151
|
+
anything, as typing a URL bypasses a page's buttons.
|
|
152
|
+
|
|
153
|
+
`call`:
|
|
154
|
+
|
|
155
|
+
- Without `seen_version`, it runs unchecked. With it, the server
|
|
156
|
+
re-renders `at` and refuses a mismatch with `Stale`, returning the
|
|
157
|
+
current version and a one-line description of what changed.
|
|
158
|
+
- `params` are checked against the tool's request schema. A mismatch
|
|
159
|
+
returns `InvalidRequest` with the full JSON schema.
|
|
160
|
+
- A success returns the tool's result, the address, its new render
|
|
161
|
+
version, and a one-line note of what changed. It never returns a render;
|
|
162
|
+
the agent calls `open` when it wants one.
|
|
163
|
+
|
|
164
|
+
The endpoint's MCP `instructions` state: start with `open("/")`; every
|
|
165
|
+
render begins with its address and version; renders are snapshots, so
|
|
166
|
+
re-open an address before answering about its current state; pass
|
|
167
|
+
`seen_version` when acting on a render.
|
|
168
|
+
|
|
169
|
+
### Resources
|
|
170
|
+
|
|
171
|
+
Each route is a resource template whose URI is the deployment's base URL
|
|
172
|
+
followed by the route. `resources/read` returns the same render as `open`.
|
|
173
|
+
The endpoint does not support `resources/subscribe`, which needs state
|
|
174
|
+
held per connection (Requirement 7).
|
|
175
|
+
|
|
176
|
+
### Render format
|
|
177
|
+
|
|
178
|
+
```markdown
|
|
179
|
+
# Handbook · stacks.Stack
|
|
180
|
+
address: /e/k3x9…/m2p… · version: 7f3a…
|
|
181
|
+
|
|
182
|
+
The team handbook. 42 documents, 3 awaiting review.
|
|
183
|
+
|
|
184
|
+
## Awaiting review
|
|
185
|
+
- Onboarding · stacks.Document · /e/k3x9…/a81…
|
|
186
|
+
- Expense policy · stacks.Document · /e/k3x9…/b02…
|
|
187
|
+
- On-call · stacks.Document · /e/k3x9…/c77…
|
|
188
|
+
|
|
189
|
+
## Tools
|
|
190
|
+
- create_document(title: str, folder?: entity) — Create a document in this stack.
|
|
191
|
+
- review_document(doc: entity, verdict: approve|reject, note?: str) — Record a review.
|
|
192
|
+
- publish_reviewed() — Publish every approved document in this stack.
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
- The header is the label and type (or the view name when there is no
|
|
196
|
+
entity), the address, and the render version.
|
|
197
|
+
- A compact placement is one line: label, type, address.
|
|
198
|
+
- A full placement is the child's render under a heading, without its
|
|
199
|
+
tools section.
|
|
200
|
+
- Tool signatures list parameters with their types and a one-line
|
|
201
|
+
description. `entity` marks a parameter that takes an address or
|
|
202
|
+
identifier.
|
|
203
|
+
|
|
204
|
+
|
|
205
|
+
|
|
206
|
+
### Agent views
|
|
207
|
+
|
|
208
|
+
An agent view is a function in the app's agent frontend package (`backend/<app>_agent_frontend/`), by convention in `agent_views.py`:
|
|
209
|
+
|
|
210
|
+
```python
|
|
211
|
+
async def stack_tools(ctx, stack):
|
|
212
|
+
return [
|
|
213
|
+
strategy_tool('CreateDocument', bind=stack.entity_id),
|
|
214
|
+
strategy_tool('ReviewDocument', name='review_document'),
|
|
215
|
+
publish_reviewed,
|
|
216
|
+
]
|
|
217
|
+
|
|
218
|
+
@agent_view('stacks.stack', default_for=['stacks.Stack'], tools=stack_tools)
|
|
219
|
+
async def stack(ctx, stack):
|
|
220
|
+
docs = await ctx.children(stack, 'stacks.Document')
|
|
221
|
+
pending = [d for d in docs if d.review_status == 'pending']
|
|
222
|
+
return [
|
|
223
|
+
f"{stack.description}\n\n{len(docs)} documents, {len(pending)} awaiting review.",
|
|
224
|
+
"## Awaiting review",
|
|
225
|
+
*[ctx.place(d.id) for d in pending],
|
|
226
|
+
]
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
- Entity types are named by their registry identifiers (`'stacks.Stack'`) and
|
|
230
|
+
strategies by their bare registry names (`'CreateDocument'`). The
|
|
231
|
+
agent frontend does not import the app's backend.
|
|
232
|
+
- `ctx` carries the user and the address, and offers `GraphAPI` reads
|
|
233
|
+
(`ctx.get`, `ctx.children`, `ctx.find`, `ctx.query`), the route table (`ctx.routes`),
|
|
234
|
+
registered agent views by name (`ctx.view`), and placement.
|
|
235
|
+
- `ctx.place(target, full=False)` places an entity identifier (its
|
|
236
|
+
`/e/{entity}` address) or any address. Placement records the address;
|
|
237
|
+
the frontend renders it.
|
|
238
|
+
- The function returns a list of strings and placements, joined in order.
|
|
239
|
+
- `@agent_view(name, default_for=[...], tools=fn)`. `tools` is
|
|
240
|
+
`async def (ctx, entity) -> list`, called on every render with the same
|
|
241
|
+
`ctx` and entity as the view; `entity` is `None` for a view with no entity.
|
|
242
|
+
- Every module-level agent view defined in an app's agent frontend
|
|
243
|
+
package is registered at startup. A view one module imports from another
|
|
244
|
+
package is not registered again.
|
|
245
|
+
- The registry has two layers. The base views (see Defaults) form the
|
|
246
|
+
lower layer; app views form the upper one. An app view with the same name
|
|
247
|
+
or `default_for` type as a base view replaces it. Two app views with the
|
|
248
|
+
same name, or claiming `default_for` on the same type, fail at
|
|
249
|
+
registration.
|
|
250
|
+
|
|
251
|
+
A parent never sees how a placement renders. The child's agent view, or the
|
|
252
|
+
default, decides that, as `<EntityView entityId={id} />` does in the web
|
|
253
|
+
client.
|
|
254
|
+
|
|
255
|
+
### Resolution
|
|
256
|
+
|
|
257
|
+
As in `VIEW_SYSTEM_TDD.md`, with the agent registry, where every view,
|
|
258
|
+
base or app, is found the same way: by the view name its route resolves to.
|
|
259
|
+
|
|
260
|
+
1. For `entity`, the agent view whose `default_for` includes the entity's
|
|
261
|
+
type.
|
|
262
|
+
2. The agent view registered under the route's view name: `home` at `/`,
|
|
263
|
+
`entity` at `/e/{entity}`, an app's own name at its routes.
|
|
264
|
+
3. For a route with an entity, the agent view registered as `entity`.
|
|
265
|
+
4. A placeholder naming the view and its address.
|
|
266
|
+
|
|
267
|
+
The agent client stores no view state of its own. It reads the view
|
|
268
|
+
entities other clients store: a `graphcore.View` renders with the
|
|
269
|
+
base `view` view (step 1), as the agent view its `component` names, over the
|
|
270
|
+
entity it `renders`. View names are shared across clients, so a web view and
|
|
271
|
+
an agent view registered under one name render the same view entity.
|
|
272
|
+
Choosing an agent view for a placement through stored view state is an open
|
|
273
|
+
item.
|
|
274
|
+
|
|
275
|
+
### Placement depth
|
|
276
|
+
|
|
277
|
+
Placements have no depth limit; a view decides how much of its children to
|
|
278
|
+
render. A render larger than the endpoint's size limit fails with
|
|
279
|
+
`RenderTooLarge`, naming the address, rather than being truncated. The
|
|
280
|
+
limit is below the tool-result limits of common agent hosts, so a host
|
|
281
|
+
never truncates a render.
|
|
282
|
+
|
|
283
|
+
### View tools
|
|
284
|
+
|
|
285
|
+
A **strategy tool** names a registered strategy and declares its target:
|
|
286
|
+
|
|
287
|
+
- **`takes_target=True`** (the default): the agent supplies the target. The
|
|
288
|
+
tool's signature and schema gain a required `target` parameter, an entity
|
|
289
|
+
id or address.
|
|
290
|
+
- **`takes_target=False`**: the strategy runs untargeted, on the
|
|
291
|
+
deployment's authority. The agent sees no target.
|
|
292
|
+
- **`bind=<entity id>`**: the view fixes the target, so the agent sees no
|
|
293
|
+
target. `bind` takes precedence over `takes_target`.
|
|
294
|
+
|
|
295
|
+
```python
|
|
296
|
+
async def stack_tools(ctx, stack):
|
|
297
|
+
return [
|
|
298
|
+
# Bound: runs on this stack.
|
|
299
|
+
# Signature: archive_stack()
|
|
300
|
+
strategy_tool('ArchiveStack', bind=stack.entity_id),
|
|
301
|
+
# Default: the agent supplies `target`.
|
|
302
|
+
# Signature: review_document(target: entity, verdict: str)
|
|
303
|
+
strategy_tool('ReviewDocument', name='review_document'),
|
|
304
|
+
# takes_target=False: runs untargeted on the deployment's authority.
|
|
305
|
+
# Signature: create_stack(name: str)
|
|
306
|
+
strategy_tool('CreateStack', takes_target=False),
|
|
307
|
+
]
|
|
308
|
+
|
|
309
|
+
@agent_view('stacks.stack', default_for=['stacks.Stack'], tools=stack_tools)
|
|
310
|
+
async def stack(ctx, stack): ...
|
|
311
|
+
```
|
|
312
|
+
|
|
313
|
+
Its schema is the strategy's request schema from the registry, with
|
|
314
|
+
`target` added only when the agent supplies it. The Tools list shows each tool as a compact
|
|
315
|
+
signature; a parameter that is not a scalar shows as `json`, and the full
|
|
316
|
+
schema is returned in the error when `call` rejects the parameters.
|
|
317
|
+
|
|
318
|
+
An **operation** is a function decorated with `@operation`, taking `ctx`
|
|
319
|
+
and its parameters and declaring its request schema. It performs reads and
|
|
320
|
+
strategy executions through `ctx`, each checked as the user; it has no
|
|
321
|
+
other path. Operations exist for multi-step tasks ("create a document in
|
|
322
|
+
the review folder and assign a reviewer") and computed targets ("archive
|
|
323
|
+
every document in this stack with no edits in 90 days").
|
|
324
|
+
|
|
325
|
+
A tool's name and description default to the strategy's; the view may set
|
|
326
|
+
either.
|
|
327
|
+
|
|
328
|
+
### Defaults
|
|
329
|
+
|
|
330
|
+
Every address renders and acts with no app agent-view code at all. The
|
|
331
|
+
defaults are the base views in `graphcore.agent_frontend.base`, declared
|
|
332
|
+
with `@agent_view` like any app view and registered in the base layer:
|
|
333
|
+
|
|
334
|
+
- **`entity`**: three sections. `## Entity` states the base entity's
|
|
335
|
+
structural keys plainly: id, type, owner (marked `(you)` for the caller),
|
|
336
|
+
parent as label, type and address or `none (top level)`, version and sibling
|
|
337
|
+
position. `## Fields` prints every other key of `to_dict()`, `attributes`
|
|
338
|
+
included: strings bare, other values as JSON, an entity identifier with its
|
|
339
|
+
address, and a value longer than 500 characters cut with its full length.
|
|
340
|
+
`## Children (n)` places the children compactly, in sibling order. Tools
|
|
341
|
+
are the strategies the policy allows on the type, each as a strategy tool
|
|
342
|
+
bound to the entity. An app that adds a strategy to another app's type
|
|
343
|
+
with `policy.extend` adds it to that type's default tools. The sections
|
|
344
|
+
are exported (`entity_summary`, `entity_fields`, `children_section`) for an
|
|
345
|
+
app view to reuse.
|
|
346
|
+
- **`home`**: `## Places`, a compact placement of every route other than
|
|
347
|
+
`/` that needs no entity, then the user's top-level entities grouped by
|
|
348
|
+
type, placed compactly. Tools are the strategies on the deployment's
|
|
349
|
+
allowlist. The web client's `TopBar` links the same routes.
|
|
350
|
+
- **`view`**, the default for `graphcore.View`: a view renders as
|
|
351
|
+
itself, as in the web client. It calls the agent view its `component`
|
|
352
|
+
names (`ctx.view(name)`) with the entity it `renders`, or with none, under
|
|
353
|
+
one line naming the component and the view entity. The component reads the view
|
|
354
|
+
entity's stored `state` as `ctx.view_state` (empty outside a view entity),
|
|
355
|
+
so it shows what another client stored there, such as a selection. Tools are the
|
|
356
|
+
component's, then the view entity's own. Without an agent view of that name,
|
|
357
|
+
or when the name is the `view` view's own, it renders with `entity` under a
|
|
358
|
+
note; when its `renders` entity is not readable, it says so.
|
|
359
|
+
|
|
360
|
+
An app replaces any of them by registering an agent view under its name, or,
|
|
361
|
+
for `view`, claiming `graphcore.View` in `default_for`:
|
|
362
|
+
|
|
363
|
+
```python
|
|
364
|
+
from graphcore.agent_frontend import agent_view
|
|
365
|
+
from graphcore.agent_frontend.base import children_section, entity_fields, type_tools
|
|
366
|
+
|
|
367
|
+
@agent_view('entity', tools=type_tools)
|
|
368
|
+
async def entity(ctx, entity):
|
|
369
|
+
return ['\n'.join(entity_fields(ctx, entity)), *await children_section(ctx, entity)]
|
|
370
|
+
```
|
|
371
|
+
|
|
372
|
+
The module also exports its parts for reuse: `entity_summary`,
|
|
373
|
+
`entity_fields`, `children_section`, `places`, `grouped`, `type_tools`,
|
|
374
|
+
`deployment_tools`, and the views `entity_view` and `home_view`. A view with `default_for` that wants the type's default tools
|
|
375
|
+
returns `type_tools(ctx, entity)` from its `tools`.
|
|
376
|
+
|
|
377
|
+
|
|
378
|
+
|
|
379
|
+
### Authorization
|
|
380
|
+
|
|
381
|
+
The agent frontend performs no checks and skips none:
|
|
382
|
+
|
|
383
|
+
- Renders, including every placement, are built from `GraphAPI` reads,
|
|
384
|
+
which refuse what the user may not read. A render cannot place an entity
|
|
385
|
+
the user cannot open.
|
|
386
|
+
- `call` and `act` run strategies through `GraphAPI` as the user.
|
|
387
|
+
- An operation's steps are checked one by one; a refused step raises, and
|
|
388
|
+
the operation reports the refusal.
|
|
389
|
+
|
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
# Kernel Architecture Principles
|
|
2
|
+
|
|
3
|
+
How the kernel is organized and the rules code must follow.
|
|
4
|
+
|
|
5
|
+
## The pattern
|
|
6
|
+
|
|
7
|
+
Hexagonal at the boundary, command-based in the core.
|
|
8
|
+
|
|
9
|
+
- **Not Django active record**: storage is a private decision below the
|
|
10
|
+
serialization boundary; the interchange model, not the Django model, is the
|
|
11
|
+
entity.
|
|
12
|
+
- **Not full tactical DDD**: the consistency unit is fixed globally — one
|
|
13
|
+
optimistic-locked entity — so aggregate machinery would re-derive settled
|
|
14
|
+
kernel contract.
|
|
15
|
+
- **CQRS by construction**: strategies are the only writes (command pattern,
|
|
16
|
+
a kernel invariant); views and ACL-scoped queries are the read side.
|
|
17
|
+
|
|
18
|
+
## The rules
|
|
19
|
+
|
|
20
|
+
1. **Entities hold domain state and behavior, and declare metadata. They
|
|
21
|
+
never call infrastructure.** No imports of DB, cache, channels, or
|
|
22
|
+
adapters from an entity class.
|
|
23
|
+
2. **Declarative metadata on domain classes is legitimate; imperative
|
|
24
|
+
infrastructure calls are not.** `write_once_fields`, `ownerless`, param
|
|
25
|
+
schemas on entities; `CPU_BOUND`, `read_only_strategy` on strategies;
|
|
26
|
+
`can_contain`, `read`, `delete` in a type's access policy — facts about the
|
|
27
|
+
type, read by the layer that owns the concern (the executor, for the
|
|
28
|
+
strategy examples; the engine, for the policy ones), never invoked by the
|
|
29
|
+
class itself.
|
|
30
|
+
3. **Strategies are the only writes.** Transports get no side paths around
|
|
31
|
+
the executor.
|
|
32
|
+
4. **Kernel services are stateless orchestrators, one concern each**
|
|
33
|
+
(graph engine, access policy, broadcast, persistence), composed by
|
|
34
|
+
constructor injection. Components swap; classes don't subclass. No
|
|
35
|
+
constructor builds a collaborator it was not given — no `param=None`
|
|
36
|
+
replaced by a constructed default, no reach for a process-wide
|
|
37
|
+
singleton. `graphcore/runtime.py` is the one place that wires concrete
|
|
38
|
+
components together; see its docstring.
|
|
39
|
+
5. **One boundary facade (`GraphAPI`); transports are adapters** doing wire
|
|
40
|
+
format and error mapping only. Pull (request/response) goes through the
|
|
41
|
+
facade; push (broadcast) is a separate surface delivered only by
|
|
42
|
+
transports that can push.
|
|
43
|
+
6. **Dependencies point inward**: transport → api → services → domain.
|
|
44
|
+
A service must not import its callers, including their input or result
|
|
45
|
+
types. The service owns its contract; callers depend on that contract.
|
|
46
|
+
`domain/` may depend on shared types and kernel errors, never on its
|
|
47
|
+
consumers.
|
|
48
|
+
(Known exception, to be removed: `Entity.get_entity_type_id()` reads the
|
|
49
|
+
registry.)
|
|
50
|
+
7. **The engine and ports are agnostic of concrete entity types.**
|
|
51
|
+
`EntityService` (the engine) knows only `Entity`. Type-specific behavior
|
|
52
|
+
reaches it through a port — an interface whose contract names no concrete
|
|
53
|
+
entity type (access, persistence, broadcast, scheduling, authentication)
|
|
54
|
+
— or through declarative metadata on the type. The kernel ships kernel
|
|
55
|
+
entity types (`User`, `Group`, `Grant`,
|
|
56
|
+
`Deployment`, `StrategyRequest`); adapters and kernel
|
|
57
|
+
services that depend on one document that dependence. An application
|
|
58
|
+
extends a kernel type by subclassing it, which is required to get the
|
|
59
|
+
behavior adapters give that type; an application that needs different
|
|
60
|
+
behavior without subclassing writes its own adapter for that port.
|
|
61
|
+
Replacing an adapter must not require changing the engine.
|
|
62
|
+
8. **Prefer declarative state and reconciliation, with entities as the
|
|
63
|
+
source of truth.** When any part of the system must follow entity state
|
|
64
|
+
(infrastructure, derived stores, external mirrors), the entity declares
|
|
65
|
+
the desired state and that part reconciles toward it, both on committed
|
|
66
|
+
changes and by periodically re-reading the full entity state, so a
|
|
67
|
+
missed change converges. Where reconciliation lives (an adapter, a
|
|
68
|
+
service, a task) is decided per case. What holds everywhere:
|
|
69
|
+
- changing desired state is one ordinary write to the entity;
|
|
70
|
+
- the follower never writes its status back onto entities;
|
|
71
|
+
- a failure to reconcile never fails the write that caused it;
|
|
72
|
+
- consumers tolerate lag by checking entity state at the point of use.
|
|
73
|
+
|
|
74
|
+
Exceptions: authorization and persistence are on the write path and are
|
|
75
|
+
synchronous; side effects that must happen exactly once are not
|
|
76
|
+
reconciled state. Scheduling is an example (`docs/SCHEDULING_TDD.md` in
|
|
77
|
+
the monorepo).
|
|
78
|
+
|
|
79
|
+
Type-to-infrastructure bindings (storage models/adapters, views, strategies)
|
|
80
|
+
live in the **registry**, not on the domain class — registry binding, not
|
|
81
|
+
dependency injection: the class is the lookup key, never a consumer of the
|
|
82
|
+
bound value.
|
|
83
|
+
|
|
84
|
+
## Shared types
|
|
85
|
+
|
|
86
|
+
Shared input and result types live in `graphcore/types/`, organized by
|
|
87
|
+
concern. They must not depend on APIs, services, or infrastructure.
|
|
88
|
+
Component-specific types stay with their owning component.
|
|
89
|
+
|
|
90
|
+
## Package map
|
|
91
|
+
|
|
92
|
+
```
|
|
93
|
+
graphcore/
|
|
94
|
+
public/ # app-author import surface (re-exports from domain/)
|
|
95
|
+
api/ # boundary facade: GraphAPI and payload conversion
|
|
96
|
+
types/ # shared input and result types, organized by concern
|
|
97
|
+
domain/ # entity/ and strategy/ implementations
|
|
98
|
+
registry/ # binding layer: type directories, discovery, decorators
|
|
99
|
+
# (see registry/README.md for the startup lifecycle)
|
|
100
|
+
graph/ # the entity-graph engine (EntityService orchestrates
|
|
101
|
+
# persistence and broadcast, and calls the access port)
|
|
102
|
+
persistence/ # the storage seam: EntityRepository contract, with the
|
|
103
|
+
# Django implementation (column split, compiler) under
|
|
104
|
+
# persistence/django
|
|
105
|
+
execution/ # strategy executor, dispatchers, Celery tasks
|
|
106
|
+
scheduling/ # the Scheduler port and its default adapter
|
|
107
|
+
auth/ # authentication: verify token, map (iss, sub) → Principal
|
|
108
|
+
transport/ # HTTP/WS adapters, routing, urls
|
|
109
|
+
errors.py # KernelError hierarchy (transports map these to the wire)
|
|
110
|
+
docs/ # doc topics + discovery (and this file)
|
|
111
|
+
runtime.py # composition root: Runtime, build_runtime, django_runtime,
|
|
112
|
+
# get_runtime — the only module naming concrete
|
|
113
|
+
# infrastructure or reading GRAPHCORE_* settings;
|
|
114
|
+
# called only from process entrypoints
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Root keeps only framework contracts (`apps.py`, `models.py`, `migrations/`,
|
|
118
|
+
`celery.py`, `urls.py` re-export, `test_settings.py`).
|
|
119
|
+
|
|
120
|
+
Planned extractions (created when their component lands): `access/` (ACL
|
|
121
|
+
policy + group resolution out of the graph engine), `broadcast/` (event
|
|
122
|
+
fan-out out of the graph engine).
|
|
123
|
+
|
|
124
|
+
## Conventions
|
|
125
|
+
|
|
126
|
+
- **`to_dict()` is full-fidelity; `to_client()` is the wire boundary; there
|
|
127
|
+
is no third representation.** `to_dict()` is the complete,
|
|
128
|
+
JSON-compatible, round-trippable state — system fields, typed subclass
|
|
129
|
+
fields, the attribute bag nested under `attributes` — and never the derived
|
|
130
|
+
projections (`children_ids`, `parent_ids`, `ancestor_ids`, `reference_ids`). `from_dict`
|
|
131
|
+
is its classmethod inverse. `to_client()` defaults to `to_dict()` plus
|
|
132
|
+
those four projections and is what every consumer (frontend, agent
|
|
133
|
+
context, CLI, MCP, other backends) is read through; override it per-type
|
|
134
|
+
to drop fields that shouldn't reach a client (e.g. auth correlation keys)
|
|
135
|
+
or trim heavy payloads (e.g. an audio entity's chunk data). Storage *is*
|
|
136
|
+
`to_dict()`/`from_dict()` too: the Django repository maps typed fields and the nested `attributes` bag directly to their columns using the bound model's `_meta` —
|
|
137
|
+
there is no mapper and no separate record type.
|
|
138
|
+
- **Reads tombstone, writes raise.** Absence and denial on reads resolve to
|
|
139
|
+
a `Tombstone(cause)` so a failed hop never breaks a surrounding render;
|
|
140
|
+
write failures raise typed `KernelError`s that adapters map mechanically.
|
|
141
|
+
- **`Principal`, never a raw user id or token**, is who is calling; it is
|
|
142
|
+
produced by a pluggable authenticator at the boundary.
|
|
143
|
+
- **Two authoring tiers per entity type.** The *attribute path*: generic base
|
|
144
|
+
strategies (set/remove attributes, generic create) over the schemaless
|
|
145
|
+
`attributes` dict — a fully functional app with zero new code, at the cost
|
|
146
|
+
of no type enforcement. The *typed path*: an entity subclass with class
|
|
147
|
+
fields and its own storage model — the generic attribute strategies cannot
|
|
148
|
+
touch class fields, so a typed entity's invariants are only reachable
|
|
149
|
+
through strategies it declares. Graduating a type is how you buy
|
|
150
|
+
enforcement; kernel-sensitive types (e.g. `Grant`) use the typed
|
|
151
|
+
path for exactly this property. (When to graduate, and what the migration
|
|
152
|
+
looks like, still needs design work.)
|