opentool-python 0.1.0__tar.gz

opentool_python-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenTool Hub
+
+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.

opentool_python-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: opentool-python
+Version: 0.1.0
+Summary: Python SDK for OpenTool-compatible clients and servers
+Author: OpenTool Hub
+License-Expression: MIT
+Project-URL: Repository, https://github.com/opentool-hub/opentool-python
+Project-URL: Issues, https://github.com/opentool-hub/opentool-python/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jsonschema[format]<5,>=4.22
+Requires-Dist: referencing<1,>=0.30
+Dynamic: license-file
+
+# OpenTool SDK for Python
+
+English | [中文](README-zh_CN.md)
+
+OpenTool SDK for Python provides the core building blocks to host or consume OpenTool-compatible tools in Python: an HTTP/JSON-RPC server runtime, an HTTP client with unary + SSE streaming calls, and a JSON schema loader. This project is designed to align with [opentool-dart](https://github.com/opentool-hub/opentool-dart) so multi-language SDK behavior stays consistent.
+
+## Library Entrypoints
+
+- `opentool_python.opentool_server` - server runtime, CLI argument helper, and Tool base class.
+- `opentool_python.opentool_client` - HTTP/JSON-RPC client plus DTO/LLM models.
+- `opentool_python.opentool_schema` - JSON specification models and loader.
+
+## Features
+
+- `OpenToolServer` mounts `/opentool` JSON-RPC endpoints backed by your `Tool` implementation, with optional Bearer API-key auth.
+- `OpenToolClient` supports version lookup, unary `call`, SSE `stream_call`, metadata `load`, and remote `stop`.
+- `OpenToolJsonLoader` parses OpenTool JSON specs and resolves `$ref` schema references.
+- End-to-end examples in `example/server.py` and `example/client.py` demonstrate CRUD + streaming usage.
+
+## Requirements
+
+- Python `>=3.10`
+- Schema validation uses `jsonschema` and `referencing`, installed with the SDK.
+
+## Installation
+
+Install from PyPI:
+
+```sh
+python -m pip install opentool-python
+```
+
+Install as editable package in local development:
+
+```sh
+pip install -e .
+```
+
+Or install with source path from another project:
+
+```sh
+pip install /absolute/path/to/opentool-python
+```
+
+## Quick Start
+
+### Implement a Tool
+
+```python
+from pathlib import Path
+from opentool_python.json_loader import OpenToolJsonLoader
+from opentool_python.opentool_server import (
+    CliTool,
+    EventType,
+    FunctionNotSupportedException,
+    OpenTool,
+)
+
+
+class MockTool(CliTool):
+    def call(self, name, arguments):
+        if name == "count":
+            return {"count": 1}
+        return FunctionNotSupportedException(function_name=name).to_json()
+
+    def stream_call(self, name, arguments, on_event):
+        if name == "sequentiallyRead":
+            on_event(EventType.DATA, {"data": "Hello"})
+        else:
+            on_event(
+                EventType.ERROR,
+                FunctionNotSupportedException(function_name=name).to_json(),
+            )
+
+    def load(self) -> OpenTool | None:
+        return OpenToolJsonLoader().load_from_file(
+            str(Path("example/mock_tool.json"))
+        )
+```
+
+### Launch the server
+
+```sh
+PYTHONPATH=src python example/server.py
+```
+
+`CliArguments` can pass built-in and custom CLI switches into your `CliTool.init_args`, so you can preload state before handlers accept requests.
+
+### Call the tool from Python
+
+```python
+from opentool_python.opentool_client import FunctionCall, HostType, OpenToolClient
+
+client = OpenToolClient(
+    tool_host=HostType.LOCALHOST,
+    tool_port=17002,
+    tool_api_key="your-key",
+)
+
+print(client.version().to_json())
+print(client.call(FunctionCall(id="call-0", name="count", arguments={})).to_json())
+
+client.stream_call(
+    FunctionCall(id="call-1", name="sequentiallyRead", arguments={}),
+    lambda event, tool_return: print(event, tool_return.result),
+)
+
+print(client.load().to_json())
+print(client.stop().to_json())
+```
+
+## CLI and HTTP Reference
+
+- Base path defaults to `/opentool`.
+- Endpoints:
+  - `GET /version`
+  - `POST /call`
+  - `POST /streamCall`
+  - `GET /load` returns HTTP 404 with code `TOOL_NOT_FOUND` when metadata is unavailable.
+  - `POST /stop`
+- Built-in CLI flags (via `CliArguments`):
+  - `--opentoolServerTag`
+  - `--opentoolServerHost`
+  - `--opentoolServerPort`
+  - repeatable `--opentoolServerApiKeys`
+- Streaming protocol is Server-Sent Events with event names `start`, `data`, `error`, and `done`.
+
+## JSON Specification Loader
+
+- Import `opentool_python.opentool_schema` if you only need spec models and parsing.
+- `OpenToolJsonLoader().load_from_file(path)` loads local files and resolves `$ref` entries under `#/schemas/*`.
+- `OpenToolJsonLoader().load(json_string)` loads from raw JSON strings.
+- Specification reference: [OpenTool Spec](https://github.com/opentool-hub/opentool-spec).
+
+Schemas default to JSON Schema Draft 2020-12. A recognized `$schema` selects its declared draft. `Schema.to_json()` returns a dictionary or boolean and preserves references, annotations, and extension keywords. Named `#/schemas/...` references are scoped to each OpenTool document, including documents loaded over HTTP.
+
+```python
+from opentool_python.opentool_schema import Schema
+
+schema = Schema.from_json({"type": "string", "minLength": 3})
+result = schema.validate("ab")
+print(result.is_valid, result.errors)
+```
+
+Use `validate_formats=True` to assert formats. To supply external schemas, pass a synchronous `schema_reference_resolver` callback to `OpenTool.from_json`, `OpenToolJsonLoader`, or `OpenToolClient`. The callback receives the resource URI and returns an object, a boolean, or `None` if unavailable.
+
+## Examples and Development
+
+- Example files:
+  - `example/server.py`
+  - `example/client.py`
+  - `example/mock_tool.json`
+- Common local workflow:
+
+```sh
+python -m compileall src example
+PYTHONPATH=src python example/server.py
+PYTHONPATH=src python example/client.py
+```
+
+## Compatibility Note
+
+This Python SDK is currently a baseline implementation focused on API shape and protocol compatibility with `opentool-dart`.

opentool_python-0.1.0/README.md

@@ -0,0 +1,163 @@
+# OpenTool SDK for Python
+
+English | [中文](README-zh_CN.md)
+
+OpenTool SDK for Python provides the core building blocks to host or consume OpenTool-compatible tools in Python: an HTTP/JSON-RPC server runtime, an HTTP client with unary + SSE streaming calls, and a JSON schema loader. This project is designed to align with [opentool-dart](https://github.com/opentool-hub/opentool-dart) so multi-language SDK behavior stays consistent.
+
+## Library Entrypoints
+
+- `opentool_python.opentool_server` - server runtime, CLI argument helper, and Tool base class.
+- `opentool_python.opentool_client` - HTTP/JSON-RPC client plus DTO/LLM models.
+- `opentool_python.opentool_schema` - JSON specification models and loader.
+
+## Features
+
+- `OpenToolServer` mounts `/opentool` JSON-RPC endpoints backed by your `Tool` implementation, with optional Bearer API-key auth.
+- `OpenToolClient` supports version lookup, unary `call`, SSE `stream_call`, metadata `load`, and remote `stop`.
+- `OpenToolJsonLoader` parses OpenTool JSON specs and resolves `$ref` schema references.
+- End-to-end examples in `example/server.py` and `example/client.py` demonstrate CRUD + streaming usage.
+
+## Requirements
+
+- Python `>=3.10`
+- Schema validation uses `jsonschema` and `referencing`, installed with the SDK.
+
+## Installation
+
+Install from PyPI:
+
+```sh
+python -m pip install opentool-python
+```
+
+Install as editable package in local development:
+
+```sh
+pip install -e .
+```
+
+Or install with source path from another project:
+
+```sh
+pip install /absolute/path/to/opentool-python
+```
+
+## Quick Start
+
+### Implement a Tool
+
+```python
+from pathlib import Path
+from opentool_python.json_loader import OpenToolJsonLoader
+from opentool_python.opentool_server import (
+    CliTool,
+    EventType,
+    FunctionNotSupportedException,
+    OpenTool,
+)
+
+
+class MockTool(CliTool):
+    def call(self, name, arguments):
+        if name == "count":
+            return {"count": 1}
+        return FunctionNotSupportedException(function_name=name).to_json()
+
+    def stream_call(self, name, arguments, on_event):
+        if name == "sequentiallyRead":
+            on_event(EventType.DATA, {"data": "Hello"})
+        else:
+            on_event(
+                EventType.ERROR,
+                FunctionNotSupportedException(function_name=name).to_json(),
+            )
+
+    def load(self) -> OpenTool | None:
+        return OpenToolJsonLoader().load_from_file(
+            str(Path("example/mock_tool.json"))
+        )
+```
+
+### Launch the server
+
+```sh
+PYTHONPATH=src python example/server.py
+```
+
+`CliArguments` can pass built-in and custom CLI switches into your `CliTool.init_args`, so you can preload state before handlers accept requests.
+
+### Call the tool from Python
+
+```python
+from opentool_python.opentool_client import FunctionCall, HostType, OpenToolClient
+
+client = OpenToolClient(
+    tool_host=HostType.LOCALHOST,
+    tool_port=17002,
+    tool_api_key="your-key",
+)
+
+print(client.version().to_json())
+print(client.call(FunctionCall(id="call-0", name="count", arguments={})).to_json())
+
+client.stream_call(
+    FunctionCall(id="call-1", name="sequentiallyRead", arguments={}),
+    lambda event, tool_return: print(event, tool_return.result),
+)
+
+print(client.load().to_json())
+print(client.stop().to_json())
+```
+
+## CLI and HTTP Reference
+
+- Base path defaults to `/opentool`.
+- Endpoints:
+  - `GET /version`
+  - `POST /call`
+  - `POST /streamCall`
+  - `GET /load` returns HTTP 404 with code `TOOL_NOT_FOUND` when metadata is unavailable.
+  - `POST /stop`
+- Built-in CLI flags (via `CliArguments`):
+  - `--opentoolServerTag`
+  - `--opentoolServerHost`
+  - `--opentoolServerPort`
+  - repeatable `--opentoolServerApiKeys`
+- Streaming protocol is Server-Sent Events with event names `start`, `data`, `error`, and `done`.
+
+## JSON Specification Loader
+
+- Import `opentool_python.opentool_schema` if you only need spec models and parsing.
+- `OpenToolJsonLoader().load_from_file(path)` loads local files and resolves `$ref` entries under `#/schemas/*`.
+- `OpenToolJsonLoader().load(json_string)` loads from raw JSON strings.
+- Specification reference: [OpenTool Spec](https://github.com/opentool-hub/opentool-spec).
+
+Schemas default to JSON Schema Draft 2020-12. A recognized `$schema` selects its declared draft. `Schema.to_json()` returns a dictionary or boolean and preserves references, annotations, and extension keywords. Named `#/schemas/...` references are scoped to each OpenTool document, including documents loaded over HTTP.
+
+```python
+from opentool_python.opentool_schema import Schema
+
+schema = Schema.from_json({"type": "string", "minLength": 3})
+result = schema.validate("ab")
+print(result.is_valid, result.errors)
+```
+
+Use `validate_formats=True` to assert formats. To supply external schemas, pass a synchronous `schema_reference_resolver` callback to `OpenTool.from_json`, `OpenToolJsonLoader`, or `OpenToolClient`. The callback receives the resource URI and returns an object, a boolean, or `None` if unavailable.
+
+## Examples and Development
+
+- Example files:
+  - `example/server.py`
+  - `example/client.py`
+  - `example/mock_tool.json`
+- Common local workflow:
+
+```sh
+python -m compileall src example
+PYTHONPATH=src python example/server.py
+PYTHONPATH=src python example/client.py
+```
+
+## Compatibility Note
+
+This Python SDK is currently a baseline implementation focused on API shape and protocol compatibility with `opentool-dart`.

opentool_python-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=77.0.3", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "opentool-python"
+version = "0.1.0"
+description = "Python SDK for OpenTool-compatible clients and servers"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+  { name = "OpenTool Hub" }
+]
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent"
+]
+dependencies = ["jsonschema[format]>=4.22,<5", "referencing>=0.30,<1"]
+
+[project.urls]
+Repository = "https://github.com/opentool-hub/opentool-python"
+Issues = "https://github.com/opentool-hub/opentool-python/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

opentool_python-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

opentool_python-0.1.0/src/opentool_python/__init__.py

@@ -0,0 +1,62 @@
+"""OpenTool SDK for Python."""
+
+from .dto import (
+    CLI_ARGUMENT_APIKEYS,
+    CLI_ARGUMENT_HOST,
+    CLI_ARGUMENT_PORT,
+    CLI_ARGUMENT_TAG,
+    DEFAULT_PREFIX,
+    DEFAULT_TOOL_HOST,
+    DEFAULT_TOOL_PORT,
+    DEFAULT_TOOL_TAG,
+    HostType,
+    JsonRPCHttpRequestBody,
+    JsonRPCHttpResponseBody,
+    JsonRPCHttpResponseBodyError,
+    StatusInfo,
+    StatusType,
+    Version,
+)
+from .json_loader import OpenToolJsonLoader
+from .llm.model import FunctionCall, ToolReturn
+from .model.data_type import DataType
+from .model.function_model import FunctionModel
+from .model.info import Info
+from .model.opentool import OpenTool
+from .model.parameter import Parameter
+from .model.return_model import Return
+from .model.schema import Schema, SchemaReferenceResolver, SchemaResolver, SchemaType, SchemaValidationResult
+from .model.server import ServerConfig
+
+__all__ = [
+    "HostType",
+    "Version",
+    "JsonRPCHttpRequestBody",
+    "JsonRPCHttpResponseBody",
+    "JsonRPCHttpResponseBodyError",
+    "StatusInfo",
+    "StatusType",
+    "DEFAULT_PREFIX",
+    "DEFAULT_TOOL_TAG",
+    "DEFAULT_TOOL_HOST",
+    "DEFAULT_TOOL_PORT",
+    "CLI_ARGUMENT_TAG",
+    "CLI_ARGUMENT_HOST",
+    "CLI_ARGUMENT_PORT",
+    "CLI_ARGUMENT_APIKEYS",
+    "FunctionCall",
+    "ToolReturn",
+    "DataType",
+    "FunctionModel",
+    "Info",
+    "OpenTool",
+    "Parameter",
+    "Return",
+    "Schema",
+    "SchemaType",
+    "SchemaReferenceResolver",
+    "SchemaResolver",
+    "SchemaValidationResult",
+    "ServerConfig",
+    "OpenToolJsonLoader",
+]

opentool_python-0.1.0/src/opentool_python/client/__init__.py

@@ -0,0 +1,18 @@
+from .exceptions import (
+    ErrorNullException,
+    OpenToolServerCallException,
+    OpenToolServerNoAccessException,
+    OpenToolServerUnauthorizedException,
+    ResponseNullException,
+)
+from .opentool_client import Client, OpenToolClient
+
+__all__ = [
+    "Client",
+    "OpenToolClient",
+    "ResponseNullException",
+    "ErrorNullException",
+    "OpenToolServerUnauthorizedException",
+    "OpenToolServerNoAccessException",
+    "OpenToolServerCallException",
+]

opentool_python-0.1.0/src/opentool_python/client/exceptions.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class ResponseNullException(Exception):
+    code: int
+    message: str = "Response is null"
+
+    def to_json(self) -> dict[str, Any]:
+        return {"code": self.code, "message": self.message}
+
+
+@dataclass
+class ErrorNullException(Exception):
+    code: int
+    message: str = "Error is null"
+
+    def to_json(self) -> dict[str, Any]:
+        return {"code": self.code, "message": self.message}
+
+
+@dataclass
+class OpenToolServerUnauthorizedException(Exception):
+    code: int = 401
+    message: str = "Please check API Key is VALID or NOT"
+
+    def to_json(self) -> dict[str, Any]:
+        return {"code": self.code, "message": self.message}
+
+
+@dataclass
+class OpenToolServerNoAccessException(Exception):
+    code: int = 404
+    message: str = "Please check OpenTool Server is RUNNING or NOT"
+
+    def to_json(self) -> dict[str, Any]:
+        return {"code": self.code, "message": self.message}
+
+
+@dataclass
+class OpenToolServerCallException(Exception):
+    message: str
+
+    def to_json(self) -> dict[str, Any]:
+        return {"message": self.message}