failsafe-llm-model-resolver 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,194 @@
+# failsafe-llm-model-resolver
+
+**Self-healing, failsafe resolver for the current frontier model.**
+
+Live `/models` fetch → preference rules → env-pinned fallback.  
+A transient network hiccup never kills a batch job.
+
+```js
+const { resolveModel, getNextFreeModel } = require('failsafe-llm-model-resolver');
+
+const { id, source } = await resolveModel('xai', process.env.XAI_API_KEY);
+// → { id: 'grok-4', source: 'live' }
+//    or { id: 'grok-4', source: 'fallback' } when the live list is unreachable
+```
+
+---
+
+## Why this exists
+
+Hard-coding model IDs is fragile. Providers ship new versions weekly; free tiers rotate; rate-limits appear and disappear. The classic pattern:
+
+```js
+const model = 'grok-4';          // stale next month
+const model = 'openrouter/free'; // may 404 or be rate-limited
+```
+
+…breaks batch jobs and agents at the worst moment.
+
+**failsafe-llm-model-resolver** does the boring but critical work once:
+
+1. Hits each provider’s native model-list endpoint
+2. Applies a stable preference rule (newest non-fast / non-mini / non-haiku)
+3. Caches the result for the process lifetime
+4. Falls back to an env-configurable pinned ID if anything fails
+
+You get the current frontier model when the network works, and a known-good model when it doesn’t.
+
+---
+
+## Supported providers
+
+| Provider       | Endpoint                                              | Preference rule                                      |
+|----------------|-------------------------------------------------------|------------------------------------------------------|
+| **xAI / Grok** | `GET https://api.x.ai/v1/models`                      | newest `grok-*`, skip `fast` / `mini` / `lite`       |
+| **Anthropic**  | `GET https://api.anthropic.com/v1/models`             | newest `claude-*`, skip `haiku` / `instant` (newest-first) |
+| **Gemini**     | `GET …/v1beta/models?key=…`                           | newest non-`flash` / non-`lite`                      |
+| **OpenRouter** | `GET https://openrouter.ai/api/v1/models`             | free models (`pricing.prompt/completion === "0"`) + round-robin |
+
+No heavy SDKs. Native `fetch` only (Node ≥ 18).
+
+---
+
+## Install
+
+```bash
+npm install failsafe-llm-model-resolver
+```
+
+Or, for personal multi-project reuse without publishing:
+
+```bash
+# place index.js somewhere shared, e.g. ~/dev/shared-lib/failsafe-llm-model-resolver/
+export NODE_PATH="$HOME/dev/shared-lib:$NODE_PATH"
+# then: require('failsafe-llm-model-resolver')
+```
+
+---
+
+## API
+
+### `resolveModel(provider, apiKey, options?)`
+
+```ts
+type Provider = 'xai' | 'anthropic' | 'gemini' | 'openrouter';
+
+interface ResolveResult {
+  id: string;                 // ready to pass to the provider’s chat endpoint
+  source: 'live' | 'fallback';
+}
+
+function resolveModel(
+  provider: Provider,
+  apiKey: string | null | undefined,
+  options?: { forceRefresh?: boolean; fallback?: string }
+): Promise<ResolveResult>;
+```
+
+- **Paid providers** → live list + preference rule → single best ID  
+- **OpenRouter** → first currently free model (use `getNextFreeModel` for rotation)  
+- **Any failure / missing key** → env-pinned fallback, `source: 'fallback'`
+
+### OpenRouter free-tier helpers
+
+Drop-in replacements for the classic `fetchOrFreeModels` / `getNextOrModel` pattern:
+
+```js
+const free = await fetchFreeModels(process.env.OPENROUTER_API_KEY); // Set<string>
+const model = await getNextFreeModel(process.env.OPENROUTER_API_KEY); // round-robin
+resetFreeModelIndex(); // call at the start of a batch if desired
+```
+
+### Cache control
+
+```js
+clearCache(); // wipe all in-memory caches (mainly for tests)
+```
+
+---
+
+## Env-configurable fallbacks
+
+Never let a transient error kill a job. Set any of:
+
+```bash
+XAI_MODEL_FALLBACK=grok-4
+# or GROK_MODEL_FALLBACK=grok-4
+
+ANTHROPIC_MODEL_FALLBACK=claude-sonnet-4-20250514
+GEMINI_MODEL_FALLBACK=gemini-2.5-pro
+OPENROUTER_MODEL_FALLBACK=openrouter/free
+# or OPENROUTER_FREE_FALLBACK=openrouter/free
+```
+
+Defaults are sensible current frontier IDs; override them for your own pins.
+
+---
+
+## Quick examples
+
+**Simple resolve**
+
+```js
+const { resolveModel } = require('failsafe-llm-model-resolver');
+
+async function chat(prompt) {
+  const { id } = await resolveModel('anthropic', process.env.ANTHROPIC_API_KEY);
+  // use `id` with the Anthropic SDK / fetch …
+}
+```
+
+**Self-healing OpenRouter free rotation** (matches the original working code)
+
+```js
+const { getNextFreeModel, resetFreeModelIndex } = require('failsafe-llm-model-resolver');
+
+async function callOpenRouter(prompt) {
+  resetFreeModelIndex();
+  let lastErr;
+  for (let attempt = 0; attempt < 10; attempt++) {
+    const model = await getNextFreeModel(process.env.OPENROUTER_API_KEY);
+    try {
+      // … POST /api/v1/chat/completions with model …
+      return result;
+    } catch (e) {
+      lastErr = e; // rate-limit / empty → try next free model
+    }
+  }
+  throw lastErr;
+}
+```
+
+**Force a refresh**
+
+```js
+const { id } = await resolveModel('xai', key, { forceRefresh: true });
+```
+
+---
+
+## Design notes
+
+- **In-memory cache** – one fetch per provider per process. Matches the proven `_orFreeModels` pattern.
+- **Preference, not exact IDs** – paid providers use regex + “first match after newest-first”. When the next `grok-5` or `claude-sonnet-5` ships, you get it automatically.
+- **OpenRouter free is special** – exact free filter + ordered round-robin. The free pool rotates; the code adapts.
+- **Fail-closed to a known model** – network, 429 on the models endpoint, empty list, missing key → pinned fallback. Batch jobs keep running.
+- **Zero dependencies** – only what Node 18+ already provides.
+
+---
+
+## Smoke test
+
+```bash
+npm test
+# or with live keys:
+XAI_API_KEY=… ANTHROPIC_API_KEY=… GEMINI_API_KEY=… OPENROUTER_API_KEY=… npm test
+```
+
+Without keys the module correctly returns every fallback (`source: 'fallback'`).
+
+---
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * self-healing-models
+ *
+ * Self-healing, failsafe resolver for the current frontier model.
+ */
+
+export type Provider = 'xai' | 'anthropic' | 'gemini' | 'openrouter';
+
+export type ResolveSource = 'live' | 'fallback';
+
+export interface ResolveResult {
+  /** Model ID ready to pass to the provider's chat/completions endpoint */
+  id: string;
+  /** Whether the ID came from a live /models fetch or from a pinned fallback */
+  source: ResolveSource;
+}
+
+export interface ResolveOptions {
+  /** Bypass the in-memory process cache */
+  forceRefresh?: boolean;
+  /** Override the env/hard-coded fallback for this call only */
+  fallback?: string;
+}
+
+/**
+ * Resolve the best model ID for a provider.
+ *
+ * Paid providers use live /models + preference rules (newest non-fast/non-mini).
+ * OpenRouter returns the first currently free model.
+ * On any failure (network, auth, empty list) returns the env-configured fallback
+ * so a transient hiccup never kills a batch job.
+ */
+export function resolveModel(
+  provider: Provider,
+  apiKey: string | undefined | null,
+  options?: ResolveOptions
+): Promise<ResolveResult>;
+
+/**
+ * Fetch (and cache) the set of currently free OpenRouter model IDs.
+ * Drop-in for the classic fetchOrFreeModels() pattern.
+ */
+export function fetchFreeModels(
+  apiKey: string,
+  forceRefresh?: boolean
+): Promise<Set<string>>;
+
+/**
+ * Round-robin through currently available OpenRouter free models.
+ * Drop-in for the classic getNextOrModel() pattern.
+ */
+export function getNextFreeModel(apiKey: string): Promise<string>;
+
+/** Reset the free-model round-robin index (call at the start of a batch). */
+export function resetFreeModelIndex(): void;
+
+/** Clear all in-memory caches (mainly for tests). */
+export function clearCache(): void;
+
+export const DEFAULT_FALLBACKS: Readonly<Record<Provider, string>>;
+
+export const PREFERENCE: Readonly<
+  Record<
+    Exclude<Provider, 'openrouter'>,
+    { include: RegExp; exclude: RegExp }
+  >
+>;

