@pwshub/aisdk 0.0.1

package/src/errors.js

@@ -0,0 +1,106 @@
+/**
+ * @fileoverview Structured error types for the AI client.
+ *
+ * Distinguishes between two categories of failure:
+ *
+ * - `ProviderError`  — transient or capacity issues on the provider side
+ *                      (5xx, 429). Safe to retry with same or fallback model.
+ *
+ * - `InputError`     — request was rejected due to bad input or auth
+ *                      (400, 401, 403, 422). Retrying will not help;
+ *                      do NOT attempt fallback for these.
+ *
+ * Callers can use `instanceof` to decide retry/fallback strategy:
+ *
+ * @example
+ * try {
+ *   const result = await ai.ask({ model: 'gpt-4o', prompt: '...' })
+ * } catch (err) {
+ *   if (err instanceof ProviderError) {
+ *     // safe to retry or fallback to another model
+ *   } else if (err instanceof InputError) {
+ *     // bad request — fix the input, do not retry
+ *   }
+ * }
+ */
+
+/**
+ * Thrown when the provider returns a transient or server-side error.
+ * HTTP 429 (rate limit) and 5xx responses produce this error.
+ * Safe to retry or fall back to another model.
+ */
+export class ProviderError extends Error {
+  /**
+   * @param {string} message
+   * @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.raw]         - Raw response body from provider
+   */
+  constructor(message, {
+    status, provider, model, raw,
+  } = {}) {
+    super(message)
+    this.name = 'ProviderError'
+    this.status = status
+    this.provider = provider
+    this.model = model
+    this.raw = raw
+  }
+}
+
+/**
+ * Thrown when the provider rejects the request due to invalid input or auth.
+ * HTTP 400, 401, 403, 422 responses produce this error.
+ * Retrying or falling back will NOT resolve this — the input must be fixed.
+ */
+export class InputError extends Error {
+  /**
+   * @param {string} message
+   * @param {object} meta
+   * @param {number} meta.status
+   * @param {string} meta.provider
+   * @param {string} meta.model
+   * @param {string} [meta.raw]
+   */
+  constructor(message, {
+    status, provider, model, raw,
+  } = {}) {
+    super(message)
+    this.name = 'InputError'
+    this.status = status
+    this.provider = provider
+    this.model = model
+    this.raw = raw
+  }
+}
+
+/**
+ * HTTP status codes that indicate a provider-side transient failure.
+ * These are safe to retry or fall back on.
+ * @type {Set<number>}
+ */
+export const PROVIDER_ERROR_STATUSES = new Set([429, 500, 502, 503, 504])
+
+/**
+ * Classifies an HTTP response into ProviderError or InputError and throws it.
+ *
+ * @param {Response} res
+ * @param {string} provider
+ * @param {string} model
+ * @returns {Promise<never>}
+ */
+export const throwHttpError = async (res, provider, model) => {
+  const raw = await res.text()
+  const meta = {
+    status: res.status, provider, model, raw,
+  }
+  const message = `${provider}/${model} responded with HTTP ${res.status}`
+
+  if (PROVIDER_ERROR_STATUSES.has(res.status)) {
+    throw new ProviderError(message, meta)
+  }
+
+  throw new InputError(message, meta)
+}

package/src/index.js

