free-coding-models 0.1.66 → 0.1.68

package/lib/config.js

@@ -28,7 +28,8 @@
  *       "siliconflow":"sk-xxx",
  *       "together":   "together-xxx",
  *       "cloudflare": "cf-xxx",
- *       "perplexity": "pplx-xxx"
+ *       "perplexity": "pplx-xxx",
+ *       "zai":        "zai-xxx"
  *     },
  *     "providers": {
  *       "nvidia":     { "enabled": true },
@@ -47,7 +48,8 @@
  *       "siliconflow":{ "enabled": true },
  *       "together":   { "enabled": true },
  *       "cloudflare": { "enabled": true },
- *       "perplexity": { "enabled": true }
+ *       "perplexity": { "enabled": true },
+ *       "zai":        { "enabled": true }
  *     },
  *     "favorites": [
  *       "nvidia/deepseek-ai/deepseek-v3.2"
@@ -56,9 +58,28 @@
  *       "enabled": true,
  *       "consentVersion": 1,
  *       "anonymousId": "anon_550e8400-e29b-41d4-a716-446655440000"
+ *     "apiKeys": { ... },
+ *     "providers": { ... },
+ *     "favorites": [ "nvidia/deepseek-ai/deepseek-v3.2" ],
+ *     "telemetry": { "enabled": true, "consentVersion": 1, "anonymousId": "anon_..." },
+ *     "activeProfile": "work",
+ *     "profiles": {
+ *       "work":     { "apiKeys": {...}, "providers": {...}, "favorites": [...], "settings": {...} },
+ *       "personal": { "apiKeys": {...}, "providers": {...}, "favorites": [...], "settings": {...} },
+ *       "fast":     { "apiKeys": {...}, "providers": {...}, "favorites": [...], "settings": {...} }
  *     }
  *   }
  *
+ * 📖 Profiles store a snapshot of the user's configuration. Each profile contains:
+ *   - apiKeys: API keys per provider (can differ between work/personal setups)
+ *   - providers: enabled/disabled state per provider
+ *   - favorites: list of pinned favorite models
+ *   - settings: extra TUI preferences (tierFilter, sortColumn, sortAsc, pingInterval)
+ *
+ * 📖 When a profile is loaded via --profile <name> or Shift+P, the main config's
+ *    apiKeys/providers/favorites are replaced with the profile's values. The profile
+ *    data itself stays in the profiles section — it's a named snapshot, not a fork.
+ *
  * 📖 Migration: On first run, if the old plain-text ~/.free-coding-models exists
  *    and the new JSON file does not, the old key is auto-migrated as the nvidia key.
  *    The old file is left in place (not deleted) for safety.
@@ -68,8 +89,17 @@
  *   → saveConfig(config) — Write config to ~/.free-coding-models.json with 0o600 permissions
  *   → getApiKey(config, providerKey) — Get effective API key (env var override > config > null)
  *   → isProviderEnabled(config, providerKey) — Check if provider is enabled (defaults true)
+ *   → saveAsProfile(config, name) — Snapshot current apiKeys/providers/favorites/settings into a named profile
+ *   → loadProfile(config, name) — Apply a named profile's values onto the live config
+ *   → listProfiles(config) — Return array of profile names
+ *   → deleteProfile(config, name) — Remove a named profile
+ *   → getActiveProfileName(config) — Get the currently active profile name (or null)
+ *   → setActiveProfile(config, name) — Set which profile is active (null to clear)
+ *   → _emptyProfileSettings() — Default TUI settings for a profile
  *
- * @exports loadConfig, saveConfig, getApiKey
+ * @exports loadConfig, saveConfig, getApiKey, isProviderEnabled
+ * @exports saveAsProfile, loadProfile, listProfiles, deleteProfile
+ * @exports getActiveProfileName, setActiveProfile
  * @exports CONFIG_PATH — path to the JSON config file
  *
  * @see bin/free-coding-models.js — main CLI that uses these functions
