Skip to content

Commit a368a54

Browse files
OskarStarkOskarStark
committed
Improve toolbox package structure and fix code style
- Reorganize test fixtures into tool-specific subfolders (brave/, wikipedia/) - Update test file paths to reference new fixture locations - Add doc/index.rst documentation file following platform/store pattern - Fix code style issues with php-cs-fixer (missing newlines) - Update README.md description to be more generic - Add missing newlines to configuration files
1 parent 6cca01a commit a368a54

15 files changed

+143
-23
lines changed

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ Symfony AI consists of several lower and higher level **components** and the res
1717
* **[Agent](src/agent/README.md)**: Framework for building AI agents that can interact with users and perform tasks.
1818
* **[Store](src/store/README.md)**: Data storage abstraction with indexing and retrieval for AI applications.
1919
* **[MCP SDK](src/mcp-sdk/README.md)**: SDK for [Model Context Protocol](https://modelcontextprotocol.io) enabling communication between AI agents and tools.
20-
* **[Toolbox](src/toolbox/README.md)**: Collection of third-party tools for AI agents including Brave Search and Wikipedia.
20+
* **[Toolbox](src/toolbox/README.md)**: Collection of third-party tools for AI agents.
2121
* **Bundles**
2222
* **[AI Bundle](src/ai-bundle/README.md)**: Symfony integration for AI Platform, Store and Agent components.
2323
* **[MCP Bundle](src/mcp-bundle/README.md)**: Symfony integration for MCP SDK, allowing them to act as MCP servers or clients.

‎src/toolbox/.gitattributes‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,4 @@
22
/.gitignore export-ignore
33
/phpunit.xml.dist export-ignore
44
/phpstan.dist.neon export-ignore
5-
/tests export-ignore
5+
/tests export-ignore

‎src/toolbox/CHANGELOG.md‎

Lines changed: 4 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,5 @@
1-
# CHANGELOG
1+
CHANGELOG
2+
=========
23

3-
## [Unreleased]
4-
5-
### Added
6-
- Initial release of AI Toolbox package
7-
- Brave Search tool for web search functionality
8-
- Wikipedia tool for article search and retrieval
9-
- Test coverage for all tools
10-
- PHPStan static analysis configuration
4+
0.1
5+
---

‎src/toolbox/doc/index.rst‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
Symfony AI - Toolbox Component
2+
===============================
3+
4+
The Toolbox component provides a collection of third-party tools for AI agents, including web search and knowledge retrieval capabilities.
5+
6+
Installation
7+
------------
8+
9+
Install the component using Composer:
10+
11+
.. code-block:: terminal
12+
13+
$ composer require symfony/ai-toolbox
14+
15+
Available Tools
16+
---------------
17+
18+
The Toolbox component includes ready-to-use tools that can be integrated with AI agents:
19+
20+
Brave Search Tool
21+
~~~~~~~~~~~~~~~~~
22+
23+
Provides web search functionality using the Brave Search API::
24+
25+
use Symfony\AI\Toolbox\Tool\Brave;
26+
use Symfony\Component\HttpClient\HttpClient;
27+
28+
$httpClient = HttpClient::create();
29+
$brave = new Brave($httpClient, 'your-brave-api-key');
30+
31+
// Search the web
32+
$results = $brave('latest news about Symfony');
33+
34+
The Brave tool returns an array of search results with title, description, and URL for each result.
35+
36+
**Configuration Options**
37+
38+
You can pass additional options to customize the search behavior::
39+
40+
$brave = new Brave($httpClient, $apiKey, [
41+
'country' => 'US',
42+
'safesearch' => 'moderate',
43+
'freshness' => 'pw', // Past week
44+
]);
45+
46+
See the `Brave Search API documentation`_ for all available options.
47+
48+
Wikipedia Tool
49+
~~~~~~~~~~~~~~
50+
51+
Provides search and article retrieval from Wikipedia::
52+
53+
use Symfony\AI\Toolbox\Tool\Wikipedia;
54+
use Symfony\Component\HttpClient\HttpClient;
55+
56+
$httpClient = HttpClient::create();
57+
$wikipedia = new Wikipedia($httpClient);
58+
59+
// Search for articles
60+
$searchResults = $wikipedia->search('artificial intelligence');
61+
62+
// Get article content
63+
$article = $wikipedia->article('Artificial intelligence');
64+
65+
The Wikipedia tool supports multiple languages by passing a locale parameter::
66+
67+
$wikipedia = new Wikipedia($httpClient, 'de'); // German Wikipedia
68+
69+
**Tool Methods**
70+
71+
The Wikipedia tool provides two methods that can be used as separate tools:
72+
73+
* ``search``: Search for articles by query
74+
* ``article``: Retrieve full article content by title
75+
76+
Agent Integration
77+
-----------------
78+
79+
These tools are designed to work with the `Agent Component`_ and can be registered using the ``#[AsTool]`` attribute::
80+
81+
use Symfony\AI\Agent\Agent;
82+
use Symfony\AI\Agent\Toolbox\AgentProcessor;
83+
use Symfony\AI\Agent\Toolbox\Toolbox;
84+
use Symfony\AI\Toolbox\Tool\Brave;
85+
use Symfony\AI\Toolbox\Tool\Wikipedia;
86+
87+
// Initialize HTTP client and tools
88+
$httpClient = HttpClient::create();
89+
$brave = new Brave($httpClient, $braveApiKey);
90+
$wikipedia = new Wikipedia($httpClient);
91+
92+
// Create toolbox and processor
93+
$toolbox = new Toolbox([$brave, $wikipedia]);
94+
$processor = new AgentProcessor($toolbox);
95+
96+
// Create agent with tools
97+
$agent = new Agent($platform, $model, [$processor], [$processor]);
98+
99+
Tool Configuration
100+
------------------
101+
102+
Each tool is automatically configured with the ``#[AsTool]`` attribute:
103+
104+
* **Brave Search**: Registered as ``brave_search`` tool
105+
* **Wikipedia Search**: Registered as ``wikipedia_search`` tool
106+
* **Wikipedia Article**: Registered as ``wikipedia_article`` tool
107+
108+
Requirements
109+
------------
110+
111+
* PHP 8.2 or higher
112+
* Symfony HTTP Client component
113+
* Brave Search API key (for Brave tool only)
114+
115+
The Wikipedia tool requires no API key as it uses the public Wikipedia API.
116+
117+
**Code Examples**
118+
119+
* `Brave Search Example`_
120+
* `Wikipedia Search Example`_
121+
122+
.. _`Brave Search API documentation`: https://api-dashboard.search.brave.com/app/documentation/web-search/query
123+
.. _`Agent Component`: https://github.com/symfony/ai-agent
124+
.. _`Brave Search Example`: https://github.com/symfony/ai/blob/main/examples/toolbox/brave.php
125+
.. _`Wikipedia Search Example`: https://github.com/symfony/ai/blob/main/examples/toolbox/wikipedia.php

‎src/toolbox/phpunit.xml.dist‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,4 +21,4 @@
2121
<directory>src</directory>
2222
</include>
2323
</source>
24-
</phpunit>
24+
</phpunit>

‎src/toolbox/src/Tool/Brave.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,4 +66,4 @@ public function __invoke(
6666
return ['title' => $result['title'], 'description' => $result['description'], 'url' => $result['url']];
6767
}, $data['web']['results'] ?? []);
6868
}
69-
}
69+
}

