holon-sh 0.0.1.dev9__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.
Files changed (31) hide show
  1. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev11}/PKG-INFO +2 -2
  2. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev11}/README.md +1 -1
  3. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev11}/holon/client.py +93 -93
  4. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev11}/holon/context.py +3 -13
  5. holon_sh-0.0.1.dev11/holon/ext/__init__.py +1 -0
  6. holon_sh-0.0.1.dev11/holon/ext/events/__init__.py +29 -0
  7. holon_sh-0.0.1.dev11/holon/ext/events/_client.py +416 -0
  8. holon_sh-0.0.1.dev11/holon/ext/events/_server.py +838 -0
  9. holon_sh-0.0.1.dev11/holon/ext/events/_wire.py +32 -0
  10. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev11}/holon/ext/files/__init__.py +5 -5
  11. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev11}/holon/ext/files/_client.py +30 -47
  12. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev11}/holon/ext/files/_server.py +42 -60
  13. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev11}/holon/ext/files/_wire.py +4 -7
  14. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev11}/pyproject.toml +2 -2
  15. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev11}/tests/test_context.py +0 -1
  16. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev11}/tests/test_elicit.py +12 -19
  17. holon_sh-0.0.1.dev11/tests/test_events.py +548 -0
  18. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev11}/tests/test_files.py +166 -108
  19. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev11}/tests/test_package.py +2 -1
  20. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev11}/tests/test_runtime.py +11 -6
  21. holon_sh-0.0.1.dev9/holon/binding.py +0 -25
  22. holon_sh-0.0.1.dev9/holon/ext/__init__.py +0 -1
  23. holon_sh-0.0.1.dev9/holon/ext/events.py +0 -1627
  24. holon_sh-0.0.1.dev9/tests/fixtures/caller/requirements.txt +0 -1
  25. holon_sh-0.0.1.dev9/tests/fixtures/caller/server.json +0 -5
  26. holon_sh-0.0.1.dev9/tests/test_events.py +0 -581
  27. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev11}/.gitignore +0 -0
  28. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev11}/LICENSE +0 -0
  29. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev11}/holon/py.typed +0 -0
  30. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev11}/scripts/verify_distribution.py +0 -0
  31. {holon_sh-0.0.1.dev9 → holon_sh-0.0.1.dev11}/tests/fixtures/caller/holon/apps/__init__.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: holon-sh
3
- Version: 0.0.1.dev9
3
+ Version: 0.0.1.dev11
4
4
  Summary: Typed MCP clients and the caller of an MCP request
5
5
  Project-URL: Repository, https://github.com/holon-sh/sdk-py
6
6
  License-Expression: Apache-2.0
@@ -14,7 +14,7 @@ Description-Content-Type: text/markdown
14
14
  # Holon Python SDK
15
15
 
16
16
  [![CI](https://github.com/holon-sh/sdk-py/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/holon-sh/sdk-py/actions/workflows/ci.yml)
17
- [![Docs](https://img.shields.io/badge/docs-holon--labs.dev-blue)](https://holon-labs.dev/docs/)
17
+ [![Docs](https://img.shields.io/badge/docs-holonlabs.ai-blue)](https://holonlabs.ai/docs/)
18
18
  [![PyPI](https://img.shields.io/pypi/v/holon-sh)](https://pypi.org/project/holon-sh/)
19
19
  [![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/downloads/)
20
20
  [![Apache 2.0 License](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE)
@@ -1,7 +1,7 @@
1
1
  # Holon Python SDK
2
2
 
3
3
  [![CI](https://github.com/holon-sh/sdk-py/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/holon-sh/sdk-py/actions/workflows/ci.yml)
4
- [![Docs](https://img.shields.io/badge/docs-holon--labs.dev-blue)](https://holon-labs.dev/docs/)
4
+ [![Docs](https://img.shields.io/badge/docs-holonlabs.ai-blue)](https://holonlabs.ai/docs/)
5
5
  [![PyPI](https://img.shields.io/pypi/v/holon-sh)](https://pypi.org/project/holon-sh/)
6
6
  [![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/downloads/)
7
7
  [![Apache 2.0 License](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE)
@@ -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 Any, Generic, Literal, Protocol, TypeAlias, TypedDict, TypeVar
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
- _VERSION = "2026-07-28"
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
- """Request controls, passed positionally to keep tool keywords available."""
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>`` for tool errors or additional input requests.
113
+ """Raised by ``tools.<name>`` when a tool fails or needs input.
91
114
 
92
115
  Attributes:
93
- result: Original MCP error or input-required result. Pass ``elicit`` to
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 = 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, Any] = {}
182
- self._definitions = (
183
- None
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 (self._definitions or {}).items()
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 dependency tool and return its full MCP result.
225
+ """Call a tool and return its full MCP result.
205
226
 
206
227
  Args:
207
- name: Tool name. Contracted dependencies reject unknown tools.
208
- options: Request timeout in seconds, input responses, continuation
209
- state, metadata, and ``elicit`` to answer the server's questions in
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
- A complete result, or an input-required result for a question left
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: Unknown tool, invalid output, or undeclared dependency.
221
- RuntimeError: Endpoint resolution failed.
222
- holon.ext.files.FileTransferError: A file was not sent; the tool did
223
- not run.
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 = None
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
- try:
243
- if holds_file(arguments):
244
- schema = definition.get("inputSchema") if definition else None
245
- arguments = await transfers.prepare(client, name, schema, arguments)
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
- if (
254
- definition is not None
255
- and isinstance(result, CallToolResult)
256
- and not result.is_error
257
- and "outputSchema" in definition
258
- ):
259
- self._validate(
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
- async with http_client() as http:
302
- if transfers is not None:
303
- transfers.bind(endpoint, http_client, http)
304
- transport: Transport = streamable_http_client(
305
- endpoint, http_client=http, max_sse_event_size=None
306
- )
307
- if wrap is not None:
308
- transport = wrap(transport)
309
- async with Client(
310
- transport,
311
- client_info=Implementation(
312
- name=self._identity["name"], version=self._identity["version"]
313
- ),
314
- mode=_VERSION,
315
- elicitation_callback=_declare_elicitation,
316
- extensions=[FILES],
317
- ) as client:
318
- yield client
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 or validator.schema is not schema:
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
- """Create the dependency collection used by generated Python clients.
356
+ """An application's dependencies, as generated clients use them.
350
357
 
351
- Applications typically use ``apps`` or ``create_apps`` from ``holon.apps``.
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 declared ``requires`` mapping.
355
- contracts: Dependency contracts with a ``tools`` list, or ``None`` for
356
- untyped dependencies.
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
- Holon drops one whose value has the wrong type; other claims pass through.
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, as Holon admitted it."""
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
- """Read the caller of the current MCP request.
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
+ ]