holon-sh 0.0.1.dev10__tar.gz → 0.0.1.dev11__tar.gz
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.
- {holon_sh-0.0.1.dev10 → holon_sh-0.0.1.dev11}/PKG-INFO +1 -1
- {holon_sh-0.0.1.dev10 → holon_sh-0.0.1.dev11}/holon/client.py +93 -93
- {holon_sh-0.0.1.dev10 → holon_sh-0.0.1.dev11}/holon/context.py +3 -13
- holon_sh-0.0.1.dev11/holon/ext/__init__.py +1 -0
- holon_sh-0.0.1.dev11/holon/ext/events/__init__.py +29 -0
- holon_sh-0.0.1.dev11/holon/ext/events/_client.py +416 -0
- holon_sh-0.0.1.dev11/holon/ext/events/_server.py +838 -0
- holon_sh-0.0.1.dev11/holon/ext/events/_wire.py +32 -0
- {holon_sh-0.0.1.dev10 → holon_sh-0.0.1.dev11}/holon/ext/files/__init__.py +5 -5
- {holon_sh-0.0.1.dev10 → holon_sh-0.0.1.dev11}/holon/ext/files/_client.py +30 -47
- {holon_sh-0.0.1.dev10 → holon_sh-0.0.1.dev11}/holon/ext/files/_server.py +42 -60
- {holon_sh-0.0.1.dev10 → holon_sh-0.0.1.dev11}/holon/ext/files/_wire.py +4 -7
- {holon_sh-0.0.1.dev10 → holon_sh-0.0.1.dev11}/pyproject.toml +2 -2
- {holon_sh-0.0.1.dev10 → holon_sh-0.0.1.dev11}/tests/test_context.py +0 -1
- {holon_sh-0.0.1.dev10 → holon_sh-0.0.1.dev11}/tests/test_elicit.py +12 -19
- {holon_sh-0.0.1.dev10 → holon_sh-0.0.1.dev11}/tests/test_events.py +33 -22
- {holon_sh-0.0.1.dev10 → holon_sh-0.0.1.dev11}/tests/test_files.py +166 -108
- {holon_sh-0.0.1.dev10 → holon_sh-0.0.1.dev11}/tests/test_package.py +2 -1
- {holon_sh-0.0.1.dev10 → holon_sh-0.0.1.dev11}/tests/test_runtime.py +11 -6
- holon_sh-0.0.1.dev10/holon/binding.py +0 -25
- holon_sh-0.0.1.dev10/holon/ext/__init__.py +0 -1
- holon_sh-0.0.1.dev10/holon/ext/events.py +0 -1669
- holon_sh-0.0.1.dev10/tests/fixtures/caller/requirements.txt +0 -1
- holon_sh-0.0.1.dev10/tests/fixtures/caller/server.json +0 -5
- {holon_sh-0.0.1.dev10 → holon_sh-0.0.1.dev11}/.gitignore +0 -0
- {holon_sh-0.0.1.dev10 → holon_sh-0.0.1.dev11}/LICENSE +0 -0
- {holon_sh-0.0.1.dev10 → holon_sh-0.0.1.dev11}/README.md +0 -0
- {holon_sh-0.0.1.dev10 → holon_sh-0.0.1.dev11}/holon/py.typed +0 -0
- {holon_sh-0.0.1.dev10 → holon_sh-0.0.1.dev11}/scripts/verify_distribution.py +0 -0
- {holon_sh-0.0.1.dev10 → holon_sh-0.0.1.dev11}/tests/fixtures/caller/holon/apps/__init__.py +0 -0
|
@@ -1,19 +1,30 @@
|
|
|
1
1
|
from __future__ import annotations
|
|
2
2
|
|
|
3
3
|
import os
|
|
4
|
-
from collections.abc import AsyncIterator, Awaitable, Callable, Mapping
|
|
4
|
+
from collections.abc import AsyncIterator, Awaitable, Callable, Mapping, Sequence
|
|
5
5
|
from contextlib import asynccontextmanager
|
|
6
6
|
from functools import partial
|
|
7
7
|
from types import SimpleNamespace
|
|
8
|
-
from typing import
|
|
8
|
+
from typing import (
|
|
9
|
+
Any,
|
|
10
|
+
Generic,
|
|
11
|
+
Literal,
|
|
12
|
+
NotRequired,
|
|
13
|
+
Protocol,
|
|
14
|
+
TypeAlias,
|
|
15
|
+
TypedDict,
|
|
16
|
+
TypeVar,
|
|
17
|
+
)
|
|
9
18
|
|
|
10
19
|
import httpx2
|
|
11
20
|
import jsonschema
|
|
21
|
+
from jsonschema.protocols import Validator
|
|
12
22
|
from mcp import Client
|
|
13
23
|
from mcp.client import Transport
|
|
14
24
|
from mcp.client.session import ClientRequestContext
|
|
15
25
|
from mcp.client.streamable_http import streamable_http_client
|
|
16
26
|
from mcp.types import (
|
|
27
|
+
LATEST_PROTOCOL_VERSION,
|
|
17
28
|
CallToolRequest,
|
|
18
29
|
CallToolRequestParams,
|
|
19
30
|
CallToolResult,
|
|
@@ -29,7 +40,6 @@ from mcp.types import (
|
|
|
29
40
|
)
|
|
30
41
|
from referencing import Registry
|
|
31
42
|
|
|
32
|
-
from holon.binding import Binding
|
|
33
43
|
from holon.ext.events import AppEvents
|
|
34
44
|
from holon.ext.files._client import (
|
|
35
45
|
FILES,
|
|
@@ -50,7 +60,20 @@ __all__ = [
|
|
|
50
60
|
]
|
|
51
61
|
|
|
52
62
|
Output = TypeVar("Output")
|
|
53
|
-
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
class Binding(TypedDict):
|
|
66
|
+
"""Connection settings for an MCP dependency.
|
|
67
|
+
|
|
68
|
+
Attributes:
|
|
69
|
+
endpoint: Streamable HTTP MCP URL.
|
|
70
|
+
http_client: Returns a new ``httpx2.AsyncClient`` for each call, e.g. to authenticate.
|
|
71
|
+
file_origins: The only origins file transfers may use. Any public https origin when unset.
|
|
72
|
+
"""
|
|
73
|
+
|
|
74
|
+
endpoint: str
|
|
75
|
+
http_client: NotRequired[Callable[[], httpx2.AsyncClient]]
|
|
76
|
+
file_origins: NotRequired[Sequence[str]]
|
|
54
77
|
|
|
55
78
|
|
|
56
79
|
class CompleteResult(Protocol, Generic[Output]):
|
|
@@ -77,7 +100,7 @@ ToolResult: TypeAlias = CompleteResult[Output] | ErrorResult | InputRequiredResu
|
|
|
77
100
|
|
|
78
101
|
|
|
79
102
|
class CallOptions(TypedDict, total=False):
|
|
80
|
-
"""
|
|
103
|
+
"""Options for one call, passed positionally before the tool's arguments."""
|
|
81
104
|
|
|
82
105
|
timeout: float | None
|
|
83
106
|
input_responses: InputResponses | None
|
|
@@ -87,11 +110,10 @@ class CallOptions(TypedDict, total=False):
|
|
|
87
110
|
|
|
88
111
|
|
|
89
112
|
class ToolCallError(RuntimeError):
|
|
90
|
-
"""Raised by ``tools.<name>``
|
|
113
|
+
"""Raised by ``tools.<name>`` when a tool fails or needs input.
|
|
91
114
|
|
|
92
115
|
Attributes:
|
|
93
|
-
result:
|
|
94
|
-
answer questions in place, or continue later through ``call_tool``.
|
|
116
|
+
result: The error or input-required result.
|
|
95
117
|
"""
|
|
96
118
|
|
|
97
119
|
def __init__(
|
|
@@ -173,25 +195,24 @@ class _App:
|
|
|
173
195
|
name: str,
|
|
174
196
|
identity: dict[str, Any],
|
|
175
197
|
contract: dict[str, Any] | None,
|
|
176
|
-
binding: Binding | None
|
|
198
|
+
binding: Binding | None,
|
|
177
199
|
) -> None:
|
|
178
200
|
self._name = name
|
|
179
201
|
self._identity = identity
|
|
180
202
|
self._binding = binding
|
|
181
|
-
self._validators: dict[str,
|
|
182
|
-
self._definitions = (
|
|
183
|
-
|
|
203
|
+
self._validators: dict[str, Validator] = {}
|
|
204
|
+
self._definitions: dict[str, dict[str, Any]] = (
|
|
205
|
+
{}
|
|
184
206
|
if contract is None
|
|
185
207
|
else {tool["name"]: tool for tool in contract["tools"]}
|
|
186
208
|
)
|
|
187
209
|
self.tools = SimpleNamespace(
|
|
188
210
|
**{
|
|
189
211
|
name: partial(self._call_tool, tool)
|
|
190
|
-
for name, tool in
|
|
212
|
+
for name, tool in self._definitions.items()
|
|
191
213
|
if not name.startswith("_")
|
|
192
214
|
}
|
|
193
215
|
)
|
|
194
|
-
# Draft extensions, whose interfaces may change with the drafts.
|
|
195
216
|
self.ext = SimpleNamespace(events=AppEvents(self, contract))
|
|
196
217
|
|
|
197
218
|
async def call_tool(
|
|
@@ -201,67 +222,42 @@ class _App:
|
|
|
201
222
|
/,
|
|
202
223
|
**arguments: object,
|
|
203
224
|
) -> CallToolResult | InputRequiredResult:
|
|
204
|
-
"""Call a
|
|
225
|
+
"""Call a tool and return its full MCP result.
|
|
205
226
|
|
|
206
227
|
Args:
|
|
207
|
-
name: Tool name.
|
|
208
|
-
options:
|
|
209
|
-
|
|
210
|
-
place. Passed positionally, separate from tool input.
|
|
211
|
-
**arguments: Tool input, which the server validates. Pass a
|
|
212
|
-
``holon.ext.files.File`` where the tool takes a file.
|
|
228
|
+
name: Tool name.
|
|
229
|
+
options: Timeout, input responses, request state, metadata, and ``elicit``.
|
|
230
|
+
**arguments: Tool input. Pass a ``holon.ext.files.File`` where the tool takes a file.
|
|
213
231
|
|
|
214
232
|
Returns:
|
|
215
|
-
|
|
216
|
-
unanswered. Tool error results are returned unchanged; successful
|
|
217
|
-
structured output is contract-validated.
|
|
233
|
+
The complete result, or an input-required result for questions left unanswered.
|
|
218
234
|
|
|
219
235
|
Raises:
|
|
220
|
-
ValueError:
|
|
221
|
-
RuntimeError:
|
|
222
|
-
holon.ext.files.FileTransferError: A file was not sent; the tool did
|
|
223
|
-
|
|
224
|
-
holon.ext.files.OutcomeUnknownError: The call failed after its files
|
|
225
|
-
were sent; the tool may have run.
|
|
226
|
-
|
|
227
|
-
Transport and protocol exceptions propagate. Each call closes its HTTP
|
|
228
|
-
client and MCP session, including when an exception occurs.
|
|
236
|
+
ValueError: The output does not match the contract, or the dependency is undeclared.
|
|
237
|
+
RuntimeError: The dependency has no endpoint.
|
|
238
|
+
holon.ext.files.FileTransferError: A file was not sent; the tool did not run.
|
|
239
|
+
holon.ext.files.OutcomeUnknownError: The call failed after its files were sent.
|
|
229
240
|
"""
|
|
230
241
|
options = options or {}
|
|
231
|
-
definition =
|
|
232
|
-
if self._definitions is not None:
|
|
233
|
-
definition = self._definitions.get(name)
|
|
234
|
-
if definition is None:
|
|
235
|
-
raise ValueError(f"Unknown tool {self._name}.{name}.")
|
|
236
|
-
failure: Exception | None = None
|
|
242
|
+
definition = self._definitions.get(name, {})
|
|
237
243
|
transfers = Transfers(
|
|
238
244
|
f"{self._name}.{name}",
|
|
239
245
|
self._binding.get("file_origins") if self._binding else None,
|
|
240
246
|
)
|
|
241
247
|
async with self._session(options.get("timeout"), transfers=transfers) as client:
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
result = await _send(client, name, arguments, options, transfers)
|
|
247
|
-
except Exception as error: # noqa: BLE001
|
|
248
|
-
failure = error
|
|
249
|
-
if failure is not None:
|
|
250
|
-
raise failure
|
|
248
|
+
if holds_file(arguments):
|
|
249
|
+
schema = definition.get("inputSchema")
|
|
250
|
+
arguments = await transfers.prepare(client, name, schema, arguments)
|
|
251
|
+
result = await _send(client, name, arguments, options, transfers)
|
|
251
252
|
if isinstance(result, CallToolResult):
|
|
252
253
|
remember(result, transfers)
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
name,
|
|
261
|
-
definition["outputSchema"],
|
|
262
|
-
result.structured_content,
|
|
263
|
-
f"structured output from {self._name}.{name}",
|
|
264
|
-
)
|
|
254
|
+
if not result.is_error and "outputSchema" in definition:
|
|
255
|
+
self._validate(
|
|
256
|
+
name,
|
|
257
|
+
definition["outputSchema"],
|
|
258
|
+
result.structured_content,
|
|
259
|
+
f"structured output from {self._name}.{name}",
|
|
260
|
+
)
|
|
265
261
|
return result
|
|
266
262
|
|
|
267
263
|
def _connection(
|
|
@@ -290,6 +286,7 @@ class _App:
|
|
|
290
286
|
headers = {"Authorization": f"Bearer {token}"} if token else None
|
|
291
287
|
return endpoint, partial(http_client, headers=headers)
|
|
292
288
|
|
|
289
|
+
# Raises an error from the block as itself, not in the session's ExceptionGroup.
|
|
293
290
|
@asynccontextmanager
|
|
294
291
|
async def _session(
|
|
295
292
|
self,
|
|
@@ -298,30 +295,40 @@ class _App:
|
|
|
298
295
|
transfers: Transfers | None = None,
|
|
299
296
|
) -> AsyncIterator[Client]:
|
|
300
297
|
endpoint, http_client = self._connection(timeout)
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
298
|
+
failure: Exception | None = None
|
|
299
|
+
try:
|
|
300
|
+
async with http_client() as http:
|
|
301
|
+
if transfers is not None:
|
|
302
|
+
transfers.bind(endpoint, http_client, http)
|
|
303
|
+
transport: Transport = streamable_http_client(
|
|
304
|
+
endpoint, http_client=http, max_sse_event_size=None
|
|
305
|
+
)
|
|
306
|
+
if wrap is not None:
|
|
307
|
+
transport = wrap(transport)
|
|
308
|
+
async with Client(
|
|
309
|
+
transport,
|
|
310
|
+
client_info=Implementation(
|
|
311
|
+
name=self._identity["name"], version=self._identity["version"]
|
|
312
|
+
),
|
|
313
|
+
mode=LATEST_PROTOCOL_VERSION,
|
|
314
|
+
elicitation_callback=_declare_elicitation,
|
|
315
|
+
extensions=[FILES],
|
|
316
|
+
) as client:
|
|
317
|
+
try:
|
|
318
|
+
yield client
|
|
319
|
+
except Exception as error: # noqa: BLE001
|
|
320
|
+
failure = error
|
|
321
|
+
except Exception:
|
|
322
|
+
if failure is None:
|
|
323
|
+
raise
|
|
324
|
+
if failure is not None:
|
|
325
|
+
raise failure
|
|
319
326
|
|
|
320
327
|
def _validate(
|
|
321
328
|
self, name: str, schema: dict[str, Any], value: Any, label: str
|
|
322
329
|
) -> None:
|
|
323
330
|
validator = self._validators.get(name)
|
|
324
|
-
if validator is None
|
|
331
|
+
if validator is None:
|
|
325
332
|
cls = jsonschema.validators.validator_for(schema)
|
|
326
333
|
cls.check_schema(schema)
|
|
327
334
|
validator = self._validators[name] = cls(
|
|
@@ -346,26 +353,19 @@ class _App:
|
|
|
346
353
|
|
|
347
354
|
|
|
348
355
|
class Apps:
|
|
349
|
-
"""
|
|
356
|
+
"""An application's dependencies, as generated clients use them.
|
|
350
357
|
|
|
351
|
-
Applications
|
|
358
|
+
Applications use ``apps`` or ``create_apps`` from ``holon.apps``. Each dependency is ``apps.<name>``
|
|
359
|
+
or ``apps[name]``: its ``tools.<name>`` return structured output or raise :class:`ToolCallError`,
|
|
360
|
+
and its ``call_tool`` returns the full result.
|
|
352
361
|
|
|
353
362
|
Args:
|
|
354
|
-
identity: Application name, version, and
|
|
355
|
-
contracts: Dependency contracts
|
|
356
|
-
|
|
357
|
-
bindings: Explicit bindings. When supplied, only these dependencies are
|
|
358
|
-
included; an empty mapping selects none. Otherwise all declared
|
|
359
|
-
dependencies and contracts are available.
|
|
363
|
+
identity: Application name, version, and ``requires``.
|
|
364
|
+
contracts: Dependency contracts by name.
|
|
365
|
+
bindings: Connection settings by name. When given, only these dependencies are available.
|
|
360
366
|
|
|
361
367
|
Raises:
|
|
362
368
|
ValueError: A binding names an unknown dependency.
|
|
363
|
-
|
|
364
|
-
Access a client with ``clients[name]`` or ``clients.name``. Its
|
|
365
|
-
``tools.<name>(**arguments)`` methods return structured output, or the
|
|
366
|
-
complete result for a tool without an output schema, and raise
|
|
367
|
-
:class:`ToolCallError` for tool errors or questions left unanswered.
|
|
368
|
-
Use its ``call_tool`` method for the full result envelope.
|
|
369
369
|
"""
|
|
370
370
|
|
|
371
371
|
def __init__(
|
|
@@ -18,7 +18,7 @@ class AddressClaims(TypedDict, total=False):
|
|
|
18
18
|
class IdentityClaims(TypedDict, total=False):
|
|
19
19
|
"""Standard OpenID Connect claims.
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims
|
|
22
22
|
"""
|
|
23
23
|
|
|
24
24
|
name: str
|
|
@@ -44,7 +44,7 @@ class IdentityClaims(TypedDict, total=False):
|
|
|
44
44
|
|
|
45
45
|
@dataclass(frozen=True)
|
|
46
46
|
class Principal:
|
|
47
|
-
"""The user a request acts for
|
|
47
|
+
"""The user a request acts for."""
|
|
48
48
|
|
|
49
49
|
issuer: str
|
|
50
50
|
subject: str
|
|
@@ -60,17 +60,7 @@ class RequestContext:
|
|
|
60
60
|
|
|
61
61
|
|
|
62
62
|
def get_context() -> RequestContext:
|
|
63
|
-
"""
|
|
64
|
-
|
|
65
|
-
Holon validates the request before it reaches the application and hands the
|
|
66
|
-
caller over as MCP's access token, so this reads ``get_access_token()``.
|
|
67
|
-
|
|
68
|
-
Returns:
|
|
69
|
-
A ``RequestContext`` whose ``principal`` is ``None`` for anonymous requests.
|
|
70
|
-
|
|
71
|
-
Example:
|
|
72
|
-
``principal = get_context().principal``
|
|
73
|
-
"""
|
|
63
|
+
"""The caller of the current MCP request; ``principal`` is ``None`` when anonymous."""
|
|
74
64
|
admitted = get_access_token()
|
|
75
65
|
extra = (admitted.claims or {}) if admitted else {}
|
|
76
66
|
if admitted is None or admitted.subject is None or "iss" not in extra:
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""MCP extensions."""
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
"""MCP Events, delivered by poll and push.
|
|
2
|
+
|
|
3
|
+
https://github.com/modelcontextprotocol/experimental-ext-triggers-events/blob/main/docs/design-sketch-proposal.md
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
from holon.ext.events._client import AppEvents, NoCompatibleDeliveryMode, Subscription
|
|
7
|
+
from holon.ext.events._server import Events, EventType
|
|
8
|
+
from holon.ext.events._wire import (
|
|
9
|
+
EVENTS_EXTENSION,
|
|
10
|
+
FORBIDDEN,
|
|
11
|
+
NOT_FOUND,
|
|
12
|
+
RESOURCE_EXHAUSTED,
|
|
13
|
+
UNSUPPORTED,
|
|
14
|
+
Event,
|
|
15
|
+
)
|
|
16
|
+
|
|
17
|
+
__all__ = [
|
|
18
|
+
"EVENTS_EXTENSION",
|
|
19
|
+
"FORBIDDEN",
|
|
20
|
+
"NOT_FOUND",
|
|
21
|
+
"RESOURCE_EXHAUSTED",
|
|
22
|
+
"UNSUPPORTED",
|
|
23
|
+
"AppEvents",
|
|
24
|
+
"Event",
|
|
25
|
+
"EventType",
|
|
26
|
+
"Events",
|
|
27
|
+
"NoCompatibleDeliveryMode",
|
|
28
|
+
"Subscription",
|
|
29
|
+
]
|