‎src/toolbox/src/Tool/Wikipedia.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -96,4 +96,4 @@ private function execute(array $query, ?string $locale = null): array
9696

9797
return $response->toArray();
9898
}
99-
}
99+
}

‎src/toolbox/tests/Tool/BraveTest.php‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ final class BraveTest extends TestCase
2323
{
2424
public function testReturnsSearchResults()
2525
{
26-
$result = JsonMockResponse::fromFile(__DIR__.'/../../fixtures/Tool/brave.json');
26+
$result = JsonMockResponse::fromFile(__DIR__.'/../fixtures/Tool/brave/brave.json');
2727
$httpClient = new MockHttpClient($result);
2828
$brave = new Brave($httpClient, 'test-api-key');
2929

@@ -40,7 +40,7 @@ public function testReturnsSearchResults()
4040

4141
public function testPassesCorrectParametersToApi()
4242
{
43-
$result = JsonMockResponse::fromFile(__DIR__.'/../../fixtures/Tool/brave.json');
43+
$result = JsonMockResponse::fromFile(__DIR__.'/../fixtures/Tool/brave/brave.json');
4444
$httpClient = new MockHttpClient($result);
4545
$brave = new Brave($httpClient, 'test-api-key', ['extra' => 'option']);
4646

@@ -67,4 +67,4 @@ public function testHandlesEmptyResults()
6767

6868
$this->assertEmpty($results);
6969
}
70-
}
70+
}