@@ -0,0 +1,269 @@
+/**
+ * @fileoverview Thin AI client — single unified interface for text generation.
+ *
+ * @example Basic usage
+ * import { createAi } from '@pwshub/aisdk'
+ *
+ * const ai = createAi()
+ * const result = await ai.ask({
+ *   model: 'claude-sonnet-4-20250514',
+ *   apikey: 'your-api-key',
+ *   prompt: 'What is the capital of Vietnam?',
+ *   temperature: 0.5,
+ * })
+ * console.log(result.text)
+ * console.log(result.usage) // { inputTokens, outputTokens, cacheTokens, estimatedCost }
+ *
+ * @example With fallbacks
+ * const result = await ai.ask({
+ *   model: 'gpt-4o',
+ *   apikey: 'your-openai-key',
+ *   prompt: '...',
+ *   fallbacks: ['gpt-4o-mini', 'claude-haiku-4-5-20251001'],
+ * })
+ * if (result.model !== 'gpt-4o') {
+ *   console.warn('Fell back to', result.model)
+ * }
+ *
+ * @example Google provider-specific options
+ * const result = await ai.ask({
+ *   model: 'gemini-2.0-flash',
+ *   apikey: 'your-google-key',
+ *   prompt: '...',
+ *   providerOptions: {
+ *     safetySettings: [
+ *       { category: 'HARM_CATEGORY_HARASSMENT', threshold: 'BLOCK_NONE' },
+ *     ],
+ *     thinkingConfig: { thinkingBudget: 1024 },
+ *   },
+ * })
+ *
+ */
+
+import {
+  getModel, listModels, setModels,
+} from './registry.js'
+import { normalizeConfig } from './config.js'
+import { coerceConfig } from './coerce.js'
+import { getAdapter } from './providers.js'
+import {
+  ProviderError, InputError, throwHttpError,
+} from './errors.js'
+import { validateAskOptions } from './validation.js'
+
+export {
+  ProviderError, InputError,
+}
+
+/**
+ * @typedef {Object} AiOptions
+ * @property {string} [gatewayUrl] - Optional AI gateway URL override
+ */
+
+/**
+ * @typedef {Object} AskParams
+ * @property {string} model                       - Model ID (must be registered via setModels())
+ * @property {string} apikey                      - API key for the provider
+ * @property {string} prompt                      - The user message
+ * @property {string} [system]                    - Optional system prompt
+ * @property {string[]} [fallbacks]               - Ordered list of fallback model IDs
+ * @property {Record<string, unknown>} [providerOptions] - Provider-specific options merged into body
+ * @property {number} [temperature]
+ * @property {number} [maxTokens]
+ * @property {number} [topP]
+ * @property {number} [topK]
+ * @property {number} [frequencyPenalty]
+ * @property {number} [presencePenalty]
+ */
+
+/**
+ * @typedef {Object} Usage
+ * @property {number} inputTokens
+ * @property {number} outputTokens
+ * @property {number} cacheTokens
+ * @property {number} estimatedCost   - In USD, based on models.json pricing
+ */
+
+/**
+ * @typedef {Object} AskResult
+ * @property {string} text
+ * @property {string} model           - The model that actually responded (may differ if fallback was used)
+ * @property {Usage} usage
+ */
+
+/**
+ * Picks generation config keys from AskParams, dropping routing params.
+ * @param {AskParams} params
+ * @returns {import('./config.js').GenerationConfig}
+ */
+const extractGenConfig = (params) => {
+  const keys = ['temperature', 'maxTokens', 'topP', 'topK', 'frequencyPenalty', 'presencePenalty']
+  return Object.fromEntries(
+    keys.filter((k) => params[k] !== undefined).map((k) => [k, params[k]])
+  )
+}
+
+/**
+ * Calculates estimated cost in USD from token counts and model pricing.
+ *
+ * @param {import('./registry.js').RawUsage} usage
+ * @param {import('./registry.js').ModelRecord} record
+ * @returns {number}
+ */
+const calcCost = (usage, record) => {
+  const M = 1_000_000
+  const inputCost = (usage.inputTokens / M) * record.input_price
+  const outputCost = (usage.outputTokens / M) * record.output_price
+  const cacheCost = (usage.cacheTokens / M) * record.cache_price
+
+  // Round to 8 decimal places to avoid floating point noise
+  return Math.round((inputCost + outputCost + cacheCost) * 1e8) / 1e8
+}
+
+/**
+ * Sends a single request to a provider. No retry logic — throws structured
+ * errors so the caller (ask) can decide how to handle them.
+ *
+ * @param {string} modelId
+ * @param {AskParams} params
+ * @param {string} [gatewayUrl]
+ * @returns {Promise<AskResult>}
+ * @throws {ProviderError} On 429 / 5xx — safe to retry or fallback
+ * @throws {InputError} On 4xx — do not retry, fix the input
+ */
+const callModel = async (modelId, params, gatewayUrl) => {
+  const {
+    record, supportedParams,
+  } = getModel(modelId)
+  const {
+    provider: providerId, name: modelName,
+  } = record
+
+  const { apikey } = params
+  const adapter = getAdapter(providerId)
+
+  const genConfig = extractGenConfig(params)
+
+  // Coerce values to provider's acceptable ranges (clamp, don't throw)
+  const coerced = coerceConfig(genConfig, providerId)
+
+  // Normalize to wire format
+  const normalizedConfig = normalizeConfig(coerced, providerId, supportedParams, modelId)
+
+  const {
+    prompt, system, providerOptions = {},
+  } = params
+
+  /** @type {import('./providers.js').Message[]} */
+  const messages = [
+    ...(system ? [{
+      role: 'system', content: system,
+    }] : []),
+    {
+      role: 'user', content: prompt,
+    },
+  ]
+
+  const url = gatewayUrl ?? adapter.url(modelName, apikey)
+  const body = adapter.buildBody(modelName, messages, normalizedConfig, providerOptions)
+
+  let res
+  try {
+    res = await fetch(url, {
+      method: 'POST',
+      headers: adapter.headers(apikey),
+      body: JSON.stringify(body),
+    })
+  } catch (networkErr) {
+    // Network-level failure (DNS, connection refused) — treat as provider error
+    throw new ProviderError(`Network error calling ${providerId}/${modelId}: ${networkErr.message}`, {
+      status: 0,
+      provider: providerId,
+      model: modelId,
+    })
+  }
+
+  if (!res.ok) {
+    await throwHttpError(res, providerId, modelId)
+  }
+
+  const data = await res.json()
+  const rawUsage = adapter.extractUsage(data)
+
+  /** @type {Usage} */
+  const usage = {
+    ...rawUsage,
+    estimatedCost: calcCost(rawUsage, record),
+  }
+
+  return {
+    text: adapter.extractText(data),
+    model: modelId,
+    usage,
+  }
+}
+
+/**
+ * Creates a thin AI client.
+ *
+ * No internal retry — the caller controls retry strategy and can track
+ * attempt counts and errors externally. Fallbacks are provider-error-only:
+ * input errors (bad request, auth) are thrown immediately without trying
+ * fallback models.
+ *
+ * @param {AiOptions} [opts={}]
+ * @returns {{ ask: (params: AskParams) => Promise<AskResult>, listModels: () => import('./registry.js').ModelRecord[] }}
+ */
+export const createAi = (opts = {}) => {
+  const { gatewayUrl } = opts
+
+  /**
+   * Sends a text generation request, with optional fallback chain.
+   * Retrying is the caller's responsibility.
+   *
+   * @param {AskParams} params
+   * @returns {Promise<AskResult>}
+   * @throws {ProviderError} When all models in the chain fail with provider errors
+   * @throws {InputError} Immediately, without trying fallbacks
+   */
+  const ask = async (params) => {
+    // Validate input structure and types
+    try {
+      validateAskOptions(params)
+    } catch (error) {
+      throw new InputError('Invalid options', {
+        status: 400,
+        provider: 'client',
+        model: params.model || 'unknown',
+        raw: error.message,
+      })
+    }
+
+    const chain = [params.model, ...(params.fallbacks ?? [])]
+    let lastProviderError
+
+    for (const modelId of chain) {
+      try {
+        return await callModel(modelId, params, gatewayUrl)
+      } catch (err) {
+        if (err instanceof InputError) {
+          // Input errors are not fallback-able — rethrow immediately
+          throw err
+        }
+        // ProviderError — log and try next model in chain
+        console.warn(
+          `[ai-client] ${err.message}. ${modelId === chain.at(-1) ? 'No more fallbacks.' : 'Trying next fallback...'}`
+        )
+        lastProviderError = err
+      }
+    }
+
+    throw lastProviderError
+  }
+
+  return {
+    ask, listModels,
+  }
+}
+
+export { setModels }

