holon-sh 0.0.1.dev1__py3-none-any.whl

holon/binding.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import NotRequired, TypedDict
+
+import httpx2
+
+
+class Binding(TypedDict):
+    endpoint: str
+    http_client: NotRequired[Callable[[], httpx2.AsyncClient]]
+    # Python clients open one session per call, so every binding already behaves as scoped.
+    scoped: NotRequired[bool]
+
+
+_resolver: Callable[[str], Binding | None] | None = None
+
+
+def set_default_binding(resolve: Callable[[str], Binding | None]) -> None:
+    """Resolve bindings for app clients that were not bound with ``create_apps``.
+
+    Without a resolver, or when it returns ``None``, a client falls back to its
+    ``<NAME>_MCP_URL`` environment variable.
+    """
+    global _resolver
+    _resolver = resolve
+
+
+def resolve_default_binding(app: str) -> Binding | None:
+    return _resolver(app) if _resolver is not None else None

holon/client.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from typing import Any, Generic, Literal, Protocol, TypeAlias, TypeVar
+
+import httpx2
+import jsonschema  # type: ignore[import-untyped,unused-ignore]
+from mcp import Client
+from mcp.client.streamable_http import streamable_http_client
+from mcp.types import (
+    CallToolRequest,
+    CallToolRequestParams,
+    CallToolResult,
+    ContentBlock,
+    Implementation,
+    InputRequiredResult,
+    InputResponses,
+    RequestParamsMeta,
+)
+from pydantic import TypeAdapter
+from referencing import Registry
+
+from holon.binding import Binding, resolve_default_binding
+
+# Binding is re-exported for the generated holon.apps module.
+__all__ = ["Apps", "Binding", "ToolCallError", "ToolResult"]
+
+Output = TypeVar("Output")
+
+
+class CompleteResult(Protocol, Generic[Output]):
+    result_type: Literal["complete"]
+    is_error: Literal[False]
+    structured_content: Output
+    content: list[ContentBlock]
+    meta: dict[str, object] | None
+
+
+class ErrorResult(Protocol):
+    result_type: Literal["complete"]
+    is_error: Literal[True]
+    structured_content: object
+    content: list[ContentBlock]
+    meta: dict[str, object] | None
+
+
+ToolResult: TypeAlias = CompleteResult[Output] | ErrorResult | InputRequiredResult
+
+_result = TypeAdapter(CallToolResult | InputRequiredResult)
+
+
+class ToolCallError(RuntimeError):
+    def __init__(
+        self, app: str, tool: str, result: CallToolResult | InputRequiredResult
+    ) -> None:
+        self.app = app
+        self.tool = tool
+        self.result = result
+        self.code: Literal["tool_error", "input_required"]
+        if isinstance(result, InputRequiredResult):
+            self.code, message = "input_required", "additional input required"
+        else:
+            self.code, message = "tool_error", "tool failed"
+        super().__init__(f"{app}.{tool}: {message}.")
+
+
+def validate(schema: dict[str, Any], value: object, label: str) -> None:
+    try:
+        jsonschema.validate(
+            value,
+            schema,
+            registry=Registry(),
+            format_checker=jsonschema.FormatChecker(),
+        )
+    except jsonschema.ValidationError as error:
+        raise ValueError(f"Invalid {label}: {error.message}") from error
+
+
+class _App:
+    def __init__(
+        self,
+        name: str,
+        identity: dict[str, Any],
+        contract: dict[str, Any] | None,
+        binding: Binding | None = None,
+    ) -> None:
+        self._name = name
+        self._identity = identity
+        self._binding = binding
+        # None for a dependency without a contract: any tool, unvalidated.
+        self._definitions = (
+            None
+            if contract is None
+            else {tool["name"]: tool for tool in contract["tools"]}
+        )
+        self.tools = _Tools(self)
+
+    async def call_tool(
+        self,
+        name: str,
+        arguments: Mapping[str, object],
+        *,
+        timeout: float | None = None,
+        input_responses: InputResponses | None = None,
+        request_state: str | None = None,
+        meta: RequestParamsMeta | None = None,
+    ) -> CallToolResult | InputRequiredResult:
+        definition = None
+        if self._definitions is not None:
+            definition = self._definitions.get(name)
+            if definition is None:
+                raise ValueError(f"Unknown tool {self._name}.{name}.")
+            validate(
+                definition["inputSchema"],
+                arguments,
+                f"arguments for {self._name}.{name}",
+            )
+        binding = self._binding or resolve_default_binding(self._name)
+        if binding is None and self._name not in self._identity["requires"]:
+            raise ValueError(
+                f"Dependency {self._name} is not declared by this application."
+            )
+        variable = self._name.upper().replace("-", "_") + "_MCP_URL"
+        endpoint = binding["endpoint"] if binding else os.environ.get(variable)
+        if not endpoint:
+            raise RuntimeError(
+                f"Dependency {self._name} is unavailable ({variable}). Set the endpoint or supply a binding."
+            )
+        http = (
+            binding["http_client"]()
+            if binding and "http_client" in binding
+            else httpx2.AsyncClient(trust_env=False)
+        )
+        async with http:
+            transport = streamable_http_client(endpoint, http_client=http)
+            async with Client(
+                transport,
+                client_info=Implementation(
+                    name=self._identity["name"], version=self._identity["version"]
+                ),
+                mode="2026-07-28",
+            ) as client:
+                result = await client.session.send_request(
+                    CallToolRequest(
+                        params=CallToolRequestParams(
+                            name=name,
+                            arguments=dict(arguments),
+                            input_responses=input_responses,
+                            request_state=request_state,
+                            _meta=meta,
+                        )
+                    ),
+                    _result,
+                    request_read_timeout_seconds=timeout,
+                )
+        if (
+            definition is not None
+            and isinstance(result, CallToolResult)
+            and not result.is_error
+            and "outputSchema" in definition
+        ):
+            validate(
+                definition["outputSchema"],
+                result.structured_content,
+                f"structured output from {self._name}.{name}",
+            )
+        return result
+
+
+class _Tools:
+    def __init__(self, client: _App) -> None:
+        self._client = client
+
+    def __getattr__(self, name: str) -> Any:
+        definitions = self._client._definitions
+        if name.startswith("_") or definitions is None or name not in definitions:
+            raise AttributeError(name)
+
+        async def call(
+            arguments: Mapping[str, object], *, timeout: float | None = None
+        ) -> object:
+            result = await self._client.call_tool(name, arguments, timeout=timeout)
+            if isinstance(result, InputRequiredResult) or result.is_error:
+                raise ToolCallError(self._client._name, name, result)
+            return result.structured_content
+
+        return call
+
+
+class Apps:
+    def __init__(
+        self,
+        identity: dict[str, Any],
+        contracts: dict[str, Any],
+        bindings: Mapping[str, Binding] | None = None,
+    ) -> None:
+        # Every declared dependency gets a client; those without a contract are untyped.
+        available: dict[str, dict[str, Any] | None] = {
+            name: None for name in identity["requires"]
+        }
+        available.update(contracts)
+        selected = available if bindings is None else {}
+        for name in bindings or ():
+            if name not in available:
+                raise ValueError(f"Unknown app binding: {name}")
+            selected[name] = available[name]
+        self._apps = {
+            name: _App(name, identity, contract, bindings[name] if bindings else None)
+            for name, contract in selected.items()
+        }
+
+    def __getitem__(self, name: str) -> _App:
+        return self._apps[name]
+
+    def __getattr__(self, name: str) -> _App:
+        if name.startswith("_") or name not in self._apps:
+            raise AttributeError(name)
+        return self._apps[name]

