opentool-python 0.1.0__py3-none-any.whl

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/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/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}

opentool_python/client/opentool_client.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+import json
+import socket
+from abc import ABC, abstractmethod
+from collections.abc import Callable, Iterator
+from typing import Any
+from urllib import error, parse, request
+
+from ..dto import (
+    DEFAULT_PREFIX,
+    LOAD_METADATA_NOT_FOUND_CODE,
+    JsonRPCHttpRequestBody,
+    JsonRPCHttpResponseBody,
+    StatusInfo,
+    Version,
+)
+from ..llm.model import FunctionCall, ToolReturn
+from ..model.opentool import OpenTool
+from ..model.schema import SchemaReferenceResolver
+from ..tool.model import EventType
+from .exceptions import (
+    OpenToolServerCallException,
+    OpenToolServerNoAccessException,
+    OpenToolServerUnauthorizedException,
+)
+
+
+class Client(ABC):
+    @abstractmethod
+    def version(self) -> Version:
+        raise NotImplementedError
+
+    @abstractmethod
+    def call(self, function_call: FunctionCall) -> ToolReturn:
+        raise NotImplementedError
+
+    @abstractmethod
+    def stream_call(
+        self,
+        function_call: FunctionCall,
+        on_stream: Callable[[str, ToolReturn], None],
+    ) -> None:
+        raise NotImplementedError
+
+    def load(self) -> OpenTool | None:
+        return None
+
+    @abstractmethod
+    def stop(self) -> StatusInfo | None:
+        raise NotImplementedError
+
+
+class OpenToolClient(Client):
+    def __init__(
+        self,
+        *,
+        tool_host: str,
+        tool_port: int,
+        tool_api_key: str | None = None,
+        is_ssl: bool = False,
+        schema_reference_resolver: SchemaReferenceResolver | None = None,
+    ) -> None:
+        self.schema_reference_resolver = schema_reference_resolver
+        self.is_ssl = is_ssl
+        self.host = tool_host
+        self.port = tool_port
+        self.prefix = DEFAULT_PREFIX
+        self.tool_api_key = tool_api_key
+        protocol = "https" if self.is_ssl else "http"
+        self.base_url = f"{protocol}://{self.host}:{self.port}{self.prefix}"
+
+    def version(self) -> Version:
+        data = self._request_json("GET", "/version")
+        return Version.from_json(data)
+
+    def call(self, function_call: FunctionCall) -> ToolReturn:
+        result = self._call_json_rpc_http(
+            function_call.id,
+            function_call.name,
+            function_call.arguments,
+        )
+        return ToolReturn(id=function_call.id, result=result)
+
+    def _call_json_rpc_http(
+        self,
+        request_id: str,
+        method: str,
+        params: dict[str, Any],
+    ) -> dict[str, Any]:
+        body = JsonRPCHttpRequestBody(id=request_id, method=method, params=params)
+        data = self._request_json("POST", "/call", body.to_json())
+        response_body = JsonRPCHttpResponseBody.from_json(data)
+        if response_body.error is not None:
+            raise OpenToolServerCallException(response_body.error.message)
+        return response_body.result
+
+    def stream_call(
+        self,
+        function_call: FunctionCall,
+        on_stream: Callable[[str, ToolReturn], None],
+    ) -> None:
+        body = JsonRPCHttpRequestBody(
+            id=function_call.id,
+            method=function_call.name,
+            params=function_call.arguments,
+        )
+
+        for event_name, event_data in self._stream_call_json_rpc_http(body.to_json()):
+            event_name = event_name.lower()
+            if event_name == EventType.START:
+                on_stream(event_name, ToolReturn(id=function_call.id, result=event_data))
+            elif event_name == EventType.DONE:
+                break
+            elif event_name in (EventType.DATA, EventType.ERROR):
+                response_body = JsonRPCHttpResponseBody.from_json(event_data)
+                if response_body.error is not None:
+                    raise OpenToolServerCallException(response_body.error.message)
+                if event_name == EventType.ERROR:
+                    raise OpenToolServerCallException(str(event_data.get("message", event_data)))
+                on_stream(event_name, ToolReturn(id=function_call.id, result=response_body.result))
+
+        on_stream(
+            EventType.DONE,
+            ToolReturn(id=function_call.id, result={EventType.DONE: function_call.name}),
+        )
+
+    def _stream_call_json_rpc_http(
+        self, payload: dict[str, Any]
+    ) -> Iterator[tuple[str, dict[str, Any]]]:
+        url = f"{self.base_url}/streamCall"
+        request_data = json.dumps(payload).encode("utf-8")
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "text/event-stream",
+        }
+        if self.tool_api_key:
+            headers["Authorization"] = f"Bearer {self.tool_api_key}"
+
+        req = request.Request(url=url, method="POST", data=request_data, headers=headers)
+        try:
+            with request.urlopen(req, timeout=60) as response:
+                if response.status == 401:
+                    raise OpenToolServerUnauthorizedException()
+                buffer: list[str] = []
+                for raw_line in response:
+                    line = raw_line.decode("utf-8").rstrip("\r\n")
+                    if line == "":
+                        event_name, event_data = _parse_sse_block(buffer)
+                        buffer = []
+                        if event_name is not None and event_data is not None:
+                            yield event_name, event_data
+                        continue
+                    buffer.append(line)
+                if buffer:
+                    event_name, event_data = _parse_sse_block(buffer)
+                    if event_name is not None and event_data is not None:
+                        yield event_name, event_data
+        except error.HTTPError as exc:
+            if exc.code == 401:
+                raise OpenToolServerUnauthorizedException() from exc
+            message = exc.read().decode("utf-8", errors="ignore")
+            raise OpenToolServerCallException(f"HTTP {exc.code} {message}") from exc
+        except (socket.timeout, error.URLError) as exc:
+            raise OpenToolServerNoAccessException() from exc
+
+    def load(self) -> OpenTool | None:
+        data = self._request_json("GET", "/load")
+        if data.get("code") == LOAD_METADATA_NOT_FOUND_CODE or (
+            data.get("code") == 404 and data.get("message") == "Json Parser NOT implement"
+        ):
+            return None
+        return OpenTool.from_json(data, schema_reference_resolver=self.schema_reference_resolver)
+
+    def stop(self) -> StatusInfo | None:
+        try:
+            data = self._request_json("POST", "/stop")
+            return StatusInfo.from_json(data)
+        except Exception:
+            return None
+
+    def _request_json(
+        self,
+        method: str,
+        path: str,
+        body: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        url = parse.urljoin(f"{self.base_url}/", path.lstrip("/"))
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+        if self.tool_api_key:
+            headers["Authorization"] = f"Bearer {self.tool_api_key}"
+
+        data = json.dumps(body).encode("utf-8") if body is not None else None
+        req = request.Request(url=url, method=method, data=data, headers=headers)
+
+        try:
+            with request.urlopen(req, timeout=20) as response:
+                payload = response.read().decode("utf-8")
+                return json.loads(payload) if payload else {}
+        except error.HTTPError as exc:
+            if exc.code == 401:
+                raise OpenToolServerUnauthorizedException() from exc
+            message = exc.read().decode("utf-8", errors="replace")
+            if path == "/load" and exc.code == 404:
+                try:
+                    data = json.loads(message)
+                except json.JSONDecodeError:
+                    data = None
+                if isinstance(data, dict) and data.get("code") == LOAD_METADATA_NOT_FOUND_CODE:
+                    return data
+            raise OpenToolServerCallException(f"HTTP {exc.code} {message}") from exc
+        except (socket.timeout, error.URLError) as exc:
+            raise OpenToolServerNoAccessException() from exc
+
+
+def _parse_sse_block(lines: list[str]) -> tuple[str | None, dict[str, Any] | None]:
+    event_name: str | None = None
+    data_lines: list[str] = []
+
+    for line in lines:
+        if line.startswith("event:"):
+            event_name = line[len("event:") :].strip()
+        elif line.startswith("data:"):
+            data_lines.append(line[len("data:") :].removeprefix(" "))
+
+    if event_name is None or not data_lines:
+        return None, None
+
+    try:
+        payload = json.loads("\n".join(data_lines))
+    except json.JSONDecodeError as exc:
+        raise OpenToolServerCallException(f"Invalid SSE JSON: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise OpenToolServerCallException("Expected an SSE JSON object")
+    return event_name, payload

opentool_python/dto.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+JSONRPC_VERSION = "2.0"
+LOAD_METADATA_NOT_FOUND_CODE = "TOOL_NOT_FOUND"
+LOAD_METADATA_NOT_FOUND_MESSAGE = "Tool metadata not found"
+DEFAULT_PREFIX = "/opentool"
+DEFAULT_TOOL_TAG = "N/A"
+DEFAULT_TOOL_HOST = "0.0.0.0"
+DEFAULT_TOOL_PORT = 17001
+CLI_ARGUMENT_TAG = "opentoolServerTag"
+CLI_ARGUMENT_HOST = "opentoolServerHost"
+CLI_ARGUMENT_PORT = "opentoolServerPort"
+CLI_ARGUMENT_APIKEYS = "opentoolServerApiKeys"
+
+
+class HostType:
+    ANY = "0.0.0.0"
+    LOCALHOST = "127.0.0.1"
+
+
+@dataclass
+class Version:
+    version: str
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "Version":
+        return cls(version=str(data["version"]))
+
+    def to_json(self) -> dict[str, Any]:
+        return {"version": self.version}
+
+
+@dataclass
+class JsonRPCHttpRequestBody:
+    method: str
+    params: dict[str, Any] | None
+    id: str
+    jsonrpc: str = JSONRPC_VERSION
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "JsonRPCHttpRequestBody":
+        method, request_id = data["method"], data["id"]
+        params = data.get("params")
+        version = data.get("jsonrpc", JSONRPC_VERSION)
+        if not isinstance(method, str) or not isinstance(request_id, str):
+            raise ValueError("method and id must be strings")
+        if params is not None and not isinstance(params, dict):
+            raise ValueError("params must be an object or null")
+        if not isinstance(version, str):
+            raise ValueError("jsonrpc must be a string")
+        return cls(method=method, params=params, id=request_id, jsonrpc=version)
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "jsonrpc": self.jsonrpc,
+            "method": self.method,
+            "id": self.id,
+            **({"params": self.params} if self.params is not None else {}),
+        }
+
+
+@dataclass
+class JsonRPCHttpResponseBodyError:
+    code: int
+    message: str
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "JsonRPCHttpResponseBodyError":
+        return cls(code=int(data["code"]), message=str(data["message"]))
+
+    def to_json(self) -> dict[str, Any]:
+        return {"code": self.code, "message": self.message}
+
+
+@dataclass
+class JsonRPCHttpResponseBody:
+    result: dict[str, Any] = field(default_factory=dict)
+    id: str = ""
+    error: JsonRPCHttpResponseBodyError | None = None
+    jsonrpc: str = JSONRPC_VERSION
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "JsonRPCHttpResponseBody":
+        error_data = data.get("error")
+        error = (
+            JsonRPCHttpResponseBodyError.from_json(error_data)
+            if isinstance(error_data, dict)
+            else None
+        )
+        return cls(
+            result=data.get("result") or {},
+            id=str(data.get("id", "")),
+            error=error,
+            jsonrpc=str(data.get("jsonrpc", JSONRPC_VERSION)),
+        )
+
+    def to_json(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "jsonrpc": self.jsonrpc,
+            "result": self.result,
+            "id": self.id,
+        }
+        if self.error is not None:
+            payload["error"] = self.error.to_json()
+        return payload
+
+
+class StatusType:
+    STOPPED = "stopped"
+
+
+@dataclass
+class StatusInfo:
+    status: str
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "StatusInfo":
+        return cls(status=str(data["status"]))
+
+    def to_json(self) -> dict[str, Any]:
+        return {"status": self.status}

opentool_python/json_loader.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .model.opentool import OpenTool
+from .model.schema import SchemaReferenceResolver
+
+
+class OpenToolJsonLoader:
+    def __init__(self, *, schema_reference_resolver: SchemaReferenceResolver | None = None) -> None:
+        self.schema_reference_resolver = schema_reference_resolver
+        self.schemas_json: dict[str, object] | None = None
+
+    def load(self, json_string: str) -> OpenTool:
+        opentool_map = json.loads(json_string)
+        self.schemas_json = opentool_map.get("schemas")
+        return OpenTool.from_json(
+            opentool_map, schema_reference_resolver=self.schema_reference_resolver
+        )
+
+    def load_from_file(self, json_path: str) -> OpenTool:
+        return self.load(Path(json_path).read_text(encoding="utf-8"))

opentool_python/llm/__init__.py

@@ -0,0 +1,3 @@
+from .model import FunctionCall, ToolReturn
+
+__all__ = ["FunctionCall", "ToolReturn"]

opentool_python/llm/model.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class FunctionCall:
+    id: str
+    name: str
+    arguments: dict[str, Any]
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "FunctionCall":
+        return cls(
+            id=str(data["id"]),
+            name=str(data["name"]),
+            arguments=data.get("arguments") or {},
+        )
+
+    def to_json(self) -> dict[str, Any]:
+        return {"id": self.id, "name": self.name, "arguments": self.arguments}
+
+
+@dataclass
+class ToolReturn:
+    id: str
+    result: dict[str, Any]
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "ToolReturn":
+        return cls(id=str(data["id"]), result=data.get("result") or {})
+
+    def to_json(self) -> dict[str, Any]:
+        return {"id": self.id, "result": self.result}

opentool_python/model/__init__.py

@@ -0,0 +1,23 @@
+from .data_type import DataType
+from .function_model import FunctionModel
+from .info import Info
+from .opentool import OpenTool
+from .parameter import Parameter
+from .return_model import Return
+from .schema import Schema, SchemaReferenceResolver, SchemaResolver, SchemaType, SchemaValidationResult
+from .server import ServerConfig
+
+__all__ = [
+    "DataType",
+    "FunctionModel",
+    "Info",
+    "OpenTool",
+    "Parameter",
+    "Return",
+    "Schema",
+    "SchemaType",
+    "SchemaReferenceResolver",
+    "SchemaResolver",
+    "SchemaValidationResult",
+    "ServerConfig",
+]

opentool_python/model/data_type.py

@@ -0,0 +1,8 @@
+class DataType:
+    BOOLEAN = "boolean"
+    INTEGER = "integer"
+    NUMBER = "number"
+    STRING = "string"
+    ARRAY = "array"
+    OBJECT = "object"
+    DYNAMIC = "dynamic"

opentool_python/model/function_model.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from .parameter import Parameter
+from .return_model import Return
+from .schema import SchemaResolver
+
+
+@dataclass
+class FunctionModel:
+    name: str
+    description: str
+    parameters: list[Parameter]
+    return_: Return | None = None
+    stream: dict[str, Return] | None = None
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any], *, schema_resolver: SchemaResolver | None = None) -> "FunctionModel":
+        parameters = data["parameters"]
+        if not isinstance(parameters, list) or any(not isinstance(item, dict) for item in parameters):
+            raise ValueError("parameters: expected an array of objects")
+
+        raw_return = data.get("return")
+        if raw_return is not None and not isinstance(raw_return, dict):
+            raise ValueError("return: expected an object")
+
+        raw_stream = data.get("stream")
+        stream: dict[str, Return] | None = None
+        if raw_stream is not None:
+            if not isinstance(raw_stream, dict) or any(not isinstance(item, dict) for item in raw_stream.values()):
+                raise ValueError("stream: expected a map of return objects")
+            stream = {
+                name: Return.from_json(value, schema_resolver=schema_resolver)
+                for name, value in raw_stream.items()
+            }
+
+        return cls(
+            name=str(data["name"]),
+            description=str(data["description"]),
+            parameters=[
+                Parameter.from_json(item, schema_resolver=schema_resolver)
+                for item in parameters
+            ],
+            return_=(
+                Return.from_json(raw_return, schema_resolver=schema_resolver)
+                if raw_return is not None else None
+            ),
+            stream=stream,
+        )
+
+    def to_json(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "name": self.name,
+            "description": self.description,
+            "parameters": [parameter.to_json() for parameter in self.parameters],
+        }
+        if self.return_ is not None:
+            payload["return"] = self.return_.to_json()
+        if self.stream is not None:
+            payload["stream"] = {
+                event_name: return_model.to_json()
+                for event_name, return_model in self.stream.items()
+            }
+        return payload

opentool_python/model/info.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class Info:
+    title: str
+    version: str
+    description: str | None = None
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "Info":
+        return cls(
+            title=str(data["title"]),
+            version=str(data["version"]),
+            description=data.get("description"),
+        )
+
+    def to_json(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {"title": self.title, "version": self.version}
+        if self.description is not None:
+            payload["description"] = self.description
+        return payload