mohdel 0.121.2 → 0.122.0

package/README.md

@@ -1,6 +1,6 @@
 # Mohdel
 
-Self-hosted LLM gateway and SDK for Node — think LiteLLM, for the JS world. One `answer()` call for 13 providers; swap models by changing one string; get real per-call USD cost back on every result, with OpenTelemetry built in and process isolation when you need it. Your keys, your infra, no SaaS proxy in the path.
+Self-hosted LLM gateway and SDK for Node — think LiteLLM, for the JS world. One `answer()` call for 13 providers or local inference; swap models by changing one string; get real per-call USD cost back on every result, with OpenTelemetry built in and process isolation when you need it. Your keys, your infra, no SaaS proxy in the path.
 
 ```bash
 npm install -g mohdel
@@ -279,10 +279,13 @@ FIREWORKS_API_SK=fw_...
 DEEPSEEK_API_SK=sk-...
 OPENROUTER_API_SK=sk-or-...
 NOVITA_API_SK=...
+MOHDEL_LOCAL_API_SK=...
 ```
 
 Only set keys for providers you use. Run `mo` with no arguments for interactive setup.
 
+`local/` routes each model to the `baseURL` of its catalog entry — any OpenAI-compatible chat-completions server (Ollama, vLLM, llama.cpp server, LM Studio). There is no default endpoint and no per-call override: an entry without `baseURL` fails `mo model check`, a call to it fails with `CONFIGURATION_MISSING`, so a call never falls through to a cloud provider. `MOHDEL_LOCAL_API_SK` is an optional bearer token. Entry format in [docs/CATALOG.md](docs/CATALOG.md#self-hosted-local-entries).
+
 ### File locations
 
 | Path | Purpose |
@@ -314,6 +317,7 @@ What each provider supports through mohdel's unified interface:
 | Qwen Cloud | No | Yes | No | No | Yes (`enable_thinking` + `thinking_budget`) | Alibaba DashScope intl; hybrid models think by default — effort `none` sends explicit off |
 | Xiaomi | No | Yes | Yes | No | Auto | MiMo; shared chat-completions path, `reasoning_content` captured |
 | OpenRouter | Yes | Yes | Yes | No | Varies | Meta-provider; `providerOptions.openrouter` for routing prefs |
+| Local | Yes | Yes | Yes | No | No | Any OpenAI-compatible server; endpoint is the catalog entry's `baseURL` |
 | Novita | No | No | No | No | No | Image generation only |
 
 Adapter capability ≠ model capability — whether a given model accepts images, tools, or thinking effort depends on the model spec in `curated.json`. The adapter passes through what the envelope supplies; the provider rejects unsupported combos.

package/config/curated.example.json

@@ -1,6 +1,6 @@
 {
   "$schema": "./curated.schema.json",
-  "_comment": "Worked examples for ~/.config/mohdel/curated.json. See docs/CATALOG.md for the field reference. Each top-level key is '<provider>/<model-id>'. The provider segment is the routing key; the model-id segment must match the value of the 'model' field below (which is the literal id mohdel sends to the provider's API).",
+  "_comment": "Worked examples for ~/.config/mohdel/curated.json. See docs/CATALOG.md for the field reference. Each top-level key is '<provider>/<model-id>'. The provider segment is the routing key; the 'model' field is the literal id mohdel sends to the provider's API and may differ from the model-id segment.",
 
   "anthropic/claude-haiku-4-5": {
     "_comment_a": "Minimal-but-useful entry. Required fields only: model, creator, inputFormat. Everything else is recommended — without prices, 'cost' on results will be 0; without contextTokenLimit, callers can't enforce input budgets.",
@@ -89,5 +89,17 @@
     "tpmLimit": 2000000,
     "rateLimitScope": "model",
     "tags": ["chat", "cheap"]
+  },
+
+  "local/llama3.1-8b": {
+    "_comment_f": "Self-hosted entry: 'baseURL' names the OpenAI-compatible server (required on local/ entries, rejected elsewhere). The key carries no ':' (mohdel reads ':' as the effort suffix); 'model' carries the server's own tag. No prices, so cost is 0.",
+    "model": "llama3.1:8b",
+    "baseURL": "http://127.0.0.1:11434/v1",
+    "creator": "meta",
+    "provider": "local",
+    "sdk": "openai",
+    "label": "Llama 3.1 8B (local)",
+    "inputFormat": ["text"],
+    "tags": ["local"]
   }
 }

package/config/curated.schema.json

@@ -70,6 +70,10 @@
           "minItems": 1,
           "uniqueItems": true
         },
