graphcore-kernel 0.2.3__py3-none-any.whl → 0.2.5__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (151) hide show
  1. graphcore/agent_frontend/api.py +9 -3
  2. graphcore/agent_frontend/base/views.py +9 -16
  3. graphcore/agent_frontend/changes.py +77 -0
  4. graphcore/agent_frontend/client.py +3 -1
  5. graphcore/agent_frontend/context.py +52 -12
  6. graphcore/agent_frontend/loading.py +7 -0
  7. graphcore/agent_frontend/mcp_server.py +80 -0
  8. graphcore/agent_frontend/render.py +32 -17
  9. graphcore/agent_frontend/server.py +14 -71
  10. graphcore/agent_frontend/signatures.py +5 -2
  11. graphcore/agent_frontend/testing.py +2 -12
  12. graphcore/agent_frontend/tests/fakes.py +30 -11
  13. graphcore/agent_frontend/tests/test_frontend.py +300 -88
  14. graphcore/agent_frontend/tests/test_mcp_contract.py +147 -0
  15. graphcore/agent_frontend/tests/test_server.py +23 -9
  16. graphcore/agent_frontend/tools.py +38 -15
  17. graphcore/api/graph_api.py +30 -1
  18. graphcore/api/predicate_codec.py +14 -2
  19. graphcore/api/tests/test_get_by_key.py +39 -0
  20. graphcore/api/tests/test_graph_api.py +34 -0
  21. graphcore/api/tests/test_predicate_codec.py +17 -1
  22. graphcore/apps.py +5 -0
  23. graphcore/auth/authn/README.md +16 -3
  24. graphcore/auth/authn/authenticator.py +41 -11
  25. graphcore/auth/authn/service_accounts.py +2 -0
  26. graphcore/auth/authn/tests/test_authenticator.py +153 -15
  27. graphcore/auth/authn/tests/test_onboarding.py +9 -5
  28. graphcore/auth/authz/defaults.py +1 -1
  29. graphcore/auth/authz/kernel_policy.py +9 -6
  30. graphcore/auth/authz/policy.py +39 -26
  31. graphcore/auth/authz/tests/test_can_contain.py +45 -0
  32. graphcore/auth/authz/tests/test_creation.py +28 -25
  33. graphcore/auth/authz/tests/test_kernel_policy.py +5 -2
  34. graphcore/auth/authz/tests/test_lockout.py +1 -1
  35. graphcore/auth/authz/tests/test_policy.py +38 -21
  36. graphcore/bootstrap/deployment.py +13 -34
  37. graphcore/bootstrap/manifests.py +10 -0
  38. graphcore/bootstrap/tests/test_deployment_seed.py +43 -16
  39. graphcore/docs/AGENT_FRONTEND_TDD.md +100 -21
  40. graphcore/docs/AUTHORIZATION_TECHNICAL_TDD.md +70 -55
  41. graphcore/docs/ENTITY_REFERENCE_TDD.md +8 -3
  42. graphcore/docs/MANIFEST_TDD.md +603 -0
  43. graphcore/docs/SCHEDULING_TDD.md +4 -3
  44. graphcore/docs/STRATEGY_EXECUTION_TDD.md +500 -122
  45. graphcore/docs/VIEW_ENTITY_TDD.md +2 -1
  46. graphcore/docs/VIEW_SYSTEM_TDD.md +14 -0
  47. graphcore/docs/doc_topics.py +5 -0
  48. graphcore/domain/entity/Entity.py +147 -12
  49. graphcore/domain/entity/deployment/Deployment.py +2 -10
  50. graphcore/domain/entity/grant/Grant.py +2 -10
  51. graphcore/domain/entity/group/Group.py +3 -23
  52. graphcore/domain/entity/group/README.md +7 -5
  53. graphcore/domain/entity/invite/Invite.py +5 -16
  54. graphcore/domain/entity/request_template/RequestTemplate.py +6 -19
  55. graphcore/domain/entity/service_account/ServiceAccount.py +8 -13
  56. graphcore/domain/entity/strategy_request/StrategyRequest.py +14 -35
  57. graphcore/domain/entity/tests/test_declared_fields.py +190 -0
  58. graphcore/domain/entity/tests/test_display_name.py +67 -0
  59. graphcore/domain/entity/tests/test_key_field.py +116 -0
  60. graphcore/domain/entity/user/User.py +8 -13
  61. graphcore/domain/entity/view/View.py +7 -22
  62. graphcore/domain/strategy/BaseStrategy.py +34 -130
  63. graphcore/domain/strategy/GroupStrategies.py +4 -7
  64. graphcore/domain/strategy/InviteStrategies.py +2 -2
  65. graphcore/domain/strategy/runner.py +3 -1
  66. graphcore/domain/strategy/session.py +136 -16
  67. graphcore/domain/strategy/tests/test_BaseStrategies.py +18 -1
  68. graphcore/domain/strategy/tests/test_runner.py +15 -18
  69. graphcore/domain/strategy/tests/test_strategy_locks.py +63 -418
  70. graphcore/errors.py +16 -1
  71. graphcore/execution/README.md +46 -21
  72. graphcore/execution/StrategyExecutorService.py +94 -29
  73. graphcore/execution/environments/attempt.py +80 -0
  74. graphcore/execution/environments/celery.py +7 -14
  75. graphcore/execution/environments/in_process.py +3 -21
  76. graphcore/execution/local_session.py +70 -54
  77. graphcore/execution/requests.py +5 -3
  78. graphcore/execution/strategy_context.py +28 -0
  79. graphcore/execution/tests/contract.py +125 -8
  80. graphcore/execution/tests/support.py +79 -3
  81. graphcore/execution/tests/test_dispatchers.py +2 -1
  82. graphcore/execution/tests/test_executor.py +189 -16
  83. graphcore/execution/tests/test_local_session.py +80 -2
  84. graphcore/execution/tests/test_locks.py +75 -0
  85. graphcore/graph/EntityService.py +117 -5
  86. graphcore/graph/tests/test_declared_freeze.py +228 -0
  87. graphcore/management/commands/graphcore_manifest_apply.py +22 -0
  88. graphcore/management/tests/test_manifest_apply.py +31 -0
  89. graphcore/manifest/__init__.py +0 -0
  90. graphcore/manifest/apply.py +181 -0
  91. graphcore/manifest/codec.py +96 -0
  92. graphcore/manifest/configure.py +45 -0
  93. graphcore/manifest/manifest.py +120 -0
  94. graphcore/manifest/record.py +60 -0
  95. graphcore/manifest/registry.py +137 -0
  96. graphcore/manifest/tests/__init__.py +0 -0
  97. graphcore/manifest/tests/test_apply.py +355 -0
  98. graphcore/manifest/tests/test_manifest.py +306 -0
  99. graphcore/manifest/tests/test_record.py +58 -0
  100. graphcore/migrations/0003_entity_key.py +35 -0
  101. graphcore/persistence/ENTITY_REPOSITORY_TECHNICAL_TDD.md +3 -1
  102. graphcore/persistence/django/compiler.py +12 -1
  103. graphcore/persistence/django/models.py +8 -6
  104. graphcore/persistence/django/repository.py +21 -2
  105. graphcore/persistence/django/tests/test_compiler.py +20 -1
  106. graphcore/persistence/django/tests/test_migration_entity_key.py +29 -0
  107. graphcore/persistence/django/tests/test_repository.py +12 -2
  108. graphcore/persistence/repository.py +11 -1
  109. graphcore/persistence/tests/contract.py +33 -1
  110. graphcore/persistence/tests/evaluate.py +15 -1
  111. graphcore/persistence/tests/memory.py +7 -0
  112. graphcore/persistence/tests/test_query_types.py +15 -1
  113. graphcore/public/__init__.py +1 -0
  114. graphcore/public/agent_frontend.py +24 -0
  115. graphcore/public/entities/__init__.py +2 -0
  116. graphcore/public/errors.py +2 -2
  117. graphcore/public/execution.py +23 -0
  118. graphcore/public/manifests.py +34 -0
  119. graphcore/public/persistence/__init__.py +2 -1
  120. graphcore/public/strategies/__init__.py +2 -1
  121. graphcore/registry/README.md +19 -11
  122. graphcore/registry/StrategyDirectory.py +5 -1
  123. graphcore/registry/discovery.py +6 -0
  124. graphcore/registry/registry.py +7 -2
  125. graphcore/registry/tests/test_app_config.py +9 -0
  126. graphcore/runtime.py +6 -2
  127. graphcore/scheduling/beat_scheduler.py +1 -1
  128. graphcore/scheduling/tests/test_beat_scheduler.py +12 -1
  129. graphcore/testing/case.py +5 -6
  130. graphcore/testing/tests/test_case_and_runner.py +8 -2
  131. graphcore/tests/memory_runtime.py +21 -0
  132. graphcore/tests/public_api_manifest.py +11 -4
  133. graphcore/tests/test_composition_boundaries.py +4 -1
  134. graphcore/transport/agent_asgi.py +3 -4
  135. graphcore/transport/agent_client.py +20 -1
  136. graphcore/transport/consumers.py +33 -17
  137. graphcore/transport/tests/test_api_views.py +26 -2
  138. graphcore/transport/tests/test_consumers.py +58 -0
  139. graphcore/transport/tests/test_in_process_mcp.py +83 -0
  140. graphcore/transport/views.py +27 -2
  141. graphcore/types/execution.py +6 -2
  142. graphcore/types/keys.py +25 -0
  143. graphcore/types/query.py +30 -2
  144. graphcore/types/strategy.py +12 -0
  145. {graphcore_kernel-0.2.3.dist-info → graphcore_kernel-0.2.5.dist-info}/METADATA +1 -1
  146. {graphcore_kernel-0.2.3.dist-info → graphcore_kernel-0.2.5.dist-info}/RECORD +151 -118
  147. {graphcore_kernel-0.2.3.dist-info → graphcore_kernel-0.2.5.dist-info}/WHEEL +0 -0
  148. {graphcore_kernel-0.2.3.dist-info → graphcore_kernel-0.2.5.dist-info}/entry_points.txt +0 -0
  149. {graphcore_kernel-0.2.3.dist-info → graphcore_kernel-0.2.5.dist-info}/licenses/LICENSE +0 -0
  150. {graphcore_kernel-0.2.3.dist-info → graphcore_kernel-0.2.5.dist-info}/licenses/NOTICE +0 -0
  151. {graphcore_kernel-0.2.3.dist-info → graphcore_kernel-0.2.5.dist-info}/top_level.txt +0 -0
