opentool-python 0.1.0__py3-none-any.whl

opentool_python/model/opentool.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from .function_model import FunctionModel
+from .info import Info
+from .schema import Schema, SchemaReferenceResolver, SchemaResolver
+from .server import ServerConfig
+
+
+@dataclass
+class OpenTool:
+    opentool: str
+    info: Info
+    functions: list[FunctionModel]
+    server: ServerConfig | None = None
+    schemas: dict[str, Schema] | None = None
+
+    @classmethod
+    def from_json(
+        cls,
+        data: dict[str, Any],
+        *,
+        schema_reference_resolver: SchemaReferenceResolver | None = None,
+    ) -> "OpenTool":
+        raw_schemas = data.get("schemas")
+        if raw_schemas is not None and not isinstance(raw_schemas, dict):
+            raise ValueError("schemas: expected an object")
+        schema_resolver = SchemaResolver(raw_schemas, schema_reference_resolver)
+        schemas = schema_resolver.resolve_all() if raw_schemas is not None else None
+        functions = data["functions"]
+        if not isinstance(functions, list) or any(not isinstance(item, dict) for item in functions):
+            raise ValueError("functions: expected an array of objects")
+
+        return cls(
+            opentool=str(data["opentool"]),
+            info=Info.from_json(data["info"]),
+            server=ServerConfig.from_json(data["server"]) if isinstance(data.get("server"), dict) else None,
+            functions=[
+                FunctionModel.from_json(item, schema_resolver=schema_resolver)
+                for item in functions
+            ],
+            schemas=schemas,
+        )
+
+    def to_json(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "opentool": self.opentool,
+            "info": self.info.to_json(),
+            "functions": [function.to_json() for function in self.functions],
+        }
+        if self.server is not None:
+            payload["server"] = self.server.to_json()
+        if self.schemas is not None:
+            payload["schemas"] = {
+                name: schema.to_json() for name, schema in self.schemas.items()
+            }
+        return payload

opentool_python/model/parameter.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from .schema import Schema, SchemaResolver
+
+
+@dataclass
+class Parameter:
+    name: str
+    schema: Schema
+    required: bool = False
+    description: str | None = None
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any], *, schema_resolver: SchemaResolver | None = None) -> "Parameter":
+        required = data.get("required")
+        if required is not None and not isinstance(required, bool):
+            raise ValueError("required: expected a boolean")
+        return cls(
+            name=str(data["name"]),
+            schema=Schema.from_json(data["schema"], resolver=schema_resolver),
+            required=required if required is not None else False,
+            description=data.get("description"),
+        )
+
+    def to_json(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "name": self.name,
+            "schema": self.schema.to_json(),
+            "required": self.required,
+        }
+        if self.description is not None:
+            payload["description"] = self.description
+        return payload

