npm - @parallel-web/ai-sdk-tools - Versions diffs - 0.1.5 → 0.2.0 - Mend

@parallel-web/ai-sdk-tools 0.1.5 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md CHANGED Viewed

@@ -12,7 +12,7 @@ pnpm add ai @parallel-web/ai-sdk-tools
 yarn add ai @parallel-web/ai-sdk-tools
 ```
-> **Note:** This package requires AI SDK v5. If you're using AI SDK v4, see the [AI SDK v4 Implementation](#ai-sdk-v4-implementation) section below.
+> **Note:** This package requires AI SDK v5. For AI SDK v4, use `parameters` instead of `inputSchema` when defining tools manually with the `parallel-web` SDK.
 ## Usage
@@ -20,17 +20,26 @@ Add `PARALLEL_API_KEY` obtained from [Parallel Platform](https://platform.parall
 ### Search Tool
-`searchTool` uses [Parallel's web search API](https://docs.parallel.ai/api-reference/search-api/search) to get fresh relevant search results.
+`searchTool` uses [Parallel's Search API](https://docs.parallel.ai/api-reference/search-beta/search) to perform web searches and return LLM-optimized results.
+**Input schema:**
+- `objective` (required): Natural-language description of what the web search is trying to find
+- `search_queries` (optional): List of keyword search queries (1-6 words each)
+- `mode` (optional): `'agentic'` (default) for concise results in agentic loops, or `'one-shot'` for comprehensive single-response results
 ### Extract Tool
-`extractTool` uses [Parallel's extract API](https://docs.parallel.ai/api-reference/search-and-extract-api-beta/extract) to extract a web-page's content, for a given objective.
+`extractTool` uses [Parallel's Extract API](https://docs.parallel.ai/api-reference/extract-beta/extract) to fetch and extract relevant content from specific URLs.
+**Input schema:**
+- `urls` (required): List of URLs to extract content from (max 10)
+- `objective` (optional): Natural-language description of what information you're looking for
 ### Basic Example
 ```typescript
 import { openai } from '@ai-sdk/openai';
