mohdel 0.90.0

package/package.json

@@ -0,0 +1,107 @@
+{
+  "name": "mohdel",
+  "version": "0.90.0",
+  "license": "MIT",
+  "author": {
+    "name": "Christophe Le Bars",
+    "email": "clb@toort.net"
+  },
+  "description": "Self-hosted LLM gateway with an embeddable SDK. Process-isolated, OpenTelemetry-native inference across 11 providers — streaming, tools, thinking control — without orchestration. Use the Node factory in-process, or run thin-gate for fault isolation and any-language HTTP callers.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clbrge/mohdel.git"
+  },
+  "homepage": "https://github.com/clbrge/mohdel#readme",
+  "bugs": {
+    "url": "https://github.com/clbrge/mohdel/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "src/lib/index.js",
+  "exports": {
+    ".": "./src/lib/index.js",
+    "./providers": "./src/lib/providers.js",
+    "./creators": "./src/lib/creators.js",
+    "./utils": "./src/lib/utils.js",
+    "./errors": "./src/lib/errors.js",
+    "./client": "./js/client/index.js",
+    "./session": "./js/session/index.js",
+    "./session/bin": "./js/session/bin.js"
+  },
+  "imports": {
+    "#core": "./js/core/index.js",
+    "#core/*": "./js/core/*"
+  },
+  "bin": {
+    "mo": "./src/cli/index.js"
+  },
+  "files": [
+    "js",
+    "src/lib",
+    "src/cli",
+    "config",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "lint": "standard",
+    "test": "vitest run test/unit",
+    "prerelease": "npm run lint && npm run test",
+    "release": "release-it",
+    "test:provider": "vitest run test/integration/provider.test.js",
+    "test:multiturn": "vitest run test/integration/multiturn.test.js",
+    "test:vision": "vitest run test/integration/vision.test.js",
+    "test:live": "vitest run test/live"
+  },
+  "release-it": {
+    "hooks": {
+      "after:bump": "node scripts/sync-version.js"
+    },
+    "git": {
+      "commitMessage": "release: v${version}",
+      "requireUpstream": false,
+      "tagName": "v${version}",
+      "push": true
+    },
+    "npm": {
+      "publish": false
+    },
+    "github": {
+      "release": true,
+      "releaseName": "mohdel v${version}",
+      "releaseNotes": "awk '/^## \\[${version}\\]/{flag=1;next}/^## \\[/{flag=0}flag' CHANGELOG.md"
+    }
+  },
+  "optionalDependencies": {
+    "@clack/prompts": "^1.2.0",
+    "@opentelemetry/exporter-trace-otlp-grpc": "^0.215.0",
+    "@opentelemetry/sdk-node": "^0.215.0",
+    "chalk": "^5.4.0",
+    "mohdel-thin-gate-linux-x64-gnu": "0.90.0"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.90.0",
+    "@cerebras/cerebras_cloud_sdk": "^1.61.1",
+    "@google/genai": "^1.50.1",
+    "@opentelemetry/api": "^1.9.1",
+    "env-paths": "^4.0.0",
+    "groq-sdk": "^1.1.2",
+    "openai": "^6.34.0"
+  },
+  "lint-staged": {
+    "*.{js,cjs}": "standard"
+  },
+  "devDependencies": {
+    "lint-staged": "^16.4.0",
+    "release-it": "^20.0.0",
+    "standard": "^17.1.2",
+    "vitest": "^4.1.5"
+  }
+}

package/src/cli/ask.js

