chore: import upstream snapshot with attribution

docs-website/reference/integrations-api/openapi.md

@@ -0,0 +1,332 @@
+---
+title: "OpenAPI"
+id: integrations-openapi
+description: "OpenAPI integration for Haystack"
+slug: "/integrations-openapi"
+---
+
+
+## haystack_integrations.components.connectors.openapi.openapi
+
+### 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.
+
+#### __init__
+
+```python
+__init__(
+    openapi_spec: str,
+    credentials: Secret | None = None,
+    service_kwargs: dict[str, Any] | None = None,
+) -> None
+```
+
+Initialize the OpenAPIConnector with a specification and optional credentials.
+
+**Parameters:**
+
+- **openapi_spec** (<code>str</code>) – URL, file path, or raw string of the OpenAPI specification
+- **credentials** (<code>Secret | None</code>) – Optional API key or credentials for the service wrapped in a Secret
+- **service_kwargs** (<code>dict\[str, Any\] | None</code>) – Additional keyword arguments passed to OpenAPIClient.from_spec()
+  For example, you can pass a custom config_factory or other configuration options.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serialize this component to a dictionary.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OpenAPIConnector
+```
+
+Deserialize this component from a dictionary.
+
+#### run
+
+```python
+run(
+    operation_id: str, arguments: dict[str, Any] | None = None
+) -> dict[str, Any]
+```
+
+Invokes a REST endpoint specified in the OpenAPI specification.
+
+**Parameters:**
+
+- **operation_id** (<code>str</code>) – The operationId from the OpenAPI spec to invoke
+- **arguments** (<code>dict\[str, Any\] | None</code>) – Optional parameters for the endpoint (query, path, or body parameters)
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary containing the service response
+
+## haystack_integrations.components.connectors.openapi.openapi_service
+
+### patch_request
+
+```python
+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.
+
+**Parameters:**
+
+- **base_url** (<code>str</code>) – The URL to append this operation's path to when making
+  the call.
+- **data** (<code>Any | None</code>) – The request body to send.
+- **parameters** (<code>dict\[str, Any\] | None</code>) – The parameters used to create the path.
+- **raw_response** (<code>bool</code>) – If true, return the raw response instead of validating
+  and extrapolating it.
+- **security** (<code>dict\[str, str\] | None</code>) – The security scheme to use, and the values it needs to
+  process successfully.
+- **session** (<code>Any | None</code>) – A persistent request session.
+- **verify** (<code>bool | str</code>) – If we should do an SSL verification on the request or not.
+  In case str was provided, will use that as the CA.
+
+**Returns:**
+
+- <code>Any | None</code> – The response data, either raw or processed depending on raw_response flag.
+
+### 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."...
+```
+
+#### __init__
+
+```python
+__init__(ssl_verify: bool | str | None = None) -> None
+```
+
+Initializes the OpenAPIServiceConnector instance
+
+**Parameters:**
+
+- **ssl_verify** (<code>[bool | str | None</code>) – Decide if to use SSL verification to the requests or not,
+  in case a string is passed, will be used as the CA.
+
+#### run
+
+```python
+run(
+    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.
+
+**Parameters:**
+
+- **messages** (<code>list\[ChatMessage\]</code>) – A list of `ChatMessage` objects containing the messages to be processed. The last message
+  should contain the tool calls.
+- **service_openapi_spec** (<code>dict\[str, Any\]</code>) – The OpenAPI JSON specification object of the service to be invoked. All the refs
+  should already be resolved.
+- **service_credentials** (<code>dict | str | None</code>) – The credentials to be used for authentication with the service.
+  Currently, only the http and apiKey OpenAPI security schemes are supported.
+
+**Returns:**
+
+- <code>dict\[str, list\[ChatMessage\]\]</code> – 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:**
+
+- <code>ValueError</code> – If the last message is not from the assistant or if it does not contain tool calls.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> OpenAPIServiceConnector
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.
+
+**Returns:**
+
+- <code>OpenAPIServiceConnector</code> – The deserialized component.
+
+## haystack_integrations.components.converters.openapi.openapi_functions
+
+### 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"]
+```
+
+#### __init__
+
+```python
+__init__() -> None
+```
+
+Create an OpenAPIServiceToFunctions component.
+
+#### run
+
+```python
+run(sources: list[str | Path | ByteStream]) -> dict[str, Any]
+```
+
+Converts OpenAPI definitions in OpenAI function calling format.
+
+**Parameters:**
+
+- **sources** (<code>list\[str | Path | ByteStream\]</code>) – File paths or ByteStream objects of OpenAPI definitions (in JSON or YAML format).
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – 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:**
+
+- <code>RuntimeError</code> – If the OpenAPI definitions cannot be downloaded or processed.
+- <code>ValueError</code> – If the source type is not recognized or no functions are found in the OpenAPI definitions.