holon/view.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from mcp.server.apps import APP_MIME_TYPE
+from mcp.server.mcpserver.resources import FunctionResource
+
+
+def app_view(
+    uri: str,
+    name: str,
+    file: Path | str,
+    *,
+    connect_domains: list[str] | None = None,
+    resource_domains: list[str] | None = None,
+) -> FunctionResource:
+    page = Path(file)
+    csp = {
+        "connectDomains": connect_domains or [],
+        "resourceDomains": resource_domains or [],
+    }
+    built: list[str] = []
+
+    def read() -> str:
+        if not built:
+            built.append(page.read_text())
+        return built[0]
+
+    return FunctionResource.from_function(
+        read,
+        uri,
+        name=name,
+        mime_type=APP_MIME_TYPE,
+        meta={"ui": {"csp": csp}},
+    )

holon_sh-0.0.1.dev1.dist-info/METADATA

@@ -0,0 +1,11 @@
+Metadata-Version: 2.5
+Name: holon-sh
+Version: 0.0.1.dev1
+Summary: Typed MCP clients, bindings, and app views
+Project-URL: Repository, https://github.com/holon-sh/sdk-py
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: httpx2<3,>=2.10
+Requires-Dist: jsonschema<5,>=4.26
+Requires-Dist: mcp<3,>=2.3

holon_sh-0.0.1.dev1.dist-info/RECORD

@@ -0,0 +1,8 @@
+holon/binding.py,sha256=ulQQIGyA80wyzAvcosArFQMXg77-HG-0LwXPahFW878,878
+holon/client.py,sha256=S-HwG4A-lUbY93jBe8ZktcibFK1Ss-0rzWCzQfEaJJQ,7464
+holon/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+holon/view.py,sha256=SuXo3cBow23OtrJaI9dF5hlptxh2NmgnbAozWTg5fRQ,797
+holon_sh-0.0.1.dev1.dist-info/METADATA,sha256=y5rVgIUZ3uxx5Mz2UrdSsjS3UnbQd6FXYoe1bsbEMfk,332
+holon_sh-0.0.1.dev1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+holon_sh-0.0.1.dev1.dist-info/licenses/LICENSE,sha256=h2vZ3IxSxiusmhPhiF-u5T3DkFywBJ3ayE0P2LpI_tQ,1067
+holon_sh-0.0.1.dev1.dist-info/RECORD,,

holon_sh-0.0.1.dev1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

holon_sh-0.0.1.dev1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Holon Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.