@@ -106,6 +136,7 @@ const ENV_VARS = {
   together:   'TOGETHER_API_KEY',
   cloudflare: ['CLOUDFLARE_API_TOKEN', 'CLOUDFLARE_API_KEY'],
   perplexity: ['PERPLEXITY_API_KEY', 'PPLX_API_KEY'],
+  zai:        'ZAI_API_KEY',
 }
 
 /**
@@ -137,6 +168,9 @@ export function loadConfig() {
       if (typeof parsed.telemetry.enabled !== 'boolean') parsed.telemetry.enabled = null
       if (typeof parsed.telemetry.consentVersion !== 'number') parsed.telemetry.consentVersion = 0
       if (typeof parsed.telemetry.anonymousId !== 'string' || !parsed.telemetry.anonymousId.trim()) parsed.telemetry.anonymousId = null
+      // 📖 Ensure profiles section exists (added in profile system)
+      if (!parsed.profiles || typeof parsed.profiles !== 'object') parsed.profiles = {}
+      if (parsed.activeProfile && typeof parsed.activeProfile !== 'string') parsed.activeProfile = null
       return parsed
     } catch {
       // 📖 Corrupted JSON — return empty config (user will re-enter keys)
@@ -222,6 +256,129 @@ export function isProviderEnabled(config, providerKey) {
   return providerConfig.enabled !== false
 }
 
+// ─── Config Profiles ──────────────────────────────────────────────────────────
+
+/**
+ * 📖 _emptyProfileSettings: Default TUI settings stored in a profile.
+ *
+ * 📖 These settings are saved/restored when switching profiles so each profile
+ *    can have different sort, filter, and ping preferences.
+ *
+ * @returns {{ tierFilter: string|null, sortColumn: string, sortAsc: boolean, pingInterval: number }}
+ */
+export function _emptyProfileSettings() {
+  return {
+    tierFilter: null,     // 📖 null = show all tiers, or 'S'|'A'|'B'|'C'|'D'
+    sortColumn: 'avg',    // 📖 default sort column
+    sortAsc: true,        // 📖 true = ascending (fastest first for latency)
+    pingInterval: 8000,   // 📖 default ms between pings
+  }
+}
+
+/**
+ * 📖 saveAsProfile: Snapshot the current config state into a named profile.
+ *
+ * 📖 Takes the current apiKeys, providers, favorites, plus explicit TUI settings
+ *    and stores them under config.profiles[name]. Does NOT change activeProfile —
+ *    call setActiveProfile() separately if you want to switch to this profile.
+ *
+ * 📖 If a profile with the same name exists, it's overwritten.
+ *
+ * @param {object} config — Live config object (will be mutated)
+ * @param {string} name — Profile name (e.g. 'work', 'personal', 'fast')
+ * @param {object} [settings] — TUI settings to save (tierFilter, sortColumn, etc.)
+ * @returns {object} The config object (for chaining)
+ */
+export function saveAsProfile(config, name, settings = null) {
+  if (!config.profiles || typeof config.profiles !== 'object') config.profiles = {}
+  config.profiles[name] = {
+    apiKeys: JSON.parse(JSON.stringify(config.apiKeys || {})),
+    providers: JSON.parse(JSON.stringify(config.providers || {})),
+    favorites: [...(config.favorites || [])],
+    settings: settings ? { ..._emptyProfileSettings(), ...settings } : _emptyProfileSettings(),
+  }
+  return config
+}
+
+/**
+ * 📖 loadProfile: Apply a named profile's values onto the live config.
+ *
+ * 📖 Replaces config.apiKeys, config.providers, config.favorites with the
+ *    profile's stored values. Also sets config.activeProfile to the loaded name.
+ *
+ * 📖 Returns the profile's TUI settings so the caller (main CLI) can apply them
+ *    to the live state object (sortColumn, tierFilter, etc.).
+ *
+ * 📖 If the profile doesn't exist, returns null (caller should show an error).
+ *
+ * @param {object} config — Live config object (will be mutated)
+ * @param {string} name — Profile name to load
+ * @returns {{ tierFilter: string|null, sortColumn: string, sortAsc: boolean, pingInterval: number }|null}
+ *          The profile's TUI settings, or null if profile not found
+ */
+export function loadProfile(config, name) {
+  const profile = config?.profiles?.[name]
+  if (!profile) return null
+
+  // 📖 Deep-copy the profile data into the live config (don't share references)
+  config.apiKeys = JSON.parse(JSON.stringify(profile.apiKeys || {}))
+  config.providers = JSON.parse(JSON.stringify(profile.providers || {}))
+  config.favorites = [...(profile.favorites || [])]
+  config.activeProfile = name
+
+  return profile.settings ? { ..._emptyProfileSettings(), ...profile.settings } : _emptyProfileSettings()
+}
+
+/**
+ * 📖 listProfiles: Get all saved profile names.
+ *
+ * @param {object} config
+ * @returns {string[]} Array of profile names, sorted alphabetically
+ */
+export function listProfiles(config) {
+  if (!config?.profiles || typeof config.profiles !== 'object') return []
+  return Object.keys(config.profiles).sort()
+}
+
+/**
+ * 📖 deleteProfile: Remove a named profile from the config.
+ *
+ * 📖 If the deleted profile is the active one, clears activeProfile.
+ *
+ * @param {object} config — Live config object (will be mutated)
+ * @param {string} name — Profile name to delete
+ * @returns {boolean} True if the profile existed and was deleted
+ */
+export function deleteProfile(config, name) {
+  if (!config?.profiles?.[name]) return false
+  delete config.profiles[name]
+  if (config.activeProfile === name) config.activeProfile = null
+  return true
+}
+
+/**
+ * 📖 getActiveProfileName: Get the currently active profile name.
+ *
+ * @param {object} config
+ * @returns {string|null} Profile name, or null if no profile is active
+ */
+export function getActiveProfileName(config) {
+  return config?.activeProfile || null
+}
+
+/**
+ * 📖 setActiveProfile: Set which profile is active (or null to clear).
+ *
+ * 📖 This just stores the name — it does NOT load the profile's data.
+ *    Call loadProfile() first to actually apply the profile's values.
+ *
+ * @param {object} config — Live config object (will be mutated)
+ * @param {string|null} name — Profile name, or null to clear
+ */
+export function setActiveProfile(config, name) {
+  config.activeProfile = name || null
+}
+
 // 📖 Internal helper: create a blank config with the right shape
 function _emptyConfig() {
   return {
@@ -235,5 +392,9 @@ function _emptyConfig() {
       consentVersion: 0,
       anonymousId: null,
     },
+    // 📖 Active profile name — null means no profile is loaded (using raw config).
+    activeProfile: null,
+    // 📖 Named profiles: each is a snapshot of apiKeys + providers + favorites + settings.
+    profiles: {},
   }
 }