@@ -21,6 +21,7 @@ class ToolSpec:
21
21
  schema: Optional[dict] = None
22
22
  fn: Optional[Callable] = None
23
23
  from_shell: bool = False
24
+ read_only: bool = False
24
25
 
25
26
 
26
27
  def strategy_tool(
@@ -45,11 +46,16 @@ class Image:
45
46
  media_type: str
46
47
 
47
48
 
48
- def operation(name: str, description: str, schema: dict) -> Callable[[Callable], ToolSpec]:
49
+ def operation(
50
+ name: str, description: str, schema: dict, read_only: bool = False,
51
+ ) -> Callable[[Callable], ToolSpec]:
49
52
  """A view tool that is code: `async def fn(ctx, **params)`. It returns JSON values, an
50
- `Image`, or a list mixing the two."""
53
+ `Image`, or a list mixing the two. A `read_only` operation writes nothing, so `call`
54
+ reports no change for it."""
51
55
  def wrap(fn: Callable) -> ToolSpec:
52
- return ToolSpec(name=name, description=description, schema=schema, fn=fn, takes_target=False)
56
+ return ToolSpec(
57
+ name=name, description=description, schema=schema, fn=fn, takes_target=False, read_only=read_only,
58
+ )
53
59
  return wrap
54
60
 
55
61
 
@@ -1,4 +1,4 @@
1
- """The base agent views: `home` at `/`, `entity` at `/e/{entity}`, and `view`, the default for view entities."""
1
+ """The base agent views: `home` at `/`, `entity` at an entity id, and `view`, the default for view entities."""
2
2
  from __future__ import annotations
3
3
 
4
4
  import json
@@ -6,32 +6,25 @@ from collections import defaultdict
6
6
  from typing import Any, Optional
7
7
 
8
8
  from graphcore.agent_frontend import AgentView, Context, ToolSpec, agent_view, strategy_tool
9
+ from graphcore.agent_frontend.context import MAX_FIELD_CHARS, STRUCTURAL_KEYS, clip
9
10
 
10
- # The base entity's own keys, rendered under `## Entity`; every other key is a field.
11
- STRUCTURAL_KEYS = ('entity_id', 'entity_type_id', 'owner', 'parent_id', 'sibling_position', 'version')
12
- MAX_FIELD_CHARS = 2000
13
11
  VIEW_TYPE = 'graphcore.View'
14
- _ENTITY_ID_PREFIX = 'gc://'
15
12
 
16
13
 
17
- def _value(ctx: Context, value: Any) -> str:
18
- """One line: strings bare unless empty or multi-line, everything else as JSON; an entity
19
- id gains its address, and a long value is cut with its full length."""
14
+ def _value(value: Any) -> str:
15
+ """One line: strings bare unless empty or multi-line, everything else as JSON; a long value
16
+ is cut with its full length."""
20
17
  if isinstance(value, str) and value and '\n' not in value:
21
18
  text = value
22
19
  else:
23
20
  text = json.dumps(value, default=str, ensure_ascii=False)
24
- if len(text) > MAX_FIELD_CHARS:
25
- return f"{text[:MAX_FIELD_CHARS]}… (truncated; {len(text)} characters)"
26
- if isinstance(value, str) and value.startswith(_ENTITY_ID_PREFIX):
27
- return f"{text} · {ctx.place(value).address}"
28
- return text
21
+ return clip(text) if len(text) > MAX_FIELD_CHARS else text
29
22
 
30
23
 
31
24
  def entity_fields(ctx: Context, entity: Any) -> list[str]:
32
25
  """`key: value` for every key of the entity that is not structural."""
33
26
  return [
34
- f"{key}: {_value(ctx, value)}"
27
+ f"{key}: {_value(value)}"
35
28
  for key, value in entity.to_dict().items() if key not in STRUCTURAL_KEYS
36
29
  ]
37
30
 
@@ -59,7 +52,7 @@ async def _parent(ctx: Context, parent_id: Optional[str]) -> str:
59
52
  return f"{parent_id} (not readable)"
60
53
  data = parent.to_dict()
61
54
  label = next((str(data[k]) for k in ('name', 'title', 'slug') if data.get(k)), parent_id)
62
- return f"{label} · {parent.entity_type_id} · {ctx.place(parent_id).address}"
55
+ return f"{label} · {parent.entity_type_id} · {parent_id}"
63
56
 
64
57
 
65
58
  async def children_section(ctx: Context, entity: Any, limit: int = 50) -> list:
@@ -154,7 +147,7 @@ async def view_view(ctx: Context, view: Any) -> list:
154
147
  return [note, *await entity_view(ctx, view)]
155
148
  if data.get('renders') and target is None:
156
149
  return [f"This view renders {data['renders']}, which does not exist or is not readable."]
157
- shows = ctx.place(data['renders']).address if target is not None else 'no entity'
150
+ shows = data['renders'] if target is not None else 'no entity'
158
151
  body = await (component.fn(ctx, target) if target is not None else component.fn(ctx))
159
152
  return [
160
153
  f"View `{component.name}` of {shows} · view entity {view.entity_id}",
@@ -0,0 +1,77 @@
1
+ """What a write changed, among the entities a place's render read."""
2
+ from __future__ import annotations
3
+
4
+ import json
5
+ from typing import Any
6
+
7
+ from graphcore.agent_frontend.client import GraphClient
8
+ from graphcore.agent_frontend.context import MAX_FIELD_CHARS, STRUCTURAL_KEYS, Reads, clip
9
+ from graphcore.types.entities import Tombstone
10
+ from graphcore.types.identity import Principal
11
+
12
+ _HIDDEN = frozenset(STRUCTURAL_KEYS) - {'version'}
13
+
14
+
15
+ def snapshot(reads: Reads) -> dict[str, dict]:
16
+ """Each readable entity's `to_dict()`, taken before a write: a client may hand back
17
+ the same object the write then changes."""
18
+ return {entity_id: entity.to_dict() for entity_id, entity in reads.cache.items()}
19
+
20
+
21
+ def _value(value: Any) -> Any:
22
+ text = value if isinstance(value, str) else json.dumps(value, default=str, ensure_ascii=False)
23
+ return clip(text) if len(text) > MAX_FIELD_CHARS else value
24
+
25
+
26
+ def _keys(before: dict, after: dict) -> list:
27
+ return [*after, *(key for key in before if key not in after)]
28
+
29
+
30
+ def changed_fields(before: dict, after: dict) -> dict:
31
+ """The new value of every non-structural key that differs, `version` included; a key
32
+ whose value is a dict on both sides, such as `attributes`, by its own keys."""
33
+ out: dict[str, Any] = {}
34
+ for key in _keys(before, after):
35
+ old, new = before.get(key), after.get(key)
36
+ if key in _HIDDEN or old == new:
37
+ continue
38
+ if isinstance(old, dict) and isinstance(new, dict):
39
+ out.update({
40
+ f"{key}.{sub}": _value(new.get(sub))
41
+ for sub in _keys(old, new) if old.get(sub) != new.get(sub)
42
+ })
43
+ else:
44
+ out[key] = _value(new)
45
+ return out
46
+
47
+
48
+ async def diff(
49
+ client: GraphClient, principal: Principal, before: Reads, snapshots: dict[str, dict], after: Reads,
50
+ ) -> dict:
51
+ """`changed`, `created` and `deleted`, each keyed by entity id and left out when empty.
52
+ An entity the place read before and no longer reads is fetched again, to tell one that
53
+ is gone from one the place stopped showing."""
54
+ changed: dict[str, dict] = {}
55
+ deleted: dict[str, dict] = {}
56
+ for entity_id, old in snapshots.items():
57
+ new = after.cache.get(entity_id)
58
+ if new is None and entity_id not in after.seen:
59
+ fetched = await client.get_entity(principal, entity_id)
60
+ new = None if isinstance(fetched, Tombstone) else fetched
61
+ if new is None:
62
+ deleted[entity_id] = {'entity_type_id': old.get('entity_type_id')}
63
+ elif f"v{new.version}" != before.seen.get(entity_id):
64
+ changed[entity_id] = changed_fields(old, new.to_dict())
65
+ created = {
66
+ entity_id: {'entity_type_id': entity.entity_type_id}
67
+ for entity_id, entity in after.cache.items() if entity_id not in snapshots
68
+ }
69
+ return {
70
+ key: value for key, value in (('changed', changed), ('created', created), ('deleted', deleted))
71
+ if value
72
+ }
73
+
74
+
75
+ def note(tool: str, changes: dict) -> str:
76
+ counts = [f"{len(changes[key])} {key}" for key in ('changed', 'created', 'deleted') if key in changes]
77
+ return f"ran {tool}; {', '.join(counts)}" if counts else f"ran {tool}; nothing this place shows changed"
@@ -31,4 +31,6 @@ class GraphClient(Protocol):
31
31
  def entity_types(self) -> list[str]: ...
32
32
  def type_strategies(self, entity_type_id: str) -> list[dict]: ...
33
33
  def deployment_strategies(self) -> list[dict]: ...
34
- def strategy_info(self) -> dict[str, dict]: ...
34
+ def strategy_info(self) -> dict[str, dict]:
35
+ """Every registered strategy by name: its `serialize()`, with `read_only`."""
36
+ ...
@@ -9,28 +9,63 @@ from graphcore.agent_frontend.client import GraphClient
9
9
  from graphcore.agent_frontend.errors import AgentError
10
10
  from graphcore.agent_frontend.registry import AgentRegistry
11
11
  from graphcore.types.entities import Tombstone
12
+ from graphcore.types.entity_id import ENTITY_ID_RE, is_entity_id
12
13
  from graphcore.types.identity import Principal
13
14
  from graphcore.types.query import Predicate
14
15
 
15
16
  ID_PREFIX = 'gc://'
16
17
  DEFAULT_QUERY_MAX = 1000
17
18
  _QUERY_PAGE = 100
19
+ # The base entity's own keys; every other key of `to_dict()` is a field.
20
+ STRUCTURAL_KEYS = ('entity_id', 'entity_type_id', 'owner', 'parent_id', 'sibling_position', 'version')
21
+ MAX_FIELD_CHARS = 2000
18
22
 
19
23
 
20
- def entity_address(entity_id: str) -> str:
21
- return '/e/' + entity_id.removeprefix(ID_PREFIX)
24
+ def clip(text: str) -> str:
25
+ """`text`, cut at `MAX_FIELD_CHARS` with its full length when it is longer."""
26
+ if len(text) <= MAX_FIELD_CHARS:
27
+ return text
28
+ return f"{text[:MAX_FIELD_CHARS]}… (truncated; {len(text)} characters)"
29
+
30
+
31
+ def to_route(address: str) -> str:
32
+ """The route table's form of an address an agent writes: an entity id as `/e/<backend>/<local>`,
33
+ an id inside a path as its two segments. Route-form addresses pass through unchanged."""
34
+ if is_entity_id(address):
35
+ return '/e/' + address.removeprefix(ID_PREFIX)
36
+ return ENTITY_ID_RE.sub(lambda match: f"{match.group(1)}/{match.group(2)}", address)
37
+
38
+
39
+ def to_agent(route: str, entity_id: Optional[str]) -> str:
40
+ """The agent's form of a route that resolved to `entity_id`: `/e/<backend>/<local>` is the id
41
+ itself, and in any other route the id's two segments are the id."""
42
+ if entity_id is None:
43
+ return route
44
+ pair = entity_id.removeprefix(ID_PREFIX).split('/')
45
+ parts = [part for part in route.split('/') if part]
46
+ if parts == ['e', *pair]:
47
+ return entity_id
48
+ for i in range(len(parts) - 1):
49
+ if parts[i:i + 2] == pair:
50
+ return '/' + '/'.join([*parts[:i], entity_id, *parts[i + 2:]])
51
+ return route
22
52
 
23
53
 
24
54
  def to_address(target: str) -> str:
25
- return entity_address(target) if target.startswith(ID_PREFIX) else target
55
+ """`target` in the agent's form, as far as it can be told without the route table: an
56
+ entity id is itself, and so is its `/e/` route."""
57
+ parts = [part for part in to_route(target).split('/') if part]
58
+ if len(parts) == 3 and parts[0] == 'e' and is_entity_id(f"{ID_PREFIX}{parts[1]}/{parts[2]}"):
59
+ return f"{ID_PREFIX}{parts[1]}/{parts[2]}"
60
+ return target
61
+
62
+
63
+ def normalized(route: str) -> str:
64
+ return '/' + route.strip('/') if route.strip('/') else '/'
26
65
 
27
66
 
28
67
  def label_of(entity: Any) -> str:
29
- data = entity.to_dict()
30
- for key in ('name', 'title', 'slug'):
31
- if data.get(key):
32
- return str(data[key])
33
- return entity.entity_id
68
+ return entity.display_name or entity.entity_id
34
69
 
35
70
 
36
71
  @dataclass(frozen=True)
@@ -132,8 +167,8 @@ class Context:
132
167
 
133
168
  def web_url(self, target: str) -> Optional[str]:
134
169
  """The web app's URL for an address or entity id: `GRAPHCORE_WEB_URL` plus its
135
- address, or None when the deployment sets no web URL."""
136
- return self._web_base + to_address(target) if self._web_base else None
170
+ route, or None when the deployment sets no web URL."""
171
+ return self._web_base + normalized(to_route(target)) if self._web_base else None
137
172
 
138
173
  def view(self, name: str) -> Optional[AgentView]:
139
174
  """The agent view registered as `name`: an app's, else the base one."""
@@ -154,10 +189,15 @@ class Context:
154
189
  async def execute(
155
190
  self, strategy: str, target: Optional[str] = None, params: Optional[dict] = None,
156
191
  ) -> dict:
192
+ return (await self.run(strategy, target, params)).get('ret_val') or {}
193
+
194
+ async def run(self, strategy: str, target: Optional[str] = None, params: Optional[dict] = None) -> dict:
195
+ """The strategy's whole outcome; `execute` is its `ret_val`."""
157
196
  outcome = await self._client.execute(self.principal, strategy, target, params or {})
158
197
  if outcome.get('status') == 'failed':
159
- raise AgentError('Refused', f"{strategy}: {outcome.get('error')}")
160
- return outcome.get('ret_val') or {}
198
+ request = outcome.get('strategy_request_id')
199
+ raise AgentError('Refused', f"{strategy}: {outcome.get('error')}" + (f" (request {request})" if request else ''))
200
+ return outcome
161
201
 
162
202
  def place(self, target: str, full: bool = False) -> Placement:
163
203
  return Placement(to_address(target), full)
@@ -3,6 +3,7 @@ from __future__ import annotations
3
3
 
4
4
  import importlib
5
5
  import pkgutil
6
+ from functools import lru_cache
6
7
  from types import ModuleType
7
8
  from typing import Iterable
8
9
 
@@ -52,3 +53,9 @@ def load_registry(modules: Iterable[str], base: str = BASE_VIEWS) -> AgentRegist
52
53
  for view in views_in(importlib.import_module(module)):
53
54
  registry.add(view)
54
55
  return registry
56
+
57
+
58
+ @lru_cache
59
+ def cached_registry(modules: tuple[str, ...]) -> AgentRegistry:
60
+ # Loading imports the app modules, and they stay in `sys.modules`.
61
+ return load_registry(modules)
@@ -0,0 +1,80 @@
1
+ """The MCP server: four fixed tools over a `Frontend`, whichever transport reaches it.
2
+ It holds the protocol's tool definitions and instructions, and nothing about a transport."""
3
+ from __future__ import annotations
4
+
5
+ import base64
6
+ from typing import Annotated, Any, Callable, Optional
7
+
8
+ from mcp.server.mcpserver import Context, MCPServer
9
+ from mcp.server.mcpserver.exceptions import ToolError
10
+ from mcp_types import CallToolResult, ImageContent, TextContent
11
+
12
+ from graphcore.agent_frontend import tools
13
+ from graphcore.agent_frontend.errors import AgentError
14
+ from graphcore.agent_frontend.render import Frontend
15
+ from graphcore.types.identity import Principal
16
+
17
+ INSTRUCTIONS = """\
18
+ This server presents a GraphCore deployment as addressed places. Start with open("/").
19
+ Every place is a Markdown page: its content, its address, a version, and a Tools list.
20
+ - open(at): read a place. Addresses look like /, /notes, or an entity id gc://<backend>/<local>,
21
+ which is the address of that entity's place. A route with an entity in it holds its full id:
22
+ /notes/gc://<backend>/<local>/history.
23
+ - call(at, tool, params): run a tool listed under that place's Tools. Pass seen_version
24
+ (the version you last read) so a write based on out-of-date content is refused.
25
+ - find(type, predicate): list entities of a type, optionally filtered by field equality.
26
+ - act(strategy, target, params): run a strategy directly when no place lists it as a tool.
27
+ Reads and writes run as the user you connected as.
28
+ """
29
+ WEB_INSTRUCTIONS = """\
30
+ A place's `web:` link opens the same place in the web app. To give the user a link,
31
+ use that line, opening the place first if needed; never build one from an address.
32
+ """
33
+
34
+
35
+ def _guard(coro_fn):
36
+ async def run(*args, **kwargs):
37
+ try:
38
+ return await coro_fn(*args, **kwargs)
39
+ except AgentError as exc:
40
+ raise ToolError(f"{exc.code}: {exc.message}")
41
+ return run
42
+
43
+
44
+ def build_server(
45
+ fe: Frontend, principal_of: Callable[[Context], Principal],
46
+ execute_url_of: Callable[[Context], str] = lambda ctx: '',
47
+ ) -> MCPServer:
48
+ """``principal_of`` and ``execute_url_of`` are what a transport supplies for each
49
+ call: who is calling, and the URL a strategy token's requests go to."""
50
+ mcp = MCPServer('graphcore', instructions=INSTRUCTIONS + (WEB_INSTRUCTIONS if fe.web_url else ''))
51
+
52
+ @mcp.tool(description='Read a place. Returns Markdown with its address, version and Tools.')
53
+ async def open(at: str, ctx: Context, version: Optional[str] = None) -> str:
54
+ return await _guard(tools.open_)(fe, principal_of(ctx), at, version)
55
+
56
+ @mcp.tool(description='List entities of a type; predicate maps field to a value or a list of values.')
57
+ async def find(type: str, ctx: Context, predicate: Optional[dict[str, Any]] = None, limit: int = 25) -> str:
58
+ return await _guard(tools.find)(fe, principal_of(ctx), type, predicate, limit)
59
+
60
+ @mcp.tool(description="Run a tool listed at a place. Pass seen_version to refuse the write if the place changed.")
61
+ async def call(
62
+ at: str, tool: str, ctx: Context, params: Optional[dict[str, Any]] = None,
63
+ seen_version: Optional[str] = None,
64
+ ) -> Annotated[CallToolResult, str]:
65
+ # Annotated with `str` so the output schema and structured content stay what a `-> str` tool's are.
66
+ out = await _guard(tools.call)(fe, principal_of(ctx), at, tool, params, seen_version, execute_url_of(ctx))
67
+ return CallToolResult(
68
+ content=[
69
+ TextContent(type='text', text=out.text),
70
+ *(ImageContent(type='image', data=base64.b64encode(i.data).decode(), mime_type=i.media_type)
71
+ for i in out.images),
72
+ ],
73
+ structured_content={'result': out.text},
74
+ )
75
+
76
+ @mcp.tool(description='Run a strategy by name, optionally on a target address or entity id.')
77
+ async def act(strategy: str, ctx: Context, target: Optional[str] = None, params: Optional[dict[str, Any]] = None) -> str:
78
+ return await _guard(tools.act)(fe, principal_of(ctx), strategy, target, params)
79
+
80
+ return mcp
@@ -7,7 +7,9 @@ from typing import Any, Optional
7
7
  from graphcore.agent_frontend import signatures
8
8
  from graphcore.agent_frontend.api import AgentView, ToolSpec
9
9
  from graphcore.agent_frontend.client import GraphClient
10
- from graphcore.agent_frontend.context import DEFAULT_QUERY_MAX, Context, Placement, Reads, label_of
10
+ from graphcore.agent_frontend.context import (
11
+ DEFAULT_QUERY_MAX, Context, Placement, Reads, label_of, normalized, to_agent, to_route,
12
+ )
11
13
  from graphcore.agent_frontend.errors import AgentError, RenderTooLarge
12
14
  from graphcore.agent_frontend.registry import AgentRegistry
13
15
  from graphcore.errors import NotFound
@@ -36,11 +38,13 @@ class ResolvedTool:
36
38
  description: Optional[str]
37
39
  schema: dict
38
40
  spec: ToolSpec
41
+ read_only: bool = False
39
42
 
40
43
  @property
41
44
  def signature(self) -> str:
42
45
  return signatures.signature(
43
46
  self.name, self.schema, self.description, target_param=self.takes_target,
47
+ read_only=self.read_only,
44
48
  )
45
49
 
46
50
  @property
@@ -63,6 +67,7 @@ class Rendered:
63
67
  version: str
64
68
  tools: list[ResolvedTool]
65
69
  entity: Any
70
+ reads: Reads
66
71
 
67
72
 
68
73
  @dataclass
@@ -71,6 +76,8 @@ class _Body:
71
76
  text: str
72
77
  tools: list[ResolvedTool]
73
78
  entity: Any
79
+ address: str
80
+ route: str
74
81
 
75
82
 
76
83
  def _one_line(description: Optional[str]) -> Optional[str]:
@@ -107,7 +114,7 @@ async def _tools(fe: Frontend, ctx: Context, view: AgentView, entity: Any) -> li
107
114
  resolved: dict[str, ResolvedTool] = {}
108
115
  for spec in specs:
109
116
  if spec.fn is not None:
110
- tool = ResolvedTool(spec.name, spec.description, spec.schema or {}, spec)
117
+ tool = ResolvedTool(spec.name, spec.description, spec.schema or {}, spec, spec.read_only)
111
118
  else:
112
119
  if spec.strategy not in info:
113
120
  continue
@@ -125,16 +132,26 @@ async def _tools(fe: Frontend, ctx: Context, view: AgentView, entity: Any) -> li
125
132
  schema = {'type': 'object', 'properties': {}}
126
133
  else:
127
134
  description, schema = strategy.get('description'), strategy.get('schema') or {}
128
- tool = ResolvedTool(spec.name, spec.description or _one_line(description), schema, spec)
135
+ tool = ResolvedTool(
136
+ spec.name, spec.description or _one_line(description), schema, spec,
137
+ bool(strategy.get('read_only')) and not spec.from_shell,
138
+ )
129
139
  resolved.setdefault(tool.name, tool)
130
140
  return list(resolved.values())
131
141
 
132
142
 
133
- async def _label_line(fe: Frontend, ctx: Context, address: str) -> Optional[str]:
143
+ def _resolve(fe: Frontend, address: str) -> tuple[str, str, dict]:
144
+ """`address`, in any form, as its route, as the agent writes it, and resolved."""
145
+ route = normalized(to_route(address))
134
146
  try:
135
- resolved = fe.client.resolve(address)
147
+ resolved = fe.client.resolve(route)
136
148
  except NotFound:
137
149
  raise AgentError('NotFound', f"no route matches {address!r}; start from open('/')")
150
+ return route, to_agent(route, resolved['entity_id']), resolved
151
+
152
+
153
+ async def _label_line(fe: Frontend, ctx: Context, address: str) -> Optional[str]:
154
+ _, address, resolved = _resolve(fe, address)
138
155
  if resolved['entity_id'] is None:
139
156
  return f"- {resolved['view_name']} · {address}"
140
157
  entity = await ctx.get(resolved['entity_id'])
@@ -163,9 +180,9 @@ async def _expand(
163
180
  flush()
164
181
  child = await _render_body(fe, principal, part.address, reads, stack)
165
182
  if child.entity is not None:
166
- heading = f"### {label_of(child.entity)} · {child.entity.entity_type_id} · {part.address}"
183
+ heading = f"### {label_of(child.entity)} · {child.entity.entity_type_id} · {child.address}"
167
184
  else:
168
- heading = f"### {child.title} · {part.address}"
185
+ heading = f"### {child.title} · {child.address}"
169
186
  blocks.append(f"{heading}\n{child.text}")
170
187
  else:
171
188
  flush()
@@ -178,32 +195,30 @@ async def _render_body(
178
195
  fe: Frontend, principal: Principal, address: str, reads: Reads, stack: tuple = (),
179
196
  with_tools: bool = False,
180
197
  ) -> _Body:
181
- if address in stack:
198
+ route, address, resolved = _resolve(fe, address)
199
+ if route in stack:
182
200
  raise RenderTooLarge(address, ': full placements form a cycle')
183
- try:
184
- resolved = fe.client.resolve(address)
185
- except NotFound:
186
- raise AgentError('NotFound', f"no route matches {address!r}; start from open('/')")
187
201
  ctx = Context(principal, address, None, fe.client, reads, fe.registry, fe.query_max, fe.web_url)
188
202
  view, entity = await _choose(fe, ctx, resolved['view_name'], resolved['entity_id'])
189
203
  ctx.entity = entity
190
204
  result = await (view.fn(ctx, entity) if entity is not None else view.fn(ctx))
191
205
  parts = result if isinstance(result, list) else [result]
192
- text = await _expand(fe, principal, ctx, parts, reads, stack + (address,))
206
+ text = await _expand(fe, principal, ctx, parts, reads, stack + (route,))
193
207
  title = (
194
208
  f"{label_of(entity)} · {entity.entity_type_id}" if entity is not None
195
209
  else ('Home' if resolved['view_name'] == 'home' else resolved['view_name'])
196
210
  )
197
211
  tools = await _tools(fe, ctx, view, entity) if with_tools else []
198
- return _Body(title, text, tools, entity)
212
+ return _Body(title, text, tools, entity, address, route)
199
213
 
200
214
 
201
215
  async def render(fe: Frontend, principal: Principal, address: str) -> Rendered:
202
- address = '/' + address.strip('/') if address.strip('/') else '/'
216
+ """The place at `address`: an entity id, a route, or a route with an entity id in it."""
203
217
  reads = Reads()
204
218
  body = await _render_body(fe, principal, address, reads, with_tools=True)
219
+ address = body.address
205
220
  version = reads.version()
206
- web = f"web: {fe.web_url}{address} · " if fe.web_url else ''
221
+ web = f"web: {fe.web_url}{body.route} · " if fe.web_url else ''
207
222
  out = [f"# {body.title}", f"address: {address} · {web}version: {version}"]
208
223
  if body.text:
209
224
  out.append('\n' + body.text)
@@ -212,4 +227,4 @@ async def render(fe: Frontend, principal: Principal, address: str) -> Rendered:
212
227
  text = '\n'.join(out)
213
228
  if len(text) > fe.max_chars:
214
229
  raise RenderTooLarge(address, f" ({len(text)} characters; the limit is {fe.max_chars})")
215
- return Rendered(address, text, version, body.tools, body.entity)
230
+ return Rendered(address, text, version, body.tools, body.entity, reads)
@@ -1,51 +1,23 @@
1
- """The MCP endpoint: four fixed tools over a `Frontend`, stateless, bearer-authenticated."""
1
+ """The MCP server's HTTP transport: stateless Streamable HTTP, bearer-authenticated."""
2
2
  from __future__ import annotations
3
3
 
4
- import base64
5
- from typing import Annotated, Any, Callable, Optional, Sequence
4
+ from typing import Callable, Sequence
6
5
 
7
- from mcp.server.mcpserver import Context, MCPServer
8
- from mcp.server.mcpserver.exceptions import ToolError
6
+ from mcp.server.mcpserver import Context
9
7
  from mcp.server.transport_security import TransportSecuritySettings
10
- from mcp_types import CallToolResult, ImageContent, TextContent
11
8
  from starlette.middleware.cors import CORSMiddleware
12
9
  from starlette.responses import JSONResponse
13
10
 
14
- from graphcore.agent_frontend import tools
15
11
  from graphcore.agent_frontend.client import GraphClient
16
- from graphcore.agent_frontend.errors import AgentError
17
- from graphcore.agent_frontend.registry import AgentRegistry
12
+ from graphcore.agent_frontend.mcp_server import build_server
18
13
  from graphcore.agent_frontend.render import Frontend
19
-
20
- INSTRUCTIONS = """\
21
- This server presents a GraphCore deployment as addressed places. Start with open("/").
22
- Every place is a Markdown page: its content, its address, a version, and a Tools list.
23
- - open(at): read a place. Addresses look like /, /notes, /e/<backend>/<local>.
24
- - call(at, tool, params): run a tool listed under that place's Tools. Pass seen_version
25
- (the version you last read) so a write based on out-of-date content is refused.
26
- - find(type, predicate): list entities of a type, optionally filtered by field equality.
27
- - act(strategy, target, params): run a strategy directly when no place lists it as a tool.
28
- Reads and writes run as the user whose token you connected with.
29
- """
30
- WEB_INSTRUCTIONS = """\
31
- A place's `web:` link opens the same place in the web app. Give it to the user when
32
- they need to do something there.
33
- """
14
+ from graphcore.errors import IssuerUnavailable
34
15
 
35
16
 
36
17
  def _principal(ctx: Context):
37
18
  return ctx.request_context.request.state.principal
38
19
 
39
20
 
40
- def _guard(coro_fn):
41
- async def run(*args, **kwargs):
42
- try:
43
- return await coro_fn(*args, **kwargs)
44
- except AgentError as exc:
45
- raise ToolError(f"{exc.code}: {exc.message}")
46
- return run
47
-
48
-
49
21
  class _BearerAuth:
50
22
  def __init__(self, app, client: GraphClient, challenge: Callable[[dict], str]):
51
23
  self.app = app
@@ -58,7 +30,11 @@ class _BearerAuth:
58
30
  headers = dict(scope['headers'])
59
31
  value = headers.get(b'authorization', b'').decode()
60
32
  scheme, _, token = value.partition(' ')
61
- principal = await self.client.authenticate(token) if scheme.lower() == 'bearer' else None
33
+ try:
34
+ principal = await self.client.authenticate(token) if scheme.lower() == 'bearer' else None
35
+ except IssuerUnavailable as exc:
36
+ response = JSONResponse(exc.to_dict(), 503, {'Retry-After': str(exc.retry_after_seconds)})
37
+ return await response(scope, receive, send)
62
38
  if principal is None:
63
39
  response = JSONResponse({'error': 'unauthorized'}, 401, {'WWW-Authenticate': self.challenge(scope)})
64
40
  return await response(scope, receive, send)
@@ -67,52 +43,19 @@ class _BearerAuth:
67
43
 
68
44
 
69
45
  def create_app(
70
- client: GraphClient, registry: AgentRegistry, path: str = '/mcp', allowed_origins: Sequence[str] = (),
71
- challenge: Callable[[dict], str] = lambda scope: 'Bearer', web_url: str = '',
46
+ frontend: Frontend, path: str = '/mcp', allowed_origins: Sequence[str] = (),
47
+ challenge: Callable[[dict], str] = lambda scope: 'Bearer',
72
48
  execute_url: Callable[[dict], str] = lambda scope: '',
73
49
  ):
74
50
  """``challenge`` builds the 401's ``WWW-Authenticate`` value from the ASGI scope;
75
- ``web_url`` is the web app's URL, which every render then links to;
76
51
  ``execute_url`` builds, from the ASGI scope, the URL a strategy token's requests go to."""
77
- fe = Frontend(client, registry, web_url=web_url)
78
- mcp = MCPServer('graphcore', instructions=INSTRUCTIONS + (WEB_INSTRUCTIONS if web_url else ''))
79
-
80
- @mcp.tool(description='Read a place. Returns Markdown with its address, version and Tools.')
81
- async def open(at: str, ctx: Context, version: Optional[str] = None) -> str:
82
- return await _guard(tools.open_)(fe, _principal(ctx), at, version)
83
-
84
- @mcp.tool(description='List entities of a type; predicate maps field to a value or a list of values.')
85
- async def find(type: str, ctx: Context, predicate: Optional[dict[str, Any]] = None, limit: int = 25) -> str:
86
- return await _guard(tools.find)(fe, _principal(ctx), type, predicate, limit)
87
-
88
- @mcp.tool(description="Run a tool listed at a place. Pass seen_version to refuse the write if the place changed.")
89
- async def call(
90
- at: str, tool: str, ctx: Context, params: Optional[dict[str, Any]] = None,
91
- seen_version: Optional[str] = None,
92
- ) -> Annotated[CallToolResult, str]:
93
- # Annotated with `str` so the output schema and structured content stay what a `-> str` tool's are.
94
- out = await _guard(tools.call)(
95
- fe, _principal(ctx), at, tool, params, seen_version, execute_url(ctx.request_context.request.scope),
96
- )
97
- return CallToolResult(
98
- content=[
99
- TextContent(type='text', text=out.text),
100
- *(ImageContent(type='image', data=base64.b64encode(i.data).decode(), mime_type=i.media_type)
101
- for i in out.images),
102
- ],
103
- structured_content={'result': out.text},
104
- )
105
-
106
- @mcp.tool(description='Run a strategy by name, optionally on a target address or entity id.')
107
- async def act(strategy: str, ctx: Context, target: Optional[str] = None, params: Optional[dict[str, Any]] = None) -> str:
108
- return await _guard(tools.act)(fe, _principal(ctx), strategy, target, params)
109
-
52
+ mcp = build_server(frontend, _principal, lambda ctx: execute_url(ctx.request_context.request.scope))
110
53
  app = mcp.streamable_http_app(
111
54
  streamable_http_path=path, stateless_http=True, json_response=True,
112
55
  # Rebinding protection is off: the SDK default allows only localhost Hosts, and the bearer token gates access. TODO: configurable allowed hosts.
113
56
  transport_security=TransportSecuritySettings(enable_dns_rebinding_protection=False),
114
57
  )
115
- served = _BearerAuth(app, client, challenge)
58
+ served = _BearerAuth(app, frontend.client, challenge)
116
59
  if allowed_origins:
117
60
  # Outside the bearer check: a browser's preflight carries no token.
118
61
  served = CORSMiddleware(
@@ -30,6 +30,9 @@ def params(schema: Optional[dict], target_param: bool = False) -> str:
30
30
  return ', '.join(parts)
31
31
 
32
32
 
33
- def signature(name: str, schema: Optional[dict], description: Optional[str], target_param: bool = False) -> str:
34
- line = f"{name}({params(schema, target_param)})"
33
+ def signature(
34
+ name: str, schema: Optional[dict], description: Optional[str], target_param: bool = False,
35
+ read_only: bool = False,
36
+ ) -> str:
37
+ line = f"{name}({params(schema, target_param)})" + (' (read)' if read_only else '')
35
38
  return f"{line} — {description}" if description else line