@pwshub/aisdk 0.0.4 → 0.0.6

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

@@ -0,0 +1,216 @@
+/**
+ * @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 { coerced } = coerceConfig(config, 'openai')
+      assert.strictEqual(coerced.temperature, 2)
+    })
+
+    it('should clamp temperature below range', () => {
+      const config = { temperature: -1 }
+      const { coerced } = coerceConfig(config, 'openai')
+      assert.strictEqual(coerced.temperature, 0)
+    })
+
+    it('should not clamp temperature within range', () => {
+      const config = { 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 { coerced } = coerceConfig(config, 'openai')
+      assert.strictEqual(coerced.topP, 1)
+    })
+
+    it('should clamp frequencyPenalty to valid range [-2, 2]', () => {
+      const config = { frequencyPenalty: 3 }
+      const { coerced } = coerceConfig(config, 'openai')
+      assert.strictEqual(coerced.frequencyPenalty, 2)
+    })
+
+    it('should clamp presencePenalty to valid range [-2, 2]', () => {
+      const config = { presencePenalty: -3 }
+      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 { coerced } = coerceConfig(config, 'anthropic')
+      assert.strictEqual(coerced.temperature, 1)
+    })
+
+    it('should clamp topK to valid range [1, 100]', () => {
+      const config = { topK: 150 }
+      const { coerced } = coerceConfig(config, 'anthropic')
+      assert.strictEqual(coerced.topK, 100)
+    })
+
+    it('should clamp topK below range', () => {
+      const config = { topK: 0 }
+      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 { coerced } = coerceConfig(config, 'google')
+      assert.strictEqual(coerced.temperature, 2)
+    })
+
+    it('should clamp topK to valid range [1, 100]', () => {
+      const config = { topK: 200 }
+      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 { coerced } = coerceConfig(config, 'dashscope')
+      assert.strictEqual(coerced.temperature, 2)
+    })
+
+    it('should clamp topP to valid range [0, 1]', () => {
+      const config = { topP: 2 }
+      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 { coerced } = coerceConfig(config, 'deepseek')
+      assert.strictEqual(coerced.temperature, 2)
+    })
+
+    it('should clamp frequencyPenalty to valid range [-2, 2]', () => {
+      const config = { frequencyPenalty: 5 }
+      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 { coerced } = coerceConfig(config, 'unknown')
+      assert.strictEqual(coerced.temperature, 100)
+    })
+
+    it('should not clamp non-numeric values', () => {
+      const config = { temperature: 'hot' }
+      const { coerced } = coerceConfig(config, 'openai')
+      assert.strictEqual(coerced.temperature, 'hot')
+    })
+
+    it('should handle empty config', () => {
+      const { coerced, dropped } = coerceConfig({}, 'openai')
+      assert.deepStrictEqual({ coerced, dropped }, { coerced: {}, dropped: [] })
+    })
+
+    it('should clamp multiple values at once', () => {
+      const config = {
+        temperature: 5,
+        topP: 2,
+        maxTokens: 100,
+      }
+      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)
+    })
+  })
+})

package/src/config.js

@@ -21,6 +21,7 @@
  * @property {number} [topK]
  * @property {number} [frequencyPenalty]
  * @property {number} [presencePenalty]
+ * @property {number} [randomSeed]
  */
 
 /**
@@ -34,6 +35,8 @@
  * @property {string} wireKey
  * @property {'root'|'generationConfig'} [scope] - Google nests some params
  * @property {ParamRange} [range] - Valid range for the param (for clamping)
+ * @property {number[]} [supportedValues] - Discrete allowed values (e.g. [1] for fixed temp)
+ * @property {number} [fixedValue] - Force param to this value regardless of input
  */
 
 /**
@@ -50,6 +53,8 @@ const WIRE_KEYS = {
       wireKey: 'temperature', range: {
         min: 0, max: 2,
       },
+      // Note: Some OpenAI models (e.g. gpt-5-nano) only support fixedValue: 1
+      // Model-specific overrides are handled in coerce.js via registry overrides
     },
     topP: {
       wireKey: 'top_p', range: {
@@ -66,6 +71,8 @@ const WIRE_KEYS = {
         min: -2, max: 2,
       },
     },
+    stop: { wireKey: 'stop' },
+    seed: { wireKey: 'seed' },
     // https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create
   },
   anthropic: {
@@ -85,6 +92,7 @@ const WIRE_KEYS = {
         min: 1, max: 100,
       },
     },
+    stop: { wireKey: 'stop_sequences' },
   },
   google: {
     temperature: {
@@ -105,6 +113,8 @@ const WIRE_KEYS = {
         min: 1, max: 100,
       },
     },
+    stop: { wireKey: 'stopSequences', scope: 'generationConfig' },
+    seed: { wireKey: 'seed', scope: 'generationConfig' },
   },
   dashscope: {
     temperature: {
@@ -123,6 +133,7 @@ const WIRE_KEYS = {
         min: 1, max: 100,
       },
     },
+    stop: { wireKey: 'stop' },
   },
   deepseek: {
     temperature: {
@@ -146,6 +157,38 @@ const WIRE_KEYS = {
         min: -2, max: 2,
       },
     },
+    stop: { wireKey: 'stop' },
+  },
+  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' },
+    stop: { wireKey: 'stop' },
+  },
+  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' },
+    stop: { wireKey: 'stop' },
   },
 }
 

package/src/config.test.js

@@ -0,0 +1,142 @@
+/**
+ * @fileoverview Tests for config module.
+ */
+
+import {
+  describe, it,
+} from 'node:test'
+import assert from 'node:assert'
+import {
+  normalizeConfig, getWireMap,
+} from '../src/config.js'
+
+describe('config', () => {
+  describe('getWireMap', () => {
+    it('should return wire map for openai', () => {
+      const wireMap = getWireMap('openai')
+      assert.ok(wireMap)
+      assert.ok(wireMap.temperature)
+      assert.strictEqual(wireMap.temperature.wireKey, 'temperature')
+    })
+
+    it('should return wire map for anthropic', () => {
+      const wireMap = getWireMap('anthropic')
+      assert.ok(wireMap)
+      assert.ok(wireMap.temperature)
+      assert.strictEqual(wireMap.temperature.wireKey, 'temperature')
+    })
+
+    it('should return wire map for google', () => {
+      const wireMap = getWireMap('google')
+      assert.ok(wireMap)
+      assert.ok(wireMap.temperature)
+      assert.strictEqual(wireMap.temperature.wireKey, 'temperature')
+      assert.strictEqual(wireMap.temperature.scope, 'generationConfig')
+    })
+
+    it('should return wire map for dashscope', () => {
+      const wireMap = getWireMap('dashscope')
+      assert.ok(wireMap)
+      assert.ok(wireMap.temperature)
+      assert.strictEqual(wireMap.temperature.wireKey, 'temperature')
+    })
+
+    it('should return wire map for deepseek', () => {
+      const wireMap = getWireMap('deepseek')
+      assert.ok(wireMap)
+      assert.ok(wireMap.temperature)
+      assert.strictEqual(wireMap.temperature.wireKey, 'temperature')
+    })
+
+    it('should return undefined for unknown provider', () => {
+      const wireMap = getWireMap('unknown')
+      assert.strictEqual(wireMap, undefined)
+    })
+  })
+
+  describe('normalizeConfig', () => {
+    it('should normalize openai config', () => {
+      const config = {
+        temperature: 0.5,
+        maxTokens: 100,
+        topP: 0.9,
+      }
+      const supportedParams = ['temperature', 'maxTokens', 'topP']
+      const result = normalizeConfig(config, 'openai', supportedParams, 'gpt-4o')
+
+      assert.strictEqual(result.temperature, 0.5)
+      assert.strictEqual(result.max_completion_tokens, 100)
+      assert.strictEqual(result.top_p, 0.9)
+    })
+
+    it('should normalize anthropic config', () => {
+      const config = {
+        temperature: 0.5,
+        maxTokens: 100,
+        topK: 50,
+      }
+      const supportedParams = ['temperature', 'maxTokens', 'topK']
+      const result = normalizeConfig(config, 'anthropic', supportedParams, 'claude-sonnet')
+
+      assert.strictEqual(result.temperature, 0.5)
+      assert.strictEqual(result.max_tokens, 100)
+      assert.strictEqual(result.top_k, 50)
+    })
+
+    it('should normalize google config with generationConfig nesting', () => {
+      const config = {
+        temperature: 0.5,
+        maxTokens: 100,
+        topP: 0.9,
+      }
+      const supportedParams = ['temperature', 'maxTokens', 'topP']
+      const result = normalizeConfig(config, 'google', supportedParams, 'gemini-2.0-flash')
+
+      assert.strictEqual(result.temperature, undefined)
+      assert.strictEqual(result.maxTokens, undefined)
+      assert.strictEqual(result.topP, undefined)
+      assert.ok(result.generationConfig)
+      assert.strictEqual(result.generationConfig.temperature, 0.5)
+      assert.strictEqual(result.generationConfig.maxOutputTokens, 100)
+      assert.strictEqual(result.generationConfig.topP, 0.9)
+    })
+
+    it('should skip unsupported params', () => {
+      const config = {
+        temperature: 0.5,
+        topK: 50, // openai doesn't support topK
+      }
+      const supportedParams = ['temperature']
+      const result = normalizeConfig(config, 'openai', supportedParams, 'gpt-4o')
+
+      assert.strictEqual(result.temperature, 0.5)
+      assert.strictEqual(result.top_k, undefined)
+    })
+
+    it('should skip null/undefined values', () => {
+      const config = {
+        temperature: 0.5,
+        maxTokens: null,
+        topP: undefined,
+      }
+      const supportedParams = ['temperature', 'maxTokens', 'topP']
+      const result = normalizeConfig(config, 'openai', supportedParams, 'gpt-4o')
+
+      assert.strictEqual(result.temperature, 0.5)
+      assert.strictEqual(result.max_completion_tokens, undefined)
+      assert.strictEqual(result.top_p, undefined)
+    })
+
+    it('should return empty object when no config provided', () => {
+      const result = normalizeConfig({}, 'openai', ['temperature'], 'gpt-4o')
+      assert.deepStrictEqual(result, {})
+    })
+
+    it('should return empty object when no supported params match', () => {
+      const config = { unknownParam: 123 }
+      const supportedParams = ['temperature']
+      const result = normalizeConfig(config, 'openai', supportedParams, 'gpt-4o')
+      assert.deepStrictEqual(result, {})
+    })
+  })
+})

