free-coding-models 0.3.6 → 0.3.9

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ---
 
+## 0.3.9
+
+### Improved
+- **Enhanced `--premium` flag**: Now applies strict elite-only constraints. Shows only **S/S+** tier models with perfect health (**UP**) and a good verdict (**Perfect**, **Normal**, or **Slow**). Models with 429 errors, auth failures, or poor performance are automatically hidden.
+- **Accurate Token Usage Tracking**: The "Used" column now uses the persistent `token-stats.json` file as the source of truth, providing accurate historical totals instead of only the most recent logs.
+- **Enhanced Log Transparency**: The request log page now always shows the requested model and the actual upstream model (e.g., `llama-3.1-405b → meta/llama-3.1-405b-instruct`) whenever they differ.
+- **Pretty Provider Labels**: The request log page now uses human-readable provider labels (e.g., "NVIDIA NIM", "SambaNova") instead of raw internal keys.
+- **Fixed Tier Filtering Family Logic**: Updated `--tier S` behavior to correctly include both **S** and **S+** models (matching documentation).
+
+---
+
 ## 0.3.6
 
 ### Added

package/README.md

@@ -200,6 +200,30 @@ free-coding-models
 # Explicitly target OpenCode CLI (TUI + Enter launches OpenCode CLI)
 free-coding-models --opencode
 
