@pwshub/aisdk 0.0.5 → 0.0.6

package/README.md

@@ -14,6 +14,15 @@ A thin, unified AI client for OpenAI, Anthropic, Google, DashScope, DeepSeek, an
 - **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
 
@@ -63,10 +72,15 @@ 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)`
 
@@ -75,8 +89,9 @@ Sends a text generation request.
 **Parameters:**
 - `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
+- `prompt` (string, required): The user message (or use `messages` array)
 - `system` (string, optional): Optional system prompt
+- `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
@@ -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
@@ -267,6 +284,151 @@ const result = await ai.ask({
 })
 ```
 
+### 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 just a few popular models configured in src/models.js
@@ -396,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
@@ -404,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:

package/index.d.ts

@@ -4,6 +4,29 @@
 
 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 {
@@ -28,6 +51,7 @@ export interface AskParams {
   randomSeed?: number;
   seed?: number;
   numPredict?: number;
+  stop?: string | string[];
 }
 
 export interface Usage {
@@ -55,6 +79,13 @@ export interface ModelRecord {
   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 {
@@ -62,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 {
@@ -73,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.5",
-  "description": "A thin, unified AI client for OpenAI, Anthropic, Google, DashScope, DeepSeek, and Mistral 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"

package/src/coerce.js

@@ -6,6 +6,7 @@
  * with a console.warn for visibility.
  *
  * Uses the merged WIRE_KEYS config from config.js for range information.
+ * Also supports model-specific overrides via the overrides parameter.
  */
 
 import { getWireMap } from './config.js'
@@ -14,27 +15,82 @@ import { getWireMap } from './config.js'
  * @typedef {import('./registry.js').ProviderId} ProviderId
  */
 
+/**
+ * @typedef {Object} ParamOverride
+ * @property {number} [fixedValue] - Force param to this value
+ * @property {number[]} [supportedValues] - Only allow these discrete values
+ * @property {{min: number, max: number}} [range] - Override the default range
+ */
+
+/**
+ * @typedef {Object} CoerceOptions
+ * @property {string} modelId - Model identifier for override lookup
+ * @property {Record<string, ParamOverride>} [overrides] - Model-specific param overrides
+ */
+
 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.
+ * Logs warnings for clamped or dropped values.
  *
  * @param {Record<string, unknown>} config
  * @param {ProviderId} providerId
- * @returns {Record<string, unknown>}
+ * @param {CoerceOptions} [options]
+ * @returns {{ coerced: Record<string, unknown>, dropped: string[] }}
  */
-export const coerceConfig = (config, providerId) => {
+export const coerceConfig = (config, providerId, options = {}) => {
+  const { modelId, overrides = {} } = options
   const wireMap = getWireMap(providerId)
   if (!wireMap) {
-    return config
+    return { coerced: config, dropped: [] }
   }
 
   const result = { ...config }
+  const dropped = []
 
   for (const [key, value] of Object.entries(config)) {
     const descriptor = wireMap[key]
-    const range = descriptor?.range
+    const override = overrides[key]
+    if (!descriptor && !override) {
+      continue
+    }
+
+    // Merge descriptor and override (override takes precedence)
+    const effectiveDescriptor = {
+      ...descriptor,
+      ...override,
+      range: override?.range || descriptor?.range,
+    }
+
+    // Handle fixedValue: force param to specific value
+    if (effectiveDescriptor.fixedValue !== undefined && typeof value === 'number') {
+      if (value !== effectiveDescriptor.fixedValue) {
+        console.warn(
+          `[ai-client] "${key}" value ${value} not supported by model "${modelId}", forced to ${effectiveDescriptor.fixedValue}`
+        )
+        result[key] = effectiveDescriptor.fixedValue
+      }
+      continue
+    }
+
+    // Handle supportedValues: only allow discrete values
+    if (effectiveDescriptor.supportedValues?.length && typeof value === 'number') {
+      if (!effectiveDescriptor.supportedValues.includes(value)) {
+        // Clamp to nearest supported value
+        const nearest = effectiveDescriptor.supportedValues.reduce((prev, curr) =>
+          Math.abs(curr - value) < Math.abs(prev - value) ? curr : prev
+        )
+        console.warn(
+          `[ai-client] "${key}" value ${value} not supported by model "${modelId}", clamped to nearest allowed ${nearest}`
+        )
+        result[key] = nearest
+      }
+      continue
+    }
+
+    // Handle range clamping (existing behavior)
+    const range = effectiveDescriptor.range
     if (!range || typeof value !== 'number') {
       continue
     }
@@ -48,5 +104,21 @@ export const coerceConfig = (config, providerId) => {
     }
   }
 
+  return { coerced: result, dropped }
+}
+
+/**
+ * Drop params that are not supported by a model.
+ * Used when provider returns an "unsupported_value" error.
+ *
+ * @param {Record<string, unknown>} config
+ * @param {string[]} paramsToDrop
+ * @returns {Record<string, unknown>}
+ */
+export const dropParams = (config, paramsToDrop) => {
+  const result = { ...config }
+  for (const param of paramsToDrop) {
+    delete result[param]
+  }
   return result
 }

package/src/coerce.test.js

@@ -12,119 +12,119 @@ 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)
+      const { coerced } = coerceConfig(config, 'openai')
+      assert.strictEqual(coerced.temperature, 2)
     })
 
     it('should clamp temperature below range', () => {
       const config = { temperature: -1 }
-      const result = coerceConfig(config, 'openai')
-      assert.strictEqual(result.temperature, 0)
+      const { coerced } = coerceConfig(config, 'openai')
+      assert.strictEqual(coerced.temperature, 0)
     })
 
     it('should not clamp temperature within range', () => {
       const config = { temperature: 1 }
-      const result = coerceConfig(config, 'openai')
-      assert.strictEqual(result.temperature, 1)
+      const { coerced } = coerceConfig(config, 'openai')
+      assert.strictEqual(coerced.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)
+      const { coerced } = coerceConfig(config, 'openai')
+      assert.strictEqual(coerced.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)
+      const { coerced } = coerceConfig(config, 'openai')
+      assert.strictEqual(coerced.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)
+      const { coerced } = coerceConfig(config, 'openai')
+      assert.strictEqual(coerced.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)
+      const { coerced } = coerceConfig(config, 'anthropic')
+      assert.strictEqual(coerced.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)
+      const { coerced } = coerceConfig(config, 'anthropic')
+      assert.strictEqual(coerced.topK, 100)
     })
 
     it('should clamp topK below range', () => {
       const config = { topK: 0 }
-      const result = coerceConfig(config, 'anthropic')
-      assert.strictEqual(result.topK, 1)
+      const { coerced } = coerceConfig(config, 'anthropic')
+      assert.strictEqual(coerced.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)
+      const { coerced } = coerceConfig(config, 'google')
+      assert.strictEqual(coerced.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)
+      const { coerced } = coerceConfig(config, 'google')
+      assert.strictEqual(coerced.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)
+      const { coerced } = coerceConfig(config, 'dashscope')
+      assert.strictEqual(coerced.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)
+      const { coerced } = coerceConfig(config, 'dashscope')
+      assert.strictEqual(coerced.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)
+      const { coerced } = coerceConfig(config, 'deepseek')
+      assert.strictEqual(coerced.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)
+      const { coerced } = coerceConfig(config, 'deepseek')
+      assert.strictEqual(coerced.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)
+      const { coerced } = coerceConfig(config, 'unknown')
+      assert.strictEqual(coerced.temperature, 100)
     })
 
     it('should not clamp non-numeric values', () => {
       const config = { temperature: 'hot' }
-      const result = coerceConfig(config, 'openai')
-      assert.strictEqual(result.temperature, 'hot')
+      const { coerced } = coerceConfig(config, 'openai')
+      assert.strictEqual(coerced.temperature, 'hot')
     })
 
     it('should handle empty config', () => {
-      const result = coerceConfig({}, 'openai')
-      assert.deepStrictEqual(result, {})
+      const { coerced, dropped } = coerceConfig({}, 'openai')
+      assert.deepStrictEqual({ coerced, dropped }, { coerced: {}, dropped: [] })
     })
 
     it('should clamp multiple values at once', () => {
@@ -133,10 +133,84 @@ describe('coerceConfig', () => {
         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
+      const { coerced } = coerceConfig(config, 'openai')
+      assert.strictEqual(coerced.temperature, 2)
+      assert.strictEqual(coerced.topP, 1)
+      assert.strictEqual(coerced.maxTokens, 100) // maxTokens has no range
+    })
+  })
+
+  describe('fixedValue overrides', () => {
+    it('should force temperature to fixedValue', () => {
+      const config = { temperature: 0.5 }
+      const { coerced } = coerceConfig(config, 'openai', {
+        modelId: 'openai/gpt-5-nano',
+        overrides: {
+          temperature: { fixedValue: 1 },
+        },
+      })
+      assert.strictEqual(coerced.temperature, 1)
+    })
+
+    it('should not change value if it already matches fixedValue', () => {
+      const config = { temperature: 1 }
+      const { coerced } = coerceConfig(config, 'openai', {
+        modelId: 'openai/gpt-5-nano',
+        overrides: {
+          temperature: { fixedValue: 1 },
+        },
+      })
+      assert.strictEqual(coerced.temperature, 1)
+    })
+
+    it('should force multiple params to fixed values', () => {
+      const config = { temperature: 0.5, topP: 0.8 }
+      const { coerced } = coerceConfig(config, 'openai', {
+        modelId: 'openai/gpt-5-nano',
+        overrides: {
+          temperature: { fixedValue: 1 },
+          topP: { fixedValue: 1 },
+        },
+      })
+      assert.strictEqual(coerced.temperature, 1)
+      assert.strictEqual(coerced.topP, 1)
+    })
+  })
+
+  describe('supportedValues (discrete values)', () => {
+    it('should clamp to nearest supported value', () => {
+      const config = { temperature: 0.3 }
+      const { coerced } = coerceConfig(config, 'openai', {
+        modelId: 'openai/some-model',
+        overrides: {
+          temperature: { supportedValues: [0, 0.5, 1] },
+        },
+      })
+      assert.strictEqual(coerced.temperature, 0.5)
+    })
+
+    it('should not change value if it matches a supported value', () => {
+      const config = { temperature: 0.5 }
+      const { coerced } = coerceConfig(config, 'openai', {
+        modelId: 'openai/some-model',
+        overrides: {
+          temperature: { supportedValues: [0, 0.5, 1] },
+        },
+      })
+      assert.strictEqual(coerced.temperature, 0.5)
+    })
+  })
+
+  describe('range overrides', () => {
+    it('should use overridden range instead of default', () => {
+      const config = { temperature: 3 }
+      const { coerced } = coerceConfig(config, 'openai', {
+        modelId: 'openai/some-model',
+        overrides: {
+          temperature: { range: { min: 0, max: 0.5 } },
+        },
+      })
+      assert.strictEqual(coerced.temperature, 0.5)
     })
   })
 })