mohdel 0.90.0

package/src/lib/common.js

@@ -0,0 +1,208 @@
+import { join } from 'path'
+import { existsSync } from 'fs'
+import { readFile, writeFile, mkdir, copyFile, stat } from 'fs/promises'
+import envPaths from 'env-paths'
+import { validate, stripComputed } from './schema.js'
+import { silent } from './logger.js'
+
+// Module-level logger — set by mohdel factory via setLogger().
+// Defaults to silent so file-load operations don't spam console when imported standalone.
+let moduleLogger = silent
+export const setLogger = (logger) => { moduleLogger = logger || silent }
+
+export const CONFIG_DIR = envPaths('mohdel', { suffix: null }).config
+export const CONFIG_PATH = join(CONFIG_DIR, 'default.json')
+export const CURATED_PATH = join(CONFIG_DIR, 'curated.json')
+export const EXCLUDED_PATH = join(CONFIG_DIR, 'excluded.json')
+export const PROVIDERS_CONFIG_PATH = join(CONFIG_DIR, 'providers.json')
+export const ENV_PATH = join(CONFIG_DIR, 'environment')
+
+const DEFAULT_CURATED = {}
+
+const DEFAULT_EXCLUDED = {}
+
+export const loadEnvFile = (envPath) => {
+  try {
+    process.loadEnvFile(envPath)
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      throw err
+    }
+  }
+}
+
+export const loadDefaultEnv = () => {
+  loadEnvFile(ENV_PATH)
+}
+
+export const getAPIKey = (envVarName) => {
+  if (process.env[envVarName]) {
+    return process.env[envVarName]
+  }
+  return null
+}
+
+const sortObjectKeys = (obj) => {
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return obj
+
+  return Object.keys(obj)
+    .sort()
+    .reduce((sorted, key) => {
+      sorted[key] = obj[key]
+      return sorted
+    }, {})
+}
+
+// 3-slot backup rotation: .prev (every save), .daily (first save of the day), .weekly (first save of the week)
+const getWeek = (ms) => {
+  const d = new Date(ms)
+  return `${d.getFullYear()}-W${String(Math.ceil((d.getDate() + new Date(d.getFullYear(), d.getMonth(), 1).getDay()) / 7)).padStart(2, '0')}-${d.getMonth()}`
+}
+
+const rotateBackup = async (filePath) => {
+  if (!existsSync(filePath)) return
+
+  const prev = filePath + '.prev'
+  const daily = filePath + '.daily'
+  const weekly = filePath + '.weekly'
+
+  try {
+    // Always: current → .prev
+    await copyFile(filePath, prev)
+
+    // First save of new day: .prev → .daily
+    const prevMtime = (await stat(prev)).mtimeMs
+    const dailyMtime = existsSync(daily) ? (await stat(daily)).mtimeMs : 0
+    if (new Date(prevMtime).toDateString() !== new Date(dailyMtime).toDateString()) {
+      await copyFile(prev, daily)
+    }
+
+    // First save of new week: .daily → .weekly
+    if (existsSync(daily)) {
+      const dMtime = (await stat(daily)).mtimeMs
+      const wMtime = existsSync(weekly) ? (await stat(weekly)).mtimeMs : 0
+      if (getWeek(dMtime) !== getWeek(wMtime)) {
+        await copyFile(daily, weekly)
+      }
+    }
+  } catch (err) {
+    moduleLogger.warn(`[mohdel:common] backup rotation failed: ${err.message}`)
+  }
+}
+
+export const BACKUP_SLOTS = ['prev', 'daily', 'weekly']
+
+const createFileOperation = (filePath, defaultValue = {}, operationType) => {
+  const loadHandler = async () => {
+    let loadedData
+    try {
+      if (!existsSync(CONFIG_DIR)) {
+        await mkdir(CONFIG_DIR, { recursive: true })
+      }
+
+      if (!existsSync(filePath)) {
+        if (defaultValue && Object.keys(defaultValue).length > 0) {
+          await writeFile(filePath, JSON.stringify(defaultValue, null, 2))
+          loadedData = JSON.parse(JSON.stringify(defaultValue))
+        } else {
+          loadedData = {}
+        }
+      } else {
+        const fileContent = await readFile(filePath, 'utf8')
+        loadedData = JSON.parse(fileContent)
+      }
+
+      if (typeof loadedData === 'object' && loadedData !== null && !Array.isArray(loadedData)) {
+        const processedData = {}
+        for (const [key, entryValue] of Object.entries(loadedData)) {
+          if (typeof entryValue !== 'object' || entryValue === null || Array.isArray(entryValue)) {
+            processedData[key] = entryValue
+            continue
+          }
+          const entry = { ...entryValue }
+          const upstreamIds = []
+          if (entry.model) {
+            upstreamIds.push(entry.model)
+          }
+          if (entry.aliases && Array.isArray(entry.aliases) && entry.aliases.length > 0) {
+            upstreamIds.push(...entry.aliases)
+          }
+          processedData[key] = { ...entry, upstreamIds }
+        }
+
+        if (operationType === 'curated models') {
+          for (const [curatedKey, entry] of Object.entries(processedData)) {
+            const issues = validate(entry, curatedKey)
+            for (const issue of issues) {
+              moduleLogger.warn(`[mohdel:schema] ${curatedKey}: ${issue.field} — ${issue.message}`)
+            }
+          }
+        }
+
+        return processedData
+      }
+
+      return loadedData
+    } catch (err) {
+      moduleLogger.warn(`[mohdel:common] failed to load ${operationType}: ${err.message}`)
+      return JSON.parse(JSON.stringify(defaultValue || {}))
+    }
+  }
+
+  const saveHandler = async (data) => {
+    try {
+      if (!existsSync(CONFIG_DIR)) {
+        await mkdir(CONFIG_DIR, { recursive: true })
+      }
+
+      await rotateBackup(filePath)
+
+      let dataToSave = data
+      if (typeof data === 'object' && data !== null && !Array.isArray(data)) {
+        const cleanedData = {}
+        for (const [key, entry] of Object.entries(data)) {
+          cleanedData[key] = (typeof entry === 'object' && entry !== null && !Array.isArray(entry))
+            ? stripComputed(entry)
+            : entry
+        }
+        dataToSave = cleanedData
+      }
+
+      const sortedData = sortObjectKeys(dataToSave)
+      await writeFile(filePath, JSON.stringify(sortedData, null, 2))
+      return true
+    } catch (err) {
+      moduleLogger.error(`[mohdel:common] failed to save ${operationType}: ${err.message}`)
+      if (operationType !== 'configuration') {
+        throw new Error(`Failed to save ${operationType}: ${err.message}`)
+      }
+      return false
+    }
+  }
+
+  return { load: loadHandler, save: saveHandler }
+}
+
+const configOps = createFileOperation(CONFIG_PATH, {}, 'configuration')
+const curatedOps = createFileOperation(CURATED_PATH, DEFAULT_CURATED, 'curated models')
+const excludedOps = createFileOperation(EXCLUDED_PATH, DEFAULT_EXCLUDED, 'excluded models')
+const providersConfigOps = createFileOperation(PROVIDERS_CONFIG_PATH, {}, 'provider config')
+
+export const getConfig = configOps.load
+export const saveConfig = configOps.save
+export const getCuratedModels = curatedOps.load
+export const saveCuratedModels = curatedOps.save
+export const getExcludedModels = excludedOps.load
+export const saveExcludedModels = excludedOps.save
+export const getProvidersConfig = providersConfigOps.load
+export const saveProvidersConfig = providersConfigOps.save
+
+export const getDefaultModelId = async () => {
+  const config = await getConfig()
+
+  if (config.defaultModel) {
+    return config.defaultModel
+  }
+
+  throw new Error('No default model configured. Run \'mo default\' to set up a default model.')
+}

