feat: Add OpenAPI support, OpenAPITool component

[vblagoje]

This PR introduces the OpenAPITool, a powerful new component that enables calling OpenAPI service endpoints using payloads generated by chat generators from human instructions.

Usage Examples

Example 1: Searching with Serper

The following example demonstrates how to use the OpenAPITool with the SerperDev API to perform a search:

from haystack_experimental.components.tools.openapi import OpenAPITool, LLMProvider
from haystack.dataclasses import ChatMessage
from haystack.utils import Secret

tool = OpenAPITool(generator_api=LLMProvider.OPENAI,   
                                   spec="https://bit.ly/serper_dev_spec_yaml",
                                   credentials=Secret.from_token("your_serper_key"))

results = tool.run(messages=[ChatMessage.from_user("Do a search for 'Who was Nikola Tesla?'")])
print(results)

Example 2: Scraping with Firecrawl

The following example demonstrates how to use the OpenAPITool with the Firecrawl API to scrape a webpage:

from haystack_experimental.components.tools.openapi import OpenAPITool, LLMProvider
from haystack.dataclasses import ChatMessage
from haystack.utils import Secret

tool = OpenAPITool(generator_api=LLMProvider.OPENAI, 
                   spec="https://raw.githubusercontent.com/mendableai/firecrawl/main/apps/api/openapi.json",
                   credentials=Secret.from_env_var("FIRECRAWL_API_KEY"))

results = tool.run(messages=[ChatMessage.from_user("Scrape URL: https://news.ycombinator.com/")])
print(results)

Example 3: Searching with Firecrawl using Anthropic Claude

The following example demonstrates how to use the OpenAPITool with the Firecrawl API to search and get back scraped pages

from haystack_experimental.components.tools.openapi import OpenAPITool, LLMProvider
from haystack.dataclasses import ChatMessage
from haystack.utils import Secret

tool = OpenAPITool(generator_api=LLMProvider.ANTHROPIC, generator_api_params={"model":"claude-3-opus-20240229"},
                   spec="https://raw.githubusercontent.com/mendableai/firecrawl/main/apps/api/openapi.json",
                   credentials=Secret.from_env_var("FIRECRAWL_API_KEY"))

results = tool.run(messages=[ChatMessage.from_user("Scrape https://haystack.deepset.ai/blog/rag-evaluation-with-prometheus-2")])
print(results)

Demo

Here is a demo notebook featuring RAG+SerperDev, here is notebook demoing use of Anthropic models in Firecrawl WebQa RAG and finally a Cohere notebook variant of the same

[coveralls]

Pull Request Test Coverage Report for Build 9649571985

Details

• 815 of 1086 (75.05%) changed or added relevant lines in 23 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage decreased (-13.8%) to 84.481%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
haystack_experimental/util/auth.py	7	8	87.5%
test/components/tools/openapi/conftest.py	33	39	84.62%
haystack_experimental/components/tools/openapi/_payload_extraction.py	32	43	74.42%
haystack_experimental/components/tools/openapi/_schema_conversion.py	95	106	89.62%
test/components/tools/openapi/test_openapi_client_live.py	13	24	54.17%
haystack_experimental/components/tools/openapi/types.py	82	98	83.67%
test/components/tools/openapi/test_openapi_client_live_anthropic.py	13	29	44.83%
test/components/tools/openapi/test_openapi_client_live_cohere.py	14	30	46.67%
test/components/tools/openapi/test_openapi_client_live_openai.py	18	49	36.73%
test/components/tools/openapi/test_openapi_client_auth.py	69	102	67.65%

Totals
Change from base Build 9646483893:	-13.8%
Covered Lines:	1546
Relevant Lines:	1830

---

💛 - Coveralls

[vblagoje]

This is the first part of the task @shadeMe as we agreed, new tool impl comes next.
@masci the specific filesystem layout was a consensus between two of us.

[vblagoje]

I ran all the integration live tests as well locally; for those we need to setup integration runs and api keys as well

[vblagoje]

We currently support OpenAI function calling compatible models (OpenAI, fireworks, anyscale) etc
After integration of deepset-ai/haystack-core-integrations#790 users will be able to use Cohere and Anthropic function calling models.
More function calling models support should come soon, including open source models from HF

[TuanaCelik]

My first question looking at this at high level: How would I provide other haystack pipelines as tools with this component?

[vblagoje]

My first question looking at this at high level: How would I provide other haystack pipelines as tools with this component?

@TuanaCelik we'll have another component for that use case. This one is specific for openapi integration, hence the package name and the component name. We'll add another component in tools.pipeline or smth similar for that use case.

For this use case see https://github.com/vblagoje/notebooks/blob/main/haystack2x-demos/haystack_rag_serperdev_demo_new.ipynb

[vblagoje]

@shadeMe I addressed 98% of the use cases as you suggested. I deviated from your advice in these situations:

• I did not lift up OpenAPISpecification to a first class citizen as it complicates use of OpenAPITool and its DX
• I left from OpenAPISpecification.from_file (needed for testing) and I removed from_dict instead of it :-)
• I left the name credentials because although we mostly use tokens for auth, you'll see that a request for at least u/p will show up soon, and then we'll need another parameter for it breaking the OpenAPITool init
• some unintended omission might have slipped as well

[vblagoje]

@shadeMe I added back in http bearer token auth, as this one is fairly common type of auth in addition to apiKey. Even our own firecrawl example uses it:

from haystack_experimental.components.tools.openapi import OpenAPITool, LLMProvider
from haystack.dataclasses import ChatMessage

tool = OpenAPITool(generator_api=LLMProvider.ANTHROPIC, generator_api_params={"model":"claude-3-opus-20240229"},
                   tool_spec="https://raw.githubusercontent.com/mendableai/firecrawl/main/apps/api/openapi.json",
                   tool_credentials="your_firecrawl_key")

results = tool.run(messages=[ChatMessage.from_user("Search for 'What was the twitter debate between Elon Musk and Yann LeCun all about?'")])
print(results)

For reference OpenAPI Specification 3.x supports the following four types of authentication:

• HTTP authentication schemes (e.g., Basic, Bearer).
• API keys (sent as a query parameter, header, or cookie).
• OAuth2 (for various OAuth2 flows such as implicit, password, client credentials, and authorization code).
• OpenID Connect Discovery (for federated identity and single sign-on).

We support only first two excluding basic http (that's user password http auth)

[shadeMe]

FYI - There are a few more unresolved comments from the previous review.

[julian-risch]

@vblagoje Please also add the new feature to the catalog in the readme: https://github.com/deepset-ai/haystack-experimental?tab=readme-ov-file#experiments-catalog

[TuanaCelik]

@vblagoje Please also add the new feature to the catalog in the readme: https://github.com/deepset-ai/haystack-experimental?tab=readme-ov-file#experiments-catalog

This made me realize that I didn't add an entry for the OpenAIFunctionCaller - I'll make a separate PR for it?

[shadeMe]

We just need to add the component to the readMe.

[vblagoje]

@shadeMe Updated README to include the component 💪