feat: adding basic Brave search tool and crawler

Author: chr-hertel

.env

@@ -37,6 +37,9 @@ SERP_API_KEY=
 # For using Tavily (tool)
 TAVILY_API_KEY=
 
+# For using Brave (tool)
+BRAVE_API_KEY=
+
 # For using MongoDB Atlas (store)
 MONGODB_URI=
 

README.md

@@ -340,7 +340,9 @@ $eventDispatcher->addListener(ToolCallsExecuted::class, function (ToolCallsExecu
 
 #### Code Examples (with built-in tools)
 
+1. **Brave Tool**: [toolbox-brave.php](examples/toolbox-brave.php)
 1. **Clock Tool**: [toolbox-clock.php](examples/toolbox-clock.php)
+1. **Crawler Tool**: [toolbox-brave.php](examples/toolbox-brave.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)

examples/toolbox-brave.php

@@ -0,0 +1,35 @@
+<?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\Brave;
+use PhpLlm\LlmChain\Chain\Toolbox\Tool\Crawler;
+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['BRAVE_API_KEY'])) {
+    echo 'Please set the OPENAI_API_KEY and BRAVE_API_KEY environment variable.'.PHP_EOL;
+    exit(1);
+}
+$platform = PlatformFactory::create($_ENV['OPENAI_API_KEY']);
+$llm = new GPT(GPT::GPT_4O_MINI);
+
+$httpClient = HttpClient::create();
+$brave = new Brave($httpClient, $_ENV['BRAVE_API_KEY']);
+$crawler = new Crawler($httpClient);
+$toolbox = Toolbox::create($brave, $crawler);
+$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/Brave.php

@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpLlm\LlmChain\Chain\Toolbox\Tool;
+
+use PhpLlm\LlmChain\Chain\JsonSchema\Attribute\With;
+use PhpLlm\LlmChain\Chain\Toolbox\Attribute\AsTool;
+use Symfony\Contracts\HttpClient\HttpClientInterface;
+
+#[AsTool('brave_search', 'Tool that searches the web using Brave Search')]
+final readonly class Brave
+{
+    /**
+     * @param array<string, mixed> $options See https://api-dashboard.search.brave.com/app/documentation/web-search/query#WebSearchAPIQueryParameters
+     */
+    public function __construct(
+        private HttpClientInterface $httpClient,
+        #[\SensitiveParameter]
+        private string $apiKey,
+        private array $options = [],
+    ) {
+    }
+
+    /**
+     * @param string $query  the search query term
+     * @param int    $count  The number of search results returned in response.
+     *                       Combine this parameter with offset to paginate search results.
+     * @param int    $offset The number of search results to skip before returning results.
+     *                       In order to paginate results use this parameter together with count.
+     *
+     * @return array<int, array{
+     *     title: string,
+     *     description: string,
+     *     url: string,
+     * }>
+     */
+    public function __invoke(
+        #[With(maximum: 500)]
+        string $query,
+        int $count = 20,
+        #[With(minimum: 0, maximum: 9)]
+        int $offset = 0,
+    ): array {
+        $response = $this->httpClient->request('GET', 'https://api.search.brave.com/res/v1/web/search', [
+            'headers' => ['X-Subscription-Token' => $this->apiKey],
+            'query' => array_merge($this->options, [
+                'q' => $query,
+                'count' => $count,
+                'offset' => $offset,
+            ]),
+        ]);
+
+        $data = $response->toArray();
+
+        return array_map(static function (array $result) {
+            return ['title' => $result['title'], 'description' => $result['description'], 'url' => $result['url']];
+        }, $data['web']['results'] ?? []);
+    }
+}

