@pwshub/aisdk 0.0.4 → 0.0.6

package/README.md

@@ -1,6 +1,6 @@
 # @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)
@@ -14,6 +14,15 @@ A thin, unified AI client for OpenAI, Anthropic, Google, DashScope, and DeepSeek
 - **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
+- **Request timeout**: Configurable timeout per client instance
+- **Request/Response hooks**: `onRequest` and `onResponse` callbacks for observability
+- **Configurable logging**: Custom or silent loggers via `setLogger()`, `getLogger()`, `noopLogger`
+- **Instance-based registry**: Each `createAi()` gets isolated model registry
+- **Custom models at creation**: Load custom models via `createAi({ models: [...] })`
+- **Stop sequences**: Control generation with `stop: string | string[]`
+- **Retry-After support**: `retryAfter` property on `ProviderError` for rate limit handling
+- **API key validation**: Pre-request validation with provider-specific format warnings
+- **Empty prompt validation**: Rejects empty prompts and message content
 
 ## Limitations
 
@@ -45,7 +54,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,
@@ -63,21 +72,27 @@ Creates an AI client instance.
 
 **Options:**
 - `gatewayUrl` (optional): Override the default API endpoint URL
+- `timeout` (optional): Request timeout in milliseconds (default: 30000)
+- `models` (optional): Custom model registry to load on creation
+- `onRequest` (optional): Hook called before each request with context `{ model, provider, url, headers, body }`
+- `onResponse` (optional): Hook called after each response with context `{ model, provider, url, headers, body, status, data, duration }`
 
 **Returns:** An object with:
 - `ask(params)`: Send a generation request
 - `listModels()`: Get all available models from the registry
+- `addModels(models)`: Add models to this instance's 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
+- `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 (or use `messages` array)
 - `system` (string, optional): Optional system prompt
-- `fallbacks` (string[], optional): Ordered list of fallback model IDs
+- `messages` (array, optional): Array of `{ role, content }` objects for multi-turn conversations
+- `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
@@ -85,6 +100,8 @@ Sends a text generation request.
 - `topK` (number, optional): Top-K sampling
 - `frequencyPenalty` (number, optional): Frequency penalty
 - `presencePenalty` (number, optional): Presence penalty
