ibm-watsonx-orchestrate 1.0.0__py3-none-any.whl

ibm_watsonx_orchestrate/agent_builder/tools/openapi_tool.py

@@ -0,0 +1,332 @@
+import copy
+import json
+import os.path
+import logging
+from typing import Dict, Any, List
+
+import yaml
+import yaml.constructor
+import re
+import httpx
+import jsonref
+from ibm_watsonx_orchestrate.utils.utils import yaml_safe_load
+from .types import ToolSpec
+from .base_tool import BaseTool
+from .types import HTTP_METHOD, ToolPermission, ToolRequestBody, ToolResponseBody, \
+    OpenApiToolBinding, \
+    JsonSchemaObject, ToolBinding, OpenApiSecurityScheme
+
+import json
+
+logger = logging.getLogger(__name__)
+
+# disables the automatic conversion of date-time objects to datetime objects and leaves them as strings
+yaml.constructor.SafeConstructor.yaml_constructors[u'tag:yaml.org,2002:timestamp'] = \
+    yaml.constructor.SafeConstructor.yaml_constructors[u'tag:yaml.org,2002:str']
+
+
+class HTTPException(Exception):
+    def __init__(self, status_code: int, message: str):
+        self.status_code = status_code
+        self.message = message
+        super().__init__(f"{status_code} {message}")
+
+    def __str__(self):
+        return f"{self.status_code} {self.message}"
+
+
+class OpenAPITool(BaseTool):
+    def __init__(self, spec: ToolSpec):
+        BaseTool.__init__(self, spec=spec)
+
+        if self.__tool_spec__.binding.openapi is None:
+            raise ValueError('Missing openapi binding')
+
+    async def __call__(self, **kwargs):
+        raise RuntimeError('OpenAPI Tools are only available when deployed onto watson orchestrate or the watson '
+                           'orchestrate-light runtime')
+
+    @staticmethod
+    def from_spec(file: str) -> 'OpenAPITool':
+        with open(file, 'r') as f:
+            if file.endswith('.yaml') or file.endswith('.yml'):
+                spec = ToolSpec.model_validate(yaml_safe_load(f))
+            elif file.endswith('.json'):
+                spec = ToolSpec.model_validate(json.load(f))
+            else:
+                raise ValueError('file must end in .json, .yaml, or .yml')
+
+        if spec.binding.openapi is None or spec.binding.openapi is None:
+            raise ValueError('failed to load python tool as the tool had no openapi binding')
+
+        return OpenAPITool(spec=spec)
+
+    def __repr__(self):
+        return f"OpenAPITool(method={self.__tool_spec__.binding.openapi.http_method}, path={self.__tool_spec__.binding.openapi.http_path}, name='{self.__tool_spec__.name}', description='{self.__tool_spec__.description}')"
+
+    def __str__(self):
+        return self.__repr__()
+
+    @property
+    def __doc__(self):
+        return self.__tool_spec__.description
+
+
+def create_openapi_json_tool(
+        openapi_spec: dict,
+        http_path: str,
+        http_method: HTTP_METHOD,
+        http_success_response_code: int = 200,
+        http_response_content_type='application/json',
+        name: str = None,
+        description: str = None,
+        permission: ToolPermission = None,
+        input_schema: ToolRequestBody = None,
+        output_schema: ToolResponseBody = None,
+        connection_id: str = None
+) -> OpenAPITool:
+    """
+    Creates a tool from an openapi spec
+
+    :param openapi_spec: The parsed dictionary representation of an openapi spec
+    :param http_path: Which path to create a tool for
+    :param http_method: Which method on that path to create the tool for
+    :param http_success_response_code: Which http status code should be considered a successful call (defaults to 200)
+    :param http_response_content_type: Which http response type should be considered successful (default to application/json)
+    :param name: The name of the resulting tool (used to invoke the tool by the agent)
+    :param description: The description of the resulting tool (used as the semantic layer to help the agent with tool selection)
+    :param permission: Which orchestrate permission level does a user need to have to invoke this tool
+    :param input_schema: The JSONSchema of the inputs to the http request
+    :param output_schema: The expected JSON schema of the outputs of the http response
+    :param connection_id: The connection id of the application containing the credentials needed to authenticate against this api
+    :return: An OpenAPITool that can be used by an agent
+    """
+
+    # limitation does not support circular $refs
+    openapi_contents = jsonref.replace_refs(openapi_spec, jsonschema=True)
+
+    paths = openapi_contents.get('paths', {})
+    route = paths.get(http_path)
+    if route is None:
+        raise ValueError(f"Path {http_path} not found in paths. Available endpoints are: {list(paths.keys())}")
+
+    route_spec = route.get(http_method.lower(), route.get(http_method.upper()))
+    if route_spec is None:
+        raise ValueError(
+            f"Path {http_path} did not have an http_method {http_method}. Available methods are {list(route.keys())}")
+
+    operation_id = (
+        re.sub(
+            '_+',
+            '_',
+            re.sub(
+                r'[^a-zA-Z_]',
+                '_',
+                route_spec.get('operationId', None)
+            )
+        )
+    ) if route_spec.get('operationId', None) is not None else None
+    spec_name = name or operation_id
+    spec_permission = permission or _action_to_perm(route_spec.get('x-ibm-operation', {}).get('action'))
+    if spec_name is None:
+        raise ValueError(
+            f"No name provided for tool. {http_method}: {http_path} did not specify an operationId, and no name was provided")
+
+    spec_description = description or route_spec.get('description')
+    if spec_description is None:
+        raise ValueError(
+            f"No description provided for tool. {http_method}: {http_path} did not specify a description field, and no description was provided")
+
+    spec = ToolSpec(
+        name=spec_name,
+        description=spec_description,
+        permission=spec_permission
+    )
+    
+    spec.input_schema = input_schema or ToolRequestBody(
+        type='object',
+        properties={},
+        required=[]
+    )
+    spec.output_schema = output_schema or ToolResponseBody(properties={}, required=[])
+
+    parameters = route_spec.get('parameters') or []
+    for parameter in parameters:
+        name = f"{parameter['in']}_{parameter['name']}"
+        if parameter.get('required'):
+            spec.input_schema.required.append(name)
+        parameter['schema']['title'] = parameter['name']
+        parameter['schema']['description'] = parameter.get('description', None)
+        spec.input_schema.properties[name] = JsonSchemaObject.model_validate(parameter['schema'])
+        spec.input_schema.properties[name].in_field = parameter['in']
+        spec.input_schema.properties[name].aliasName = parameter['name']
+
+    # special case in runtime where __requestBody__ will be directly translated to the request body without translation
+    request_body_params = route_spec.get('requestBody', {}).get('content', {}).get(http_response_content_type, {}).get(
+        'schema', None)
+    if request_body_params is not None:
+        spec.input_schema.required.append('__requestBody__')
+        request_body_params = copy.deepcopy(request_body_params)
+        request_body_params['in'] = 'body'
+        if request_body_params.get('title') is None:
+            request_body_params['title'] = 'RequestBody'
+        if request_body_params.get('description') is None:
+            request_body_params['description'] = 'The html request body used to satisfy this user utterance.'
+
+        spec.input_schema.properties['__requestBody__'] = JsonSchemaObject.model_validate(request_body_params)
+
+    responses = route_spec.get('responses', {})
+    response = responses.get(str(http_success_response_code), {})
+    response_description = response.get('description')
+    response_schema = response.get('content', {}).get(http_response_content_type, {}).get('schema', {})
+
+    response_schema['required'] = []
+    spec.output_schema = ToolResponseBody.model_validate(response_schema)
+    spec.output_schema.description = response_description
+
+    servers = list(map(lambda x: x if isinstance(x, str) else x['url'],
+                       openapi_contents.get('servers', openapi_contents.get('x-servers', []))))
+
+    raw_open_api_security_schemes = openapi_contents.get('components', {}).get('securitySchemes', {})
+    security_schemes_map = {}
+    for key, security_scheme in raw_open_api_security_schemes.items():
+        security_schemes_map[key] = OpenApiSecurityScheme(
+            type=security_scheme['type'],
+            scheme=security_scheme.get('scheme'),
+            flows=security_scheme.get('flows'),
+            name=security_scheme.get('name'),
+            open_id_connect_url=security_scheme.get('openId', {}).get('openIdConnectUrl'),
+            in_field=security_scheme.get('in', security_scheme.get('in_field'))
+        )
+
+    # - Note it's possible for security to be configured per route or globally
+    # - Note we have no concept of scope because to a user their auth cred either has access or it doesn't
+    #   unless we ask them for a scope they don't know to validate it provides no value
+    security = []
+    for needed_security in route_spec.get('security', []) + openapi_spec.get('security', []):
+        name = next(iter(needed_security.keys()), None)
+        if name is None or name not in security_schemes_map:
+            raise ValueError(f"Invalid openapi spec, {HTTP_METHOD} {http_path} asks for a security scheme of {name}, "
+                             f"but no such security scheme was configured in the .security section of the spec")
+
+        security.append(security_schemes_map[name])
+
+    spec.binding = ToolBinding(openapi=OpenApiToolBinding(
+        http_path=http_path,
+        http_method=http_method,
+        security=security,
+        servers=servers,
+        connection_id=connection_id
+    ))
+
+    return OpenAPITool(spec=spec)
+
+
+async def _get_openapi_spec_from_uri(openapi_uri: str) -> Dict[str, Any]:
+    if os.path.exists(openapi_uri) or openapi_uri.startswith('file://'):
+        with open(openapi_uri, 'r') as fp:
+            if openapi_uri.endswith('.json'):
+                openapi_contents = json.load(fp)
+            elif openapi_uri.endswith('.yaml') or openapi_uri.endswith('.yml'):
+                openapi_contents = yaml_safe_load(fp)
+            else:
+                raise ValueError(
+                    f"Unexpected file extension for file {openapi_uri}, expected one of [.json, .yaml, .yml]")
+    elif openapi_uri.endswith('.json'):
+        async with httpx.AsyncClient() as client:
+            r = await client.get(openapi_uri)
+            if r.status_code != 200:
+                raise ValueError(f"Failed to fetch an openapi spec from {openapi_uri}, status code: {r.status_code}")
+            openapi_contents = r.json()
+    elif openapi_uri.endswith('.yaml'):
+        async with httpx.AsyncClient() as client:
+            r = await client.get(openapi_uri)
+            if r.status_code != 200:
+                raise ValueError(f"Failed to fetch an openapi spec from {openapi_uri}, status code: {r.status_code}")
+            openapi_contents = yaml_safe_load(r.text)
+
+    if openapi_contents is None:
+        raise ValueError(f"Unrecognized path or uri {openapi_uri}")
+
+    return openapi_contents
+
+
+def _action_to_perm(action: str) -> str:
+    if action and (
+            action.lower().startswith('create') or action.lower().startswith('update') or action.lower().startswith(
+            'delete')):
+        return ToolPermission.READ_WRITE
+    return ToolPermission.READ_ONLY
+
+
+async def create_openapi_json_tool_from_uri(
+        openapi_uri: str,
+        http_path: str,
+        http_method: HTTP_METHOD,
+        http_success_response_code: int = 200,
+        http_response_content_type='application/json',
+        permission: ToolPermission = ToolPermission.READ_ONLY,
+        name: str = None,
+        description: str = None,
+        input_schema: ToolRequestBody = None,
+        output_schema: ToolResponseBody = None,
+        app_id: str = None
+) -> OpenAPITool:
+    """
+    Creates a tool from an openapi spec
+
+    :param openapi_uri: The uri to the openapi spec to generate the tool from (ie file://path/to/openapi_file.json, https://catfact.ninja/docs/api-docs.json)
+    :param http_path: Which path to create a tool for
+    :param http_method: Which method on that path to create the tool for
+    :param http_success_response_code: Which http status code should be considered a successful call (defaults to 200)
+    :param http_response_content_type: Which http response type should be considered successful (default to application/json)
+    :param name: The name of the resulting tool (used to invoke the tool by the agent)
+    :param description: The description of the resulting tool (used as the semantic layer to help the agent with tool selection)
+    :param permission: Which orchestrate permission level does a user need to have to invoke this tool
+    :param input_schema: The JSONSchema of the inputs to the http request
+    :param output_schema: The expected JSON schema of the outputs of the http response
+    :param app_id: The app id of the connection containing the credentials needed to authenticate against this api
+    :return: An OpenAPITool that can be used by an agent
+    """
+    openapi_contents = await _get_openapi_spec_from_uri(openapi_uri)
+
+    return create_openapi_json_tool(
+        openapi_spec=openapi_contents,
+        http_path=http_path,
+        http_method=http_method,
+        http_success_response_code=http_success_response_code,
+        http_response_content_type=http_response_content_type,
+        permission=permission,
+        name=name,
+        description=description,
+        input_schema=input_schema,
+        output_schema=output_schema,
+        app_id=app_id
+    )
+
+
+async def create_openapi_json_tools_from_uri(
+        openapi_uri: str,
+        connection_id: str = None
+) -> List[OpenAPITool]:
+    openapi_contents = await _get_openapi_spec_from_uri(openapi_uri)
+    tools: List[OpenAPITool] = []
+
+    for path, methods in openapi_contents.get('paths', {}).items():
+        for method, spec in methods.items():
+            if method.lower() == 'head':
+                continue
+            success_codes = list(filter(lambda code: 200 <= int(code) < 300, spec['responses'].keys()))
+            if len(success_codes) > 1:
+                logger.warning(
+                    f"There were multiple candidate success codes for {method} {path}, using {success_codes[0]} to generate output schema")
+
+            tools.append(create_openapi_json_tool(
+                openapi_contents,
+                http_path=path,
+                http_method=method.upper(),
+                http_success_response_code=success_codes[0] if len(success_codes) > 0 else None,
+                connection_id=connection_id
+            ))
+
+    return tools

