@pwshub/aisdk 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dong Nguyen
+
+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,297 @@
+# @pwshub/aisdk
+
+A thin, unified AI client for OpenAI, Anthropic, Google, DashScope, and DeepSeek with automatic parameter normalization and fallback support.
+
+## Features
+
+- **Unified API**: Single interface for multiple AI providers
+- **Automatic parameter normalization**: Canonical camelCase params are translated to provider-specific wire format
+- **Parameter clamping**: Values are automatically clamped to provider-accepted ranges
+- **Fallback support**: Chain multiple models with automatic fallback on provider errors
+- **Token usage tracking**: Detailed token counts and estimated cost per request
+- **Provider-specific options**: Pass provider-specific parameters when needed
+
+## Installation
+
+```bash
+npm i @pwshub/aisdk
+# or
+pnpm i @pwshub/aisdk
+# or
+bun add @pwshub/aisdk
+```
+
+## Quick Start
+
+```javascript
+import { createAi } from '@pwshub/aisdk'
+
+const ai = createAi()
+
+// Basic usage
+const result = await ai.ask({
+  model: 'gpt-4o',
+  apikey: 'your-api-key-here',
+  prompt: 'What is the capital of Vietnam?',
+  temperature: 0.5,
+})
+
+console.log(result.text)
+console.log(result.usage) // { inputTokens, outputTokens, cacheTokens, estimatedCost }
+```
+
+## API
+
+### `createAi(options?)`
+
+Creates an AI client instance.
+
+**Options:**
+- `gatewayUrl` (optional): Override the default API endpoint URL
+
+**Returns:** An object with:
+- `ask(params)`: Send a generation request
+- `listModels()`: Get all available models from the registry
+
+### `ai.ask(params)`
+
+Sends a text generation request.
+
+**Parameters:**
+- `model` (string, required): Model ID (must exist in models.json)
+- `apikey` (string, required): API key for the provider
+- `prompt` (string, required): The user message
+- `system` (string, optional): Optional system prompt
+- `fallbacks` (string[], optional): Ordered list of fallback model IDs
+- `providerOptions` (object, optional): Provider-specific options
+- `temperature` (number, optional): Sampling temperature
+- `maxTokens` (number, optional): Maximum output tokens
+- `topP` (number, optional): Nucleus sampling parameter
+- `topK` (number, optional): Top-K sampling
+- `frequencyPenalty` (number, optional): Frequency penalty
+- `presencePenalty` (number, optional): Presence penalty
+
+**Returns:** Promise resolving to:
+```javascript
+{
+  text: string,           // Generated text
+  model: string,          // Model that responded
+  usage: {
+    inputTokens: number,
+    outputTokens: number,
+    cacheTokens: number,
+    estimatedCost: number // USD
+  }
+}
+```
+
+**Throws:**
+- `ProviderError`: Transient provider errors (429, 5xx) — safe to retry
+- `InputError`: Invalid input (400, 401, 403, 422) — fix input, do not retry
+
+## Examples
+
+### OpenAI
+
+```javascript
+import { createAi } from '@pwshub/aisdk'
+
+const ai = createAi()
+
+const result = await ai.ask({
+  model: 'gpt-4o',
+  apikey: process.env.OPENAI_API_KEY,
+  prompt: 'Explain quantum entanglement',
+  temperature: 0.7,
+  maxTokens: 500,
+})
+```
+
+### Anthropic
+
+```javascript
+const result = await ai.ask({
+  model: 'claude-sonnet-4-6',
+  apikey: process.env.ANTHROPIC_API_KEY,
+  prompt: 'Write a haiku about TypeScript',
+  temperature: 0.5,
+})
+```
+
+### Google
+
+```javascript
+const result = await ai.ask({
+  model: 'gemini-2.5-flash',
+  apikey: process.env.GOOGLE_API_KEY,
+  prompt: 'What is 2+2?',
+  providerOptions: {
+    safetySettings: [
+      { category: 'HARM_CATEGORY_HARASSMENT', threshold: 'BLOCK_NONE' },
+    ],
+  },
+})
+```
+
+### With Fallbacks
+
+```javascript
+try {
+  const result = await ai.ask({
+    model: 'gpt-4o',
+    apikey: process.env.OPENAI_API_KEY,
+    prompt: 'Hello',
+    fallbacks: ['gpt-4o-mini', 'claude-haiku-4-5'],
+  })
+  
+  if (result.model !== 'gpt-4o') {
+    console.warn(`Fell back to ${result.model}`)
+  }
+} catch (error) {
+  if (error instanceof ProviderError) {
+    console.error('All models failed:', error.message)
+  } else if (error instanceof InputError) {
+    console.error('Invalid request:', error.message)
+  }
+}
+```
+
+### DashScope (Alibaba)
+
+```javascript
+const result = await ai.ask({
+  model: 'qwen3.5-plus',
+  apikey: process.env.DASHSCOPE_API_KEY,
+  prompt: 'Hello',
+})
+```
+
+### DeepSeek
+
+```javascript
+const result = await ai.ask({
+  model: 'deepseek-chat',
+  apikey: process.env.DEEPSEEK_API_KEY,
+  prompt: 'Hello',
+})
+```
+
+## Supported Models
+
+This library does not ship with a predefined list of models. Instead, it accepts **any model** from the supported providers:
+
+- **OpenAI**: Any OpenAI model
+- **Anthropic**: Any Anthropic model
+- **Google**: Any Google model
+- **DashScope**: Any DashScope model
+- **DeepSeek**: Any DeepSeek model
+
+### Loading Models
+
+Models are loaded programmatically via `setModels()` from external sources (CMS, API, or local files for evaluation):
+
+```javascript
+import { createAi, setModels } from '@pwshub/aisdk'
+
+// Load models from your CMS or API
+const modelsFromCms = await fetch('https://cms.example.com/api/models').then(r => r.json())
+setModels(modelsFromCms)
+
+const ai = createAi()
+const result = await ai.ask({
+  model: 'gemini-2.5-flash',
+  apikey: 'your-api-key',
+  prompt: 'Hello!',
+})
+```
+
+### Model Record Format
+
+Each model record should include:
+- `id`: Model identifier used in requests
+- `name`: Official model name (used in API calls)
+- `provider`: Provider ID (openai, anthropic, google, dashscope, deepseek)
+- `input_price`: Price per 1M input tokens (USD)
+- `output_price`: Price per 1M output tokens (USD)
+- `cache_price`: Price per 1M cached tokens (USD)
+- `max_in`: Maximum input tokens (context window)
+- `max_out`: Maximum output tokens
+- `enable`: Boolean to enable/disable the model
+- `supportedParams` (optional): Array of supported parameter names
+
+> **Note**: The `examples/` folder includes `models.json` as a reference for running evaluation scripts.
+
+## Error Handling
+
+```javascript
+import { createAi, ProviderError, InputError } from '@pwshub/aisdk'
+
+const ai = createAi()
+
+try {
+  const result = await ai.ask({
+    model: 'gpt-4o',
+    apikey: process.env.OPENAI_API_KEY,
+    prompt: 'Hello',
+  })
+} catch (error) {
+  if (error instanceof ProviderError) {
+    // Provider-side error (rate limit, server error)
+    // Safe to retry or fallback to another model
+    console.error('Provider error:', error.status, error.message)
+  } else if (error instanceof InputError) {
+    // Client-side error (bad request, invalid API key)
+    // Do NOT retry — fix the input
+    console.error('Input error:', error.status, error.message)
+  }
+}
+```
+
+## Running Evaluation Scripts
+
+The package includes evaluation scripts to test each provider:
+
+```bash
+# OpenAI
+OPENAI_API_KEY=your-key npm run eval:openai
+
+# Anthropic
+ANTHROPIC_API_KEY=your-key npm run eval:anthropic
+
+# Google
+GOOGLE_API_KEY=your-key npm run eval:google
+
+# DashScope
+DASHSCOPE_API_KEY=your-key npm run eval:dashscope
+
+# DeepSeek
+DEEPSEEK_API_KEY=your-key npm run eval:deepseek
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Run linter
+npm run lint
+
+# Auto-fix linting issues
+npm run lint:fix
+```
+
+## AI Agents team
+
+- Claude Code: initiator
+- Qwen Code: implementer
+- Google Gemini: reviewer
+- DeepSeek: supporter
+- Ollama: supporter
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@pwshub/aisdk",
+  "version": "0.0.1",
+  "description": "A thin, unified AI client for OpenAI, Anthropic, Google, DashScope, and DeepSeek with automatic param normalization and fallback support",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ndaidong/aisdk"
+  },
+  "engines": {
+    "node": ">=22.0.0",
+    "bun": ">=1.0.0"
+  },
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "types": "./src/index.js",
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "lint": "eslint src/ test/",
+    "lint:fix": "eslint src/ test/ --fix",
+    "eval:openai": "node examples/openai.js",
+    "eval:anthropic": "node examples/anthropic.js",
+    "eval:google": "node examples/google.js",
+    "eval:dashscope": "node examples/dashscope.js",
+    "eval:deepseek": "node examples/deepseek.js"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.0.3",
+    "globals": "^17.4.0"
+  },
+  "keywords": [
+    "ai",
+    "llm",
+    "openai",
+    "anthropic",
+    "google",
+    "gemini",
+    "claude",
+    "gpt",
+    "qwen",
+    "deepseek",
+    "chat",
+    "generation",
+    "sdk"
+  ],
+  "author": "ndaidong",
+  "license": "MIT"
+}