+- `stop` (string | string[], optional): Stop sequences to end generation
+- `seed` (number, optional): Random seed for reproducible output
 
 **Returns:** Promise resolving to:
 ```javascript
@@ -115,7 +132,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,
@@ -127,7 +144,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,
@@ -138,7 +155,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: {
@@ -155,7 +172,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,
@@ -175,10 +192,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') {
@@ -197,7 +214,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',
 })
@@ -227,7 +244,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!',
 })
@@ -237,74 +254,291 @@ 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,
+})
+```
+
+### With Stop Sequences
+
+Control where generation stops using `stop` parameter:
+
+```javascript
+// Single stop sequence
+const result = await ai.ask({
+  model: 'openai/gpt-4o',
+  apikey: process.env.OPENAI_API_KEY,
+  prompt: 'Complete this sentence: The quick brown fox',
+  stop: '.',  // Stop at first period
+})
+
+// Multiple stop sequences
+const result = await ai.ask({
+  model: 'anthropic/claude-sonnet-4-6',
+  apikey: process.env.ANTHROPIC_API_KEY,
+  prompt: 'Write a story',
+  stop: ['\n\n', 'THE END'],  // Stop at double newline or "THE END"
+})
+```
+
+### With Request Timeout
+
+Set a custom timeout for requests:
+
+```javascript
+import { createAi } from '@pwshub/aisdk'
+
+const ai = createAi({
+  timeout: 5000,  // 5 second timeout
+})
+
+try {
+  const result = await ai.ask({
+    model: 'openai/gpt-4o',
+    apikey: process.env.OPENAI_API_KEY,
+    prompt: 'Hello',
+  })
+} catch (error) {
+  if (error.message.includes('timeout')) {
+    console.error('Request timed out after 5 seconds')
+  }
+}
+```
+
+### With Request/Response Hooks
+
+Add observability with hooks:
+
+```javascript
+import { createAi } from '@pwshub/aisdk'
+
+const ai = createAi({
+  onRequest: (context) => {
+    console.log(`Sending request to ${context.provider}/${context.model}`)
+    console.log(`URL: ${context.url}`)
+    // context.headers and context.body are also available
+  },
+  onResponse: (context) => {
+    console.log(`Response from ${context.provider}/${context.model}`)
+    console.log(`Status: ${context.status}, Duration: ${context.duration}ms`)
+    // context.data contains the raw response
+  },
+})
+
+const result = await ai.ask({
+  model: 'openai/gpt-4o',
+  apikey: process.env.OPENAI_API_KEY,
+  prompt: 'Hello',
+})
+```
+
+### Custom Logger
+
+Configure logging behavior:
+
+```javascript
+import { createAi, setLogger, noopLogger } from '@pwshub/aisdk'
+
+// Use a custom logger
+setLogger({
+  warn: (msg) => myLogger.warning(msg),
+  error: (msg) => myLogger.error(msg),
+  debug: (msg) => myLogger.debug(msg),
+})
+
+// Or silence all logging (production)
+setLogger(noopLogger)
+
+// Get current logger
+const logger = getLogger()
+
+const ai = createAi()
+```
+
+### Instance-Based Registry
+
+Each `createAi()` instance has its own isolated model registry:
+
+```javascript
+import { createAi, addModels } from '@pwshub/aisdk'
+
+// Create two independent instances
+const ai1 = createAi()
+const ai2 = createAi()
+
+// Add models to ai1 only
+ai1.addModels([
+  { name: 'llama3.2', provider: 'ollama' },
+])
+
+// ai1 has the custom model
+console.log(ai1.listModels().length) // includes llama3.2
+
+// ai2 doesn't have it (isolated registry)
+console.log(ai2.listModels().length) // default models only
+```
+
+### Custom Models at Creation
+
+Load custom models when creating the AI client:
+
+```javascript
+import { createAi } from '@pwshub/aisdk'
+
+const customModels = [
+  { name: 'llama3.2', provider: 'ollama' },
+  { name: 'mistral', provider: 'ollama' },
+  {
+    name: 'gpt-4o-custom',
+    provider: 'openai',
+    input_price: 0.5,
+    output_price: 1.5,
+  },
+]
+
+const ai = createAi({
+  models: customModels,
+})
+
+// This instance only has the custom models
+console.log(ai.listModels())
+```
+
 ## Supported Models
 
-The library comes with **30 pre-configured models** from all supported providers:
+The library comes with just a few popular models configured in src/models.js
 
-- **OpenAI**: gpt-4.1-nano, gpt-4.1-mini, gpt-4.1, gpt-4o, gpt-4o-mini, gpt-5, gpt-5-mini, gpt-5-nano, gpt-5.1, gpt-5.2, gpt-5.4, o3-mini, o4-mini
-- **Anthropic**: claude-haiku-4-5, claude-sonnet-4-6, claude-sonnet-4-5, claude-opus-4-6
-- **Google**: gemini-2.5-flash, gemini-2.5-flash-lite, gemini-2.5-pro, gemini-3.1-pro-preview, gemini-3.1-flash-lite-preview
-- **DashScope**: qwen-flash, qwen3.5-flash, qwen-plus, qwen3.5-plus, qwen-max, qwen3-max
-- **DeepSeek**: deepseek-chat, deepseek-reasoner
+## Model Management
 
-### Managing Models
+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).
 
-Models are managed via `addModels()` and `setModels()`:
+### Adding Custom Models
+
+Use `addModels()` to add models to the existing registry. Only `name` and `provider` are required — other fields get sensible defaults:
 
 ```javascript
-import { createAi, addModels, setModels, listModels } from '@pwshub/aisdk'
+import { createAi, addModels, listModels } from '@pwshub/aisdk'
 
-// List all available models (30 models loaded by default)
-console.log(listModels())
+// 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 more models to the existing list
+// Add models with custom pricing
 addModels([
   {
-    id: 'my-custom-model',
     name: 'my-custom-model',
     provider: 'openai',
-    input_price: 1,
-    output_price: 2,
-    cache_price: 0.5,
+    input_price: 0.5,
+    output_price: 1.5,
     max_in: 128000,
     max_out: 16384,
-    enable: true,
   },
 ])
 
-// Replace all models with your own list (e.g., from CMS)
+// 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'
+
+// 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:** Models are loaded automatically from `src/models.js` when the library is imported. You don't need to call `setModels()` unless you want to use a custom model list.
+> **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
+| 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
 
@@ -315,7 +549,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',
   })
@@ -324,6 +558,11 @@ try {
     // Provider-side error (rate limit, server error)
     // Safe to retry or fallback to another model
     console.error('Provider error:', error.status, error.message)
+    
+    // For rate limits (429), check retryAfter for recommended wait time
+    if (error.retryAfter) {
+      console.log(`Retry after ${error.retryAfter} seconds`)
+    }
   } else if (error instanceof InputError) {
     // Client-side error (bad request, invalid API key)
     // Do NOT retry — fix the input
@@ -332,6 +571,19 @@ try {
 }
 ```
 
