|
| 1 | +# Copyright (c) Microsoft. All rights reserved. |
| 2 | + |
| 3 | +from __future__ import annotations |
| 4 | + |
| 5 | +import json |
| 6 | +import logging |
| 7 | +import sys |
| 8 | +from typing import TYPE_CHECKING, Any, Callable, Dict, Mapping |
| 9 | + |
| 10 | +if sys.version_info >= (3, 9): |
| 11 | + from typing import Annotated |
| 12 | +else: |
| 13 | + from typing_extensions import Annotated |
| 14 | +from urllib.parse import urljoin, urlparse, urlunparse |
| 15 | + |
| 16 | +import aiohttp |
| 17 | +import requests |
| 18 | +from openapi_core import Spec, unmarshal_request |
| 19 | +from openapi_core.contrib.requests import RequestsOpenAPIRequest |
| 20 | +from openapi_core.exceptions import OpenAPIError |
| 21 | +from prance import ResolvingParser |
| 22 | + |
| 23 | +from semantic_kernel.connectors.ai.open_ai.const import ( |
| 24 | + USER_AGENT, |
| 25 | +) |
| 26 | +from semantic_kernel.exceptions import ServiceInvalidRequestError |
| 27 | +from semantic_kernel.functions.kernel_function_decorator import kernel_function |
| 28 | +from semantic_kernel.functions.kernel_plugin import KernelPlugin |
| 29 | + |
| 30 | +if TYPE_CHECKING: |
| 31 | + from semantic_kernel.connectors.openai_plugin.openai_function_execution_parameters import ( |
| 32 | + OpenAIFunctionExecutionParameters, |
| 33 | + ) |
| 34 | + from semantic_kernel.connectors.openapi_plugin.openapi_function_execution_parameters import ( |
| 35 | + OpenAPIFunctionExecutionParameters, |
| 36 | + ) |
| 37 | + |
| 38 | +logger: logging.Logger = logging.getLogger(__name__) |
| 39 | + |
| 40 | + |
| 41 | +class PreparedRestApiRequest: |
| 42 | + def __init__(self, method: str, url: str, params=None, headers=None, request_body=None): |
| 43 | + self.method = method |
| 44 | + self.url = url |
| 45 | + self.params = params |
| 46 | + self.headers = headers |
| 47 | + self.request_body = request_body |
| 48 | + |
| 49 | + def __repr__(self): |
| 50 | + return ( |
| 51 | + "PreparedRestApiRequest(" |
| 52 | + f"method={self.method}, " |
| 53 | + f"url={self.url}, " |
| 54 | + f"params={self.params}, " |
| 55 | + f"headers={self.headers}, " |
| 56 | + f"request_body={self.request_body})" |
| 57 | + ) |
| 58 | + |
| 59 | + def validate_request(self, spec: Spec): |
| 60 | + """Validate the request against the OpenAPI spec.""" |
| 61 | + request = requests.Request( |
| 62 | + self.method, |
| 63 | + self.url, |
| 64 | + params=self.params, |
| 65 | + headers=self.headers, |
| 66 | + json=self.request_body, |
| 67 | + ) |
| 68 | + openapi_request = RequestsOpenAPIRequest(request=request) |
| 69 | + try: |
| 70 | + unmarshal_request(openapi_request, spec=spec) |
| 71 | + return True |
| 72 | + except OpenAPIError as e: |
| 73 | + logger.debug(f"Error validating request: {e}", exc_info=True) |
| 74 | + return False |
| 75 | + |
| 76 | + |
| 77 | +class RestApiOperation: |
| 78 | + def __init__( |
| 79 | + self, |
| 80 | + id: str, |
| 81 | + method: str, |
| 82 | + server_url: str, |
| 83 | + path: str, |
| 84 | + summary: str | None = None, |
| 85 | + description: str | None = None, |
| 86 | + params: Mapping[str, str] | None = None, |
| 87 | + request_body: Mapping[str, str] | None = None, |
| 88 | + ): |
| 89 | + self.id = id |
| 90 | + self.method = method.upper() |
| 91 | + self.server_url = server_url |
| 92 | + self.path = path |
| 93 | + self.summary = summary |
| 94 | + self.description = description |
| 95 | + self.params = params |
| 96 | + self.request_body = request_body |
| 97 | + |
| 98 | + def url_join(self, base_url, path): |
| 99 | + """Join a base URL and a path, correcting for any missing slashes.""" |
| 100 | + parsed_base = urlparse(base_url) |
| 101 | + if not parsed_base.path.endswith("/"): |
| 102 | + base_path = parsed_base.path + "/" |
| 103 | + else: |
| 104 | + base_path = parsed_base.path |
| 105 | + full_path = urljoin(base_path, path.lstrip("/")) |
| 106 | + return urlunparse(parsed_base._replace(path=full_path)) |
| 107 | + |
| 108 | + def prepare_request( |
| 109 | + self, |
| 110 | + path_params: dict[str, Any] | None = None, |
| 111 | + query_params: dict[str, Any] | None = None, |
| 112 | + headers: dict[str, Any] | None = None, |
| 113 | + request_body: Any | None = None, |
| 114 | + ) -> PreparedRestApiRequest: |
| 115 | + """Prepare the request for this operation. |
| 116 | +
|
| 117 | + Args: |
| 118 | + path_params: A dictionary of path parameters |
| 119 | + query_params: A dictionary of query parameters |
| 120 | + headers: A dictionary of headers |
| 121 | + request_body: The payload of the request |
| 122 | +
|
| 123 | + Returns: |
| 124 | + A PreparedRestApiRequest object |
| 125 | + """ |
| 126 | + from semantic_kernel.connectors.telemetry import HTTP_USER_AGENT |
| 127 | + |
| 128 | + path = self.path |
| 129 | + if path_params: |
| 130 | + path = path.format(**path_params) |
| 131 | + |
| 132 | + url = self.url_join(self.server_url, path) |
| 133 | + |
| 134 | + processed_query_params = {} |
| 135 | + processed_headers = headers if headers is not None else {} |
| 136 | + for param in self.params: |
| 137 | + param_name = param["name"] |
| 138 | + param_schema = param["schema"] |
| 139 | + param_default = param_schema.get("default", None) |
| 140 | + |
| 141 | + if param["in"] == "query": |
| 142 | + if query_params and param_name in query_params: |
| 143 | + processed_query_params[param_name] = query_params[param_name] |
| 144 | + elif param["schema"] and "default" in param["schema"] is not None: |
| 145 | + processed_query_params[param_name] = param_default |
| 146 | + elif param["in"] == "header": |
| 147 | + if headers and param_name in headers: |
| 148 | + processed_headers[param_name] = headers[param_name] |
| 149 | + elif param_default is not None: |
| 150 | + processed_headers[param_name] = param_default |
| 151 | + elif param["in"] == "path": |
| 152 | + if not path_params or param_name not in path_params: |
| 153 | + raise ServiceInvalidRequestError(f"Required path parameter {param_name} not provided") |
| 154 | + |
| 155 | + processed_payload = None |
| 156 | + if self.request_body and (self.method == "POST" or self.method == "PUT"): |
| 157 | + if request_body is None and "required" in self.request_body and self.request_body["required"]: |
| 158 | + raise ServiceInvalidRequestError("Payload is required but was not provided") |
| 159 | + content = self.request_body["content"] |
| 160 | + content_type = list(content.keys())[0] |
| 161 | + processed_headers["Content-Type"] = content_type |
| 162 | + processed_payload = request_body |
| 163 | + |
| 164 | + processed_headers[USER_AGENT] = " ".join((HTTP_USER_AGENT, processed_headers.get(USER_AGENT, ""))).rstrip() |
| 165 | + |
| 166 | + req = PreparedRestApiRequest( |
| 167 | + method=self.method, |
| 168 | + url=url, |
| 169 | + params=processed_query_params, |
| 170 | + headers=processed_headers, |
| 171 | + request_body=processed_payload, |
| 172 | + ) |
| 173 | + return req |
| 174 | + |
| 175 | + def __repr__(self): |
| 176 | + return ( |
| 177 | + "RestApiOperation(" |
| 178 | + f"id={self.id}, " |
| 179 | + f"method={self.method}, " |
| 180 | + f"server_url={self.server_url}, " |
| 181 | + f"path={self.path}, " |
| 182 | + f"params={self.params}, " |
| 183 | + f"request_body={self.request_body}, " |
| 184 | + f"summary={self.summary}, " |
| 185 | + f"description={self.description})" |
| 186 | + ) |
| 187 | + |
| 188 | + |
| 189 | +class OpenApiParser: |
| 190 | + """ |
| 191 | + NOTE: SK Python only supports the OpenAPI Spec >=3.0 |
| 192 | +
|
| 193 | + Import an OpenAPI file. |
| 194 | +
|
| 195 | + Args: |
| 196 | + openapi_file: The path to the OpenAPI file which can be local or a URL. |
| 197 | +
|
| 198 | + Returns: |
| 199 | + The parsed OpenAPI file |
| 200 | +
|
| 201 | +
|
| 202 | + :param openapi_file: The path to the OpenAPI file which can be local or a URL. |
| 203 | + :return: The parsed OpenAPI file |
| 204 | + """ |
| 205 | + |
| 206 | + def parse(self, openapi_document: str) -> Any | dict[str, Any] | None: |
| 207 | + """Parse the OpenAPI document.""" |
| 208 | + parser = ResolvingParser(openapi_document) |
| 209 | + return parser.specification |
| 210 | + |
| 211 | + def create_rest_api_operations( |
| 212 | + self, |
| 213 | + parsed_document: Any, |
| 214 | + execution_settings: "OpenAIFunctionExecutionParameters" | "OpenAPIFunctionExecutionParameters" | None = None, |
| 215 | + ) -> Dict[str, RestApiOperation]: |
| 216 | + """Create the REST API Operations from the parsed OpenAPI document. |
| 217 | +
|
| 218 | + Args: |
| 219 | + parsed_document: The parsed OpenAPI document |
| 220 | + execution_settings: The execution settings |
| 221 | +
|
| 222 | + Returns: |
| 223 | + A dictionary of RestApiOperation objects keyed by operationId |
| 224 | + """ |
| 225 | + paths = parsed_document.get("paths", {}) |
| 226 | + request_objects = {} |
| 227 | + |
| 228 | + base_url = "/" |
| 229 | + servers = parsed_document.get("servers", []) |
| 230 | + base_url = servers[0].get("url") if servers else "/" |
| 231 | + |
| 232 | + if execution_settings and execution_settings.server_url_override: |
| 233 | + base_url = execution_settings.server_url_override |
| 234 | + |
| 235 | + for path, methods in paths.items(): |
| 236 | + for method, details in methods.items(): |
| 237 | + request_method = method.lower() |
| 238 | + |
| 239 | + parameters = details.get("parameters", []) |
| 240 | + operationId = details.get("operationId", path + "_" + request_method) |
| 241 | + summary = details.get("summary", None) |
| 242 | + description = details.get("description", None) |
| 243 | + |
| 244 | + rest_api_operation = RestApiOperation( |
| 245 | + id=operationId, |
| 246 | + method=request_method, |
| 247 | + server_url=base_url, |
| 248 | + path=path, |
| 249 | + params=parameters, |
| 250 | + request_body=details.get("requestBody", None), |
| 251 | + summary=summary, |
| 252 | + description=description, |
| 253 | + ) |
| 254 | + |
| 255 | + request_objects[operationId] = rest_api_operation |
| 256 | + return request_objects |
| 257 | + |
| 258 | + |
| 259 | +class OpenApiRunner: |
| 260 | + """The OpenApiRunner that runs the operations defined in the OpenAPI manifest""" |
| 261 | + |
| 262 | + def __init__( |
| 263 | + self, |
| 264 | + parsed_openapi_document: Mapping[str, str], |
| 265 | + auth_callback: Callable[[Dict[str, str]], Dict[str, str]] | None = None, |
| 266 | + ): |
| 267 | + self.spec = Spec.from_dict(parsed_openapi_document) |
| 268 | + self.auth_callback = auth_callback |
| 269 | + |
| 270 | + async def run_operation( |
| 271 | + self, |
| 272 | + operation: RestApiOperation, |
| 273 | + path_params: Dict[str, str] | None = None, |
| 274 | + query_params: Dict[str, str] | None = None, |
| 275 | + headers: Dict[str, str] | None = None, |
| 276 | + request_body: str | Dict[str, str] | None = None, |
| 277 | + ) -> str: |
| 278 | + """Runs the operation defined in the OpenAPI manifest""" |
| 279 | + if headers is None: |
| 280 | + headers = {} |
| 281 | + |
| 282 | + if self.auth_callback: |
| 283 | + headers_update = await self.auth_callback(headers=headers) |
| 284 | + headers.update(headers_update) |
| 285 | + |
| 286 | + prepared_request = operation.prepare_request( |
| 287 | + path_params=path_params, |
| 288 | + query_params=query_params, |
| 289 | + headers=headers, |
| 290 | + request_body=request_body, |
| 291 | + ) |
| 292 | + # TODO - figure out how to validate a request that has a dynamic API |
| 293 | + # against a spec that has a template path |
| 294 | + |
| 295 | + async with aiohttp.ClientSession(raise_for_status=True) as session: |
| 296 | + async with session.request( |
| 297 | + prepared_request.method, |
| 298 | + prepared_request.url, |
| 299 | + params=prepared_request.params, |
| 300 | + headers=prepared_request.headers, |
| 301 | + json=prepared_request.request_body, |
| 302 | + ) as response: |
| 303 | + return await response.text() |
| 304 | + |
| 305 | + |
| 306 | +class OpenAPIPlugin: |
| 307 | + @staticmethod |
| 308 | + def create( |
| 309 | + plugin_name: str, |
| 310 | + openapi_document_path: str, |
| 311 | + execution_settings: "OpenAIFunctionExecutionParameters" | "OpenAPIFunctionExecutionParameters" | None = None, |
| 312 | + ) -> KernelPlugin: |
| 313 | + """Creates an OpenAPI plugin |
| 314 | +
|
| 315 | + Args: |
| 316 | + plugin_name: The name of the plugin |
| 317 | + openapi_document_path: The OpenAPI document path, it must be a file path to the spec. |
| 318 | + execution_settings: The execution settings |
| 319 | +
|
| 320 | + Returns: |
| 321 | + The KernelPlugin |
| 322 | + """ |
| 323 | + parser = OpenApiParser() |
| 324 | + parsed_doc = parser.parse(openapi_document_path) |
| 325 | + operations = parser.create_rest_api_operations(parsed_doc, execution_settings=execution_settings) |
| 326 | + |
| 327 | + auth_callback = None |
| 328 | + if execution_settings and execution_settings.auth_callback: |
| 329 | + auth_callback = execution_settings.auth_callback |
| 330 | + openapi_runner = OpenApiRunner(parsed_openapi_document=parsed_doc, auth_callback=auth_callback) |
| 331 | + |
| 332 | + plugin = {} |
| 333 | + |
| 334 | + def create_run_operation_function(runner: OpenApiRunner, operation: RestApiOperation): |
| 335 | + @kernel_function( |
| 336 | + description=operation.summary if operation.summary else operation.description, |
| 337 | + name=operation.id, |
| 338 | + ) |
| 339 | + async def run_openapi_operation( |
| 340 | + path_params: Annotated[dict | str | None, "A dictionary of path parameters"] = None, |
| 341 | + query_params: Annotated[dict | str | None, "A dictionary of query parameters"] = None, |
| 342 | + headers: Annotated[dict | str | None, "A dictionary of headers"] = None, |
| 343 | + request_body: Annotated[dict | str | None, "A dictionary of the request body"] = None, |
| 344 | + ) -> str: |
| 345 | + response = await runner.run_operation( |
| 346 | + operation, |
| 347 | + path_params=( |
| 348 | + json.loads(path_params) |
| 349 | + if isinstance(path_params, str) |
| 350 | + else path_params if path_params else None |
| 351 | + ), |
| 352 | + query_params=( |
| 353 | + json.loads(query_params) |
| 354 | + if isinstance(query_params, str) |
| 355 | + else query_params if query_params else None |
| 356 | + ), |
| 357 | + headers=json.loads(headers) if isinstance(headers, str) else headers if headers else None, |
| 358 | + request_body=( |
| 359 | + json.loads(request_body) |
| 360 | + if isinstance(request_body, str) |
| 361 | + else request_body if request_body else None |
| 362 | + ), |
| 363 | + ) |
| 364 | + return response |
| 365 | + |
| 366 | + return run_openapi_operation |
| 367 | + |
| 368 | + for operation_id, operation in operations.items(): |
| 369 | + logger.info(f"Registering OpenAPI operation: {plugin_name}.{operation_id}") |
| 370 | + plugin[operation_id] = create_run_operation_function(openapi_runner, operation) |
| 371 | + return plugin |
0 commit comments