package/lib/utils.js

@@ -27,15 +27,20 @@
  *
  * @functions
  *   → getAvg(result) — Calculate average latency from successful pings only
- *   → getVerdict(result) — Determine model health verdict based on avg latency and status
+ *   → getVerdict(result) — Determine model health verdict based on avg latency and stability
  *   → getUptime(result) — Calculate uptime percentage (successful / total pings)
+ *   → getP95(result) — Calculate 95th percentile latency from successful pings
+ *   → getJitter(result) — Calculate latency standard deviation (jitter)
+ *   → getStabilityScore(result) — Composite 0–100 stability score (p95 + jitter + spikes + uptime)
  *   → sortResults(results, sortColumn, sortDirection) — Sort model results by any column
  *   → filterByTier(results, tierLetter) — Filter results by tier letter (S/A/B/C)
- *   → findBestModel(results) — Pick the best model by status → avg → uptime priority
+ *   → findBestModel(results) — Pick the best model by status → avg → stability → uptime priority
  *   → parseArgs(argv) — Parse CLI arguments into structured flags and values
  *
- * @exports getAvg, getVerdict, getUptime, sortResults, filterByTier, findBestModel, parseArgs
- * @exports TIER_ORDER, VERDICT_ORDER, TIER_LETTER_MAP
+ * @exports getAvg, getVerdict, getUptime, getP95, getJitter, getStabilityScore
+ * @exports sortResults, filterByTier, findBestModel, parseArgs
+ * @exports scoreModelForTask, getTopRecommendations
+ * @exports TIER_ORDER, VERDICT_ORDER, TIER_LETTER_MAP, TASK_TYPES, PRIORITY_TYPES, CONTEXT_BUDGETS
  *
  * @see bin/free-coding-models.js — main CLI that imports these utils
  * @see sources.js — model definitions consumed by these functions
@@ -54,7 +59,7 @@ export const TIER_ORDER = ['S+', 'S', 'A+', 'A', 'A-', 'B+', 'B', 'C']
 // 📖 Used by sortResults when sorting by the "verdict" column.
 // 📖 "Perfect" means < 400ms avg, "Pending" means no data yet.
 // 📖 The order matters — it determines sort rank in the TUI table.