package/src/coerce.js

@@ -0,0 +1,52 @@
+/**
+ * @fileoverview Per-provider param clamping.
+ *
+ * Coerces generation config values to each provider's acceptable ranges.
+ * Instead of throwing errors, values are silently clamped to min/max bounds
+ * with a console.warn for visibility.
+ *
+ * Uses the merged WIRE_KEYS config from config.js for range information.
+ */
+
+import { getWireMap } from './config.js'
+
+/**
+ * @typedef {import('./registry.js').ProviderId} ProviderId
+ */
+
+const clamp = (value, min, max) => Math.min(Math.max(value, min), max)
+
+/**
+ * Coerce config values to provider's acceptable ranges.
+ * Logs warnings for clamped values.
+ *
+ * @param {Record<string, unknown>} config
+ * @param {ProviderId} providerId
+ * @returns {Record<string, unknown>}
+ */
+export const coerceConfig = (config, providerId) => {
+  const wireMap = getWireMap(providerId)
+  if (!wireMap) {
+    return config
+  }
+
+  const result = { ...config }
+
+  for (const [key, value] of Object.entries(config)) {
+    const descriptor = wireMap[key]
+    const range = descriptor?.range
+    if (!range || typeof value !== 'number') {
+      continue
+    }
+
+    const clamped = clamp(value, range.min, range.max)
+    if (clamped !== value) {
+      console.warn(
+        `[ai-client] "${key}" value ${value} out of range for ${providerId}, clamped to ${clamped}`
+      )
+      result[key] = clamped
+    }
+  }
+
+  return result
+}