@@ -0,0 +1,160 @@
+import mohdel, { silent } from '../lib/index.js'
+import { loadDefaultEnv } from '../lib/common.js'
+
+const noop = () => {}
+
+export async function runAsk (args) {
+  if (args.includes('-h') || args.includes('--help')) {
+    console.log(`mohdel ask — one-shot inference, pipeable
+
+Usage:
+  mo ask <model> [prompt]              Prompt from args
+  echo "prompt" | mo ask <model>       Prompt from stdin
+  mo ask <model> "question" < file     Combined: args + stdin
+
+Options:
+  --effort <level>     Thinking effort: high, medium, low, none
+  --budget <tokens>    Output token budget
+  --json               Output full result as JSON
+  --stream             Stream output to stdout in real time
+  -v, --verbose        Show debug info on stderr (cooldown, rate limit, SDK calls)
+
+Output:
+  stdout: model output text (raw, no formatting — or JSON with --json)
+  stderr: model name + token usage summary
+
+Examples:
+  mo ask gemini/gemini-3-flash-preview "why is the sky blue"
+  cat article.txt | mo ask anthropic/claude-sonnet-4-6 "summarize this"
+  mo ask openai/gpt-5.4 --effort high "explain monads" --json | jq .cost`)
+    process.exit(0)
+  }
+
+  loadDefaultEnv()
+
+  // Parse flags
+  const flagVal = (name) => {
+    const idx = args.indexOf(name)
+    if (idx === -1) return undefined
+    const val = args[idx + 1]
+    args.splice(idx, 2)
+    return val
+  }
+  const flag = (name) => {
+    const idx = args.indexOf(name)
+    if (idx === -1) return false
+    args.splice(idx, 1)
+    return true
+  }
+
+  const json = flag('--json')
+  const stream = flag('--stream')
+  const verbose = flag('--verbose') || flag('-v')
+  const effort = flagVal('--effort')
+  const budget = flagVal('--budget')
+
+  // First remaining arg is model
+  const modelId = args[0]
+  if (!modelId) {
+    console.error('Usage: mo ask <model> [prompt]')
+    process.exit(1)
+  }
+
+  // Remaining args form the prompt
+  const promptArgs = args.slice(1).join(' ').trim()
+
+  // Read stdin if piped
+  let stdinContent = ''
+  if (!process.stdin.isTTY) {
+    const chunks = []
+    for await (const chunk of process.stdin) chunks.push(chunk)
+    stdinContent = Buffer.concat(chunks).toString('utf8').trim()
+  }
+
+  // Build prompt: args + stdin
+  const parts = [promptArgs, stdinContent].filter(Boolean)
+  const prompt = parts.join('\n\n')
+
+  if (!prompt) {
+    console.error('No prompt provided. Pass as argument or pipe via stdin.')
+    process.exit(1)
+  }
+
+  const log = verbose ? (...args) => process.stderr.write(`${args.map(a => typeof a === 'string' ? a : JSON.stringify(a)).join(' ')}\n`) : noop
+  // Verbose mode routes info+warn+error+fatal (and debug) to stderr; trace stays silent.
+  // Non-verbose: only error/fatal go to stderr (everything else silent).
+  const askLogger = {
+    ...silent,
+    debug: verbose ? log : noop,
+    info: log,
+    warn: log,
+    error: log,
+    fatal: log
+  }
+  const mo = await mohdel({ logger: askLogger })
+  let model
+  try {
+    model = mo.use(modelId)
+  } catch (err) {
+    console.error(err.message)
+    process.exit(1)
+  }
+
+  const options = {}
+  if (effort) options.outputEffort = effort
+  if (budget) options.outputBudget = parseInt(budget, 10)
+  if (stream && !json) {
+    options.realtimeHandler = (delta) => process.stdout.write(delta)
+    options.bufferOpts = { maxChars: 1, maxMs: 0 }
+  }
+
+  process.stderr.write(`${model.id}\n`)
+
+  try {
+    const result = await model.answer(prompt, options)
+    const output = typeof result === 'string' ? result : result?.output || ''
+    const tokens = typeof result === 'object' ? result : {}
+
+    if (json) {
+      console.log(JSON.stringify({
+        model: model.id,
+        output,
+        inputTokens: tokens.inputTokens || 0,
+        outputTokens: tokens.outputTokens || 0,
+        thinkingTokens: tokens.thinkingTokens || 0,
+        cost: tokens.cost ?? null,
+        status: tokens.status || 'completed'
+      }, null, 2))
+    } else if (!stream) {
+      process.stdout.write(output)
+      if (output && !output.endsWith('\n')) process.stdout.write('\n')
+    } else {
+      // Stream already wrote to stdout; ensure trailing newline
+      if (output && !output.endsWith('\n')) process.stdout.write('\n')
+    }
+
+    // Token + timing summary to stderr
+    const summary = []
+    if (tokens.inputTokens) summary.push(`${tokens.inputTokens} in`)
+    if (tokens.outputTokens) summary.push(`${tokens.outputTokens} out`)
+    if (tokens.thinkingTokens) summary.push(`${tokens.thinkingTokens} think`)
+    if (tokens.cost != null) summary.push(`$${tokens.cost.toFixed(4)}`)
+    const ts = tokens.timestamps
+    if (ts) {
+      const toMs = (a, b) => {
+        if (!a || !b) return null
+        const na = typeof a === 'bigint' ? a : BigInt(a)
+        const nb = typeof b === 'bigint' ? b : BigInt(b)
+        return Number(nb - na) / 1e6
+      }
+      const ttft = toMs(ts.start, ts.first)
+      const total = toMs(ts.start, ts.end)
+      if (ttft != null) summary.push(`${Math.round(ttft)}ms ttft`)
+      if (total != null) summary.push(`${Math.round(total)}ms total`)
+    }
+    if (summary.length) process.stderr.write(`${summary.join(', ')}\n`)
+  } catch (err) {
+    console.error(`Error: ${err.detail || err.message}`)
+    process.exit(1)
+  }
+}