‎src/toolbox/tests/Tool/WikipediaTest.php‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ final class WikipediaTest extends TestCase
2222
{
2323
public function testSearchWithResults()
2424
{
25-
$result = JsonMockResponse::fromFile(__DIR__.'/../../fixtures/Tool/wikipedia-search-result.json');
25+
$result = JsonMockResponse::fromFile(__DIR__.'/../fixtures/Tool/wikipedia/wikipedia-search-result.json');
2626
$httpClient = new MockHttpClient($result);
2727

2828
$wikipedia = new Wikipedia($httpClient);
@@ -49,7 +49,7 @@ public function testSearchWithResults()
4949

5050
public function testSearchWithoutResults()
5151
{
52-
$result = JsonMockResponse::fromFile(__DIR__.'/../../fixtures/Tool/wikipedia-search-empty.json');
52+
$result = JsonMockResponse::fromFile(__DIR__.'/../fixtures/Tool/wikipedia/wikipedia-search-empty.json');
5353
$httpClient = new MockHttpClient($result);
5454

5555
$wikipedia = new Wikipedia($httpClient);
@@ -62,7 +62,7 @@ public function testSearchWithoutResults()
6262

6363
public function testArticleWithResult()
6464
{
65-
$result = JsonMockResponse::fromFile(__DIR__.'/../../fixtures/Tool/wikipedia-article.json');
65+
$result = JsonMockResponse::fromFile(__DIR__.'/../fixtures/Tool/wikipedia/wikipedia-article.json');
6666
$httpClient = new MockHttpClient($result);
6767

6868
$wikipedia = new Wikipedia($httpClient);
@@ -78,7 +78,7 @@ public function testArticleWithResult()
7878

7979
public function testArticleWithRedirect()
8080
{
81-
$result = JsonMockResponse::fromFile(__DIR__.'/../../fixtures/Tool/wikipedia-article-redirect.json');
81+
$result = JsonMockResponse::fromFile(__DIR__.'/../fixtures/Tool/wikipedia/wikipedia-article-redirect.json');
8282
$httpClient = new MockHttpClient($result);
8383

8484
$wikipedia = new Wikipedia($httpClient);
@@ -96,7 +96,7 @@ public function testArticleWithRedirect()
9696

9797
public function testArticleMissing()
9898
{
99-
$result = JsonMockResponse::fromFile(__DIR__.'/../../fixtures/Tool/wikipedia-article-missing.json');
99+
$result = JsonMockResponse::fromFile(__DIR__.'/../fixtures/Tool/wikipedia/wikipedia-article-missing.json');
100100
$httpClient = new MockHttpClient($result);
101101

102102
$wikipedia = new Wikipedia($httpClient);
@@ -106,4 +106,4 @@ public function testArticleMissing()
106106

107107
$this->assertSame($expected, $actual);
108108
}
109-
}
109+
}

‎src/toolbox/tests/Tool/fixtures/brave.json‎ renamed to ‎src/toolbox/tests/fixtures/Tool/brave/brave.json‎

File renamed without changes.

0 commit comments

Comments
 (0)