package/src/providers.js

@@ -0,0 +1,249 @@
+/**
+ * @fileoverview Provider adapters — headers, URL, request body, response parsing.
+ *
+ * Each adapter also implements `extractUsage()` to pull token counts from the
+ * raw response. Field names differ per provider; we normalize to canonical names.
+ *
+ * `providerOptions` is an escape hatch for provider-specific features that
+ * cannot be generalized (e.g. Google's safetySettings, thinkingConfig).
+ * Its contents are merged directly into the request body.
+ */
+
+/**
+ * @typedef {'openai'|'anthropic'|'google'|'dashscope'|'deepseek'} ProviderId
+ */
+
+/**
+ * @typedef {Object} Message
+ * @property {'user'|'assistant'|'system'} role
+ * @property {string} content
+ */
+
+/**
+ * @typedef {Object} RawUsage
+ * @property {number} inputTokens
+ * @property {number} outputTokens
+ * @property {number} cacheTokens   - 0 when not applicable
+ */
+
+/**
+ * @typedef {Object} ProviderAdapter
+ * @property {(apikey: string) => Record<string, string>} headers
+ * @property {(modelName: string, apikey: string) => string} url
+ * @property {(modelName: string, messages: Message[], config: Record<string, unknown>, providerOptions: Record<string, unknown>) => Record<string, unknown>} buildBody
+ * @property {(data: Record<string, unknown>) => string} extractText
+ * @property {(data: Record<string, unknown>) => RawUsage} extractUsage
+ */
+
+/** @type {ProviderAdapter} */
+const openai = {
+  headers: (apikey) => ({
+    Authorization: `Bearer ${apikey}`,
+    'Content-Type': 'application/json',
+  }),
+  url: () => 'https://api.openai.com/v1/chat/completions',
+  buildBody: (modelName, messages, config, providerOptions) => ({
+    model: modelName,
+    messages,
+    n: 1,
+    ...config,
+    ...providerOptions,
+  }),
+  extractText: (data) => {
+    const choice = data.choices?.[0]
+    if (!choice) {
+      throw new Error(`OpenAI response missing choices. Full response: ${JSON.stringify(data)}`)
+    }
+
+    const message = choice.message
+    if (!message) {
+      throw new Error(`OpenAI response missing message. Full response: ${JSON.stringify(data)}`)
+    }
+
+    // Reasoning models (o1, o3, gpt-5) may return content differently
+    // Try standard content first, then reasoning_content
+    if (message.content) {
+      return message.content
+    }
+
+    // Some reasoning models use reasoning_content
+    if (message.reasoning_content) {
+      return message.reasoning_content
+    }
+
+    // Fallback: check for any content-like field
+    for (const key of Object.keys(message)) {
+      if (key.includes('content') && typeof message[key] === 'string') {
+        return message[key]
+      }
+    }
+
+    throw new Error(`OpenAI response missing content. Message: ${JSON.stringify(message)}`)
+  },
+  extractUsage: (data) => ({
+    inputTokens: data.usage?.prompt_tokens ?? 0,
+    outputTokens: data.usage?.completion_tokens ?? 0,
+    cacheTokens: data.usage?.prompt_tokens_details?.cached_tokens ?? 0,
+  }),
+}
+
+/** @type {ProviderAdapter} */
+const anthropic = {
+  headers: (apikey) => ({
+    'x-api-key': apikey,
+    'anthropic-version': '2023-06-01',
+    'Content-Type': 'application/json',
+  }),
+  url: () => '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')
+    return {
+      model: modelName,
+      messages: filtered,
+      ...(system && { system }),
+      max_tokens: 4096, // required — overridden if maxTokens was in config
+      ...config,
+      ...providerOptions,
+    }
+  },
+  extractText: (data) => {
+    // Anthropic can return multiple content blocks (text, tool_use, etc.)
+    // Concatenate all text blocks
+    const texts = data.content?.filter((c) => c.type === 'text').map((c) => c.text)
+    if (!texts || texts.length === 0) {
+      throw new Error('Anthropic response missing content')
+    }
+    return texts.join('')
+  },
+  extractUsage: (data) => ({
+    inputTokens: data.usage?.input_tokens ?? 0,
+    outputTokens: data.usage?.output_tokens ?? 0,
+    cacheTokens: data.usage?.cache_read_input_tokens ?? 0,
+  }),
+}
+
+/** @type {ProviderAdapter} */
+const google = {
+  headers: () => ({ 'Content-Type': 'application/json' }),
+  url: (modelName, apikey) =>
+    `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
+      .filter((m) => m.role !== 'system')
+      .map((m) => ({
+        role: m.role === 'assistant' ? 'model' : 'user',
+        parts: [{ text: m.content }],
+      }))
+    return {
+      contents,
+      ...(system && { systemInstruction: { parts: [{ text: system }] } }),
+      ...config, // includes nested generationConfig
+      ...providerOptions, // safetySettings, thinkingConfig, etc.
+    }
+  },
+  extractText: (data) => {
+    // Google may return empty candidates if blocked by safety filters
+    const candidate = data.candidates?.[0]
+    if (!candidate) {
+      throw new Error('Google response has no candidates (may be blocked by safety filters)')
+    }
+
+    const finishReason = candidate.finishReason
+    if (finishReason === 'SAFETY') {
+      throw new Error('Google response blocked by safety filters')
+    }
+
+    const text = candidate.content?.parts?.[0]?.text
+    if (!text) {
+      throw new Error('Google response missing content')
+    }
+    return text
+  },
+  extractUsage: (data) => ({
+    inputTokens: data.usageMetadata?.promptTokenCount ?? 0,
+    outputTokens: data.usageMetadata?.candidatesTokenCount ?? 0,
+    cacheTokens: data.usageMetadata?.cachedContentTokenCount ?? 0,
+  }),
+}
+
+/** @type {ProviderAdapter} */
+const dashscope = {
+  headers: (apikey) => ({
+    Authorization: `Bearer ${apikey}`,
+    'Content-Type': 'application/json',
+  }),
+  // 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',
+  buildBody: (modelName, messages, config, providerOptions) => ({
+    model: modelName,
+    messages,
+    ...config,
+    ...providerOptions,
+  }),
+  extractText: (data) => {
+    // OpenAI-compatible format returns choices directly
+    const content = data.choices?.[0]?.message?.content ?? data.output?.choices?.[0]?.message?.content
+    if (!content) {
+      throw new Error('DashScope response missing content')
+    }
+    return content
+  },
+  extractUsage: (data) => {
+    // OpenAI-compatible format
+    const usage = data.usage ?? data.output?.usage
+    return {
+      inputTokens: usage?.input_tokens ?? usage?.prompt_tokens ?? 0,
+      outputTokens: usage?.output_tokens ?? usage?.completion_tokens ?? 0,
+      cacheTokens: 0,
+    }
+  },
+}
+
+/** @type {ProviderAdapter} */
+const deepseek = {
+  headers: (apikey) => ({
+    Authorization: `Bearer ${apikey}`,
+    'Content-Type': 'application/json',
+  }),
+  url: () => 'https://api.deepseek.com/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('DeepSeek response missing content')
+    }
+    return content
+  },
+  extractUsage: (data) => ({
+    inputTokens: data.usage?.prompt_tokens ?? 0,
+    outputTokens: data.usage?.completion_tokens ?? 0,
+    cacheTokens: 0,
+  }),
+}
+
+/** @type {Record<string, ProviderAdapter>} */
+const ADAPTERS = {
+  openai, anthropic, google, dashscope, deepseek,
+}
+
+/**
+ * Returns the provider adapter for a given provider ID.
+ * @param {string} providerId
+ * @returns {ProviderAdapter}
+ * @throws {Error}
+ */
+export const getAdapter = (providerId) => {
+  const adapter = ADAPTERS[providerId]
+  if (!adapter) {
+    throw new Error(`No adapter found for provider: "${providerId}"`)
+  }
+  return adapter
+}