package/src/cli/backup.js

@@ -0,0 +1,107 @@
+import { existsSync } from 'fs'
+import { readFile, copyFile, stat } from 'fs/promises'
+import { CURATED_PATH, BACKUP_SLOTS } from '../lib/common.js'
+import { id, meta, ok, err, warn } from './colors.js'
+
+export async function runBackup (args) {
+  const [action, slot] = args
+
+  if (!action || action === '-h' || action === '--help') {
+    console.log(`mohdel model backup — manage catalog backups
+
+Usage:
+  model backup list                Show backup slots with timestamps
+  model backup restore <slot>      Restore from a backup slot
+  model backup diff <slot>         Show changes between current and slot
+
+Slots: prev (last save), daily (first save of the day), weekly (first save of the week)`)
+    process.exit(0)
+  }
+
+  if (action === 'list') {
+    const current = existsSync(CURATED_PATH) ? await stat(CURATED_PATH) : null
+    if (current) {
+      const entries = JSON.parse(await readFile(CURATED_PATH, 'utf8'))
+      const count = Object.keys(entries).length
+      console.log(`  ${ok('●')} current  ${meta(fmtDate(current.mtimeMs))}  ${meta(`${count} models`)}`)
+    } else {
+      console.log(`  ${meta('○')} current  ${meta('(no catalog)')}`)
+    }
+    for (const s of BACKUP_SLOTS) {
+      const path = CURATED_PATH + '.' + s
+      if (existsSync(path)) {
+        const st = await stat(path)
+        const entries = JSON.parse(await readFile(path, 'utf8'))
+        const count = Object.keys(entries).length
+        console.log(`  ${ok('●')} ${id(s.padEnd(7))}  ${meta(fmtDate(st.mtimeMs))}  ${meta(`${count} models`)}`)
+      } else {
+        console.log(`  ${meta('○')} ${meta(s.padEnd(7))}  ${meta('(empty)')}`)
+      }
+    }
+    return
+  }
+
+  if (action === 'restore') {
+    if (!slot || !BACKUP_SLOTS.includes(slot)) {
+      console.error(`Usage: model backup restore <${BACKUP_SLOTS.join('|')}>`)
+      process.exit(1)
+    }
+    const backupPath = CURATED_PATH + '.' + slot
+    if (!existsSync(backupPath)) {
+      console.error(err(`No backup in slot "${slot}"`))
+      process.exit(1)
+    }
+    // Rotate current to .prev before restoring
+    if (existsSync(CURATED_PATH)) {
+      await copyFile(CURATED_PATH, CURATED_PATH + '.prev')
+    }
+    await copyFile(backupPath, CURATED_PATH)
+    const entries = JSON.parse(await readFile(CURATED_PATH, 'utf8'))
+    console.log(`${ok('✓')} Restored from ${id(slot)} (${Object.keys(entries).length} models). Previous state saved to ${meta('prev')}.`)
+    return
+  }
+
+  if (action === 'diff') {
+    if (!slot || !BACKUP_SLOTS.includes(slot)) {
+      console.error(`Usage: model backup diff <${BACKUP_SLOTS.join('|')}>`)
+      process.exit(1)
+    }
+    const backupPath = CURATED_PATH + '.' + slot
+    if (!existsSync(backupPath)) {
+      console.error(err(`No backup in slot "${slot}"`))
+      process.exit(1)
+    }
+    if (!existsSync(CURATED_PATH)) {
+      console.error(err('No current catalog'))
+      process.exit(1)
+    }
+
+    const current = JSON.parse(await readFile(CURATED_PATH, 'utf8'))
+    const backup = JSON.parse(await readFile(backupPath, 'utf8'))
+    const currentKeys = new Set(Object.keys(current))
+    const backupKeys = new Set(Object.keys(backup))
+
+    const added = [...currentKeys].filter(k => !backupKeys.has(k))
+    const removed = [...backupKeys].filter(k => !currentKeys.has(k))
+    const changed = [...currentKeys].filter(k => backupKeys.has(k) && JSON.stringify(current[k]) !== JSON.stringify(backup[k]))
+
+    if (!added.length && !removed.length && !changed.length) {
+      console.log(meta('No differences'))
+      return
+    }
+
+    for (const k of added) console.log(`${ok('+')} ${id(k)}`)
+    for (const k of removed) console.log(`${err('-')} ${id(k)}`)
+    for (const k of changed) console.log(`${warn('~')} ${id(k)}`)
+    console.log(meta(`\n${added.length} added, ${removed.length} removed, ${changed.length} changed`))
+    return
+  }
+
+  console.error(`Unknown action: ${action}. Run "model backup --help".`)
+  process.exit(1)
+}
+
+function fmtDate (ms) {
+  const d = new Date(ms)
+  return d.toLocaleDateString() + ' ' + d.toLocaleTimeString()
+}

