@pwshub/aisdk 0.0.4 → 0.0.6

package/src/logger.js

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview Configurable logger for @pwshub/aisdk
+ *
+ * Provides a default console logger with the ability to set custom
+ * or no-op loggers for production environments.
+ */
+
+/**
+ * @typedef {Object} Logger
+ * @property {(message: string) => void} warn
+ * @property {(message: string) => void} error
+ * @property {(message: string) => void} debug
+ */
+
+const defaultLogger = {
+  warn: (message) => console.warn(message),
+  error: (message) => console.error(message),
+  debug: (message) => console.debug(message),
+}
+
+let currentLogger = defaultLogger
+
+/**
+ * Sets a custom logger instance
+ * @param {Logger} logger
+ * @throws {Error} When logger doesn't implement required methods
+ */
+export const setLogger = (logger) => {
+  if (!logger || typeof logger.warn !== 'function' || typeof logger.error !== 'function') {
+    throw new Error('Logger must implement warn() and error() methods')
+  }
+  currentLogger = logger
+}
+
+/**
+ * Returns the current logger instance
+ * @returns {Logger}
+ */
+export const getLogger = () => currentLogger
+
+/**
+ * No-op logger for silencing all output
+ */
+export const noopLogger = {
+  warn: () => {},
+  error: () => {},
+  debug: () => {},
+}

package/src/models.js

@@ -198,6 +198,11 @@ export const DEFAULT_MODELS = [
     max_in: 400000,
     max_out: 128000,
     enable: true,
+    // gpt-5-nano only supports default values for temperature and top_p
+    paramOverrides: {
+      temperature: { fixedValue: 1 },
+      topP: { fixedValue: 1 },
+    },
   },
   {
     id: 'gpt-5.1',
@@ -342,4 +347,60 @@ export const DEFAULT_MODELS = [
     max_out: 65536,
     enable: true,
   },
+  // Mistral models
+  {
+    id: 'mistral-large-latest',
+    name: 'mistral-large-latest',
+    provider: 'mistral',
+    input_price: 0.5,
+    output_price: 1.5,
+    cache_price: 0,
+    max_in: 128000,
+    max_out: 128000,
+    enable: true,
+  },
+  {
+    id: 'mistral-medium-latest',
+    name: 'mistral-medium-latest',
+    provider: 'mistral',
+    input_price: 0.4,
+    output_price: 2,
+    cache_price: 0,
+    max_in: 64000,
+    max_out: 64000,
+    enable: true,
+  },
+  {
+    id: 'mistral-small-latest',
+    name: 'mistral-small-latest',
+    provider: 'mistral',
+    input_price: 0.15,
+    output_price: 0.6,
+    cache_price: 0,
+    max_in: 128000,
+    max_out: 128000,
+    enable: true,
+  },
+  {
+    id: 'magistral-medium-latest',
+    name: 'magistral-medium-latest',
+    provider: 'mistral',
+    input_price: 2,
+    output_price: 5,
+    cache_price: 0,
+    max_in: 64000,
+    max_out: 64000,
+    enable: true,
+  },
+  {
+    id: 'magistral-small-latest',
+    name: 'magistral-small-latest',
+    provider: 'mistral',
+    input_price: 0.5,
+    output_price: 1.5,
+    cache_price: 0,
+    max_in: 64000,
+    max_out: 64000,
+    enable: true,
+  },
 ]

package/src/providers.js

