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,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
|