@tavily/ai-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alpha AI Technologies Inc dba Tavily.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,248 @@
+# @tavily/ai-sdk
+
+AI SDK tools for Tavily, built for Vercel's AI SDK v5.
+
+## Features
+
+- **Search**: Real-time web search optimized for AI applications
+- **Extract**: Clean, structured content extraction from URLs
+- **Crawl**: Intelligent website crawling at scale
+- **Map**: Website structure discovery and mapping
+
+## Installation
+
+```bash
+npm install @tavily/ai-sdk
+# or
+pnpm install @tavily/ai-sdk
+# or
+yarn add @tavily/ai-sdk
+```
+
+## Prerequisites
+
+You need a Tavily API key to use these tools. Get one at [tavily.com](https://tavily.com).
+
+Set your API key as an environment variable:
+
+```bash
+export TAVILY_API_KEY=tvly-your-api-key
+```
+
+Or pass it directly to the tool configuration.
+
+## Usage
+
+### Tavily Search
+
+Search the web for real-time, AI-optimized information:
+
+```typescript
+import { tavilySearch } from "@tavily/ai-sdk";
+import { generateText, gateway } from "ai";
+
+const result = await generateText({
+  model: gateway("openai/gpt-5-mini"),
+  prompt: "What are the latest developments in quantum computing?",
+  tools: {
+    tavilySearch: tavilySearch({
+      searchDepth: "advanced",
+      includeAnswer: true,
+      maxResults: 5,
+    }),
+  },
+});
+```
+
+**Configuration Options:**
+- `apiKey?: string` - Tavily API key (defaults to `TAVILY_API_KEY` env var)
+- `searchDepth?: "basic" | "advanced"` - Search depth (default: "basic")
+- `topic?: "general" | "news" | "finance"` - Search category (default: "general")
+- `includeImages?: boolean` - Include images in results (default: false)
+- `includeAnswer?: boolean` - Include AI-generated answer (default: false)
+- `maxResults?: number` - Maximum results to return (default: 5)
+- `includeImageDescriptions?: boolean` - Include AI-generated image descriptions
+- `includeRawContent?: false | "markdown" | "text"` - Include raw content in specified format
+- `includeDomains?: string[]` - List of domains to include in search
+- `excludeDomains?: string[]` - List of domains to exclude from search
+- `maxTokens?: number` - Maximum number of tokens in response
+- `timeRange?: "year" | "month" | "week" | "day" | "y" | "m" | "w" | "d"` - Time range for results
+- `chunksPerSource?: number` - Number of content chunks per source
+- `country?: string` - Country code for localized results
+- `startDate?: string` - Start date for results (YYYY-MM-DD format)
+- `endDate?: string` - End date for results (YYYY-MM-DD format)
+- `days?: number` - Number of days back to search (for news/finance topics)
+- `autoParameters?: boolean` - Enable automatic parameter optimization
+- `timeout?: number` - Request timeout in milliseconds
+- `includeFavicon?: boolean` - Include favicon URLs in results
+- `proxies?: { http?: string, https?: string }` - HTTP/HTTPS proxy configuration
+- `apiBaseURL?: string` - Custom API base URL
+
+### Tavily Extract
+
+Extract clean, structured content from URLs:
+
+```typescript
+import { tavilyExtract } from "@tavily/ai-sdk";
+import { generateText, gateway } from "ai";
+
+const result = await generateText({
+  model: gateway("openai/gpt-5-mini"),
+  prompt: "Extract and summarize the content from https://tavily.com",
+  tools: {
+    tavilyExtract: tavilyExtract(),
+  },
+});
+```
+
+**Configuration Options:**
+- `apiKey?: string` - Tavily API key (defaults to `TAVILY_API_KEY` env var)
+- `includeImages?: boolean` - Include images in extracted content (default: false)
+- `extractDepth?: "basic" | "advanced"` - Extraction depth (default: "basic")
+- `format?: "markdown" | "text"` - Output format (default: "markdown")
+- `timeout?: number` - Request timeout in milliseconds
+- `includeFavicon?: boolean` - Include favicon URLs in results
+- `proxies?: { http?: string, https?: string }` - HTTP/HTTPS proxy configuration
+- `apiBaseURL?: string` - Custom API base URL
+
+**Input Parameters (for AI agent):**
+- `urls: string[]` - Array of URLs to extract content from (required)
+- `extractDepth?: "basic" | "advanced"` - Override extraction depth per call
+
+### Tavily Crawl
+
+Crawl websites to discover and extract content from multiple pages:
+
+```typescript
+import { tavilyCrawl } from "@tavily/ai-sdk";
+import { generateText, gateway } from "ai";
+
+const result = await generateText({
+  model: gateway("openai/gpt-5-mini"),
+  prompt: "Crawl tavily.com and tell me about their integrations",
+  tools: {
+    tavilyCrawl: tavilyCrawl(),
+  },
+});
+```
+
+**Configuration Options:**
+- `apiKey?: string` - Tavily API key (defaults to `TAVILY_API_KEY` env var)
+- `maxDepth?: number` - Maximum crawl depth (1-5, default: 1)
+- `maxBreadth?: number` - Maximum pages per depth level (1-100, default: 20)
+- `limit?: number` - Maximum total pages to crawl (default: 50)
+- `extractDepth?: "basic" | "advanced"` - Content extraction depth
+- `instructions?: string` - Natural language crawling instructions
+- `selectPaths?: string[]` - Path patterns to include (e.g., `["/blog/*"]`)
+- `selectDomains?: string[]` - Domains to include
+- `excludePaths?: string[]` - Path patterns to exclude (e.g., `["/admin/*"]`)
+- `excludeDomains?: string[]` - Domains to exclude
+- `allowExternal?: boolean` - Allow crawling external domains (default: false)
+- `includeImages?: boolean` - Include images in extracted content
+- `format?: "markdown" | "text"` - Output format (default: "markdown")
+- `timeout?: number` - Request timeout in milliseconds
+- `includeFavicon?: boolean` - Include favicon URLs in results
+- `proxies?: { http?: string, https?: string }` - HTTP/HTTPS proxy configuration
+- `apiBaseURL?: string` - Custom API base URL
+
+**Input Parameters (for AI agent):**
+- `url: string` - Base URL to start crawling from (required)
+- `maxDepth?: number` - Override maximum crawl depth per call
+- `extractDepth?: "basic" | "advanced"` - Override extraction depth per call
+- `instructions?: string` - Override or specify crawling instructions per call
+- `allowExternal?: boolean` - Override external domain crawling setting per call
+
+### Tavily Map
+
+Map website structure to understand site architecture:
+
+```typescript
+import { tavilyMap } from "@tavily/ai-sdk";
+import { generateText, gateway } from "ai";
+
+const result = await generateText({
+  model: gateway("openai/gpt-5-mini"),
+  prompt: "Map the structure of tavily.com",
+  tools: {
+    tavilyMap: tavilyMap(),
+  },
+});
+```
+
+**Configuration Options:**
+- `apiKey?: string` - Tavily API key (defaults to `TAVILY_API_KEY` env var)
+- `maxDepth?: number` - Maximum mapping depth (1-5, default: 1)
+- `maxBreadth?: number` - Maximum pages per depth level (1-100, default: 20)
+- `limit?: number` - Maximum total pages to map (default: 50)
+- `instructions?: string` - Natural language mapping instructions
+- `selectPaths?: string[]` - Path patterns to include (e.g., `["/docs/*"]`)
+- `selectDomains?: string[]` - Domains to include
+- `excludePaths?: string[]` - Path patterns to exclude (e.g., `["/api/*"]`)
+- `excludeDomains?: string[]` - Domains to exclude
+- `allowExternal?: boolean` - Allow mapping external domains (default: false)
+- `timeout?: number` - Request timeout in milliseconds
+- `proxies?: { http?: string, https?: string }` - HTTP/HTTPS proxy configuration
+- `apiBaseURL?: string` - Custom API base URL
+
+**Input Parameters (for AI agent):**
+- `url: string` - Base URL to start mapping from (required)
+- `maxDepth?: number` - Override maximum mapping depth per call
+- `instructions?: string` - Override or specify mapping instructions per call
+- `allowExternal?: boolean` - Override external domain mapping setting per call
+
+
+## Using Multiple Tools Together
+
+You can combine multiple Tavily tools in a single AI agent:
+
+```typescript
+import { 
+  tavilySearch, 
+  tavilyExtract, 
+  tavilyCrawl, 
+  tavilyMap 
+} from "@tavily/ai-sdk";
+import { generateText, gateway } from "ai";
+
+const result = await generateText({
+  model: gateway("openai/gpt-5-mini"),
+  prompt: "Research the company at tavily.com - search for news, map their site, and extract key pages",
+  tools: {
+    tavilySearch: tavilySearch({ searchDepth: "advanced" }),
+    tavilyExtract: tavilyExtract(),
+    tavilyCrawl: tavilyCrawl(),
+    tavilyMap: tavilyMap(),
+  },
+});
+```
+
+## Development
+
+### Setup
+
+1. Clone the repository
+2. Install dependencies:
+
+```bash
+npm install
+```
+
+3. Create a `.env` file:
+
+```bash
+TAVILY_API_KEY=tvly-your-api-key
+```
+
+## API Reference
+
+For detailed API documentation, visit [docs.tavily.com](https://docs.tavily.com).
+
+## License
+
+MIT
+
+## Support
+
+- Documentation: [docs.tavily.com](https://docs.tavily.com)
+- Support: [help.tavily.com](https://help.tavily.com)
+- Issues: [GitHub Issues](https://github.com/tavily-ai/ai-sdk/issues)

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+import * as ai from 'ai';
+import * as _tavily_core from '@tavily/core';
+import { TavilyClientOptions, TavilySearchOptions as TavilySearchOptions$1, TavilyExtractOptions as TavilyExtractOptions$1, TavilyCrawlOptions as TavilyCrawlOptions$1, TavilyMapOptions as TavilyMapOptions$1 } from '@tavily/core';
+
+type TavilySearchOptions = TavilyClientOptions & Partial<TavilySearchOptions$1>;
+/**
+ * Tavily Search tool for AI SDK
+ * Performs web searches optimized for AI applications with real-time, contextual information
+ */
+declare const tavilySearch: (options?: TavilySearchOptions) => ai.Tool<{
+    query: string;
+    searchDepth?: "basic" | "advanced" | undefined;
+    timeRange?: "year" | "month" | "week" | "day" | "y" | "m" | "w" | "d" | undefined;
+}, _tavily_core.TavilySearchResponse>;
+
+type TavilyExtractOptions = TavilyClientOptions & Partial<TavilyExtractOptions$1>;
+/**
+ * Tavily Extract tool for AI SDK
+ * Extracts structured content from specified URLs with AI-optimized parsing
+ */
+declare const tavilyExtract: (options?: TavilyExtractOptions) => ai.Tool<{
+    urls: string[];
+    extractDepth?: "basic" | "advanced" | undefined;
+}, _tavily_core.TavilyExtractResponse>;
+
+type TavilyCrawlOptions = TavilyClientOptions & Partial<TavilyCrawlOptions$1>;
+/**
+ * Tavily Crawl tool for AI SDK
+ * Crawls a website starting from a base URL to discover and extract content from multiple pages
+ */
+declare const tavilyCrawl: (options?: TavilyCrawlOptions) => ai.Tool<{
+    url: string;
+    maxDepth?: number | undefined;
+    extractDepth?: "basic" | "advanced" | undefined;
+    instructions?: string | undefined;
+    allowExternal?: boolean | undefined;
+}, _tavily_core.TavilyCrawlResponse>;
+
+type TavilyMapOptions = TavilyClientOptions & Partial<TavilyMapOptions$1>;
+/**
+ * Tavily Map tool for AI SDK
+ * Maps the structure of a website to discover and organize its pages and hierarchy
+ */
+declare const tavilyMap: (options?: TavilyMapOptions) => ai.Tool<{
+    url: string;
+    maxDepth?: number | undefined;
+    instructions?: string | undefined;
+    allowExternal?: boolean | undefined;
+}, _tavily_core.TavilyMapResponse>;
+
+export { tavilyCrawl, tavilyExtract, tavilyMap, tavilySearch };

package/dist/index.js

@@ -0,0 +1,135 @@
+// src/tools/tavily-search.ts
+import { tool } from "ai";
+import { z } from "zod";
+import { tavily } from "@tavily/core";
+var tavilySearch = (options = {}) => {
+  const client = tavily(options);
+  const inputSchema = z.object({
+    query: z.string().describe("The search query to look up on the web"),
+    searchDepth: z.enum(["basic", "advanced"]).optional().describe(
+      "The depth of the search - 'basic' for quick results, 'advanced' for comprehensive search"
+    ),
+    timeRange: z.enum(["year", "month", "week", "day", "y", "m", "w", "d"]).optional().describe("Time range for search results")
+  });
+  return tool({
+    description: "Search the web for real-time information using Tavily's AI-optimized search engine. Returns relevant sources, snippets, and optional AI-generated answers.",
+    inputSchema,
+    execute: async ({
+      query,
+      searchDepth: inputSearchDepth,
+      timeRange: inputTimeRange
+    }) => {
+      return await client.search(query, {
+        ...options,
+        searchDepth: inputSearchDepth ?? options.searchDepth,
+        timeRange: inputTimeRange ?? options.timeRange
+      });
+    }
+  });
+};
+
+// src/tools/tavily-extract.ts
+import { tool as tool2 } from "ai";
+import { z as z2 } from "zod";
+import { tavily as tavily2 } from "@tavily/core";
+var tavilyExtract = (options = {}) => {
+  const client = tavily2(options);
+  const inputSchema = z2.object({
+    urls: z2.array(z2.string()).describe("Array of URLs to extract content from"),
+    extractDepth: z2.enum(["basic", "advanced"]).optional().describe(
+      "Extraction depth - 'basic' for main content, 'advanced' for comprehensive extraction (default: 'basic')"
+    )
+  });
+  return tool2({
+    description: "Extract clean, structured content from one or more URLs. Returns parsed content in markdown or text format, optimized for AI consumption.",
+    inputSchema,
+    execute: async ({
+      urls,
+      extractDepth: inputExtractDepth
+    }) => {
+      return await client.extract(urls, {
+        ...options,
+        extractDepth: inputExtractDepth ?? options.extractDepth
+      });
+    }
+  });
+};
+
+// src/tools/tavily-crawl.ts
+import { tool as tool3 } from "ai";
+import { z as z3 } from "zod";
+import { tavily as tavily3 } from "@tavily/core";
+var tavilyCrawl = (options = {}) => {
+  const client = tavily3(options);
+  const inputSchema = z3.object({
+    url: z3.string().describe("The base URL to start crawling from"),
+    maxDepth: z3.number().min(1).max(5).optional().describe(
+      "Maximum depth to crawl (number of link hops from the base URL, default: 1)"
+    ),
+    extractDepth: z3.enum(["basic", "advanced"]).optional().describe("Extraction depth for page content (default: 'basic')"),
+    instructions: z3.string().optional().describe(
+      "Optional instructions to guide the crawler (e.g., 'only crawl blog posts', 'focus on product pages')"
+    ),
+    allowExternal: z3.boolean().optional().describe("Whether to allow crawling external domains (default: false)")
+  });
+  return tool3({
+    description: "Crawl a website starting from a base URL to discover and extract content from multiple pages. Intelligently traverses links and extracts structured data at scale.",
+    inputSchema,
+    execute: async ({
+      url,
+      maxDepth: inputMaxDepth,
+      extractDepth: inputExtractDepth,
+      instructions: inputInstructions,
+      allowExternal: inputAllowExternal
+    }) => {
+      return await client.crawl(url, {
+        ...options,
+        maxDepth: inputMaxDepth ?? options.maxDepth,
+        extractDepth: inputExtractDepth ?? options.extractDepth,
+        instructions: inputInstructions ?? options.instructions,
+        allowExternal: inputAllowExternal ?? options.allowExternal
+      });
+    }
+  });
+};
+
+// src/tools/tavily-map.ts
+import { tool as tool4 } from "ai";
+import { z as z4 } from "zod";
+import { tavily as tavily4 } from "@tavily/core";
+var tavilyMap = (options = {}) => {
+  const client = tavily4(options);
+  const inputSchema = z4.object({
+    url: z4.string().describe("The base URL to start mapping from"),
+    maxDepth: z4.number().min(1).max(5).optional().describe(
+      "Maximum depth to map (number of link hops from the base URL, default: 1)"
+    ),
+    instructions: z4.string().optional().describe(
+      "Optional instructions to guide the mapping (e.g., 'focus on documentation pages', 'skip API references')"
+    ),
+    allowExternal: z4.boolean().optional().describe("Whether to allow mapping external domains (default: false)")
+  });
+  return tool4({
+    description: "Map the structure of a website starting from a base URL. Discovers pages, links, and site hierarchy without extracting full content. Ideal for understanding site architecture.",
+    inputSchema,
+    execute: async ({
+      url,
+      maxDepth: inputMaxDepth,
+      instructions: inputInstructions,
+      allowExternal: inputAllowExternal
+    }) => {
+      return await client.map(url, {
+        ...options,
+        maxDepth: inputMaxDepth ?? options.maxDepth,
+        instructions: inputInstructions ?? options.instructions,
+        allowExternal: inputAllowExternal ?? options.allowExternal
+      });
+    }
+  });
+};
+export {
+  tavilyCrawl,
+  tavilyExtract,
+  tavilyMap,
+  tavilySearch
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@tavily/ai-sdk",
+  "version": "0.1.0",
+  "description": "Tavily AI SDK tools - Search, Extract, Crawl, and Map",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "prepublishOnly": "pnpm build"
+  },
+  "keywords": [
+    "ai",
+    "ai-sdk",
+    "tools",
+    "tavily",
+    "search",
+    "web-search",
+    "crawl",
+    "extract"
+  ],
+  "author": "Tavily",
+  "license": "MIT",
+  "packageManager": "pnpm@10.8.0",
+  "devDependencies": {
+    "@ai-sdk/openai": "^2.0.71",
+    "@types/node": "^24.10.1",
+    "dotenv": "^17.2.3",
+    "tsup": "^8.5.0",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@tavily/core": "*"
+  },
+  "peerDependencies": {
+    "ai": "^5.0.0",
+    "zod": "^4.0.0"
+  }
+}