@pwshub/aisdk 0.0.3 → 0.0.5

package/README.md

@@ -1,6 +1,10 @@
 # @pwshub/aisdk
 
-A thin, unified AI client for OpenAI, Anthropic, Google, DashScope, and DeepSeek with automatic parameter normalization and fallback support.
+A thin, unified AI client for OpenAI, Anthropic, Google, DashScope, DeepSeek, and Mistral with automatic parameter normalization and fallback support.
+
+[![npm version](https://badge.fury.io/js/@pwshub%2Faisdk.svg)](https://badge.fury.io/js/@pwshub%2Faisdk)
+![CodeQL](https://github.com/pwshub/aisdk/workflows/CodeQL/badge.svg)
+![CI test](https://github.com/pwshub/aisdk/workflows/ci-test/badge.svg)
 
 ## Features
 
@@ -41,7 +45,7 @@ const ai = createAi()
 
 // Basic usage
 const result = await ai.ask({
-  model: 'gpt-4o',
+  model: 'openai/gpt-4o',
   apikey: 'your-api-key-here',
   prompt: 'What is the capital of Vietnam?',
   temperature: 0.5,
@@ -69,11 +73,11 @@ Creates an AI client instance.
 Sends a text generation request.
 
 **Parameters:**
-- `model` (string, required): Model ID (must exist in models.json)
-- `apikey` (string, required): API key for the provider
+- `model` (string, required): Use `provider/name` format (e.g., `anthropic/claude-sonnet-4-6`)
+- `apikey` (string, required): API key for the provider. With ollama local, set to any string.
 - `prompt` (string, required): The user message
 - `system` (string, optional): Optional system prompt
-- `fallbacks` (string[], optional): Ordered list of fallback model IDs
+- `fallbacks` (string[], optional): Ordered list of fallback models (same format as `model`)
 - `providerOptions` (object, optional): Provider-specific options
 - `temperature` (number, optional): Sampling temperature
 - `maxTokens` (number, optional): Maximum output tokens
@@ -111,7 +115,7 @@ import { createAi } from '@pwshub/aisdk'
 const ai = createAi()
 
 const result = await ai.ask({
-  model: 'gpt-4o',
+  model: 'openai/gpt-4o',
   apikey: process.env.OPENAI_API_KEY,
   prompt: 'Explain quantum entanglement',
   temperature: 0.7,
@@ -123,7 +127,7 @@ const result = await ai.ask({
 
 ```javascript
 const result = await ai.ask({
-  model: 'claude-sonnet-4-6',
+  model: 'anthropic/claude-sonnet-4-6',
   apikey: process.env.ANTHROPIC_API_KEY,
   prompt: 'Write a haiku about TypeScript',
   temperature: 0.5,
@@ -134,7 +138,7 @@ const result = await ai.ask({
 
 ```javascript
 const result = await ai.ask({
-  model: 'gemini-2.5-flash',
+  model: 'google/gemini-2.5-flash',
   apikey: process.env.GOOGLE_API_KEY,
   prompt: 'What is 2+2?',
   providerOptions: {
@@ -151,7 +155,7 @@ Gemini 2.5 Pro and other reasoning models use thinking tokens by default. Disabl
 
 ```javascript
 const result = await ai.ask({
-  model: 'gemini-2.5-pro',
+  model: 'google/gemini-2.5-pro',
   apikey: process.env.GOOGLE_API_KEY,
   prompt: 'What is the capital of Vietnam?',
   maxTokens: 256,
@@ -171,10 +175,10 @@ const result = await ai.ask({
 ```javascript
 try {
   const result = await ai.ask({
-    model: 'gpt-4o',
+    model: 'openai/gpt-4o',
     apikey: process.env.OPENAI_API_KEY,
     prompt: 'Hello',
-    fallbacks: ['gpt-4o-mini', 'claude-haiku-4-5'],
+    fallbacks: ['openai/gpt-4o-mini', 'anthropic/claude-haiku-4-5'],
   })
   
   if (result.model !== 'gpt-4o') {
@@ -193,7 +197,7 @@ try {
 
 ```javascript
 const result = await ai.ask({
-  model: 'qwen3.5-plus',
+  model: 'dashscope/qwen3.5-plus',
   apikey: process.env.DASHSCOPE_API_KEY,
   prompt: 'Hello',
 })
@@ -223,7 +227,7 @@ const aiCN = createAi({
 
 // Use the regional client
 const result = await aiSingapore.ask({
-  model: 'qwen3.5-plus',
+  model: 'dashscope/qwen3.5-plus',
   apikey: process.env.DASHSCOPE_API_KEY,
   prompt: 'Hello from Singapore!',
 })
@@ -233,56 +237,146 @@ const result = await aiSingapore.ask({
 
 ```javascript
 const result = await ai.ask({
-  model: 'deepseek-chat',
+  model: 'deepseek/deepseek-chat',
   apikey: process.env.DEEPSEEK_API_KEY,
   prompt: 'Hello',
 })
 ```
 
+### Mistral
+
+```javascript
+const result = await ai.ask({
+  model: 'mistral/mistral-large-latest',
+  apikey: process.env.MISTRAL_API_KEY,
+  prompt: 'Hello',
+  temperature: 0.7,
+})
+```
+
+### Mistral with Random Seed
+
+For reproducible results, use `randomSeed`:
+
+```javascript
+const result = await ai.ask({
+  model: 'mistral/mistral-medium-latest',
+  apikey: process.env.MISTRAL_API_KEY,
+  prompt: 'Write a poem',
+  randomSeed: 42,
+})
+```
+
 ## Supported Models
 
-This library does not ship with a predefined list of models. Instead, it accepts **any model** from the supported providers:
+The library comes with just a few popular models configured in src/models.js
+
+## Model Management
 
-- **OpenAI**: Any OpenAI model
-- **Anthropic**: Any Anthropic model
-- **Google**: Any Google model
-- **DashScope**: Any DashScope model
-- **DeepSeek**: Any DeepSeek model
+Models are automatically loaded from the built-in registry when the library is imported. You can add custom models or replace the entire list with your own (e.g., from a CMS).
 
-### Loading Models
+### Adding Custom Models
 
-Models are loaded programmatically via `setModels()` from external sources (CMS, API, or local files for evaluation):
+Use `addModels()` to add models to the existing registry. Only `name` and `provider` are required — other fields get sensible defaults:
+
+```javascript
+import { createAi, addModels, listModels } from '@pwshub/aisdk'
+
+// Add minimal model records (auto-generates ID and sets defaults)
+addModels([
+  { name: 'llama3.2', provider: 'ollama' },
+  { name: 'mistral', provider: 'ollama' },
+  { name: 'gemma3', provider: 'ollama' },
+])
+
+// Add models with custom pricing
+addModels([
+  {
+    name: 'my-custom-model',
+    provider: 'openai',
+    input_price: 0.5,
+    output_price: 1.5,
+    max_in: 128000,
+    max_out: 16384,
+  },
+])
+
+// View all available models
+console.log(listModels())
+```
+
+**Default values for missing fields:**
+- `id`: Auto-generated as `${provider}_${name}` (e.g., `ollama_llama3.2`)
+- `input_price`, `output_price`, `cache_price`: `0`
+- `max_in`: `32000`
+- `max_out`: `8000`
+- `enable`: `true`
+
+### Loading Models from CMS
+
+Use `setModels()` to replace the entire registry with models from your CMS:
 
 ```javascript
 import { createAi, setModels } from '@pwshub/aisdk'
 
-// Load models from your CMS or API
+// Fetch models from your CMS
 const modelsFromCms = await fetch('https://cms.example.com/api/models').then(r => r.json())
+
+// Expected format from CMS:
+// [
+//   { id: 'uuid-123', name: 'llama3.2', provider: 'ollama', ... },
+//   { id: 'uuid-456', name: 'mistral', provider: 'ollama', ... }
+// ]
+
 setModels(modelsFromCms)
 
 const ai = createAi()
-const result = await ai.ask({
-  model: 'gemini-2.5-flash',
-  apikey: 'your-api-key',
-  prompt: 'Hello!',
+```
+
+> **Note:** Model `id` can be any unique string (UUID, slug, etc.). The library uses it for internal tracking. When using models from CMS, you reference them by `provider/name` format (see below).
+
+### Using Models
+
+Models MUST be referenced in `provider/name` format:
+
+```javascript
+const ai = createAi()
+
+// Correct: provider/name format
+await ai.ask({
+  model: 'openai/gpt-4o',
+  apikey: process.env.OPENAI_API_KEY,
+  prompt: 'Hello',
+})
+
+// Correct: works for all providers
+await ai.ask({
+  model: 'ollama/llama3.2',
+  apikey: '',
+  prompt: 'Hello',
+})
+
+await ai.ask({
+  model: 'anthropic/claude-sonnet-4-6',
+  apikey: process.env.ANTHROPIC_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.
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `name` | Yes | - | Model name used in API calls |
+| `provider` | Yes | - | Provider ID (openai, anthropic, google, dashscope, deepseek, mistral, ollama) |
+| `id` | No | `${provider}_${name}` | Unique identifier (auto-generated if not provided) |
+| `input_price` | No | `0` | Price per 1M input tokens (USD) |
+| `output_price` | No | `0` | Price per 1M output tokens (USD) |
+| `cache_price` | No | `0` | Price per 1M cached tokens (USD) |
+| `max_in` | No | `32000` | Maximum input tokens (context window) |
+| `max_out` | No | `8000` | Maximum output tokens |
+| `enable` | No | `true` | Enable/disable the model |
+| `supportedParams` | No | Provider defaults | Array of supported parameter names |
 
 ## Error Handling
 
@@ -293,7 +387,7 @@ const ai = createAi()
 
 try {
   const result = await ai.ask({
-    model: 'gpt-4o',
+    model: 'openai/gpt-4o',
     apikey: process.env.OPENAI_API_KEY,
     prompt: 'Hello',
   })
@@ -329,6 +423,9 @@ DASHSCOPE_API_KEY=your-key npm run eval:dashscope
 
 # DeepSeek
 DEEPSEEK_API_KEY=your-key npm run eval:deepseek
+
+# Mistral
+MISTRAL_API_KEY=your-key npm run eval:mistral
 ```
 
 ## Development
@@ -357,4 +454,4 @@ npm run lint:fix
 
 ## License
 
-MIT
+The MIT License (MIT)

package/index.d.ts

@@ -6,11 +6,17 @@ export interface AiOptions {
   gatewayUrl?: string;
 }
 
+export interface Message {
+  role: 'user' | 'assistant' | 'system';
+  content: string;
+}
+
 export interface AskParams {
   model: string;
   apikey: string;
-  prompt: string;
+  prompt?: string;
   system?: string;
+  messages?: Message[];
   fallbacks?: string[];
   providerOptions?: Record<string, unknown>;
   temperature?: number;
@@ -19,6 +25,9 @@ export interface AskParams {
   topK?: number;
   frequencyPenalty?: number;
   presencePenalty?: number;
+  randomSeed?: number;
+  seed?: number;
+  numPredict?: number;
 }
 
 export interface Usage {
@@ -36,15 +45,15 @@ export interface AskResult {
 }
 
 export interface ModelRecord {
-  id: string;
+  id?: string;
   name: string;
   provider: string;
-  input_price: number;
-  output_price: number;
-  cache_price: number;
-  max_in: number;
-  max_out: number;
-  enable: boolean;
+  input_price?: number;
+  output_price?: number;
+  cache_price?: number;
+  max_in?: number;
+  max_out?: number;
+  enable?: boolean;
   supportedParams?: string[];
 }
 
@@ -70,5 +79,6 @@ export interface AiClient {
 }
 
 export function createAi(opts?: AiOptions): AiClient;
+export function addModels(models: ModelRecord[]): void;
 export function setModels(models: ModelRecord[]): void;
 export function listModels(): ModelRecord[];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pwshub/aisdk",
-  "version": "0.0.3",
-  "description": "A thin, unified AI client for OpenAI, Anthropic, Google, DashScope, and DeepSeek with automatic param normalization and fallback support",
+  "version": "0.0.5",
+  "description": "A thin, unified AI client for OpenAI, Anthropic, Google, DashScope, DeepSeek, and Mistral with automatic param normalization and fallback support",
   "repository": {
     "type": "git",
     "url": "https://github.com/pwshub/aisdk"
@@ -22,14 +22,15 @@
     "index.d.ts"
   ],
   "scripts": {
-    "test": "node --test test/*.test.js",
-    "lint": "eslint src/ test/",
-    "lint:fix": "eslint src/ test/ --fix",
+    "test": "node --test src/*.test.js",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --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"
+    "eval:deepseek": "node examples/deepseek.js",
+    "eval:mistral": "node examples/mistral.js"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
@@ -47,6 +48,7 @@
     "gpt",
     "qwen",
     "deepseek",
+    "mistral",
     "chat",
     "generation",
     "sdk"

package/src/coerce.test.js

@@ -0,0 +1,142 @@
+/**
+ * @fileoverview Tests for coerce module.
+ */
+
+import {
+  describe, it,
+} from 'node:test'
+import assert from 'node:assert'
+import { coerceConfig } from '../src/coerce.js'
+
+describe('coerceConfig', () => {
+  describe('openai', () => {
+    it('should clamp temperature to valid range [0, 2]', () => {
+      const config = { temperature: 3 }
+      const result = coerceConfig(config, 'openai')
+      assert.strictEqual(result.temperature, 2)
+    })
+
+    it('should clamp temperature below range', () => {
+      const config = { temperature: -1 }
+      const result = coerceConfig(config, 'openai')
+      assert.strictEqual(result.temperature, 0)
+    })
+
+    it('should not clamp temperature within range', () => {
+      const config = { temperature: 1 }
+      const result = coerceConfig(config, 'openai')
+      assert.strictEqual(result.temperature, 1)
+    })
+
+    it('should clamp topP to valid range [0, 1]', () => {
+      const config = { topP: 1.5 }
+      const result = coerceConfig(config, 'openai')
+      assert.strictEqual(result.topP, 1)
+    })
+
+    it('should clamp frequencyPenalty to valid range [-2, 2]', () => {
+      const config = { frequencyPenalty: 3 }
+      const result = coerceConfig(config, 'openai')
+      assert.strictEqual(result.frequencyPenalty, 2)
+    })
+
+    it('should clamp presencePenalty to valid range [-2, 2]', () => {
+      const config = { presencePenalty: -3 }
+      const result = coerceConfig(config, 'openai')
+      assert.strictEqual(result.presencePenalty, -2)
+    })
+  })
+
+  describe('anthropic', () => {
+    it('should clamp temperature to valid range [0, 1]', () => {
+      const config = { temperature: 1.5 }
+      const result = coerceConfig(config, 'anthropic')
+      assert.strictEqual(result.temperature, 1)
+    })
+
+    it('should clamp topK to valid range [1, 100]', () => {
+      const config = { topK: 150 }
+      const result = coerceConfig(config, 'anthropic')
+      assert.strictEqual(result.topK, 100)
+    })
+
+    it('should clamp topK below range', () => {
+      const config = { topK: 0 }
+      const result = coerceConfig(config, 'anthropic')
+      assert.strictEqual(result.topK, 1)
+    })
+  })
+
+  describe('google', () => {
+    it('should clamp temperature to valid range [0, 2]', () => {
+      const config = { temperature: 3 }
+      const result = coerceConfig(config, 'google')
+      assert.strictEqual(result.temperature, 2)
+    })
+
+    it('should clamp topK to valid range [1, 100]', () => {
+      const config = { topK: 200 }
+      const result = coerceConfig(config, 'google')
+      assert.strictEqual(result.topK, 100)
+    })
+  })
+
+  describe('dashscope', () => {
+    it('should clamp temperature to valid range [0, 2]', () => {
+      const config = { temperature: 5 }
+      const result = coerceConfig(config, 'dashscope')
+      assert.strictEqual(result.temperature, 2)
+    })
+
+    it('should clamp topP to valid range [0, 1]', () => {
+      const config = { topP: 2 }
+      const result = coerceConfig(config, 'dashscope')
+      assert.strictEqual(result.topP, 1)
+    })
+  })
+
+  describe('deepseek', () => {
+    it('should clamp temperature to valid range [0, 2]', () => {
+      const config = { temperature: 3 }
+      const result = coerceConfig(config, 'deepseek')
+      assert.strictEqual(result.temperature, 2)
+    })
+
+    it('should clamp frequencyPenalty to valid range [-2, 2]', () => {
+      const config = { frequencyPenalty: 5 }
+      const result = coerceConfig(config, 'deepseek')
+      assert.strictEqual(result.frequencyPenalty, 2)
+    })
+  })
+
+  describe('edge cases', () => {
+    it('should return config unchanged for unknown provider', () => {
+      const config = { temperature: 100 }
+      const result = coerceConfig(config, 'unknown')
+      assert.strictEqual(result.temperature, 100)
+    })
+
+    it('should not clamp non-numeric values', () => {
+      const config = { temperature: 'hot' }
+      const result = coerceConfig(config, 'openai')
+      assert.strictEqual(result.temperature, 'hot')
+    })
+
+    it('should handle empty config', () => {
+      const result = coerceConfig({}, 'openai')
+      assert.deepStrictEqual(result, {})
+    })
+
+    it('should clamp multiple values at once', () => {
+      const config = {
+        temperature: 5,
+        topP: 2,
+        maxTokens: 100,
+      }
+      const result = coerceConfig(config, 'openai')
+      assert.strictEqual(result.temperature, 2)
+      assert.strictEqual(result.topP, 1)
+      assert.strictEqual(result.maxTokens, 100) // maxTokens has no range
+    })
+  })
+})

package/src/config.js

@@ -21,6 +21,7 @@
  * @property {number} [topK]
  * @property {number} [frequencyPenalty]
  * @property {number} [presencePenalty]
+ * @property {number} [randomSeed]
  */
 
 /**
@@ -147,6 +148,35 @@ const WIRE_KEYS = {
       },
     },
   },
+  mistral: {
+    temperature: {
+      wireKey: 'temperature', range: {
+        min: 0, max: 2,
+      },
+    },
+    maxTokens: { wireKey: 'max_tokens' },
+    topP: {
+      wireKey: 'top_p', range: {
+        min: 0, max: 1,
+      },
+    },
+    randomSeed: { wireKey: 'random_seed' },
+  },
+  ollama: {
+    temperature: {
+      wireKey: 'temperature', range: {
+        min: 0, max: 2,
+      },
+    },
+    maxTokens: { wireKey: 'num_predict' },
+    topP: {
+      wireKey: 'top_p', range: {
+        min: 0, max: 1,
+      },
+    },
+    topK: { wireKey: 'top_k' },
+    seed: { wireKey: 'seed' },
+  },
 }
 
 /**