@alexanderfortin/pi-tavily-tools 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Fortin
+
+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,366 @@
+# Pi Tavily Web Search Extension
+
+Add web search capabilities to Pi using the Tavily search API.
+
+This extension provides a `web_search` tool that the LLM can use to find current information, recent news, documentation, and time-sensitive data.
+
+Requires a valid `TAVILY_API_KEY` exported in the enviornment, e.g.
+
+```bash
+TAVILY_API_KEY=tvly-xxxx-xxxxxxx-xxxxxxxxxx pi
+```
+
+You can get a free one at <https://tavily.com>
+
+## Features
+
+- **Web Search:** Query the web for real-time information
+- **AI-Generated Answers:** Get direct answers to questions powered by Tavily
+- **Configurable Depth:** Choose between "basic" and "advanced" search modes
+- **Time Filtering:** Limit results to recent timeframes (e.g., last 7 days)
+- **Image Support:** Include relevant images in search results
+- **Content Extraction:** Optional raw content for deeper analysis
+- **Proper Truncation:** Output truncated to 50KB / 2000 lines to avoid context overflow
+- **Custom TUI Rendering:** Beautiful display with expandable results
+- **Error Handling:** Graceful failures with helpful error messages
+
+## Installation
+
+### Option 1: Install from npm (Recommended)
+
+```bash
+pi install npm:@alexanderfortin/pi-tavily-tools
+```
+
+### Option 2: Install from Git
+
+```bash
+pi install git:github.com/shaftoe/pi-tavily-tools
+```
+
+### Option 3: Quick Test with -e flag
+
+```bash
+git clone https://github.com/shaftoe/pi-tavily-tools
+cd pi-tavily-tools
+pi -e ./src/index.ts
+```
+
+## Setup
+
+### 1. Get a Tavily API Key
+
+Visit <https://tavily.com> and sign up for a free account. The free tier includes:
+
+- 1,000 requests per month
+- Basic search depth
+- Standard rate limits
+
+### 2. Configure the API Key
+
+Set the `TAVILY_API_KEY` environment variable:
+
+```bash
+export TAVILY_API_KEY="your-api-key-here"
+```
+
+**Add to your shell profile** (~/.zshrc, ~/.bashrc, etc.) for persistent access:
+
+```bash
+echo 'export TAVILY_API_KEY="your-api-key-here"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+## Usage
+
+### Basic Web Search
+
+Simply ask Pi to search the web:
+
+```
+Search for the latest version of React
+```
+
+```
+What are the new features in TypeScript 6.0?
+```
+
+```
+Find recent news about artificial intelligence
+```
+
+### Time-Limited Search
+
+Limit results to a specific timeframe:
+
+```
+Search for AI news from the last 7 days
+```
+
+```
+Show me the latest JavaScript updates from the past 30 days
+```
+
+### Advanced Search
+
+Use advanced search depth for more detailed results:
+
+```
+Search for quantum computing trends using advanced search
+```
+
+### Image Search
+
+Include relevant images in results:
+
+```
+Find cute cats with images
+```
+
+### Raw Content
+
+Get detailed content from search results:
+
+```
+Search for Bun test runner documentation and include raw content
+```
+
+## Available Parameters
+
+The `web_search` tool accepts the following parameters:
+
+| Parameter             | Type    | Required | Default | Description                                    |
+| --------------------- | ------- | -------- | ------- | ---------------------------------------------- |
+| `query`               | string  | Yes      | -       | The search query string                        |
+| `max_results`         | number  | No       | 5       | Number of results to return (1-20)             |
+| `search_depth`        | string  | No       | "basic" | Search depth: "basic" or "advanced"            |
+| `include_answer`      | boolean | No       | true    | Include AI-generated answer                    |
+| `include_raw_content` | boolean | No       | false   | Include raw page content (markdown or text)    |
+| `include_images`      | boolean | No       | false   | Include relevant images                        |
+| `days`                | number  | No       | -       | Limit results to last N days (e.g., 7, 30, 90) |
+
+### Parameter Examples
+
+```typescript
+// Basic search
+{ query: "TypeScript 6" }
+
+// Time-limited search
+{ query: "AI news", days: 7 }
+
+// Advanced search with more results
+{ query: "quantum computing", search_depth: "advanced", max_results: 10 }
+
+// Search with images
+{ query: "cute cats", include_images: true }
+
+// Search with raw content
+{ query: "Bun documentation", include_raw_content: true }
+```
+
+## Output Truncation
+
+To prevent overwhelming the LLM context, tool output is truncated to:
+
+- **50KB** of data
+- **2,000 lines** of text
+
+Whichever limit is hit first triggers truncation.
+
+When output is truncated:
+
+- A warning is displayed in the results
+- Full output is saved to a temp file in your project directory: `.pi-tavily-temp/search-{timestamp}.txt`
+- The LLM is informed where to find the complete output
+
+## Troubleshooting
+
+### "TAVILY_API_KEY is not set"
+
+**Error Message:**
+
+```
+Error: TAVILY_API_KEY environment variable is not set.
+```
+
+**Solution:**
+
+1. Get an API key from <https://tavily.com>
+2. Set the environment variable:
+   ```bash
+   export TAVILY_API_KEY="your-api-key-here"
+   ```
+3. Add to your shell profile for persistence:
+   ```bash
+   echo 'export TAVILY_API_KEY="your-api-key-here"' >> ~/.zshrc
+   source ~/.zshrc
+   ```
+
+### "Failed to initialize Tavily client"
+
+**Error Message:**
+
+```
+Error: Failed to initialize Tavily client: ...
+```
+
+**Possible Causes:**
+
+1. Invalid API key format
+2. Network connectivity issues
+3. Tavily API is down
+
+**Solutions:**
+
+1. Verify your API key is correct (should start with "tvly-")
+2. Check your internet connection
+3. Try a simple curl test:
+   ```bash
+   curl -X POST https://api.tavily.com/search \\
+     -H "Content-Type: application/json" \\
+     -d '{"api_key":"YOUR_KEY","query":"test","max_results":1}'
+   ```
+
+### Rate Limit Errors
+
+**Error Message:**
+
+```
+Error: You have exceeded your monthly request limit
+```
+
+**Solution:**
+
+- The free tier includes 1,000 requests per month
+- Upgrade your Tavily plan if you need more requests
+- Visit <https://tavily.com/pricing> for details
+
+### No Results Found
+
+**Symptoms:**
+
+- Search returns "No results found."
+- Empty results list
+
+**Solutions:**
+
+1. Try a broader or different search query
+2. Check spelling of your query
+3. Remove any special characters or complex filters
+4. Try basic search depth instead of advanced
+
+## Development
+
+### Project Structure
+
+```
+pi-tavily-tools/
+├── .github/
+│   └── dependabot.yml    # Dependency update configuration
+├── .envrc                # Direnv configuration for API keys
+├── .gitignore
+├── .prettierignore
+├── .prettierrc           # Prettier code formatter config
+├── AGENTS.md             # Project guidelines for Pi agents
+├── LICENSE
+├── README.md
+├── bun.lock
+├── eslint.config.js      # ESLint linting config
+├── lefthook.yml          # Git hooks configuration
+├── package.json          # Package manifest
+├── tsconfig.json         # TypeScript compiler config
+├── src/
+│   ├── index.ts          # Extension entry point
+│   └── tools/
+│       ├── index.ts      # Tool exports
+│       ├── web-search.ts # Web search tool implementation
+│       ├── tavily/       # Tavily API integration
+│       │   ├── client.ts     # Tavily client & initialization
+│       │   ├── formatters.ts # Response formatting
+│       │   ├── renderers.ts  # TUI rendering utilities
+│       │   ├── schemas.ts    # TypeBox parameter schemas
+│       │   └── types.ts      # Type definitions
+│       └── shared/       # Shared utilities
+│           └── truncation.ts # Output truncation utilities
+└── tests/
+    ├── integration/      # Integration tests
+    │   └── web-search.test.ts
+    ├── client.test.ts
+    ├── create-error-output.test.ts
+    ├── formatters.test.ts
+    ├── renderers.test.ts
+    ├── schemas.test.ts
+    └── truncation.test.ts
+```
+
+### Running Type Checks
+
+```bash
+bun run check
+```
+
+Watch mode for instant feedback during development:
+
+```bash
+bun run check:watch
+```
+
+### Running Tests
+
+```bash
+bun run test
+```
+
+Watch mode for continuous testing:
+
+```bash
+bun run test:watch
+```
+
+Run only integration tests (requires valid API key):
+
+```bash
+bun test tests/integration/
+```
+
+### Running Linting
+
+```bash
+bun run lint
+```
+
+### Formatting Code
+
+```bash
+bun run format:fix
+```
+
+### All Checks
+
+Run all checks before committing:
+
+```bash
+bun run check && bun run lint && bun run test
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Support
+
+- **GitHub Issues:** [shaftoe/pi-tavily-tools/issues](https://github.com/shaftoe/pi-tavily-tools/issues)
+- **Tavily Documentation:** [https://docs.tavily.com](https://docs.tavily.com)
+- **Pi Documentation:** [https://shittycodingagent.ai](https://shittycodingagent.ai)
+
+## Acknowledgments
+
+Built with:
+
+- [Tavily API](https://tavily.com) - Web search and AI answers
+- [Pi Coding Agent](https://pi.dev) - Extension framework
+- [Bun](https://bun.sh) - Package manager and test runner

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Pi Tavily Web Search Extension
+ *
+ * Provides web search capabilities to Pi using Tavily's search API.
+ * Adds a `web_search` tool that the LLM can use to find current
+ * information, recent news, documentation, and time-sensitive data.
+ */
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+/**
+ * Main extension entry point.
+ *
+ * Defers tool registration to `session_start` so Pi can start
+ * even if the TAVILY_API_KEY is missing. The tool is registered only
+ * once on the first agent run and persists across sessions.
+ */
+export default function (pi: ExtensionAPI): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAIlE;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,WAAW,EAAE,EAAE,YAAY,GAAG,IAAI,CAmB/C"}

package/dist/index.js

@@ -0,0 +1,38 @@
+/**
+ * Pi Tavily Web Search Extension
+ *
+ * Provides web search capabilities to Pi using Tavily's search API.
+ * Adds a `web_search` tool that the LLM can use to find current
+ * information, recent news, documentation, and time-sensitive data.
+ */
+import { createTavilyClient } from "./tools/tavily/client.js";
+import { registerWebSearchTool } from "./tools/web-search.js";
+/**
+ * Main extension entry point.
+ *
+ * Defers tool registration to `session_start` so Pi can start
+ * even if the TAVILY_API_KEY is missing. The tool is registered only
+ * once on the first agent run and persists across sessions.
+ */
+export default function (pi) {
+    let registered = false;
+    pi.on("session_start", (_event, ctx) => {
+        if (registered)
+            return;
+        registered = true;
+        try {
+            const client = createTavilyClient();
+            registerWebSearchTool(pi, client);
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                ctx.ui.notify(`[pi-tavily-tools] ${error.message}`, "error");
+            }
+            else {
+                // Re-throw non-Error types (shouldn't happen, but be safe)
+                throw error;
+            }
+        }
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAE9D;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,WAAW,EAAgB;IACvC,IAAI,UAAU,GAAG,KAAK,CAAC;IAEvB,EAAE,CAAC,EAAE,CAAC,eAAe,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE;QACrC,IAAI,UAAU;YAAE,OAAO;QACvB,UAAU,GAAG,IAAI,CAAC;QAElB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,kBAAkB,EAAE,CAAC;YACpC,qBAAqB,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QACpC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;gBAC3B,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,qBAAqB,KAAK,CAAC,OAAO,EAAE,EAAE,OAAO,CAAC,CAAC;YAC/D,CAAC;iBAAM,CAAC;gBACN,2DAA2D;gBAC3D,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/tools/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Tavily Tools for Pi
+ *
+ * This package provides Pi tools for interacting with Tavily's API.
+ */
+export { registerWebSearchTool } from "./web-search.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/tools/index.js

@@ -0,0 +1,7 @@
+/**
+ * Tavily Tools for Pi
+ *
+ * This package provides Pi tools for interacting with Tavily's API.
+ */
+export { registerWebSearchTool } from "./web-search.js";
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/tools/shared/truncation.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared truncation utilities
+ */
+import { type TruncationResult } from "@mariozechner/pi-coding-agent";
+export interface TruncatedOutput {
+    content: string;
+    truncation?: TruncationResult;
+    fullOutputPath?: string;
+}
+/**
+ * Apply truncation to output and save full content to temp file if needed
+ */
+export declare function applyTruncation(fullOutput: string, cwd: string, toolName: string): Promise<TruncatedOutput>;
+/**
+ * Create error output
+ */
+export declare function createErrorOutput(errorMessage: string, baseDetails: Record<string, unknown>): {
+    content: string;
+    details: Record<string, unknown>;
+};
+//# sourceMappingURL=truncation.d.ts.map

package/dist/tools/shared/truncation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"truncation.d.ts","sourceRoot":"","sources":["../../../src/tools/shared/truncation.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAML,KAAK,gBAAgB,EACtB,MAAM,+BAA+B,CAAC;AAMvC,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,eAAe,CAAC,CAuC1B;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAUvD"}

package/dist/tools/shared/truncation.js

@@ -0,0 +1,55 @@
+/**
+ * Shared truncation utilities
+ */
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, truncateHead, withFileMutationQueue, } from "@mariozechner/pi-coding-agent";
+/**
+ * Apply truncation to output and save full content to temp file if needed
+ */
+export async function applyTruncation(fullOutput, cwd, toolName) {
+    const truncation = truncateHead(fullOutput, {
+        maxLines: DEFAULT_MAX_LINES,
+        maxBytes: DEFAULT_MAX_BYTES,
+    });
+    let content = truncation.content;
+    // Save full output to temp file if truncated
+    if (truncation.truncated) {
+        const tempDir = `${cwd}/.pi-tavily-temp`;
+        const timestamp = Date.now();
+        const tempFile = `${tempDir}/${toolName}-${timestamp}.txt`;
+        await withFileMutationQueue(tempFile, async () => {
+            const { writeFile, mkdir } = await import("node:fs/promises");
+            await mkdir(tempDir, { recursive: true });
+            await writeFile(tempFile, fullOutput, "utf8");
+        });
+        // Add truncation notice
+        const truncatedLines = truncation.totalLines - truncation.outputLines;
+        const truncatedBytes = truncation.totalBytes - truncation.outputBytes;
+        content += "\n\n";
+        content += "[Output truncated: ";
+        content += `showing ${truncation.outputLines} of ${truncation.totalLines} lines, `;
+        content += `(${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}). `;
+        content += `${truncatedLines} lines (${formatSize(truncatedBytes)}) omitted. `;
+        content += `Full output saved to: ${tempFile}]`;
+        return {
+            content,
+            truncation,
+            fullOutputPath: tempFile,
+        };
+    }
+    return { content };
+}
+/**
+ * Create error output
+ */
+export function createErrorOutput(errorMessage, baseDetails) {
+    return {
+        content: `Error: ${errorMessage}`,
+        details: {
+            ...baseDetails,
+            resultCount: 0,
+            sources: [],
+            error: errorMessage,
+        },
+    };
+}
+//# sourceMappingURL=truncation.js.map

package/dist/tools/shared/truncation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"truncation.js","sourceRoot":"","sources":["../../../src/tools/shared/truncation.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,UAAU,EACV,YAAY,EACZ,qBAAqB,GAEtB,MAAM,+BAA+B,CAAC;AAYvC;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,UAAkB,EAClB,GAAW,EACX,QAAgB;IAEhB,MAAM,UAAU,GAAG,YAAY,CAAC,UAAU,EAAE;QAC1C,QAAQ,EAAE,iBAAiB;QAC3B,QAAQ,EAAE,iBAAiB;KAC5B,CAAC,CAAC;IAEH,IAAI,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC;IAEjC,6CAA6C;IAC7C,IAAI,UAAU,CAAC,SAAS,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,GAAG,GAAG,kBAAkB,CAAC;QACzC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,MAAM,QAAQ,GAAG,GAAG,OAAO,IAAI,QAAQ,IAAI,SAAS,MAAM,CAAC;QAE3D,MAAM,qBAAqB,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;YAC/C,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAC;YAC9D,MAAM,KAAK,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC1C,MAAM,SAAS,CAAC,QAAQ,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;QAChD,CAAC,CAAC,CAAC;QAEH,wBAAwB;QACxB,MAAM,cAAc,GAAG,UAAU,CAAC,UAAU,GAAG,UAAU,CAAC,WAAW,CAAC;QACtE,MAAM,cAAc,GAAG,UAAU,CAAC,UAAU,GAAG,UAAU,CAAC,WAAW,CAAC;QAEtE,OAAO,IAAI,MAAM,CAAC;QAClB,OAAO,IAAI,qBAAqB,CAAC;QACjC,OAAO,IAAI,WAAW,UAAU,CAAC,WAAW,OAAO,UAAU,CAAC,UAAU,UAAU,CAAC;QACnF,OAAO,IAAI,IAAI,UAAU,CAAC,UAAU,CAAC,WAAW,CAAC,OAAO,UAAU,CAAC,UAAU,CAAC,UAAU,CAAC,KAAK,CAAC;QAC/F,OAAO,IAAI,GAAG,cAAc,WAAW,UAAU,CAAC,cAAc,CAAC,aAAa,CAAC;QAC/E,OAAO,IAAI,yBAAyB,QAAQ,GAAG,CAAC;QAEhD,OAAO;YACL,OAAO;YACP,UAAU;YACV,cAAc,EAAE,QAAQ;SACzB,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,CAAC;AACrB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAC/B,YAAoB,EACpB,WAAoC;IAEpC,OAAO;QACL,OAAO,EAAE,UAAU,YAAY,EAAE;QACjC,OAAO,EAAE;YACP,GAAG,WAAW;YACd,WAAW,EAAE,CAAC;YACd,OAAO,EAAE,EAAE;YACX,KAAK,EAAE,YAAY;SACpB;KACF,CAAC;AACJ,CAAC"}

package/dist/tools/tavily/client.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Tavily Client Management
+ *
+ * Creates Tavily client instances with proper initialization.
+ */
+import { type TavilyClient, type TavilySearchOptions } from "@tavily/core";
+/**
+ * Create a new Tavily client instance
+ * @throws {Error} If TAVILY_API_KEY is not set or client initialization fails
+ */
+export declare function createTavilyClient(apiKey?: string): TavilyClient;
+/**
+ * Build Tavily search options from parameters
+ */
+export declare function buildSearchOptions(params: Record<string, unknown>): TavilySearchOptions;
+/**
+ * Create a search function pre-bound with a client
+ * @param client Tavily client instance
+ * @returns Search function
+ */
+export declare function createSearchFunction(client: TavilyClient): import("@tavily/core").TavilySearchFuncton;
+/**
+ * Validate search query
+ * @throws {Error} If query is empty or whitespace only
+ */
+export declare function validateQuery(query: string): string;
+//# sourceMappingURL=client.d.ts.map

package/dist/tools/tavily/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/tools/tavily/client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAU,KAAK,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAMnF;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAiBhE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,mBAAmB,CAYvF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,8CAExD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMnD"}

package/dist/tools/tavily/client.js

@@ -0,0 +1,62 @@
+/**
+ * Tavily Client Management
+ *
+ * Creates Tavily client instances with proper initialization.
+ */
+import { tavily } from "@tavily/core";
+// ============================================================================
+// Client Creation
+// ============================================================================
+/**
+ * Create a new Tavily client instance
+ * @throws {Error} If TAVILY_API_KEY is not set or client initialization fails
+ */
+export function createTavilyClient(apiKey) {
+    const key = apiKey ?? process.env.TAVILY_API_KEY;
+    if (!key) {
+        throw new Error("TAVILY_API_KEY environment variable is not set. " +
+            'Please set it with: export TAVILY_API_KEY="your-api-key" ' +
+            "or get a free key from https://tavily.com");
+    }
+    try {
+        return tavily({ apiKey: key });
+    }
+    catch (error) {
+        throw new Error(`Failed to initialize Tavily client: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Build Tavily search options from parameters
+ */
+export function buildSearchOptions(params) {
+    return {
+        maxResults: typeof params.max_results === "number" ? Math.max(1, Math.min(20, params.max_results)) : 5,
+        searchDepth: params.search_depth ?? "basic",
+        includeAnswer: params.include_answer !== false,
+        includeImages: params.include_images === true,
+        includeRawContent: params.include_raw_content === true ? "markdown" : false,
+        days: typeof params.days === "number" ? params.days : undefined,
+        includeDomains: undefined,
+        excludeDomains: undefined,
+    };
+}
+/**
+ * Create a search function pre-bound with a client
+ * @param client Tavily client instance
+ * @returns Search function
+ */
+export function createSearchFunction(client) {
+    return client.search.bind(client);
+}
+/**
+ * Validate search query
+ * @throws {Error} If query is empty or whitespace only
+ */
+export function validateQuery(query) {
+    const trimmed = query.trim();
+    if (!trimmed) {
+        throw new Error("Query cannot be empty");
+    }
+    return trimmed;
+}
+//# sourceMappingURL=client.js.map

package/dist/tools/tavily/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/tools/tavily/client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,EAA+C,MAAM,cAAc,CAAC;AAEnF,+EAA+E;AAC/E,kBAAkB;AAClB,+EAA+E;AAE/E;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAe;IAChD,MAAM,GAAG,GAAG,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IACjD,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CACb,kDAAkD;YAChD,2DAA2D;YAC3D,2CAA2C,CAC9C,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;IACjC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,uCAAuC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAChG,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAA+B;IAChE,OAAO;QACL,UAAU,EACR,OAAO,MAAM,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5F,WAAW,EAAG,MAAM,CAAC,YAAqC,IAAI,OAAO;QACrE,aAAa,EAAE,MAAM,CAAC,cAAc,KAAK,KAAK;QAC9C,aAAa,EAAE,MAAM,CAAC,cAAc,KAAK,IAAI;QAC7C,iBAAiB,EAAE,MAAM,CAAC,mBAAmB,KAAK,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK;QAC3E,IAAI,EAAE,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;QAC/D,cAAc,EAAE,SAAS;QACzB,cAAc,EAAE,SAAS;KAC1B,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAoB;IACvD,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AACpC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/tools/tavily/formatters.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Response formatters for Tavily tools
+ */
+import type { FormattedOutputParts, ImageResult, SearchResult } from "./types.js";
+/**
+ * Format Tavily search response into human-readable text
+ */
+export declare function formatWebSearchResponse(answer: string | null, results: SearchResult[], images: ImageResult[], includeImages: boolean | undefined): string;
+/**
+ * Format Tavily search results into compact parts structure
+ */
+export declare function formatSearchResults(answer: string | null, results: SearchResult[], images: ImageResult[], includeImages: boolean): FormattedOutputParts;
+/**
+ * Extract and type-safe Tavily response data
+ */
+export declare function extractSearchResults(response: unknown): {
+    answer: string | null;
+    results: SearchResult[];
+    images: ImageResult[];
+};
+//# sourceMappingURL=formatters.d.ts.map