package/src/lib/cooldown.js

@@ -0,0 +1,63 @@
+import { Severity, MohdelError } from './errors.js'
+import { silent } from './logger.js'
+
+const createCooldownTracker = (threshold = 3, durationMs = 60000, { logger = silent } = {}) => {
+  // key → { failCount, until, reason }
+  const entries = new Map()
+
+  const check = (key) => {
+    const entry = entries.get(key)
+    if (!entry || !entry.until) return null
+    if (Date.now() >= entry.until) {
+      entries.delete(key)
+      logger.debug({ key }, '[mohdel:cooldown] expired')
+      return null
+    }
+    return entry
+  }
+
+  const recordFailure = (key, { immediate = false, cause } = {}) => {
+    const entry = entries.get(key) || { failCount: 0, until: null, reason: null }
+    entry.failCount++
+    if (cause) entry.lastCause = cause
+    const shouldCooldown = immediate || entry.failCount >= threshold
+    if (shouldCooldown) {
+      entry.until = Date.now() + durationMs
+      entry.reason = immediate ? 'auth' : 'consecutive_failures'
+      entries.set(key, entry)
+      logger.info({
+        key,
+        reason: entry.reason,
+        failCount: entry.failCount,
+        durationMs,
+        triggeredBy: entry.lastCause || null
+      }, '[mohdel:cooldown] activated')
+      return true
+    }
+    entries.set(key, entry)
+    return false
+  }
+
+  const reset = (key) => {
+    const had = entries.has(key)
+    entries.delete(key)
+    if (had) logger.debug({ key }, '[mohdel:cooldown] reset')
+  }
+
+  const throwIfCoolingDown = (key, span) => {
+    const entry = check(key)
+    if (!entry) return
+    const secsLeft = Math.ceil((entry.until - Date.now()) / 1000)
+    logger.trace({ key, secsLeft }, '[mohdel:cooldown] fast-fail')
+    throw new MohdelError('PROVIDER_COOLDOWN', {
+      severity: Severity.WARN,
+      retryable: true,
+      detail: `Provider ${key} is in cooldown for ${secsLeft}s after ${entry.failCount} consecutive failures (${entry.reason}).`,
+      context: { provider: key, failCount: entry.failCount, reason: entry.reason, cooldownUntil: entry.until }
+    })
+  }
+
+  return { check, recordFailure, reset, throwIfCoolingDown }
+}
+
+export default createCooldownTracker

