Skip to content

Commit b47d83e

Browse files
pushpak1300pushpak1300
committed
Add Tavily toolkit with Search, Extract, Crawl, and Map tools
1 parent c8593b8 commit b47d83e

12 files changed

Lines changed: 1414 additions & 2 deletions

‎README.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,17 @@ Toolkit is a community catalog of reusable AI tools for the [Laravel AI SDK](htt
1313

1414
> Requires PHP 8.4+ and `laravel/ai`.
1515
16+
## Available Tools
17+
18+
| Tool | Description |
19+
|------|-------------|
20+
| `CalculatorTool` | Evaluate mathematical expressions with perfect accuracy. Supports `+`, `-`, `*`, `/`, `%`, `^`, parentheses, and decimals. |
21+
| `DatabaseQueryTool` | Run read-only `SELECT` queries against your Laravel database and return results as JSON. |
22+
| `TavilySearch` | Search the web for real-time information using [Tavily](https://tavily.com). |
23+
| `TavilyExtract` | Extract clean, structured content from URLs. |
24+
| `TavilyCrawl` | Intelligently crawl a website and extract content. |
25+
| `TavilyMap` | Discover and map a website's structure. |
26+
1627
## Official Documentation
1728

1829
Documentation for Toolkit can be found on the [documentation site](https://toolkit.shipfastlabs.com).

‎composer.json‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,21 +33,24 @@
3333
"replace": {
3434
"shipfastlabs/toolkit-calculator": "self.version",
3535
"shipfastlabs/toolkit-database": "self.version",
36-
"shipfastlabs/toolkit-stub": "self.version"
36+
"shipfastlabs/toolkit-stub": "self.version",
37+
"shipfastlabs/toolkit-tavily": "self.version"
3738
},
3839
"minimum-stability": "dev",
3940
"prefer-stable": true,
4041
"autoload": {
4142
"psr-4": {
4243
"Shipfastlabs\\Toolkit\\": "src/",
4344
"Shipfastlabs\\Toolkit\\Calculator\\": "src/Calculator/src/",
44-
"Shipfastlabs\\Toolkit\\Database\\": "src/Database/src/"
45+
"Shipfastlabs\\Toolkit\\Database\\": "src/Database/src/",
46+
"Shipfastlabs\\Toolkit\\Tavily\\": "src/Tavily/src/"
4547
}
4648
},
4749
"autoload-dev": {
4850
"psr-4": {
4951
"Shipfastlabs\\Toolkit\\Calculator\\Tests\\": "src/Calculator/tests/",
5052
"Shipfastlabs\\Toolkit\\Database\\Tests\\": "src/Database/tests/",
53+
"Shipfastlabs\\Toolkit\\Tavily\\Tests\\": "src/Tavily/tests/",
5154
"Shipfastlabs\\Toolkit\\Tests\\": "tests/"
5255
}
5356
},

‎src/Tavily/README.md‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
# shipfastlabs/toolkit-tavily
2+
3+
[![Latest Version](https://img.shields.io/packagist/v/shipfastlabs/toolkit-tavily.svg)](https://packagist.org/packages/shipfastlabs/toolkit-tavily)
4+
[![Total Downloads](https://img.shields.io/packagist/dt/shipfastlabs/toolkit-tavily.svg)](https://packagist.org/packages/shipfastlabs/toolkit-tavily)
5+
6+
> Tavily tools for the Laravel AI SDK - Search, Extract, Crawl, and Map
7+
8+
Part of the [shipfastlabs/toolkit](https://github.com/shipfastlabs/toolkit) catalog of reusable AI tools for the Laravel AI SDK.
9+
10+
## Installation
11+
12+
```bash
13+
composer require shipfastlabs/toolkit-tavily
14+
```
15+
16+
## Usage
17+
18+
Add the tools to an agent's `tools()`:
19+
20+
```php
21+
use Shipfastlabs\Toolkit\Tavily\TavilySearch;
22+
use Shipfastlabs\Toolkit\Tavily\TavilyExtract;
23+
use Shipfastlabs\Toolkit\Tavily\TavilyCrawl;
24+
use Shipfastlabs\Toolkit\Tavily\TavilyMap;
25+
26+
$tools = [
27+
new TavilySearch,
28+
new TavilyExtract,
29+
new TavilyCrawl,
30+
new TavilyMap,
31+
];
32+
```
33+
34+
## Tools
35+
36+
### TavilySearch
37+
38+
Search the web for real-time information.
39+
40+
| Parameter | Type | Required | Description |
41+
|---------------|---------|----------|--------------------------------------------------------------------|
42+
| `query` | string | yes | The search query to look up on the web. |
43+
| `max_results` | integer | no | Maximum number of search results to return (1-10). Defaults to 5. |
44+
| `search_depth` | string | no | `"basic"` for fast results or `"advanced"` for comprehensive. Defaults to `"basic"`. |
45+
| `include_answer` | boolean | no | Whether to include a concise AI-generated answer. Defaults to false. |
46+
47+
### TavilyExtract
48+
49+
Extract clean, structured content from URLs.
50+
51+
| Parameter | Type | Required | Description |
52+
|---------------|---------|----------|--------------------------------------------------------------------|
53+
| `urls` | string | yes | A single URL or comma-separated URLs to extract content from. |
54+
| `query` | string | no | Optional query to rerank extracted chunks by relevance. |
55+
| `extract_depth` | string | no | `"basic"` or `"advanced"`. Defaults to `"basic"`. |
56+
| `format` | string | no | `"markdown"` or `"text"`. Defaults to `"markdown"`. |
57+
| `include_images` | boolean | no | Whether to include images extracted from URLs. Defaults to false. |
58+
59+
### TavilyCrawl
60+
61+
Intelligently crawl a website and extract content.
62+
63+
| Parameter | Type | Required | Description |
64+
|---------------|---------|----------|--------------------------------------------------------------------|
65+
| `url` | string | yes | The root URL to begin the crawl from. |
66+
| `instructions` | string | no | Optional natural language instructions for the crawler. |
67+
| `max_depth` | integer | no | Maximum crawl depth (1-5). Defaults to 1. |
68+
| `max_breadth` | integer | no | Maximum links to follow per page (1-500). Defaults to 20. |
69+
| `limit` | integer | no | Total number of links to process. Defaults to 50. |
70+
| `extract_depth` | string | no | `"basic"` or `"advanced"`. Defaults to `"basic"`. |
71+
| `allow_external` | boolean | no | Whether to include external domain links. Defaults to true. |
72+
73+
### TavilyMap
74+
75+
Discover and map a website's structure.
76+
77+
| Parameter | Type | Required | Description |
78+
|---------------|---------|----------|--------------------------------------------------------------------|
79+
| `url` | string | yes | The root URL to begin the mapping from. |
80+
| `instructions` | string | no | Optional natural language instructions for the crawler. |
81+
| `max_depth` | integer | no | Maximum map depth (1-5). Defaults to 1. |
82+
| `max_breadth` | integer | no | Maximum links to follow per page (1-500). Defaults to 20. |
83+
| `limit` | integer | no | Total number of links to process. Defaults to 50. |
84+
| `allow_external` | boolean | no | Whether to include external domain links. Defaults to true. |
85+
86+
## Provider setup
87+
88+
All tools read their API credentials from Laravel's `services` config and their optional defaults from the `ai` config.
89+
90+
### 1. Add the Tavily service to `config/services.php`
91+
92+
```php
93+
// config/services.php
94+
95+
return [
96+
97+
// ... existing services ...
98+
99+
'tavily' => [
100+
'key' => env('TAVILY_API_KEY'),
101+
],
102+
103+
];
104+
```
105+
106+
### 2. Add toolkit defaults to `config/ai.php`
107+
108+
```php
109+
// config/ai.php
110+
111+
return [
112+
113+
// ... existing laravel/ai config ...
114+
115+
'toolkit' => [
116+
'tavily' => [
117+
'search' => [
118+
'max_results' => (int) env('TAVILY_SEARCH_MAX_RESULTS', 5),
119+
'search_depth' => env('TAVILY_SEARCH_DEPTH', 'basic'),
120+
'include_answer' => (bool) env('TAVILY_SEARCH_INCLUDE_ANSWER', false),
121+
],
122+
'extract' => [
123+
'extract_depth' => env('TAVILY_EXTRACT_DEPTH', 'basic'),
124+
'format' => env('TAVILY_EXTRACT_FORMAT', 'markdown'),
125+
],
126+
'crawl' => [
127+
'max_depth' => (int) env('TAVILY_CRAWL_MAX_DEPTH', 1),
128+
'max_breadth' => (int) env('TAVILY_CRAWL_MAX_BREADTH', 20),
129+
'limit' => (int) env('TAVILY_CRAWL_LIMIT', 50),
130+
'extract_depth' => env('TAVILY_CRAWL_EXTRACT_DEPTH', 'basic'),
131+
],
132+
'map' => [
133+
'max_depth' => (int) env('TAVILY_MAP_MAX_DEPTH', 1),
134+
'max_breadth' => (int) env('TAVILY_MAP_MAX_BREADTH', 20),
135+
'limit' => (int) env('TAVILY_MAP_LIMIT', 50),
136+
],
137+
],
138+
],
139+
140+
];
141+
```
142+
143+
### 3. Add environment variables to `.env`
144+
145+
```dotenv
146+
TAVILY_API_KEY=tvly-your-key-here
147+
148+
# Search defaults
149+
TAVILY_SEARCH_MAX_RESULTS=5
150+
TAVILY_SEARCH_DEPTH=basic
151+
TAVILY_SEARCH_INCLUDE_ANSWER=false
152+
153+
# Extract defaults
154+
TAVILY_EXTRACT_DEPTH=basic
155+
TAVILY_EXTRACT_FORMAT=markdown
156+
157+
# Crawl defaults
158+
TAVILY_CRAWL_MAX_DEPTH=1
159+
TAVILY_CRAWL_MAX_BREADTH=20
160+
TAVILY_CRAWL_LIMIT=50
161+
TAVILY_CRAWL_EXTRACT_DEPTH=basic
162+
163+
# Map defaults
164+
TAVILY_MAP_MAX_DEPTH=1
165+
TAVILY_MAP_MAX_BREADTH=20
166+
TAVILY_MAP_LIMIT=50
167+
```
168+
169+
| Config key | Env var | Default | Description |
170+
|---|---|---|---|
171+
| `services.tavily.key` | `TAVILY_API_KEY` | - | **Required.** Your Tavily API key. |
172+
| `ai.toolkit.tavily.search.max_results` | `TAVILY_SEARCH_MAX_RESULTS` | `5` | Default search results (1-10). |
173+
| `ai.toolkit.tavily.search.search_depth` | `TAVILY_SEARCH_DEPTH` | `"basic"` | `"basic"` or `"advanced"`. |
174+
| `ai.toolkit.tavily.search.include_answer` | `TAVILY_SEARCH_INCLUDE_ANSWER` | `false` | Default for AI-generated answer. |
175+
| `ai.toolkit.tavily.extract.extract_depth` | `TAVILY_EXTRACT_DEPTH` | `"basic"` | `"basic"` or `"advanced"`. |
176+
| `ai.toolkit.tavily.extract.format` | `TAVILY_EXTRACT_FORMAT` | `"markdown"` | `"markdown"` or `"text"`. |
177+
| `ai.toolkit.tavily.crawl.max_depth` | `TAVILY_CRAWL_MAX_DEPTH` | `1` | Max crawl depth (1-5). |
178+
| `ai.toolkit.tavily.crawl.max_breadth` | `TAVILY_CRAWL_MAX_BREADTH` | `20` | Max links per page (1-500). |
179+
| `ai.toolkit.tavily.crawl.limit` | `TAVILY_CRAWL_LIMIT` | `50` | Total links to process. |
180+
| `ai.toolkit.tavily.crawl.extract_depth` | `TAVILY_CRAWL_EXTRACT_DEPTH` | `"basic"` | `"basic"` or `"advanced"`. |
181+
| `ai.toolkit.tavily.map.max_depth` | `TAVILY_MAP_MAX_DEPTH` | `1` | Max map depth (1-5). |
182+
| `ai.toolkit.tavily.map.max_breadth` | `TAVILY_MAP_MAX_BREADTH` | `20` | Max links per page (1-500). |
183+
| `ai.toolkit.tavily.map.limit` | `TAVILY_MAP_LIMIT` | `50` | Total links to process. |
184+
185+
## Safety
186+
187+
- All tools validate required inputs before calling the API.
188+
- Numeric parameters are clamped to their valid ranges.
189+
- API errors are caught and returned as friendly string messages.
190+
- Requires a valid Tavily API key.
191+
192+
## Tavily API
193+
194+
These tools use the Tavily API. Tavily offers a generous free tier with 1,000 API credits per month.
195+
196+
Full API reference:
197+
- [Search Endpoint](https://docs.tavily.com/documentation/api-reference/endpoint/search)
198+
- [Extract Endpoint](https://docs.tavily.com/documentation/api-reference/endpoint/extract)
199+
- [Crawl Endpoint](https://docs.tavily.com/documentation/api-reference/endpoint/crawl)
200+
- [Map Endpoint](https://docs.tavily.com/documentation/api-reference/endpoint/map)

‎src/Tavily/composer.json‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
{
2+
"name": "shipfastlabs/toolkit-tavily",
3+
"description": "Tavily tools for the Laravel AI SDK - Search, Extract, Crawl, and Map",
4+
"keywords": ["laravel", "ai", "tool", "tavily", "search", "extract", "crawl", "map"],
5+
"license": "MIT",
6+
"require": {
7+
"php": "^8.4.0",
8+
"laravel/ai": "^0.7"
9+
},
10+
"autoload": {
11+
"psr-4": {
12+
"Shipfastlabs\\Toolkit\\Tavily\\": "src/"
13+
}
14+
},
15+
"autoload-dev": {
16+
"psr-4": {
17+
"Shipfastlabs\\Toolkit\\Tavily\\Tests\\": "tests/"
18+
}
19+
},
20+
"minimum-stability": "dev",
21+
"prefer-stable": true
22+
}

0 commit comments

Comments
 (0)