ibm_watsonx_orchestrate/agent_builder/tools/python_tool.py

@@ -0,0 +1,195 @@
+import importlib
+import inspect
+import json
+import os
+from typing import Callable, List
+import logging
+
+import docstring_parser
+from langchain_core.tools.base import create_schema_from_function
+from langchain_core.utils.json_schema import dereference_refs
+from pydantic import TypeAdapter, BaseModel
+
+from ibm_watsonx_orchestrate.utils.utils import yaml_safe_load
+from ibm_watsonx_orchestrate.agent_builder.connections import ExpectedCredentials
+from .base_tool import BaseTool
+from .types import ToolSpec, ToolPermission, ToolRequestBody, ToolResponseBody, JsonSchemaObject, ToolBinding, \
+    PythonToolBinding
+
+_all_tools = []
+logger = logging.getLogger(__name__)
+
+class PythonTool(BaseTool):
+    def __init__(self, fn, spec: ToolSpec, expected_credentials: List[ExpectedCredentials]=None):
+        BaseTool.__init__(self, spec=spec)
+        self.fn = fn
+        self.expected_credentials=expected_credentials
+
+    def __call__(self, *args, **kwargs):
+        return self.fn(*args, **kwargs)
+
+    @staticmethod
+    def from_spec(file: str) -> 'PythonTool':
+        with open(file, 'r') as f:
+            if file.endswith('.yaml') or file.endswith('.yml'):
+                spec = ToolSpec.model_validate(yaml_safe_load(f))
+            elif file.endswith('.json'):
+                spec = ToolSpec.model_validate(json.load(f))
+            else:
+                raise ValueError('file must end in .json, .yaml, or .yml')
+
+        if spec.binding.python is None:
+            raise ValueError('failed to load python tool as the tool had no python binding')
+
+        [module, fn_name] = spec.binding.python.function.split(':')
+        fn = getattr(importlib.import_module(module), fn_name)
+
+        return PythonTool(fn=fn, spec=spec)
+
+    def __repr__(self):
+        return f"PythonTool(fn={self.__tool_spec__.binding.python.function}, name='{self.__tool_spec__.name}', description='{self.__tool_spec__.description}')"
+
+    def __str__(self):
+        return self.__repr__()
+
+def _fix_optional(schema):
+    if schema.properties is None:
+        return schema
+    # Pydantic tends to create types of anyOf: [{type: thing}, {type: null}] instead of simply
+    # while simultaneously marking the field as required, which can be confusing for the model.
+    # This removes union types with null and simply marks the field as not required
+    not_required = []
+    replacements = {}
+    if schema.required is None:
+        schema.required = []
+
+    for k, v in schema.properties.items():
+        if v.type == 'null' and k in schema.required:
+            not_required.append(k)
+        if v.anyOf is not None and next(filter(lambda x: x.type == 'null', v.anyOf)) and k in schema.required:
+            v.anyOf = list(filter(lambda x: x.type != 'null', v.anyOf))
+            if len(v.anyOf) == 1:
+                replacements[k] = v.anyOf[0]
+            not_required.append(k)
+    schema.required = list(filter(lambda x: x not in not_required, schema.required if schema.required is not None else []))
+    for k, v in replacements.items():
+        combined = {
+            **schema.properties[k].model_dump(exclude_unset=True, exclude_none=True),
+            **v.model_dump(exclude_unset=True, exclude_none=True)
+        }
+        schema.properties[k] = JsonSchemaObject(**combined)
+        schema.properties[k].anyOf = None
+
+    for k in schema.properties.keys():
+        if schema.properties[k].type == 'object':
+            schema.properties[k] = _fix_optional(schema.properties[k])
+
+    return schema
+
+def _validate_input_schema(input_schema: ToolRequestBody) -> None:
+    props = input_schema.properties
+    for prop in props:
+        if not props.get(prop).type:
+            logger.warning(f"Missing type hint for tool property '{prop}' defaulting to 'str'. To remove this warning add a type hint to the property in the tools signature. See Python docs for guidance: https://docs.python.org/3/library/typing.html")
+
+def tool(
+    *args,
+    name: str = None,
+    description: str = None,
+    input_schema: ToolRequestBody = None,
+    output_schema: ToolResponseBody = None,
+    permission: ToolPermission = ToolPermission.READ_ONLY,
+    expected_credentials: List[ExpectedCredentials] = None
+) -> Callable[[{__name__, __doc__}], PythonTool]:
+    """
+    Decorator to convert a python function into a callable tool.
+
+    :param name: the agent facing name of the tool (defaults to the function name)
+    :param description: the description of the tool (used for tool routing by the agent)
+    :param input_schema: the json schema args to the tool
+    :param output_schema: the response json schema for the tool
+    :param permission: the permissions needed by the user of the agent to invoke the tool
+    :return:
+    """
+    # inspiration: https://github.com/pydantic/pydantic/blob/main/pydantic/validate_call_decorator.py
+    def _tool_decorator(fn):
+        if fn.__doc__ is not None:
+            doc = docstring_parser.parse(fn.__doc__)
+        else:
+            doc = None
+
+        _desc = description
+        if description is None and doc is not None:
+            _desc = doc.description
+        
+        spec = ToolSpec(
+            name=name or fn.__name__,
+            description=_desc,
+            permission=permission
+        )
+
+        parsed_expected_credentials = []
+        if expected_credentials:
+            for credential in expected_credentials:
+                if isinstance(credential, ExpectedCredentials):
+                    parsed_expected_credentials.append(credential)
+                else:
+                    parsed_expected_credentials.append(ExpectedCredentials.model_validate(credential))
+        
+        t = PythonTool(fn=fn, spec=spec, expected_credentials=parsed_expected_credentials)
+        spec.binding = ToolBinding(python=PythonToolBinding(function=''))
+
+        linux_friendly_os_cwd = os.getcwd().replace("\\", "/")
+        function_binding = (inspect.getsourcefile(fn)
+                            .replace("\\", "/")
+                            .replace(linux_friendly_os_cwd+'/', '')
+                            .replace('.py', '')
+                            .replace('/','.') +
+                            f":{fn.__name__}")
+        spec.binding.python.function = function_binding
+
+        sig = inspect.signature(fn)
+        if not input_schema:
+            input_schema_model: type[BaseModel] = create_schema_from_function(spec.name, fn, parse_docstring=True)
+            input_schema_json = input_schema_model.model_json_schema()
+            input_schema_json = dereference_refs(input_schema_json)
+
+            # Convert the input schema to a JsonSchemaObject
+            input_schema_obj = JsonSchemaObject(**input_schema_json)
+            input_schema_obj = _fix_optional(input_schema_obj)
+
+            spec.input_schema = ToolRequestBody(
+                type='object',
+                properties=input_schema_obj.properties or {},
+                required=input_schema_obj.required or []
+            )
+        else:
+            spec.input_schema = input_schema
+
+        _validate_input_schema(spec.input_schema)
+
+        if not output_schema:
+            ret = sig.return_annotation
+            if ret != sig.empty:
+                _schema = dereference_refs(TypeAdapter(ret).json_schema())
+                if '$defs' in _schema:
+                    _schema.pop('$defs')
+                spec.output_schema = _fix_optional(ToolResponseBody(**_schema))
+            else:
+                spec.output_schema = ToolResponseBody()
+
+            if doc is not None and doc.returns is not None and doc.returns.description is not None:
+                spec.output_schema.description = doc.returns.description
+
+        else:
+            spec.output_schema = ToolResponseBody()
+        _all_tools.append(t)
+        return t
+
+    if len(args) == 1 and callable(args[0]):
+        return _tool_decorator(args[0])
+    return _tool_decorator
+
+
+def get_all_python_tools():
+    return [t for t in _all_tools]

