feat: add tavily tool support (#204)

Author: chr-hertel

.env

@@ -27,6 +27,9 @@ OPENROUTER_KEY=
 # For using SerpApi (tool)
 SERP_API_KEY=
 
+# For using Tavily (tool)
+TAVILY_API_KEY=
+
 # For using MongoDB Atlas (store)
 MONGODB_URI=
 

README.md

@@ -251,6 +251,7 @@ $eventDispatcher->addListener(ToolCallsExecuted::class, function (ToolCallsExecu
 
 1. **Clock Tool**: [toolbox-clock.php](examples/toolbox-clock.php)
 1. **SerpAPI Tool**: [toolbox-serpapi.php](examples/toolbox-serpapi.php)
+1. **Tavily Tool**: [toolbox-tavily.php](examples/toolbox-tavily.php)
 1. **Weather Tool with Event Listener**: [toolbox-weather-event.php](examples/toolbox-weather-event.php)
 1. **Wikipedia Tool**: [toolbox-wikipedia.php](examples/toolbox-wikipedia.php)
 1. **YouTube Transcriber Tool**: [toolbox-youtube.php](examples/toolbox-youtube.php) (with streaming)

examples/toolbox-tavily.php

@@ -0,0 +1,33 @@
+<?php
+
+use PhpLlm\LlmChain\Bridge\OpenAI\GPT;
+use PhpLlm\LlmChain\Bridge\OpenAI\PlatformFactory;
+use PhpLlm\LlmChain\Chain;
+use PhpLlm\LlmChain\Chain\ToolBox\ChainProcessor;
+use PhpLlm\LlmChain\Chain\ToolBox\Tool\Tavily;
+use PhpLlm\LlmChain\Chain\ToolBox\ToolAnalyzer;
+use PhpLlm\LlmChain\Chain\ToolBox\ToolBox;
+use PhpLlm\LlmChain\Model\Message\Message;
+use PhpLlm\LlmChain\Model\Message\MessageBag;
+use Symfony\Component\Dotenv\Dotenv;
+use Symfony\Component\HttpClient\HttpClient;
+
+require_once dirname(__DIR__).'/vendor/autoload.php';
+(new Dotenv())->loadEnv(dirname(__DIR__).'/.env');
+
+if (empty($_ENV['OPENAI_API_KEY']) || empty($_ENV['TAVILY_API_KEY'])) {
+    echo 'Please set the OPENAI_API_KEY and TAVILY_API_KEY environment variable.'.PHP_EOL;
+    exit(1);
+}
+$platform = PlatformFactory::create($_ENV['OPENAI_API_KEY']);
+$llm = new GPT(GPT::GPT_4O_MINI);
+
+$tavily = new Tavily(HttpClient::create(), $_ENV['TAVILY_API_KEY']);
+$toolBox = new ToolBox(new ToolAnalyzer(), [$tavily]);
+$processor = new ChainProcessor($toolBox);
+$chain = new Chain($platform, $llm, [$processor], [$processor]);
+
+$messages = new MessageBag(Message::ofUser('What was the latest game result of Dallas Cowboys?'));
+$response = $chain->call($messages);
+
+echo $response->getContent().PHP_EOL;

src/Chain/ToolBox/Tool/Tavily.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpLlm\LlmChain\Chain\ToolBox\Tool;
+
+use PhpLlm\LlmChain\Chain\ToolBox\Attribute\AsTool;
+use Symfony\Contracts\HttpClient\HttpClientInterface;
+
+/**
+ * Tool integration of tavily.com.
+ */
+#[AsTool('tavily_search', description: 'search for information on the internet', method: 'search')]
+#[AsTool('tavily_extract', description: 'fetch content from a website', method: 'extract')]
+final readonly class Tavily
+{
+    /**
+     * @param array<string, string|string[]|int|bool> $options
+     */
+    public function __construct(
+        private HttpClientInterface $httpClient,
+        private string $apiKey,
+        private array $options = ['include_images' => false],
+    ) {
+    }
+
+    /**
+     * @param string $query The search query to use
+     */
+    public function search(string $query): string
+    {
+        $response = $this->httpClient->request('POST', 'https://api.tavily.com/search', [
+            'json' => array_merge($this->options, [
+                'query' => $query,
+                'api_key' => $this->apiKey,
+            ]),
+        ]);
+
+        return $response->getContent();
+    }
+
+    /**
+     * TODO: Support list of URLs.
+     *
+     * @param string $url URL to fetch information from
+     */
+    public function extract(string $url): string
+    {
+        $response = $this->httpClient->request('POST', 'https://api.tavily.com/extract', [
+            'json' => [
+                'urls' => [$url],
+                'api_key' => $this->apiKey,
+            ],
+        ]);
+
+        return $response->getContent();
+    }
+}