package/src/lib/creators.js

@@ -0,0 +1,71 @@
+const creators = {
+  alibaba: {
+    label: 'Alibaba',
+    logo: 'alibaba.svg',
+    description: 'Alibaba Cloud’s Qwen models target large-scale enterprise scenarios with strong multilingual and commerce-focused capabilities.'
+  },
+  bfl: {
+    label: 'Black Forest Labs',
+    logo: 'bfl.svg',
+    description: 'Black Forest Labs builds the Flux family of image generation models, delivering fast, high-quality text-to-image synthesis.'
+  },
+  anthropic: {
+    label: 'Anthropic',
+    logo: 'anthropic.svg',
+    description: 'Anthropic builds Claude models that emphasize safe reasoning, tool use, and reliable outputs for production assistants.'
+  },
+  deepseek: {
+    label: 'DeepSeek',
+    logo: 'deepseek.svg',
+    description: 'DeepSeek offers fast, cost-efficient foundation models optimized for coding, chat, and multilingual reasoning.'
+  },
+  google: {
+    label: 'Google',
+    logo: 'gemini.svg',
+    description: 'Google’s Gemini family blends multimodal understanding, coding assistance, and long-context reasoning from Google DeepMind research.'
+  },
+  kwaipilot: {
+    label: 'Kwaipilot',
+    logo: 'kwaipilot.svg',
+    description: 'Kuaishou\'s KwaiPilot team builds KAT-Coder, a MoE coding model with strong agentic and multi-step reasoning for software engineering tasks.'
+  },
+  meta: {
+    label: 'Meta',
+    logo: 'meta.svg',
+    description: 'Meta stewards the Llama ecosystem with open, widely adoptable models for chat, coding, and research.'
+  },
+  minimax: {
+    label: 'Minimax',
+    logo: 'minimax.svg',
+    description: 'Minimax offers versatile Chinese-first chat and coding models tuned for fast, cost-aware assistants and enterprise integrations.'
+  },
+  moonshotai: {
+    label: 'Moonshot AI',
+    logo: 'moonshotai.svg',
+    description: 'Moonshot AI ships fluent, Chinese-first assistants and lean models tuned for consumer chat and business workflows.'
+  },
+  openai: {
+    label: 'OpenAI',
+    logo: 'openai.svg',
+    description: 'OpenAI’s GPT and o-series models focus on broad tool-use, reasoning quality, and multimodal support across developer platforms.'
+  },
+  xai: {
+    label: 'xAI',
+    logo: 'xai.svg',
+    description: 'xAI develops Grok with real-time, web-aware chat and coding behavior aimed at terse, fast responses.'
+  },
+  xiaomi: {
+    label: 'Xiaomi',
+    logo: 'xiaomi.svg',
+    description: 'Xiaomi develops MiMo, a high-efficiency MoE reasoning model optimized for agentic coding and tool use at low inference cost.'
+  },
+  zai: {
+    label: 'Z AI',
+    logo: 'zai.svg',
+    description: 'Z AI delivers streamlined assistants with lightweight models oriented toward pragmatic productivity use cases.'
+  }
+}
+
+Object.freeze(creators)
+
+export default creators

package/src/lib/curated-cache.js