package/src/config.js

@@ -0,0 +1,209 @@
+/**
+ * @fileoverview Generation config normalizer.
+ *
+ * Validates canonical camelCase params against the model's supportedParams list
+ * (from registry), warns on unsupported ones, then translates to provider
+ * wire-format keys.
+ *
+ * Wire-key mappings are defined per-provider here. Google additionally needs
+ * some params nested under `generationConfig`.
+ */
+
+/**
+ * @typedef {import('./registry.js').ProviderId} ProviderId
+ */
+
+/**
+ * @typedef {Object} GenerationConfig
+ * @property {number} [temperature]
+ * @property {number} [maxTokens]
+ * @property {number} [topP]
+ * @property {number} [topK]
+ * @property {number} [frequencyPenalty]
+ * @property {number} [presencePenalty]
+ */
+
+/**
+ * @typedef {Object} ParamRange
+ * @property {number} min
+ * @property {number} max
+ */
+
+/**
+ * @typedef {Object} WireDescriptor
+ * @property {string} wireKey
+ * @property {'root'|'generationConfig'} [scope] - Google nests some params
+ * @property {ParamRange} [range] - Valid range for the param (for clamping)
+ */
+
+/**
+ * Wire-key translation table per provider.
+ * Only lists params that exist for that provider.
+ * Includes range info for param clamping.
+ *
+ * @type {Record<ProviderId, Record<string, WireDescriptor>>}
+ */
+const WIRE_KEYS = {
+  openai: {
+    maxTokens: { wireKey: 'max_completion_tokens' },
+    temperature: {
+      wireKey: 'temperature', range: {
+        min: 0, max: 2,
+      },
+    },
+    topP: {
+      wireKey: 'top_p', range: {
+        min: 0, max: 1,
+      },
+    },
+    frequencyPenalty: {
+      wireKey: 'frequency_penalty', range: {
+        min: -2, max: 2,
+      },
+    },
+    presencePenalty: {
+      wireKey: 'presence_penalty', range: {
+        min: -2, max: 2,
+      },
+    },
+    // https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create
+  },
+  anthropic: {
+    maxTokens: { wireKey: 'max_tokens' },
+    temperature: {
+      wireKey: 'temperature', range: {
+        min: 0, max: 1,
+      },
+    },
+    topP: {
+      wireKey: 'top_p', range: {
+        min: 0, max: 1,
+      },
+    },
+    topK: {
+      wireKey: 'top_k', range: {
+        min: 1, max: 100,
+      },
+    },
+  },
+  google: {
+    temperature: {
+      wireKey: 'temperature', scope: 'generationConfig', range: {
+        min: 0, max: 2,
+      },
+    },
+    maxTokens: {
+      wireKey: 'maxOutputTokens', scope: 'generationConfig',
+    },
+    topP: {
+      wireKey: 'topP', scope: 'generationConfig', range: {
+        min: 0, max: 1,
+      },
+    },
+    topK: {
+      wireKey: 'topK', scope: 'generationConfig', range: {
+        min: 1, max: 100,
+      },
+    },
+  },
+  dashscope: {
+    temperature: {
+      wireKey: 'temperature', range: {
+        min: 0, max: 2,
+      },
+    },
+    maxTokens: { wireKey: 'max_tokens' },
+    topP: {
+      wireKey: 'top_p', range: {
+        min: 0, max: 1,
+      },
+    },
+    topK: {
+      wireKey: 'top_k', range: {
+        min: 1, max: 100,
+      },
+    },
+  },
+  deepseek: {
+    temperature: {
+      wireKey: 'temperature', range: {
+        min: 0, max: 2,
+      },
+    },
+    maxTokens: { wireKey: 'max_tokens' },
+    topP: {
+      wireKey: 'top_p', range: {
+        min: 0, max: 1,
+      },
+    },
+    frequencyPenalty: {
+      wireKey: 'frequency_penalty', range: {
+        min: -2, max: 2,
+      },
+    },
+    presencePenalty: {
+      wireKey: 'presence_penalty', range: {
+        min: -2, max: 2,
+      },
+    },
+  },
+}
+
+/**
+ * Normalizes a GenerationConfig to provider wire format, using the model's
+ * `supportedParams` list as the source of truth for what's allowed.
+ *
+ * - Params not in `supportedParams` → console.warn + drop
+ * - Params in `supportedParams` → translate to provider wire key
+ * - Google params with scope 'generationConfig' → nested automatically
+ *
+ * @param {GenerationConfig} config
+ * @param {ProviderId} providerId
+ * @param {string[]} supportedParams  - From the model's registry entry
+ * @param {string} modelId            - Used in warning messages
+ * @returns {Record<string, unknown>}
+ */
+export const normalizeConfig = (config, providerId, supportedParams, modelId) => {
+  const wireMap = WIRE_KEYS[providerId]
+  const supported = new Set(supportedParams)
+  const root = {}
+  const generationConfig = {}
+
+  for (const [canonicalKey, value] of Object.entries(config)) {
+    if (value === null || value === undefined) {
+      continue
+    }
+
+    if (!supported.has(canonicalKey)) {
+      console.warn(
+        `[ai-client] "${canonicalKey}" is not supported by model "${modelId}" — skipping.`
+      )
+      continue
+    }
+
+    const descriptor = wireMap[canonicalKey]
+    if (!descriptor) {
+      continue
+    } // paranoia guard — should not happen if registry is correct
+
+    if (descriptor.scope === 'generationConfig') {
+      generationConfig[descriptor.wireKey] = value
+    } else {
+      root[descriptor.wireKey] = value
+    }
+  }
+
+  if (Object.keys(generationConfig).length > 0) {
+    root.generationConfig = generationConfig
+  }
+
+  return root
+}
+
+/**
+ * Returns the wire-key map for a provider.
+ * Used by coerce.js for param range validation.
+ * @param {ProviderId} providerId
+ * @returns {Record<string, WireDescriptor>}
+ */
+export const getWireMap = (providerId) => WIRE_KEYS[providerId]