+        "baseURL": {
+          "type": "string",
+          "description": "local/ entries only: the OpenAI-compatible server this model is served from (e.g. http://127.0.0.1:11434/v1). Required there, rejected elsewhere."
+        },
         "provider": {
           "type": "string",
           "description": "Routing provider. Defaults to the provider segment of the catalog key."

package/js/core/envelope.js

@@ -87,10 +87,6 @@
 /**
  * @typedef {object} Auth
  * @property {string} key  Provider API key. Redact in logs; never persist.
- * @property {string} [baseURL]
- *   Optional override of the adapter's default provider endpoint.
- *   Lets callers point at a self-hosted deployment, regional endpoint,
- *   proxy, or test server. Adapters treat it as `baseURL ?? ADAPTER_DEFAULT`.
  */
 
 /**

package/js/factory/bridge.js

@@ -271,7 +271,7 @@ function newCallId () {
 
 /**
  * Turn the factory's `configuration` bag into an envelope `auth` object.
- * Accepts `apiKey` + `baseURL`; anything else is rejected with
+ * Accepts `apiKey`; anything else is rejected with
  * `CONFIGURATION_UNSUPPORTED` rather than silently dropped — otherwise
  * a caller could believe their proxy / org header / timeout is in
  * effect when it isn't, which in the worst case leaks auth keys and
@@ -280,7 +280,7 @@ function newCallId () {
  * @param {any} configuration
  * @returns {import('#core/envelope.js').Auth}
  */
-const ALLOWED_CONFIG_KEYS = new Set(['apiKey', 'baseURL'])
+const ALLOWED_CONFIG_KEYS = new Set(['apiKey'])
 
 export function configToAuth (configuration) {
   if (!configuration) return { key: '' }
@@ -289,15 +289,13 @@ export function configToAuth (configuration) {
     throw new MohdelError('unsupported per-call configuration', {
       type: 'CONFIGURATION_UNSUPPORTED',
       detail:
-        'per-call SDK configuration is limited to `apiKey` and `baseURL`. ' +
+        'per-call SDK configuration is limited to `apiKey`. ' +
         `Unsupported keys: ${unsupported.join(', ')}. ` +
         'Move other fields to environment variables or pin them at factory construction.',
       retryable: false
     })
   }
-  const auth = { key: configuration.apiKey || '' }
-  if (configuration.baseURL) auth.baseURL = configuration.baseURL
-  return auth
+  return { key: configuration.apiKey || '' }
 }
 
 /**

package/js/session/adapters/deepseek.js

@@ -23,7 +23,7 @@ const BASE_URL = 'https://api.deepseek.com'
 export async function * deepseek (envelope, deps = {}) {
   const client = deps.client ?? new OpenAI({
     apiKey: envelope.auth.key,
-    baseURL: envelope.auth.baseURL || BASE_URL,
+    baseURL: BASE_URL,
     fetchOptions: { dispatcher: streamingDispatcher() }
   })
   yield * runChatCompletions(envelope, client, {

package/js/session/adapters/fireworks.js

@@ -28,7 +28,7 @@ const BASE_URL = 'https://api.fireworks.ai/inference/v1'
 export async function * fireworks (envelope, deps = {}) {
   const client = deps.client ?? new OpenAI({
     apiKey: envelope.auth.key,
-    baseURL: envelope.auth.baseURL || BASE_URL,
+    baseURL: BASE_URL,
     fetchOptions: { dispatcher: streamingDispatcher() }
   })
   yield * runChatCompletions(envelope, client, {

package/js/session/adapters/index.js

@@ -19,6 +19,7 @@ import { fake } from './fake.js'
 import { fireworks } from './fireworks.js'
 import { gemini } from './gemini.js'
 import { groq } from './groq.js'
+import { local } from './local.js'
 import { mistral } from './mistral.js'
 import { novita } from './novita.js'
 import { openai } from './openai.js'
@@ -36,6 +37,7 @@ export const adapters = Object.freeze({
   fireworks,
   gemini,
   groq,
+  local,
   mistral,
   novita,
   openai,

package/js/session/adapters/local.js

@@ -0,0 +1,60 @@
+/**
+ * Local adapter — any OpenAI-compatible chat-completions server
+ * (Ollama, vLLM, llama.cpp server, LM Studio). The endpoint is the
+ * catalog entry's `baseURL`; there is no default and no per-call
+ * override, so a call can never fall through to a cloud provider.
+ *
+ * @module session/adapters/local
+ */
+
+import OpenAI from 'openai'
+
+import { catalogKey } from '#core/model-id.js'
+
+import { getSpec } from './_catalog.js'
+import { runChatCompletions } from './_chat_completions.js'
+import { streamingDispatcher } from './_dispatcher.js'
+
+// The SDK constructor rejects an empty `apiKey`. An unauthenticated
+// server gets a placeholder key that never reaches the wire: the
+// explicit `Authorization: null` default header makes the SDK omit
+// the header entirely.
+const UNAUTHENTICATED = 'unauthenticated'
+
+/**
+ * @param {import('#core/envelope.js').CallEnvelope} envelope
+ * @param {{client?: any, signal?: AbortSignal, log?: any, span?: any}} [deps]
+ * @returns {AsyncGenerator<import('#core/events.js').Event>}
+ */
+export async function * local (envelope, deps = {}) {
+  const key = catalogKey(envelope.model)
+  const baseURL = getSpec(key)?.baseURL
+  if (!baseURL) {
+    yield {
+      type: 'error',
+      error: {
+        message: 'local provider has no endpoint',
+        detail: `catalog entry '${key}' has no baseURL`,
+        severity: 'error',
+        retryable: false,
+        type: 'CONFIGURATION_MISSING'
+      }
+    }
+    return
+  }
+  const client = deps.client ?? new OpenAI({
+    baseURL,
+    fetchOptions: { dispatcher: streamingDispatcher() },
+    ...(envelope.auth.key
+      ? { apiKey: envelope.auth.key }
+      : { apiKey: UNAUTHENTICATED, defaultHeaders: { Authorization: null } })
+  })
+  yield * runChatCompletions(envelope, client, {
+    provider: 'local',
+    stream: true
+  }, {
+    signal: deps.signal,
+    log: deps.log,
+    span: deps.span
+  })
+}

package/js/session/adapters/mistral.js

@@ -22,7 +22,7 @@ const BASE_URL = 'https://api.mistral.ai/v1'
 export async function * mistral (envelope, deps = {}) {
   const client = deps.client ?? new OpenAI({
     apiKey: envelope.auth.key,
-    baseURL: envelope.auth.baseURL || BASE_URL,
+    baseURL: BASE_URL,
     fetchOptions: { dispatcher: streamingDispatcher() }
   })
   yield * runChatCompletions(envelope, client, {

package/js/session/adapters/novita.js

@@ -18,7 +18,7 @@ const BASE_URL = 'https://api.novita.ai/openai'
  * @returns {AsyncGenerator<import('#core/events.js').Event>}
  */
 export async function * novita (envelope, deps = {}) {
-  const client = deps.client ?? new OpenAI({ apiKey: envelope.auth.key, baseURL: envelope.auth.baseURL || BASE_URL })
+  const client = deps.client ?? new OpenAI({ apiKey: envelope.auth.key, baseURL: BASE_URL })
   yield * runChatCompletions(envelope, client, {
     provider: 'novita'
   }, {

package/js/session/adapters/openai.js

@@ -46,7 +46,6 @@ import { streamingDispatcher } from './_dispatcher.js'
 export async function * openai (envelope, deps = {}) {
   const client = deps.client ?? new OpenAI({
     apiKey: envelope.auth.key,
-    ...(envelope.auth.baseURL ? { baseURL: envelope.auth.baseURL } : {}),
     fetchOptions: { dispatcher: streamingDispatcher() }
   })
   const signal = deps.signal

package/js/session/adapters/openrouter.js

@@ -47,7 +47,7 @@ export async function * openrouter (envelope, deps = {}) {
   }
   const client = deps.client ?? new OpenAI({
     apiKey: envelope.auth.key,
-    baseURL: envelope.auth.baseURL || BASE_URL,
+    baseURL: BASE_URL,
     defaultHeaders,
     fetchOptions: { dispatcher: streamingDispatcher() }
   })

package/js/session/adapters/qwen.js

@@ -23,7 +23,7 @@ const BASE_URL = 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1'
 export async function * qwen (envelope, deps = {}) {
   const client = deps.client ?? new OpenAI({
     apiKey: envelope.auth.key,
-    baseURL: envelope.auth.baseURL || BASE_URL,
+    baseURL: BASE_URL,
     fetchOptions: { dispatcher: streamingDispatcher() }
   })
   yield * runChatCompletions(envelope, client, {

package/js/session/adapters/transcription/openai_compatible.js

@@ -48,7 +48,7 @@ export function createTranscriptionAdapter ({ baseURL, responseFormat }) {
     if (envelope.language) form.append('language', envelope.language)
     if (envelope.prompt) form.append('prompt', envelope.prompt)
 
-    const root = (envelope.auth.baseURL || baseURL).replace(/\/$/, '')
+    const root = baseURL.replace(/\/$/, '')
     let res
     try {
       res = await fetchFn(`${root}/audio/transcriptions`, {

package/js/session/adapters/xai.js

@@ -22,7 +22,7 @@ const BASE_URL = 'https://api.x.ai/v1'
 export async function * xai (envelope, deps = {}) {
   const client = deps.client ?? new OpenAI({
     apiKey: envelope.auth.key,
-    baseURL: envelope.auth.baseURL || BASE_URL,
+    baseURL: BASE_URL,
     fetchOptions: { dispatcher: streamingDispatcher() }
   })
   yield * openai(envelope, { ...deps, client })

package/js/session/adapters/xiaomi.js

@@ -22,7 +22,7 @@ const BASE_URL = 'https://api.xiaomimimo.com/v1'
 export async function * xiaomi (envelope, deps = {}) {
   const client = deps.client ?? new OpenAI({
     apiKey: envelope.auth.key,
-    baseURL: envelope.auth.baseURL || BASE_URL,
+    baseURL: BASE_URL,
     fetchOptions: { dispatcher: streamingDispatcher() }
   })
   yield * runChatCompletions(envelope, client, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mohdel",
-  "version": "0.121.2",
+  "version": "0.122.0",
   "license": "MIT",
   "author": {
     "name": "Christophe Le Bars",
@@ -108,7 +108,7 @@
     "@opentelemetry/exporter-trace-otlp-grpc": "^0.222.0",
     "@opentelemetry/sdk-node": "^0.222.0",
     "chalk": "^6.0.0",
-    "mohdel-thin-gate-linux-x64-gnu": "0.121.2"
+    "mohdel-thin-gate-linux-x64-gnu": "0.122.0"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.122.0",

package/src/cli/doctor.js

@@ -51,6 +51,7 @@ Exit code:
 
   // 2. API keys per provider
   for (const [name, def] of Object.entries(providers)) {
+    if (!def.apiKeyEnv) continue
     if (getAPIKey(def.apiKeyEnv)) {
       report.keys.configured.push({ provider: name, envVar: def.apiKeyEnv })
     } else {
@@ -137,7 +138,7 @@ Exit code:
   }
 
   console.log()
-  console.log(label(`API keys (${report.keys.configured.length} of ${Object.keys(providers).length})`))
+  console.log(label(`API keys (${report.keys.configured.length} of ${Object.values(providers).filter(def => def.apiKeyEnv).length})`))
   for (const k of report.keys.configured) {
     console.log(row(ok('✓'), k.provider, k.envVar))
   }

package/src/lib/providers.js

@@ -19,7 +19,8 @@ const providers = {
     sdk: 'openai',
     api: 'chatCompletions',
     apiKeyEnv: 'DEEPSEEK_API_SK',
-    createConfiguration: apiKey => ({ baseURL: 'https://api.deepseek.com', apiKey }),
+    baseURL: 'https://api.deepseek.com',
+    createConfiguration: apiKey => ({ apiKey }),
     creators: ['deepseek'],
     contextSemantics: 'shared',
     outputCapStrategy: 'accept'
@@ -27,7 +28,8 @@ const providers = {
   fireworks: {
     sdk: 'fireworks',
     apiKeyEnv: 'FIREWORKS_API_SK',
-    createConfiguration: apiKey => ({ apiKey, baseURL: 'https://api.fireworks.ai/inference/v1' }),
+    baseURL: 'https://api.fireworks.ai/inference/v1',
+    createConfiguration: apiKey => ({ apiKey }),
     creators: ['meta', 'alibaba'],
     contextSemantics: 'shared',
     outputCapStrategy: 'accept'
@@ -46,11 +48,21 @@ const providers = {
     createConfiguration: apiKey => ({ apiKey }),
     creators: ['meta']
   },
+  local: {
+    sdk: 'openai',
+    api: 'chatCompletions',
+    catalog: false,
+    resolveConfiguration: () => ({ apiKey: process.env.MOHDEL_LOCAL_API_SK || '' }),
+    creators: [],
+    contextSemantics: 'shared',
+    outputCapStrategy: 'accept'
+  },
   mistral: {
     sdk: 'openai',
     api: 'chatCompletions',
     apiKeyEnv: 'MISTRAL_API_SK',
-    createConfiguration: apiKey => ({ baseURL: 'https://api.mistral.ai/v1', apiKey }),
+    baseURL: 'https://api.mistral.ai/v1',
+    createConfiguration: apiKey => ({ apiKey }),
     creators: ['mistral']
   },
   novita: {
@@ -58,7 +70,8 @@ const providers = {
     api: 'chatCompletions',
     imageHandler: 'novita',
     apiKeyEnv: 'NOVITA_API_SK',
-    createConfiguration: apiKey => ({ apiKey, baseURL: 'https://api.novita.ai/openai' }),
+    baseURL: 'https://api.novita.ai/openai',
+    createConfiguration: apiKey => ({ apiKey }),
     creators: ['deepseek', 'openai', 'bfl'],
     contextSemantics: 'shared',
     outputCapStrategy: 'error'
@@ -74,14 +87,16 @@ const providers = {
   openrouter: {
     sdk: 'openrouter',
     apiKeyEnv: 'OPENROUTER_API_SK',
-    createConfiguration: apiKey => ({ baseURL: 'https://openrouter.ai/api/v1', apiKey }),
+    baseURL: 'https://openrouter.ai/api/v1',
+    createConfiguration: apiKey => ({ apiKey }),
     creators: []
   },
   qwen: {
     sdk: 'openai',
     api: 'chatCompletions',
     apiKeyEnv: 'QWEN_API_SK',
-    createConfiguration: apiKey => ({ baseURL: 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1', apiKey }),
+    baseURL: 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1',
+    createConfiguration: apiKey => ({ apiKey }),
     creators: ['alibaba'],
     contextSemantics: 'shared',
     outputCapStrategy: 'accept'
@@ -89,7 +104,8 @@ const providers = {
   xai: {
     sdk: 'openai',
     apiKeyEnv: 'XAI_API_SK',
-    createConfiguration: apiKey => ({ baseURL: 'https://api.x.ai/v1', apiKey }),
+    baseURL: 'https://api.x.ai/v1',
+    createConfiguration: apiKey => ({ apiKey }),
     creators: ['xai'],
     contextSemantics: 'shared',
     outputCapStrategy: 'accept'
@@ -98,7 +114,8 @@ const providers = {
     sdk: 'openai',
     api: 'chatCompletions',
     apiKeyEnv: 'XIAOMI_API_SK',
-    createConfiguration: apiKey => ({ baseURL: 'https://api.xiaomimimo.com/v1', apiKey }),
+    baseURL: 'https://api.xiaomimimo.com/v1',
+    createConfiguration: apiKey => ({ apiKey }),
     creators: ['xiaomi'],
     contextSemantics: 'shared',
     outputCapStrategy: 'accept'

package/src/lib/schema.js

@@ -17,6 +17,7 @@ const validateSpeeds = (speeds) => {
 
 const fieldDefs = {
   model: { type: 'string', required: true },
+  baseURL: { type: 'string' },
   provider: { type: 'string' },
   sdk: { type: 'string' },
   type: { type: 'string', default: 'model' },
@@ -122,6 +123,14 @@ const validate = (entry, curatedKey, { strict = false } = {}) => {
     }
   }
 
+  const provider = entry.provider ?? (typeof curatedKey === 'string' ? curatedKey.split('/')[0] : undefined)
+  if (provider === 'local' && !isDeprecatedStub && !entry.baseURL) {
+    issues.push({ field: 'baseURL', message: 'required for local/ entries', severity: 'error' })
+  }
+  if (provider !== 'local' && entry.baseURL !== undefined) {
+    issues.push({ field: 'baseURL', message: 'only local/ entries carry an endpoint', severity: 'error' })
+  }
+
   if (strict) {
     for (const key of Object.keys(entry)) {
       if (!knownFields.has(key) && !COMPUTED_FIELDS.has(key)) {

package/src/lib/select.js

@@ -41,7 +41,7 @@ export const initializeAPIs = async () => {
       const sdkPath = `./catalog/${config.sdk}.js`
       const { default: API } = await import(sdkPath)
 
-      api[name] = API(sdkConfig, {}, silent)
+      api[name] = API({ ...sdkConfig, baseURL: config.baseURL }, {}, silent)
       providersWithKeys.push(name)
     } catch (err) {
       console.error(`Error initializing provider ${name} api:`, err.message)