{"_id":"@ai-integrator/core","_rev":"4-05d1faf0dedbeaf30ea3061922621f66","name":"@ai-integrator/core","dist-tags":{"latest":"0.3.0"},"versions":{"0.1.0":{"name":"@ai-integrator/core","version":"0.1.0","keywords":["ai","llm","openai","anthropic","claude","gemini","gpt","edge","cloudflare","vercel","lightweight","typescript"],"author":{"name":"hv-ojha"},"license":"MIT","_id":"@ai-integrator/core@0.1.0","maintainers":[{"name":"hv-ojha","email":"ojhaharsh7@gmail.com"}],"homepage":"https://github.com/hv-ojha/ai-integrator#readme","bugs":{"url":"https://github.com/hv-ojha/ai-integrator/issues"},"dist":{"shasum":"ebfcf5a6a65d2bf9a50dab715564f0f07506dd15","tarball":"https://registry.npmjs.org/@ai-integrator/core/-/core-0.1.0.tgz","fileCount":9,"integrity":"sha512-03fPSDsxtCdce1bB7ZFlM0tfkVYFXtnYhD7Pjv8maXBQVjdjQ/E6ykRkwb5bdczV1AEJo/ZYr+ZXXyDcRozKTQ==","signatures":[{"sig":"MEQCIF5qbZwBSHRFrGjXZ0xzx64C/5sSLdvC4OVsP+M6fCHkAiBLoT3lgcNnY1l8w2BnIcsNj8+biZ76HwQD2Qo6s7WzcA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":177001},"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":"78105e84fb5bab0edf93c10b940519ada7919f63","scripts":{"dev":"tsup src/index.ts --format cjs,esm --dts --watch","lint":"eslint src --ext .ts","test":"vitest run","build":"tsup src/index.ts --format cjs,esm --dts --clean","test:ui":"vitest --ui","validate":"npm run typecheck && npm run lint && npm run test","typecheck":"tsc --noEmit","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"hv-ojha","email":"ojhaharsh7@gmail.com"},"repository":{"url":"git+https://github.com/hv-ojha/ai-integrator.git","type":"git"},"_npmVersion":"11.5.2","description":"The lightest AI integration library with zero-config switching between OpenAI, Anthropic, and Google Gemini. Optimized for edge runtimes.","directories":{},"_nodeVersion":"20.18.1","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.5","eslint":"^8.57.1","openai":"^4.77.0","vitest":"^2.1.8","@vitest/ui":"^2.1.8","typescript":"^5.7.2","@types/node":"^20.17.0","@anthropic-ai/sdk":"^0.32.1","@vitest/coverage-v8":"^2.1.8","@google/generative-ai":"^0.21.0","@typescript-eslint/parser":"^7.18.0","@typescript-eslint/eslint-plugin":"^7.18.0"},"peerDependencies":{"openai":"^4.0.0","@anthropic-ai/sdk":"^0.20.0","@google/generative-ai":"^0.21.0"},"peerDependenciesMeta":{"openai":{"optional":true},"@anthropic-ai/sdk":{"optional":true},"@google/generative-ai":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/core_0.1.0_1762607237218_0.6181330220080701","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@ai-integrator/core","version":"0.1.1","keywords":["ai","llm","openai","anthropic","claude","gemini","gpt","edge","cloudflare","vercel","lightweight","typescript"],"author":{"name":"hv-ojha"},"license":"MIT","_id":"@ai-integrator/core@0.1.1","maintainers":[{"name":"hv-ojha","email":"ojhaharsh7@gmail.com"}],"homepage":"https://github.com/hv-ojha/ai-integrator#readme","bugs":{"url":"https://github.com/hv-ojha/ai-integrator/issues"},"dist":{"shasum":"9f18c5f653ea5b1aa4081d9eac374f51fe5dbe26","tarball":"https://registry.npmjs.org/@ai-integrator/core/-/core-0.1.1.tgz","fileCount":7,"integrity":"sha512-wcglnPNjB3GjnwYHgX3blCPtAcfQiKyP80cqZ53+idpy8vovfgiZEZea+W+XDEP/Uwuww0JD9fSVhPZX2h3iUA==","signatures":[{"sig":"MEQCIHDRusOWoGn0uKjTHjOhtVLWL8kGggqRxQ/3QOY7ZkavAiB/CZjIcXd2G1iQx79t4de7JcHM0hoDWrj3qlPFXRd08g==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":59583},"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":"b62332f491e34ca61aa2ad33cb87baeedfb93bc0","scripts":{"dev":"tsup src/index.ts --format cjs,esm --dts --watch","lint":"eslint src","test":"vitest run","build":"tsup src/index.ts --format cjs,esm --dts --clean","test:ui":"vitest --ui","lint:fix":"eslint src --fix","validate":"npm run typecheck && npm run lint && npm run test","typecheck":"tsc --noEmit","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"hv-ojha","email":"ojhaharsh7@gmail.com"},"repository":{"url":"git+https://github.com/hv-ojha/ai-integrator.git","type":"git"},"_npmVersion":"11.5.2","description":"The lightest AI integration library with zero-config switching between OpenAI, Anthropic, and Google Gemini. Optimized for edge runtimes.","directories":{},"_nodeVersion":"20.18.1","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.5","eslint":"^9.17.0","openai":"^4.77.0","terser":"^5.44.1","vitest":"^2.1.8","@eslint/js":"^9.17.0","@vitest/ui":"^2.1.8","typescript":"^5.7.2","@types/node":"^20.17.0","@anthropic-ai/sdk":"^0.32.1","typescript-eslint":"^8.18.2","@vitest/coverage-v8":"^2.1.8","@google/generative-ai":"^0.21.0"},"peerDependencies":{"openai":"^4.0.0","@anthropic-ai/sdk":"^0.20.0","@google/generative-ai":"^0.21.0"},"peerDependenciesMeta":{"openai":{"optional":true},"@anthropic-ai/sdk":{"optional":true},"@google/generative-ai":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/core_0.1.1_1762641925053_0.42271181244834577","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@ai-integrator/core","version":"0.2.0","keywords":["ai","llm","openai","anthropic","claude","gemini","gpt","edge","cloudflare","vercel","lightweight","typescript"],"author":{"name":"hv-ojha"},"license":"MIT","_id":"@ai-integrator/core@0.2.0","maintainers":[{"name":"hv-ojha","email":"ojhaharsh7@gmail.com"}],"homepage":"https://github.com/hv-ojha/ai-integrator#readme","bugs":{"url":"https://github.com/hv-ojha/ai-integrator/issues"},"dist":{"shasum":"1d38a678dcef81497c528a4a082c0f074fc11a4c","tarball":"https://registry.npmjs.org/@ai-integrator/core/-/core-0.2.0.tgz","fileCount":7,"integrity":"sha512-GRXZJZX1nrg79XuYnqrU9/JDkWGRRdlEIjX4mspGng/GEKVX/uZkvrl8tJI/dqjexVmou+SHbeHWlLBZRwEAVQ==","signatures":[{"sig":"MEUCIQCqt7t8nWtaMNBXMNPuK7mUJQWpxFhOpUEd2+kAHdTDQwIgHGE1vWqAyRfPqhYcKLbHhUQ0tgFMRI5f0xyQAba70Us=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":76895},"main":"./dist/index.js","types":"./dist/index.d.ts","module":"./dist/index.mjs","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"b161c01a44a68a040bc8fe15db66f876e70d1f1d","scripts":{"dev":"tsup src/index.ts --format cjs,esm --dts --watch","lint":"eslint src","test":"vitest run","build":"tsup src/index.ts --format cjs,esm --dts --clean","test:ui":"vitest --ui","lint:fix":"eslint src --fix","validate":"npm run typecheck && npm run lint && npm run test","typecheck":"tsc --noEmit","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"hv-ojha","email":"ojhaharsh7@gmail.com"},"repository":{"url":"git+https://github.com/hv-ojha/ai-integrator.git","type":"git"},"_npmVersion":"11.5.2","description":"The lightest AI integration library with zero-config switching between OpenAI, Anthropic, and Google Gemini. Optimized for edge runtimes.","directories":{},"_nodeVersion":"20.18.1","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.5","eslint":"^9.17.0","openai":"^4.77.0","terser":"^5.44.1","vitest":"^4.0.9","@eslint/js":"^9.17.0","@vitest/ui":"^4.0.9","typescript":"^5.7.2","@types/node":"^20.17.0","@anthropic-ai/sdk":"^0.32.1","typescript-eslint":"^8.18.2","@vitest/coverage-v8":"^4.0.9","@google/generative-ai":"^0.21.0"},"peerDependencies":{"openai":"^4.0.0","@anthropic-ai/sdk":"^0.20.0","@google/generative-ai":"^0.21.0"},"peerDependenciesMeta":{"openai":{"optional":true},"@anthropic-ai/sdk":{"optional":true},"@google/generative-ai":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/core_0.2.0_1763238813776_0.6614795181626265","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@ai-integrator/core","version":"0.3.0","description":"The lightest AI integration library with zero-config switching between OpenAI, Anthropic, and Google Gemini. Optimized for edge runtimes.","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 src/index.ts --format cjs,esm --dts --clean","dev":"tsup src/index.ts --format cjs,esm --dts --watch","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","test:ui":"vitest --ui","lint":"eslint src","lint:fix":"eslint src --fix","typecheck":"tsc --noEmit","prepublishOnly":"npm run build","validate":"npm run typecheck && npm run lint && npm run test"},"keywords":["ai","llm","openai","anthropic","claude","gemini","gpt","edge","cloudflare","vercel","lightweight","typescript"],"author":{"name":"hv-ojha"},"license":"MIT","peerDependencies":{"@anthropic-ai/sdk":"^0.20.0","@google/generative-ai":"^0.21.0","openai":"^4.0.0"},"peerDependenciesMeta":{"openai":{"optional":true},"@anthropic-ai/sdk":{"optional":true},"@google/generative-ai":{"optional":true}},"devDependencies":{"@anthropic-ai/sdk":"^0.32.1","@eslint/js":"^9.17.0","@google/generative-ai":"^0.21.0","@types/node":"^20.17.0","@vitest/coverage-v8":"^4.0.9","@vitest/ui":"^4.0.9","eslint":"^9.17.0","openai":"^4.77.0","terser":"^5.44.1","tsup":"^8.3.5","typescript":"^5.7.2","typescript-eslint":"^8.18.2","vitest":"^4.0.9"},"engines":{"node":">=20.0.0"},"repository":{"type":"git","url":"git+https://github.com/hv-ojha/ai-integrator.git"},"bugs":{"url":"https://github.com/hv-ojha/ai-integrator/issues"},"homepage":"https://github.com/hv-ojha/ai-integrator#readme","_id":"@ai-integrator/core@0.3.0","gitHead":"33780e4fc2dd9f482b8a7d5e21e6b077eefa4a3a","_nodeVersion":"20.18.1","_npmVersion":"11.5.2","dist":{"integrity":"sha512-LRb+onuUy78QfSQJlZXy1r3/DA64gNNQDT75Zi6kQxHvIqfrITrNEekPxOAWksy5ZszjUd6yIARmvbJ7e+Qi6Q==","shasum":"3dfc08be43627bc24247accdcde46ab5b25197cd","tarball":"https://registry.npmjs.org/@ai-integrator/core/-/core-0.3.0.tgz","fileCount":7,"unpackedSize":83409,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDE7SOHqyEDoSwVXDVSE6KNTPV2VPJtzYr3EWbazaPa0QIhAIHmgPygsWJXdUU1i3/cGG9LFv33dO0WCOq6tl0o/f4Q"}]},"_npmUser":{"name":"hv-ojha","email":"ojhaharsh7@gmail.com"},"directories":{},"maintainers":[{"name":"hv-ojha","email":"ojhaharsh7@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/core_0.3.0_1763683246732_0.10354630013088029"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-08T13:07:17.141Z","modified":"2025-11-21T00:00:47.255Z","0.1.0":"2025-11-08T13:07:17.436Z","0.1.1":"2025-11-08T22:45:25.261Z","0.2.0":"2025-11-15T20:33:34.001Z","0.3.0":"2025-11-21T00:00:47.029Z"},"bugs":{"url":"https://github.com/hv-ojha/ai-integrator/issues"},"author":{"name":"hv-ojha"},"license":"MIT","homepage":"https://github.com/hv-ojha/ai-integrator#readme","keywords":["ai","llm","openai","anthropic","claude","gemini","gpt","edge","cloudflare","vercel","lightweight","typescript"],"repository":{"type":"git","url":"git+https://github.com/hv-ojha/ai-integrator.git"},"description":"The lightest AI integration library with zero-config switching between OpenAI, Anthropic, and Google Gemini. Optimized for edge runtimes.","maintainers":[{"name":"hv-ojha","email":"ojhaharsh7@gmail.com"}],"readme":"# @ai-integrator/core\n\n> The lightest AI integration library with zero-config switching between OpenAI, Anthropic, and Google Gemini. Optimized for edge runtimes.\n\n[![npm version](https://badge.fury.io/js/@ai-integrator%2Fcore.svg)](https://www.npmjs.com/package/@ai-integrator/core)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## Why @ai-integrator/core?\n\n- **🪶 Lightweight**: Minimal dependencies, tree-shakable, ~17KB raw / ~4KB gzipped\n- **⚡ Zero-config**: Switch providers with a single parameter\n- **🌐 Edge-ready**: Works on Cloudflare Workers, Vercel Edge, Deno, Node.js\n- **🔄 Auto-fallback**: Automatic provider switching when APIs fail\n- **📡 Streaming**: First-class streaming support across all providers\n- **🛠️ Tool calling**: Unified function/tool calling API across all providers\n- **🔌 Custom providers**: Bring your own LLM backend or integrate any provider\n- **🔒 Type-safe**: Full TypeScript support with comprehensive types\n- **🎯 Simple API**: Unified interface across OpenAI, Anthropic, Gemini, and custom providers\n\n## Installation\n\n```bash\nnpm install @ai-integrator/core\n```\n\nThen install the provider SDKs you need:\n\n```bash\n# OpenAI\nnpm install openai\n\n# Anthropic (Claude)\nnpm install @anthropic-ai/sdk\n\n# Google Gemini\nnpm install @google/generative-ai\n```\n\n> **Note**: Provider SDKs are peer dependencies, so you only install what you use.\n\n## Quick Start\n\n### Basic Usage\n\n```typescript\nimport { AIClient } from '@ai-integrator/core';\n\nconst client = new AIClient({\n  provider: 'openai',\n  apiKey: process.env.OPENAI_API_KEY,\n});\n\nconst response = await client.chat({\n  model: 'gpt-4o-mini',\n  messages: [\n    { role: 'user', content: 'What is the capital of France?' }\n  ],\n});\n\nconsole.log(response.message.content);\n// Output: \"The capital of France is Paris.\"\n```\n\n### Switch Providers\n\n```typescript\n// Use Anthropic instead\nconst client = new AIClient({\n  provider: 'anthropic',\n  apiKey: process.env.ANTHROPIC_API_KEY,\n});\n\nconst response = await client.chat({\n  model: 'claude-3-5-sonnet-20241022',\n  messages: [\n    { role: 'user', content: 'Explain quantum computing' }\n  ],\n});\n\n// Or use Gemini\nconst client = new AIClient({\n  provider: 'gemini',\n  apiKey: process.env.GEMINI_API_KEY,\n});\n\nconst response = await client.chat({\n  model: 'gemini-2.0-flash-exp',\n  messages: [\n    { role: 'user', content: 'Write a haiku about code' }\n  ],\n});\n```\n\n## Streaming\n\n```typescript\nconst stream = client.chatStream({\n  model: 'gpt-4o-mini',\n  messages: [\n    { role: 'user', content: 'Write a short story about a robot' }\n  ],\n});\n\nfor await (const chunk of stream) {\n  process.stdout.write(chunk.delta.content || '');\n}\n```\n\n## Automatic Fallback\n\nConfigure fallback providers for high availability:\n\n```typescript\nconst client = new AIClient({\n  provider: 'openai',\n  apiKey: process.env.OPENAI_API_KEY,\n  fallbacks: [\n    {\n      provider: 'anthropic',\n      apiKey: process.env.ANTHROPIC_API_KEY,\n      priority: 1, // Lower = higher priority\n    },\n    {\n      provider: 'gemini',\n      apiKey: process.env.GEMINI_API_KEY,\n      priority: 2,\n    },\n  ],\n});\n\n// If OpenAI fails, automatically tries Anthropic, then Gemini\nconst response = await client.chat({\n  model: 'gpt-4o-mini',\n  messages: [{ role: 'user', content: 'Hello!' }],\n});\n```\n\n## Advanced Configuration\n\n### Retry Logic\n\n```typescript\nconst client = new AIClient({\n  provider: 'openai',\n  apiKey: process.env.OPENAI_API_KEY,\n  retry: {\n    maxRetries: 3,\n    initialDelay: 1000, // 1 second\n    maxDelay: 60000, // 60 seconds\n    backoffMultiplier: 2, // Exponential backoff\n  },\n  timeout: 30000, // 30 seconds\n});\n```\n\n### Debug Mode\n\n```typescript\nconst client = new AIClient({\n  provider: 'openai',\n  apiKey: process.env.OPENAI_API_KEY,\n  debug: true, // Enables detailed logging\n});\n```\n\n### System Messages\n\n```typescript\nconst response = await client.chat({\n  model: 'gpt-4o-mini',\n  messages: [\n    { role: 'system', content: 'You are a helpful coding assistant' },\n    { role: 'user', content: 'How do I center a div?' },\n  ],\n});\n```\n\n### Temperature & Other Options\n\n```typescript\nconst response = await client.chat({\n  model: 'gpt-4o-mini',\n  messages: [{ role: 'user', content: 'Be creative!' }],\n  temperature: 1.5,\n  max_tokens: 500,\n  top_p: 0.9,\n  stop: ['\\n\\n', 'END'],\n});\n```\n\n## Function/Tool Calling\n\nCall external functions and APIs from your AI models across all providers.\n\n> **Note**: If you're upgrading from the legacy `functions` API, see the [Migration Guide](MIGRATION_GUIDE.md).\n\n### Basic Example\n\n```typescript\nconst response = await client.chat({\n  model: 'gpt-4o-mini',\n  messages: [{ role: 'user', content: 'What is the weather in Tokyo?' }],\n  tools: [{\n    type: 'function',\n    function: {\n      name: 'get_weather',\n      description: 'Get current weather for a location',\n      parameters: {\n        type: 'object',\n        properties: {\n          location: { type: 'string', description: 'City name' },\n          unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }\n        },\n        required: ['location']\n      }\n    }\n  }]\n});\n\nif (response.message.tool_calls) {\n  // Execute your function\n  const weatherData = getWeather('Tokyo');\n\n  // Send result back\n  const finalResponse = await client.chat({\n    model: 'gpt-4o-mini',\n    messages: [\n      { role: 'user', content: 'What is the weather in Tokyo?' },\n      response.message,\n      {\n        role: 'tool',\n        content: JSON.stringify(weatherData),\n        tool_call_id: response.message.tool_calls[0].id,\n      }\n    ],\n    tools,\n  });\n\n  console.log(finalResponse.message.content);\n}\n```\n\n### Provider Support\n\n| Provider | Tool Calling | Parallel Calls | Streaming |\n|----------|--------------|----------------|-----------|\n| OpenAI | ✅ | ✅ | ✅ |\n| Anthropic | ✅ | ✅ | ✅ |\n| Gemini | ✅ | ❌ | ✅ |\n\n### Tool Choice Options\n\n```typescript\n// Let model decide (default)\ntool_choice: 'auto'\n\n// Disable tools\ntool_choice: 'none'\n\n// Force tool use (OpenAI only)\ntool_choice: 'required'\n\n// Force specific tool\ntool_choice: { type: 'function', function: { name: 'get_weather' } }\n\n// Enable parallel tool calls (OpenAI only, default: true)\nparallel_tool_calls: true\n```\n\n## Custom Provider Support\n\nYou can now create custom providers to integrate any LLM or backend API while maintaining the unified interface and features like auto-fallback and retry logic.\n\n### Creating a Custom Provider\n\nExtend the `BaseProvider` class to create your own provider:\n\n```typescript\nimport { BaseProvider, type ChatRequest, type ChatResponse, type StreamChunk, AIIntegratorError, ErrorType } from '@ai-integrator/core';\n\nclass MyCustomProvider extends BaseProvider {\n  readonly type = 'my-custom' as const;\n\n  protected getProviderDefaultModel(): string {\n    return 'my-default-model';\n  }\n\n  async chat(request: ChatRequest): Promise<ChatResponse> {\n    this.validateRequest(request);\n\n    const response = await fetch(`${this.config.baseURL}/chat`, {\n      method: 'POST',\n      headers: {\n        'Authorization': `Bearer ${this.config.apiKey}`,\n        'Content-Type': 'application/json',\n      },\n      body: JSON.stringify({\n        model: request.model || this.getDefaultModel(),\n        messages: request.messages,\n      }),\n    });\n\n    const data = await response.json();\n\n    return {\n      id: data.id,\n      provider: this.type,\n      model: data.model,\n      message: {\n        role: 'assistant',\n        content: data.content,\n      },\n      finish_reason: 'stop',\n      created_at: new Date(),\n    };\n  }\n\n  async *chatStream(request: ChatRequest): AsyncGenerator<StreamChunk> {\n    // Implement streaming logic\n    this.validateRequest(request);\n    // ... streaming implementation\n  }\n\n  protected handleError(error: unknown): AIIntegratorError {\n    return new AIIntegratorError(\n      ErrorType.API_ERROR,\n      error instanceof Error ? error.message : 'Unknown error',\n      undefined,\n      this.type,\n      false,\n      error\n    );\n  }\n}\n```\n\n### Using a Custom Provider\n\n```typescript\nimport { AIClient } from '@ai-integrator/core';\nimport { MyCustomProvider } from './my-custom-provider';\n\nconst client = new AIClient({\n  provider: 'my-custom',\n  customProvider: MyCustomProvider,\n  apiKey: process.env.MY_API_KEY,\n  baseURL: 'https://my-api.com/v1',\n});\n\nconst response = await client.chat({\n  model: 'my-model',\n  messages: [{ role: 'user', content: 'Hello!' }],\n});\n```\n\n### Custom Provider with Fallbacks\n\nCustom providers work seamlessly with the auto-fallback system:\n\n```typescript\nconst client = new AIClient({\n  provider: 'my-custom',\n  customProvider: MyCustomProvider,\n  apiKey: process.env.MY_API_KEY,\n  baseURL: 'https://my-api.com/v1',\n  fallbacks: [\n    {\n      provider: 'openai',\n      apiKey: process.env.OPENAI_API_KEY,\n      priority: 1,\n    },\n    {\n      provider: 'another-custom',\n      customProvider: AnotherCustomProvider,\n      apiKey: process.env.ANOTHER_API_KEY,\n      priority: 2,\n    },\n  ],\n});\n```\n\n### Benefits of Custom Providers\n\n- ✅ **No vendor lock-in**: Use any LLM provider or your own backend\n- ✅ **Unified interface**: Same API across all providers (built-in and custom)\n- ✅ **Auto-fallback support**: Custom providers work with the fallback system\n- ✅ **Type-safe**: Full TypeScript support for custom providers\n- ✅ **Retry logic**: Automatic retries work with custom providers\n- ✅ **Streaming support**: Implement streaming for your custom provider\n\n### Use Cases\n\n- **Custom backend API**: Integrate with your own LLM backend\n- **Fine-tuned models**: Use fine-tuned models from custom endpoints\n- **New LLM providers**: Add support for providers like Mistral, Cohere, etc.\n- **Proxy/Middleware**: Add logging, caching, or rate limiting\n\nSee [examples/custom-provider.ts](examples/custom-provider.ts) for complete examples.\n\n## Edge Runtime Examples\n\n### Cloudflare Workers\n\n```typescript\nexport default {\n  async fetch(request: Request, env: Env) {\n    const client = new AIClient({\n      provider: 'openai',\n      apiKey: env.OPENAI_API_KEY,\n    });\n\n    const response = await client.chat({\n      model: 'gpt-4o-mini',\n      messages: [{ role: 'user', content: 'Hello from the edge!' }],\n    });\n\n    return new Response(response.message.content);\n  },\n};\n```\n\n### Vercel Edge Functions\n\n```typescript\nimport { AIClient } from '@ai-integrator/core';\n\nexport const config = {\n  runtime: 'edge',\n};\n\nexport default async function handler(req: Request) {\n  const client = new AIClient({\n    provider: 'anthropic',\n    apiKey: process.env.ANTHROPIC_API_KEY,\n  });\n\n  const stream = client.chatStream({\n    model: 'claude-3-5-sonnet-20241022',\n    messages: [{ role: 'user', content: 'Stream me a story' }],\n  });\n\n  const encoder = new TextEncoder();\n  const readable = new ReadableStream({\n    async start(controller) {\n      for await (const chunk of stream) {\n        controller.enqueue(encoder.encode(chunk.delta.content || ''));\n      }\n      controller.close();\n    },\n  });\n\n  return new Response(readable, {\n    headers: { 'Content-Type': 'text/plain' },\n  });\n}\n```\n\n### Deno\n\n```typescript\nimport { AIClient } from 'npm:@ai-integrator/core';\n\nconst client = new AIClient({\n  provider: 'gemini',\n  apiKey: Deno.env.get('GEMINI_API_KEY')!,\n});\n\nconst response = await client.chat({\n  model: 'gemini-2.0-flash-exp',\n  messages: [{ role: 'user', content: 'Hello from Deno!' }],\n});\n\nconsole.log(response.message.content);\n```\n\n## API Reference\n\n### `AIClient`\n\nMain client class for interacting with AI providers.\n\n#### Constructor\n\n```typescript\nnew AIClient(config: AIClientConfig)\n```\n\n**AIClientConfig:**\n\n| Property | Type | Required | Description |\n|----------|------|----------|-------------|\n| `provider` | `'openai' \\| 'anthropic' \\| 'gemini' \\| string` | Yes | Primary AI provider (built-in or custom identifier) |\n| `apiKey` | `string` | Yes | API key for the provider |\n| `customProvider` | `class extending BaseProvider` | No | Custom provider class (required when using custom provider identifier) |\n| `baseURL` | `string` | No | Custom API endpoint |\n| `organization` | `string` | No | Organization ID (OpenAI only) |\n| `defaultModel` | `string` | No | Default model to use |\n| `fallbacks` | `FallbackConfig[]` | No | Fallback providers (supports both built-in and custom providers) |\n| `retry` | `RetryConfig` | No | Retry configuration |\n| `timeout` | `number` | No | Request timeout in ms |\n| `debug` | `boolean` | No | Enable debug logging |\n\n#### Methods\n\n##### `chat(request: ChatRequest): Promise<ChatResponse>`\n\nPerform a chat completion.\n\n**ChatRequest:**\n\n| Property | Type | Required | Description |\n|----------|------|----------|-------------|\n| `model` | `string` | Yes | Model identifier |\n| `messages` | `Message[]` | Yes | Conversation messages |\n| `temperature` | `number` | No | Sampling temperature (0-2) |\n| `max_tokens` | `number` | No | Maximum tokens to generate |\n| `top_p` | `number` | No | Nucleus sampling parameter |\n| `stop` | `string \\| string[]` | No | Stop sequences |\n| `stream` | `boolean` | No | Enable streaming |\n| `tools` | `ToolDefinition[]` | No | Function/tool definitions for tool calling |\n| `tool_choice` | `ToolChoice` | No | Control which tool to call (`'auto'`, `'none'`, `'required'`, or specific tool) |\n| `parallel_tool_calls` | `boolean` | No | Enable parallel tool execution (OpenAI only, default: `true`) |\n\n##### `chatStream(request: ChatRequest): AsyncGenerator<StreamChunk>`\n\nPerform a streaming chat completion.\n\n##### `getPrimaryProvider(): string`\n\nGet the current primary provider type.\n\n##### `getProviders(): string[]`\n\nGet all configured providers.\n\n##### `setDebug(enabled: boolean): void`\n\nEnable or disable debug logging.\n\n## Feature Comparison\n\n| Feature | OpenAI | Anthropic | Gemini | @ai-integrator/core |\n|---------|--------|-----------|--------|---------------------|\n| Unified API | ❌ | ❌ | ❌ | ✅ |\n| Auto-fallback | ❌ | ❌ | ❌ | ✅ |\n| Edge-ready | ⚠️ | ⚠️ | ⚠️ | ✅ |\n| Zero-config switching | ❌ | ❌ | ❌ | ✅ |\n| Built-in retry | ❌ | ❌ | ❌ | ✅ |\n| Custom provider support | ❌ | ❌ | ❌ | ✅ |\n| Tool/Function calling | ✅ | ✅ | ✅ | ✅ |\n| Streaming | ✅ | ✅ | ✅ | ✅ |\n| TypeScript | ✅ | ✅ | ✅ | ✅ |\n\n## Comparison with Other Libraries\n\n### When to Use Each Library\n\n| You Need | Use This | Why |\n|----------|----------|-----|\n| **Simple provider switching** | @ai-integrator/core | Minimal overhead, focused scope |\n| **UI streaming components** | Vercel AI SDK | React hooks, UI framework integration |\n| **Full AI framework** | LangChain | Chains, agents, memory, retrievers |\n| **Self-hosted proxy** | LiteLLM | Centralized routing, enterprise features |\n\n### vs. Vercel AI SDK\n\n**@ai-integrator/core:**\n\n- Focused on backend provider abstraction\n- Wraps official provider SDKs (peer dependencies)\n- 4.4 KB gzipped - optimized for edge\n- No UI components or framework integration\n\n**Vercel AI SDK:**\n\n- Comprehensive UI and streaming toolkit\n- Custom API client implementations\n- ~50 KB gzipped - includes React hooks, Zod validation\n- Built for full-stack Next.js applications\n\n**Best of both:** Use Vercel AI SDK for UI, @ai-integrator/core for backend provider management.\n\n### vs. LangChain\n\n**@ai-integrator/core:**\n\n- Minimal provider abstraction layer\n- Simple API for chat completions and streaming\n- 4.4 KB gzipped - single-purpose library\n- Perfect for straightforward LLM API calls\n\n**LangChain:**\n\n- Full AI application framework\n- Chains, agents, memory, retrievers, vector stores\n- 37+ KB gzipped (core) to 200+ KB (full) - comprehensive features\n- Built for complex AI workflows and orchestration\n\n**Best of both:** Use LangChain for complex AI workflows, @ai-integrator/core for simple provider switching.\n\n### vs. LiteLLM\n\n**@ai-integrator/core:**\n\n- Zero infrastructure required\n- Edge-compatible npm package\n- Direct integration in your codebase\n- Developer-first, library approach\n\n**LiteLLM:**\n\n- Self-hosted proxy server\n- Centralized routing and rate limiting\n- Python-first with enterprise features\n- Operations-first, infrastructure approach\n\n**Best of both:** Use LiteLLM for centralized management, @ai-integrator/core for embedded integration.\n\n## Default Models\n\n| Provider | Default Model |\n|----------|---------------|\n| OpenAI | `gpt-4o-mini` |\n| Anthropic | `claude-3-5-sonnet-20241022` |\n| Gemini | `gemini-2.0-flash-exp` |\n\n## Error Handling\n\n```typescript\nimport { AIIntegratorError } from '@ai-integrator/core';\n\ntry {\n  const response = await client.chat({\n    model: 'gpt-4o-mini',\n    messages: [{ role: 'user', content: 'Hello!' }],\n  });\n} catch (error) {\n  if (error instanceof AIIntegratorError) {\n    console.error('Error type:', error.type);\n    console.error('Provider:', error.provider);\n    console.error('Status code:', error.statusCode);\n    console.error('Retryable:', error.retryable);\n  }\n}\n```\n\n**Error Types:**\n\n- `authentication_error`: Invalid API key\n- `rate_limit_error`: Rate limit exceeded\n- `invalid_request_error`: Invalid request parameters\n- `api_error`: API error from provider\n- `timeout_error`: Request timeout\n- `network_error`: Network connectivity issue\n- `unknown_error`: Unknown error\n\n## Bundle Size\n\n| Package | Minified | Gzipped | Focus Area | Dependency Strategy |\n|---------|----------|---------|------------|---------------------|\n| **@ai-integrator/core** | 17.6 KB | **4.4 KB** ✨ | Provider abstraction | Peer deps (optional SDKs) |\n| Vercel AI SDK (`ai`) | ~186 KB | ~50 KB† | UI + streaming toolkit | Custom API clients |\n| LangChain Core | ~120 KB | ~37 KB | Framework base | Optional dependencies |\n| LangChain (full) | 800+ KB | 200+ KB | Complete framework | Modular packages |\n\n**Measurement notes:**\n\n- **Gzipped** is the actual size delivered to users (HTTP compression) - the industry standard\n- **@ai-integrator/core**: Measured from built package v0.2.0\n- **Vercel AI SDK**: Based on community analysis ([source](https://blog.hyperknot.com/p/til-vercel-ai-sdk-the-bloat-king))\n- **LangChain**: Based on official docs and Bundlephobia\n- † Estimated from typical gzip compression ratios\n\n### Why These Size Differences?\n\n**We're smaller because:**\n\n- **Focused scope**: Only provider switching, no UI, no chains, no agents\n- **Leverage official SDKs**: We wrap existing libraries (peer deps)\n- **Minimal transformations**: Only convert between formats when needed\n- **No validation library**: Rely on provider SDKs for validation\n\n**Vercel AI SDK is larger because:**\n\n- **Custom implementations**: Reimplements API clients for all providers\n- **UI framework integration**: React hooks, streaming components\n- **Zod validation**: Runtime validation and deep type inference\n- **More features**: Structured outputs, middleware, tooling\n\n**LangChain is larger because:**\n\n- **Full framework**: Chains, agents, memory, retrievers, tools\n- **100+ integrations**: Vector stores, document loaders, etc.\n- **Complex abstractions**: LCEL, Runnables, callback systems\n\n> 💡 **Bottom line:** Each library serves different needs. We're the smallest because we focus exclusively on provider abstraction.\n\n## Best Practices\n\n1. **Use environment variables** for API keys\n2. **Enable fallbacks** for production applications\n3. **Configure timeouts** appropriate for your use case\n4. **Use streaming** for better UX in chat applications\n5. **Handle errors** gracefully with try-catch\n6. **Set appropriate temperature** based on use case (lower for factual, higher for creative)\n\n## Requirements\n\n- Node.js 20+\n- TypeScript 5+ (for type support)\n\n## License\n\nMIT\n\n## Contributing\n\nContributions are welcome! Please read our [Contributing Guide](.github/CONTRIBUTING.md) before submitting a pull request.\n\n### Development Workflow\n\n1. Fork the repository\n2. Clone and install dependencies: `npm install`\n3. Create a feature branch: `git checkout -b feat/my-feature`\n4. Make your changes\n5. Run validation: `npm run validate`\n6. Commit with conventional commits (enforced by git hooks)\n7. Submit a pull request\n\n**Quick links:**\n- [Quick Start Guide](.github/QUICK_START.md) - Fast setup and workflow\n- [Contributing Guide](.github/CONTRIBUTING.md) - Detailed contribution guidelines\n\n### Commit Message Format\n\n**This repository enforces commit message conventions using git hooks.**\n\nUse the interactive commit tool:\n```bash\ngit add .\nnpm run commit\n```\n\nOr write commits manually following the format:\n```bash\ngit commit -m \"feat: add new feature\"\ngit commit -m \"fix: resolve bug\"\ngit commit -m \"docs: update readme\"\n```\n\nSee our guides:\n- [Commit Convention](.github/COMMIT_CONVENTION.md) - Format and versioning rules\n- [Commit Linting Guide](.github/COMMIT_LINT_GUIDE.md) - Validation and troubleshooting\n\n### Automated Release Process\n\nWhen your PR is merged to `main`, the package will be automatically:\n- Version bumped (based on commit messages)\n- Published to npm\n- Released on GitHub with bundle size info\n\nSee [RELEASING.md](.github/RELEASING.md) for details.\n\n## Documentation\n\n- [Documentation Index](.github/DOCS.md) - Complete guide to all documentation\n- [GitHub Issues](https://github.com/hv-ojha/ai-integrator/issues) - Report issues or request features\n- [Contributing Guide](.github/CONTRIBUTING.md) - How to contribute\n\n## Roadmap\n\n### ✅ Completed (v0.2.0)\n- [x] **Function/tool calling support** - Full support across OpenAI, Anthropic, and Gemini\n  - Unified tool API with backward compatibility\n  - Parallel tool execution (OpenAI)\n  - Streaming tool calls\n  - Comprehensive migration guide\n\n### ✅ Completed (v0.3.0)\n- [x] **Custom provider support** - Bring your own LLM backend\n  - Extend BaseProvider class for custom implementations\n  - Full type safety for custom providers\n  - Custom providers work with auto-fallback system\n  - Example implementations and documentation\n  - No breaking changes to existing API\n\n### 🚀 Upcoming\n\n#### Near-term (v0.3.x - v0.4.x)\n- [ ] **Vision support for multimodal models**\n  - Image inputs for GPT-4 Vision, Claude 3, Gemini Pro Vision\n  - Unified image handling API\n- [ ] **Enhanced streaming capabilities**\n  - Server-sent events (SSE) support\n  - WebSocket streaming option\n  - Better error handling in streams\n\n#### Mid-term (v0.5.x - v0.7.x)\n- [ ] **Caching layer**\n  - Built-in response caching\n  - Prompt caching (Anthropic)\n  - Cache invalidation strategies\n- [ ] **Community provider registry**\n  - Pre-built custom providers for Mistral, Cohere, etc.\n  - Verified provider implementations\n  - Example providers and templates\n- [ ] **Observability & monitoring**\n  - Custom hooks for logging\n  - Token usage tracking\n  - Cost estimation\n  - Performance metrics\n\n#### Long-term (v0.8.x+)\n- [ ] **Advanced features**\n  - Structured output modes\n  - JSON mode support across providers\n  - Audio input/output support\n  - Batch processing API\n- [ ] **Developer tooling**\n  - Admin dashboard for monitoring\n  - CLI tool for testing providers\n  - Playground/sandbox environment\n\n---\n\nMade with ❤️ for developers who want simple AI integration\n","readmeFilename":"README.md"}