@@ -10,7 +10,7 @@
  */
 
 /**
- * @typedef {'openai'|'anthropic'|'google'|'dashscope'|'deepseek'} ProviderId
+ * @typedef {'openai'|'anthropic'|'google'|'dashscope'|'deepseek'|'mistral'|'ollama'} ProviderId
  */
 
 /**
@@ -42,7 +42,7 @@ const openai = {
     Authorization: `Bearer ${apikey}`,
     'Content-Type': 'application/json',
   }),
-  url: () => 'https://api.openai.com/v1/chat/completions',
+  url: (modelName, apikey, gatewayUrl) => gatewayUrl || 'https://api.openai.com/v1/chat/completions',
   buildBody: (modelName, messages, config, providerOptions) => ({
     model: modelName,
     messages,
@@ -96,7 +96,7 @@ const anthropic = {
     'anthropic-version': '2023-06-01',
     'Content-Type': 'application/json',
   }),
-  url: () => 'https://api.anthropic.com/v1/messages',
+  url: (modelName, apikey, gatewayUrl) => gatewayUrl || 'https://api.anthropic.com/v1/messages',
   buildBody: (modelName, messages, config, providerOptions) => {
     const system = messages.find((m) => m.role === 'system')?.content
     const filtered = messages.filter((m) => m.role !== 'system')
@@ -129,8 +129,12 @@ const anthropic = {
 /** @type {ProviderAdapter} */
 const google = {
   headers: () => ({ 'Content-Type': 'application/json' }),
-  url: (modelName, apikey) =>
-    `https://generativelanguage.googleapis.com/v1/models/${modelName}:generateContent?key=${apikey}`,
+  url: (modelName, apikey, gatewayUrl) => {
+    if (gatewayUrl) {
+      return gatewayUrl
+    }
+    return `https://generativelanguage.googleapis.com/v1/models/${modelName}:generateContent?key=${apikey}`
+  },
   buildBody: (modelName, messages, config, providerOptions) => {
     const system = messages.find((m) => m.role === 'system')?.content
     const contents = messages
@@ -243,7 +247,7 @@ const dashscope = {
   }),
   // International users should use dashscope-intl.aliyuncs.com
   // China users can use dashscope.aliyuncs.com
-  url: () => 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions',
+  url: (modelName, apikey, gatewayUrl) => gatewayUrl || 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions',
   buildBody: (modelName, messages, config, providerOptions) => ({
     model: modelName,
     messages,
@@ -276,7 +280,7 @@ const deepseek = {
     Authorization: `Bearer ${apikey}`,
     'Content-Type': 'application/json',
   }),
-  url: () => 'https://api.deepseek.com/chat/completions',
+  url: (modelName, apikey, gatewayUrl) => gatewayUrl || 'https://api.deepseek.com/chat/completions',
   buildBody: (modelName, messages, config, providerOptions) => ({
     model: modelName,
     messages,
@@ -298,9 +302,85 @@ const deepseek = {
   }),
 }
 
+/** @type {ProviderAdapter} */
+const mistral = {
+  headers: (apikey) => ({
+    Authorization: `Bearer ${apikey}`,
+    'Content-Type': 'application/json',
+    Accept: 'application/json',
+  }),
+  url: (modelName, apikey, gatewayUrl) => gatewayUrl || 'https://api.mistral.ai/v1/chat/completions',
+  buildBody: (modelName, messages, config, providerOptions) => ({
+    model: modelName,
+    messages,
+    ...config,
+    ...providerOptions,
+  }),
+  extractText: (data) => {
+    const content = data.choices?.[0]?.message?.content
+    if (!content) {
+      throw new Error('Mistral response missing content')
+    }
+    return content
+  },
+  extractUsage: (data) => ({
+    inputTokens: data.usage?.prompt_tokens ?? 0,
+    outputTokens: data.usage?.completion_tokens ?? 0,
+    cacheTokens: 0,
+    reasoningTokens: 0,
+  }),
+}
+
+/** @type {ProviderAdapter} */
+const ollama = {
+  headers: (apikey) => ({
+    'Content-Type': 'application/json',
+    ...(apikey && { Authorization: `Bearer ${apikey}` }),
+  }),
+  url: (modelName, apikey, gatewayUrl) => {
+    if (gatewayUrl) {
+      return gatewayUrl
+    }
+    // Warn about localhost default in development
+    console.warn('[ai-client] Ollama using default localhost URL (http://localhost:11434). Set gatewayUrl in createAi() for production.')
+    return 'http://localhost:11434/api/chat'
+  },
+  buildBody: (modelName, messages, config, providerOptions) => {
+    // Ollama uses snake_case options
+    const options = {}
+    if (config.temperature !== undefined) options.temperature = config.temperature
+    if (config.top_p !== undefined) options.top_p = config.top_p
+    if (config.top_k !== undefined) options.top_k = config.top_k
+    if (config.num_predict !== undefined) options.num_predict = config.num_predict
+    if (config.seed !== undefined) options.seed = config.seed
+    if (config.stop !== undefined) options.stop = config.stop
+    
+    return {
+      model: modelName,
+      messages,
+      stream: false,
+      ...providerOptions,
+      ...(Object.keys(options).length > 0 && { options }),
+    }
+  },
+  extractText: (data) => {
+    const content = data.message?.content
+    if (!content) {
+      throw new Error('Ollama response missing content')
+    }
+    return content
+  },
+  extractUsage: (data) => ({
+    inputTokens: data.prompt_eval_count ?? 0,
+    outputTokens: data.eval_count ?? 0,
+    cacheTokens: 0,
+    reasoningTokens: 0,
+  }),
+}
+
 /** @type {Record<string, ProviderAdapter>} */
 const ADAPTERS = {
-  openai, anthropic, google, dashscope, deepseek,
+  openai, anthropic, google, dashscope, deepseek, mistral, ollama,
 }
 
 /**

package/src/registry.js

@@ -4,7 +4,8 @@
  * Default models are loaded automatically from ./models.js at import time.
  * Users can modify the registry via addModels() and setModels().
  *
- * This module provides O(1) lookups at runtime via a Map indexed by model ID.
+ * This module provides O(1) lookups at runtime via a Map.
+ * Models can be looked up by name, or by provider/name format.
  *
  * `supportedParams` is optional per record. When absent, the provider's
  * default param set is used.
@@ -29,6 +30,7 @@ import { DEFAULT_MODELS } from './models.js'
  * @property {number} max_out               - Max output tokens
  * @property {boolean} enable
  * @property {string[]} [supportedParams]   - Canonical param names; falls back to provider default
+ * @property {Record<string, import('./coerce.js').ParamOverride>} [paramOverrides] - Model-specific param overrides
  */
 
 /**
@@ -43,16 +45,123 @@ export const PROVIDER_DEFAULT_PARAMS = {
   google: ['temperature', 'maxTokens', 'topP', 'topK', 'seed', 'stop'],
   dashscope: ['temperature', 'maxTokens', 'topP', 'topK', 'stop'],
   deepseek: ['temperature', 'maxTokens', 'topP', 'frequencyPenalty', 'presencePenalty', 'stop'],
+  mistral: ['temperature', 'maxTokens', 'topP', 'randomSeed', 'stop'],
+  ollama: ['temperature', 'maxTokens', 'topP', 'topK', 'seed', 'stop'],
 }
 
 /** @type {ProviderId[]} */
-const VALID_PROVIDERS = ['openai', 'anthropic', 'google', 'dashscope', 'deepseek']
+const VALID_PROVIDERS = ['openai', 'anthropic', 'google', 'dashscope', 'deepseek', 'mistral', 'ollama']
+
+/**
+ * Creates a new registry instance with the given models
+ * @param {import('./models.js').ModelRecord[]} [initialModels] - Initial models to load (defaults to DEFAULT_MODELS)
+ * @returns {{
+ *   getModel: (modelId: string) => { record: ModelRecord, supportedParams: string[], paramOverrides: Record<string, import('./coerce.js').ParamOverride> },
+ *   listModels: () => ModelRecord[],
+ *   addModels: (models: ModelRecord[]) => void,
+ *   setModels: (models: ModelRecord[]) => void
+ * }}
+ */
+export const createRegistry = (initialModels = DEFAULT_MODELS) => {
+  /** @type {Map<string, ModelRecord>} */
+  let REGISTRY = new Map(initialModels.map((model) => {
+    const normalized = normalizeModelRecord(model)
+    return [normalized.id, normalized]
+  }))
+
+  /**
+   * Looks up a model by provider/name format.
+   * @param {string} modelId - Model in 'provider/name' format
+   * @returns {{ record: ModelRecord, supportedParams: string[], paramOverrides: Record<string, import('./coerce.js').ParamOverride> }}
+   */
+  const getModel = (modelId) => {
+    if (!modelId.includes('/')) {
+      const available = [...REGISTRY.values()].map(m => `${m.provider}/${m.name}`).join(', ')
+      throw new Error(`Model must be in 'provider/name' format. Got: "${modelId}". Available: ${available}`)
+    }
+
+    const parts = modelId.split('/')
+    if (parts.length !== 2) {
+      const available = [...REGISTRY.values()].map(m => `${m.provider}/${m.name}`).join(', ')
+      throw new Error(`Model must be in 'provider/name' format. Got: "${modelId}". Available: ${available}`)
+    }
+
+    const [provider, name] = parts
+
+    for (const m of REGISTRY.values()) {
+      if (m.name === name && m.provider === provider) {
+        const record = m
+
+        if (!record.enable) {
+          throw new Error(`Model "${record.provider}/${record.name}" is currently disabled.`)
+        }
+
+        const supportedParams = record.supportedParams ?? PROVIDER_DEFAULT_PARAMS[record.provider]
+        const paramOverrides = record.paramOverrides ?? {}
+
+        return {
+          record, supportedParams, paramOverrides,
+        }
+      }
+    }
+
+    const available = [...REGISTRY.values()].map(m => `${m.provider}/${m.name}`).join(', ')
+    throw new Error(`Unknown model "${modelId}". Available: ${available}`)
+  }
+
+  /**
+   * Returns all enabled model records.
+   * @returns {ModelRecord[]}
+   */
+  const listModels = () =>
+    [...REGISTRY.values()].filter((m) => m.enable)
+
+  /**
+   * Adds one or more models to the registry.
+   * @param {ModelRecord[]} models - Array of model records to add
+   */
+  const addModels = (models) => {
+    if (!Array.isArray(models)) {
+      throw new Error(`addModels expects an array. Got: ${typeof models}`)
+    }
+
+    models.forEach((model, index) => {
+      validateModelRecord(model, index)
+    })
+
+    models.forEach((model) => {
+      const normalized = normalizeModelRecord(model)
+      REGISTRY.set(normalized.id, normalized)
+    })
+  }
+
+  /**
+   * Replaces the entire registry with a new list of models.
+   * @param {ModelRecord[]} models - Array of model records
+   */
+  const setModels = (models) => {
+    if (!Array.isArray(models)) {
+      throw new Error(`setModels expects an array. Got: ${typeof models}`)
+    }
+
+    models.forEach((model, index) => {
+      validateModelRecord(model, index)
+    })
+
+    REGISTRY = new Map(models.map((model) => {
+      const normalized = normalizeModelRecord(model)
+      return [normalized.id, normalized]
+    }))
+  }
+
+  return { getModel, listModels, addModels, setModels }
+}
 
 /** @type {Map<string, ModelRecord>} */
 let REGISTRY = new Map()
 
 /**
- * Initializes the registry with default models.
+ * Initializes the global registry with default models.
  * Called automatically at module import.
  */
 const initRegistry = () => {
@@ -72,34 +181,29 @@ initRegistry()
 const validateModelRecord = (model, index) => {
   const errors = []
 
-  // Check required string fields
-  if (!model.id || typeof model.id !== 'string') {
-    errors.push('"id" must be a non-empty string')
-  }
-
+  // Only name and provider are required
   if (!model.name || typeof model.name !== 'string') {
     errors.push('"name" must be a non-empty string')
   }
 
-  // Check provider is valid
   if (!model.provider || typeof model.provider !== 'string') {
     errors.push('"provider" must be a string')
   } else if (!VALID_PROVIDERS.includes(model.provider)) {
     errors.push(`"provider" must be one of: ${VALID_PROVIDERS.join(', ')}. Got: "${model.provider}"`)
   }
 
-  // Check required number fields (must be non-negative)
+  // Check optional number fields if present (must be non-negative)
   const numberFields = ['input_price', 'output_price', 'cache_price', 'max_in', 'max_out']
   for (const field of numberFields) {
-    if (typeof model[field] !== 'number') {
+    if (model[field] !== undefined && typeof model[field] !== 'number') {
       errors.push(`"${field}" must be a number`)
-    } else if (model[field] < 0) {
+    } else if (model[field] !== undefined && model[field] < 0) {
       errors.push(`"${field}" must be non-negative, got: ${model[field]}`)
     }
   }
 
-  // Check enable is boolean
-  if (typeof model.enable !== 'boolean') {
+  // Check optional enable if present
+  if (model.enable !== undefined && typeof model.enable !== 'boolean') {
     errors.push('"enable" must be a boolean')
   }
 
@@ -116,40 +220,123 @@ const validateModelRecord = (model, index) => {
     }
   }
 
+  // Check optional paramOverrides if present
+  if (model.paramOverrides !== undefined) {
+    if (typeof model.paramOverrides !== 'object' || model.paramOverrides === null || Array.isArray(model.paramOverrides)) {
+      errors.push('"paramOverrides" must be an object')
+    } else {
+      for (const [param, override] of Object.entries(model.paramOverrides)) {
+        if (typeof override !== 'object' || override === null) {
+          errors.push(`"paramOverrides.${param}" must be an object`)
+        } else {
+          // Check that override has at least one valid property
+          const validKeys = ['fixedValue', 'supportedValues', 'range']
+          const hasValidKey = Object.keys(override).some((k) => validKeys.includes(k))
+          if (!hasValidKey) {
+            errors.push(`"paramOverrides.${param}" must have at least one of: ${validKeys.join(', ')}`)
+          }
+          // Validate fixedValue type
+          if (override.fixedValue !== undefined && typeof override.fixedValue !== 'number') {
+            errors.push(`"paramOverrides.${param}.fixedValue" must be a number`)
+          }
+          // Validate supportedValues type
+          if (override.supportedValues !== undefined) {
+            if (!Array.isArray(override.supportedValues)) {
+              errors.push(`"paramOverrides.${param}.supportedValues" must be an array`)
+            } else {
+              override.supportedValues.forEach((v, i) => {
+                if (typeof v !== 'number') {
+                  errors.push(`"paramOverrides.${param}.supportedValues[${i}]" must be a number`)
+                }
+              })
+            }
+          }
+          // Validate range type
+          if (override.range !== undefined) {
+            if (typeof override.range !== 'object' || override.range === null) {
+              errors.push(`"paramOverrides.${param}.range" must be an object`)
+            } else if (typeof override.range.min !== 'number' || typeof override.range.max !== 'number') {
+              errors.push(`"paramOverrides.${param}.range" must have numeric min and max`)
+            }
+          }
+        }
+      }
+    }
+  }
+
   if (errors.length > 0) {
     throw new Error(`Invalid model record at index ${index}: ${errors.join('; ')}`)
   }
 }
 
 /**
- * Looks up a model by ID, validates it is enabled, and resolves its
- * effective supported params (record-level override or provider default).
+ * Normalizes a model record by setting defaults for missing fields.
+ * Generates id from provider and name if not provided.
  *
- * @param {string} modelId
- * @returns {{ record: ModelRecord, supportedParams: string[] }}
- * @throws {Error} When the model is not found or is disabled
+ * @param {Object} model - The model record to normalize
+ * @returns {ModelRecord} Normalized model record
  */
-export const getModel = (modelId) => {
-  const record = REGISTRY.get(modelId)
+const normalizeModelRecord = (model) => {
+  return {
+    id: model.id || `${model.provider}_${model.name}`,
+    name: model.name,
+    provider: model.provider,
+    input_price: model.input_price ?? 0,
+    output_price: model.output_price ?? 0,
+    cache_price: model.cache_price ?? 0,
+    max_in: model.max_in ?? 32000,
+    max_out: model.max_out ?? 8000,
+    enable: model.enable ?? true,
+    ...(model.supportedParams !== undefined && { supportedParams: model.supportedParams }),
+    ...(model.paramOverrides !== undefined && { paramOverrides: model.paramOverrides }),
+  }
+}
 
-  if (!record) {
-    const available = [...REGISTRY.keys()].join(', ')
-    throw new Error(`Unknown model "${modelId}". Available: ${available}`)
+/**
+ * Gets a model from the global registry (for backward compatibility).
+ * For isolated registries, use the getModel from createRegistry() instead.
+ *
+ * @param {string} modelId - Model in 'provider/name' format
+ * @returns {{ record: ModelRecord, supportedParams: string[], paramOverrides: Record<string, import('./coerce.js').ParamOverride> }}
+ */
+export const getModel = (modelId) => {
+  if (!modelId.includes('/')) {
+    const available = [...REGISTRY.values()].map(m => `${m.provider}/${m.name}`).join(', ')
+    throw new Error(`Model must be in 'provider/name' format. Got: "${modelId}". Available: ${available}`)
   }
 
-  if (!record.enable) {
-    throw new Error(`Model "${modelId}" is currently disabled.`)
+  const parts = modelId.split('/')
+  if (parts.length !== 2) {
+    const available = [...REGISTRY.values()].map(m => `${m.provider}/${m.name}`).join(', ')
+    throw new Error(`Model must be in 'provider/name' format. Got: "${modelId}". Available: ${available}`)
   }
 
-  const supportedParams = record.supportedParams ?? PROVIDER_DEFAULT_PARAMS[record.provider]
+  const [provider, name] = parts
 
-  return {
-    record, supportedParams,
+  for (const m of REGISTRY.values()) {
+    if (m.name === name && m.provider === provider) {
+      const record = m
+
+      if (!record.enable) {
+        throw new Error(`Model "${record.provider}/${record.name}" is currently disabled.`)
+      }
+
+      const supportedParams = record.supportedParams ?? PROVIDER_DEFAULT_PARAMS[record.provider]
+      const paramOverrides = record.paramOverrides ?? {}
+
+      return {
+        record, supportedParams, paramOverrides,
+      }
+    }
   }
+
+  const available = [...REGISTRY.values()].map(m => `${m.provider}/${m.name}`).join(', ')
+  throw new Error(`Unknown model "${modelId}". Available: ${available}`)
 }
 
 /**
- * Returns all enabled model records.
+ * Returns all enabled model records from the global registry.
+ * For isolated registries, use the listModels from createRegistry() instead.
  *
  * @returns {ModelRecord[]}
  */
@@ -157,44 +344,43 @@ export const listModels = () =>
   [...REGISTRY.values()].filter((m) => m.enable)
 
 /**
- * Adds one or more models to the registry.
- * Existing models with the same ID are overwritten.
+ * Adds one or more models to the global registry.
+ * For isolated registries, use the addModels from createRegistry() instead.
  *
  * @param {ModelRecord[]} models - Array of model records to add
- * @throws {Error} When models is not an array or contains invalid records
  */
 export const addModels = (models) => {
   if (!Array.isArray(models)) {
     throw new Error(`addModels expects an array. Got: ${typeof models}`)
   }
 
-  // Validate each model record
   models.forEach((model, index) => {
     validateModelRecord(model, index)
   })
 
-  // Add models to the registry
   models.forEach((model) => {
-    REGISTRY.set(model.id, model)
+    const normalized = normalizeModelRecord(model)
+    REGISTRY.set(normalized.id, normalized)
   })
 }
 
 /**
- * Replaces the entire model registry with a new list of models.
- * Use this to load models from a CMS or other external source.
+ * Replaces the entire global registry with a new list of models.
+ * For isolated registries, use the setModels from createRegistry() instead.
  *
  * @param {ModelRecord[]} models - Array of model records
- * @throws {Error} When models is not an array or contains invalid records
  */
 export const setModels = (models) => {
   if (!Array.isArray(models)) {
     throw new Error(`setModels expects an array. Got: ${typeof models}`)
   }
 
-  // Validate each model record strictly
   models.forEach((model, index) => {
     validateModelRecord(model, index)
   })
 
-  REGISTRY = new Map(models.map((model) => [model.id, model]))
+  REGISTRY = new Map(models.map((model) => {
+    const normalized = normalizeModelRecord(model)
+    return [normalized.id, normalized]
+  }))
 }