ibm_watsonx_orchestrate/agent_builder/tools/types.py

@@ -0,0 +1,162 @@
+from enum import Enum
+from typing import List, Any, Dict, Literal, Optional
+
+from pydantic import BaseModel, model_validator, ConfigDict, Field, AliasChoices
+
+
+class ToolPermission(str, Enum):
+    READ_ONLY = 'read_only'
+    WRITE_ONLY = 'write_only'
+    READ_WRITE = 'read_write'
+    ADMIN = 'admin'
+
+
+class JsonSchemaObject(BaseModel):
+    model_config = ConfigDict(extra='allow')
+
+    type: Optional[Literal['object', 'string', 'number', 'integer', 'boolean', 'array', 'null']] = None
+    title: str | None = None
+    description: str | None = None
+    properties: Optional[Dict[str, 'JsonSchemaObject']] = None
+    required: Optional[List[str]] = None
+    items: Optional['JsonSchemaObject'] = None
+    uniqueItems: bool | None = None
+    default: Any | None = None
+    enum: List[Any] | None = None
+    minimum: float | None = None
+    maximum: float | None = None
+    minLength: int | None = None
+    maxLength: int | None = None
+    format: str | None = None
+    pattern: str | None = None
+    anyOf: Optional[List['JsonSchemaObject']] = None
+    in_field: Optional[Literal['query', 'header', 'path', 'body']] = Field(None, alias='in')
+    aliasName: str | None = None
+    "Runtime feature where the sdk can provide the original name of a field before prefixing"
+
+
+class ToolRequestBody(BaseModel):
+    model_config = ConfigDict(extra='allow')
+
+    type: Literal['object']
+    properties: Dict[str, JsonSchemaObject]
+    required: List[str]
+
+
+class ToolResponseBody(BaseModel):
+    model_config = ConfigDict(extra='allow')
+
+    type: Literal['object', 'string', 'number', 'integer', 'boolean', 'array','null'] = None
+    description: str = None
+    properties: Dict[str, JsonSchemaObject] = None
+    items: JsonSchemaObject = None
+    uniqueItems: bool = None
+    anyOf: List['JsonSchemaObject'] = None
+    required: List[str] = None
+
+class OpenApiSecurityScheme(BaseModel):
+    type: Literal['apiKey', 'http', 'oauth2', 'openIdConnect']
+    scheme: Optional[Literal['basic', 'bearer', 'oauth']] = None
+    in_field: Optional[Literal['query', 'header', 'cookie']] = Field(None, validation_alias=AliasChoices('in', 'in_field'), serialization_alias='in')
+    name: str | None = None
+    open_id_connect_url: str | None = None
+    flows: dict | None = None
+
+    @model_validator(mode='after')
+    def validate_security_scheme(self) -> 'OpenApiSecurityScheme':
+        if self.type == 'http' and self.scheme is None:
+            raise ValueError("'scheme' is required when type is 'http'")
+
+        if self.type == 'oauth2' and self.flows is None:
+            raise ValueError("'flows' is required when type is 'oauth2'")
+
+        if self.type == 'openIdConnect' and self.open_id_connect_url is None:
+            raise ValueError("'open_id_connect_url' is required when type is 'openIdConnect'")
+
+        if self.type == 'apiKey':
+            if self.name is None:
+                raise ValueError("'name' is required when type is 'apiKey'")
+            if self.in_field is None:
+                raise ValueError("'in_field' is required when type is 'apiKey'")
+
+        return self
+
+
+HTTP_METHOD = Literal['GET', 'POST', 'PUT', 'PATCH', 'DELETE']
+
+
+class OpenApiToolBinding(BaseModel):
+    http_method: HTTP_METHOD
+    http_path: str
+    success_status_code: int = 200  # this is a diff from the spec
+    security: Optional[List[OpenApiSecurityScheme]] = None
+    servers: Optional[List[str]] = None
+    connection_id: str | None = None
+
+    @model_validator(mode='after')
+    def validate_openapi_tool_binding(self):
+        if len(self.servers) != 1:
+            raise ValueError("OpenAPI definition must include exactly one server")
+        return self
+
+
+class PythonToolBinding(BaseModel):
+    function: str
+    requirements: Optional[List[str]] = []
+    connections: dict[str, str] = None
+
+
+class WxFlowsToolBinding(BaseModel):
+    endpoint: str
+    flow_name: str
+    security: OpenApiSecurityScheme
+
+    @model_validator(mode='after')
+    def validate_security_scheme(self) -> 'WxFlowsToolBinding':
+        if self.security.type != 'apiKey':
+            raise ValueError("'security' scheme must be of type 'apiKey'")
+        return self
+
+
+class SkillToolBinding(BaseModel):
+    skillset_id: str
+    skill_id: str
+    skill_operator_path: str
+    http_method: HTTP_METHOD
+
+
+class ClientSideToolBinding(BaseModel):
+    pass
+
+
+class ToolBinding(BaseModel):
+    openapi: OpenApiToolBinding = None
+    python: PythonToolBinding = None
+    wxflows: WxFlowsToolBinding = None
+    skill: SkillToolBinding = None
+    client_side: ClientSideToolBinding = None
+
+    @model_validator(mode='after')
+    def validate_binding_type(self) -> 'ToolBinding':
+        bindings = [
+            self.openapi is not None,
+            self.python is not None,
+            self.wxflows is not None,
+            self.skill is not None,
+            self.client_side is not None
+        ]
+        if sum(bindings) == 0:
+            raise ValueError("One binding must be set")
+        if sum(bindings) > 1:
+            raise ValueError("Only one binding can be set")
+        return self
+
+
+class ToolSpec(BaseModel):
+    name: str
+    description: str
+    permission: ToolPermission
+    input_schema: ToolRequestBody = None
+    output_schema: ToolResponseBody = None
+    binding: ToolBinding = None
+