@pwshub/aisdk 0.0.1

package/src/registry.js

@@ -0,0 +1,164 @@
+/**
+ * @fileoverview Model registry — in-memory store for model records.
+ *
+ * Models are loaded programmatically via setModels() from external sources
+ * (CMS, API, or local files for evaluation). This module provides O(1) lookups
+ * at runtime via a Map indexed by model ID.
+ *
+ * `supportedParams` is optional per record. When absent, the provider's
+ * default param set is used.
+ *
+ * @typedef {'openai'|'anthropic'|'google'|'dashscope'|'deepseek'} ProviderId
+ */
+
+/**
+ * Mirrors the Directus collection schema exactly.
+ * `supportedParams` is optional — added later via Directus field.
+ *
+ * @typedef {Object} ModelRecord
+ * @property {string} id
+ * @property {string} name                  - Official model name used in API calls
+ * @property {ProviderId} provider
+ * @property {number} input_price           - Per 1M tokens, USD
+ * @property {number} output_price          - Per 1M tokens, USD
+ * @property {number} cache_price           - Per 1M tokens, USD
+ * @property {number} max_in                - Max input tokens (context window)
+ * @property {number} max_out               - Max output tokens
+ * @property {boolean} enable
+ * @property {string[]} [supportedParams]   - Canonical param names; falls back to provider default
+ */
+
+/**
+ * Default supported params per provider.
+ * Used as fallback when a model record has no `supportedParams` field.
+ *
+ * @type {Record<ProviderId, string[]>}
+ */
+export const PROVIDER_DEFAULT_PARAMS = {
+  openai: ['temperature', 'maxTokens', 'topP', 'frequencyPenalty', 'presencePenalty', 'seed', 'stop'],
+  anthropic: ['temperature', 'maxTokens', 'topP', 'topK', 'stop'],
+  google: ['temperature', 'maxTokens', 'topP', 'topK', 'seed', 'stop'],
+  dashscope: ['temperature', 'maxTokens', 'topP', 'topK', 'stop'],
+  deepseek: ['temperature', 'maxTokens', 'topP', 'frequencyPenalty', 'presencePenalty', 'stop'],
+}
+
+/** @type {ProviderId[]} */
+const VALID_PROVIDERS = ['openai', 'anthropic', 'google', 'dashscope', 'deepseek']
+
+/** @type {Map<string, ModelRecord>} */
+let REGISTRY = new Map()
+
+/**
+ * Validates a single model record structure and types.
+ *
+ * @param {Object} model - The model record to validate
+ * @param {number} index - Index in the array for error messages
+ * @throws {Error} When validation fails
+ */
+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')
+  }
+
+  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)
+  const numberFields = ['input_price', 'output_price', 'cache_price', 'max_in', 'max_out']
+  for (const field of numberFields) {
+    if (typeof model[field] !== 'number') {
+      errors.push(`"${field}" must be a number`)
+    } else if (model[field] < 0) {
+      errors.push(`"${field}" must be non-negative, got: ${model[field]}`)
+    }
+  }
+
+  // Check enable is boolean
+  if (typeof model.enable !== 'boolean') {
+    errors.push('"enable" must be a boolean')
+  }
+
+  // Check optional supportedParams if present
+  if (model.supportedParams !== undefined) {
+    if (!Array.isArray(model.supportedParams)) {
+      errors.push('"supportedParams" must be an array')
+    } else {
+      model.supportedParams.forEach((param, i) => {
+        if (typeof param !== 'string') {
+          errors.push(`"supportedParams[${i}]" must be a string`)
+        }
+      })
+    }
+  }
+
+  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).
+ *
+ * @param {string} modelId
+ * @returns {{ record: ModelRecord, supportedParams: string[] }}
+ * @throws {Error} When the model is not found or is disabled
+ */
+export const getModel = (modelId) => {
+  const record = REGISTRY.get(modelId)
+
+  if (!record) {
+    const available = [...REGISTRY.keys()].join(', ')
+    throw new Error(`Unknown model "${modelId}". Available: ${available}`)
+  }
+
+  if (!record.enable) {
+    throw new Error(`Model "${modelId}" is currently disabled.`)
+  }
+
+  const supportedParams = record.supportedParams ?? PROVIDER_DEFAULT_PARAMS[record.provider]
+
+  return {
+    record, supportedParams,
+  }
+}
+
+/**
+ * Returns all enabled model records.
+ *
+ * @returns {ModelRecord[]}
+ */
+export const listModels = () =>
+  [...REGISTRY.values()].filter((m) => m.enable)
+
+/**
+ * Programmatically sets the model registry from an array of model records.
+ * Use this when loading models from a CMS or other external source instead of
+ * the built-in models.json file.
+ *
+ * @param {ModelRecord[]} models - Array of model records (same format as models.json)
+ * @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]))
+}

package/src/validation.js

@@ -0,0 +1,113 @@
+/**
+ * @fileoverview Simple validation for AI client input.
+ *
+ * Uses loose validation — only checks structure and types, not ranges.
+ * Range validation is handled by coerce.js which clamps values silently.
+ */
+
+/**
+ * @typedef {Object} AskParams
+ * @property {string} model
+ * @property {string} apikey
+ * @property {string} prompt
+ * @property {string} [system]
+ * @property {import('../index.js').Message[]} [messages]
+ * @property {number} [temperature]
+ * @property {number} [maxTokens]
+ * @property {number} [topP]
+ * @property {number} [topK]
+ * @property {number} [frequencyPenalty]
+ * @property {number} [presencePenalty]
+ * @property {number} [seed]
+ * @property {string|string[]} [stop]
+ * @property {string[]} [fallbacks]
+ * @property {Record<string, unknown>} [providerOptions]
+ */
+
+/**
+ * Validates ask() options structure and types.
+ * @param {AskParams} params
+ * @returns {void}
+ * @throws {Error}
+ */
+export const validateAskOptions = (params) => {
+  const errors = []
+
+  // Required fields
+  if (!params.model || typeof params.model !== 'string') {
+    errors.push('"model" must be a non-empty string')
+  }
+
+  if (!params.apikey || typeof params.apikey !== 'string') {
+    errors.push('"apikey" must be a non-empty string')
+  }
+
+  if (!params.prompt || typeof params.prompt !== 'string') {
+    errors.push('"prompt" must be a non-empty string')
+  }
+
+  // Optional string fields
+  if (params.system !== undefined && typeof params.system !== 'string') {
+    errors.push('"system" must be a string')
+  }
+
+  // Optional number fields
+  const numberFields = ['temperature', 'maxTokens', 'topP', 'topK', 'frequencyPenalty', 'presencePenalty', 'seed']
+  for (const field of numberFields) {
+    if (params[field] !== undefined && typeof params[field] !== 'number') {
+      errors.push(`"${field}" must be a number`)
+    }
+  }
+
+  // Optional array fields
+  if (params.messages !== undefined) {
+    if (!Array.isArray(params.messages)) {
+      errors.push('"messages" must be an array')
+    } else {
+      params.messages.forEach((msg, i) => {
+        if (!msg || typeof msg !== 'object') {
+          errors.push(`messages[${i}] must be an object`)
+        } else if (!['user', 'assistant', 'system'].includes(msg.role)) {
+          errors.push(`messages[${i}].role must be 'user', 'assistant', or 'system'`)
+        } else if (typeof msg.content !== 'string') {
+          errors.push(`messages[${i}].content must be a string`)
+        }
+      })
+    }
+  }
+
+  if (params.fallbacks !== undefined) {
+    if (!Array.isArray(params.fallbacks)) {
+      errors.push('"fallbacks" must be an array')
+    } else {
+      params.fallbacks.forEach((model, i) => {
+        if (typeof model !== 'string') {
+          errors.push(`fallbacks[${i}] must be a string`)
+        }
+      })
+    }
+  }
+
+  // stop can be string or array of strings
+  if (params.stop !== undefined) {
+    if (typeof params.stop !== 'string' && !Array.isArray(params.stop)) {
+      errors.push('"stop" must be a string or array of strings')
+    } else if (Array.isArray(params.stop)) {
+      params.stop.forEach((s, i) => {
+        if (typeof s !== 'string') {
+          errors.push(`stop[${i}] must be a string`)
+        }
+      })
+    }
+  }
+
+  // providerOptions must be an object
+  if (params.providerOptions !== undefined &&
+      (typeof params.providerOptions !== 'object' || params.providerOptions === null || Array.isArray(params.providerOptions))) {
+    errors.push('"providerOptions" must be an object')
+  }
+
+  if (errors.length > 0) {
+    throw new Error(errors.join('; '))
+  }
+}