@geraldmaron/construct 1.0.0 → 1.0.1

package/lib/model-free-selector.mjs

@@ -0,0 +1,184 @@
+/**
+ * lib/model-free-selector.mjs — Free model polling, scoring, and selection.
+ *
+ * Extracted from model-router.mjs to keep each module under 800 lines.
+ * Polls OpenRouter for free models, scores them by tier, and provides
+ * helpers for free-preference modes (global, same-family).
+ *
+ * Consumed by:
+ *   • bin/construct          – model configuration commands (--auto, --apply).
+ *   • lib/model-router.mjs  – re-exports for backward compatibility.
+ */
+
+const OPENROUTER_MODELS_URL = "https://openrouter.ai/api/v1/models";
+const FETCH_TIMEOUT_MS = 10_000;
+
+/**
+ * Fetch the list of currently available free models from OpenRouter.
+ * Returns an array sorted by descending capability score.
+ * Returns `[]` (with a logged error) if the API key is missing or the request fails.
+ * @param {string} apiKey – OpenRouter bearer token.
+ * @returns {Promise<Array<{id:string,name:string,contextLength:number,isFree:boolean,score:number}>>}
+ */
+export async function pollFreeModels(apiKey) {
+  if (!apiKey) {
+    console.error(
+      "Error: OPENROUTER_API_KEY is not set. Cannot poll free models."
+    );
+    return [];
+  }
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+
+  let data;
+  try {
+    const res = await fetch(OPENROUTER_MODELS_URL, {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      console.error(
+        `Error: OpenRouter models endpoint returned ${res.status} ${res.statusText}`
+      );
+      return [];
+    }
+    data = await res.json();
+  } catch (err) {
+    if (err.name === "AbortError") {
+      console.error(
+        "Error: OpenRouter request timed out after 10 seconds."
+      );
+    } else {
+      console.error(`Error: Failed to fetch OpenRouter models — ${err.message}`);
+    }
+    return [];
+  } finally {
+    clearTimeout(timeout);
+  }
+
+  const models = (data?.data ?? [])
+    .filter(
+      (m) =>
+        m?.pricing?.prompt === "0" && m?.pricing?.completion === "0"
+    )
+    .map((m) => ({
+      id: `openrouter/${m.id}`,
+      name: m.name ?? m.id,
+      contextLength: m.context_length ?? 0,
+      isFree: true,
+    }));
+
+  return models.sort((a, b) => score(b, "standard") - score(a, "standard"));
+}
+
+/**
+ * Score a model for a given tier (higher is better).
+ * @param {object} model – Model object as returned by `pollFreeModels`.
+ * @param {"reasoning"|"standard"|"fast"} tier – The tier to score for.
+ * @returns {number} – Numerical score used for ranking.
+ */
+export function score(model, tier) {
+  const { id, contextLength } = model;
+  let s = 0;
+
+  // Context-length weighting
+  if (contextLength >= 128_000) s += 40;
+  else if (contextLength >= 32_000) s += 20;
+  else if (contextLength >= 16_000) s += 10;
+
+  // Provider-agnostic capability weighting
+  if (id.includes("gemma-4")) s += 30;
+  if (id.includes("gemma-3")) s += 25;
+  if (id.includes("gpt-4o")) s += 25;
+  if (id.includes("nemotron-3-super")) s += 20;
+  if (id.includes("llama-3.3-70b")) s += 20;
+  if (id.includes("qwen3") && contextLength >= 32_000) s += 20;
+  if (id.includes("deepseek-r1")) s += 20;
+  if (id.includes("deepseek-v3")) s += 15;
+  // Extra boost for reasoning-heavy models when the tier is reasoning
+  if (
+    tier === "reasoning" &&
+    (id.includes("deepseek-r1") ||
+      id.includes("nemotron-3-super") ||
+      id.includes("qwen3"))
+  ) {
+    s += 15;
+  }
+
+  return s;
+}
+
+/**
+ * Select the best free model for a given tier from an array of free models.
+ * Falls back to a registry-provided fallback chain if no suitable free model exists.
+ * @param {Array} freeModels – Output of `pollFreeModels`.
+ * @param {"reasoning"|"standard"|"fast"} tier – Target tier.
+ * @param {string[]} [registryFallbacks=[]] – Ordered list of fallback IDs.
+ * @returns {string|null} – Best model ID, or `null` if none found.
+ */
+export function selectForTier(freeModels, tier, registryFallbacks = []) {
+  const minContext = tier === "fast" ? 8_000 : tier === "standard" ? 16_000 : 32_000;
+
+  if (freeModels && freeModels.length > 0) {
+    const candidates = freeModels
+      .filter((m) => m.contextLength >= minContext)
+      .map((m) => ({ ...m, tierScore: score(m, tier) }))
+      .sort((a, b) => b.tierScore - a.tierScore);
+
+    if (candidates[0]?.id) return candidates[0].id;
+  }
+
+  return registryFallbacks[0] ?? null;
+}
+
+/**
+ * Return the top N candidates for a given tier (used for UI lists).
+ * @param {Array} freeModels – Array of model objects.
+ * @param {"reasoning"|"standard"|"fast"} tier – Target tier.
+ * @param {number} n – Number of candidates to return (default = 3).
+ * @returns {Array} – Sorted candidate objects.
+ */
+export function topForTier(freeModels, tier, n = 3) {
+  if (!freeModels || freeModels.length === 0) return [];
+
+  const minContext = tier === "fast" ? 8_000 : tier === "standard" ? 16_000 : 32_000;
+  return freeModels
+    .filter((m) => m.contextLength >= minContext)
+    .map((m) => ({ ...m, tierScore: score(m, tier) }))
+    .sort((a, b) => b.tierScore - a.tierScore)
+    .slice(0, n);
+}
+
+/**
+ * Check if a model ID ends with `:free`.
+ * @param {string} modelId – Model identifier.
+ * @returns {boolean} – True if the model is marked as free.
+ */
+export function isFreeModel(modelId = "") {
+  return /:free$/i.test(modelId);
+}
+
+/**
+ * Choose a free model when multiple candidates exist.
+ * Preference order: explicit primary > fallback > registry default > builtin default.
+ * @param {string} primary – Explicitly selected model.
+ * @param {string} fallback – Second-choice candidate.
+ * @param {string} registryDefault – Default from registry.
+ * @param {string} builtinDefault – Built-in fallback.
+ * @returns {string|null} – The chosen model ID, or `null` if none selected.
+ */
+export function preferFreeValue(
+  primary,
+  fallback,
+  registryDefault,
+  builtinDefault
+) {
+  if (primary && isFreeModel(primary)) return primary;
+  if (fallback && isFreeModel(fallback)) return fallback;
+  if (registryDefault && isFreeModel(registryDefault))
+    return registryDefault;
+  if (builtinDefault && isFreeModel(builtinDefault))
+    return builtinDefault;
+  return primary ?? fallback ?? registryDefault ?? builtinDefault ?? null;
+}

package/lib/model-pricing.mjs

@@ -0,0 +1,152 @@
+/**
+ * lib/model-pricing.mjs — best-effort live pricing for the model selector.
+ *
+ * OpenRouter exposes a free, unauthenticated `GET /api/v1/models` endpoint
+ * with per-1M-token pricing for every model in its catalog. We hit it once
+ * per process (with a 5-minute cache to ~/.cx/model-pricing.json) and fall
+ * back to a built-in pricing table for first-party endpoints (Anthropic,
+ * OpenAI) when their providers aren't proxied through OpenRouter.
+ *
+ * For local providers (ollama, local) we return zero pricing with a
+ * `runs locally` label so the UI can render `free · runs locally` without
+ * any network call.
+ *
+ * Pricing shape: { input: number, output: number, unit: '1M tokens', currency: 'USD', source }.
+ * Numbers are USD per 1M tokens for direct comparability across providers.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const DEFAULT_CACHE_FILE = path.join(os.homedir(), '.cx', 'model-pricing.json');
+const CACHE_TTL_MS = 5 * 60 * 1000;
+const OPENROUTER_ENDPOINT = 'https://openrouter.ai/api/v1/models';
+
+const STATIC_PRICING = {
+  'anthropic/claude-opus-4-6': { input: 15.0, output: 75.0 },
+  'anthropic/claude-sonnet-4-6': { input: 3.0, output: 15.0 },
+  'anthropic/claude-haiku-4-5-20251001': { input: 0.8, output: 4.0 },
+  'openai/gpt-5.4': { input: 12.0, output: 60.0 },
+  'openai/gpt-5.1': { input: 2.5, output: 12.5 },
+  'openai/gpt-5.1-mini': { input: 0.6, output: 3.0 },
+};
+
+const LOCAL_PRICING = { input: 0, output: 0, source: 'local', label: 'free · runs locally' };
+
+function readCache(cacheFile) {
+  try {
+    const raw = fs.readFileSync(cacheFile, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object' && parsed.fetchedAt) return parsed;
+  } catch { /* cache miss */ }
+  return null;
+}
+
+function writeCache(cacheFile, payload) {
+  try {
+    fs.mkdirSync(path.dirname(cacheFile), { recursive: true });
+    fs.writeFileSync(cacheFile, JSON.stringify(payload, null, 2));
+  } catch { /* non-fatal */ }
+}
+
+function isCacheFresh(cache, now = Date.now()) {
+  if (!cache || typeof cache.fetchedAt !== 'number') return false;
+  const age = now - cache.fetchedAt;
+  if (age < 0) return false;
+  return age < CACHE_TTL_MS;
+}
+
+/**
+ * Fetch the OpenRouter catalog. Returns a Map of model id -> { input, output }
+ * in USD per 1M tokens. The endpoint returns pricing per token; we multiply
+ * by 1e6 so callers compare in the same unit as Anthropic / OpenAI lists.
+ */
+async function fetchOpenRouterPricing({ fetchImpl = globalThis.fetch, signal } = {}) {
+  if (typeof fetchImpl !== 'function') return null;
+  let res;
+  try {
+    res = await fetchImpl(OPENROUTER_ENDPOINT, { signal });
+  } catch {
+    return null;
+  }
+  if (!res?.ok) return null;
+  let data;
+  try { data = await res.json(); } catch { return null; }
+  const list = Array.isArray(data?.data) ? data.data : [];
+  const map = {};
+  for (const entry of list) {
+    if (!entry?.id) continue;
+    const p = entry.pricing || {};
+    const input = Number(p.prompt);
+    const output = Number(p.completion);
+    if (!Number.isFinite(input) || !Number.isFinite(output)) continue;
+    map[`openrouter/${entry.id}`] = {
+      input: input * 1_000_000,
+      output: output * 1_000_000,
+      context: entry.context_length || null,
+    };
+  }
+  return map;
+}
+
+/**
+ * Resolve pricing for a list of model ids. Always returns an object keyed by
+ * model id; missing entries map to null so the UI can render an em-dash.
+ */
+export async function getPricingForModels(modelIds, { fetchImpl, signal, now = Date.now(), cacheFile = DEFAULT_CACHE_FILE } = {}) {
+  const result = {};
+  const needsRemote = [];
+  for (const id of modelIds || []) {
+    if (typeof id !== 'string' || !id) continue;
+    if (/^ollama\//.test(id) || /^local\//.test(id)) {
+      result[id] = { ...LOCAL_PRICING, unit: '1M tokens', currency: 'USD' };
+      continue;
+    }
+    if (STATIC_PRICING[id]) {
+      result[id] = { ...STATIC_PRICING[id], unit: '1M tokens', currency: 'USD', source: 'static' };
+      continue;
+    }
+    if (/^openrouter\//.test(id)) {
+      needsRemote.push(id);
+      continue;
+    }
+    result[id] = null;
+  }
+
+  if (needsRemote.length === 0) return result;
+
+  let cache = readCache(cacheFile);
+  if (!isCacheFresh(cache, now)) {
+    const fresh = await fetchOpenRouterPricing({ fetchImpl, signal });
+    if (fresh) {
+      cache = { fetchedAt: now, models: fresh };
+      writeCache(cacheFile, cache);
+    }
+  }
+
+  const remoteMap = cache?.models ?? {};
+  for (const id of needsRemote) {
+    const hit = remoteMap[id];
+    result[id] = hit
+      ? { input: hit.input, output: hit.output, context: hit.context, unit: '1M tokens', currency: 'USD', source: 'openrouter' }
+      : null;
+  }
+  return result;
+}
+
+/**
+ * Format a pricing entry into a compact selector label like
+ * `$3.00 / $15.00 per 1M`. Returns null for missing or all-zero entries so
+ * callers can render `free` or an em-dash without branching on each field.
+ */
+export function formatPricingLabel(entry) {
+  if (!entry) return null;
+  if (entry.source === 'local' || (entry.input === 0 && entry.output === 0)) {
+    return entry.label || 'free · runs locally';
+  }
+  const input = Number(entry.input);
+  const output = Number(entry.output);
+  if (!Number.isFinite(input) || !Number.isFinite(output)) return null;
+  return `$${input.toFixed(2)} in · $${output.toFixed(2)} out / 1M`;
+}

