holon-sh 0.0.1.dev6__tar.gz → 0.0.1.dev7__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.
@@ -0,0 +1,84 @@
1
+ Metadata-Version: 2.5
2
+ Name: holon-sh
3
+ Version: 0.0.1.dev7
4
+ Summary: Typed MCP clients and the caller of an MCP request
5
+ Project-URL: Repository, https://github.com/holon-sh/sdk-py
6
+ License-Expression: Apache-2.0
7
+ License-File: LICENSE
8
+ Requires-Python: >=3.11
9
+ Requires-Dist: httpx2<3,>=2.10
10
+ Requires-Dist: jsonschema<5,>=4.26
11
+ Requires-Dist: mcp<3,>=2.3
12
+ Description-Content-Type: text/markdown
13
+
14
+ # Holon Python SDK
15
+
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/)
18
+ [![PyPI](https://img.shields.io/pypi/v/holon-sh)](https://pypi.org/project/holon-sh/)
19
+ [![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/downloads/)
20
+ [![Apache 2.0 License](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE)
21
+ [![Discord](https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/jXExyBdy)
22
+
23
+ This repository contains the Python runtime for [`holon`](https://github.com/holon-sh/cli).
24
+
25
+ ## Install
26
+
27
+ ```sh
28
+ uv add --prerelease allow holon-sh
29
+ uv add --dev holon-types
30
+ ```
31
+
32
+ ## Create an app
33
+
34
+ ```sh
35
+ uvx create-holon-app foo
36
+ ```
37
+
38
+ ## Invoking MCP Servers
39
+
40
+ Declare dependencies under `sh.holon.requires` in a [`server.json`](https://modelcontextprotocol.io/registry/quickstart#step-4-create-server-json) beside the server, here the public [Hugging Face](https://huggingface.co/docs/hub/en/hf-mcp-server) MCP server:
41
+
42
+ ```json
43
+ {
44
+ "name": "com.example/foo",
45
+ "version": "0.1.0",
46
+ "description": "Example Foo",
47
+ "_meta": {
48
+ "io.modelcontextprotocol.registry/publisher-provided": {
49
+ "sh.holon": {
50
+ "requires": {
51
+ "huggingface": { "url": "https://huggingface.co/mcp" }
52
+ }
53
+ }
54
+ }
55
+ }
56
+ }
57
+ ```
58
+
59
+ ### Type-checking MCP invocations
60
+
61
+ ```sh
62
+ uv run holon types check
63
+ ```
64
+
65
+ A wrong tool name or argument is a type error:
66
+
67
+ ```python
68
+ from holon.apps import apps
69
+
70
+ await apps.huggingface.tools.hub_repo_search(query="llama")
71
+
72
+ await apps.huggingface.tools.hub_repo_search(limit="3")
73
+ # error: Argument "limit" to "hub_repo_search" of "HuggingfaceTools" has incompatible type "str"; expected "float" [arg-type]
74
+
75
+ await apps.huggingface.tools.hub_repo_details()
76
+ # error: Missing named argument "repo_ids" for "hub_repo_details" of "HuggingfaceTools" [call-arg]
77
+
78
+ await apps.huggingface.tools.hub_search(query="llama")
79
+ # error: "HuggingfaceTools" has no attribute "hub_search"; maybe "hub_repo_search"? [attr-defined]
80
+ ```
81
+
82
+ ## Community
83
+
84
+ Ask questions and share what you're building on the [Holon Discord](https://discord.gg/jXExyBdy).
@@ -0,0 +1,71 @@
1
+ # Holon Python SDK
2
+
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/)
5
+ [![PyPI](https://img.shields.io/pypi/v/holon-sh)](https://pypi.org/project/holon-sh/)
6
+ [![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/downloads/)
7
+ [![Apache 2.0 License](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE)
8
+ [![Discord](https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/jXExyBdy)
9
+
10
+ This repository contains the Python runtime for [`holon`](https://github.com/holon-sh/cli).
11
+
12
+ ## Install
13
+
14
+ ```sh
15
+ uv add --prerelease allow holon-sh
16
+ uv add --dev holon-types
17
+ ```
18
+
19
+ ## Create an app
20
+
21
+ ```sh
22
+ uvx create-holon-app foo
23
+ ```
24
+
25
+ ## Invoking MCP Servers
26
+
27
+ Declare dependencies under `sh.holon.requires` in a [`server.json`](https://modelcontextprotocol.io/registry/quickstart#step-4-create-server-json) beside the server, here the public [Hugging Face](https://huggingface.co/docs/hub/en/hf-mcp-server) MCP server:
28
+
29
+ ```json
30
+ {
31
+ "name": "com.example/foo",
32
+ "version": "0.1.0",
33
+ "description": "Example Foo",
34
+ "_meta": {
35
+ "io.modelcontextprotocol.registry/publisher-provided": {
36
+ "sh.holon": {
37
+ "requires": {
38
+ "huggingface": { "url": "https://huggingface.co/mcp" }
39
+ }
40
+ }
41
+ }
42
+ }
43
+ }
44
+ ```
45
+
46
+ ### Type-checking MCP invocations
47
+
48
+ ```sh
49
+ uv run holon types check
50
+ ```
51
+
52
+ A wrong tool name or argument is a type error:
53
+
54
+ ```python
55
+ from holon.apps import apps
56
+
57
+ await apps.huggingface.tools.hub_repo_search(query="llama")
58
+
59
+ await apps.huggingface.tools.hub_repo_search(limit="3")
60
+ # error: Argument "limit" to "hub_repo_search" of "HuggingfaceTools" has incompatible type "str"; expected "float" [arg-type]
61
+
62
+ await apps.huggingface.tools.hub_repo_details()
63
+ # error: Missing named argument "repo_ids" for "hub_repo_details" of "HuggingfaceTools" [call-arg]
64
+
65
+ await apps.huggingface.tools.hub_search(query="llama")
66
+ # error: "HuggingfaceTools" has no attribute "hub_search"; maybe "hub_repo_search"? [attr-defined]
67
+ ```
68
+
69
+ ## Community
70
+
71
+ Ask questions and share what you're building on the [Holon Discord](https://discord.gg/jXExyBdy).
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "holon-sh"
7
- version = "0.0.1.dev6"
7
+ version = "0.0.1.dev7"
8
8
  description = "Typed MCP clients and the caller of an MCP request"
9
9
  readme = "README.md"
10
10
  license = "Apache-2.0"
@@ -1,3 +1,5 @@
1
+ """Consumer contracts at the generated namespace boundary."""
2
+
1
3
  import os
2
4
  import shutil
3
5
  import subprocess
@@ -6,18 +8,7 @@ from pathlib import Path
6
8
 
7
9
 
8
10
  def test_generated_namespace_combines_app_types_with_installed_runtime(tmp_path):
9
- env = os.environ.copy()
10
- env.pop("MYPYPATH", None)
11
- env.pop("PYTHONPATH", None)
12
- placeholder = subprocess.run(
13
- [sys.executable, "-c", "import holon.apps"],
14
- cwd=tmp_path,
15
- env=env,
16
- capture_output=True,
17
- text=True,
18
- check=False,
19
- )
20
- assert "run `holon types generate`" in placeholder.stderr
11
+ # Refresh with scripts/fixtures.sh; generation is tested in holon-sh/cli.
21
12
  shutil.copytree(
22
13
  Path(__file__).parent / "fixtures/caller", tmp_path, dirs_exist_ok=True
23
14
  )
@@ -57,6 +48,11 @@ async def invalid() -> None:
57
48
  assert holon.__file__ is None
58
49
  assert Path(holon.client.__file__).parent != Path(__file__).parent / "holon"
59
50
  """)
51
+ # Runtime and typing must agree across the two namespace portions. No
52
+ # MYPYPATH/PYTHONPATH override is allowed to hide packaging problems.
53
+ env = os.environ.copy()
54
+ env.pop("MYPYPATH", None)
55
+ env.pop("PYTHONPATH", None)
60
56
  result = subprocess.run(
61
57
  [sys.executable, "-m", "mypy", "--strict", "--no-error-summary", "check.py"],
62
58
  cwd=tmp_path,
@@ -69,14 +65,3 @@ assert Path(holon.client.__file__).parent != Path(__file__).parent / "holon"
69
65
  assert len(result.stdout.splitlines()) == 1, result.stdout
70
66
  assert '"OrdersApp" has no attribute "missing"' in result.stdout
71
67
  subprocess.run([sys.executable, "check.py"], cwd=tmp_path, env=env, check=True)
72
- (tmp_path / "later").mkdir()
73
- subprocess.run(
74
- [
75
- sys.executable,
76
- "-c",
77
- "import sys; sys.path.append('..'); from holon.apps import apps",
78
- ],
79
- cwd=tmp_path / "later",
80
- env=env,
81
- check=True,
82
- )
@@ -1,122 +0,0 @@
1
- Metadata-Version: 2.5
2
- Name: holon-sh
3
- Version: 0.0.1.dev6
4
- Summary: Typed MCP clients and the caller of an MCP request
5
- Project-URL: Repository, https://github.com/holon-sh/sdk-py
6
- License-Expression: Apache-2.0
7
- License-File: LICENSE
8
- Requires-Python: >=3.11
9
- Requires-Dist: httpx2<3,>=2.10
10
- Requires-Dist: jsonschema<5,>=4.26
11
- Requires-Dist: mcp<3,>=2.3
12
- Description-Content-Type: text/markdown
13
-
14
- # Holon Python SDK
15
-
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
- [![PyPI](https://img.shields.io/pypi/v/holon-sh)](https://pypi.org/project/holon-sh/)
18
- [![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/downloads/)
19
- [![Apache 2.0 License](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE)
20
-
21
- This repository contains the Python runtime for [`holon`](https://github.com/holon-sh/cli).
22
-
23
- ## Install
24
-
25
- ```sh
26
- uv add --prerelease allow holon-sh
27
- uv add --dev holon-types
28
- ```
29
-
30
- `holon-types` is the `holon` CLI; it brings mypy, which `holon types check` runs from the project's environment.
31
-
32
- ## Invoking MCP Servers
33
-
34
- 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.
35
-
36
- ### Type-checking MCP invocations
37
-
38
- ```sh
39
- uv run holon types check
40
- ```
41
-
42
- <details open>
43
- <summary><h3>Call a tool</h3></summary>
44
-
45
- ```python
46
- from holon.apps import apps
47
-
48
-
49
- async def greet(name: str) -> str:
50
- greeting = await apps.bar.tools.greet({"timeout": 5.0}, name=name)
51
- return greeting["result"]
52
- ```
53
-
54
- Arguments are keywords; the result is validated against the output schema and returned.
55
-
56
- </details>
57
-
58
- <details open>
59
- <summary><h3>Handle errors</h3></summary>
60
-
61
- ```python
62
- from holon.client import ToolCallError
63
-
64
- try:
65
- await apps.bar.tools.greet(name="world")
66
- except ToolCallError as error:
67
- error.result # the original MCP result
68
- ```
69
-
70
- </details>
71
-
72
- <details open>
73
- <summary><h3>Read the whole result</h3></summary>
74
-
75
- `call_tool` returns the full MCP result instead of raising:
76
-
77
- ```python
78
- result = await apps.bar.call_tool("greet", name="world")
79
- if result.result_type == "input_required":
80
- ... # call again with input_responses and request_state
81
- elif result.is_error:
82
- ... # inspect result.content
83
- else:
84
- result.structured_content # typed as Outputs.bar.greet
85
- ```
86
-
87
- The options dict also accepts `input_responses`, `request_state` and `meta`.
88
-
89
- </details>
90
-
91
- <details open>
92
- <summary><h3>Answer a server's question</h3></summary>
93
-
94
- A tool can stop and ask for input through an [MCP elicitation](https://modelcontextprotocol.io/specification/2026-07-28/client/elicitation). Pass `elicit` to answer in place, and the call returns its usual typed output:
95
-
96
- ```python
97
- from mcp.types import ElicitResult
98
-
99
-
100
- async def elicit(params):
101
- return ElicitResult(action="accept", content=await ask(params.message))
102
-
103
-
104
- greeting = await apps.bar.tools.greet({"elicit": elicit}, name="world")
105
- ```
106
-
107
- Without `elicit`, the question arrives on `ToolCallError.result`, or as an `input_required` result from `call_tool`. To answer later, for example in another request, call again with `input_responses` and `request_state`.
108
-
109
- </details>
110
-
111
- ## Identify the caller
112
-
113
- Inside a tool handler, `get_context().principal` is the user Holon admitted for the request, or `None` for anonymous requests:
114
-
115
- ```python
116
- from holon.context import get_context
117
-
118
- principal = get_context().principal
119
- if principal is not None:
120
- principal.issuer, principal.subject, principal.scopes
121
- principal.claims.get("email") # standard OpenID claims are typed: str | None
122
- ```
@@ -1,109 +0,0 @@
1
- # Holon Python SDK
2
-
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
- [![PyPI](https://img.shields.io/pypi/v/holon-sh)](https://pypi.org/project/holon-sh/)
5
- [![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/downloads/)
6
- [![Apache 2.0 License](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE)
7
-
8
- This repository contains the Python runtime for [`holon`](https://github.com/holon-sh/cli).
9
-
10
- ## Install
11
-
12
- ```sh
13
- uv add --prerelease allow holon-sh
14
- uv add --dev holon-types
15
- ```
16
-
17
- `holon-types` is the `holon` CLI; it brings mypy, which `holon types check` runs from the project's environment.
18
-
19
- ## Invoking MCP Servers
20
-
21
- 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.
22
-
23
- ### Type-checking MCP invocations
24
-
25
- ```sh
26
- uv run holon types check
27
- ```
28
-
29
- <details open>
30
- <summary><h3>Call a tool</h3></summary>
31
-
32
- ```python
33
- from holon.apps import apps
34
-
35
-
36
- async def greet(name: str) -> str:
37
- greeting = await apps.bar.tools.greet({"timeout": 5.0}, name=name)
38
- return greeting["result"]
39
- ```
40
-
41
- Arguments are keywords; the result is validated against the output schema and returned.
42
-
43
- </details>
44
-
45
- <details open>
46
- <summary><h3>Handle errors</h3></summary>
47
-
48
- ```python
49
- from holon.client import ToolCallError
50
-
51
- try:
52
- await apps.bar.tools.greet(name="world")
53
- except ToolCallError as error:
54
- error.result # the original MCP result
55
- ```
56
-
57
- </details>
58
-
59
- <details open>
60
- <summary><h3>Read the whole result</h3></summary>
61
-
62
- `call_tool` returns the full MCP result instead of raising:
63
-
64
- ```python
65
- result = await apps.bar.call_tool("greet", name="world")
66
- if result.result_type == "input_required":
67
- ... # call again with input_responses and request_state
68
- elif result.is_error:
69
- ... # inspect result.content
70
- else:
71
- result.structured_content # typed as Outputs.bar.greet
72
- ```
73
-
74
- The options dict also accepts `input_responses`, `request_state` and `meta`.
75
-
76
- </details>
77
-
78
- <details open>
79
- <summary><h3>Answer a server's question</h3></summary>
80
-
81
- A tool can stop and ask for input through an [MCP elicitation](https://modelcontextprotocol.io/specification/2026-07-28/client/elicitation). Pass `elicit` to answer in place, and the call returns its usual typed output:
82
-
83
- ```python
84
- from mcp.types import ElicitResult
85
-
86
-
87
- async def elicit(params):
88
- return ElicitResult(action="accept", content=await ask(params.message))
89
-
90
-
91
- greeting = await apps.bar.tools.greet({"elicit": elicit}, name="world")
92
- ```
93
-
94
- Without `elicit`, the question arrives on `ToolCallError.result`, or as an `input_required` result from `call_tool`. To answer later, for example in another request, call again with `input_responses` and `request_state`.
95
-
96
- </details>
97
-
98
- ## Identify the caller
99
-
100
- Inside a tool handler, `get_context().principal` is the user Holon admitted for the request, or `None` for anonymous requests:
101
-
102
- ```python
103
- from holon.context import get_context
104
-
105
- principal = get_context().principal
106
- if principal is not None:
107
- principal.issuer, principal.subject, principal.scopes
108
- principal.claims.get("email") # standard OpenID claims are typed: str | None
109
- ```
@@ -1,19 +0,0 @@
1
- import sys
2
- from importlib.util import module_from_spec, spec_from_file_location
3
- from pathlib import Path
4
-
5
- import holon
6
-
7
- _here = Path(__file__).resolve().parent
8
- for _portion in holon.__path__:
9
- _generated = Path(_portion, "apps")
10
- if _generated.resolve() != _here and (_generated / "__init__.py").is_file():
11
- _spec = spec_from_file_location(__name__, _generated / "__init__.py")
12
- assert _spec and _spec.loader
13
- sys.modules[__name__] = _module = module_from_spec(_spec)
14
- _spec.loader.exec_module(_module)
15
- break
16
- else:
17
- raise ImportError(
18
- "no generated holon.apps on sys.path: run `holon types generate` in the project"
19
- )
File without changes
File without changes