package/index.js

@@ -0,0 +1,272 @@
+/**
+ * failsafe-llm-model-resolver
+ *
+ * Self-healing, failsafe resolver for the current frontier model across
+ * xAI, Anthropic, Gemini, and OpenRouter.
+ *
+ *   resolveModel(provider, apiKey, options?) → Promise<{ id, source: 'live'|'fallback' }>
+ *
+ * Design goals
+ * ────────────
+ * • Live fetch from each provider’s native /models endpoint
+ * • Preference rules:
+ *     – paid providers: regex + “newest first, skip fast/mini/lite/haiku”
+ *     – OpenRouter free: filter pricing.prompt/completion === '0', then round-robin
+ * • In-memory cache per process
+ * • Env-configurable pinned fallbacks so a transient network blip never kills a batch job
+ *
+ * @see https://github.com/prakar/failsafe-llm-model-resolver
+ */
+
+'use strict';
+
+// ---------------------------------------------------------------------------
+// In-memory caches (process lifetime)
+// ---------------------------------------------------------------------------
+const _cache = {
+  xai: null,
+  anthropic: null,
+  gemini: null,
+  openrouter: null,       // full free-model Set
+};
+let _orFreeIdx = 0;       // round-robin index for OpenRouter free models
+
+// ---------------------------------------------------------------------------
+// Defaults / env fallbacks
+// ---------------------------------------------------------------------------
+const DEFAULT_FALLBACKS = {
+  xai:        process.env.XAI_MODEL_FALLBACK        || process.env.GROK_MODEL_FALLBACK        || 'grok-4',
+  anthropic:  process.env.ANTHROPIC_MODEL_FALLBACK  || 'claude-sonnet-4-20250514',
+  gemini:     process.env.GEMINI_MODEL_FALLBACK     || 'gemini-2.5-pro',
+  openrouter: process.env.OPENROUTER_MODEL_FALLBACK || process.env.OPENROUTER_FREE_FALLBACK || 'openrouter/free',
+};
+
+// Preference patterns for paid providers (applied after newest-first ordering)
+const PREFERENCE = {
+  // Prefer flagship grok-*, skip fast / mini / code-fast variants when possible
+  xai: {
+    include: /^grok-/i,
+    exclude: /fast|mini|lite|code-fast/i,
+  },
+  // Prefer sonnet/opus over haiku; newest first already gives us the latest
+  anthropic: {
+    include: /^claude-/i,
+    exclude: /haiku|instant|mini/i,
+  },
+  // Prefer pro / non-flash / non-lite when available
+  gemini: {
+    include: /gemini-/i,
+    exclude: /flash|lite|embedding|aqa|imagen|veo|tts|live/i,
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Tiny fetch helper (native fetch, Node 18+)
+// ---------------------------------------------------------------------------
+async function httpGet(url, headers = {}) {
+  const res = await fetch(url, {
+    method: 'GET',
+    headers: {
+      'Accept': 'application/json',
+      ...headers,
+    },
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throw new Error(`HTTP ${res.status} ${res.statusText}: ${body.slice(0, 200)}`);
+  }
+  return res.json();
+}
+
+// ---------------------------------------------------------------------------
+// Per-provider fetch + normalize → string[] of usable model IDs (newest first)
+// ---------------------------------------------------------------------------
+async function fetchXaiModels(apiKey) {
+  const json = await httpGet('https://api.x.ai/v1/models', {
+    Authorization: `Bearer ${apiKey}`,
+  });
+  // OpenAI-compatible shape: { data: [ { id, ... } ] }
+  const list = (json.data || json.models || []).map(m => m.id || m.name).filter(Boolean);
+  return list;
+}
+
+async function fetchAnthropicModels(apiKey) {
+  const json = await httpGet('https://api.anthropic.com/v1/models', {
+    'x-api-key': apiKey,
+    'anthropic-version': '2023-06-01',
+  });
+  // Newest-first by design. Shape: { data: [ { id, display_name, created_at } ] }
+  const list = (json.data || []).map(m => m.id).filter(Boolean);
+  return list;
+}
+
+async function fetchGeminiModels(apiKey) {
+  // Gemini uses query-string key and a different envelope
+  const url = `https://generativelanguage.googleapis.com/v1beta/models?key=${encodeURIComponent(apiKey)}&pageSize=1000`;
+  const json = await httpGet(url);
+  // Shape: { models: [ { name: "models/gemini-…", … } ] }
+  // The ID used in generateContent is the part after "models/"
+  const list = (json.models || [])
+    .map(m => {
+      const name = m.name || '';
+      return name.startsWith('models/') ? name.slice(7) : name;
+    })
+    .filter(id => id && /generateContent/i.test((m => (m.supportedGenerationMethods || m.supported_actions || []).join(','))(m) || 'generateContent'))
+    .filter(Boolean);
+  return list;
+}
+
+async function fetchOpenRouterFreeModels(apiKey) {
+  const json = await httpGet('https://openrouter.ai/api/v1/models', {
+    Authorization: `Bearer ${apiKey}`,
+  });
+  // Free = pricing.prompt === "0" && pricing.completion === "0" (string or number)
+  const isZero = v => v === 0 || v === '0' || v === '0.0' || v === '0.00';
+  const free = (json.data || [])
+    .filter(m => m.pricing && isZero(m.pricing.prompt) && isZero(m.pricing.completion))
+    .map(m => m.id)
+    .filter(Boolean);
+  return free;
+}
+
+// ---------------------------------------------------------------------------
+// Preference selector (paid providers)
+// ---------------------------------------------------------------------------
+function pickPreferred(ids, rules) {
+  if (!ids || ids.length === 0) return null;
+
+  // 1. Prefer models that match include and do NOT match exclude
+  const preferred = ids.filter(id =>
+    rules.include.test(id) && !rules.exclude.test(id)
+  );
+  if (preferred.length) return preferred[0];
+
+  // 2. Fall back to any that match include (even if they hit exclude)
+  const anyInclude = ids.filter(id => rules.include.test(id));
+  if (anyInclude.length) return anyInclude[0];
+
+  // 3. Absolute last resort: first ID in the list
+  return ids[0];
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the best model ID for a provider.
+ *
+ * @param {'xai'|'anthropic'|'gemini'|'openrouter'} provider
+ * @param {string} apiKey
+ * @param {object} [options]
+ * @param {boolean} [options.forceRefresh=false]  Bypass cache
+ * @param {string}  [options.fallback]            Override env fallback for this call
+ * @returns {Promise<{ id: string, source: 'live'|'fallback' }>}
+ */
+async function resolveModel(provider, apiKey, options = {}) {
+  const p = String(provider || '').toLowerCase();
+  if (!['xai', 'anthropic', 'gemini', 'openrouter'].includes(p)) {
+    throw new Error(`Unknown provider: ${provider}. Expected xai|anthropic|gemini|openrouter`);
+  }
+  if (!apiKey) {
+    // No key → immediate fallback (still useful for offline / test runs)
+    return { id: options.fallback || DEFAULT_FALLBACKS[p], source: 'fallback' };
+  }
+
+  const force = !!options.forceRefresh;
+  const pinned = options.fallback || DEFAULT_FALLBACKS[p];
+
+  try {
+    let id;
+
+    if (p === 'openrouter') {
+      // For the generic resolve we return the first free model (or the fallback).
+      // Callers that want round-robin should use getNextFreeModel().
+      const free = await _getOpenRouterFreeSet(apiKey, force);
+      id = free.size ? Array.from(free)[0] : null;
+    } else {
+      let list = _cache[p];
+      if (!list || force) {
+        if (p === 'xai')        list = await fetchXaiModels(apiKey);
+        if (p === 'anthropic')  list = await fetchAnthropicModels(apiKey);
+        if (p === 'gemini')     list = await fetchGeminiModels(apiKey);
+        _cache[p] = list;
+      }
+      id = pickPreferred(list, PREFERENCE[p]);
+    }
+
+    if (id) return { id, source: 'live' };
+    return { id: pinned, source: 'fallback' };
+  } catch (err) {
+    // Never let a transient network error kill a batch job
+    return { id: pinned, source: 'fallback' };
+  }
+}
+
+/**
+ * Return the cached (or freshly fetched) Set of OpenRouter free model IDs.
+ * Matches the old fetchOrFreeModels() contract.
+ */
+async function fetchFreeModels(apiKey, forceRefresh = false) {
+  return _getOpenRouterFreeSet(apiKey, forceRefresh);
+}
+
+async function _getOpenRouterFreeSet(apiKey, force = false) {
+  if (_cache.openrouter && !force) return _cache.openrouter;
+  try {
+    const ids = await fetchOpenRouterFreeModels(apiKey);
+    _cache.openrouter = new Set(ids);
+    return _cache.openrouter;
+  } catch (e) {
+    // Preserve previous cache if any; otherwise seed with the hard-coded fallback
+    if (!_cache.openrouter) {
+      _cache.openrouter = new Set([DEFAULT_FALLBACKS.openrouter]);
+    }
+    return _cache.openrouter;
+  }
+}
+
+/**
+ * Round-robin through currently available OpenRouter free models.
+ * Drop-in replacement for the legacy getNextOrModel().
+ */
+async function getNextFreeModel(apiKey) {
+  const available = await _getOpenRouterFreeSet(apiKey);
+  if (available.size === 0) return DEFAULT_FALLBACKS.openrouter;
+  const models = Array.from(available);
+  const model = models[_orFreeIdx % models.length];
+  _orFreeIdx = (_orFreeIdx + 1) % models.length;
+  return model;
+}
+
+/**
+ * Reset the free-model round-robin index (useful at the start of a batch).
+ */
+function resetFreeModelIndex() {
+  _orFreeIdx = 0;
+}
+
+/**
+ * Clear all in-memory caches (mainly for tests).
+ */
+function clearCache() {
+  _cache.xai = null;
+  _cache.anthropic = null;
+  _cache.gemini = null;
+  _cache.openrouter = null;
+  _orFreeIdx = 0;
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+module.exports = {
+  resolveModel,
+  fetchFreeModels,
+  getNextFreeModel,
+  resetFreeModelIndex,
+  clearCache,
+  // exposed for advanced callers / tests
+  DEFAULT_FALLBACKS,
+  PREFERENCE,
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "failsafe-llm-model-resolver",
+  "version": "1.0.0",
+  "description": "Self-healing, failsafe resolver for the current frontier model across xAI, Anthropic, Gemini, and OpenRouter. Live /models fetch + preference rules + env fallbacks so a network blip never kills a batch job.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "scripts": {
+    "test": "node smoke-test.js",
+    "smoke": "node smoke-test.js"
+  },
+  "keywords": [
+    "llm",
+    "models",
+    "openai",
+    "anthropic",
+    "claude",
+    "gemini",
+    "xai",
+    "grok",
+    "openrouter",
+    "self-healing",
+    "failover",
+    "fallback",
+    "model-resolver",
+    "frontier"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/prakar/failsafe-llm-model-resolver.git"
+  },
+  "bugs": {
+    "url": "https://github.com/prakar/failsafe-llm-model-resolver/issues"
+  },
+  "homepage": "https://github.com/prakar/failsafe-llm-model-resolver#readme",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ]
+}