+## 📋 CLI Flags (expanded)
+
+The tool now supports a comprehensive set of flags to fine‑tune its behavior. All flags can be combined in any order.
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--best` | boolean | Show only top‑tier models (A+, S, S+). |
+| `--fiable` | boolean | Run a 10 s reliability analysis and output the most reliable model. |
+| `--json` | boolean | Output results as JSON for scripting/automation. |
+| `--tier <S|A|B|C>` | value | Filter models by tier family (e.g. `S` shows S+ and S). |
+| `--recommend` | boolean | Open Smart Recommend mode immediately on startup. |
+| `--sort <column>` | value | Sort by a specific column (`rank`, `tier`, `origin`, `model`, `ping`, `avg`, `swe`, `ctx`, `condition`, `verdict`, `uptime`, `stability`, `usage`). |
+| `--desc` / `--asc` | boolean | Set sort direction explicitly (descending or ascending). |
+| `--origin <provider>` | value | Filter models by provider origin (e.g. `nvidia`, `groq`). |
+| `--ping-interval <ms>` | value | Override the ping interval in milliseconds (affects live monitoring speed). |
+| `--hide-unconfigured` | boolean | Hide models whose providers have no configured API key. |
+| `--show-unconfigured` | boolean | Show all models regardless of API key configuration. |
+| `--disable-widths-warning` | boolean | Disable the terminal width warning banner. |
+| `--profile <name>` | value | Load a saved configuration profile before startup. |
+| `--no-telemetry` | boolean | Disable anonymous telemetry for this run. |
+| `--clean-proxy`, `--proxy-clean` | boolean | Remove persisted FCM proxy configuration from OpenCode. |
+| `--help`, `-h` | boolean | Print the complete help text and exit. |
+
+These flags are also reflected in the built‑in help (`free-coding-models --help`).
 # Explicitly target OpenCode Desktop (TUI + Enter sets model & opens Desktop app)
 free-coding-models --opencode-desktop
 
@@ -920,6 +944,25 @@ This script:
 
 ## 📋 API Reference
 
+### 🎁 Premium Flag
+
+The `--premium` flag provides a quick view of only the elite **S/S+ tier** models with perfect health (**UP**) and a good verdict (**Perfect**, **Normal**, or **Slow**). This is useful when you want to focus exclusively on the highest‑quality, most reliable models that are currently available.
+
+```bash
+free-coding-models --premium
+```
+
+What it does under the hood:
+- Sets `tierFilter` to `S` (showing only S+ and S tier models).
+- Filters out any model that is not currently **UP** (hides 429, 410, auth fail, timeouts, etc.).
+- Filters out models with poor verdicts (hides **Spiky**, **Very Slow**, **Overloaded**, **Unstable**, etc.).
+- Forces the sort column to `verdict` with ascending order, so the best‑rated models appear at the top.
+- Leaves other settings untouched, so you can still combine it with flags like `--json` for scripting.
+
+You can combine `--premium` with other flags (e.g., `--json --hide-unconfigured`) to further tailor the output.
+
+---
+
 **Environment variables (override config file):**
 
 | Variable | Description |

package/bin/free-coding-models.js

@@ -203,6 +203,22 @@ async function main() {
     // 📖 User declined auto-fix or it failed — continue anyway, just warned
   }
 
+  // 📖 Apply CLI overrides for settings
+  if (cliArgs.sortColumn) config.settings.sortColumn = cliArgs.sortColumn
+  if (cliArgs.sortDirection) config.settings.sortAsc = cliArgs.sortDirection === 'asc'
+  if (cliArgs.originFilter) config.settings.originFilter = cliArgs.originFilter
+  if (cliArgs.pingInterval) config.settings.pingInterval = cliArgs.pingInterval
+  if (cliArgs.hideUnconfigured) config.settings.hideUnconfiguredModels = true
+  if (cliArgs.showUnconfigured) config.settings.hideUnconfiguredModels = false
+  if (cliArgs.disableWidthsWarning) config.settings.disableWidthsWarning = true
+
+  // 📖 Apply premium mode: show only S‑tier models sorted by verdict
+  if (cliArgs.premiumMode) {
+    config.settings.tierFilter = 'S'
+    config.settings.sortColumn = 'verdict'
+    config.settings.sortAsc = true
+  }
+
   if (cliArgs.cleanProxyMode) {
     const cleaned = cleanupOpenCodeProxyConfig()
     console.log()
@@ -499,8 +515,9 @@ async function main() {
     mode,                         // 📖 'opencode' or 'openclaw' — controls Enter action
     tierFilterMode: 0,            // 📖 Index into TIER_CYCLE (0=All, 1=S+, 2=S, ...)
     originFilterMode: 0,          // 📖 Index into ORIGIN_CYCLE (0=All, then providers)
-hideUnconfiguredModels: startupProfileSettings?.hideUnconfiguredModels === true || config.settings?.hideUnconfiguredModels === true, // 📖 Hide providers with no configured API key when true.
-      disableWidthsWarning: config.settings?.disableWidthsWarning ?? false, // 📖 Disable widths warning toggle (default off)
+    premiumMode: cliArgs.premiumMode, // 📖 Special elite-only mode: S/S+ only, Health UP only, Perfect/Normal/Slow verdict only.
+    hideUnconfiguredModels: startupProfileSettings?.hideUnconfiguredModels === true || config.settings?.hideUnconfiguredModels === true, // 📖 Hide providers with no configured API key when true.
+    disableWidthsWarning: config.settings?.disableWidthsWarning ?? false, // 📖 Disable widths warning toggle (default off)
       scrollOffset: 0,              // 📖 First visible model index in viewport
       terminalRows: process.stdout.rows || 24,  // 📖 Current terminal height
       terminalCols: process.stdout.columns || 80, // 📖 Current terminal width
@@ -756,6 +773,17 @@ hideUnconfiguredModels: startupProfileSettings?.hideUnconfiguredModels === true
       outputResults = outputResults.filter(r => ['S+', 'S', 'A+'].includes(r.tier))
     }
 
+    // 📖 Apply premium mode filter if specified: elite-only (S/S+, UP, Good Verdict)
+    if (cliArgs.premiumMode) {
+      outputResults = outputResults.filter(r => {
+        const isEliteTier = r.tier === 'S' || r.tier === 'S+'
+        const isHealthUp = r.status === 'up'
+        const verdict = getVerdict(r)
+        const isGoodVerdict = ['Perfect', 'Normal', 'Slow'].includes(verdict)
+        return isEliteTier && isHealthUp && isGoodVerdict
+      })
+    }
+
     // 📖 Sort by avg ping (ascending)
     outputResults = sortResults(outputResults, 'avg', 'asc')
 
@@ -805,9 +833,23 @@ hideUnconfiguredModels: startupProfileSettings?.hideUnconfiguredModels === true
         return
       }
       // 📖 Apply both tier and origin filters — model is hidden if it fails either
-      const tierHide = activeTier !== null && r.tier !== activeTier
+      // 📖 TIER_LETTER_MAP is used so --tier S also includes S+ models (tier family behavior).
+      const allowedTiers = (activeTier && TIER_LETTER_MAP[activeTier]) ? TIER_LETTER_MAP[activeTier] : [activeTier]
+      const tierHide = activeTier !== null && !allowedTiers.includes(r.tier)
       const originHide = activeOrigin !== null && r.providerKey !== activeOrigin
       r.hidden = tierHide || originHide
+
+      // 📖 Premium Mode: elite-only constraints (Health UP, Good Verdict, S/S+ only)
+      if (state.premiumMode && !r.hidden) {
+        const isEliteTier = r.tier === 'S' || r.tier === 'S+'
+        const isHealthUp = r.status === 'up'
+        const verdict = getVerdict(r)
+        const isGoodVerdict = ['Perfect', 'Normal', 'Slow'].includes(verdict)
+
+        if (!isEliteTier || !isHealthUp || !isGoodVerdict) {
+          r.hidden = true
+        }
+      }
     })
     return state.results
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.3.6",
+  "version": "0.3.9",
   "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",

package/src/cli-help.js

@@ -26,6 +26,14 @@ const ANALYSIS_FLAGS = [
   { flag: '--json', description: 'Output results as JSON for scripts/automation' },
   { flag: '--tier <S|A|B|C>', description: 'Filter models by tier family' },
   { flag: '--recommend', description: 'Open Smart Recommend immediately on startup' },
+  { flag: '--premium', description: 'Show only S/S+ models with perfect health and good verdict' },
+  { flag: '--sort <column>', description: 'Sort by column (rank, tier, origin, model, ping, avg, swe, ctx, condition, verdict, uptime, stability, usage)' },
+  { flag: '--desc | --asc', description: 'Set sort direction (descending or ascending)' },
+  { flag: '--origin <provider>', description: 'Filter models by provider origin' },
+  { flag: '--ping-interval <ms>', description: 'Override ping interval in milliseconds' },
+  { flag: '--hide-unconfigured', description: 'Hide models without configured API keys' },
+  { flag: '--show-unconfigured', description: 'Show all models regardless of API key config' },
+  { flag: '--disable-widths-warning', description: 'Disable terminal width warning' },
 ]
 
 const CONFIG_FLAGS = [

package/src/overlays.js

@@ -736,7 +736,8 @@ const profileStartIdx = updateRowIdx + 5
         } catch { /* keep raw */ }
 
         const requestedModelLabel = row.requestedModel || ''
-        const displayModel = row.switched && requestedModelLabel && requestedModelLabel !== row.model
+        // 📖 Always show "requested → actual" if they differ, not just when switched
+        const displayModel = requestedModelLabel && requestedModelLabel !== row.model
           ? `${requestedModelLabel} → ${row.model}`
           : row.model
 
@@ -781,9 +782,11 @@ const profileStartIdx = updateRowIdx + 5
         const isFailedWithZeroTokens = row.status !== '200' && (!row.tokens || Number(row.tokens) === 0)
 
         const timeCell  = chalk.dim(timeStr.slice(0, W_TIME).padEnd(W_TIME))
-        // 📖 Color provider the same way as in the main table (row.provider is already the providerKey, e.g. "nvidia")
+        // 📖 Provider display: Use pretty label if available, otherwise raw key.
+        // 📖 All these logs are from FCM Proxy V2.
+        const providerLabel = PROVIDER_METADATA[row.provider]?.label || row.provider
         const providerRgb = PROVIDER_COLOR[row.provider] ?? [105, 190, 245]
-        const provCell  = chalk.bold.rgb(...providerRgb)(row.provider.slice(0, W_PROV).padEnd(W_PROV))
+        const provCell  = chalk.bold.rgb(...providerRgb)(providerLabel.slice(0, W_PROV).padEnd(W_PROV))
 
         // 📖 Color model based on status - red for failed requests with zero tokens
         let modelCell

package/src/token-usage-reader.js

@@ -26,28 +26,70 @@
  * @see src/render-table.js
  */
 
+import { readFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
 import { loadRecentLogs } from './log-reader.js'
 
+const DEFAULT_DATA_DIR = join(homedir(), '.free-coding-models')
+const STATS_FILE = join(DEFAULT_DATA_DIR, 'token-stats.json')
+
 // 📖 buildProviderModelTokenKey keeps provider-scoped totals isolated even when
 // 📖 multiple Origins expose the same model ID.
 export function buildProviderModelTokenKey(providerKey, modelId) {
   return `${providerKey}::${modelId}`
 }
 
-// 📖 loadTokenUsageByProviderModel reads the full bounded log history available
-// 📖 through log-reader and sums tokens per exact provider+model pair.
-export function loadTokenUsageByProviderModel({ logFile, limit = 50_000 } = {}) {
-  const rows = loadRecentLogs({ logFile, limit })
+// 📖 loadTokenUsageByProviderModel prioritizes token-stats.json for accurate
+// 📖 historical totals. If missing, it falls back to parsing the bounded log history.
+export function loadTokenUsageByProviderModel({ logFile, statsFile = STATS_FILE, limit = 50_000 } = {}) {
+  // 📖 If a custom logFile is provided (Test Mode), ONLY use that file.
+  if (logFile) {
+    const testTotals = {}
+    const rows = loadRecentLogs({ logFile, limit })
+    for (const row of rows) {
+      const key = buildProviderModelTokenKey(row.provider, row.model)
+      testTotals[key] = (testTotals[key] || 0) + (Number(row.tokens) || 0)
+    }
+    return testTotals
+  }
+
   const totals = {}
 
-  for (const row of rows) {
-    const providerKey = typeof row.provider === 'string' ? row.provider : 'unknown'
-    const modelId = typeof row.model === 'string' ? row.model : 'unknown'
-    const tokens = Number(row.tokens) || 0
-    if (tokens <= 0) continue
+  // 📖 Phase 1: Try to load from the aggregated stats file (canonical source for totals)
+  try {
+    if (existsSync(statsFile)) {
+      const stats = JSON.parse(readFileSync(statsFile, 'utf8'))
+      // 📖 Aggregate byAccount entries (which use providerKey/slug/keyIdx as ID)
+      // 📖 into providerKey::modelId buckets.
+      if (stats.byAccount && typeof stats.byAccount === 'object') {
+        for (const [accountId, acct] of Object.entries(stats.byAccount)) {
+          const tokens = Number(acct.tokens) || 0
+          if (tokens <= 0) continue
+
+          // 📖 Extract providerKey and modelId from accountId (provider/model/index)
+          const parts = accountId.split('/')
+          if (parts.length >= 2) {
+            const providerKey = parts[0]
+            const modelId = parts[1]
+            const key = buildProviderModelTokenKey(providerKey, modelId)
+            totals[key] = (totals[key] || 0) + tokens
+          }
+        }
+      }
+    }
+  } catch (err) {
+    // 📖 Silently fall back to log parsing if stats file is corrupt or unreadable
+  }
 
-    const key = buildProviderModelTokenKey(providerKey, modelId)
-    totals[key] = (totals[key] || 0) + tokens
+  // 📖 Phase 2: Supplement with recent log entries if totals are still empty
+  // 📖 (e.g. fresh install or token-stats.json deleted)
+  if (Object.keys(totals).length === 0) {
+    const rows = loadRecentLogs({ limit })
+    for (const row of rows) {
+      const key = buildProviderModelTokenKey(row.provider, row.model)
+      totals[key] = (totals[key] || 0) + (Number(row.tokens) || 0)
+    }
   }
 
   return totals

package/src/utils.js

@@ -414,10 +414,29 @@ export function parseArgs(argv) {
     ? profileIdx + 1
     : -1
 
+  // New value flags
+  const sortIdx = args.findIndex(a => a.toLowerCase() === '--sort')
+  const sortValueIdx = (sortIdx !== -1 && args[sortIdx + 1] && !args[sortIdx + 1].startsWith('--'))
+    ? sortIdx + 1
+    : -1
+
+  const originIdx = args.findIndex(a => a.toLowerCase() === '--origin')
+  const originValueIdx = (originIdx !== -1 && args[originIdx + 1] && !args[originIdx + 1].startsWith('--'))
+    ? originIdx + 1
+    : -1
+
+  const pingIntervalIdx = args.findIndex(a => a.toLowerCase() === '--ping-interval')
+  const pingIntervalValueIdx = (pingIntervalIdx !== -1 && args[pingIntervalIdx + 1] && !args[pingIntervalIdx + 1].startsWith('--'))
+    ? pingIntervalIdx + 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)
+  if (sortValueIdx !== -1) skipIndices.add(sortValueIdx)
+  if (originValueIdx !== -1) skipIndices.add(originValueIdx)
+  if (pingIntervalValueIdx !== -1) skipIndices.add(pingIntervalValueIdx)
 
   for (const [i, arg] of args.entries()) {
     if (arg.startsWith('--') || arg === '-h') {
@@ -448,8 +467,20 @@ export function parseArgs(argv) {
   const cleanProxyMode = flags.includes('--clean-proxy') || flags.includes('--proxy-clean')
   const jsonMode = flags.includes('--json')
   const helpMode = flags.includes('--help') || flags.includes('-h')
+  const premiumMode = flags.includes('--premium')
+
+  // New boolean flags
+  const sortDesc = flags.includes('--desc')
+  const sortAscFlag = flags.includes('--asc')
+  const hideUnconfigured = flags.includes('--hide-unconfigured')
+  const showUnconfigured = flags.includes('--show-unconfigured')
+  const disableWidthsWarning = flags.includes('--disable-widths-warning')
 
   let tierFilter = tierValueIdx !== -1 ? args[tierValueIdx].toUpperCase() : null
+  let sortColumn = sortValueIdx !== -1 ? args[sortValueIdx].toLowerCase() : null
+  let originFilter = originValueIdx !== -1 ? args[originValueIdx] : null
+  let pingInterval = pingIntervalValueIdx !== -1 ? parseInt(args[pingIntervalValueIdx], 10) : null
+  let sortDirection = sortDesc ? 'desc' : (sortAscFlag ? 'asc' : null)
 
   const profileName = profileValueIdx !== -1 ? args[profileValueIdx] : null
 
@@ -478,6 +509,14 @@ export function parseArgs(argv) {
     jsonMode,
     helpMode,
     tierFilter,
+    sortColumn,
+    sortDirection,
+    originFilter,
+    pingInterval,
+    hideUnconfigured,
+    showUnconfigured,
+    disableWidthsWarning,
+    premiumMode,
     profileName,
     recommendMode
   }