openapi-haystack 0.1.0__py3-none-any.whl

haystack_integrations/components/connectors/openapi/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+from .openapi import OpenAPIConnector
+from .openapi_service import OpenAPIServiceConnector
+
+__all__ = ["OpenAPIConnector", "OpenAPIServiceConnector"]

haystack_integrations/components/connectors/openapi/openapi.py

@@ -0,0 +1,98 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Any
+
+from haystack import component, default_from_dict, default_to_dict
+from haystack.utils import Secret
+from openapi_llm.client.openapi import OpenAPIClient
+
+
+@component
+class OpenAPIConnector:
+    """
+    OpenAPIConnector enables direct invocation of REST endpoints defined in an OpenAPI specification.
+
+    The OpenAPIConnector serves as a bridge between Haystack pipelines and any REST API that follows
+    the OpenAPI(formerly Swagger) specification. It dynamically interprets the API specification and
+    provides an interface for executing API operations. It is usually invoked by passing input
+    arguments to it from a Haystack pipeline run method or by other components in a pipeline that
+    pass input arguments to this component.
+
+    Example:
+    ```python
+    from haystack.utils import Secret
+    from haystack_integrations.components.connectors.openapi import OpenAPIConnector
+
+    serper_dev_token = Secret.from_env_var("SERPERDEV_API_KEY")
+
+    def my_custom_config_factory():
+        # Create and return a custom configuration for the OpenAPIClient
+        pass
+
+    connector = OpenAPIConnector(
+        openapi_spec="https://bit.ly/serperdev_openapi",
+        credentials=serper_dev_token,
+        service_kwargs={"config_factory": my_custom_config_factory()}
+    )
+    response = connector.run(
+        operation_id="search",
+        arguments={"q": "Who was Nikola Tesla?"}
+    )
+    ```
+    Note:
+    - The `service_kwargs` argument is optional, it can be used to pass additional options to the OpenAPIClient.
+
+    """
+
+    def __init__(
+        self, openapi_spec: str, credentials: Secret | None = None, service_kwargs: dict[str, Any] | None = None
+    ) -> None:
+        """
+        Initialize the OpenAPIConnector with a specification and optional credentials.
+
+        :param openapi_spec: URL, file path, or raw string of the OpenAPI specification
+        :param credentials: Optional API key or credentials for the service wrapped in a Secret
+        :param service_kwargs: Additional keyword arguments passed to OpenAPIClient.from_spec()
+            For example, you can pass a custom config_factory or other configuration options.
+        """
+        self.openapi_spec = openapi_spec
+        self.credentials = credentials
+        self.service_kwargs = service_kwargs or {}
+
+        self.client = OpenAPIClient.from_spec(
+            openapi_spec=openapi_spec,
+            credentials=credentials.resolve_value() if credentials else None,
+            **self.service_kwargs,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Serialize this component to a dictionary.
+        """
+        return default_to_dict(
+            self, openapi_spec=self.openapi_spec, credentials=self.credentials, service_kwargs=self.service_kwargs
+        )
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "OpenAPIConnector":
+        """
+        Deserialize this component from a dictionary.
+        """
+        return default_from_dict(cls, data)
+
+    @component.output_types(response=dict[str, Any])
+    def run(self, operation_id: str, arguments: dict[str, Any] | None = None) -> dict[str, Any]:
+        """
+        Invokes a REST endpoint specified in the OpenAPI specification.
+
+        :param operation_id: The operationId from the OpenAPI spec to invoke
+        :param arguments: Optional parameters for the endpoint (query, path, or body parameters)
+        :return: Dictionary containing the service response
+        """
+        payload = {"name": operation_id, "arguments": arguments or {}}
+
+        # Invoke the endpoint using openapi-llm client
+        response = self.client.invoke(payload)
+        return {"response": response}

haystack_integrations/components/connectors/openapi/openapi_service.py

@@ -0,0 +1,402 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import json
+from collections import defaultdict
+from copy import copy
+from typing import Any
+
+import requests
+from haystack import component, default_from_dict, default_to_dict
+from haystack.dataclasses import ChatMessage, ChatRole
+from openapi3 import OpenAPI
+from openapi3.errors import UnexpectedResponseError
+from openapi3.paths import Operation
+
+
+# Patch the request method to add support for the proper raw_response handling
+# If you see that https://github.com/Dorthu/openapi3/pull/124/
+# is merged, we can remove this patch - notify authors of this code
+def patch_request(
+    self: "Operation",
+    base_url: str,
+    *,
+    data: Any | None = None,
+    parameters: dict[str, Any] | None = None,
+    raw_response: bool = False,
+    security: dict[str, str] | None = None,
+    session: Any | None = None,
+    verify: bool | str = True,
+) -> Any | None:
+    """
+    Sends an HTTP request as described by this path.
+
+    :param base_url: The URL to append this operation's path to when making
+                     the call.
+    :param data: The request body to send.
+    :param parameters: The parameters used to create the path.
+    :param raw_response: If true, return the raw response instead of validating
+                         and extrapolating it.
+    :param security: The security scheme to use, and the values it needs to
+                     process successfully.
+    :param session: A persistent request session.
+    :param verify: If we should do an SSL verification on the request or not.
+                   In case str was provided, will use that as the CA.
+    :return: The response data, either raw or processed depending on raw_response flag.
+    """
+    # Set request method (e.g. 'GET')
+    self._request = requests.Request(self.path[-1])
+
+    # Set self._request.url to base_url w/ path
+    self._request.url = base_url + self.path[-2]
+
+    parameters = parameters or {}
+    security = security or {}
+
+    if security and self.security:
+        security_requirement = None
+        for scheme, value in security.items():
+            security_requirement = None
+            for r in self.security:
+                if r.name == scheme:
+                    security_requirement = r
+                    self._request_handle_secschemes(r, value)
+
+        if security_requirement is None:
+            err_msg = """No security requirement satisfied (accepts {}) \
+                      """.format(", ".join(self.security.keys()))
+            raise ValueError(err_msg)
+
+    if self.requestBody:
+        if self.requestBody.required and data is None:
+            err_msg = "Request Body is required but none was provided."
+            raise ValueError(err_msg)
+
+        self._request_handle_body(data)
+
+    self._request_handle_parameters(parameters)
+
+    if session is None:
+        session = self._session
+
+    # send the prepared request
+    result = session.send(self._request.prepare(), verify=verify)
+
+    # spec enforces these are strings
+    status_code = str(result.status_code)
+
+    # find the response model in spec we received
+    expected_response = None
+    if status_code in self.responses:
+        expected_response = self.responses[status_code]
+    elif "default" in self.responses:
+        expected_response = self.responses["default"]
+
+    if expected_response is None:
+        raise UnexpectedResponseError(result, self)
+
+    # if we got back a valid response code (or there was a default) and no
+    # response content was expected, return None
+    if expected_response.content is None:
+        return None
+
+    content_type = result.headers["Content-Type"]
+    if ";" in content_type:
+        # if the content type that came in included an encoding, we'll ignore
+        # it for now (requests has already parsed it for us) and only look at
+        # the MIME type when determining if an expected content type was returned.
+        content_type = content_type.split(";")[0].strip()
+
+    expected_media = expected_response.content.get(content_type, None)
+
+    # If raw_response is True, return the raw text or json based on content type
+    if raw_response:
+        if "application/json" in content_type:
+            return result.json()
+        return result.text
+
+    if expected_media is None and "/" in content_type:
+        # accept media type ranges in the spec. the most specific matching
+        # type should always be chosen, but if we do not have a match here
+        # a generic range should be accepted if one if provided
+        # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#response-object
+
+        generic_type = content_type.split("/")[0] + "/*"
+        expected_media = expected_response.content.get(generic_type, None)
+
+    if expected_media is None:
+        err_msg = """Unexpected Content-Type {} returned for operation {} \
+                     (expected one of {})"""
+        err_var = result.headers["Content-Type"], self.operationId, ",".join(expected_response.content.keys())
+
+        raise RuntimeError(err_msg.format(*err_var))
+
+    if content_type.lower() == "application/json":
+        return expected_media.schema.model(result.json())
+
+    raise NotImplementedError("Only application/json content type is supported")
+
+
+# Apply the patch
+Operation.request = patch_request
+
+
+@component
+class OpenAPIServiceConnector:
+    """
+    A component which connects the Haystack framework to OpenAPI services.
+
+    The `OpenAPIServiceConnector` component connects the Haystack framework to OpenAPI services, enabling it to call
+    operations as defined in the OpenAPI specification of the service.
+
+    It integrates with `ChatMessage` dataclass, where the `ToolCall` entries in messages are used to determine the
+    method to be called and the parameters to be passed. The method name and parameters are then used to invoke the
+    method on the OpenAPI service. The response from the service is returned as a `ChatMessage`.
+
+    Before using this component, users usually resolve service endpoint parameters with a help of
+    `OpenAPIServiceToFunctions` component.
+
+    The example below demonstrates how to use the `OpenAPIServiceConnector` to invoke a method on a https://serper.dev/
+    service specified via OpenAPI specification.
+
+    Note, however, that `OpenAPIServiceConnector` is usually not meant to be used directly, but rather as part of a
+    pipeline that includes the `OpenAPIServiceToFunctions` component and a Chat Generator component using an LLM
+    with tool calling capabilities. In the example below we use the tool call payload directly, but in a
+    real-world scenario, the tool calls would usually be generated by the Chat Generator component.
+
+    You need to define the `serper_token` variable with your Serper.dev API token for the example to work.
+    Can be through the `SERPERDEV_API_KEY` environment variable or by directly assigning the token string to the
+    variable in the code.
+
+    Usage example:
+    ```python
+    import json
+    import httpx
+
+    from haystack.dataclasses import ChatMessage, ToolCall
+    from haystack.utils import Secret
+    from haystack_integrations.components.connectors.openapi import OpenAPIServiceConnector
+
+    tool_call = ToolCall(
+        tool_name="search",
+        arguments={"q": "Why was Sam Altman ousted from OpenAI?"},
+    )
+    message = ChatMessage.from_assistant(tool_calls=[tool_call])
+
+    serper_token = Secret.from_env_var("SERPERDEV_API_KEY").resolve_value()
+    serperdev_openapi_spec = json.loads(httpx.get("https://bit.ly/serper_dev_spec", follow_redirects=True).text)
+    service_connector = OpenAPIServiceConnector()
+    result = service_connector.run(
+        messages=[message],
+        service_openapi_spec=serperdev_openapi_spec,
+        service_credentials=serper_token,
+    )
+    print(result)
+
+    # {'service_response': [ChatMessage(_role=<ChatRole.USER: 'user'>, _content=[TextContent(text=
+    # '{"searchParameters": {"q": "Why was Sam Altman ousted from OpenAI?",
+    # "type": "search", "engine": "google"}, "answerBox": {"snippet": "Concerns over AI safety and OpenAI\'s role
+    # in protecting were at the center of Altman\'s brief ouster from the company."...
+    ```
+
+    """
+
+    def __init__(self, ssl_verify: bool | str | None = None) -> None:
+        """
+        Initializes the OpenAPIServiceConnector instance
+
+        :param ssl_verify: Decide if to use SSL verification to the requests or not,
+        in case a string is passed, will be used as the CA.
+        """
+        self.ssl_verify = ssl_verify
+
+    @component.output_types(service_response=dict[str, Any])
+    def run(
+        self,
+        messages: list[ChatMessage],
+        service_openapi_spec: dict[str, Any],
+        service_credentials: dict | str | None = None,
+    ) -> dict[str, list[ChatMessage]]:
+        """
+        Processes a list of chat messages to invoke a method on an OpenAPI service.
+
+        It parses the last message in the list, expecting it to contain tool calls.
+
+        :param messages: A list of `ChatMessage` objects containing the messages to be processed. The last message
+        should contain the tool calls.
+        :param service_openapi_spec: The OpenAPI JSON specification object of the service to be invoked. All the refs
+        should already be resolved.
+        :param service_credentials: The credentials to be used for authentication with the service.
+        Currently, only the http and apiKey OpenAPI security schemes are supported.
+
+        :return: A dictionary with the following keys:
+            - `service_response`:  a list of `ChatMessage` objects, each containing the response from the service. The
+                                   response is in JSON format, and the `content` attribute of the `ChatMessage` contains
+                                   the JSON string.
+
+        :raises ValueError: If the last message is not from the assistant or if it does not contain tool calls.
+        """
+
+        last_message = messages[-1]
+        if not last_message.is_from(ChatRole.ASSISTANT):
+            raise ValueError(f"{last_message} is not from the assistant.")
+
+        tool_calls = last_message.tool_calls
+        if not tool_calls:
+            raise ValueError(f"The provided ChatMessage has no tool calls.\nChatMessage: {last_message}")
+
+        function_payloads = []
+        for tool_call in tool_calls:
+            function_payloads.append({"arguments": tool_call.arguments, "name": tool_call.tool_name})
+
+        # instantiate the OpenAPI service for the given specification
+        openapi_service = OpenAPI(service_openapi_spec, ssl_verify=self.ssl_verify)
+        self._authenticate_service(openapi_service, service_credentials)
+
+        response_messages = []
+        for method_invocation_descriptor in function_payloads:
+            service_response = self._invoke_method(openapi_service, method_invocation_descriptor)
+            # openapi3 parses the JSON service response into a model object, which is not our focus at the moment.
+            # Instead, we require direct access to the raw JSON data of the response, rather than the model objects
+            # provided by the openapi3 library. This approach helps us avoid issues related to (de)serialization.
+            # By accessing the raw JSON response through `service_response._raw_data`, we can serialize this data
+            # into a string. Finally, we use this string to create a ChatMessage object.
+            response_messages.append(ChatMessage.from_user(json.dumps(service_response)))
+
+        return {"service_response": response_messages}
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Serializes the component to a dictionary.
+
+        :returns:
+            Dictionary with serialized data.
+        """
+        return default_to_dict(self, ssl_verify=self.ssl_verify)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "OpenAPIServiceConnector":
+        """
+        Deserializes the component from a dictionary.
+
+        :param data:
+            The dictionary to deserialize from.
+        :returns:
+            The deserialized component.
+        """
+        return default_from_dict(cls, data)
+
+    def _authenticate_service(self, openapi_service: "OpenAPI", credentials: dict | str | None = None) -> None:
+        """
+        Authentication with an OpenAPI service.
+
+        Authenticates with the OpenAPI service if required, supporting both single (str) and multiple
+        authentication methods (dict).
+
+        OpenAPI spec v3 supports the following security schemes:
+        http - for Basic, Bearer and other HTTP authentications schemes
+        apiKey - for API keys and cookie authentication
+        oauth2 - for OAuth 2
+        openIdConnect - for OpenID Connect Discovery
+
+        Currently, only the http and apiKey schemes are supported. Multiple security schemes can be defined in the
+        OpenAPI spec, and the credentials should be provided as a dictionary with keys matching the security scheme
+        names. If only one security scheme is defined, the credentials can be provided as a simple string.
+
+        :param openapi_service: The OpenAPI service instance.
+        :param credentials: Credentials for authentication, which can be either a string (e.g. token) or a dictionary
+        with keys matching the authentication method names.
+        :raises ValueError: If authentication fails, is not found, or if appropriate credentials are missing.
+        """
+        if openapi_service.raw_element.get("components", {}).get("securitySchemes"):
+            service_name = openapi_service.info.title
+            if not credentials:
+                raise ValueError(f"Service {service_name} requires authentication but no credentials were provided.")
+
+            # a dictionary of security schemes defined in the OpenAPI spec
+            # each key is the name of the security scheme, and the value is the scheme definition
+            security_schemes = openapi_service.components.securitySchemes.raw_element
+            supported_schemes = ["http", "apiKey"]  # todo: add support for oauth2 and openIdConnect
+
+            authenticated = False
+            for scheme_name, scheme in security_schemes.items():
+                if scheme["type"] in supported_schemes:
+                    auth_credentials = None
+                    if isinstance(credentials, str):
+                        auth_credentials = credentials
+                    elif isinstance(credentials, dict) and scheme_name in credentials:
+                        auth_credentials = credentials[scheme_name]
+                    if auth_credentials:
+                        openapi_service.authenticate(scheme_name, auth_credentials)
+                        authenticated = True
+                        break
+
+                    raise ValueError(
+                        f"Service {service_name} requires {scheme_name} security scheme but no "
+                        f"credentials were provided for it. Check the service configuration and credentials."
+                    )
+            if not authenticated:
+                raise ValueError(
+                    f"Service {service_name} requires authentication but no credentials were provided "
+                    f"for it. Check the service configuration and credentials."
+                )
+
+    def _invoke_method(self, openapi_service: "OpenAPI", method_invocation_descriptor: dict[str, Any]) -> Any:
+        """
+        Invokes the specified method on the OpenAPI service.
+
+        The method name and arguments are passed in the method_invocation_descriptor.
+
+        :param openapi_service: The OpenAPI service instance.
+        :param method_invocation_descriptor: The method name and arguments to be passed to the method. The payload
+        should contain the method name (key: "name") and the arguments (key: "arguments"). The name is a string, and
+        the arguments are a dictionary of key-value pairs.
+        :return: A service JSON response.
+        :raises ValueError: If the descriptor is malformed or a required parameter is missing.
+        :raises TypeError: If the operation is not found in the OpenAPI specification.
+        """
+        name = method_invocation_descriptor.get("name")
+        invocation_arguments = copy(method_invocation_descriptor.get("arguments", {}))
+        if not name or not invocation_arguments:
+            raise ValueError(
+                f"Invalid function calling descriptor: {method_invocation_descriptor} . It should contain "
+                f"a method name and arguments."
+            )
+
+        # openapi3 specific method to call the operation, do we have it?
+        method_to_call = getattr(openapi_service, f"call_{name}", None)
+        if not callable(method_to_call):
+            raise TypeError(f"Operation {name} not found in OpenAPI specification {openapi_service.info.title}")
+
+        # get the operation reference from the method_to_call
+        operation = method_to_call.operation.__self__
+        operation_dict = operation.raw_element
+
+        # Pack URL/query parameters under "parameters" key
+        method_call_params: dict[str, dict[str, Any]] = defaultdict(dict)
+        parameters = operation_dict.get("parameters", [])
+        request_body = operation_dict.get("requestBody", {})
+
+        for param in parameters:
+            param_name = param["name"]
+            param_value = invocation_arguments.get(param_name)
+            if param_value:
+                method_call_params["parameters"][param_name] = param_value
+            elif param.get("required", False):
+                raise ValueError(f"Missing parameter: '{param_name}' required for the '{name}' operation.")
+
+        # Pack request body parameters under "data" key
+        if request_body:
+            schema = request_body.get("content", {}).get("application/json", {}).get("schema", {})
+            required_params = schema.get("required", [])
+            for param_name in schema.get("properties", {}):
+                param_value = invocation_arguments.get(param_name)
+                if param_value:
+                    method_call_params["data"][param_name] = param_value
+                elif param_name in required_params:
+                    raise ValueError(
+                        f"Missing requestBody parameter: '{param_name}' required for the '{name}' operation."
+                    )
+        # call the underlying service REST API with the parameters
+        return method_to_call(**method_call_params, raw_response=True)

haystack_integrations/components/converters/openapi/__init__.py

@@ -0,0 +1,6 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+from .openapi_functions import OpenAPIServiceToFunctions
+
+__all__ = ["OpenAPIServiceToFunctions"]

haystack_integrations/components/converters/openapi/openapi_functions.py

@@ -0,0 +1,256 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+import jsonref
+import yaml
+from haystack import component, logging
+from haystack.dataclasses.byte_stream import ByteStream
+
+logger = logging.getLogger(__name__)
+
+
+@component
+class OpenAPIServiceToFunctions:
+    """
+    Converts OpenAPI service definitions to a format suitable for OpenAI function calling.
+
+    The definition must respect OpenAPI specification 3.0.0 or higher.
+    It can be specified in JSON or YAML format.
+    Each function must have:
+        - unique operationId
+        - description
+        - requestBody and/or parameters
+        - schema for the requestBody and/or parameters
+    For more details on OpenAPI specification see the [official documentation](https://github.com/OAI/OpenAPI-Specification).
+    For more details on OpenAI function calling see the [official documentation](https://platform.openai.com/docs/guides/function-calling).
+
+    Usage example:
+    ```python
+    from haystack.dataclasses.byte_stream import ByteStream
+    from haystack_integrations.components.converters.openapi import OpenAPIServiceToFunctions
+
+    converter = OpenAPIServiceToFunctions()
+    spec = ByteStream.from_string(
+        '{"openapi":"3.0.0","info":{"title":"API","version":"1.0.0"},"paths":{"/search":{"get":{"operationId":"search","summary":"Search","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}}]}}}}'
+    )
+    result = converter.run(sources=[spec])
+    assert result["functions"]
+    ```
+    """
+
+    MIN_REQUIRED_OPENAPI_SPEC_VERSION = 3
+
+    def __init__(self) -> None:
+        """
+        Create an OpenAPIServiceToFunctions component.
+        """
+
+    @component.output_types(functions=list[dict[str, Any]], openapi_specs=list[dict[str, Any]])
+    def run(self, sources: list[str | Path | ByteStream]) -> dict[str, Any]:
+        """
+        Converts OpenAPI definitions in OpenAI function calling format.
+
+        :param sources:
+            File paths or ByteStream objects of OpenAPI definitions (in JSON or YAML format).
+
+        :returns:
+            A dictionary with the following keys:
+            - functions: Function definitions in JSON object format
+            - openapi_specs: OpenAPI specs in JSON/YAML object format with resolved references
+
+        :raises RuntimeError:
+            If the OpenAPI definitions cannot be downloaded or processed.
+        :raises ValueError:
+            If the source type is not recognized or no functions are found in the OpenAPI definitions.
+        """
+        all_extracted_fc_definitions: list[dict[str, Any]] = []
+        all_openapi_specs = []
+        for source in sources:
+            openapi_spec_content = None
+            if isinstance(source, (str, Path)):
+                if os.path.exists(source):
+                    try:
+                        with open(source) as f:
+                            openapi_spec_content = f.read()
+                    except OSError as e:
+                        logger.warning(
+                            "IO error reading OpenAPI specification file: {source}. Error: {e}", source=source, e=e
+                        )
+                else:
+                    logger.warning("OpenAPI specification file not found: {source}", source=source)
+            elif isinstance(source, ByteStream):
+                openapi_spec_content = source.data.decode("utf-8")
+                if not openapi_spec_content:
+                    logger.warning(
+                        "Invalid OpenAPI specification content provided: {openapi_spec_content}",
+                        openapi_spec_content=openapi_spec_content,
+                    )
+            else:
+                logger.warning(
+                    "Invalid source type {source}. Only str, Path, and ByteStream are supported.", source=type(source)
+                )
+                continue
+
+            if openapi_spec_content:
+                try:
+                    service_openapi_spec = self._parse_openapi_spec(openapi_spec_content)
+                    functions: list[dict[str, Any]] = self._openapi_to_functions(service_openapi_spec)
+                    all_extracted_fc_definitions.extend(functions)
+                    all_openapi_specs.append(service_openapi_spec)
+                except Exception as e:
+                    logger.exception(
+                        "Error processing OpenAPI specification from source {source}: {error}", source=source, error=e
+                    )
+
+        if not all_extracted_fc_definitions:
+            logger.warning("No OpenAI function definitions extracted from the provided OpenAPI specification sources.")
+
+        return {"functions": all_extracted_fc_definitions, "openapi_specs": all_openapi_specs}
+
+    def _openapi_to_functions(self, service_openapi_spec: dict[str, Any]) -> list[dict[str, Any]]:
+        """
+        OpenAPI to OpenAI function conversion.
+
+        Extracts functions from the OpenAPI specification of the service and converts them into a format
+        suitable for OpenAI function calling.
+
+        :param service_openapi_spec: The OpenAPI specification from which functions are to be extracted.
+        :type service_openapi_spec: dict[str, Any]
+        :return: A list of dictionaries, each representing a function. Each dictionary includes the function's
+                 name, description, and a schema of its parameters.
+        :rtype: list[dict[str, Any]]
+        """
+
+        # Doesn't enforce rigid spec validation because that would require a lot of dependencies
+        # We check the version and require minimal fields to be present, so we can extract functions
+        spec_version = service_openapi_spec.get("openapi")
+        if not spec_version:
+            raise ValueError(f"Invalid OpenAPI spec provided. Could not extract version from {service_openapi_spec}")
+        service_openapi_spec_version = int(spec_version.split(".")[0])
+
+        # Compare the versions
+        if service_openapi_spec_version < OpenAPIServiceToFunctions.MIN_REQUIRED_OPENAPI_SPEC_VERSION:
+            raise ValueError(
+                f"Invalid OpenAPI spec version {service_openapi_spec_version}. Must be "
+                f"at least {OpenAPIServiceToFunctions.MIN_REQUIRED_OPENAPI_SPEC_VERSION}."
+            )
+
+        functions: list[dict[str, Any]] = []
+        for paths in service_openapi_spec["paths"].values():
+            for path_spec in paths.values():
+                function_dict = self._parse_endpoint_spec(path_spec)
+                if function_dict:
+                    functions.append(function_dict)
+        return functions
+
+    def _parse_endpoint_spec(self, resolved_spec: dict[str, Any]) -> dict[str, Any] | None:
+        if not isinstance(resolved_spec, dict):
+            logger.warning("Invalid OpenAPI spec format provided. Could not extract function.")
+            return {}
+
+        function_name = resolved_spec.get("operationId")
+        description = resolved_spec.get("description") or resolved_spec.get("summary", "")
+
+        schema: dict[str, Any] = {"type": "object", "properties": {}}
+
+        # requestBody section
+        req_body_schema = (
+            resolved_spec.get("requestBody", {}).get("content", {}).get("application/json", {}).get("schema", {})
+        )
+        if "properties" in req_body_schema:
+            for prop_name, prop_schema in req_body_schema["properties"].items():
+                schema["properties"][prop_name] = self._parse_property_attributes(prop_schema)
+
+            if "required" in req_body_schema:
+                schema.setdefault("required", []).extend(req_body_schema["required"])
+
+        # parameters section
+        for param in resolved_spec.get("parameters", []):
+            if "schema" in param:
+                schema_dict = self._parse_property_attributes(param["schema"])
+                # these attributes are not in param[schema] level but on param level
+                useful_attributes = ["description", "pattern", "enum"]
+                schema_dict.update({key: param[key] for key in useful_attributes if param.get(key)})
+                schema["properties"][param["name"]] = schema_dict
+                if param.get("required", False):
+                    schema.setdefault("required", []).append(param["name"])
+
+        if function_name and description and schema["properties"]:
+            return {"name": function_name, "description": description, "parameters": schema}
+
+        logger.warning(
+            "Invalid OpenAPI spec format provided. Could not extract function from {spec}", spec=resolved_spec
+        )
+        return {}
+
+    def _parse_property_attributes(
+        self, property_schema: dict[str, Any], include_attributes: list[str] | None = None
+    ) -> dict[str, Any]:
+        """
+        Parses the attributes of a property schema.
+
+        Recursively parses the attributes of a property schema, including nested objects and arrays,
+        and includes specified attributes like description, pattern, etc.
+
+        :param property_schema: The schema of the property to parse.
+        :param include_attributes: The list of attributes to include in the parsed schema.
+        :return: The parsed schema of the property including the specified attributes.
+        """
+        include_attributes = include_attributes or ["description", "pattern", "enum"]
+
+        schema_type = property_schema.get("type")
+
+        parsed_schema = {"type": schema_type} if schema_type else {}
+        for attr in include_attributes:
+            if attr in property_schema:
+                parsed_schema[attr] = property_schema[attr]
+
+        if schema_type == "object":
+            properties = property_schema.get("properties", {})
+            parsed_properties = {
+                prop_name: self._parse_property_attributes(prop, include_attributes)
+                for prop_name, prop in properties.items()
+            }
+            parsed_schema["properties"] = parsed_properties
+
+            if "required" in property_schema:
+                parsed_schema["required"] = property_schema["required"]
+
+        elif schema_type == "array":
+            items = property_schema.get("items", {})
+            parsed_schema["items"] = self._parse_property_attributes(items, include_attributes)
+
+        return parsed_schema
+
+    def _parse_openapi_spec(self, content: str) -> dict[str, Any]:
+        """
+        Parses OpenAPI specification content, supporting both JSON and YAML formats.
+
+        :param content: The content of the OpenAPI specification.
+        :return: The parsed OpenAPI specification.
+        """
+        open_api_spec_content = None
+        try:
+            open_api_spec_content = json.loads(content)
+            return jsonref.replace_refs(open_api_spec_content)
+        except json.JSONDecodeError as json_error:
+            # heuristic to confirm that the content is likely malformed JSON
+            if content.strip().startswith(("{", "[")):
+                raise json_error
+
+        try:
+            open_api_spec_content = yaml.safe_load(content)
+        except yaml.YAMLError as e:
+            error_message = (
+                "Failed to parse the OpenAPI specification. The content does not appear to be valid JSON or YAML.\n\n"
+            )
+            raise RuntimeError(error_message, content) from e
+
+        # Replace references in the object with their resolved values, if any
+        return jsonref.replace_refs(open_api_spec_content)

openapi_haystack-0.1.0.dist-info/METADATA

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: openapi-haystack
+Version: 0.1.0
+Summary: Haystack integration for openapi
+Project-URL: Documentation, https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/openapi#readme
+Project-URL: Issues, https://github.com/deepset-ai/haystack-core-integrations/issues
+Project-URL: Source, https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/openapi
+Author-email: deepset GmbH <info@deepset.ai>
+License-Expression: Apache-2.0
+License-File: LICENSE.txt
+Keywords: api,connector,function-calling,haystack,openapi,rest
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.10
+Requires-Dist: haystack-ai>=2.23.0
+Requires-Dist: openapi-llm>=0.4.1
+Requires-Dist: openapi3>=1.8.2
+Description-Content-Type: text/markdown
+
+# openapi-haystack
+
+[![PyPI - Version](https://img.shields.io/pypi/v/openapi-haystack.svg)](https://pypi.org/project/openapi-haystack)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/openapi-haystack.svg)](https://pypi.org/project/openapi-haystack)
+
+- [Integration page](https://haystack.deepset.ai/integrations/openapi)
+- [Changelog](https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/openapi/CHANGELOG.md)
+
+---
+
+## Contributing
+
+Refer to the general [Contribution Guidelines](https://github.com/deepset-ai/haystack-core-integrations/blob/main/CONTRIBUTING.md).

openapi_haystack-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+haystack_integrations/components/connectors/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+haystack_integrations/components/connectors/openapi/__init__.py,sha256=n2wOErOeajviZ404v1SjBSSD6hsUW0chCLLYjuVwTKA,260
+haystack_integrations/components/connectors/openapi/openapi.py,sha256=pvokis7cYm4QNkwmE7jhG89nZzZg4eC1sKIjoC4CP8Q,3826
+haystack_integrations/components/connectors/openapi/openapi_service.py,sha256=_QChS7DmOy2ErVyM4Ln7MfuCpu8TAMJhY1ti2x5dKhY,18598
+haystack_integrations/components/converters/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+haystack_integrations/components/converters/openapi/__init__.py,sha256=S90Ozy9211q-WBermg31Qd33o6_VF7CQawbZO-iL7bE,208
+haystack_integrations/components/converters/openapi/openapi_functions.py,sha256=B-qT6BHDmbQ5UC8Kzhnehm4yLQnLp9u3mkag77WE8Co,11541
+openapi_haystack-0.1.0.dist-info/METADATA,sha256=7xbX56KA5Mum-0CGOPOT_2xBPzMtxvOuipeMnC-bLik,1903
+openapi_haystack-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+openapi_haystack-0.1.0.dist-info/licenses/LICENSE.txt,sha256=OrAtTu4aPmrTjKDSTzkSPgo_ji6NOMWO2N9JOTFyAzM,11350
+openapi_haystack-0.1.0.dist-info/RECORD,,

openapi_haystack-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

openapi_haystack-0.1.0.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2023-present deepset GmbH
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.