@@ -0,0 +1,146 @@
+import { getCuratedModels, saveCuratedModels } from './common.js'
+
+let curatedCache = null
+let aliasMapCache = null
+
+export const getMohdelModel = curatedKey => {
+  const [provider, ...modelParts] = curatedKey.split('/')
+  return { provider, model: modelParts.join('/') }
+}
+
+const BASE_NAME_RE = /^([^-\d]+-\d+(?:-\d+)*(?:-[a-z]+)?)/
+
+const buildAliasMap = (curatedModels) => {
+  const aliasMap = new Map()
+  const modelCountByName = new Map()
+  const parsed = []
+
+  // Pass 1: count names and cache parsed results
+  for (const fullModelId in curatedModels) {
+    const { provider, model: modelName } = getMohdelModel(fullModelId)
+    const baseMatch = modelName.match(BASE_NAME_RE)
+    const baseName = baseMatch?.[1] || null
+
+    if (baseName) modelCountByName.set(baseName, (modelCountByName.get(baseName) || 0) + 1)
+    modelCountByName.set(modelName, (modelCountByName.get(modelName) || 0) + 1)
+    parsed.push({ fullModelId, provider, modelName, baseName, entry: curatedModels[fullModelId] })
+  }
+
+  // Pass 2: build aliases + explicit aliases
+  for (const { fullModelId, provider, modelName, baseName, entry } of parsed) {
+    if (modelCountByName.get(modelName) === 1) aliasMap.set(modelName, fullModelId)
+
+    if (baseName) {
+      if (modelCountByName.get(baseName) === 1) aliasMap.set(baseName, fullModelId)
+      aliasMap.set(`${provider}/${baseName}`, fullModelId)
+    }
+
+    if (Array.isArray(entry.aliases)) {
+      for (const alias of entry.aliases) {
+        if (!aliasMap.has(alias)) aliasMap.set(alias, fullModelId)
+      }
+    }
+  }
+
+  return aliasMap
+}
+
+const expandModelAliasInternal = (modelId) => {
+  if (curatedCache[modelId]) return modelId
+  if (aliasMapCache.has(modelId)) {
+    return aliasMapCache.get(modelId)
+  }
+  return modelId
+}
+
+const ensureCuratedCache = async () => {
+  if (!curatedCache) {
+    curatedCache = await getCuratedModels()
+    aliasMapCache = buildAliasMap(curatedCache)
+  }
+  return curatedCache
+}
+
+const rebuildAliasMap = () => {
+  aliasMapCache = buildAliasMap(curatedCache || {})
+  return aliasMapCache
+}
+
+export const loadCuratedCache = ensureCuratedCache
+
+export const getCuratedCacheSnapshot = () => curatedCache
+
+export const getAliasMapSnapshot = () => aliasMapCache
+
+// Find close matches for a model ID that wasn't found.
+// Returns array of { id, label } sorted by relevance (max 5).
+export const suggestModels = (query, maxResults = 5) => {
+  if (!curatedCache) return []
+  const q = query.toLowerCase()
+  const scored = []
+
+  for (const fullId of Object.keys(curatedCache)) {
+    if (curatedCache[fullId].deprecated) continue
+    const entry = curatedCache[fullId]
+    const label = (entry.label || '').toLowerCase()
+    const id = fullId.toLowerCase()
+    const model = (entry.model || '').toLowerCase()
+
+    // Score by how well the query matches
+    let score = 0
+    if (id.includes(q)) score = 3
+    else if (model.includes(q)) score = 2.5
+    else if (label.includes(q)) score = 2
+    else {
+      // Fuzzy: check if all query segments appear somewhere
+      const terms = q.split(/[\s/\-_]+/).filter(Boolean)
+      const haystack = `${id} ${label} ${model}`
+      const matched = terms.filter(t => haystack.includes(t))
+      if (matched.length === terms.length) score = 1.5
+      else if (matched.length > 0) score = matched.length / terms.length
+    }
+
+    if (score > 0) scored.push({ id: fullId, label: entry.label || fullId, score })
+  }
+
+  scored.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id))
+  return scored.slice(0, maxResults)
+}
+
+export const expandModelAliasSync = (modelId) => {
+  if (!curatedCache || !aliasMapCache) {
+    throw new Error('Curated cache has not been loaded yet')
+  }
+  return expandModelAliasInternal(modelId)
+}
+
+export const expandModelAlias = async (modelId) => {
+  await ensureCuratedCache()
+  return expandModelAliasInternal(modelId)
+}
+
+export const persistCuratedCache = async () => {
+  if (!curatedCache) {
+    await ensureCuratedCache()
+  }
+
+  rebuildAliasMap()
+  await saveCuratedModels(curatedCache)
+  return curatedCache
+}
+
+export const overwriteCuratedCache = async (nextCache) => {
+  curatedCache = nextCache || {}
+  return persistCuratedCache()
+}
+
+export const reloadCuratedCache = async () => {
+  curatedCache = null
+  aliasMapCache = null
+  return ensureCuratedCache()
+}
+
+export const clearCuratedCache = () => {
+  curatedCache = null
+  aliasMapCache = null
+}