src/Chain/Toolbox/Tool/Crawler.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpLlm\LlmChain\Chain\Toolbox\Tool;
+
+use PhpLlm\LlmChain\Chain\Toolbox\Attribute\AsTool;
+use Symfony\Component\DomCrawler\Crawler as DomCrawler;
+use Symfony\Contracts\HttpClient\HttpClientInterface;
+
+#[AsTool('crawler', 'A tool that crawls one page of a website and returns the visible text of it.')]
+final readonly class Crawler
+{
+    public function __construct(
+        private HttpClientInterface $httpClient,
+    ) {
+        if (!class_exists(DomCrawler::class)) {
+            throw new \RuntimeException('The DomCrawler component is not installed. Please install it using "composer require symfony/dom-crawler".');
+        }
+    }
+
+    /**
+     * @param string $url the URL of the page to crawl
+     */
+    public function __invoke(string $url): string
+    {
+        $response = $this->httpClient->request('GET', $url);
+
+        return (new DomCrawler($response->getContent()))->filter('body')->text();
+    }
+}

tests/Chain/Toolbox/Tool/BraveTest.php

@@ -0,0 +1,75 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpLlm\LlmChain\Tests\Chain\Toolbox\Tool;
+
+use PhpLlm\LlmChain\Chain\Toolbox\Tool\Brave;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+use Symfony\Component\HttpClient\MockHttpClient;
+use Symfony\Component\HttpClient\Response\JsonMockResponse;
+use Symfony\Component\HttpClient\Response\MockResponse;
+
+#[CoversClass(Brave::class)]
+final class BraveTest extends TestCase
+{
+    #[Test]
+    public function returnsSearchResults(): void
+    {
+        $response = $this->jsonMockResponseFromFile(__DIR__.'/fixtures/brave.json');
+        $httpClient = new MockHttpClient($response);
+        $brave = new Brave($httpClient, 'test-api-key');
+
+        $results = $brave('latest Dallas Cowboys game result');
+
+        self::assertCount(5, $results);
+        self::assertArrayHasKey('title', $results[0]);
+        self::assertSame('Dallas Cowboys Scores, Stats and Highlights - ESPN', $results[0]['title']);
+        self::assertArrayHasKey('description', $results[0]);
+        self::assertSame('Visit ESPN for <strong>Dallas</strong> <strong>Cowboys</strong> live scores, video highlights, and <strong>latest</strong> news. Find standings and the full 2024 season schedule.', $results[0]['description']);
+        self::assertArrayHasKey('url', $results[0]);
+        self::assertSame('https://www.espn.com/nfl/team/_/name/dal/dallas-cowboys', $results[0]['url']);
+    }
+
+    #[Test]
+    public function passesCorrectParametersToApi(): void
+    {
+        $response = $this->jsonMockResponseFromFile(__DIR__.'/fixtures/brave.json');
+        $httpClient = new MockHttpClient($response);
+        $brave = new Brave($httpClient, 'test-api-key', ['extra' => 'option']);
+
+        $brave('test query', 10, 5);
+
+        $request = $response->getRequestUrl();
+        self::assertStringContainsString('q=test%20query', $request);
+        self::assertStringContainsString('count=10', $request);
+        self::assertStringContainsString('offset=5', $request);
+        self::assertStringContainsString('extra=option', $request);
+
+        $requestOptions = $response->getRequestOptions();
+        self::assertArrayHasKey('headers', $requestOptions);
+        self::assertContains('X-Subscription-Token: test-api-key', $requestOptions['headers']);
+    }
+
+    #[Test]
+    public function handlesEmptyResults(): void
+    {
+        $response = new MockResponse(json_encode(['web' => ['results' => []]]));
+        $httpClient = new MockHttpClient($response);
+        $brave = new Brave($httpClient, 'test-api-key');
+
+        $results = $brave('this should return nothing');
+
+        self::assertEmpty($results);
+    }
+
+    /**
+     * This can be replaced by `JsonMockResponse::fromFile` when dropping Symfony 6.4.
+     */
+    private function jsonMockResponseFromFile(string $file): JsonMockResponse
+    {
+        return new JsonMockResponse(json_decode(file_get_contents($file), true));
+    }
+}