package/src/errors.js

@@ -24,6 +24,9 @@
  * }
  */
 
+import { sanitizeForLogging } from './security.js'
+import { getLogger } from './logger.js'
+
 /**
  * Thrown when the provider returns a transient or server-side error.
  * HTTP 429 (rate limit) and 5xx responses produce this error.
@@ -35,11 +38,12 @@ export class ProviderError extends Error {
    * @param {object} meta
    * @param {number} meta.status        - HTTP status code
    * @param {string} meta.provider      - Provider ID
-   * @param {string} meta.model         - Model ID that was called
+   * @param {string} meta.model         - Model name that was called
    * @param {string} [meta.raw]         - Raw response body from provider
+   * @param {number} [meta.retryAfter]  - Milliseconds to wait before retrying
    */
   constructor(message, {
-    status, provider, model, raw,
+    status, provider, model, raw, retryAfter,
   } = {}) {
     super(message)
     this.name = 'ProviderError'
@@ -47,6 +51,7 @@ export class ProviderError extends Error {
     this.provider = provider
     this.model = model
     this.raw = raw
+    this.retryAfter = retryAfter
   }
 }
 
@@ -83,21 +88,63 @@ export class InputError extends Error {
  */
 export const PROVIDER_ERROR_STATUSES = new Set([429, 500, 502, 503, 504])
 
+/**
+ * Parses Retry-After header value to milliseconds
+ * @param {string} value - Retry-After header value (seconds or HTTP date)
+ * @returns {number|undefined} Milliseconds to wait, or undefined if unparseable
+ */
+const parseRetryAfter = (value) => {
+  if (!value) return undefined
+  
+  // Try parsing as seconds (number)
+  const seconds = parseInt(value, 10)
+  if (!isNaN(seconds)) {
+    return seconds * 1000 // Return milliseconds
+  }
+  
+  // Try parsing as HTTP date
+  const date = new Date(value)
+  if (!isNaN(date.getTime())) {
+    return date.getTime() - Date.now()
+  }
+  
+  return undefined
+}
+
 /**
  * Classifies an HTTP response into ProviderError or InputError and throws it.
  *
  * @param {Response} res
  * @param {string} provider
  * @param {string} model
+ * @param {import('./logger.js').Logger} logger
  * @returns {Promise<never>}
  */
-export const throwHttpError = async (res, provider, model) => {
+export const throwHttpError = async (res, provider, model, logger = getLogger()) => {
   const raw = await res.text()
+  const sanitizedRaw = sanitizeForLogging(raw)
+  const retryAfterHeader = res.headers.get('retry-after')
+  
   const meta = {
-    status: res.status, provider, model, raw,
+    status: res.status,
+    provider,
+    model,
+    raw: sanitizedRaw,
+    retryAfter: retryAfterHeader ? parseRetryAfter(retryAfterHeader) : undefined,
   }
-  const message = `${provider}/${model} responded with HTTP ${res.status}`
-
+  const message = `${model} responded with HTTP ${res.status}`
+  
+  // Only log if status is not a client error (avoid logging bad API keys, etc.)
+  if (res.status >= 500 || res.status === 429) {
+    logger.error(`[ai-client] ${message}`)
+    if (sanitizedRaw) {
+      logger.error(sanitizedRaw)
+    }
+    if (meta.retryAfter) {
+      logger.error(`[ai-client] Retry-After: ${meta.retryAfter}ms`)
+    }
+  }
+  
   if (PROVIDER_ERROR_STATUSES.has(res.status)) {
     throw new ProviderError(message, meta)
   }