package/src/lib/errors.js

@@ -0,0 +1,126 @@
+export const Severity = Object.freeze({
+  TRACE: Symbol('TRACE'),
+  DEBUG: Symbol('DEBUG'),
+  INFO: Symbol('INFO'),
+  WARN: Symbol('WARN'),
+  ERROR: Symbol('ERROR'),
+  FATAL: Symbol('FATAL')
+})
+
+export const getSeverityNumber = (severitySymbol) => {
+  switch (severitySymbol) {
+    case Severity.TRACE:
+      return 1
+    case Severity.DEBUG:
+      return 5
+    case Severity.INFO:
+      return 9
+    case Severity.WARN:
+      return 13
+    case Severity.ERROR:
+      return 17
+    case Severity.FATAL:
+      return 21
+    default:
+      throw new Error(`[mohdel] unknown severity symbol: ${String(severitySymbol)}`)
+  }
+}
+
+// NOTE used to mock upstream Error
+export class APIError extends Error {
+  constructor (message, status = 500) {
+    super(message)
+    this.name = 'APIError'
+    this.status = status
+  }
+}
+
+// usually Severity at least info
+export class MohdelError extends Error {
+  constructor (
+    message,
+    { cause, severity, detail, context, component = 'inference', retryable = false, silent = false } = {}
+  ) {
+    super(message, { cause })
+    this.name = 'MohdelError'
+    this.severity = severity
+    this.detail = detail
+    this.context = context
+    this.component = component
+    this.retryable = retryable
+    this.silent = silent
+  }
+}
+
+// Convert any error to the serialized transport shape. Duck-types on
+// `detail` to distinguish typed errors (MohdelError) from plain Error.
+export const toTransportError = (err, span) => {
+  const isTyped = err.detail !== undefined
+  return {
+    message: isTyped ? err.message : 'UNEXPECTED_ERROR',
+    detail: isTyped ? err.detail : 'An unexpected error occurred',
+    trace: span?.spanContext()?.traceId,
+    component: err.component || undefined,
+    context: err.context || undefined,
+    retryable: err.retryable ?? false,
+    silent: err.silent ?? false
+  }
+}
+
+export const retryableWarn = (err, detail) => {
+  return {
+    message: 'PROVIDER_OVERLOADED',
+    severity: Severity.WARN,
+    retryable: true,
+    detail,
+    cause: err
+  }
+}
+export const reportRetryable = (err, provider, detail) => {
+  detail ||= `**An unexpected error occurred**: ${provider}'s API failed to respond. Try again or switch to a different model. If the issue persists, please contact support and provide the Trace ID.`
+  return {
+    message: 'PROVIDER_RETRYABLE_ERROR',
+    severity: Severity.ERROR,
+    detail,
+    retryable: true,
+    cause: err
+  }
+}
+
+export const reportDefault = (err, provider) => {
+  return {
+    message: 'PROVIDER_ERROR',
+    severity: Severity.ERROR,
+    detail: `**An unexpected error occurred**: ${provider}'s API failed to respond. Try switching to a different model or please contact support and provide the Trace ID.`,
+    retryable: isConnectionError(err),
+    cause: err
+  }
+}
+
+export const reportContextOverflow = (err, provider) => {
+  return {
+    message: 'CONTEXT_OVERFLOW',
+    severity: Severity.WARN,
+    detail: `The prompt exceeds ${provider}'s context limit. Reduce input or switch to a larger context model.`,
+    retryable: false,
+    cause: err
+  }
+}
+
+export function isContextOverflowMessage (errMessage) {
+  const msg = (errMessage || '').toLowerCase()
+  if (msg.includes('context_length') || msg.includes('context length')) return true
+  if (msg.includes('token limit') || msg.includes('too long') || msg.includes('too many tokens')) return true
+  if (msg.includes('maximum context') || msg.includes('prompt is too long')) return true
+  if (msg.includes('max_tokens') && msg.includes('exceed')) return true
+  return false
+}
+
+function isConnectionError (err) {
+  const code = err?.code || err?.cause?.code
+  if (code === 'ECONNRESET' || code === 'ECONNREFUSED' || code === 'ETIMEDOUT' ||
+      code === 'EPIPE' || code === 'ENOTFOUND' || code === 'UND_ERR_CONNECT_TIMEOUT') return true
+  const msg = (err?.message || '').toLowerCase()
+  if (msg.includes('fetch failed') || msg.includes('socket hang up') || msg.includes('network')) return true
+  return false
+}