opentool_python/model/return_model.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from .schema import Schema, SchemaResolver
+
+
+@dataclass
+class Return:
+    name: str
+    schema: Schema
+    description: str | None = None
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any], *, schema_resolver: SchemaResolver | None = None) -> "Return":
+        return cls(
+            name=str(data["name"]),
+            schema=Schema.from_json(data["schema"], resolver=schema_resolver),
+            description=data.get("description"),
+        )
+
+    def to_json(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {"name": self.name, "schema": self.schema.to_json()}
+        if self.description is not None:
+            payload["description"] = self.description
+        return payload

opentool_python/model/schema.py

@@ -0,0 +1,251 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from copy import deepcopy
+from dataclasses import dataclass, field
+from typing import Any
+from urllib.parse import quote, unquote
+
+from jsonschema import Draft202012Validator, FormatChecker
+from jsonschema.validators import validator_for
+from referencing import Registry, Resource
+from referencing.exceptions import NoSuchResource
+from referencing.jsonschema import DRAFT202012
+
+
+SchemaValue = dict[str, Any] | bool
+SchemaReferenceResolver = Callable[[str], SchemaValue | None]
+_LOCAL_PREFIX = "https://opentool.invalid/schemas/"
+
+
+class SchemaType:
+    BOOLEAN = "boolean"
+    INTEGER = "integer"
+    NUMBER = "number"
+    STRING = "string"
+    ARRAY = "array"
+    OBJECT = "object"
+    NULL = "null"
+
+
+@dataclass
+class SchemaValidationResult:
+    valid: bool
+    errors: list[str]
+    warnings: list[str] = field(default_factory=list)
+
+    @property
+    def is_valid(self) -> bool:
+        return self.valid
+
+
+class SchemaResolver:
+    def __init__(
+        self,
+        definitions: dict[str, SchemaValue] | None = None,
+        reference_resolver: SchemaReferenceResolver | None = None,
+    ) -> None:
+        self._definitions = deepcopy(definitions) if definitions is not None else {}
+
+        def retrieve(uri: str) -> Resource:
+            value = reference_resolver(uri) if reference_resolver is not None else None
+            if value is None:
+                raise NoSuchResource(ref=uri)
+            return self._resource(value)
+
+        self.registry = Registry(retrieve=retrieve).with_resources(
+            (_LOCAL_PREFIX + quote(name, safe=""), self._resource(value))
+            for name, value in self._definitions.items()
+        )
+
+    def resolve_all(self) -> dict[str, Schema]:
+        return {name: Schema.from_json(value, resolver=self) for name, value in self._definitions.items()}
+
+    def _resource(self, value: SchemaValue) -> Resource:
+        if not isinstance(value, (dict, bool)):
+            raise ValueError("Expected a JSON Schema object or boolean")
+        return Resource.from_contents(self.normalize(value), default_specification=DRAFT202012)
+
+    def keyword_view(self, value: dict[str, Any]) -> dict[str, Any]:
+        chain = [value]
+        seen = set()
+        while isinstance(ref := value.get("$ref"), str) and ref.startswith("#/schemas/"):
+            token = ref[len("#/schemas/"):]
+            if "/" in token or ref in seen:
+                break
+            seen.add(ref)
+            name = unquote(token).replace("~1", "/").replace("~0", "~")
+            target = self._definitions.get(name)
+            if not isinstance(target, dict):
+                break
+            chain.append(target)
+            value = target
+        view: dict[str, Any] = {}
+        for node in reversed(chain):
+            view.update(node)
+        return view
+
+    def normalize(self, value: SchemaValue) -> SchemaValue:
+        if not isinstance(value, dict):
+            return value
+        normalized = dict(value)
+        # Only visit schema positions, leaving literal values in enum, const and annotations intact.
+        for key in ("$ref", "$dynamicRef", "$recursiveRef"):
+            ref = value.get(key)
+            if isinstance(ref, str) and ref.startswith("#/schemas/"):
+                token, separator, rest = ref[len("#/schemas/"):].partition("/")
+                name = unquote(token).replace("~1", "/").replace("~0", "~")
+                if name not in self._definitions:
+                    raise ValueError(f"Unknown OpenTool schema reference: {ref}")
+                normalized[key] = _LOCAL_PREFIX + quote(name, safe="") + (f"#/{rest}" if separator else "")
+        for key in ("$defs", "definitions", "properties", "patternProperties", "dependentSchemas", "dependencies"):
+            if isinstance(value.get(key), dict):
+                normalized[key] = {name: self.normalize(node) for name, node in value[key].items()}
+        for key in ("allOf", "anyOf", "oneOf", "prefixItems", "items"):
+            if isinstance(value.get(key), list):
+                normalized[key] = [self.normalize(node) for node in value[key]]
+        for key in (
+            "additionalProperties", "unevaluatedProperties", "items", "additionalItems",
+            "unevaluatedItems", "contains", "propertyNames", "not", "if", "then", "else", "contentSchema",
+        ):
+            if isinstance(value.get(key), (dict, bool)):
+                normalized[key] = self.normalize(value[key])
+        return normalized
+
+
+class SchemasSingleton:
+    """Legacy registry for standalone Schema.from_json callers."""
+
+    _resolver = SchemaResolver()
+    _schemas: dict[str, Schema] = {}
+
+    @classmethod
+    def init_instance(cls, schemas_json: dict[str, SchemaValue]) -> None:
+        resolver = SchemaResolver(schemas_json)
+        schemas = resolver.resolve_all()
+        cls._resolver = resolver
+        cls._schemas = schemas
+
+    @classmethod
+    def get_instance(cls) -> dict[str, Schema]:
+        return dict(cls._schemas)
+
+
+class Schema:
+    def __init__(
+        self,
+        type: str | list[str],
+        description: str | None = None,
+        properties: dict[str, Schema] | None = None,
+        items: Schema | None = None,
+        enum_: list[Any] | None = None,
+        required: list[str] | None = None,
+        **keywords: Any,
+    ) -> None:
+        value = {"type": type, **keywords}
+        if description is not None:
+            value["description"] = description
+        if properties is not None:
+            value["properties"] = {key: schema.to_json() for key, schema in properties.items()}
+        if items is not None:
+            value["items"] = items.to_json()
+        if enum_ is not None:
+            value["enum"] = enum_
+        if required is not None:
+            value["required"] = required
+        self._initialize(value, SchemaResolver())
+
+    @classmethod
+    def from_json(cls, data: SchemaValue, *, resolver: SchemaResolver | None = None) -> Schema:
+        schema = cls.__new__(cls)
+        schema._initialize(data, resolver if resolver is not None else SchemasSingleton._resolver)
+        return schema
+
+    def _initialize(self, data: SchemaValue, resolver: SchemaResolver) -> None:
+        if not isinstance(data, (dict, bool)):
+            raise ValueError("Expected a JSON Schema object or boolean")
+        self._json = deepcopy(data)
+        self._resolver = resolver
+        normalized = resolver.normalize(self._json)
+        validator_class = validator_for(normalized, default=Draft202012Validator)
+        validator_class.check_schema(normalized)
+        self._validator = validator_class(normalized, registry=resolver.registry)
+        self._format_validator = self._validator.evolve(format_checker=validator_class.FORMAT_CHECKER or FormatChecker())
+
+    @property
+    def is_boolean_schema(self) -> bool:
+        return isinstance(self._json, bool)
+
+    @property
+    def raw_schema(self) -> SchemaValue:
+        return self.to_json()
+
+    def __getitem__(self, keyword: str) -> Any:
+        if not isinstance(self._json, dict):
+            return None
+        if keyword in self._json:
+            return deepcopy(self._json[keyword])
+        return deepcopy(self._resolver.keyword_view(self._json).get(keyword))
+
+    @property
+    def has_type(self) -> bool:
+        return self["type"] is not None
+
+    @property
+    def type(self) -> str:
+        value = self["type"]
+        if isinstance(value, list):
+            return value[0] if value else ""
+        return value if isinstance(value, str) else ""
+
+    @property
+    def type_union(self) -> list[str] | None:
+        value = self["type"]
+        return value if isinstance(value, list) else None
+
+    @property
+    def description(self) -> str | None:
+        return self["description"]
+
+    @property
+    def enum_(self) -> list[Any] | None:
+        return self["enum"]
+
+    @property
+    def required(self) -> list[str] | None:
+        return self["required"]
+
+    @property
+    def properties(self) -> dict[str, Schema] | None:
+        properties = self["properties"]
+        if properties is None:
+            return None
+        return {key: self._child(node) for key, node in properties.items()}
+
+    @property
+    def items(self) -> Schema | list[Schema] | None:
+        items = self["items"]
+        if isinstance(items, list):
+            return [self._child(node) for node in items]
+        return self._child(items) if items is not None else None
+
+    def _child(self, node: SchemaValue) -> Schema:
+        child = self.__class__.__new__(self.__class__)
+        child._json = node
+        child._resolver = self._resolver
+        normalized = self._resolver.normalize(node)
+        child._validator = self._validator.evolve(schema=normalized)
+        child._format_validator = self._format_validator.evolve(schema=normalized)
+        return child
+
+    def to_json(self) -> SchemaValue:
+        return deepcopy(self._json)
+
+    def validate(self, instance: Any, *, validate_formats: bool = False) -> SchemaValidationResult:
+        validator = self._format_validator if validate_formats else self._validator
+        errors = [f"{error.json_path}: {error.message}" for error in validator.iter_errors(instance)]
+        return SchemaValidationResult(valid=not errors, errors=errors)
+
+    def is_valid(self, instance: Any, *, validate_formats: bool = False) -> bool:
+        validator = self._format_validator if validate_formats else self._validator
+        return validator.is_valid(instance)

opentool_python/model/server.py

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

opentool_python/opentool_client.py

@@ -0,0 +1,24 @@
+"""Client exports for OpenTool Python SDK."""
+
+from .client.exceptions import (
+    ErrorNullException,
+    OpenToolServerCallException,
+    OpenToolServerNoAccessException,
+    OpenToolServerUnauthorizedException,
+    ResponseNullException,
+)
+from .client.opentool_client import Client, OpenToolClient
+from .dto import *  # noqa: F403
+from .llm.model import *  # noqa: F403
+from .tool.exceptions import *  # noqa: F403
+from .tool.model import *  # noqa: F403
+
+__all__ = [
+    "Client",
+    "OpenToolClient",
+    "ResponseNullException",
+    "ErrorNullException",
+    "OpenToolServerUnauthorizedException",
+    "OpenToolServerNoAccessException",
+    "OpenToolServerCallException",
+]

opentool_python/opentool_schema.py

@@ -0,0 +1,27 @@
+"""Schema exports for OpenTool Python SDK."""
+
+from .json_loader import OpenToolJsonLoader
+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__ = [
+    "FunctionModel",
+    "Info",
+    "OpenTool",
+    "Parameter",
+    "Return",
+    "Schema",
+    "SchemaType",
+    "SchemaReferenceResolver",
+    "SchemaResolver",
+    "SchemaValidationResult",
+    "DataType",
+    "ServerConfig",
+    "OpenToolJsonLoader",
+]

opentool_python/opentool_server.py

@@ -0,0 +1,17 @@
+"""Server exports for OpenTool Python SDK."""
+
+from .dto import *  # noqa: F403
+from .llm.model import *  # noqa: F403
+from .opentool_schema import *  # noqa: F403
+from .server.cli_arguments import CliArguments
+from .server.opentool_server import OpenToolServer, Server
+from .server.cli_tool import CliTool
+from .tool.exceptions import *  # noqa: F403
+from .tool.model import *  # noqa: F403
+
+__all__ = [
+    "Server",
+    "OpenToolServer",
+    "CliArguments",
+    "CliTool",
+]

opentool_python/server/__init__.py

@@ -0,0 +1,5 @@
+from .cli_arguments import CliArguments
+from .cli_tool import CliTool
+from .opentool_server import OpenToolServer, Server
+
+__all__ = ["CliArguments", "CliTool", "OpenToolServer", "Server"]

opentool_python/server/cli_arguments.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from ..dto import (
+    CLI_ARGUMENT_APIKEYS,
+    CLI_ARGUMENT_HOST,
+    CLI_ARGUMENT_PORT,
+    CLI_ARGUMENT_TAG,
+)
+
+
+class CliArguments:
+    def __init__(self, args: list[str]) -> None:
+        self._args = args
+        self._parser = argparse.ArgumentParser(add_help=False)
+        self._parser.add_argument(f"--{CLI_ARGUMENT_TAG}")
+        self._parser.add_argument(f"--{CLI_ARGUMENT_HOST}")
+        self._parser.add_argument(f"--{CLI_ARGUMENT_PORT}")
+        self._parser.add_argument(f"--{CLI_ARGUMENT_APIKEYS}", action="append")
+
+    def add_custom_option(self, name: str, **kwargs: Any) -> "CliArguments":
+        argument_name = f"--{name}"
+        self._parser.add_argument(argument_name, **kwargs)
+        return self
+
+    def add_custom_multi_option(self, name: str, **kwargs: Any) -> "CliArguments":
+        argument_name = f"--{name}"
+        if "action" not in kwargs:
+            kwargs["action"] = "append"
+        self._parser.add_argument(argument_name, **kwargs)
+        return self
+
+    def parse(self) -> dict[str, Any]:
+        namespace, _ = self._parser.parse_known_args(self._args)
+        data: dict[str, Any] = {}
+        for key, value in vars(namespace).items():
+            if value is not None:
+                data[key] = value
+        return data

opentool_python/server/cli_tool.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..tool.tool import Tool
+
+
+class CliTool(Tool):
+    def init_args(self, args: dict[str, Any] | None) -> dict[str, Any] | None:
+        return args

opentool_python/server/exceptions.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+
+class ServerException(Exception):
+    code: int
+    message: str
+
+    def to_json(self) -> dict[str, Any]:
+        return {"code": self.code, "message": self.message}
+
+
+@dataclass
+class JsonParseException(ServerException):
+    message: str = "Parse error"
+    code: int = -32700
+
+    def __str__(self) -> str:
+        return json.dumps(self.to_json(), ensure_ascii=False)
+
+
+@dataclass
+class InvalidJsonPayloadException(ServerException):
+    message: str = "Invalid JSON payload: expected object"
+    code: int = -32700
+
+    def __str__(self) -> str:
+        return json.dumps(self.to_json(), ensure_ascii=False)