package/src/cli/bench.js

@@ -0,0 +1,262 @@
+import { id, label, meta, price, err } from './colors.js'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import mohdel from '../lib/index.js'
+import { loadDefaultEnv } from '../lib/common.js'
+import {
+  loadPrompt, parseJson, scoreCorrectness, computeCost,
+  computeTiming, formatNumber
+} from '../lib/benchmark-score.js'
+
+export async function runBench (args) {
+  if (args.includes('-h') || args.includes('--help')) {
+    console.log(`mohdel model bench — benchmark models with live inference
+
+Usage:
+  model bench <model> [options]         Benchmark a single model
+  model bench --tag <tag> [options]     Benchmark all models with a tag
+
+Options:
+  --effort <level>      Thinking effort: high, medium, low, none
+  --budget <tokens>     Output token budget (default: 12000)
+  --prompt <path>       Prompt file (default: test/benchmark.md)
+  --save <path>         Save results to JSON file
+  --json                Output as JSON (single model only)
+
+Examples:
+  mo bench anthropic/claude-sonnet-4-6
+  mo bench --tag fast --effort low
+  mo bench openai/gpt-5 --budget 8000 --save results.json`)
+    process.exit(0)
+  }
+
+  loadDefaultEnv()
+
+  // Parse flags
+  const flag = (name) => {
+    const idx = args.indexOf(name)
+    if (idx === -1) return false
+    args.splice(idx, 1)
+    return true
+  }
+  const flagVal = (name) => {
+    const idx = args.indexOf(name)
+    if (idx === -1) return undefined
+    const val = args[idx + 1]
+    args.splice(idx, 2)
+    return val
+  }
+
+  const json = flag('--json')
+  const effort = flagVal('--effort')
+  const budget = parseInt(flagVal('--budget') || '12000', 10)
+  const promptPath = flagVal('--prompt') || 'test/benchmark.md'
+  const savePath = flagVal('--save')
+  const tags = []
+  let t
+  while ((t = flagVal('--tag'))) tags.push(t)
+
+  const mo = await mohdel()
+
+  if (tags.length) {
+    await runSuite(mo, { tags, effort, budget, promptPath, savePath })
+  } else {
+    const modelId = args[0]
+    if (!modelId) {
+      console.error('Provide a model ID or --tag. Run "mo model bench --help".')
+      process.exit(1)
+    }
+    await runSingle(mo, modelId, { effort, budget, promptPath, savePath, json })
+  }
+}
+
+// --- Single model ---
+
+async function runSingle (mo, modelId, { effort, budget, promptPath, savePath, json }) {
+  const prompt = await loadPrompt(promptPath)
+  const model = mo.use(modelId)
+  const info = model.info()
+  const pricing = resolvePricing(info)
+
+  const result = await benchmarkModel(model, prompt, { effort, budget, pricing })
+
+  if (savePath) {
+    await fs.writeFile(path.resolve(savePath), JSON.stringify(result, null, 2))
+  }
+
+  if (json) {
+    console.log(JSON.stringify(result, null, 2))
+  } else {
+    printSingleResult(result)
+  }
+}
+
+// --- Suite (multi-model by tag) ---
+
+async function runSuite (mo, { tags, effort, budget, promptPath, savePath }) {
+  const prompt = await loadPrompt(promptPath)
+  const seen = new Set()
+  const models = []
+  for (const tag of tags) {
+    for (const m of mo.list(tag)) {
+      if (!seen.has(m.value)) {
+        seen.add(m.value)
+        models.push(m)
+      }
+    }
+  }
+
+  if (!models.length) {
+    console.error(err(`No models found with tags: ${tags.join(', ')}`))
+    process.exit(1)
+  }
+
+  const results = []
+  for (let i = 0; i < models.length; i++) {
+    const { value, label } = models[i]
+    process.stderr.write(`[${i + 1}/${models.length}] ${value}...`)
+
+    try {
+      const model = mo.use(value)
+      const pricing = resolvePricing(model.info())
+      const result = await benchmarkModel(model, prompt, { effort, budget, pricing })
+      results.push(result)
+      process.stderr.write(` ${result.correctness.toFixed(3)}\n`)
+    } catch (e) {
+      process.stderr.write(` ${err('FAILED')}: ${e.message}\n`)
+      results.push({ model: value, label, correctness: null, cost: null, correctnessPerDollar: null, error: e.message })
+    }
+  }
+
+  results.sort((a, b) => {
+    if (a.correctnessPerDollar === null && b.correctnessPerDollar === null) return 0
+    if (a.correctnessPerDollar === null) return 1
+    if (b.correctnessPerDollar === null) return -1
+    return b.correctnessPerDollar - a.correctnessPerDollar
+  })
+
+  printSuiteTable(results)
+
+  if (savePath) {
+    await fs.writeFile(path.resolve(savePath), JSON.stringify(results, null, 2))
+    process.stderr.write(`\nResults saved to ${path.resolve(savePath)}\n`)
+  }
+}
+
+// --- Shared benchmark runner ---
+
+async function benchmarkModel (model, prompt, { effort, budget, pricing }) {
+  const runTag = `[run:${Date.now()}-${Math.random().toString(36).slice(2, 8)}]`
+  const minimalBudget = Math.min(budget || 0, 32) || 32
+
+  const minimalResponse = await model.answer(`${runTag} say ack`, { outputBudget: minimalBudget, outputEffort: effort })
+  const response = await model.answer(`${runTag}\n${prompt}`, { outputBudget: budget, outputEffort: effort })
+
+  const rawOutput = typeof response === 'string' ? response : response?.output || ''
+  const parsed = parseJson(rawOutput)
+  const scoring = scoreCorrectness(parsed)
+
+  const minimalTiming = computeTiming(typeof minimalResponse === 'object' ? minimalResponse.timestamps : {})
+  const standardTiming = computeTiming(typeof response === 'object' ? response.timestamps : {})
+
+  const generationSeconds = standardTiming.generationMs !== null ? standardTiming.generationMs / 1000 : null
+  const outputTokens = Number.isFinite(response?.outputTokens) ? response.outputTokens : null
+
+  const tokens = {
+    input: response?.inputTokens ?? null,
+    output: response?.outputTokens ?? null,
+    thinking: response?.thinkingTokens ?? null
+  }
+
+  const costDollars = computeCost(tokens, pricing)
+
+  return {
+    model: model.id,
+    label: model.label,
+    correctness: formatNumber(scoring.correctness),
+    cost: costDollars !== null ? formatNumber(costDollars) : null,
+    correctnessPerDollar: costDollars > 0 ? formatNumber(scoring.correctness / costDollars) : null,
+    breakdown: Object.fromEntries(
+      Object.entries(scoring.breakdown).map(([k, v]) => [k, formatNumber(v)])
+    ),
+    tokens,
+    pricing: pricing ? { inputPerMillion: pricing.input, outputPerMillion: pricing.output, thinkingPerMillion: pricing.thinking } : null,
+    parse: { ok: parsed.ok, error: parsed.ok ? null : parsed.error, extraneous: parsed.extraneous },
+    timing: { minimal: minimalTiming, standard: standardTiming },
+    throughput: {
+      outputTokensPerSecond: outputTokens !== null && generationSeconds > 0 ? formatNumber(outputTokens / generationSeconds) : null,
+      charactersPerSecond: generationSeconds > 0 ? formatNumber(rawOutput.length / generationSeconds) : null
+    },
+    latencyMs: { minimal: minimalTiming.latencyMs, standard: standardTiming.latencyMs },
+    requested: { outputBudget: budget, outputEffort: effort || null },
+    details: scoring.details,
+    raw: rawOutput
+  }
+}
+
+// --- Helpers ---
+
+function resolvePricing (info) {
+  if (!info) return null
+  const rp = p => typeof p === 'number' ? p : (p?.default ?? 0)
+  return { input: rp(info.inputPrice), output: rp(info.outputPrice), thinking: rp(info.thinkingPrice) }
+}
+
+// --- Output ---
+
+function printSingleResult (r) {
+  console.log(`\n${label(r.label)} ${meta(`(${r.model})`)}`)
+  console.log(`${meta('correctness:')}  ${id(r.correctness?.toFixed(3) || '—')}`)
+  console.log(`${meta('cost:')}         ${r.cost != null ? price('$' + r.cost.toFixed(4)) : '—'}`)
+  console.log(`${meta('corr/$:')}       ${r.correctnessPerDollar?.toFixed(1) || '—'}`)
+  console.log(`${meta('latency:')}      ${r.latencyMs.standard != null ? r.latencyMs.standard.toFixed(0) + 'ms' : '—'}`)
+  console.log(`${meta('throughput:')}   ${r.throughput.outputTokensPerSecond || '—'} tok/s`)
+  console.log(`${meta('tokens:')}       ${r.tokens.input || 0} in, ${r.tokens.output || 0} out, ${r.tokens.thinking || 0} thinking`)
+
+  if (r.breakdown) {
+    const parts = Object.entries(r.breakdown).map(([k, v]) => `${k}=${v?.toFixed(3) || '—'}`)
+    console.log(`${meta('breakdown:')}    ${parts.join('  ')}`)
+  }
+  console.log()
+}
+
+const pad = (str, len) => {
+  const s = String(str)
+  return s.length >= len ? s : s + ' '.repeat(len - s.length)
+}
+
+const fmtNum = (v, width) => {
+  if (v === null || v === undefined) return pad('-', width)
+  return pad(v.toFixed(3), width)
+}
+
+function printSuiteTable (results) {
+  const colModel = 35
+  const colNum = 9
+  const header = pad('Model', colModel) +
+    pad('Correct', colNum) +
+    pad('Cost($)', colNum) +
+    pad('Corr/$', colNum) +
+    pad('Entities', colNum) +
+    pad('Metrics', colNum) +
+    pad('Contrad.', colNum)
+  console.log('\n' + meta(header))
+  console.log(meta('─'.repeat(header.length)))
+
+  for (const r of results) {
+    if (r.error) {
+      console.log(pad(r.model, colModel) + err('FAILED: ' + r.error))
+      continue
+    }
+    console.log(
+      pad(r.model, colModel) +
+      fmtNum(r.correctness, colNum) +
+      fmtNum(r.cost, colNum) +
+      fmtNum(r.correctnessPerDollar, colNum) +
+      fmtNum(r.breakdown?.entities, colNum) +
+      fmtNum(r.breakdown?.metrics, colNum) +
+      fmtNum(r.breakdown?.contradictions, colNum)
+    )
+  }
+  console.log()
+}