package/lib/model-registry.mjs

@@ -0,0 +1,226 @@
+/**
+ * lib/model-registry.mjs — Single source of truth for model tier resolution.
+ *
+ * Addresses model tier complexity by:
+ * 1. ONE resolution path with clear precedence
+ * 2. Validated at config time, not runtime
+ * 3. Simple env-only overrides for emergencies
+ * 4. Clear error messages when config is missing
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Configuration precedence (single source of truth)
+// ---------------------------------------------------------------------------
+
+/**
+ * RESOLUTION ORDER (highest to lowest):
+ * 1. Environment variables (CX_MODEL_*): Emergency overrides
+ * 2. User config (~/.construct/config.env): Personal defaults
+ * 3. Registry (agents/registry.json): Project recommendations
+ * 4. Built-in defaults: Last resort fallbacks
+ * 
+ * Primary resolution path. All code must use this function.
+ */
+
+const BUILTIN_DEFAULTS = {
+  reasoning: 'anthropic/claude-3-5-sonnet',
+  standard: 'anthropic/claude-3-haiku',
+  fast: 'anthropic/claude-3-haiku',
+};
+
+const ENV_PREFIX = 'CX_MODEL';
+
+// ---------------------------------------------------------------------------
+// Core resolution function
+// ---------------------------------------------------------------------------
+
+export function resolveModelTiers(options = {}) {
+  const { 
+    env = process.env,
+    registryPath = null,
+    strict = false,  // If true, require all tiers to be configured
+  } = options;
+  
+  const result = {
+    reasoning: null,
+    standard: null,
+    fast: null,
+  };
+  
+  const sources = {};
+  const errors = [];
+  
+  for (const tier of ['reasoning', 'standard', 'fast']) {
+    const envKey = `${ENV_PREFIX}_${tier.toUpperCase()}`;
+    
+    // Environment variable (highest priority)
+    if (env[envKey]) {
+      result[tier] = env[envKey];
+      sources[tier] = 'env';
+      continue;
+    }
+    
+    // User config (read from env which was loaded by env-config)
+    const configKey = `CONSTRUCT_MODEL_${tier.toUpperCase()}`;
+    if (env[configKey]) {
+      result[tier] = env[configKey];
+      sources[tier] = 'config';
+      continue;
+    }
+    
+    // Registry
+    if (registryPath && fs.existsSync(registryPath)) {
+      try {
+        const registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+        const registryModel = registry.models?.[tier]?.primary;
+        if (registryModel) {
+          result[tier] = registryModel;
+          sources[tier] = 'registry';
+          continue;
+        }
+      } catch (error) {
+        errors.push(`Failed to read registry: ${error.message}`);
+      }
+    }
+    
+    // Built-in default
+    result[tier] = BUILTIN_DEFAULTS[tier];
+    sources[tier] = 'default';
+  }
+  
+  // Validation
+  const configured = Object.values(result).filter(Boolean).length;
+  
+  if (strict && configured < 3) {
+    const missing = Object.entries(result)
+      .filter(([, v]) => !v)
+      .map(([k]) => k);
+    errors.push(`Missing configuration for tiers: ${missing.join(', ')}`);
+  }
+  
+  return {
+    models: result,
+    sources,
+    configured,
+    complete: configured === 3,
+    errors: errors.length > 0 ? errors : null,
+    defaultsUsed: Object.values(sources).filter(s => s === 'default').length,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Quick access helpers
+// ---------------------------------------------------------------------------
+
+export function getModelForTier(tier, options = {}) {
+  const resolved = resolveModelTiers(options);
+  return resolved.models[tier] || BUILTIN_DEFAULTS[tier];
+}
+
+export function getModelSource(tier, options = {}) {
+  const resolved = resolveModelTiers(options);
+  return resolved.sources[tier] || 'unknown';
+}
+
+// ---------------------------------------------------------------------------
+// Configuration helpers
+// ---------------------------------------------------------------------------
+
+export function validateModelTiers(options = {}) {
+  const resolved = resolveModelTiers({ ...options, strict: true });
+  
+  return {
+    valid: resolved.complete && !resolved.errors,
+    errors: resolved.errors,
+    warnings: resolved.defaultsUsed > 0 
+      ? [`Using ${resolved.defaultsUsed} built-in default(s). Consider configuring custom models.`]
+      : [],
+    resolution: resolved,
+  };
+}
+
+export function formatModelStatus(options = {}) {
+  const resolved = resolveModelTiers(options);
+  
+  let output = 'Model Configuration:\n\n';
+  
+  for (const tier of ['reasoning', 'standard', 'fast']) {
+    const model = resolved.models[tier];
+    const source = resolved.sources[tier];
+    const icon = source === 'default' ? '⚠' : '✓';
+    
+    output += `${icon} ${tier.padEnd(10)} ${model}\n`;
+    output += `  Source: ${source}\n\n`;
+  }
+  
+  if (resolved.defaultsUsed > 0) {
+    output += '\nNote: Using built-in defaults. To customize:\n';
+    output += '  export CX_MODEL_REASONING=your-model\n';
+    output += '  export CX_MODEL_STANDARD=your-model\n';
+    output += '  export CX_MODEL_FAST=your-model\n';
+  }
+  
+  return output;
+}
+
+// ---------------------------------------------------------------------------
+// Backwards compatibility
+// ---------------------------------------------------------------------------
+
+/**
+ * Legacy wrapper for code that expects the old interface.
+ * New code should use resolveModelTiers() directly.
+ */
+export function readCurrentModels(envPath, registryModels = {}) {
+  // Maintains backwards compatibility with existing code
+  // while using the new resolution logic internally
+  
+  const env = {};
+  
+  // Load from env file if provided
+  if (envPath && fs.existsSync(envPath)) {
+    const content = fs.readFileSync(envPath, 'utf8');
+    for (const line of content.split('\n')) {
+      const match = line.match(/^([^=]+)=(.*)$/);
+      if (match) {
+        env[match[1].trim()] = match[2].trim();
+      }
+    }
+  }
+  
+  // Merge with process.env
+  Object.assign(env, process.env);
+  
+  const resolved = resolveModelTiers({ env });
+  
+  // Return in legacy format
+  return {
+    reasoning: resolved.models.reasoning,
+    standard: resolved.models.standard,
+    fast: resolved.models.fast,
+    // Legacy code expects these fields
+    _resolved: resolved,
+  };
+}
+
+export function setTierModel(tier, model, envPath) {
+  // Simplified interface for setting a model
+  // In practice, this should update the user config file
+  
+  if (!['reasoning', 'standard', 'fast'].includes(tier)) {
+    throw new Error(`Invalid tier: ${tier}. Must be reasoning, standard, or fast.`);
+  }
+  
+  const envKey = `${ENV_PREFIX}_${tier.toUpperCase()}`;
+  
+  return {
+    success: true,
+    tier,
+    model,
+    envKey,
+    instruction: `Add to your shell profile: export ${envKey}="${model}"`,
+  };
+}