holon-sh 0.0.1.dev1__tar.gz → 0.0.1.dev3__tar.gz

{holon_sh-0.0.1.dev1 → holon_sh-0.0.1.dev3}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Holon Labs
+Copyright (c) 2026 Holon Systems, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

holon_sh-0.0.1.dev3/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.5
+Name: holon-sh
+Version: 0.0.1.dev3
+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
+Description-Content-Type: text/markdown
+
+# Holon Python SDK
+
+[![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)
+[![PyPI](https://img.shields.io/pypi/v/holon-sh)](https://pypi.org/project/holon-sh/)
+[![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![MIT License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+This repository contains the Python runtime for [`holon`](https://github.com/holon-sh/cli).
+
+## Install
+
+```sh
+uv add --prerelease allow holon-sh
+uv add --dev holon-types
+```
+
+`holon-types` is the `holon` CLI; it brings mypy, which `holon types check` runs from the project's environment.
+
+## Invoking MCP Servers
+
+The Holon Python SDK allows generation of type-safe MCP clients. See [Example](https://github.com/holon-sh/cli#example) for an explanation, or [Dependencies](https://github.com/holon-sh/cli#dependencies) to understand dependency resolution.
+
+### Type-checking MCP invocations
+
+```sh
+uv run holon types check
+```
+
+<details open>
+<summary><h3>Call a tool</h3></summary>
+
+```python
+from holon.apps import apps
+
+async def greet(name: str) -> str:
+    greeting = await apps.bar.tools.greet({"timeout": 5.0}, name=name)
+    return greeting["result"]
+```
+
+Arguments are keywords, validated before sending; the result is validated against the output schema and returned.
+
+</details>
+
+<details open>
+<summary><h3>Handle errors</h3></summary>
+
+```python
+from holon.client import ToolCallError
+
+try:
+    await apps.bar.tools.greet(name="world")
+except ToolCallError as error:
+    error.code     # "tool_error" or "input_required"
+    error.result   # the original MCP result
+```
+
+</details>
+
+<details open>
+<summary><h3>Read the whole result</h3></summary>
+
+`call_tool` returns the full MCP result instead of raising:
+
+```python
+result = await apps.bar.call_tool("greet", name="world")
+if result.result_type == "input_required":
+    ...                          # call again with input_responses and request_state
+elif result.is_error:
+    ...                          # inspect result.content
+else:
+    result.structured_content    # typed as Outputs.bar.greet
+```
+
+The options dict also accepts `input_responses`, `request_state` and `meta`.
+
+</details>
+
+## Serve an [MCP App](https://modelcontextprotocol.io/extensions/apps/overview) view
+
+`holon.view.app_view` registers a built HTML file as an MCP App resource:
+
+```python
+from holon.view import app_view
+
+server.add_resource(app_view(
+    "ui://foo/index.html", "Foo", "dist/index.html",
+    connect_domains=["https://bar.example.com"],
+))
+```
+
+The page itself uses [`holon-ui`](https://github.com/holon-sh/sdk-ui).

holon_sh-0.0.1.dev3/README.md

@@ -0,0 +1,91 @@
+# Holon Python SDK
+
+[![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)
+[![PyPI](https://img.shields.io/pypi/v/holon-sh)](https://pypi.org/project/holon-sh/)
+[![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![MIT License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+This repository contains the Python runtime for [`holon`](https://github.com/holon-sh/cli).
+
+## Install
+
+```sh
+uv add --prerelease allow holon-sh
+uv add --dev holon-types
+```
+
+`holon-types` is the `holon` CLI; it brings mypy, which `holon types check` runs from the project's environment.
+
+## Invoking MCP Servers
+
+The Holon Python SDK allows generation of type-safe MCP clients. See [Example](https://github.com/holon-sh/cli#example) for an explanation, or [Dependencies](https://github.com/holon-sh/cli#dependencies) to understand dependency resolution.
+
+### Type-checking MCP invocations
+
+```sh
+uv run holon types check
+```
+
+<details open>
+<summary><h3>Call a tool</h3></summary>
+
+```python
+from holon.apps import apps
+
+async def greet(name: str) -> str:
+    greeting = await apps.bar.tools.greet({"timeout": 5.0}, name=name)
+    return greeting["result"]
+```
+
+Arguments are keywords, validated before sending; the result is validated against the output schema and returned.
+
+</details>
+
+<details open>
+<summary><h3>Handle errors</h3></summary>
+
+```python
+from holon.client import ToolCallError
+
+try:
+    await apps.bar.tools.greet(name="world")
+except ToolCallError as error:
+    error.code     # "tool_error" or "input_required"
+    error.result   # the original MCP result
+```
+
+</details>
+
+<details open>
+<summary><h3>Read the whole result</h3></summary>
+
+`call_tool` returns the full MCP result instead of raising:
+
+```python
+result = await apps.bar.call_tool("greet", name="world")
+if result.result_type == "input_required":
+    ...                          # call again with input_responses and request_state
+elif result.is_error:
+    ...                          # inspect result.content
+else:
+    result.structured_content    # typed as Outputs.bar.greet
+```
+
+The options dict also accepts `input_responses`, `request_state` and `meta`.
+
+</details>
+
+## Serve an [MCP App](https://modelcontextprotocol.io/extensions/apps/overview) view
+
+`holon.view.app_view` registers a built HTML file as an MCP App resource:
+
+```python
+from holon.view import app_view
+
+server.add_resource(app_view(
+    "ui://foo/index.html", "Foo", "dist/index.html",
+    connect_domains=["https://bar.example.com"],
+))
+```
+
+The page itself uses [`holon-ui`](https://github.com/holon-sh/sdk-ui).

holon_sh-0.0.1.dev3/holon/binding.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import NotRequired, TypedDict
+
+import httpx2
+
+
+class Binding(TypedDict):
+    """Connection settings for an MCP dependency.
+
+    Attributes:
+        endpoint: Streamable HTTP MCP URL.
+        http_client: Factory returning a fresh ``httpx2.AsyncClient`` for each
+            call. Configure authentication headers or a custom transport here.
+            The SDK closes the returned client when the call finishes.
+    """
+
+    endpoint: str
+    http_client: NotRequired[Callable[[], httpx2.AsyncClient]]
+
+
+_resolver: Callable[[str], Binding | None] | None = None
+
+
+def set_default_binding(resolve: Callable[[str], Binding | None]) -> None:
+    """Register the default binding resolver for app clients.
+
+    Args:
+        resolve: Process-wide callback receiving the dependency name. Return a
+            binding or ``None`` to use the environment fallback. Explicit
+            bindings take precedence. Register during application startup.
+    """
+    global _resolver
+    _resolver = resolve
+
+
+def resolve_default_binding(app: str) -> Binding | None:
+    """Return the registered resolver's binding for an app.
+
+    Args:
+        app: Dependency name passed unchanged to the resolver.
+
+    Returns:
+        The resolved binding, or ``None`` if none is available.
+    """
+    return _resolver(app) if _resolver is not None else None

{holon_sh-0.0.1.dev1 → holon_sh-0.0.1.dev3}/holon/client.py

@@ -2,7 +2,9 @@ from __future__ import annotations
 
 import os
 from collections.abc import Mapping
-from typing import Any, Generic, Literal, Protocol, TypeAlias, TypeVar
+from functools import partial
+from types import SimpleNamespace
+from typing import Any, Generic, Literal, Protocol, TypeAlias, TypedDict, TypeVar
 
 import httpx2
 import jsonschema  # type: ignore[import-untyped,unused-ignore]
@@ -24,12 +26,14 @@ 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"]
+__all__ = ["Apps", "Binding", "CallOptions", "ToolCallError", "ToolResult"]
 
 Output = TypeVar("Output")
 
 
 class CompleteResult(Protocol, Generic[Output]):
+    """Successful tool result with contract-typed structured content."""
+
     result_type: Literal["complete"]
     is_error: Literal[False]
     structured_content: Output
@@ -38,6 +42,8 @@ class CompleteResult(Protocol, Generic[Output]):
 
 
 class ErrorResult(Protocol):
+    """Completed tool result reporting an application error."""
+
     result_type: Literal["complete"]
     is_error: Literal[True]
     structured_content: object
@@ -50,7 +56,26 @@ ToolResult: TypeAlias = CompleteResult[Output] | ErrorResult | InputRequiredResu
 _result = TypeAdapter(CallToolResult | InputRequiredResult)
 
 
+class CallOptions(TypedDict, total=False):
+    """Request controls, passed positionally to keep tool keywords available."""
+
+    timeout: float | None
+    input_responses: InputResponses | None
+    request_state: str | None
+    meta: RequestParamsMeta | None
+
+
 class ToolCallError(RuntimeError):
+    """Raised by ``tools.<name>`` for tool errors or additional input requests.
+
+    Attributes:
+        app: Dependency name.
+        tool: Requested tool name.
+        result: Original MCP error or input-required result.
+        code: ``tool_error`` or ``input_required``. Use ``call_tool`` when you
+            need to inspect these results and submit additional input.
+    """
+
     def __init__(
         self, app: str, tool: str, result: CallToolResult | InputRequiredResult
     ) -> None:
@@ -94,18 +119,41 @@ class _App:
             if contract is None
             else {tool["name"]: tool for tool in contract["tools"]}
         )
-        self.tools = _Tools(self)
+        self.tools = SimpleNamespace(
+            **{
+                name: partial(self._call_tool, name)
+                for name in self._definitions or ()
+                if not name.startswith("_")
+            }
+        )
 
     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,
+        options: CallOptions | None = None,
+        /,
+        **arguments: object,
     ) -> CallToolResult | InputRequiredResult:
+        """Call a dependency tool and return its full MCP result.
+
+        Args:
+            name: Tool name. Contracted dependencies reject unknown tools.
+            options: Request timeout in seconds, input responses, continuation
+                state, and metadata. Passed positionally, separate from tool input.
+            **arguments: Tool input, validated against the contract if present.
+
+        Returns:
+            A complete or input-required result. Tool error results are returned
+            unchanged; successful structured output is contract-validated.
+
+        Raises:
+            ValueError: Unknown tool, invalid input/output, or undeclared dependency.
+            RuntimeError: Endpoint resolution failed.
+
+        Transport and protocol exceptions propagate. Each call closes its HTTP
+        client and MCP session, including when an exception occurs.
+        """
+        options = options or {}
         definition = None
         if self._definitions is not None:
             definition = self._definitions.get(name)
@@ -127,12 +175,10 @@ class _App:
             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:
+        http_client = partial(httpx2.AsyncClient, trust_env=False)
+        async with (
+            binding.get("http_client", http_client) if binding else http_client
+        )() as http:
             transport = streamable_http_client(endpoint, http_client=http)
             async with Client(
                 transport,
@@ -145,14 +191,14 @@ class _App:
                     CallToolRequest(
                         params=CallToolRequestParams(
                             name=name,
-                            arguments=dict(arguments),
-                            input_responses=input_responses,
-                            request_state=request_state,
-                            _meta=meta,
+                            arguments=arguments,
+                            input_responses=options.get("input_responses"),
+                            request_state=options.get("request_state"),
+                            _meta=options.get("meta"),
                         )
                     ),
                     _result,
-                    request_read_timeout_seconds=timeout,
+                    request_read_timeout_seconds=options.get("timeout"),
                 )
         if (
             definition is not None
@@ -167,28 +213,41 @@ class _App:
             )
         return result
 
+    async def _call_tool(
+        self,
+        name: str,
+        options: CallOptions | None = None,
+        /,
+        **arguments: object,
+    ) -> object:
+        result = await self.call_tool(name, options, **arguments)
+        if isinstance(result, InputRequiredResult) or result.is_error:
+            raise ToolCallError(self._name, name, result)
+        return result.structured_content
+
 
-class _Tools:
-    def __init__(self, client: _App) -> None:
-        self._client = client
+class Apps:
+    """Create the dependency collection used by generated Python clients.
 
-    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)
+    Applications typically use ``apps`` or ``create_apps`` from ``holon.apps``.
 
-        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
+    Args:
+        identity: Application name, version, and declared ``requires`` mapping.
+        contracts: Dependency contracts with a ``tools`` list, or ``None`` for
+            untyped dependencies.
+        bindings: Explicit bindings. When supplied, only these dependencies are
+            included; an empty mapping selects none. Otherwise all declared
+            dependencies and contracts are available.
 
-        return call
+    Raises:
+        ValueError: A binding names an unknown dependency.
 
+    Access a client with ``clients[name]`` or ``clients.name``. Its
+    ``tools.<name>(**arguments)`` methods return structured output
+    and raise :class:`ToolCallError` for tool errors or additional input requests.
+    Use its ``call_tool`` method for the full result envelope.
+    """
 
-class Apps:
     def __init__(
         self,
         identity: dict[str, Any],
@@ -196,19 +255,14 @@ class Apps:
         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 ():
+        available = dict.fromkeys(identity["requires"]) | contracts
+        self._apps = {}
+        for name in available if bindings is None else bindings:
             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()
-        }
+            self._apps[name] = _App(
+                name, identity, available[name], bindings[name] if bindings else None
+            )
 
     def __getitem__(self, name: str) -> _App:
         return self._apps[name]

holon_sh-0.0.1.dev3/holon/view.py

@@ -0,0 +1,55 @@
+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:
+    """Create a server resource serving a built MCP App HTML file.
+
+    Args:
+        uri: Resource URI, normally starting with ``ui://``.
+        name: Human-readable resource name.
+        file: HTML file to read lazily on the first resource request.
+        connect_domains: Domains allowed for network connections by the view.
+        resource_domains: Domains allowed for external view assets.
+
+    Returns:
+        A ``FunctionResource`` ready for the MCP server's resource manager.
+        Successful reads are cached for the lifetime of this resource instance.
+
+    Raises:
+        OSError: Reading the HTML file failed.
+
+    Example:
+        ``resource = app_view("ui://app/index.html", "App", "dist/index.html")``
+    """
+    page = Path(file)
+    csp = {
+        "connectDomains": connect_domains or [],
+        "resourceDomains": resource_domains or [],
+    }
+    built: list[str] = []
+
+    def read() -> str:
+        # Concurrent first reads must all return the first cached build.
+        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 → holon_sh-0.0.1.dev3}/pyproject.toml

@@ -4,8 +4,9 @@ build-backend = "hatchling.build"
 
 [project]
 name = "holon-sh"
-version = "0.0.1.dev1"
+version = "0.0.1.dev3"
 description = "Typed MCP clients, bindings, and app views"
+readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
 requires-python = ">=3.11"
@@ -25,6 +26,7 @@ testpaths = ["tests"]
 
 [tool.ruff]
 target-version = "py311"
+extend-exclude = ["tests/fixtures"]
 
 [dependency-groups]
-dev = ["mcptype==0.0.6", "mypy==2.4.0", "pytest==9.1.1", "ruff==0.16.8", "types-jsonschema", "hatchling>=1.27,<2"]
+dev = ["mypy==2.4.0", "pytest==9.1.1", "ruff==0.16.8", "types-jsonschema", "hatchling>=1.27,<2"]

holon_sh-0.0.1.dev3/scripts/fixtures.sh

@@ -0,0 +1,7 @@
+#!/bin/sh
+set -eu
+
+# Run from any directory with the holon CLI on PATH. The orders server is
+# statically extracted; no running server or installed fixture dependencies are needed.
+cd "$(dirname "$0")/../tests/fixtures/caller"
+exec holon types generate -s ../orders

holon_sh-0.0.1.dev3/scripts/verify_distribution.py

@@ -0,0 +1,37 @@
+"""Install and test each built distribution in an isolated uv environment."""
+
+import subprocess
+import sys
+from importlib.metadata import version
+from pathlib import Path
+
+root = Path(__file__).resolve().parents[1]
+artifacts = sorted(root.glob("dist/holon_sh-*.whl")) + sorted(
+    root.glob("dist/holon_sh-*.tar.gz")
+)
+if len(artifacts) != 2:
+    raise RuntimeError("Build exactly one wheel and one sdist before verification.")
+for artifact in artifacts:
+    subprocess.run(
+        [
+            "uv",
+            "run",
+            "--isolated",
+            "--no-project",
+            "--no-config",
+            "--python",
+            sys.executable,
+            "--with",
+            str(artifact),
+            "--with",
+            f"pytest=={version('pytest')}",
+            "--with",
+            f"mypy=={version('mypy')}",
+            "python",
+            "-m",
+            "pytest",
+            str(root / "tests/test_package.py"),
+        ],
+        cwd=root / "dist",
+        check=True,
+    )