-export const VERDICT_ORDER = ['Perfect', 'Normal', 'Slow', 'Very Slow', 'Overloaded', 'Unstable', 'Not Active', 'Pending']
+export const VERDICT_ORDER = ['Perfect', 'Normal', 'Slow', 'Spiky', 'Very Slow', 'Overloaded', 'Unstable', 'Not Active', 'Pending']
 
 // 📖 Maps a CLI tier letter (--tier S/A/B/C) to the full tier strings it includes.
 // 📖 Example: --tier A matches A+, A, and A- models (all "A-family" tiers).
@@ -91,11 +96,17 @@ export const getAvg = (r) => {
 //   2. Timeout/down BUT was previously up → "Unstable" (it worked before, now it doesn't)
 //   3. Timeout/down and never worked → "Not Active" (model might be offline)
 //   4. No successful pings yet → "Pending" (still waiting for first response)
-//   5. Avg < 400ms → "Perfect"
-//   6. Avg < 1000ms → "Normal"
-//   7. Avg < 3000ms → "Slow"
-//   8. Avg < 5000ms → "Very Slow"
-//   9. Avg >= 5000ms → "Unstable"
+//   5. Stability-aware speed tiers (avg + p95/jitter penalty):
+//      - Avg < 400ms + stable → "Perfect"
+//      - Avg < 400ms but spiky p95 → "Spiky" (fast on average, but tail latency hurts)
+//      - Avg < 1000ms → "Normal"
+//      - Avg < 3000ms → "Slow"
+//      - Avg < 5000ms → "Very Slow"
+//      - Avg >= 5000ms → "Unstable"
+//
+// 📖 The "Spiky" verdict catches models that look fast on paper (low avg) but randomly
+//    stall your IDE/agent with tail-latency spikes. A model with avg 250ms but p95 6000ms
+//    gets downgraded from "Perfect" to "Spiky" — because consistency matters more than speed.
 //
 // 📖 The "wasUpBefore" check is key — it distinguishes between a model that's
 //    temporarily flaky vs one that was never reachable in the first place.
@@ -107,8 +118,20 @@ export const getVerdict = (r) => {
   if ((r.status === 'timeout' || r.status === 'down') && wasUpBefore) return 'Unstable'
   if (r.status === 'timeout' || r.status === 'down') return 'Not Active'
   if (avg === Infinity) return 'Pending'
-  if (avg < 400) return 'Perfect'
-  if (avg < 1000) return 'Normal'
+
+  // 📖 Stability-aware verdict: penalize models with good avg but terrible tail latency
+  const successfulPings = (r.pings || []).filter(p => p.code === '200')
+  const p95 = getP95(r)
+
+  if (avg < 400) {
+    // 📖 Only flag as "Spiky" when we have enough data (≥3 pings) to judge stability
+    if (successfulPings.length >= 3 && p95 > 3000) return 'Spiky'
+    return 'Perfect'
+  }
+  if (avg < 1000) {
+    if (successfulPings.length >= 3 && p95 > 5000) return 'Spiky'
+    return 'Normal'
+  }
   if (avg < 3000) return 'Slow'
   if (avg < 5000) return 'Very Slow'
   if (avg < 10000) return 'Unstable'
@@ -125,21 +148,84 @@ export const getUptime = (r) => {
   return Math.round((successful / r.pings.length) * 100)
 }
 
+// 📖 getP95: Calculate the 95th percentile latency from successful pings (HTTP 200).
+// 📖 The p95 answers: "95% of requests are faster than this value."
+// 📖 A low p95 means consistently fast responses — a high p95 signals tail-latency spikes.
+// 📖 Returns Infinity when no successful pings exist.
+//
+// 📖 Algorithm: sort latencies ascending, pick the value at ceil(N * 0.95) - 1.
+// 📖 Example: [100, 200, 300, 400, 5000] → p95 index = ceil(5 * 0.95) - 1 = 4 → 5000ms
+export const getP95 = (r) => {
+  const successfulPings = (r.pings || []).filter(p => p.code === '200')
+  if (successfulPings.length === 0) return Infinity
+  const sorted = successfulPings.map(p => p.ms).sort((a, b) => a - b)
+  const idx = Math.ceil(sorted.length * 0.95) - 1
+  return sorted[Math.max(0, idx)]
+}
+
+// 📖 getJitter: Calculate latency standard deviation (σ) from successful pings.
+// 📖 Low jitter = predictable response times. High jitter = erratic, spiky latency.
+// 📖 Returns 0 when fewer than 2 successful pings (can't compute variance from 1 point).
+// 📖 Uses population σ (divides by N, not N-1) since we have ALL the data, not a sample.
+export const getJitter = (r) => {
+  const successfulPings = (r.pings || []).filter(p => p.code === '200')
+  if (successfulPings.length < 2) return 0
+  const mean = successfulPings.reduce((a, b) => a + b.ms, 0) / successfulPings.length
+  const variance = successfulPings.reduce((sum, p) => sum + (p.ms - mean) ** 2, 0) / successfulPings.length
+  return Math.round(Math.sqrt(variance))
+}
+
+// 📖 getStabilityScore: Composite 0–100 score that rewards consistency and reliability.
+// 📖 Combines four signals into a single number:
+//   - p95 latency (30%) — penalizes tail-latency spikes
+//   - Jitter / σ (30%) — penalizes erratic response times
+//   - Spike rate (20%) — fraction of pings above 3000ms threshold
+//   - Uptime / reliability (20%) — fraction of successful pings
+//
+// 📖 Each component is normalized to 0–100, then weighted and combined.
+// 📖 Returns -1 when no successful pings exist (not enough data yet).
+//
+// 📖 Example:
+//   Model A: avg 250ms, p95 6000ms (tons of spikes) → score ~30
+//   Model B: avg 400ms, p95 650ms (boringly consistent) → score ~85
+//   In real usage, Model B FEELS faster because it doesn't randomly stall.
+export const getStabilityScore = (r) => {
+  const successfulPings = (r.pings || []).filter(p => p.code === '200')
+  if (successfulPings.length === 0) return -1
+
+  const p95 = getP95(r)
+  const jitter = getJitter(r)
+  const uptime = getUptime(r)
+  const spikeCount = successfulPings.filter(p => p.ms > 3000).length
+  const spikeRate = spikeCount / successfulPings.length
+
+  // 📖 Normalize each component to 0–100 (higher = better)
+  const p95Score = Math.max(0, Math.min(100, 100 * (1 - p95 / 5000)))
+  const jitterScore = Math.max(0, Math.min(100, 100 * (1 - jitter / 2000)))
+  const spikeScore = Math.max(0, 100 * (1 - spikeRate))
+  const reliabilityScore = uptime
+
+  // 📖 Weighted composite: 30% p95, 30% jitter, 20% spikes, 20% reliability
+  const score = 0.3 * p95Score + 0.3 * jitterScore + 0.2 * spikeScore + 0.2 * reliabilityScore
+  return Math.round(score)
+}
+
 // 📖 sortResults: Sort the results array by any column the user can click/press in the TUI.
 // 📖 Returns a NEW array — never mutates the original (important for React-style re-renders).
 //
 // 📖 Supported columns (matching the keyboard shortcuts in the TUI):
-//   - 'rank'    (R key) — original index from sources.js
-//   - 'tier'    (T key) — tier hierarchy (S+ first, C last)
-//   - 'origin'  (O key) — provider name (all NIM for now, future-proofed)
-//   - 'model'   (M key) — alphabetical by display label
-//   - 'ping'    (L key) — last ping latency (only successful ones count)
-//   - 'avg'     (A key) — average latency across all successful pings
-//   - 'swe'     (S key) — SWE-bench score (higher is better)
-//   - 'ctx'     (N key) — context window size (larger is better)
-//   - 'condition' (H key) — health status (alphabetical)
-//   - 'verdict' (V key) — verdict order (Perfect → Pending)
-//   - 'uptime'  (U key) — uptime percentage
+//   - 'rank'      (R key) — original index from sources.js
+//   - 'tier'      (T key) — tier hierarchy (S+ first, C last)
+//   - 'origin'    (O key) — provider name (all NIM for now, future-proofed)
+//   - 'model'     (M key) — alphabetical by display label
+//   - 'ping'      (L key) — last ping latency (only successful ones count)
+//   - 'avg'       (A key) — average latency across all successful pings
+//   - 'swe'       (S key) — SWE-bench score (higher is better)
+//   - 'ctx'       (N key) — context window size (larger is better)
+//   - 'condition'  (H key) — health status (alphabetical)
+//   - 'verdict'   (V key) — verdict order (Perfect → Pending)
+//   - 'uptime'    (U key) — uptime percentage
+//   - 'stability' (B key) — stability score (0–100, higher = more stable)
 //
 // 📖 sortDirection 'asc' = ascending (smallest first), 'desc' = descending (largest first)
 export const sortResults = (results, sortColumn, sortDirection) => {
@@ -219,6 +305,11 @@ export const sortResults = (results, sortColumn, sortDirection) => {
       case 'uptime':
         cmp = getUptime(a) - getUptime(b)
         break
+      case 'stability':
+        // 📖 Sort by stability score — higher = more stable = better
+        // 📖 Models with no data (-1) sort to the bottom
+        cmp = getStabilityScore(a) - getStabilityScore(b)
+        break
     }
 
     // 📖 Flip comparison for descending order
@@ -242,16 +333,19 @@ export function filterByTier(results, tierLetter) {
 // 📖 findBestModel: Pick the single best model from a results array.
 // 📖 Used by --fiable mode to output the most reliable model after 10s of analysis.
 //
-// 📖 Selection priority (tri-key sort):
+// 📖 Selection priority (quad-key sort):
 //   1. Status: "up" models always beat non-up models
 //   2. Average latency: faster average wins (lower is better)
-//   3. Uptime %: higher uptime wins as tiebreaker
+//   3. Stability score: higher stability wins (more consistent = better)
+//   4. Uptime %: higher uptime wins as final tiebreaker
 //
 // 📖 Returns null if the array is empty.
 export function findBestModel(results) {
   const sorted = [...results].sort((a, b) => {
     const avgA = getAvg(a)
     const avgB = getAvg(b)
+    const stabilityA = getStabilityScore(a)
+    const stabilityB = getStabilityScore(b)
     const uptimeA = getUptime(a)
     const uptimeB = getUptime(b)
 
@@ -262,7 +356,10 @@ export function findBestModel(results) {
     // 📖 Priority 2: Lower average latency = faster = better
     if (avgA !== avgB) return avgA - avgB
 
-    // 📖 Priority 3: Higher uptime = more reliable = better (tiebreaker)
+    // 📖 Priority 3: Higher stability = more consistent = better
+    if (stabilityA !== stabilityB) return stabilityB - stabilityA
+
+    // 📖 Priority 4: Higher uptime = more reliable = better (final tiebreaker)
     return uptimeB - uptimeA
   })
 
@@ -289,17 +386,27 @@ export function parseArgs(argv) {
   let apiKey = null
   const flags = []
 
-  // Determine which arg index is consumed by --tier so we skip it
+  // 📖 Determine which arg indices are consumed by --tier and --profile so we skip them
   const tierIdx = args.findIndex(a => a.toLowerCase() === '--tier')
   const tierValueIdx = (tierIdx !== -1 && args[tierIdx + 1] && !args[tierIdx + 1].startsWith('--'))
     ? tierIdx + 1
     : -1
 
+  const profileIdx = args.findIndex(a => a.toLowerCase() === '--profile')
+  const profileValueIdx = (profileIdx !== -1 && args[profileIdx + 1] && !args[profileIdx + 1].startsWith('--'))
+    ? profileIdx + 1
+    : -1
+
+  // 📖 Set of arg indices that are values for flags (not API keys)
+  const skipIndices = new Set()
+  if (tierValueIdx !== -1) skipIndices.add(tierValueIdx)
+  if (profileValueIdx !== -1) skipIndices.add(profileValueIdx)
+
   for (const [i, arg] of args.entries()) {
     if (arg.startsWith('--')) {
       flags.push(arg.toLowerCase())
-    } else if (i === tierValueIdx) {
-      // Skip -- this is the --tier value, not an API key
+    } else if (skipIndices.has(i)) {
+      // 📖 Skip — this is a value for --tier or --profile, not an API key
     } else if (!apiKey) {
       apiKey = arg
     }
@@ -314,5 +421,161 @@ export function parseArgs(argv) {
 
   let tierFilter = tierValueIdx !== -1 ? args[tierValueIdx].toUpperCase() : null
 
-  return { apiKey, bestMode, fiableMode, openCodeMode, openCodeDesktopMode, openClawMode, noTelemetry, tierFilter }
+  const profileName = profileValueIdx !== -1 ? args[profileValueIdx] : null
+
+  // 📖 --recommend — launch directly into Smart Recommend mode (Q key equivalent)
+  const recommendMode = flags.includes('--recommend')
+
+  return { apiKey, bestMode, fiableMode, openCodeMode, openCodeDesktopMode, openClawMode, noTelemetry, tierFilter, profileName, recommendMode }
+}
+
+// ─── Smart Recommend — Scoring Engine ─────────────────────────────────────────
+
+// 📖 Task types for the Smart Recommend questionnaire.
+// 📖 Each task type has different weight priorities — quick fixes favor speed,
+//    deep refactors favor SWE score and context, code review needs balanced quality,
+//    test generation needs high SWE score + medium context.
+export const TASK_TYPES = {
+  quickfix:    { label: 'Quick Fix',       sweWeight: 0.2, speedWeight: 0.5, ctxWeight: 0.1, stabilityWeight: 0.2 },
+  refactor:    { label: 'Deep Refactor',   sweWeight: 0.4, speedWeight: 0.1, ctxWeight: 0.3, stabilityWeight: 0.2 },
+  review:      { label: 'Code Review',     sweWeight: 0.35, speedWeight: 0.2, ctxWeight: 0.25, stabilityWeight: 0.2 },
+  testgen:     { label: 'Test Generation', sweWeight: 0.35, speedWeight: 0.15, ctxWeight: 0.2, stabilityWeight: 0.3 },
+}
+
+// 📖 Priority presets — bias the scoring toward speed or quality.
+// 📖 'speed' amplifies latency weighting, 'quality' amplifies SWE score weighting.
+export const PRIORITY_TYPES = {
+  speed:   { label: 'Speed',   speedMultiplier: 1.5, sweMultiplier: 0.7 },
+  quality: { label: 'Quality', speedMultiplier: 0.7, sweMultiplier: 1.5 },
+  balanced:{ label: 'Balanced', speedMultiplier: 1.0, sweMultiplier: 1.0 },
+}
+
+// 📖 Context budget categories — match against model's context window size.
+// 📖 'small' (<4K tokens) can use any model. 'large' (>32K) strongly penalizes small-ctx models.
+export const CONTEXT_BUDGETS = {
+  small:  { label: 'Small file (<4K)',      minCtx: 0,     idealCtx: 32 },
+  medium: { label: 'Medium project (<32K)', minCtx: 32,    idealCtx: 128 },
+  large:  { label: 'Large codebase (>32K)', minCtx: 128,   idealCtx: 256 },
+}
+
+// 📖 parseCtxToK: Convert context window string ("128k", "1m", "200k") into numeric K tokens.
+// 📖 Used by the scoring engine to compare against CONTEXT_BUDGETS thresholds.
+function parseCtxToK(ctx) {
+  if (!ctx || ctx === '—') return 0
+  const str = ctx.toLowerCase()
+  if (str.includes('m')) return parseFloat(str.replace('m', '')) * 1000
+  if (str.includes('k')) return parseFloat(str.replace('k', ''))
+  return 0
+}
+
+// 📖 parseSweToNum: Convert SWE-bench score string ("49.2%", "73.1%") into a 0–100 number.
+// 📖 Returns 0 for missing or invalid scores.
+function parseSweToNum(sweScore) {
+  if (!sweScore || sweScore === '—') return 0
+  const num = parseFloat(sweScore.replace('%', ''))
+  return isNaN(num) ? 0 : num
+}
+
+/**
+ * 📖 scoreModelForTask: Score a single model result for a specific task/priority/context combination.
+ *
+ * 📖 The score is a weighted composite of 4 signals:
+ *   - SWE quality score (0–100): how good the model is at coding (from sources.js benchmarks)
+ *   - Speed score (0–100): inverse of average latency (faster = higher score)
+ *   - Context fit score (0–100): how well the model's context window matches the user's budget
+ *   - Stability score (0–100): composite p95/jitter/uptime from getStabilityScore()
+ *
+ * 📖 Each signal is weighted by the task type, then further adjusted by the priority multiplier.
+ * 📖 Models that are down/timeout get a harsh penalty but aren't completely excluded
+ *    (they might come back up during the analysis phase).
+ *
+ * @param {object} result — A model result object (from state.results)
+ * @param {string} taskType — Key from TASK_TYPES ('quickfix'|'refactor'|'review'|'testgen')
+ * @param {string} priority — Key from PRIORITY_TYPES ('speed'|'quality'|'balanced')
+ * @param {string} contextBudget — Key from CONTEXT_BUDGETS ('small'|'medium'|'large')
+ * @returns {number} Score between 0 and 100 (higher = better recommendation)
+ */
+export function scoreModelForTask(result, taskType, priority, contextBudget) {
+  const task = TASK_TYPES[taskType]
+  const prio = PRIORITY_TYPES[priority]
+  const budget = CONTEXT_BUDGETS[contextBudget]
+  if (!task || !prio || !budget) return 0
+
+  // 📖 SWE quality signal (0–100) — raw SWE-bench score
+  const sweNum = parseSweToNum(result.sweScore)
+  const sweScore = Math.min(100, sweNum * (100 / 80)) // 📖 Normalize: 80% SWE → 100 score
+
+  // 📖 Speed signal (0–100) — inverse latency, capped at 5000ms
+  const avg = getAvg(result)
+  let speedScore
+  if (avg === Infinity) {
+    speedScore = 0 // 📖 No data yet — can't judge speed
+  } else {
+    speedScore = Math.max(0, Math.min(100, 100 * (1 - avg / 5000)))
+  }
+
+  // 📖 Context fit signal (0–100):
+  //   - Full score if model ctx >= idealCtx
+  //   - Partial score if model ctx >= minCtx but < idealCtx (linear interpolation)
+  //   - Zero if model ctx < minCtx (too small for the job)
+  const modelCtx = parseCtxToK(result.ctx)
+  let ctxScore
+  if (modelCtx >= budget.idealCtx) {
+    ctxScore = 100
+  } else if (modelCtx >= budget.minCtx) {
+    ctxScore = budget.idealCtx === budget.minCtx
+      ? 100
+      : Math.round(100 * (modelCtx - budget.minCtx) / (budget.idealCtx - budget.minCtx))
+  } else {
+    ctxScore = 0
+  }
+
+  // 📖 Stability signal (0–100) — from getStabilityScore(), or 0 if no data
+  const stability = getStabilityScore(result)
+  const stabScore = stability === -1 ? 0 : stability
+
+  // 📖 Weighted combination: task weights × priority multipliers
+  const rawScore =
+    (sweScore   * task.sweWeight       * prio.sweMultiplier) +
+    (speedScore * task.speedWeight     * prio.speedMultiplier) +
+    (ctxScore   * task.ctxWeight) +
+    (stabScore  * task.stabilityWeight)
+
+  // 📖 Normalize by total effective weight to keep result in 0–100 range
+  const totalWeight =
+    (task.sweWeight   * prio.sweMultiplier) +
+    (task.speedWeight * prio.speedMultiplier) +
+    task.ctxWeight +
+    task.stabilityWeight
+
+  let score = totalWeight > 0 ? rawScore / totalWeight : 0
+
+  // 📖 Penalty for models that are currently down/timeout — still scoreable but penalized
+  if (result.status === 'down' || result.status === 'timeout') {
+    score *= 0.2
+  }
+
+  return Math.round(Math.min(100, Math.max(0, score)))
+}
+
+/**
+ * 📖 getTopRecommendations: Score all models and return the top N recommendations.
+ *
+ * 📖 Filters out hidden models, scores each one, sorts descending, returns topN.
+ * 📖 Each returned item includes the original result + computed score for display.
+ *
+ * @param {Array} results — Full state.results array
+ * @param {string} taskType — Key from TASK_TYPES
+ * @param {string} priority — Key from PRIORITY_TYPES
+ * @param {string} contextBudget — Key from CONTEXT_BUDGETS
+ * @param {number} [topN=3] — How many recommendations to return
+ * @returns {Array<{result: object, score: number}>} Top N scored models, descending by score
+ */
+export function getTopRecommendations(results, taskType, priority, contextBudget, topN = 3) {
+  const scored = results
+    .filter(r => !r.hidden)
+    .map(r => ({ result: r, score: scoreModelForTask(r, taskType, priority, contextBudget) }))
+    .sort((a, b) => b.score - a.score)
+
+  return scored.slice(0, topN)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.1.66",
+  "version": "0.1.68",
   "description": "Find the fastest coding LLM models in seconds — ping free models from multiple providers, pick the best one for OpenCode, Cursor, or any AI coding assistant.",
   "keywords": [
     "nvidia",