diff --git a/docs-website/reference/integrations-api/openapi.md b/docs-website/reference/integrations-api/openapi.md new file mode 100644 index 00000000000..e0543a065a1 --- /dev/null +++ b/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** (str) – URL, file path, or raw string of the OpenAPI specification +- **credentials** (Secret | None) – Optional API key or credentials for the service wrapped in a Secret +- **service_kwargs** (dict\[str, Any\] | None) – 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** (str) – The operationId from the OpenAPI spec to invoke +- **arguments** (dict\[str, Any\] | None) – Optional parameters for the endpoint (query, path, or body parameters) + +**Returns:** + +- dict\[str, Any\] – 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** (str) – The URL to append this operation's path to when making + the call. +- **data** (Any | None) – The request body to send. +- **parameters** (dict\[str, Any\] | None) – The parameters used to create the path. +- **raw_response** (bool) – If true, return the raw response instead of validating + and extrapolating it. +- **security** (dict\[str, str\] | None) – The security scheme to use, and the values it needs to + process successfully. +- **session** (Any | None) – A persistent request session. +- **verify** (bool | str) – If we should do an SSL verification on the request or not. + In case str was provided, will use that as the CA. + +**Returns:** + +- Any | None – 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=, _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** ([bool | str | None) – 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** (list\[ChatMessage\]) – A list of `ChatMessage` objects containing the messages to be processed. The last message + should contain the tool calls. +- **service_openapi_spec** (dict\[str, Any\]) – The OpenAPI JSON specification object of the service to be invoked. All the refs + should already be resolved. +- **service_credentials** (dict | str | None) – The credentials to be used for authentication with the service. + Currently, only the http and apiKey OpenAPI security schemes are supported. + +**Returns:** + +- dict\[str, list\[ChatMessage\]\] – 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. + +#### to_dict + +```python +to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns:** + +- dict\[str, Any\] – Dictionary with serialized data. + +#### from_dict + +```python +from_dict(data: dict[str, Any]) -> OpenAPIServiceConnector +``` + +Deserializes the component from a dictionary. + +**Parameters:** + +- **data** (dict\[str, Any\]) – The dictionary to deserialize from. + +**Returns:** + +- OpenAPIServiceConnector – 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** (list\[str | Path | ByteStream\]) – File paths or ByteStream objects of OpenAPI definitions (in JSON or YAML format). + +**Returns:** + +- dict\[str, Any\] – 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. +- ValueError – If the source type is not recognized or no functions are found in the OpenAPI definitions. diff --git a/docs-website/reference_versioned_docs/version-2.18/integrations-api/openapi.md b/docs-website/reference_versioned_docs/version-2.18/integrations-api/openapi.md new file mode 100644 index 00000000000..e0543a065a1 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.18/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** (str) – URL, file path, or raw string of the OpenAPI specification +- **credentials** (Secret | None) – Optional API key or credentials for the service wrapped in a Secret +- **service_kwargs** (dict\[str, Any\] | None) – 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** (str) – The operationId from the OpenAPI spec to invoke +- **arguments** (dict\[str, Any\] | None) – Optional parameters for the endpoint (query, path, or body parameters) + +**Returns:** + +- dict\[str, Any\] – 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** (str) – The URL to append this operation's path to when making + the call. +- **data** (Any | None) – The request body to send. +- **parameters** (dict\[str, Any\] | None) – The parameters used to create the path. +- **raw_response** (bool) – If true, return the raw response instead of validating + and extrapolating it. +- **security** (dict\[str, str\] | None) – The security scheme to use, and the values it needs to + process successfully. +- **session** (Any | None) – A persistent request session. +- **verify** (bool | str) – If we should do an SSL verification on the request or not. + In case str was provided, will use that as the CA. + +**Returns:** + +- Any | None – 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=, _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** ([bool | str | None) – 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** (list\[ChatMessage\]) – A list of `ChatMessage` objects containing the messages to be processed. The last message + should contain the tool calls. +- **service_openapi_spec** (dict\[str, Any\]) – The OpenAPI JSON specification object of the service to be invoked. All the refs + should already be resolved. +- **service_credentials** (dict | str | None) – The credentials to be used for authentication with the service. + Currently, only the http and apiKey OpenAPI security schemes are supported. + +**Returns:** + +- dict\[str, list\[ChatMessage\]\] – 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. + +#### to_dict + +```python +to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns:** + +- dict\[str, Any\] – Dictionary with serialized data. + +#### from_dict + +```python +from_dict(data: dict[str, Any]) -> OpenAPIServiceConnector +``` + +Deserializes the component from a dictionary. + +**Parameters:** + +- **data** (dict\[str, Any\]) – The dictionary to deserialize from. + +**Returns:** + +- OpenAPIServiceConnector – 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** (list\[str | Path | ByteStream\]) – File paths or ByteStream objects of OpenAPI definitions (in JSON or YAML format). + +**Returns:** + +- dict\[str, Any\] – 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. +- ValueError – If the source type is not recognized or no functions are found in the OpenAPI definitions. diff --git a/docs-website/reference_versioned_docs/version-2.19/integrations-api/openapi.md b/docs-website/reference_versioned_docs/version-2.19/integrations-api/openapi.md new file mode 100644 index 00000000000..e0543a065a1 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.19/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** (str) – URL, file path, or raw string of the OpenAPI specification +- **credentials** (Secret | None) – Optional API key or credentials for the service wrapped in a Secret +- **service_kwargs** (dict\[str, Any\] | None) – 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** (str) – The operationId from the OpenAPI spec to invoke +- **arguments** (dict\[str, Any\] | None) – Optional parameters for the endpoint (query, path, or body parameters) + +**Returns:** + +- dict\[str, Any\] – 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** (str) – The URL to append this operation's path to when making + the call. +- **data** (Any | None) – The request body to send. +- **parameters** (dict\[str, Any\] | None) – The parameters used to create the path. +- **raw_response** (bool) – If true, return the raw response instead of validating + and extrapolating it. +- **security** (dict\[str, str\] | None) – The security scheme to use, and the values it needs to + process successfully. +- **session** (Any | None) – A persistent request session. +- **verify** (bool | str) – If we should do an SSL verification on the request or not. + In case str was provided, will use that as the CA. + +**Returns:** + +- Any | None – 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=, _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** ([bool | str | None) – 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** (list\[ChatMessage\]) – A list of `ChatMessage` objects containing the messages to be processed. The last message + should contain the tool calls. +- **service_openapi_spec** (dict\[str, Any\]) – The OpenAPI JSON specification object of the service to be invoked. All the refs + should already be resolved. +- **service_credentials** (dict | str | None) – The credentials to be used for authentication with the service. + Currently, only the http and apiKey OpenAPI security schemes are supported. + +**Returns:** + +- dict\[str, list\[ChatMessage\]\] – 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. + +#### to_dict + +```python +to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns:** + +- dict\[str, Any\] – Dictionary with serialized data. + +#### from_dict + +```python +from_dict(data: dict[str, Any]) -> OpenAPIServiceConnector +``` + +Deserializes the component from a dictionary. + +**Parameters:** + +- **data** (dict\[str, Any\]) – The dictionary to deserialize from. + +**Returns:** + +- OpenAPIServiceConnector – 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** (list\[str | Path | ByteStream\]) – File paths or ByteStream objects of OpenAPI definitions (in JSON or YAML format). + +**Returns:** + +- dict\[str, Any\] – 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. +- ValueError – If the source type is not recognized or no functions are found in the OpenAPI definitions. diff --git a/docs-website/reference_versioned_docs/version-2.20/integrations-api/openapi.md b/docs-website/reference_versioned_docs/version-2.20/integrations-api/openapi.md new file mode 100644 index 00000000000..e0543a065a1 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20/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** (str) – URL, file path, or raw string of the OpenAPI specification +- **credentials** (Secret | None) – Optional API key or credentials for the service wrapped in a Secret +- **service_kwargs** (dict\[str, Any\] | None) – 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** (str) – The operationId from the OpenAPI spec to invoke +- **arguments** (dict\[str, Any\] | None) – Optional parameters for the endpoint (query, path, or body parameters) + +**Returns:** + +- dict\[str, Any\] – 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** (str) – The URL to append this operation's path to when making + the call. +- **data** (Any | None) – The request body to send. +- **parameters** (dict\[str, Any\] | None) – The parameters used to create the path. +- **raw_response** (bool) – If true, return the raw response instead of validating + and extrapolating it. +- **security** (dict\[str, str\] | None) – The security scheme to use, and the values it needs to + process successfully. +- **session** (Any | None) – A persistent request session. +- **verify** (bool | str) – If we should do an SSL verification on the request or not. + In case str was provided, will use that as the CA. + +**Returns:** + +- Any | None – 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=, _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** ([bool | str | None) – 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** (list\[ChatMessage\]) – A list of `ChatMessage` objects containing the messages to be processed. The last message + should contain the tool calls. +- **service_openapi_spec** (dict\[str, Any\]) – The OpenAPI JSON specification object of the service to be invoked. All the refs + should already be resolved. +- **service_credentials** (dict | str | None) – The credentials to be used for authentication with the service. + Currently, only the http and apiKey OpenAPI security schemes are supported. + +**Returns:** + +- dict\[str, list\[ChatMessage\]\] – 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. + +#### to_dict + +```python +to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns:** + +- dict\[str, Any\] – Dictionary with serialized data. + +#### from_dict + +```python +from_dict(data: dict[str, Any]) -> OpenAPIServiceConnector +``` + +Deserializes the component from a dictionary. + +**Parameters:** + +- **data** (dict\[str, Any\]) – The dictionary to deserialize from. + +**Returns:** + +- OpenAPIServiceConnector – 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** (list\[str | Path | ByteStream\]) – File paths or ByteStream objects of OpenAPI definitions (in JSON or YAML format). + +**Returns:** + +- dict\[str, Any\] – 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. +- ValueError – If the source type is not recognized or no functions are found in the OpenAPI definitions. diff --git a/docs-website/reference_versioned_docs/version-2.21/integrations-api/openapi.md b/docs-website/reference_versioned_docs/version-2.21/integrations-api/openapi.md new file mode 100644 index 00000000000..e0543a065a1 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.21/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** (str) – URL, file path, or raw string of the OpenAPI specification +- **credentials** (Secret | None) – Optional API key or credentials for the service wrapped in a Secret +- **service_kwargs** (dict\[str, Any\] | None) – 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** (str) – The operationId from the OpenAPI spec to invoke +- **arguments** (dict\[str, Any\] | None) – Optional parameters for the endpoint (query, path, or body parameters) + +**Returns:** + +- dict\[str, Any\] – 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** (str) – The URL to append this operation's path to when making + the call. +- **data** (Any | None) – The request body to send. +- **parameters** (dict\[str, Any\] | None) – The parameters used to create the path. +- **raw_response** (bool) – If true, return the raw response instead of validating + and extrapolating it. +- **security** (dict\[str, str\] | None) – The security scheme to use, and the values it needs to + process successfully. +- **session** (Any | None) – A persistent request session. +- **verify** (bool | str) – If we should do an SSL verification on the request or not. + In case str was provided, will use that as the CA. + +**Returns:** + +- Any | None – 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=, _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** ([bool | str | None) – 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** (list\[ChatMessage\]) – A list of `ChatMessage` objects containing the messages to be processed. The last message + should contain the tool calls. +- **service_openapi_spec** (dict\[str, Any\]) – The OpenAPI JSON specification object of the service to be invoked. All the refs + should already be resolved. +- **service_credentials** (dict | str | None) – The credentials to be used for authentication with the service. + Currently, only the http and apiKey OpenAPI security schemes are supported. + +**Returns:** + +- dict\[str, list\[ChatMessage\]\] – 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. + +#### to_dict + +```python +to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns:** + +- dict\[str, Any\] – Dictionary with serialized data. + +#### from_dict + +```python +from_dict(data: dict[str, Any]) -> OpenAPIServiceConnector +``` + +Deserializes the component from a dictionary. + +**Parameters:** + +- **data** (dict\[str, Any\]) – The dictionary to deserialize from. + +**Returns:** + +- OpenAPIServiceConnector – 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** (list\[str | Path | ByteStream\]) – File paths or ByteStream objects of OpenAPI definitions (in JSON or YAML format). + +**Returns:** + +- dict\[str, Any\] – 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. +- ValueError – If the source type is not recognized or no functions are found in the OpenAPI definitions. diff --git a/docs-website/reference_versioned_docs/version-2.22/integrations-api/openapi.md b/docs-website/reference_versioned_docs/version-2.22/integrations-api/openapi.md new file mode 100644 index 00000000000..e0543a065a1 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.22/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** (str) – URL, file path, or raw string of the OpenAPI specification +- **credentials** (Secret | None) – Optional API key or credentials for the service wrapped in a Secret +- **service_kwargs** (dict\[str, Any\] | None) – 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** (str) – The operationId from the OpenAPI spec to invoke +- **arguments** (dict\[str, Any\] | None) – Optional parameters for the endpoint (query, path, or body parameters) + +**Returns:** + +- dict\[str, Any\] – 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** (str) – The URL to append this operation's path to when making + the call. +- **data** (Any | None) – The request body to send. +- **parameters** (dict\[str, Any\] | None) – The parameters used to create the path. +- **raw_response** (bool) – If true, return the raw response instead of validating + and extrapolating it. +- **security** (dict\[str, str\] | None) – The security scheme to use, and the values it needs to + process successfully. +- **session** (Any | None) – A persistent request session. +- **verify** (bool | str) – If we should do an SSL verification on the request or not. + In case str was provided, will use that as the CA. + +**Returns:** + +- Any | None – 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=, _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** ([bool | str | None) – 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** (list\[ChatMessage\]) – A list of `ChatMessage` objects containing the messages to be processed. The last message + should contain the tool calls. +- **service_openapi_spec** (dict\[str, Any\]) – The OpenAPI JSON specification object of the service to be invoked. All the refs + should already be resolved. +- **service_credentials** (dict | str | None) – The credentials to be used for authentication with the service. + Currently, only the http and apiKey OpenAPI security schemes are supported. + +**Returns:** + +- dict\[str, list\[ChatMessage\]\] – 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. + +#### to_dict + +```python +to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns:** + +- dict\[str, Any\] – Dictionary with serialized data. + +#### from_dict + +```python +from_dict(data: dict[str, Any]) -> OpenAPIServiceConnector +``` + +Deserializes the component from a dictionary. + +**Parameters:** + +- **data** (dict\[str, Any\]) – The dictionary to deserialize from. + +**Returns:** + +- OpenAPIServiceConnector – 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** (list\[str | Path | ByteStream\]) – File paths or ByteStream objects of OpenAPI definitions (in JSON or YAML format). + +**Returns:** + +- dict\[str, Any\] – 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. +- ValueError – If the source type is not recognized or no functions are found in the OpenAPI definitions. diff --git a/docs-website/reference_versioned_docs/version-2.23/integrations-api/openapi.md b/docs-website/reference_versioned_docs/version-2.23/integrations-api/openapi.md new file mode 100644 index 00000000000..e0543a065a1 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.23/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** (str) – URL, file path, or raw string of the OpenAPI specification +- **credentials** (Secret | None) – Optional API key or credentials for the service wrapped in a Secret +- **service_kwargs** (dict\[str, Any\] | None) – 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** (str) – The operationId from the OpenAPI spec to invoke +- **arguments** (dict\[str, Any\] | None) – Optional parameters for the endpoint (query, path, or body parameters) + +**Returns:** + +- dict\[str, Any\] – 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** (str) – The URL to append this operation's path to when making + the call. +- **data** (Any | None) – The request body to send. +- **parameters** (dict\[str, Any\] | None) – The parameters used to create the path. +- **raw_response** (bool) – If true, return the raw response instead of validating + and extrapolating it. +- **security** (dict\[str, str\] | None) – The security scheme to use, and the values it needs to + process successfully. +- **session** (Any | None) – A persistent request session. +- **verify** (bool | str) – If we should do an SSL verification on the request or not. + In case str was provided, will use that as the CA. + +**Returns:** + +- Any | None – 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=, _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** ([bool | str | None) – 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** (list\[ChatMessage\]) – A list of `ChatMessage` objects containing the messages to be processed. The last message + should contain the tool calls. +- **service_openapi_spec** (dict\[str, Any\]) – The OpenAPI JSON specification object of the service to be invoked. All the refs + should already be resolved. +- **service_credentials** (dict | str | None) – The credentials to be used for authentication with the service. + Currently, only the http and apiKey OpenAPI security schemes are supported. + +**Returns:** + +- dict\[str, list\[ChatMessage\]\] – 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. + +#### to_dict + +```python +to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns:** + +- dict\[str, Any\] – Dictionary with serialized data. + +#### from_dict + +```python +from_dict(data: dict[str, Any]) -> OpenAPIServiceConnector +``` + +Deserializes the component from a dictionary. + +**Parameters:** + +- **data** (dict\[str, Any\]) – The dictionary to deserialize from. + +**Returns:** + +- OpenAPIServiceConnector – 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** (list\[str | Path | ByteStream\]) – File paths or ByteStream objects of OpenAPI definitions (in JSON or YAML format). + +**Returns:** + +- dict\[str, Any\] – 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. +- ValueError – If the source type is not recognized or no functions are found in the OpenAPI definitions. diff --git a/docs-website/reference_versioned_docs/version-2.24/integrations-api/openapi.md b/docs-website/reference_versioned_docs/version-2.24/integrations-api/openapi.md new file mode 100644 index 00000000000..e0543a065a1 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.24/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** (str) – URL, file path, or raw string of the OpenAPI specification +- **credentials** (Secret | None) – Optional API key or credentials for the service wrapped in a Secret +- **service_kwargs** (dict\[str, Any\] | None) – 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** (str) – The operationId from the OpenAPI spec to invoke +- **arguments** (dict\[str, Any\] | None) – Optional parameters for the endpoint (query, path, or body parameters) + +**Returns:** + +- dict\[str, Any\] – 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** (str) – The URL to append this operation's path to when making + the call. +- **data** (Any | None) – The request body to send. +- **parameters** (dict\[str, Any\] | None) – The parameters used to create the path. +- **raw_response** (bool) – If true, return the raw response instead of validating + and extrapolating it. +- **security** (dict\[str, str\] | None) – The security scheme to use, and the values it needs to + process successfully. +- **session** (Any | None) – A persistent request session. +- **verify** (bool | str) – If we should do an SSL verification on the request or not. + In case str was provided, will use that as the CA. + +**Returns:** + +- Any | None – 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=, _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** ([bool | str | None) – 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** (list\[ChatMessage\]) – A list of `ChatMessage` objects containing the messages to be processed. The last message + should contain the tool calls. +- **service_openapi_spec** (dict\[str, Any\]) – The OpenAPI JSON specification object of the service to be invoked. All the refs + should already be resolved. +- **service_credentials** (dict | str | None) – The credentials to be used for authentication with the service. + Currently, only the http and apiKey OpenAPI security schemes are supported. + +**Returns:** + +- dict\[str, list\[ChatMessage\]\] – 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. + +#### to_dict + +```python +to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns:** + +- dict\[str, Any\] – Dictionary with serialized data. + +#### from_dict + +```python +from_dict(data: dict[str, Any]) -> OpenAPIServiceConnector +``` + +Deserializes the component from a dictionary. + +**Parameters:** + +- **data** (dict\[str, Any\]) – The dictionary to deserialize from. + +**Returns:** + +- OpenAPIServiceConnector – 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** (list\[str | Path | ByteStream\]) – File paths or ByteStream objects of OpenAPI definitions (in JSON or YAML format). + +**Returns:** + +- dict\[str, Any\] – 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. +- ValueError – If the source type is not recognized or no functions are found in the OpenAPI definitions. diff --git a/docs-website/reference_versioned_docs/version-2.25/integrations-api/openapi.md b/docs-website/reference_versioned_docs/version-2.25/integrations-api/openapi.md new file mode 100644 index 00000000000..e0543a065a1 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.25/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** (str) – URL, file path, or raw string of the OpenAPI specification +- **credentials** (Secret | None) – Optional API key or credentials for the service wrapped in a Secret +- **service_kwargs** (dict\[str, Any\] | None) – 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** (str) – The operationId from the OpenAPI spec to invoke +- **arguments** (dict\[str, Any\] | None) – Optional parameters for the endpoint (query, path, or body parameters) + +**Returns:** + +- dict\[str, Any\] – 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** (str) – The URL to append this operation's path to when making + the call. +- **data** (Any | None) – The request body to send. +- **parameters** (dict\[str, Any\] | None) – The parameters used to create the path. +- **raw_response** (bool) – If true, return the raw response instead of validating + and extrapolating it. +- **security** (dict\[str, str\] | None) – The security scheme to use, and the values it needs to + process successfully. +- **session** (Any | None) – A persistent request session. +- **verify** (bool | str) – If we should do an SSL verification on the request or not. + In case str was provided, will use that as the CA. + +**Returns:** + +- Any | None – 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=, _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** ([bool | str | None) – 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** (list\[ChatMessage\]) – A list of `ChatMessage` objects containing the messages to be processed. The last message + should contain the tool calls. +- **service_openapi_spec** (dict\[str, Any\]) – The OpenAPI JSON specification object of the service to be invoked. All the refs + should already be resolved. +- **service_credentials** (dict | str | None) – The credentials to be used for authentication with the service. + Currently, only the http and apiKey OpenAPI security schemes are supported. + +**Returns:** + +- dict\[str, list\[ChatMessage\]\] – 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. + +#### to_dict + +```python +to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns:** + +- dict\[str, Any\] – Dictionary with serialized data. + +#### from_dict + +```python +from_dict(data: dict[str, Any]) -> OpenAPIServiceConnector +``` + +Deserializes the component from a dictionary. + +**Parameters:** + +- **data** (dict\[str, Any\]) – The dictionary to deserialize from. + +**Returns:** + +- OpenAPIServiceConnector – 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** (list\[str | Path | ByteStream\]) – File paths or ByteStream objects of OpenAPI definitions (in JSON or YAML format). + +**Returns:** + +- dict\[str, Any\] – 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. +- ValueError – If the source type is not recognized or no functions are found in the OpenAPI definitions. diff --git a/docs-website/reference_versioned_docs/version-2.26/integrations-api/openapi.md b/docs-website/reference_versioned_docs/version-2.26/integrations-api/openapi.md new file mode 100644 index 00000000000..e0543a065a1 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.26/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** (str) – URL, file path, or raw string of the OpenAPI specification +- **credentials** (Secret | None) – Optional API key or credentials for the service wrapped in a Secret +- **service_kwargs** (dict\[str, Any\] | None) – 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** (str) – The operationId from the OpenAPI spec to invoke +- **arguments** (dict\[str, Any\] | None) – Optional parameters for the endpoint (query, path, or body parameters) + +**Returns:** + +- dict\[str, Any\] – 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** (str) – The URL to append this operation's path to when making + the call. +- **data** (Any | None) – The request body to send. +- **parameters** (dict\[str, Any\] | None) – The parameters used to create the path. +- **raw_response** (bool) – If true, return the raw response instead of validating + and extrapolating it. +- **security** (dict\[str, str\] | None) – The security scheme to use, and the values it needs to + process successfully. +- **session** (Any | None) – A persistent request session. +- **verify** (bool | str) – If we should do an SSL verification on the request or not. + In case str was provided, will use that as the CA. + +**Returns:** + +- Any | None – 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=, _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** ([bool | str | None) – 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** (list\[ChatMessage\]) – A list of `ChatMessage` objects containing the messages to be processed. The last message + should contain the tool calls. +- **service_openapi_spec** (dict\[str, Any\]) – The OpenAPI JSON specification object of the service to be invoked. All the refs + should already be resolved. +- **service_credentials** (dict | str | None) – The credentials to be used for authentication with the service. + Currently, only the http and apiKey OpenAPI security schemes are supported. + +**Returns:** + +- dict\[str, list\[ChatMessage\]\] – 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. + +#### to_dict + +```python +to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns:** + +- dict\[str, Any\] – Dictionary with serialized data. + +#### from_dict + +```python +from_dict(data: dict[str, Any]) -> OpenAPIServiceConnector +``` + +Deserializes the component from a dictionary. + +**Parameters:** + +- **data** (dict\[str, Any\]) – The dictionary to deserialize from. + +**Returns:** + +- OpenAPIServiceConnector – 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** (list\[str | Path | ByteStream\]) – File paths or ByteStream objects of OpenAPI definitions (in JSON or YAML format). + +**Returns:** + +- dict\[str, Any\] – 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. +- ValueError – If the source type is not recognized or no functions are found in the OpenAPI definitions. diff --git a/docs-website/reference_versioned_docs/version-2.27/integrations-api/openapi.md b/docs-website/reference_versioned_docs/version-2.27/integrations-api/openapi.md new file mode 100644 index 00000000000..e0543a065a1 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.27/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** (str) – URL, file path, or raw string of the OpenAPI specification +- **credentials** (Secret | None) – Optional API key or credentials for the service wrapped in a Secret +- **service_kwargs** (dict\[str, Any\] | None) – 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** (str) – The operationId from the OpenAPI spec to invoke +- **arguments** (dict\[str, Any\] | None) – Optional parameters for the endpoint (query, path, or body parameters) + +**Returns:** + +- dict\[str, Any\] – 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** (str) – The URL to append this operation's path to when making + the call. +- **data** (Any | None) – The request body to send. +- **parameters** (dict\[str, Any\] | None) – The parameters used to create the path. +- **raw_response** (bool) – If true, return the raw response instead of validating + and extrapolating it. +- **security** (dict\[str, str\] | None) – The security scheme to use, and the values it needs to + process successfully. +- **session** (Any | None) – A persistent request session. +- **verify** (bool | str) – If we should do an SSL verification on the request or not. + In case str was provided, will use that as the CA. + +**Returns:** + +- Any | None – 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=, _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** ([bool | str | None) – 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** (list\[ChatMessage\]) – A list of `ChatMessage` objects containing the messages to be processed. The last message + should contain the tool calls. +- **service_openapi_spec** (dict\[str, Any\]) – The OpenAPI JSON specification object of the service to be invoked. All the refs + should already be resolved. +- **service_credentials** (dict | str | None) – The credentials to be used for authentication with the service. + Currently, only the http and apiKey OpenAPI security schemes are supported. + +**Returns:** + +- dict\[str, list\[ChatMessage\]\] – 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. + +#### to_dict + +```python +to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns:** + +- dict\[str, Any\] – Dictionary with serialized data. + +#### from_dict + +```python +from_dict(data: dict[str, Any]) -> OpenAPIServiceConnector +``` + +Deserializes the component from a dictionary. + +**Parameters:** + +- **data** (dict\[str, Any\]) – The dictionary to deserialize from. + +**Returns:** + +- OpenAPIServiceConnector – 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** (list\[str | Path | ByteStream\]) – File paths or ByteStream objects of OpenAPI definitions (in JSON or YAML format). + +**Returns:** + +- dict\[str, Any\] – 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. +- ValueError – If the source type is not recognized or no functions are found in the OpenAPI definitions. diff --git a/docs-website/reference_versioned_docs/version-2.28/integrations-api/openapi.md b/docs-website/reference_versioned_docs/version-2.28/integrations-api/openapi.md new file mode 100644 index 00000000000..e0543a065a1 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.28/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** (str) – URL, file path, or raw string of the OpenAPI specification +- **credentials** (Secret | None) – Optional API key or credentials for the service wrapped in a Secret +- **service_kwargs** (dict\[str, Any\] | None) – 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** (str) – The operationId from the OpenAPI spec to invoke +- **arguments** (dict\[str, Any\] | None) – Optional parameters for the endpoint (query, path, or body parameters) + +**Returns:** + +- dict\[str, Any\] – 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** (str) – The URL to append this operation's path to when making + the call. +- **data** (Any | None) – The request body to send. +- **parameters** (dict\[str, Any\] | None) – The parameters used to create the path. +- **raw_response** (bool) – If true, return the raw response instead of validating + and extrapolating it. +- **security** (dict\[str, str\] | None) – The security scheme to use, and the values it needs to + process successfully. +- **session** (Any | None) – A persistent request session. +- **verify** (bool | str) – If we should do an SSL verification on the request or not. + In case str was provided, will use that as the CA. + +**Returns:** + +- Any | None – 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=, _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** ([bool | str | None) – 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** (list\[ChatMessage\]) – A list of `ChatMessage` objects containing the messages to be processed. The last message + should contain the tool calls. +- **service_openapi_spec** (dict\[str, Any\]) – The OpenAPI JSON specification object of the service to be invoked. All the refs + should already be resolved. +- **service_credentials** (dict | str | None) – The credentials to be used for authentication with the service. + Currently, only the http and apiKey OpenAPI security schemes are supported. + +**Returns:** + +- dict\[str, list\[ChatMessage\]\] – 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. + +#### to_dict + +```python +to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns:** + +- dict\[str, Any\] – Dictionary with serialized data. + +#### from_dict + +```python +from_dict(data: dict[str, Any]) -> OpenAPIServiceConnector +``` + +Deserializes the component from a dictionary. + +**Parameters:** + +- **data** (dict\[str, Any\]) – The dictionary to deserialize from. + +**Returns:** + +- OpenAPIServiceConnector – 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** (list\[str | Path | ByteStream\]) – File paths or ByteStream objects of OpenAPI definitions (in JSON or YAML format). + +**Returns:** + +- dict\[str, Any\] – 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. +- ValueError – If the source type is not recognized or no functions are found in the OpenAPI definitions. diff --git a/docs-website/reference_versioned_docs/version-2.29/integrations-api/openapi.md b/docs-website/reference_versioned_docs/version-2.29/integrations-api/openapi.md new file mode 100644 index 00000000000..e0543a065a1 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.29/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** (str) – URL, file path, or raw string of the OpenAPI specification +- **credentials** (Secret | None) – Optional API key or credentials for the service wrapped in a Secret +- **service_kwargs** (dict\[str, Any\] | None) – 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** (str) – The operationId from the OpenAPI spec to invoke +- **arguments** (dict\[str, Any\] | None) – Optional parameters for the endpoint (query, path, or body parameters) + +**Returns:** + +- dict\[str, Any\] – 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** (str) – The URL to append this operation's path to when making + the call. +- **data** (Any | None) – The request body to send. +- **parameters** (dict\[str, Any\] | None) – The parameters used to create the path. +- **raw_response** (bool) – If true, return the raw response instead of validating + and extrapolating it. +- **security** (dict\[str, str\] | None) – The security scheme to use, and the values it needs to + process successfully. +- **session** (Any | None) – A persistent request session. +- **verify** (bool | str) – If we should do an SSL verification on the request or not. + In case str was provided, will use that as the CA. + +**Returns:** + +- Any | None – 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=, _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** ([bool | str | None) – 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** (list\[ChatMessage\]) – A list of `ChatMessage` objects containing the messages to be processed. The last message + should contain the tool calls. +- **service_openapi_spec** (dict\[str, Any\]) – The OpenAPI JSON specification object of the service to be invoked. All the refs + should already be resolved. +- **service_credentials** (dict | str | None) – The credentials to be used for authentication with the service. + Currently, only the http and apiKey OpenAPI security schemes are supported. + +**Returns:** + +- dict\[str, list\[ChatMessage\]\] – 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. + +#### to_dict + +```python +to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns:** + +- dict\[str, Any\] – Dictionary with serialized data. + +#### from_dict + +```python +from_dict(data: dict[str, Any]) -> OpenAPIServiceConnector +``` + +Deserializes the component from a dictionary. + +**Parameters:** + +- **data** (dict\[str, Any\]) – The dictionary to deserialize from. + +**Returns:** + +- OpenAPIServiceConnector – 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** (list\[str | Path | ByteStream\]) – File paths or ByteStream objects of OpenAPI definitions (in JSON or YAML format). + +**Returns:** + +- dict\[str, Any\] – 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. +- ValueError – If the source type is not recognized or no functions are found in the OpenAPI definitions. diff --git a/docs-website/reference_versioned_docs/version-2.30/integrations-api/openapi.md b/docs-website/reference_versioned_docs/version-2.30/integrations-api/openapi.md new file mode 100644 index 00000000000..e0543a065a1 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.30/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** (str) – URL, file path, or raw string of the OpenAPI specification +- **credentials** (Secret | None) – Optional API key or credentials for the service wrapped in a Secret +- **service_kwargs** (dict\[str, Any\] | None) – 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** (str) – The operationId from the OpenAPI spec to invoke +- **arguments** (dict\[str, Any\] | None) – Optional parameters for the endpoint (query, path, or body parameters) + +**Returns:** + +- dict\[str, Any\] – 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** (str) – The URL to append this operation's path to when making + the call. +- **data** (Any | None) – The request body to send. +- **parameters** (dict\[str, Any\] | None) – The parameters used to create the path. +- **raw_response** (bool) – If true, return the raw response instead of validating + and extrapolating it. +- **security** (dict\[str, str\] | None) – The security scheme to use, and the values it needs to + process successfully. +- **session** (Any | None) – A persistent request session. +- **verify** (bool | str) – If we should do an SSL verification on the request or not. + In case str was provided, will use that as the CA. + +**Returns:** + +- Any | None – 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=, _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** ([bool | str | None) – 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** (list\[ChatMessage\]) – A list of `ChatMessage` objects containing the messages to be processed. The last message + should contain the tool calls. +- **service_openapi_spec** (dict\[str, Any\]) – The OpenAPI JSON specification object of the service to be invoked. All the refs + should already be resolved. +- **service_credentials** (dict | str | None) – The credentials to be used for authentication with the service. + Currently, only the http and apiKey OpenAPI security schemes are supported. + +**Returns:** + +- dict\[str, list\[ChatMessage\]\] – 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. + +#### to_dict + +```python +to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns:** + +- dict\[str, Any\] – Dictionary with serialized data. + +#### from_dict + +```python +from_dict(data: dict[str, Any]) -> OpenAPIServiceConnector +``` + +Deserializes the component from a dictionary. + +**Parameters:** + +- **data** (dict\[str, Any\]) – The dictionary to deserialize from. + +**Returns:** + +- OpenAPIServiceConnector – 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** (list\[str | Path | ByteStream\]) – File paths or ByteStream objects of OpenAPI definitions (in JSON or YAML format). + +**Returns:** + +- dict\[str, Any\] – 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. +- ValueError – If the source type is not recognized or no functions are found in the OpenAPI definitions.