-import { streamText, type Tool } from 'ai';
+import { streamText } from 'ai';
 import { searchTool, extractTool } from '@parallel-web/ai-sdk-tools';
 const result = streamText({
@@ -46,16 +55,47 @@ const result = streamText({
 });
 // Stream the response
-return result.toDataStreamResponse();
+return result.toUIMessageStreamResponse();
 ```
-### Custom Tools
+## Factory Functions
+For more control over the tool configuration, use the factory functions to create tools with custom defaults:
+### createSearchTool
-You can create custom tools that wrap the Parallel Web API:
+Create a search tool with custom defaults for mode, max_results, excerpts, source_policy, or fetch_policy.
 ```typescript
-import { tool, generateText } from 'ai';
-import { openai } from '@ai-sdk/openai';
+import { createSearchTool } from '@parallel-web/ai-sdk-tools';
+const myCustomSearchTool = createSearchTool({
+  mode: 'one-shot',            // 'one-shot' returns more comprehensive results and longer excerpts to answer questions from a single response.
+  max_results: 5,              // Limit to 5 results
+});
+```
+### createExtractTool
+Create an extract tool with custom defaults for excerpts, full_content, or fetch_policy.
+```typescript
+import { createExtractTool } from '@parallel-web/ai-sdk-tools';
+const myExtractTool = createExtractTool({
+  full_content: true,          // Include full page content
+  excerpts: {
+    max_chars_per_result: 10000,
+  },
+});
+```
+## Direct API Usage
+You can also use the `parallel-web` SDK directly for maximum flexibility:
+```typescript
+import { tool } from 'ai';
 import { z } from 'zod';
 import { Parallel } from 'parallel-web';
@@ -64,149 +104,120 @@ const parallel = new Parallel({
 });
 const webSearch = tool({
-  description: 'Use this tool to search the web.',
+  description: 'Search the web for information.',
   inputSchema: z.object({
-    searchQueries: z.array(z.string()).describe('Search queries'),
-    usersQuestion: z.string().describe("The user's question"),
+    query: z.string().describe("The user's question"),
   }),
-  execute: async ({ searchQueries, usersQuestion }) => {
-    const search = await parallel.beta.search({
-      objective: usersQuestion,
-      search_queries: searchQueries,
-      max_results: 3,
-      max_chars_per_result: 1000,
+  execute: async ({ query }) => {
+    const result = await parallel.beta.search({
+      objective: query,
+      mode: 'agentic',
+      max_results: 5,
     });
-    return search.results;
+    return result;
   },
 });
 ```
-## AI SDK v4 Implementation
+## API Reference
-If you're using AI SDK v4, you can implement the tools manually using the Parallel Web API. The key difference is that v4 uses `parameters` instead of `inputSchema`.
+- [Search API Documentation](https://docs.parallel.ai/search/search-quickstart)
+- [Extract API Documentation](https://docs.parallel.ai/extract/extract-quickstart)
+- [Search API Best Practices](https://docs.parallel.ai/search/best-practices)
-### Search Tool (v4)
+## Response Format
+Both tools return the raw API response from Parallel:
+### Search Response
 ```typescript
-import { tool } from 'ai';
-import { z } from 'zod';
-import { Parallel } from 'parallel-web';
+{
+  search_id: string;
+  results: Array<{
+    url: string;
+    title?: string;
+    publish_date?: string;
+    excerpts: string[];
+  }>;
+  usage?: Array<{ name: string; count: number }>;
+  warnings?: Array<{ code: string; message: string }>;
+}
+```
-const parallel = new Parallel({
-  apiKey: process.env.PARALLEL_API_KEY,
-});
+### Extract Response
-function getSearchParams(
-  search_type: 'list' | 'targeted' | 'general' | 'single_page'
-): Pick<BetaSearchParams, 'max_results' | 'max_chars_per_result'> {
-  switch (search_type) {
-    case 'targeted':
-      return {
-        max_results: 5,
-        max_chars_per_result: 16000
-      };
-    case 'general':
-      return {
-        max_results: 10,
-        max_chars_per_result: 9000
-      };
-    case 'single_page':
-      return {
-        max_results: 2,
-        max_chars_per_result: 30000
-      };
-    case 'list':
-    default:
-      return {
-        max_results: 20,
-        max_chars_per_result: 1500
-      };
-  }
+```typescript
+{
+  extract_id: string;
+  results: Array<{
+    url: string;
+    title?: string;
+    excerpts?: string[];
+    full_content?: string;
+    publish_date?: string;
+  }>;
+  errors: Array<{
+    url: string;
+    error_type: string;
+    http_status_code?: number;
+    content?: string;
+  }>;
+  usage?: Array<{ name: string; count: number }>;
+  warnings?: Array<{ code: string; message: string }>;
 }
+```
-const searchTool = tool({
-  description: `Use the web_search_parallel tool to access information from the web. The
-web_search_parallel tool returns ranked, extended web excerpts optimized for LLMs.
-Intelligently scale the number of web_search_parallel tool calls to get more information
-when needed, from a single call for simple factual questions to five or more calls for
-complex research questions.`,
-  parameters: z.object({  // v4 uses parameters instead of inputSchema
-    objective: z.string().describe(
-      'Natural-language description of what the web research goal is.'
-    ),
-    search_type: z
-      .enum(['list', 'general', 'single_page', 'targeted'])
-      .optional()
-      .default('list'),
-    search_queries: z
-      .array(z.string())
-      .optional()
-      .describe('List of keyword search queries of 1-6 words.'),
-    include_domains: z
-      .array(z.string())
-      .optional()
-      .describe('List of valid URL domains to restrict search results.'),
-  }),
-  execute: async (
-    { ...args },
-    { abortSignal }: { abortSignal?: AbortSignal }
-  ) => {
-    const results = const results = await search(
-      { ...args, ...getSearchParams(args.search_type) },
-      { abortSignal }
-    );
-    return {
-      searchParams: { objective, search_type, search_queries, include_domains },
-      answer: results,
-    };
-  },
+## Migration from v0.1.x
+Version 0.2.0 introduces an updated API that conforms with Parallel's Search and Extract MCP tools:
+### searchTool changes
+- **Input schema changed**: Removed `search_type` and `include_domains`. Added `mode` parameter.
+- **Return value changed**: Now returns raw API response (`{ search_id, results, ... }`) instead of `{ searchParams, answer }`.
+**Before (v0.1.x):**
+```typescript
+const result = await searchTool.execute({
+  objective: 'Find TypeScript info',
+  search_type: 'list',
+  search_queries: ['TypeScript'],
+  include_domains: ['typescriptlang.org'],
 });
+console.log(result.answer.results);
 ```
-### Extract Tool (v4)
+**After (v0.2.0):**
 ```typescript
-import { tool } from 'ai';
-import { z } from 'zod';
-import { Parallel } from 'parallel-web';
+const result = await searchTool.execute({
+  objective: 'Find TypeScript info',
+  search_queries: ['TypeScript'],
+  mode: 'agentic', // optional, defaults to 'agentic'
+});
+console.log(result.results);
+```
-const parallel = new Parallel({
-  apiKey: process.env.PARALLEL_API_KEY,
+### extractTool changes
+- **Input schema changed**: `urls` is now first, `objective` is optional.
+- **Return value changed**: Now returns raw API response (`{ extract_id, results, errors, ... }`) instead of `{ searchParams, answer }`.
+**Before (v0.1.x):**
+```typescript
+const result = await extractTool.execute({
+  objective: 'Extract content',
+  urls: ['https://example.com'],
+  search_queries: ['keyword'],
 });
+console.log(result.answer.results);
+```
-const extractTool = tool({
-  description: `Purpose: Fetch and extract relevant content from specific web URLs.
-Ideal Use Cases:
-- Extracting content from specific URLs you've already identified
-- Exploring URLs returned by a web search in greater depth`,
-  parameters: z.object({
-    // v4 uses parameters instead of inputSchema
-    objective: z
-      .string()
-      .describe(
-        "Natural-language description of what information you're looking for from the URLs."
-      ),
-    urls: z
-      .array(z.string())
-      .describe(
-        'List of URLs to extract content from. Maximum 10 URLs per request.'
-      ),
-    search_queries: z
-      .array(z.string())
-      .optional()
-      .describe('Optional keyword search queries related to the objective.'),
-  }),
-  execute: async ({ objective, urls, search_queries }) => {
-    const results = await parallel.beta.extract({
-      objective,
-      urls,
-      search_queries,
-    });
-    return {
-      searchParams: { objective, urls, search_queries },
-      answer: results,
-    };
-  },
+**After (v0.2.0):**
+```typescript
+const result = await extractTool.execute({
+  urls: ['https://example.com'],
+  objective: 'Extract content', // optional
 });
+console.log(result.results);
 ```

package/dist/index.cjs CHANGED Viewed

@@ -10,7 +10,10 @@ var parallelClient = new Proxy({}, {
   get(_target, prop) {
     if (!_parallelClient) {
       _parallelClient = new parallelWeb.Parallel({
-        apiKey: process.env["PARALLEL_API_KEY"]
+        apiKey: process.env["PARALLEL_API_KEY"],
+        defaultHeaders: {
+          "X-Tool-Calling-Package": `npm:@parallel-web/ai-sdk-tools/v${"0.2.0"}`
+        }
       });
     }
     return _parallelClient[prop];
@@ -18,90 +21,70 @@ var parallelClient = new Proxy({}, {
 });
 // src/tools/search.ts
-function getSearchParams(search_type) {
-  switch (search_type) {
-    case "targeted":
-      return { max_results: 5, max_chars_per_result: 16e3 };
-    case "general":
-      return { max_results: 10, max_chars_per_result: 9e3 };
-    case "single_page":
-      return { max_results: 2, max_chars_per_result: 3e4 };
-    case "list":
-    default:
-      return { max_results: 20, max_chars_per_result: 1500 };
-  }
-}
-var search = async (searchArgs, { abortSignal }) => {
-  return await parallelClient.beta.search(
-    {
-      ...searchArgs
-    },
-    {
-      signal: abortSignal,
-      headers: { "parallel-beta": "search-extract-2025-10-10" }
-    }
-  );
-};
+var objectiveDescription = `Natural-language description of what the web search is trying to find.
+Try to make the search objective atomic, looking for a specific piece of information. May include guidance about preferred sources or freshness.`;
+var searchQueriesDescription = `(optional) List of keyword search queries of 1-6 words, which may include search operators. The search queries should be related to the objective. Limited to 5 entries of 200 characters each.`;
+var modeDescription = `Presets default values for different use cases. "one-shot" returns more comprehensive results and longer excerpts to answer questions from a single response, while "agentic" returns more concise, token-efficient results for use in an agentic loop. Defaults to "agentic".`;
 var searchTool = ai.tool({
-  description: `Use the web_search_parallel tool to access information from the web. The
-web_search_parallel tool returns ranked, extended web excerpts optimized for LLMs.
-Intelligently scale the number of web_search_parallel tool calls to get more information
-when needed, from a single call for simple factual questions to five or more calls for
-complex research questions.
-* Keep queries concise - 1-6 words for best results. Start broad with very short
-  queries and medium context, then add words to narrow results or use high context
-  if needed.
-* Include broader context about what the search is trying to accomplish in the
-  \`objective\` field. This helps the search engine understand the user's intent and
-  provide relevant results and excerpts.
-* Never repeat similar search queries - make every query unique. If initial results are
-  insufficient, reformulate queries to obtain new and better results.
+  description: `Purpose: Perform web searches and return results in an LLM-friendly format.
-How to use:
-- For simple queries, a one-shot call to depth is usually sufficient.
-- For complex multi-hop queries, first try to use breadth to narrow down sources. Then
-use other search types with include_domains to get more detailed results.`,
+Use the web search tool to search the web and access information from the web. The tool returns ranked, extended web excerpts optimized for LLMs.`,
   inputSchema: zod.z.object({
-    objective: zod.z.string().describe(
-      `Natural-language description of what the web research goal
- is. Specify the broad intent of the search query here. Also include any source or
- freshness guidance here. Limit to 200 characters. This should reflect the end goal so
- that the tool can better understand the intent and return the best results. Do not
- dump long texts.`
-    ),
-    search_type: zod.z.enum(["list", "general", "single_page", "targeted"]).describe(
-      `Can be "list", "general", "single_page" or "targeted".
- "list" should be used for searching for data broadly, like aggregating data or
- considering multiple sources or doing broad initial research. "targeted" should be
- used for searching for data from a specific source set. "general" is a catch all case
- if there is no specific use case from list or targeted. "single_page" extracts data
- from a single page - extremely targeted. If there is a specific webpage you want the
- data from, use "single_page" and mention the URL in the objective.
- Use search_type appropriately.`
-    ).optional().default("list"),
-    search_queries: zod.z.array(zod.z.string()).optional().describe(
-      `(optional) List of keyword search queries of 1-6
- words, which may include search operators. The search queries should be related to the
- objective. Limited to 5 entries of 200 characters each. Usually 1-3 queries are
- ideal.`
-    ),
-    include_domains: zod.z.array(zod.z.string()).optional().describe(`(optional) List of valid URL domains to explicitly
- focus on for the search. This will restrict all search results to only include results
- from the provided list. This is useful when you want to only use a specific set of
- sources. example: ["google.com", "wikipedia.org"]. Maximum 10 entries.`)
+    objective: zod.z.string().describe(objectiveDescription),
+    search_queries: zod.z.array(zod.z.string()).optional().describe(searchQueriesDescription),
+    mode: zod.z.enum(["agentic", "one-shot"]).optional().default("agentic").describe(modeDescription)
   }),
-  execute: async function({ ...args }, { abortSignal }) {
-    const results = await search(
-      { ...args, ...getSearchParams(args.search_type) },
-      { abortSignal }
+  execute: async function({ objective, search_queries, mode }, { abortSignal }) {
+    return await parallelClient.beta.search(
+      {
+        objective,
+        search_queries,
+        mode
+      },
+      {
+        signal: abortSignal
+      }
     );
-    return {
-      searchParams: args,
-      answer: results
-    };
   }
 });
+var defaultSearchDescription = `Purpose: Perform web searches and return results in an LLM-friendly format.
+Use the web search tool to search the web and access information from the web. The tool returns ranked, extended web excerpts optimized for LLMs.`;
+function createSearchTool(options = {}) {
+  const {
+    mode: defaultMode = "agentic",
+    max_results,
+    excerpts,
+    source_policy,
+    fetch_policy,
+    description = defaultSearchDescription
+  } = options;
+  return ai.tool({
+    description,
+    inputSchema: zod.z.object({
+      objective: zod.z.string().describe(objectiveDescription),
+      search_queries: zod.z.array(zod.z.string()).optional().describe(searchQueriesDescription)
+    }),
+    execute: async function({ objective, search_queries }, { abortSignal }) {
+      return await parallelClient.beta.search(
+        {
+          objective,
+          search_queries,
+          mode: defaultMode,
+          max_results,
+          excerpts,
+          source_policy,
+          fetch_policy
+        },
+        {
+          signal: abortSignal
+        }
+      );
+    }
+  });
+}
+var urlsDescription = `List of URLs to extract content from. Must be valid HTTP/HTTPS URLs. Maximum 10 URLs per request.`;
+var objectiveDescription2 = `Natural-language description of what information you're looking for from the URLs.`;
 var extractTool = ai.tool({
   description: `Purpose: Fetch and extract relevant content from specific web URLs.
@@ -109,36 +92,58 @@ Ideal Use Cases:
 - Extracting content from specific URLs you've already identified
 - Exploring URLs returned by a web search in greater depth`,
   inputSchema: zod.z.object({
-    objective: zod.z.string().describe(
-      `Natural-language description of what information you're looking for from the URLs.
- Limit to 200 characters.`
-    ),
-    urls: zod.z.array(zod.z.string()).describe(
-      `List of URLs to extract content from. Must be valid
-HTTP/HTTPS URLs. Maximum 10 URLs per request.`
-    ),
-    search_queries: zod.z.array(zod.z.string()).optional().describe(
-      `(optional) List of keyword search queries of 1-6
- words, which may include search operators. The search queries should be related to the
- objective. Limited to 5 entries of 200 characters each. Usually 1-3 queries are
- ideal.`
-    )
+    urls: zod.z.array(zod.z.string()).describe(urlsDescription),
+    objective: zod.z.string().optional().describe(objectiveDescription2)
   }),
-  execute: async function({ ...args }, { abortSignal }) {
-    const results = await parallelClient.beta.extract(
-      { ...args },
+  execute: async function({ urls, objective }, { abortSignal }) {
+    return await parallelClient.beta.extract(
       {
-        signal: abortSignal,
-        headers: { "parallel-beta": "search-extract-2025-10-10" }
+        urls,
+        objective
+      },
+      {
+        signal: abortSignal
       }
     );
-    return {
-      searchParams: args,
-      answer: results
-    };
   }
 });
+var defaultExtractDescription = `Purpose: Fetch and extract relevant content from specific web URLs.
+Ideal Use Cases:
+- Extracting content from specific URLs you've already identified
+- Exploring URLs returned by a web search in greater depth`;
+function createExtractTool(options = {}) {
+  const {
+    excerpts,
+    full_content,
+    fetch_policy,
+    description = defaultExtractDescription
+  } = options;
+  return ai.tool({
+    description,
+    inputSchema: zod.z.object({
+      urls: zod.z.array(zod.z.string()).describe(urlsDescription),
+      objective: zod.z.string().optional().describe(objectiveDescription2)
+    }),
+    execute: async function({ urls, objective }, { abortSignal }) {
+      return await parallelClient.beta.extract(
+        {
+          urls,
+          objective,
+          excerpts,
+          full_content,
+          fetch_policy
+        },
+        {
+          signal: abortSignal
+        }
+      );
+    }
+  });
+}
+exports.createExtractTool = createExtractTool;
+exports.createSearchTool = createSearchTool;
 exports.extractTool = extractTool;
 exports.searchTool = searchTool;
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"sources":["../src/client.ts","../src/tools/search.ts","../src/tools/extract.ts"],"names":["Parallel","tool","z"],"mappings":"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","file":"index.cjs","sourcesContent":["/*\n Shared Parallel Web client instance\n /\n\nimport { Parallel } from 'parallel-web';\n\nlet _parallelClient: Parallel \| null = null;\n\nexport const parallelClient = new Proxy({} as Parallel, {\n get(_target, prop) {\n if (!_parallelClient) {\n _parallelClient = new Parallel({\n apiKey: process.env['PARALLEL_API_KEY'],\n });\n }\n return (_parallelClient as any)[prop];\n },\n});\n","/\n Search tool for Parallel Web\n /\n\nimport { tool } from 'ai';\nimport { z } from 'zod';\nimport { BetaSearchParams } from 'parallel-web/resources/beta/beta.mjs';\nimport { parallelClient } from '../client.js';\n\nfunction getSearchParams(\n search_type: 'list' \| 'targeted' \| 'general' \| 'single_page'\n): Pick<BetaSearchParams, 'max_results' \| 'max_chars_per_result'> {\n switch (search_type) {\n case 'targeted':\n return { max_results: 5, max_chars_per_result: 16000 };\n case 'general':\n return { max_results: 10, max_chars_per_result: 9000 };\n case 'single_page':\n return { max_results: 2, max_chars_per_result: 30000 };\n case 'list':\n default:\n return { max_results: 20, max_chars_per_result: 1500 };\n }\n}\n\nconst search = async (\n searchArgs: BetaSearchParams,\n { abortSignal }: { abortSignal: AbortSignal \| undefined }\n) => {\n return await parallelClient.beta.search(\n {\n ...searchArgs,\n },\n {\n signal: abortSignal,\n headers: { 'parallel-beta': 'search-extract-2025-10-10' },\n }\n );\n};\n\nexport const searchTool = tool({\n description: `Use the web_search_parallel tool to access information from the web. The\nweb_search_parallel tool returns ranked, extended web excerpts optimized for LLMs.\nIntelligently scale the number of web_search_parallel tool calls to get more information\nwhen needed, from a single call for simple factual questions to five or more calls for\ncomplex research questions.\n\n Keep queries concise - 1-6 words for best results. Start broad with very short\n queries and medium context, then add words to narrow results or use high context\n if needed.\n* Include broader context about what the search is trying to accomplish in the\n \\`objective\\` field. This helps the search engine understand the user's intent and\n provide relevant results and excerpts.\n* Never repeat similar search queries - make every query unique. If initial results are\n insufficient, reformulate queries to obtain new and better results.\n\nHow to use:\n- For simple queries, a one-shot call to depth is usually sufficient.\n- For complex multi-hop queries, first try to use breadth to narrow down sources. Then\nuse other search types with include_domains to get more detailed results.`,\n inputSchema: z.object({\n objective: z.string().describe(\n `Natural-language description of what the web research goal\n is. Specify the broad intent of the search query here. Also include any source or\n freshness guidance here. Limit to 200 characters. This should reflect the end goal so\n that the tool can better understand the intent and return the best results. Do not\n dump long texts.`\n ),\n search_type: z\n .enum(['list', 'general', 'single_page', 'targeted'])\n .describe(\n `Can be \"list\", \"general\", \"single_page\" or \"targeted\".\n \"list\" should be used for searching for data broadly, like aggregating data or\n considering multiple sources or doing broad initial research. \"targeted\" should be\n used for searching for data from a specific source set. \"general\" is a catch all case\n if there is no specific use case from list or targeted. \"single_page\" extracts data\n from a single page - extremely targeted. If there is a specific webpage you want the\n data from, use \"single_page\" and mention the URL in the objective.\n Use search_type appropriately.`\n )\n .optional()\n .default('list'),\n search_queries: z\n .array(z.string())\n .optional()\n .describe(\n `(optional) List of keyword search queries of 1-6\n words, which may include search operators. The search queries should be related to the\n objective. Limited to 5 entries of 200 characters each. Usually 1-3 queries are\n ideal.`\n ),\n include_domains: z.array(z.string()).optional()\n .describe(`(optional) List of valid URL domains to explicitly\n focus on for the search. This will restrict all search results to only include results\n from the provided list. This is useful when you want to only use a specific set of\n sources. example: [\"google.com\", \"wikipedia.org\"]. Maximum 10 entries.`),\n }),\n\n execute: async function ({ ...args }, { abortSignal }) {\n const results = await search(\n { ...args, ...getSearchParams(args.search_type) },\n { abortSignal }\n );\n\n return {\n searchParams: args,\n answer: results,\n };\n },\n});\n","/*\n Extract tool for Parallel Web\n */\n\nimport { tool } from 'ai';\nimport { z } from 'zod';\nimport { parallelClient } from '../client.js';\n\nexport const extractTool = tool({\n description: `Purpose: Fetch and extract relevant content from specific web URLs.\n\nIdeal Use Cases:\n- Extracting content from specific URLs you've already identified\n- Exploring URLs returned by a web search in greater depth`,\n inputSchema: z.object({\n objective: z.string().describe(\n `Natural-language description of what information you're looking for from the URLs. \n Limit to 200 characters.`\n ),\n\n urls: z.array(z.string()).describe(\n `List of URLs to extract content from. Must be valid\nHTTP/HTTPS URLs. Maximum 10 URLs per request.`\n ),\n search_queries: z\n .array(z.string())\n .optional()\n .describe(\n `(optional) List of keyword search queries of 1-6\n words, which may include search operators. The search queries should be related to the\n objective. Limited to 5 entries of 200 characters each. Usually 1-3 queries are\n ideal.`\n ),\n }),\n\n execute: async function ({ ...args }, { abortSignal }) {\n const results = await parallelClient.beta.extract(\n { ...args },\n {\n signal: abortSignal,\n headers: { 'parallel-beta': 'search-extract-2025-10-10' },\n }\n );\n\n return {\n searchParams: args,\n answer: results,\n };\n },\n});\n"]}
1	+ {"version":3,"sources":["../src/client.ts","../src/tools/search.ts","../src/tools/extract.ts"],"names":["Parallel","tool","z","objectiveDescription"],"mappings":"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","file":"index.cjs","sourcesContent":["/*\n Shared Parallel Web client instance\n /\n\ndeclare const __PACKAGE_VERSION__: string;\n\nimport { Parallel } from 'parallel-web';\n\nlet _parallelClient: Parallel \| null = null;\n\nexport const parallelClient = new Proxy({} as Parallel, {\n get(_target, prop: keyof Parallel) {\n if (!_parallelClient) {\n _parallelClient = new Parallel({\n apiKey: process.env['PARALLEL_API_KEY'],\n defaultHeaders: {\n 'X-Tool-Calling-Package': `npm:@parallel-web/ai-sdk-tools/v${__PACKAGE_VERSION__ ?? '0.0.0'}`,\n },\n });\n }\n return _parallelClient[prop];\n },\n});\n","/\n Search tool for Parallel Web\n /\n\nimport { tool } from 'ai';\nimport { z } from 'zod';\nimport type {\n ExcerptSettings,\n FetchPolicy,\n} from 'parallel-web/resources/beta/beta.mjs';\nimport type { SourcePolicy } from 'parallel-web/resources/shared.mjs';\nimport { parallelClient } from '../client.js';\n\n/\n Options for creating a custom search tool with code-supplied defaults.\n /\nexport interface CreateSearchToolOptions {\n /\n Default mode for search. 'agentic' returns concise, token-efficient results\n * for multi-step workflows. 'one-shot' returns comprehensive results with\n * longer excerpts. Defaults to 'agentic'.\n /\n mode?: 'agentic' \| 'one-shot';\n\n /\n Maximum number of search results to return. Defaults to 10.\n /\n max_results?: number;\n\n /\n Excerpt settings for controlling excerpt length.\n /\n excerpts?: ExcerptSettings;\n\n /\n Source policy for controlling which domains to include/exclude and freshness.\n /\n source_policy?: SourcePolicy \| null;\n\n /\n Fetch policy for controlling cached vs fresh content.\n /\n fetch_policy?: FetchPolicy \| null;\n\n /\n Custom tool description. If not provided, uses the default description.\n /\n description?: string;\n}\n\nconst objectiveDescription = `Natural-language description of what the web search is trying to find.\nTry to make the search objective atomic, looking for a specific piece of information. May include guidance about preferred sources or freshness.`;\n\nconst searchQueriesDescription = `(optional) List of keyword search queries of 1-6 words, which may include search operators. The search queries should be related to the objective. Limited to 5 entries of 200 characters each.`;\n\nconst modeDescription = `Presets default values for different use cases. \"one-shot\" returns more comprehensive results and longer excerpts to answer questions from a single response, while \"agentic\" returns more concise, token-efficient results for use in an agentic loop. Defaults to \"agentic\".`;\n\n/\n Search tool that mirrors the MCP web_search_preview tool.\n * Takes objective and optional search_queries/mode, returns raw search response.\n /\nexport const searchTool = tool({\n description: `Purpose: Perform web searches and return results in an LLM-friendly format.\n\nUse the web search tool to search the web and access information from the web. The tool returns ranked, extended web excerpts optimized for LLMs.`,\n inputSchema: z.object({\n objective: z.string().describe(objectiveDescription),\n search_queries: z\n .array(z.string())\n .optional()\n .describe(searchQueriesDescription),\n mode: z\n .enum(['agentic', 'one-shot'])\n .optional()\n .default('agentic')\n .describe(modeDescription),\n }),\n\n execute: async function (\n { objective, search_queries, mode },\n { abortSignal }\n ) {\n return await parallelClient.beta.search(\n {\n objective,\n search_queries,\n mode,\n },\n {\n signal: abortSignal,\n }\n );\n },\n});\n\nconst defaultSearchDescription = `Purpose: Perform web searches and return results in an LLM-friendly format.\n\nUse the web search tool to search the web and access information from the web. The tool returns ranked, extended web excerpts optimized for LLMs.`;\n\n/\n Factory function to create a search tool with custom defaults.\n \n Use this when you want to set defaults for mode, max_results, excerpts,\n * source_policy, or fetch_policy in your code, so the LLM only needs to\n * provide objective and search_queries.\n \n @example\n * ```ts\n * const mySearchTool = createSearchTool({\n * mode: 'one-shot',\n * max_results: 5,\n * excerpts: { max_chars_per_result: 5000 },\n * });\n * ```\n /\nexport function createSearchTool(options: CreateSearchToolOptions = {}) {\n const {\n mode: defaultMode = 'agentic',\n max_results,\n excerpts,\n source_policy,\n fetch_policy,\n description = defaultSearchDescription,\n } = options;\n\n return tool({\n description,\n inputSchema: z.object({\n objective: z.string().describe(objectiveDescription),\n search_queries: z\n .array(z.string())\n .optional()\n .describe(searchQueriesDescription),\n }),\n\n execute: async function ({ objective, search_queries }, { abortSignal }) {\n return await parallelClient.beta.search(\n {\n objective,\n search_queries,\n mode: defaultMode,\n max_results,\n excerpts,\n source_policy,\n fetch_policy,\n },\n {\n signal: abortSignal,\n }\n );\n },\n });\n}\n","/\n Extract tool for Parallel Web\n /\n\nimport { tool } from 'ai';\nimport { z } from 'zod';\nimport type {\n ExcerptSettings,\n FetchPolicy,\n BetaExtractParams,\n} from 'parallel-web/resources/beta/beta.mjs';\nimport { parallelClient } from '../client.js';\n\n/\n Options for creating a custom extract tool with code-supplied defaults.\n /\nexport interface CreateExtractToolOptions {\n /\n Include excerpts from each URL relevant to the search objective and queries.\n * Can be a boolean or ExcerptSettings object. Defaults to true.\n /\n excerpts?: boolean \| ExcerptSettings;\n\n /\n Include full content from each URL. Can be a boolean or FullContentSettings object.\n * Defaults to false.\n /\n full_content?: BetaExtractParams['full_content'];\n\n /\n Fetch policy for controlling cached vs fresh content.\n /\n fetch_policy?: FetchPolicy \| null;\n\n /\n Custom tool description. If not provided, uses the default description.\n /\n description?: string;\n}\n\nconst urlsDescription = `List of URLs to extract content from. Must be valid HTTP/HTTPS URLs. Maximum 10 URLs per request.`;\n\nconst objectiveDescription = `Natural-language description of what information you're looking for from the URLs.`;\n\n/\n Extract tool that mirrors the MCP web_fetch tool.\n * Takes urls and optional objective, returns raw extract response.\n /\nexport const extractTool = tool({\n description: `Purpose: Fetch and extract relevant content from specific web URLs.\n\nIdeal Use Cases:\n- Extracting content from specific URLs you've already identified\n- Exploring URLs returned by a web search in greater depth`,\n inputSchema: z.object({\n urls: z.array(z.string()).describe(urlsDescription),\n objective: z.string().optional().describe(objectiveDescription),\n }),\n\n execute: async function (\n { urls, objective }: { urls: string[]; objective?: string },\n { abortSignal }: { abortSignal?: AbortSignal }\n ) {\n return await parallelClient.beta.extract(\n {\n urls,\n objective,\n },\n {\n signal: abortSignal,\n }\n );\n },\n});\n\nconst defaultExtractDescription = `Purpose: Fetch and extract relevant content from specific web URLs.\n\nIdeal Use Cases:\n- Extracting content from specific URLs you've already identified\n- Exploring URLs returned by a web search in greater depth`;\n\n/\n Factory function to create an extract tool with custom defaults.\n \n Use this when you want to set defaults for excerpts, full_content, or\n * fetch_policy in your code, so the LLM only needs to provide urls and objective.\n \n @example\n * ```ts\n * const myExtractTool = createExtractTool({\n * excerpts: { max_chars_per_result: 5000 },\n * full_content: true,\n * });\n * ```\n */\nexport function createExtractTool(options: CreateExtractToolOptions = {}) {\n const {\n excerpts,\n full_content,\n fetch_policy,\n description = defaultExtractDescription,\n } = options;\n\n return tool({\n description,\n inputSchema: z.object({\n urls: z.array(z.string()).describe(urlsDescription),\n objective: z.string().optional().describe(objectiveDescription),\n }),\n\n execute: async function (\n { urls, objective }: { urls: string[]; objective?: string },\n { abortSignal }: { abortSignal?: AbortSignal }\n ) {\n return await parallelClient.beta.extract(\n {\n urls,\n objective,\n excerpts,\n full_content,\n fetch_policy,\n },\n {\n signal: abortSignal,\n }\n );\n },\n });\n}\n"]}

package/dist/index.d.cts CHANGED Viewed

@@ -1,38 +1,117 @@
 import * as ai from 'ai';
 import * as parallel_web_resources_beta_beta_mjs from 'parallel-web/resources/beta/beta.mjs';
+import { ExcerptSettings, FetchPolicy, BetaExtractParams } from 'parallel-web/resources/beta/beta.mjs';
+import { SourcePolicy } from 'parallel-web/resources/shared.mjs';
 /**
- * Search tool for Parallel Web
+ * Options for creating a custom search tool with code-supplied defaults.
+ */
+interface CreateSearchToolOptions {
+    /**
+     * Default mode for search. 'agentic' returns concise, token-efficient results
+     * for multi-step workflows. 'one-shot' returns comprehensive results with
+     * longer excerpts. Defaults to 'agentic'.
+     */
+    mode?: 'agentic' | 'one-shot';
+    /**
+     * Maximum number of search results to return. Defaults to 10.
+     */
+    max_results?: number;
+    /**
+     * Excerpt settings for controlling excerpt length.
+     */
+    excerpts?: ExcerptSettings;
+    /**
+     * Source policy for controlling which domains to include/exclude and freshness.
+     */
+    source_policy?: SourcePolicy | null;
+    /**
+     * Fetch policy for controlling cached vs fresh content.
+     */
+    fetch_policy?: FetchPolicy | null;
+    /**
+     * Custom tool description. If not provided, uses the default description.
+     */
+    description?: string;
+}
+/**
+ * Search tool that mirrors the MCP web_search_preview tool.
+ * Takes objective and optional search_queries/mode, returns raw search response.
  */
 declare const searchTool: ai.Tool<{
     objective: string;
-    search_type: "list" | "targeted" | "general" | "single_page";
+    mode: "agentic" | "one-shot";
     search_queries?: string[] | undefined;
-    include_domains?: string[] | undefined;
-}, {
-    searchParams: {
-        objective: string;
-        search_type: "list" | "targeted" | "general" | "single_page";
-        search_queries?: string[] | undefined;
-        include_domains?: string[] | undefined;
-    };
-    answer: parallel_web_resources_beta_beta_mjs.SearchResult;
-}>;
+}, parallel_web_resources_beta_beta_mjs.SearchResult>;
+/**
+ * Factory function to create a search tool with custom defaults.
+ *
+ * Use this when you want to set defaults for mode, max_results, excerpts,
+ * source_policy, or fetch_policy in your code, so the LLM only needs to
+ * provide objective and search_queries.
+ *
+ * @example
+ * ```ts
+ * const mySearchTool = createSearchTool({
+ *   mode: 'one-shot',
+ *   max_results: 5,
+ *   excerpts: { max_chars_per_result: 5000 },
+ * });
+ * ```
+ */
+declare function createSearchTool(options?: CreateSearchToolOptions): ai.Tool<{
+    objective: string;
+    search_queries?: string[] | undefined;
+}, parallel_web_resources_beta_beta_mjs.SearchResult>;
 /**
- * Extract tool for Parallel Web
+ * Options for creating a custom extract tool with code-supplied defaults.
+ */
+interface CreateExtractToolOptions {
+    /**
+     * Include excerpts from each URL relevant to the search objective and queries.
+     * Can be a boolean or ExcerptSettings object. Defaults to true.
+     */
+    excerpts?: boolean | ExcerptSettings;
+    /**
+     * Include full content from each URL. Can be a boolean or FullContentSettings object.
+     * Defaults to false.
+     */
+    full_content?: BetaExtractParams['full_content'];
+    /**
+     * Fetch policy for controlling cached vs fresh content.
+     */
+    fetch_policy?: FetchPolicy | null;
+    /**
+     * Custom tool description. If not provided, uses the default description.
+     */
+    description?: string;
+}
+/**
+ * Extract tool that mirrors the MCP web_fetch tool.
+ * Takes urls and optional objective, returns raw extract response.
  */
 declare const extractTool: ai.Tool<{
-    objective: string;
     urls: string[];
-    search_queries?: string[] | undefined;
-}, {
-    searchParams: {
-        objective: string;
-        urls: string[];
-        search_queries?: string[] | undefined;
-    };
-    answer: parallel_web_resources_beta_beta_mjs.ExtractResponse;
-}>;
+    objective?: string | undefined;
+}, parallel_web_resources_beta_beta_mjs.ExtractResponse>;
+/**
+ * Factory function to create an extract tool with custom defaults.
+ *
+ * Use this when you want to set defaults for excerpts, full_content, or
+ * fetch_policy in your code, so the LLM only needs to provide urls and objective.
+ *
+ * @example
+ * ```ts
+ * const myExtractTool = createExtractTool({
+ *   excerpts: { max_chars_per_result: 5000 },
+ *   full_content: true,
+ * });
+ * ```
+ */
+declare function createExtractTool(options?: CreateExtractToolOptions): ai.Tool<{
+    urls: string[];
+    objective?: string | undefined;
+}, parallel_web_resources_beta_beta_mjs.ExtractResponse>;
-export { extractTool, searchTool };
+export { type CreateExtractToolOptions, type CreateSearchToolOptions, createExtractTool, createSearchTool, extractTool, searchTool };

package/dist/index.d.ts CHANGED Viewed

@@ -1,38 +1,117 @@
 import * as ai from 'ai';
 import * as parallel_web_resources_beta_beta_mjs from 'parallel-web/resources/beta/beta.mjs';
+import { ExcerptSettings, FetchPolicy, BetaExtractParams } from 'parallel-web/resources/beta/beta.mjs';
+import { SourcePolicy } from 'parallel-web/resources/shared.mjs';
 /**
- * Search tool for Parallel Web
+ * Options for creating a custom search tool with code-supplied defaults.
+ */
+interface CreateSearchToolOptions {
+    /**
+     * Default mode for search. 'agentic' returns concise, token-efficient results
+     * for multi-step workflows. 'one-shot' returns comprehensive results with
+     * longer excerpts. Defaults to 'agentic'.
+     */
+    mode?: 'agentic' | 'one-shot';
+    /**
+     * Maximum number of search results to return. Defaults to 10.
+     */
+    max_results?: number;
+    /**
+     * Excerpt settings for controlling excerpt length.
+     */
+    excerpts?: ExcerptSettings;
+    /**
+     * Source policy for controlling which domains to include/exclude and freshness.
+     */
+    source_policy?: SourcePolicy | null;
+    /**
+     * Fetch policy for controlling cached vs fresh content.
+     */
+    fetch_policy?: FetchPolicy | null;
+    /**
+     * Custom tool description. If not provided, uses the default description.
+     */
+    description?: string;
+}
+/**
+ * Search tool that mirrors the MCP web_search_preview tool.
+ * Takes objective and optional search_queries/mode, returns raw search response.
  */
 declare const searchTool: ai.Tool<{
     objective: string;
-    search_type: "list" | "targeted" | "general" | "single_page";
+    mode: "agentic" | "one-shot";
     search_queries?: string[] | undefined;
-    include_domains?: string[] | undefined;
-}, {
-    searchParams: {
-        objective: string;
-        search_type: "list" | "targeted" | "general" | "single_page";
-        search_queries?: string[] | undefined;
-        include_domains?: string[] | undefined;
-    };
-    answer: parallel_web_resources_beta_beta_mjs.SearchResult;
-}>;
+}, parallel_web_resources_beta_beta_mjs.SearchResult>;
+/**
+ * Factory function to create a search tool with custom defaults.
+ *
+ * Use this when you want to set defaults for mode, max_results, excerpts,
+ * source_policy, or fetch_policy in your code, so the LLM only needs to
+ * provide objective and search_queries.
+ *
+ * @example
+ * ```ts
+ * const mySearchTool = createSearchTool({
+ *   mode: 'one-shot',
+ *   max_results: 5,
+ *   excerpts: { max_chars_per_result: 5000 },
+ * });
+ * ```
+ */
+declare function createSearchTool(options?: CreateSearchToolOptions): ai.Tool<{
+    objective: string;
+    search_queries?: string[] | undefined;
+}, parallel_web_resources_beta_beta_mjs.SearchResult>;
 /**
- * Extract tool for Parallel Web
+ * Options for creating a custom extract tool with code-supplied defaults.
+ */
+interface CreateExtractToolOptions {
+    /**
+     * Include excerpts from each URL relevant to the search objective and queries.
+     * Can be a boolean or ExcerptSettings object. Defaults to true.
+     */
+    excerpts?: boolean | ExcerptSettings;
+    /**
+     * Include full content from each URL. Can be a boolean or FullContentSettings object.
+     * Defaults to false.
+     */
+    full_content?: BetaExtractParams['full_content'];
+    /**
+     * Fetch policy for controlling cached vs fresh content.
+     */
+    fetch_policy?: FetchPolicy | null;
+    /**
+     * Custom tool description. If not provided, uses the default description.
+     */
+    description?: string;
+}
+/**
+ * Extract tool that mirrors the MCP web_fetch tool.
+ * Takes urls and optional objective, returns raw extract response.
  */
 declare const extractTool: ai.Tool<{
-    objective: string;
     urls: string[];
-    search_queries?: string[] | undefined;
-}, {
-    searchParams: {
-        objective: string;
-        urls: string[];
-        search_queries?: string[] | undefined;
-    };
-    answer: parallel_web_resources_beta_beta_mjs.ExtractResponse;
-}>;
+    objective?: string | undefined;
+}, parallel_web_resources_beta_beta_mjs.ExtractResponse>;
+/**
+ * Factory function to create an extract tool with custom defaults.
+ *
+ * Use this when you want to set defaults for excerpts, full_content, or
+ * fetch_policy in your code, so the LLM only needs to provide urls and objective.
+ *
+ * @example
+ * ```ts
+ * const myExtractTool = createExtractTool({
+ *   excerpts: { max_chars_per_result: 5000 },
+ *   full_content: true,
+ * });
+ * ```
+ */
+declare function createExtractTool(options?: CreateExtractToolOptions): ai.Tool<{
+    urls: string[];
+    objective?: string | undefined;
+}, parallel_web_resources_beta_beta_mjs.ExtractResponse>;
-export { extractTool, searchTool };
+export { type CreateExtractToolOptions, type CreateSearchToolOptions, createExtractTool, createSearchTool, extractTool, searchTool };

package/dist/index.js CHANGED Viewed

@@ -8,7 +8,10 @@ var parallelClient = new Proxy({}, {
   get(_target, prop) {
     if (!_parallelClient) {
       _parallelClient = new Parallel({
-        apiKey: process.env["PARALLEL_API_KEY"]
+        apiKey: process.env["PARALLEL_API_KEY"],
+        defaultHeaders: {
+          "X-Tool-Calling-Package": `npm:@parallel-web/ai-sdk-tools/v${"0.2.0"}`
+        }
       });
     }
     return _parallelClient[prop];
@@ -16,90 +19,70 @@ var parallelClient = new Proxy({}, {
 });
 // src/tools/search.ts
-function getSearchParams(search_type) {
-  switch (search_type) {
-    case "targeted":
-      return { max_results: 5, max_chars_per_result: 16e3 };
-    case "general":
-      return { max_results: 10, max_chars_per_result: 9e3 };
-    case "single_page":
-      return { max_results: 2, max_chars_per_result: 3e4 };
-    case "list":
-    default:
-      return { max_results: 20, max_chars_per_result: 1500 };
-  }
-}
-var search = async (searchArgs, { abortSignal }) => {
-  return await parallelClient.beta.search(
-    {
-      ...searchArgs
-    },
-    {
-      signal: abortSignal,
-      headers: { "parallel-beta": "search-extract-2025-10-10" }
-    }
-  );
-};
+var objectiveDescription = `Natural-language description of what the web search is trying to find.
+Try to make the search objective atomic, looking for a specific piece of information. May include guidance about preferred sources or freshness.`;
+var searchQueriesDescription = `(optional) List of keyword search queries of 1-6 words, which may include search operators. The search queries should be related to the objective. Limited to 5 entries of 200 characters each.`;
+var modeDescription = `Presets default values for different use cases. "one-shot" returns more comprehensive results and longer excerpts to answer questions from a single response, while "agentic" returns more concise, token-efficient results for use in an agentic loop. Defaults to "agentic".`;
 var searchTool = tool({
-  description: `Use the web_search_parallel tool to access information from the web. The
-web_search_parallel tool returns ranked, extended web excerpts optimized for LLMs.
-Intelligently scale the number of web_search_parallel tool calls to get more information
-when needed, from a single call for simple factual questions to five or more calls for
-complex research questions.
-* Keep queries concise - 1-6 words for best results. Start broad with very short
-  queries and medium context, then add words to narrow results or use high context
-  if needed.
-* Include broader context about what the search is trying to accomplish in the
-  \`objective\` field. This helps the search engine understand the user's intent and
-  provide relevant results and excerpts.
-* Never repeat similar search queries - make every query unique. If initial results are
-  insufficient, reformulate queries to obtain new and better results.
+  description: `Purpose: Perform web searches and return results in an LLM-friendly format.
-How to use:
-- For simple queries, a one-shot call to depth is usually sufficient.
-- For complex multi-hop queries, first try to use breadth to narrow down sources. Then
-use other search types with include_domains to get more detailed results.`,
+Use the web search tool to search the web and access information from the web. The tool returns ranked, extended web excerpts optimized for LLMs.`,
   inputSchema: z.object({
-    objective: z.string().describe(
-      `Natural-language description of what the web research goal
- is. Specify the broad intent of the search query here. Also include any source or
- freshness guidance here. Limit to 200 characters. This should reflect the end goal so
- that the tool can better understand the intent and return the best results. Do not
- dump long texts.`
-    ),
-    search_type: z.enum(["list", "general", "single_page", "targeted"]).describe(
-      `Can be "list", "general", "single_page" or "targeted".
- "list" should be used for searching for data broadly, like aggregating data or
- considering multiple sources or doing broad initial research. "targeted" should be
- used for searching for data from a specific source set. "general" is a catch all case
- if there is no specific use case from list or targeted. "single_page" extracts data
- from a single page - extremely targeted. If there is a specific webpage you want the
- data from, use "single_page" and mention the URL in the objective.
- Use search_type appropriately.`
-    ).optional().default("list"),
-    search_queries: z.array(z.string()).optional().describe(
-      `(optional) List of keyword search queries of 1-6
- words, which may include search operators. The search queries should be related to the
- objective. Limited to 5 entries of 200 characters each. Usually 1-3 queries are
- ideal.`
-    ),
-    include_domains: z.array(z.string()).optional().describe(`(optional) List of valid URL domains to explicitly
- focus on for the search. This will restrict all search results to only include results
- from the provided list. This is useful when you want to only use a specific set of
- sources. example: ["google.com", "wikipedia.org"]. Maximum 10 entries.`)
+    objective: z.string().describe(objectiveDescription),
+    search_queries: z.array(z.string()).optional().describe(searchQueriesDescription),
+    mode: z.enum(["agentic", "one-shot"]).optional().default("agentic").describe(modeDescription)
   }),
-  execute: async function({ ...args }, { abortSignal }) {
-    const results = await search(
-      { ...args, ...getSearchParams(args.search_type) },
-      { abortSignal }
+  execute: async function({ objective, search_queries, mode }, { abortSignal }) {
+    return await parallelClient.beta.search(
+      {
+        objective,
+        search_queries,
+        mode
+      },
+      {
+        signal: abortSignal
+      }
     );
-    return {
-      searchParams: args,
-      answer: results
-    };
   }
 });
+var defaultSearchDescription = `Purpose: Perform web searches and return results in an LLM-friendly format.
+Use the web search tool to search the web and access information from the web. The tool returns ranked, extended web excerpts optimized for LLMs.`;
+function createSearchTool(options = {}) {
+  const {
+    mode: defaultMode = "agentic",
+    max_results,
+    excerpts,
+    source_policy,
+    fetch_policy,
+    description = defaultSearchDescription
+  } = options;
+  return tool({
+    description,
+    inputSchema: z.object({
+      objective: z.string().describe(objectiveDescription),
+      search_queries: z.array(z.string()).optional().describe(searchQueriesDescription)
+    }),
+    execute: async function({ objective, search_queries }, { abortSignal }) {
+      return await parallelClient.beta.search(
+        {
+          objective,
+          search_queries,
+          mode: defaultMode,
+          max_results,
+          excerpts,
+          source_policy,
+          fetch_policy
+        },
+        {
+          signal: abortSignal
+        }
+      );
+    }
+  });
+}
+var urlsDescription = `List of URLs to extract content from. Must be valid HTTP/HTTPS URLs. Maximum 10 URLs per request.`;
+var objectiveDescription2 = `Natural-language description of what information you're looking for from the URLs.`;
 var extractTool = tool({
   description: `Purpose: Fetch and extract relevant content from specific web URLs.
@@ -107,36 +90,56 @@ Ideal Use Cases:
 - Extracting content from specific URLs you've already identified
 - Exploring URLs returned by a web search in greater depth`,
   inputSchema: z.object({
-    objective: z.string().describe(
-      `Natural-language description of what information you're looking for from the URLs.
- Limit to 200 characters.`
-    ),
-    urls: z.array(z.string()).describe(
-      `List of URLs to extract content from. Must be valid
-HTTP/HTTPS URLs. Maximum 10 URLs per request.`
-    ),
-    search_queries: z.array(z.string()).optional().describe(
-      `(optional) List of keyword search queries of 1-6
- words, which may include search operators. The search queries should be related to the
- objective. Limited to 5 entries of 200 characters each. Usually 1-3 queries are
- ideal.`
-    )
+    urls: z.array(z.string()).describe(urlsDescription),
+    objective: z.string().optional().describe(objectiveDescription2)
   }),
-  execute: async function({ ...args }, { abortSignal }) {
-    const results = await parallelClient.beta.extract(
-      { ...args },
+  execute: async function({ urls, objective }, { abortSignal }) {
+    return await parallelClient.beta.extract(
       {
-        signal: abortSignal,
-        headers: { "parallel-beta": "search-extract-2025-10-10" }
+        urls,
+        objective
+      },
+      {
+        signal: abortSignal
       }
     );
-    return {
-      searchParams: args,
-      answer: results
-    };
   }
 });
+var defaultExtractDescription = `Purpose: Fetch and extract relevant content from specific web URLs.
+Ideal Use Cases:
+- Extracting content from specific URLs you've already identified
+- Exploring URLs returned by a web search in greater depth`;
+function createExtractTool(options = {}) {
+  const {
+    excerpts,
+    full_content,
+    fetch_policy,
+    description = defaultExtractDescription
+  } = options;
+  return tool({
+    description,
+    inputSchema: z.object({
+      urls: z.array(z.string()).describe(urlsDescription),
+      objective: z.string().optional().describe(objectiveDescription2)
+    }),
+    execute: async function({ urls, objective }, { abortSignal }) {
+      return await parallelClient.beta.extract(
+        {
+          urls,
+          objective,
+          excerpts,
+          full_content,
+          fetch_policy
+        },
+        {
+          signal: abortSignal
+        }
+      );
+    }
+  });
+}
-export { extractTool, searchTool };
+export { createExtractTool, createSearchTool, extractTool, searchTool };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"sources":["../src/client.ts","../src/tools/search.ts","../src/tools/extract.ts"],"names":["tool","z"],"mappings":"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","file":"index.js","sourcesContent":["/*\n Shared Parallel Web client instance\n /\n\nimport { Parallel } from 'parallel-web';\n\nlet _parallelClient: Parallel \| null = null;\n\nexport const parallelClient = new Proxy({} as Parallel, {\n get(_target, prop) {\n if (!_parallelClient) {\n _parallelClient = new Parallel({\n apiKey: process.env['PARALLEL_API_KEY'],\n });\n }\n return (_parallelClient as any)[prop];\n },\n});\n","/\n Search tool for Parallel Web\n /\n\nimport { tool } from 'ai';\nimport { z } from 'zod';\nimport { BetaSearchParams } from 'parallel-web/resources/beta/beta.mjs';\nimport { parallelClient } from '../client.js';\n\nfunction getSearchParams(\n search_type: 'list' \| 'targeted' \| 'general' \| 'single_page'\n): Pick<BetaSearchParams, 'max_results' \| 'max_chars_per_result'> {\n switch (search_type) {\n case 'targeted':\n return { max_results: 5, max_chars_per_result: 16000 };\n case 'general':\n return { max_results: 10, max_chars_per_result: 9000 };\n case 'single_page':\n return { max_results: 2, max_chars_per_result: 30000 };\n case 'list':\n default:\n return { max_results: 20, max_chars_per_result: 1500 };\n }\n}\n\nconst search = async (\n searchArgs: BetaSearchParams,\n { abortSignal }: { abortSignal: AbortSignal \| undefined }\n) => {\n return await parallelClient.beta.search(\n {\n ...searchArgs,\n },\n {\n signal: abortSignal,\n headers: { 'parallel-beta': 'search-extract-2025-10-10' },\n }\n );\n};\n\nexport const searchTool = tool({\n description: `Use the web_search_parallel tool to access information from the web. The\nweb_search_parallel tool returns ranked, extended web excerpts optimized for LLMs.\nIntelligently scale the number of web_search_parallel tool calls to get more information\nwhen needed, from a single call for simple factual questions to five or more calls for\ncomplex research questions.\n\n Keep queries concise - 1-6 words for best results. Start broad with very short\n queries and medium context, then add words to narrow results or use high context\n if needed.\n* Include broader context about what the search is trying to accomplish in the\n \\`objective\\` field. This helps the search engine understand the user's intent and\n provide relevant results and excerpts.\n* Never repeat similar search queries - make every query unique. If initial results are\n insufficient, reformulate queries to obtain new and better results.\n\nHow to use:\n- For simple queries, a one-shot call to depth is usually sufficient.\n- For complex multi-hop queries, first try to use breadth to narrow down sources. Then\nuse other search types with include_domains to get more detailed results.`,\n inputSchema: z.object({\n objective: z.string().describe(\n `Natural-language description of what the web research goal\n is. Specify the broad intent of the search query here. Also include any source or\n freshness guidance here. Limit to 200 characters. This should reflect the end goal so\n that the tool can better understand the intent and return the best results. Do not\n dump long texts.`\n ),\n search_type: z\n .enum(['list', 'general', 'single_page', 'targeted'])\n .describe(\n `Can be \"list\", \"general\", \"single_page\" or \"targeted\".\n \"list\" should be used for searching for data broadly, like aggregating data or\n considering multiple sources or doing broad initial research. \"targeted\" should be\n used for searching for data from a specific source set. \"general\" is a catch all case\n if there is no specific use case from list or targeted. \"single_page\" extracts data\n from a single page - extremely targeted. If there is a specific webpage you want the\n data from, use \"single_page\" and mention the URL in the objective.\n Use search_type appropriately.`\n )\n .optional()\n .default('list'),\n search_queries: z\n .array(z.string())\n .optional()\n .describe(\n `(optional) List of keyword search queries of 1-6\n words, which may include search operators. The search queries should be related to the\n objective. Limited to 5 entries of 200 characters each. Usually 1-3 queries are\n ideal.`\n ),\n include_domains: z.array(z.string()).optional()\n .describe(`(optional) List of valid URL domains to explicitly\n focus on for the search. This will restrict all search results to only include results\n from the provided list. This is useful when you want to only use a specific set of\n sources. example: [\"google.com\", \"wikipedia.org\"]. Maximum 10 entries.`),\n }),\n\n execute: async function ({ ...args }, { abortSignal }) {\n const results = await search(\n { ...args, ...getSearchParams(args.search_type) },\n { abortSignal }\n );\n\n return {\n searchParams: args,\n answer: results,\n };\n },\n});\n","/*\n Extract tool for Parallel Web\n */\n\nimport { tool } from 'ai';\nimport { z } from 'zod';\nimport { parallelClient } from '../client.js';\n\nexport const extractTool = tool({\n description: `Purpose: Fetch and extract relevant content from specific web URLs.\n\nIdeal Use Cases:\n- Extracting content from specific URLs you've already identified\n- Exploring URLs returned by a web search in greater depth`,\n inputSchema: z.object({\n objective: z.string().describe(\n `Natural-language description of what information you're looking for from the URLs. \n Limit to 200 characters.`\n ),\n\n urls: z.array(z.string()).describe(\n `List of URLs to extract content from. Must be valid\nHTTP/HTTPS URLs. Maximum 10 URLs per request.`\n ),\n search_queries: z\n .array(z.string())\n .optional()\n .describe(\n `(optional) List of keyword search queries of 1-6\n words, which may include search operators. The search queries should be related to the\n objective. Limited to 5 entries of 200 characters each. Usually 1-3 queries are\n ideal.`\n ),\n }),\n\n execute: async function ({ ...args }, { abortSignal }) {\n const results = await parallelClient.beta.extract(\n { ...args },\n {\n signal: abortSignal,\n headers: { 'parallel-beta': 'search-extract-2025-10-10' },\n }\n );\n\n return {\n searchParams: args,\n answer: results,\n };\n },\n});\n"]}
1	+ {"version":3,"sources":["../src/client.ts","../src/tools/search.ts","../src/tools/extract.ts"],"names":["objectiveDescription","tool","z"],"mappings":"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","file":"index.js","sourcesContent":["/*\n Shared Parallel Web client instance\n /\n\ndeclare const __PACKAGE_VERSION__: string;\n\nimport { Parallel } from 'parallel-web';\n\nlet _parallelClient: Parallel \| null = null;\n\nexport const parallelClient = new Proxy({} as Parallel, {\n get(_target, prop: keyof Parallel) {\n if (!_parallelClient) {\n _parallelClient = new Parallel({\n apiKey: process.env['PARALLEL_API_KEY'],\n defaultHeaders: {\n 'X-Tool-Calling-Package': `npm:@parallel-web/ai-sdk-tools/v${__PACKAGE_VERSION__ ?? '0.0.0'}`,\n },\n });\n }\n return _parallelClient[prop];\n },\n});\n","/\n Search tool for Parallel Web\n /\n\nimport { tool } from 'ai';\nimport { z } from 'zod';\nimport type {\n ExcerptSettings,\n FetchPolicy,\n} from 'parallel-web/resources/beta/beta.mjs';\nimport type { SourcePolicy } from 'parallel-web/resources/shared.mjs';\nimport { parallelClient } from '../client.js';\n\n/\n Options for creating a custom search tool with code-supplied defaults.\n /\nexport interface CreateSearchToolOptions {\n /\n Default mode for search. 'agentic' returns concise, token-efficient results\n * for multi-step workflows. 'one-shot' returns comprehensive results with\n * longer excerpts. Defaults to 'agentic'.\n /\n mode?: 'agentic' \| 'one-shot';\n\n /\n Maximum number of search results to return. Defaults to 10.\n /\n max_results?: number;\n\n /\n Excerpt settings for controlling excerpt length.\n /\n excerpts?: ExcerptSettings;\n\n /\n Source policy for controlling which domains to include/exclude and freshness.\n /\n source_policy?: SourcePolicy \| null;\n\n /\n Fetch policy for controlling cached vs fresh content.\n /\n fetch_policy?: FetchPolicy \| null;\n\n /\n Custom tool description. If not provided, uses the default description.\n /\n description?: string;\n}\n\nconst objectiveDescription = `Natural-language description of what the web search is trying to find.\nTry to make the search objective atomic, looking for a specific piece of information. May include guidance about preferred sources or freshness.`;\n\nconst searchQueriesDescription = `(optional) List of keyword search queries of 1-6 words, which may include search operators. The search queries should be related to the objective. Limited to 5 entries of 200 characters each.`;\n\nconst modeDescription = `Presets default values for different use cases. \"one-shot\" returns more comprehensive results and longer excerpts to answer questions from a single response, while \"agentic\" returns more concise, token-efficient results for use in an agentic loop. Defaults to \"agentic\".`;\n\n/\n Search tool that mirrors the MCP web_search_preview tool.\n * Takes objective and optional search_queries/mode, returns raw search response.\n /\nexport const searchTool = tool({\n description: `Purpose: Perform web searches and return results in an LLM-friendly format.\n\nUse the web search tool to search the web and access information from the web. The tool returns ranked, extended web excerpts optimized for LLMs.`,\n inputSchema: z.object({\n objective: z.string().describe(objectiveDescription),\n search_queries: z\n .array(z.string())\n .optional()\n .describe(searchQueriesDescription),\n mode: z\n .enum(['agentic', 'one-shot'])\n .optional()\n .default('agentic')\n .describe(modeDescription),\n }),\n\n execute: async function (\n { objective, search_queries, mode },\n { abortSignal }\n ) {\n return await parallelClient.beta.search(\n {\n objective,\n search_queries,\n mode,\n },\n {\n signal: abortSignal,\n }\n );\n },\n});\n\nconst defaultSearchDescription = `Purpose: Perform web searches and return results in an LLM-friendly format.\n\nUse the web search tool to search the web and access information from the web. The tool returns ranked, extended web excerpts optimized for LLMs.`;\n\n/\n Factory function to create a search tool with custom defaults.\n \n Use this when you want to set defaults for mode, max_results, excerpts,\n * source_policy, or fetch_policy in your code, so the LLM only needs to\n * provide objective and search_queries.\n \n @example\n * ```ts\n * const mySearchTool = createSearchTool({\n * mode: 'one-shot',\n * max_results: 5,\n * excerpts: { max_chars_per_result: 5000 },\n * });\n * ```\n /\nexport function createSearchTool(options: CreateSearchToolOptions = {}) {\n const {\n mode: defaultMode = 'agentic',\n max_results,\n excerpts,\n source_policy,\n fetch_policy,\n description = defaultSearchDescription,\n } = options;\n\n return tool({\n description,\n inputSchema: z.object({\n objective: z.string().describe(objectiveDescription),\n search_queries: z\n .array(z.string())\n .optional()\n .describe(searchQueriesDescription),\n }),\n\n execute: async function ({ objective, search_queries }, { abortSignal }) {\n return await parallelClient.beta.search(\n {\n objective,\n search_queries,\n mode: defaultMode,\n max_results,\n excerpts,\n source_policy,\n fetch_policy,\n },\n {\n signal: abortSignal,\n }\n );\n },\n });\n}\n","/\n Extract tool for Parallel Web\n /\n\nimport { tool } from 'ai';\nimport { z } from 'zod';\nimport type {\n ExcerptSettings,\n FetchPolicy,\n BetaExtractParams,\n} from 'parallel-web/resources/beta/beta.mjs';\nimport { parallelClient } from '../client.js';\n\n/\n Options for creating a custom extract tool with code-supplied defaults.\n /\nexport interface CreateExtractToolOptions {\n /\n Include excerpts from each URL relevant to the search objective and queries.\n * Can be a boolean or ExcerptSettings object. Defaults to true.\n /\n excerpts?: boolean \| ExcerptSettings;\n\n /\n Include full content from each URL. Can be a boolean or FullContentSettings object.\n * Defaults to false.\n /\n full_content?: BetaExtractParams['full_content'];\n\n /\n Fetch policy for controlling cached vs fresh content.\n /\n fetch_policy?: FetchPolicy \| null;\n\n /\n Custom tool description. If not provided, uses the default description.\n /\n description?: string;\n}\n\nconst urlsDescription = `List of URLs to extract content from. Must be valid HTTP/HTTPS URLs. Maximum 10 URLs per request.`;\n\nconst objectiveDescription = `Natural-language description of what information you're looking for from the URLs.`;\n\n/\n Extract tool that mirrors the MCP web_fetch tool.\n * Takes urls and optional objective, returns raw extract response.\n /\nexport const extractTool = tool({\n description: `Purpose: Fetch and extract relevant content from specific web URLs.\n\nIdeal Use Cases:\n- Extracting content from specific URLs you've already identified\n- Exploring URLs returned by a web search in greater depth`,\n inputSchema: z.object({\n urls: z.array(z.string()).describe(urlsDescription),\n objective: z.string().optional().describe(objectiveDescription),\n }),\n\n execute: async function (\n { urls, objective }: { urls: string[]; objective?: string },\n { abortSignal }: { abortSignal?: AbortSignal }\n ) {\n return await parallelClient.beta.extract(\n {\n urls,\n objective,\n },\n {\n signal: abortSignal,\n }\n );\n },\n});\n\nconst defaultExtractDescription = `Purpose: Fetch and extract relevant content from specific web URLs.\n\nIdeal Use Cases:\n- Extracting content from specific URLs you've already identified\n- Exploring URLs returned by a web search in greater depth`;\n\n/\n Factory function to create an extract tool with custom defaults.\n \n Use this when you want to set defaults for excerpts, full_content, or\n * fetch_policy in your code, so the LLM only needs to provide urls and objective.\n \n @example\n * ```ts\n * const myExtractTool = createExtractTool({\n * excerpts: { max_chars_per_result: 5000 },\n * full_content: true,\n * });\n * ```\n */\nexport function createExtractTool(options: CreateExtractToolOptions = {}) {\n const {\n excerpts,\n full_content,\n fetch_policy,\n description = defaultExtractDescription,\n } = options;\n\n return tool({\n description,\n inputSchema: z.object({\n urls: z.array(z.string()).describe(urlsDescription),\n objective: z.string().optional().describe(objectiveDescription),\n }),\n\n execute: async function (\n { urls, objective }: { urls: string[]; objective?: string },\n { abortSignal }: { abortSignal?: AbortSignal }\n ) {\n return await parallelClient.beta.extract(\n {\n urls,\n objective,\n excerpts,\n full_content,\n fetch_policy,\n },\n {\n signal: abortSignal,\n }\n );\n },\n });\n}\n"]}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@parallel-web/ai-sdk-tools",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "AI SDK tools for Parallel Web",
   "author": "Parallel Web",
   "license": "MIT",
@@ -41,8 +41,8 @@
     "access": "public"
   },
   "dependencies": {
-    "parallel-web": "^0.2.1",
-    "zod": "^3.23.0"
+    "parallel-web": "^0.3.1",
+    "zod": "^4.3.6"
   },
   "peerDependencies": {
     "ai": "^5.0.0"