ai-tool-adapter 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,444 @@
+# ai-tool-adapter
+
+Universal AI tool schema adapter for function calling across multiple LLM providers.
+
+Write your tool definitions once, convert to any provider format instantly. No more duplicating schemas for OpenAI, Anthropic, Google, and Mistral.
+
+## Features
+
+- **Zero dependencies** - Lightweight and secure
+- **Type-safe** - Full TypeScript support with strict typing
+- **Provider-agnostic** - One schema, multiple formats
+- **Pure functions** - Predictable transformations with no side effects
+- **Well-tested** - Comprehensive test coverage across all adapters
+
+## Supported Providers
+
+- **OpenAI** - GPT-4, GPT-3.5 function calling
+- **Anthropic** - Claude tool use
+- **Google Gemini** - Gemini function calling
+- **Mistral** - Mistral AI function calling
+
+## Installation
+
+```bash
+npm install ai-tool-adapter
+```
+
+## Quick Start
+
+```typescript
+import { adapt } from 'ai-tool-adapter';
+
+// Define your tool once using the universal schema
+const weatherTool = {
+  name: 'get_weather',
+  description: 'Get current weather for a location',
+  params: {
+    location: {
+      type: 'string',
+      description: 'City name',
+      required: true,
+    },
+    units: {
+      type: 'string',
+      description: 'Temperature units',
+      enum: ['celsius', 'fahrenheit'],
+    },
+  },
+};
+
+// Convert to any provider format
+const openaiTool = adapt(weatherTool, 'openai');
+const anthropicTool = adapt(weatherTool, 'anthropic');
+const geminiTool = adapt(weatherTool, 'gemini');
+const mistralTool = adapt(weatherTool, 'mistral');
+```
+
+## API Reference
+
+### `adapt(tool, provider)`
+
+Convert a single universal tool definition to a specific provider's format.
+
+**Parameters:**
+- `tool` (UniversalTool) - Your universal tool definition
+- `provider` (Provider) - Target provider: `'openai'` | `'anthropic'` | `'gemini'` | `'mistral'`
+
+**Returns:** Provider-specific tool format
+
+**Throws:** Error if provider is not supported
+
+```typescript
+const tool = {
+  name: 'calculate',
+  description: 'Perform arithmetic calculation',
+  params: {
+    operation: {
+      type: 'string',
+      enum: ['add', 'subtract', 'multiply', 'divide'],
+      required: true,
+    },
+    a: { type: 'number', required: true },
+    b: { type: 'number', required: true },
+  },
+};
+
+const openaiTool = adapt(tool, 'openai');
+```
+
+### `adaptAll(tools, provider)`
+
+Convert multiple tools at once.
+
+**Parameters:**
+- `tools` (UniversalTool[]) - Array of universal tool definitions
+- `provider` (Provider) - Target provider
+
+**Returns:** Array of provider-specific tool formats
+
+```typescript
+const tools = [weatherTool, calculatorTool, searchTool];
+const openaiTools = adaptAll(tools, 'openai');
+```
+
+### `getProviders()`
+
+Get list of all supported providers.
+
+**Returns:** Array of provider names
+
+```typescript
+const providers = getProviders();
+console.log(providers); // ['openai', 'anthropic', 'gemini', 'mistral']
+```
+
+## Universal Tool Schema
+
+### Basic Structure
+
+```typescript
+interface UniversalTool {
+  name: string;           // Function name
+  description: string;    // What the tool does
+  params: Record<string, ToolParam>;  // Parameter definitions
+}
+```
+
+### Parameter Definition
+
+```typescript
+interface ToolParam {
+  type: 'string' | 'number' | 'boolean' | 'array' | 'object';
+  description?: string;   // Parameter description
+  required?: boolean;     // Whether required (default: false)
+  default?: unknown;      // Default value
+  enum?: string[];        // Allowed values
+  items?: {               // For array types
+    type: ParamType;
+  };
+}
+```
+
+## Examples
+
+### Simple Tool
+
+```typescript
+const statusTool = {
+  name: 'get_status',
+  description: 'Get current system status',
+  params: {},  // No parameters
+};
+```
+
+### Tool with Required Parameters
+
+```typescript
+const searchTool = {
+  name: 'search',
+  description: 'Search for items',
+  params: {
+    query: {
+      type: 'string',
+      description: 'Search query',
+      required: true,
+    },
+  },
+};
+```
+
+### Tool with Enums
+
+```typescript
+const sortTool = {
+  name: 'sort_results',
+  description: 'Sort search results',
+  params: {
+    order: {
+      type: 'string',
+      enum: ['asc', 'desc'],
+      default: 'asc',
+    },
+  },
+};
+```
+
+### Tool with Array Parameters
+
+```typescript
+const batchTool = {
+  name: 'process_batch',
+  description: 'Process multiple items',
+  params: {
+    items: {
+      type: 'array',
+      description: 'Items to process',
+      items: { type: 'string' },
+      required: true,
+    },
+  },
+};
+```
+
+### Complex Tool
+
+```typescript
+const apiTool = {
+  name: 'api_request',
+  description: 'Make an API request',
+  params: {
+    endpoint: {
+      type: 'string',
+      description: 'API endpoint path',
+      required: true,
+    },
+    method: {
+      type: 'string',
+      description: 'HTTP method',
+      enum: ['GET', 'POST', 'PUT', 'DELETE'],
+      default: 'GET',
+    },
+    headers: {
+      type: 'object',
+      description: 'Request headers',
+    },
+    params: {
+      type: 'array',
+      description: 'Query parameters',
+      items: { type: 'string' },
+    },
+    timeout: {
+      type: 'number',
+      description: 'Request timeout in milliseconds',
+      default: 5000,
+    },
+  },
+};
+```
+
+## Provider Output Formats
+
+### OpenAI
+
+Wraps function definition in a type object:
+
+```json
+{
+  "type": "function",
+  "function": {
+    "name": "get_weather",
+    "description": "Get weather",
+    "parameters": {
+      "type": "object",
+      "properties": {...},
+      "required": [...]
+    }
+  }
+}
+```
+
+### Anthropic
+
+Flat structure with `input_schema`:
+
+```json
+{
+  "name": "get_weather",
+  "description": "Get weather",
+  "input_schema": {
+    "type": "object",
+    "properties": {...},
+    "required": [...]
+  }
+}
+```
+
+### Gemini
+
+Flat structure with UPPERCASE types:
+
+```json
+{
+  "name": "get_weather",
+  "description": "Get weather",
+  "parameters": {
+    "type": "OBJECT",
+    "properties": {
+      "location": { "type": "STRING" }
+    },
+    "required": [...]
+  }
+}
+```
+
+### Mistral
+
+OpenAI-compatible format:
+
+```json
+{
+  "type": "function",
+  "function": {
+    "name": "get_weather",
+    "description": "Get weather",
+    "parameters": {...}
+  }
+}
+```
+
+## Real-World Usage
+
+### With OpenAI SDK
+
+```typescript
+import OpenAI from 'openai';
+import { adapt } from 'ai-tool-adapter';
+
+const client = new OpenAI();
+
+const tools = [weatherTool, calculatorTool].map(tool =>
+  adapt(tool, 'openai')
+);
+
+const response = await client.chat.completions.create({
+  model: 'gpt-4',
+  messages: [{ role: 'user', content: 'What\'s the weather in Paris?' }],
+  tools,
+});
+```
+
+### With Anthropic SDK
+
+```typescript
+import Anthropic from '@anthropic-ai/sdk';
+import { adaptAll } from 'ai-tool-adapter';
+
+const client = new Anthropic();
+
+const tools = adaptAll([weatherTool, calculatorTool], 'anthropic');
+
+const response = await client.messages.create({
+  model: 'claude-3-5-sonnet-20241022',
+  max_tokens: 1024,
+  messages: [{ role: 'user', content: 'What\'s the weather in Paris?' }],
+  tools,
+});
+```
+
+### Multi-Provider Support
+
+```typescript
+import { adapt } from 'ai-tool-adapter';
+
+// Single source of truth for your tools
+const myTools = [weatherTool, calculatorTool, searchTool];
+
+// Support all providers effortlessly
+const providerClients = {
+  openai: { tools: myTools.map(t => adapt(t, 'openai')) },
+  anthropic: { tools: myTools.map(t => adapt(t, 'anthropic')) },
+  gemini: { tools: myTools.map(t => adapt(t, 'gemini')) },
+  mistral: { tools: myTools.map(t => adapt(t, 'mistral')) },
+};
+
+// Use whichever provider you need
+function callLLM(provider: string, prompt: string) {
+  const config = providerClients[provider];
+  // Make API call with provider-specific tools
+}
+```
+
+## TypeScript Support
+
+Full type definitions included:
+
+```typescript
+import type {
+  UniversalTool,
+  ToolParam,
+  Provider,
+  ParamType
+} from 'ai-tool-adapter';
+
+const tool: UniversalTool = {
+  name: 'my_tool',
+  description: 'My custom tool',
+  params: {
+    param1: {
+      type: 'string',
+      required: true,
+    },
+  },
+};
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Watch mode for tests
+npm run test:watch
+```
+
+## Architecture
+
+This library follows the **Strategy Pattern** with each provider adapter as an independent, interchangeable strategy. This design ensures:
+
+- **Orthogonality** - Adapters are completely independent
+- **Open/Closed Principle** - Easy to add new providers without modifying existing code
+- **Single Responsibility** - Each adapter handles exactly one provider's format
+- **Pure Functions** - Predictable, testable transformations
+
+For detailed architecture documentation, see [CLAUDE.md](./CLAUDE.md).
+
+## Contributing
+
+Contributions are welcome! To add a new provider:
+
+1. Create adapter in `src/adapters/yourprovider.ts`
+2. Add provider to `Provider` type in `src/types.ts`
+3. Register adapter in `src/index.ts`
+4. Add comprehensive tests
+5. Update documentation
+
+See [CLAUDE.md](./CLAUDE.md) for detailed guidelines.
+
+## License
+
+ISC
+
+## Related
+
+- [OpenAI Function Calling](https://platform.openai.com/docs/guides/function-calling)
+- [Anthropic Tool Use](https://docs.anthropic.com/claude/docs/tool-use)
+- [Google Gemini Function Calling](https://ai.google.dev/docs/function_calling)
+- [Mistral AI Function Calling](https://docs.mistral.ai/capabilities/function_calling/)

package/dist/adapters/anthropic.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Anthropic (Claude) Tool Adapter
+ *
+ * Converts UniversalTool to Anthropic's tool format.
+ * Output structure is flat with input_schema instead of parameters.
+ *
+ * @see https://docs.anthropic.com/claude/docs/tool-use
+ */
+import { UniversalTool } from '../types';
+interface AnthropicProperty {
+    type: string;
+    description?: string;
+    enum?: string[];
+    default?: unknown;
+    items?: {
+        type: string;
+    };
+}
+interface AnthropicInputSchema {
+    type: 'object';
+    properties: Record<string, AnthropicProperty>;
+    required: string[];
+}
+interface AnthropicTool {
+    name: string;
+    description: string;
+    input_schema: AnthropicInputSchema;
+}
+/**
+ * Converts a UniversalTool to Anthropic tool format
+ *
+ * @param tool - Universal tool definition
+ * @returns Anthropic-formatted tool object
+ */
+export declare function anthropicAdapter(tool: UniversalTool): AnthropicTool;
+export {};

package/dist/adapters/anthropic.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * Anthropic (Claude) Tool Adapter
+ *
+ * Converts UniversalTool to Anthropic's tool format.
+ * Output structure is flat with input_schema instead of parameters.
+ *
+ * @see https://docs.anthropic.com/claude/docs/tool-use
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.anthropicAdapter = anthropicAdapter;
+/**
+ * Convert a single parameter to Anthropic property format
+ */
+function convertParam(param) {
+    const property = {
+        type: param.type,
+    };
+    if (param.description) {
+        property.description = param.description;
+    }
+    if (param.enum) {
+        property.enum = param.enum;
+    }
+    if (param.default !== undefined) {
+        property.default = param.default;
+    }
+    if (param.type === 'array' && param.items) {
+        property.items = { type: param.items.type };
+    }
+    return property;
+}
+/**
+ * Converts a UniversalTool to Anthropic tool format
+ *
+ * @param tool - Universal tool definition
+ * @returns Anthropic-formatted tool object
+ */
+function anthropicAdapter(tool) {
+    const properties = {};
+    const required = [];
+    for (const [paramName, paramDef] of Object.entries(tool.params)) {
+        properties[paramName] = convertParam(paramDef);
+        if (paramDef.required) {
+            required.push(paramName);
+        }
+    }
+    return {
+        name: tool.name,
+        description: tool.description,
+        input_schema: {
+            type: 'object',
+            properties,
+            required,
+        },
+    };
+}

package/dist/adapters/anthropic.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Tests for Anthropic (Claude) adapter
+ */
+export {};

package/dist/adapters/anthropic.test.js

@@ -0,0 +1,173 @@
+"use strict";
+/**
+ * Tests for Anthropic (Claude) adapter
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const anthropic_1 = require("./anthropic");
+(0, vitest_1.describe)('anthropicAdapter', () => {
+    (0, vitest_1.it)('should convert a basic tool with required params', () => {
+        const tool = {
+            name: 'get_weather',
+            description: 'Get current weather for a location',
+            params: {
+                location: {
+                    type: 'string',
+                    description: 'City name',
+                    required: true,
+                },
+            },
+        };
+        const result = (0, anthropic_1.anthropicAdapter)(tool);
+        (0, vitest_1.expect)(result).toEqual({
+            name: 'get_weather',
+            description: 'Get current weather for a location',
+            input_schema: {
+                type: 'object',
+                properties: {
+                    location: {
+                        type: 'string',
+                        description: 'City name',
+                    },
+                },
+                required: ['location'],
+            },
+        });
+    });
+    (0, vitest_1.it)('should handle enum values', () => {
+        const tool = {
+            name: 'set_temperature',
+            description: 'Set temperature unit',
+            params: {
+                unit: {
+                    type: 'string',
+                    enum: ['celsius', 'fahrenheit', 'kelvin'],
+                    required: true,
+                },
+            },
+        };
+        const result = (0, anthropic_1.anthropicAdapter)(tool);
+        (0, vitest_1.expect)(result.input_schema.properties.unit).toEqual({
+            type: 'string',
+            enum: ['celsius', 'fahrenheit', 'kelvin'],
+        });
+    });
+    (0, vitest_1.it)('should handle array types with items', () => {
+        const tool = {
+            name: 'process_items',
+            description: 'Process a list of items',
+            params: {
+                items: {
+                    type: 'array',
+                    description: 'List of items',
+                    items: { type: 'string' },
+                    required: true,
+                },
+            },
+        };
+        const result = (0, anthropic_1.anthropicAdapter)(tool);
+        (0, vitest_1.expect)(result.input_schema.properties.items).toEqual({
+            type: 'array',
+            description: 'List of items',
+            items: { type: 'string' },
+        });
+    });
+    (0, vitest_1.it)('should handle default values', () => {
+        const tool = {
+            name: 'paginate',
+            description: 'Get paginated results',
+            params: {
+                page: {
+                    type: 'number',
+                    default: 1,
+                },
+                limit: {
+                    type: 'number',
+                    default: 10,
+                },
+            },
+        };
+        const result = (0, anthropic_1.anthropicAdapter)(tool);
+        (0, vitest_1.expect)(result.input_schema.properties.page).toEqual({
+            type: 'number',
+            default: 1,
+        });
+        (0, vitest_1.expect)(result.input_schema.properties.limit).toEqual({
+            type: 'number',
+            default: 10,
+        });
+    });
+    (0, vitest_1.it)('should handle mixed required and optional params', () => {
+        const tool = {
+            name: 'search',
+            description: 'Search for items',
+            params: {
+                query: {
+                    type: 'string',
+                    description: 'Search query',
+                    required: true,
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Result limit',
+                    default: 10,
+                },
+                exact: {
+                    type: 'boolean',
+                    description: 'Exact match',
+                },
+            },
+        };
+        const result = (0, anthropic_1.anthropicAdapter)(tool);
+        (0, vitest_1.expect)(result.input_schema.required).toEqual(['query']);
+        (0, vitest_1.expect)(result.input_schema.properties).toHaveProperty('query');
+        (0, vitest_1.expect)(result.input_schema.properties).toHaveProperty('limit');
+        (0, vitest_1.expect)(result.input_schema.properties).toHaveProperty('exact');
+    });
+    (0, vitest_1.it)('should handle empty params', () => {
+        const tool = {
+            name: 'get_status',
+            description: 'Get current status',
+            params: {},
+        };
+        const result = (0, anthropic_1.anthropicAdapter)(tool);
+        (0, vitest_1.expect)(result.input_schema).toEqual({
+            type: 'object',
+            properties: {},
+            required: [],
+        });
+    });
+    (0, vitest_1.it)('should use lowercase type names', () => {
+        const tool = {
+            name: 'test_types',
+            description: 'Test all types',
+            params: {
+                str: { type: 'string' },
+                num: { type: 'number' },
+                bool: { type: 'boolean' },
+                arr: { type: 'array', items: { type: 'string' } },
+                obj: { type: 'object' },
+            },
+        };
+        const result = (0, anthropic_1.anthropicAdapter)(tool);
+        const props = result.input_schema.properties;
+        (0, vitest_1.expect)(props.str.type).toBe('string');
+        (0, vitest_1.expect)(props.num.type).toBe('number');
+        (0, vitest_1.expect)(props.bool.type).toBe('boolean');
+        (0, vitest_1.expect)(props.arr.type).toBe('array');
+        (0, vitest_1.expect)(props.obj.type).toBe('object');
+    });
+    (0, vitest_1.it)('should use flat structure with input_schema', () => {
+        const tool = {
+            name: 'test',
+            description: 'Test tool',
+            params: {},
+        };
+        const result = (0, anthropic_1.anthropicAdapter)(tool);
+        (0, vitest_1.expect)(result).toHaveProperty('name');
+        (0, vitest_1.expect)(result).toHaveProperty('description');
+        (0, vitest_1.expect)(result).toHaveProperty('input_schema');
+        (0, vitest_1.expect)(result).not.toHaveProperty('type');
+        (0, vitest_1.expect)(result).not.toHaveProperty('function');
+    });
+});