{"_id":"@ainative/ai-kit-tools","_rev":"3-f213f97baee1a0d509cd64ba5604676d","name":"@ainative/ai-kit-tools","dist-tags":{"alpha":"0.1.0-alpha.0","latest":"0.1.0-alpha.2"},"versions":{"0.1.0-alpha.0":{"name":"@ainative/ai-kit-tools","version":"0.1.0-alpha.0","keywords":["ainative","ai","llm","typescript","ai-agents","ai-primitives","ainative-developer","claude","claude-code","openai","anthropic","tools","utilities","helpers","mcp","integrations"],"author":{"name":"AINative Studio"},"license":"MIT","_id":"@ainative/ai-kit-tools@0.1.0-alpha.0","maintainers":[{"name":"ainative-studio","email":"toby@rely.ventures"}],"homepage":"https://github.com/AINative-Studio/ai-kit#readme","bugs":{"url":"https://github.com/AINative-Studio/ai-kit/issues"},"dist":{"shasum":"f496bedc9c4a9ab8b815e1592ba8991f3483acf4","tarball":"https://registry.npmjs.org/@ainative/ai-kit-tools/-/ai-kit-tools-0.1.0-alpha.0.tgz","fileCount":9,"integrity":"sha512-for6fo0ZF9+JOewTZZl7N9+dHFc1RegNd8fLtWbrrWkA5p7RUZnXtDFiQmLI7quXESjIe03afeGASukGk1FQZQ==","signatures":[{"sig":"MEUCIQChLr4eJgBfcALzqWFTBe55lPIwwthwChDsyPYupxpOuwIgM/6jWc3wo9XDAl6v6LJrfQquCLagn/44dpSJ/0x1KnY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1218838},"main":"./dist/index.js","types":"./dist/index.d.ts","module":"./dist/index.mjs","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"fc76d30b210657f175234126d6c0edbaa71d4140","scripts":{"dev":"tsup --watch","lint":"eslint src","test":"vitest","build":"tsup","clean":"rm -rf dist","type-check":"tsc --noEmit","test:coverage":"vitest --coverage"},"_npmUser":{"name":"ainative-studio","email":"toby@rely.ventures"},"repository":{"url":"git+https://github.com/AINative-Studio/ai-kit.git","type":"git","directory":"packages/tools"},"_npmVersion":"10.9.4","description":"AI Kit - Built-in tools for agents including web search, calculator, code interpreter, and more","directories":{},"_nodeVersion":"22.21.0","dependencies":{"vm2":"^3.10.0","zod":"^3.22.4","mathjs":"^15.1.0","isolated-vm":"^6.0.2","@ainative/ai-kit-core":"workspace:*"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.1","vitest":"^1.0.0","typescript":"^5.3.0","@types/node":"^20.10.0","@types/mathjs":"^9.4.2"},"_npmOperationalInternal":{"tmp":"tmp/ai-kit-tools_0.1.0-alpha.0_1763694106031_0.42227280675614387","host":"s3://npm-registry-packages-npm-production"}},"0.1.0-alpha.1":{"name":"@ainative/ai-kit-tools","version":"0.1.0-alpha.1","keywords":["ainative","ai","llm","typescript","ai-agents","ai-primitives","ainative-developer","claude","claude-code","openai","anthropic","tools","utilities","helpers","mcp","integrations"],"author":{"name":"AINative Studio"},"license":"MIT","_id":"@ainative/ai-kit-tools@0.1.0-alpha.1","maintainers":[{"name":"ainative-studio","email":"toby@rely.ventures"}],"homepage":"https://github.com/AINative-Studio/ai-kit#readme","bugs":{"url":"https://github.com/AINative-Studio/ai-kit/issues"},"dist":{"shasum":"32d3ac50e5496635312bcc46c830879cfba5020a","tarball":"https://registry.npmjs.org/@ainative/ai-kit-tools/-/ai-kit-tools-0.1.0-alpha.1.tgz","fileCount":9,"integrity":"sha512-dieYivYKJuFF/8cr6ZHdtIDBR1/jQYMIBtG3vLR72KznuPctoQxwcqxdUPuiEiBzNsVlDBBZoXbbAymxWfzXDQ==","signatures":[{"sig":"MEUCIAx1LChZFX2o0lX47H642jOz6K2bBxhfM+OxstoX7CnBAiEAn7evMaZ1d6/02mOBayp1sRvMny6NAX7jd7dHtMRG7YM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1218841},"main":"./dist/index.js","types":"./dist/index.d.ts","module":"./dist/index.mjs","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"dc8dc4a4951e8951a407b2c28d26fcda12bf373d","scripts":{"dev":"tsup --watch","lint":"eslint src","test":"vitest","build":"tsup","clean":"rm -rf dist","type-check":"tsc --noEmit","test:coverage":"vitest --coverage"},"_npmUser":{"name":"ainative-studio","email":"toby@rely.ventures"},"repository":{"url":"git+https://github.com/AINative-Studio/ai-kit.git","type":"git","directory":"packages/tools"},"_npmVersion":"10.9.4","description":"AI Kit - Built-in tools for agents including web search, calculator, code interpreter, and more","directories":{},"_nodeVersion":"22.21.0","dependencies":{"vm2":"^3.10.0","zod":"^3.22.4","mathjs":"^15.1.0","isolated-vm":"^6.0.2","@ainative/ai-kit-core":"^0.1.2"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.1","vitest":"^1.0.0","typescript":"^5.3.0","@types/node":"^20.10.0","@types/mathjs":"^9.4.2"},"_npmOperationalInternal":{"tmp":"tmp/ai-kit-tools_0.1.0-alpha.1_1763767324745_0.12278115587788263","host":"s3://npm-registry-packages-npm-production"}},"0.1.0-alpha.2":{"name":"@ainative/ai-kit-tools","version":"0.1.0-alpha.2","description":"AI Kit - Built-in tools for agents including web search, calculator, code interpreter, and more","main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest","test:coverage":"vitest --coverage","type-check":"tsc --noEmit","lint":"eslint src","clean":"rm -rf dist"},"keywords":["ainative","ai","llm","typescript","ai-agents","ai-primitives","ainative-developer","claude","claude-code","openai","anthropic","tools","utilities","helpers","mcp","integrations"],"author":{"name":"AINative Studio"},"license":"MIT","homepage":"https://github.com/AINative-Studio/ai-kit#readme","repository":{"type":"git","url":"git+https://github.com/AINative-Studio/ai-kit.git","directory":"packages/tools"},"bugs":{"url":"https://github.com/AINative-Studio/ai-kit/issues"},"dependencies":{"@ainative-studio/aikit-core":"^0.1.3","isolated-vm":"^6.0.2","mathjs":"^15.1.0","vm2":"^3.10.0","zod":"^3.22.4"},"devDependencies":{"@types/mathjs":"^9.4.2","@types/node":"^20.10.0","tsup":"^8.0.1","typescript":"^5.3.0","vitest":"^1.0.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"engines":{"node":">=18.0.0"},"_id":"@ainative/ai-kit-tools@0.1.0-alpha.2","gitHead":"dc8dc4a4951e8951a407b2c28d26fcda12bf373d","_nodeVersion":"22.21.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-E4jaFJDCbTMLJ20nqdbe4nUuu0LgW9/p2OP6kihtc2McyI0pXSLr9GnEZoh1ep4khRzeltzeU5z6kgpFWoa2DQ==","shasum":"ede95e93cd7f3c8340d63fabd93ffe043f315236","tarball":"https://registry.npmjs.org/@ainative/ai-kit-tools/-/ai-kit-tools-0.1.0-alpha.2.tgz","fileCount":9,"unpackedSize":1218847,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC/xrkYSGNDZSzDkBDG+K7IzmjeYLREpbJSZ2AsGiu5wwIhALa1EGy8erte4VvHXPyFeAIuE6h93fFirUgoykI04iKC"}]},"_npmUser":{"name":"ainative-studio","email":"toby@rely.ventures"},"directories":{},"maintainers":[{"name":"ainative-studio","email":"toby@rely.ventures"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ai-kit-tools_0.1.0-alpha.2_1763779244371_0.670579593505499"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-21T03:01:45.909Z","modified":"2025-11-22T02:40:44.865Z","0.1.0-alpha.0":"2025-11-21T03:01:46.312Z","0.1.0-alpha.1":"2025-11-21T23:22:04.997Z","0.1.0-alpha.2":"2025-11-22T02:40:44.642Z"},"bugs":{"url":"https://github.com/AINative-Studio/ai-kit/issues"},"author":{"name":"AINative Studio"},"license":"MIT","homepage":"https://github.com/AINative-Studio/ai-kit#readme","keywords":["ainative","ai","llm","typescript","ai-agents","ai-primitives","ainative-developer","claude","claude-code","openai","anthropic","tools","utilities","helpers","mcp","integrations"],"repository":{"type":"git","url":"git+https://github.com/AINative-Studio/ai-kit.git","directory":"packages/tools"},"description":"AI Kit - Built-in tools for agents including web search, calculator, code interpreter, and more","maintainers":[{"name":"ainative-studio","email":"toby@rely.ventures"}],"readme":"# @ainative/ai-kit-tools\n\nProduction-ready tools for AI Kit agents.\n\n## Overview\n\nThis package provides a collection of built-in tools that AI agents can use to perform various tasks. Each tool is designed to be:\n\n- **Type-safe**: Full TypeScript support with Zod schemas\n- **Well-tested**: 80%+ test coverage\n- **Production-ready**: Comprehensive error handling and rate limiting\n- **Agent-compatible**: Works seamlessly with the AI Kit agent framework\n\n## Available Tools\n\n### Web Search Tool\n\nSearch the web using Brave Search API with structured results.\n\n```typescript\nimport { createWebSearchTool } from '@ainative/ai-kit-tools';\n\nconst webSearchTool = createWebSearchTool({\n  provider: 'brave',\n  apiKey: process.env.BRAVE_API_KEY!,\n  maxResults: 10,\n});\n\nconst result = await webSearchTool.execute({\n  query: 'latest AI developments 2025',\n  maxResults: 5,\n});\n```\n\n**Features:**\n- Multiple search provider support (Brave, Google, Bing)\n- Built-in rate limiting (token bucket algorithm)\n- Structured results with title, URL, snippet, and metadata\n- Comprehensive error handling\n- Configurable timeouts and retry logic\n\n**Documentation:** [Web Search Usage Guide](./docs/WEB_SEARCH_USAGE.md)\n\n**Story Points:** 8\n\n### Calculator Tool\n\nSafe mathematical expression evaluation with support for statistics.\n\n```typescript\nimport { calculator } from '@ainative/ai-kit-tools';\n\nconst result = calculator.execute({\n  expression: '(10 + 5) * 2',\n});\n```\n\n**Features:**\n- Safe expression evaluation (no eval)\n- Statistical operations (mean, median, mode, etc.)\n- Equation solving\n- Batch calculations\n- Input validation\n\n**Story Points:** 5\n\n### Code Interpreter Tool\n\nExecute code in a sandboxed environment with multiple language support.\n\n```typescript\nimport { codeInterpreterTool } from '@ainative/ai-kit-tools';\n\nconst result = await codeInterpreterTool.execute({\n  language: 'javascript',\n  code: 'console.log(\"Hello, World!\")',\n});\n```\n\n**Features:**\n- JavaScript execution\n- Python support (coming soon)\n- Sandboxed environment\n- Timeout protection\n- Memory limits\n- Output capture\n\n**Story Points:** 13\n\n### ZeroDB Query Tool\n\nQuery and manage ZeroDB resources with natural language.\n\n```typescript\nimport { createZeroDBQueryTool } from '@ainative/ai-kit-tools';\n\nconst zerodbTool = createZeroDBQueryTool({\n  apiKey: process.env.ZERODB_API_KEY!,\n  projectId: 'my-project',\n});\n```\n\n**Features:**\n- Natural language query parsing\n- Vector search support\n- Table operations\n- Event stream access\n- Result formatting\n\n**Story Points:** 13\n\n## Installation\n\n```bash\nnpm install @ainative/ai-kit-tools\n# or\npnpm add @ainative/ai-kit-tools\n# or\nyarn add @ainative/ai-kit-tools\n```\n\n## Usage with Agents\n\n```typescript\nimport { Agent } from '@ainative/ai-kit-core';\nimport {\n  createWebSearchTool,\n  calculator,\n  codeInterpreterTool,\n} from '@ainative/ai-kit-tools';\n\nconst agent = new Agent({\n  id: 'research-agent',\n  name: 'Research Agent',\n  systemPrompt: 'You are a research assistant with web search and calculation capabilities.',\n  llm: {\n    provider: 'anthropic',\n    model: 'claude-3-5-sonnet-20241022',\n    apiKey: process.env.ANTHROPIC_API_KEY!,\n  },\n  tools: [\n    createWebSearchTool({\n      provider: 'brave',\n      apiKey: process.env.BRAVE_API_KEY!,\n    }),\n    calculator,\n    codeInterpreterTool,\n  ],\n});\n\nconst response = await agent.execute('Find the latest AI news and calculate market growth');\n```\n\n## API Reference\n\n### Tool Definition Interface\n\nAll tools follow the standard `ToolDefinition` interface from `@ainative/ai-kit-core`:\n\n```typescript\ninterface ToolDefinition<TParams = any, TResult = any> {\n  name: string;\n  description: string;\n  parameters: z.ZodObject<any> | z.ZodType<any>;\n  execute: (params: TParams) => Promise<TResult>;\n  retry?: {\n    maxAttempts: number;\n    backoffMs: number;\n  };\n  timeoutMs?: number;\n  metadata?: Record<string, unknown>;\n}\n```\n\n## Environment Variables\n\n### Required\n\n- `BRAVE_API_KEY` - For web search tool (get from [Brave Search API](https://brave.com/search/api/))\n\n### Optional\n\n- `ZERODB_API_KEY` - For ZeroDB query tool\n- `ZERODB_PROJECT_ID` - Your ZeroDB project ID\n\n## Testing\n\nEach tool comes with comprehensive test coverage:\n\n```bash\n# Run all tests\npnpm test\n\n# Run tests with coverage\npnpm test:coverage\n\n# Run specific tool tests\npnpm test web-search\npnpm test calculator\n```\n\n## Development\n\n### Building\n\n```bash\npnpm build\n```\n\n### Type Checking\n\n```bash\npnpm type-check\n```\n\n### Linting\n\n```bash\npnpm lint\n```\n\n## Contributing\n\nWhen adding a new tool:\n\n1. Create the tool implementation in `src/`\n2. Add comprehensive tests in `__tests__/`\n3. Ensure 80%+ test coverage\n4. Update exports in `src/index.ts`\n5. Create usage documentation in `docs/`\n6. Update this README\n\n## Error Handling\n\nAll tools provide specific error classes for better error handling:\n\n```typescript\nimport {\n  WebSearchError,\n  RateLimitError,\n  InvalidAPIKeyError,\n} from '@ainative/ai-kit-tools';\n\ntry {\n  await webSearchTool.execute({ query: 'test' });\n} catch (error) {\n  if (error instanceof RateLimitError) {\n    console.log('Rate limited. Retry after:', error.resetAt);\n  } else if (error instanceof InvalidAPIKeyError) {\n    console.log('Invalid API key');\n  } else if (error instanceof WebSearchError) {\n    console.log('Search error:', error.message);\n  }\n}\n```\n\n## Performance\n\nAll tools are optimized for production use:\n\n- **Rate Limiting**: Built-in rate limiting prevents API quota exhaustion\n- **Timeouts**: Configurable timeouts prevent hanging requests\n- **Retries**: Automatic retry with exponential backoff for transient failures\n- **Caching**: Response caching where appropriate\n\n## License\n\nMIT\n\n## Support\n\n- GitHub Issues: [ai-kit/issues](https://github.com/AINative-Studio/ai-kit/issues)\n- Documentation: [https://ainative.studio/ai-kit](https://ainative.studio/ai-kit)\n","readmeFilename":"README.md"}