+**ProviderError properties:**
+- `status`: HTTP status code (429, 5xx, etc.)
+- `provider`: Provider ID (e.g., 'openai', 'anthropic')
+- `model`: Model identifier that failed
+- `raw`: Raw response data from provider
+- `retryAfter`: Seconds to wait before retrying (only for 429 responses with Retry-After header)
+
+**InputError properties:**
+- `status`: HTTP status code (400, 401, 403, 422)
+- `provider`: Provider ID
+- `model`: Model identifier
+- `raw`: Raw response data from provider
+
 ## Running Evaluation Scripts
 
 The package includes evaluation scripts to test each provider:
@@ -351,6 +603,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
@@ -379,4 +634,4 @@ npm run lint:fix
 
 ## License
 
-MIT
+The MIT License (MIT)

package/index.d.ts

@@ -4,13 +4,42 @@
 
 export interface AiOptions {
   gatewayUrl?: string;
+  timeout?: number;
+  models?: ModelRecord[];
+  onRequest?: (context: HookContext) => void | Promise<void>;
+  onResponse?: (context: ResponseHookContext) => void | Promise<void>;
+}
+
+export interface HookContext {
+  model: string;
+  provider: string;
+  url: string;
+  headers: Record<string, string>;
+  body: Record<string, unknown>;
+}
+
+export interface ResponseHookContext {
+  model: string;
+  provider: string;
+  url: string;
+  headers: Record<string, string>;
+  body: Record<string, unknown>;
+  status: number;
+  data: unknown;
+  duration: number;
+}
+
+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 +48,10 @@ export interface AskParams {
   topK?: number;
   frequencyPenalty?: number;
   presencePenalty?: number;
+  randomSeed?: number;
+  seed?: number;
+  numPredict?: number;
+  stop?: string | string[];
 }
 
 export interface Usage {
@@ -36,16 +69,23 @@ 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[];
+  paramOverrides?: Record<string, ParamOverride>;
+}
+
+export interface ParamOverride {
+  fixedValue?: number;
+  supportedValues?: number[];
+  range?: { min: number; max: number };
 }
 
 export class ProviderError extends Error {
@@ -53,7 +93,8 @@ export class ProviderError extends Error {
   provider: string;
   model: string;
   raw?: unknown;
-  constructor(message: string, options: { status: number; provider: string; model: string; raw?: unknown });
+  retryAfter?: number;
+  constructor(message: string, options: { status: number; provider: string; model: string; raw?: unknown; retryAfter?: number });
 }
 
 export class InputError extends Error {
@@ -64,12 +105,22 @@ export class InputError extends Error {
   constructor(message: string, options: { status: number; provider: string; model: string; raw?: unknown });
 }
 
+export interface Logger {
+  warn: (message: string) => void;
+  error: (message: string) => void;
+  debug: (message: string) => void;
+}
+
 export interface AiClient {
   ask: (params: AskParams) => Promise<AskResult>;
   listModels: () => ModelRecord[];
+  addModels: (models: ModelRecord[]) => void;
 }
 
 export function createAi(opts?: AiOptions): AiClient;
 export function addModels(models: ModelRecord[]): void;
 export function setModels(models: ModelRecord[]): void;
 export function listModels(): ModelRecord[];
+export function setLogger(logger: Logger): void;
+export function getLogger(): Logger;
+export const noopLogger: Logger;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pwshub/aisdk",
-  "version": "0.0.4",
-  "description": "A thin, unified AI client for OpenAI, Anthropic, Google, DashScope, and DeepSeek with automatic param normalization and fallback support",
+  "version": "0.0.6",
+  "description": "A thin, unified AI client for OpenAI, Anthropic, Google, DashScope, DeepSeek, and Mistral with automatic param normalization, fallback support, hooks, and timeout",
   "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"