adaptive-memory-multi-model-router 2.16.0 → 2.16.1

package/src/cli/tui.ts

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+/**
+ * A3M Router Quick TUI
+ * Zero-config experience - no API key needed for free tier
+ */
+
+import * as readline from 'readline';
+
+const args = process.argv.slice(2);
+
+if (args.length === 0) {
+  console.log(`
+╔══════════════════════════════════════════════╗
+║         🔀 A3M Router - Zero Config          ║
+╠══════════════════════════════════════════════╣
+║                                              ║
+║  One prompt in. The right model out.         ║
+║                                              ║
+║  Usage:                                      ║
+║    a3m hello world      # Route a query       ║
+║    a3m --serve         # Start proxy          ║
+║    a3m --setup        # Configure API keys   ║
+║    a3m --demo         # Try without keys     ║
+║                                              ║
+╚══════════════════════════════════════════════╝
+`);
+  process.exit(0);
+}
+
+const command = args[0];
+
+// Demo mode - works without API key
+if (command === '--demo') {
+  console.log(`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🎮  A3M Router Demo Mode
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Try these queries:
+  • "Write Python hello world"
+  • "Explain quantum physics"
+  • "Translate to Japanese: Hello"
+  • "Write a haiku about coding"
+`);
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  const demoResults = [
+    { provider: 'groq', model: 'llama-3.3-70b-versatile', tier: 'free', cost: '$0.00' },
+    { provider: 'deepseek', model: 'deepseek-chat-v3', tier: 'cheap', cost: '$0.00' },
+    { provider: 'kimi', model: 'moonshot-v1-8k', tier: 'cheap', cost: '$0.00' },
+    { provider: 'openai', model: 'gpt-4o-mini', tier: 'paid', cost: '$0.00' },
+  ];
+
+  let count = 0;
+  function ask(): void {
+    rl.question('\n🔀 Query: ', (q: string) => {
+      if (!q || q.toLowerCase() === 'exit') {
+        console.log('\n👋 Ready for the real thing? Run: npm install adaptive-memory-multi-model-router\n');
+        rl.close();
+        return;
+      }
+      const r = demoResults[count++ % demoResults.length];
+      console.log(`\n  🏆 Best: ${r.provider} / ${r.model}`);
+      console.log(`  💰 Cost: ${r.cost} (${r.tier})`);
+      ask();
+    });
+  }
+  ask();
+  return;
+}
+
+// Serve mode
+if (command === '--serve') {
+  console.log(`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🚀  A3M Router Proxy Server
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Server: http://localhost:8787/v1/chat/completions
+API: OpenAI-compatible
+
+No API keys configured? Add free tier:
+  GROQ_API_KEY=your_key npx a3m-router serve
+
+Or run setup: a3m --setup
+`);
+
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const server = require('../server/proxyServer.js');
+    const port = parseInt(args[1], 10) || 8787;
+    server.createProxyServer({ port });
+    console.log(`\n✅ Server running at http://localhost:${port}`);
+  } catch (e: unknown) {
+    const msg = e instanceof Error ? e.message : String(e);
+    console.log('\n⚠️  Run "npm install" first, then "npm run build"\n');
+    console.error('Error:', msg);
+  }
+  return;
+}
+
+// Setup mode
+if (command === '--setup') {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const wizard = require('./setupWizard.js');
+  wizard.runWizard();
+  return;
+}
+
+// Zero-config mode - route with free tier defaults
+const query = args.join(' ');
+
+// Check for GROQ_API_KEY first (free tier)
+if (process.env.GROQ_API_KEY) {
+  console.log('\n🔀 Routing: "' + query + '"');
+  console.log('📡 Using free tier (Groq)...\n');
+
+  // Quick route via groq
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const { routeQuery } = require('../index.js');
+  routeQuery(query).then((r: { provider?: string; model?: string; estimated_cost?: number }) => {
+    console.log(`  🏆 Provider: ${r.provider || 'groq'}`);
+    console.log(`  🤖 Model: ${r.model || 'llama-3.3-70b-versatile'}`);
+    console.log(`  💰 Est: $${(r.estimated_cost || 0.0001).toFixed(6)}`);
+  }).catch((e: unknown) => {
+    const msg = e instanceof Error ? e.message : String(e);
+    console.log('  ⚠️  Error:', msg);
+    console.log('  Tip: Get free key at https://console.groq.com\n');
+  });
+  return;
+}
+
+// No API key - show helpful message
+console.log(`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚠️  No API key detected
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+A3M Router needs at least one API key to route queries.
+
+🔥 FREE TIER OPTIONS:
+  1. Groq (fastest, 1000+ req/day free)
+     → https://console.groq.com/apikeys
+     → Set: export GROQ_API_KEY=your_key
+
+  2. Cerebras (fastest inference, free)
+     → https://cerebras.ai/labs
+     → Set: export CEREBRAS_API_KEY=your_key
+
+  3. Google AI (Gemini, free tier)
+     → https://aistudio.google.com/app/apikey
+     → Set: export GOOGLE_API_KEY=your_key
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Quick setup: npx a3m --setup
+Quick start: GROQ_API_KEY=your_key npx a3m-router serve
+`);

package/src/ensemble.ts

@@ -21,6 +21,126 @@ interface RouteDecision {
   reasoning: string;
 }
 
+// ============================================================
+// SEMANTIC VOTING: Cluster similar answers together
+// ============================================================
+
+/**
+ * Simple word-overlap based semantic similarity
+ * Returns 0-1 similarity score
+ */
+function wordOverlapSimilarity(a: string, b: string): number {
+  // Normalize: lowercase, remove code blocks, extract words
+  const normalize = (s: string) => {
+    return s.toLowerCase()
+      .replace(/```[\s\S]*?```/g, ' CODE ')  // Replace code blocks
+      .replace(/`[^`]*`/g, ' CODE ')          // Replace inline code
+      .replace(/[^a-z0-9\s]/g, ' ')          // Remove punctuation
+      .split(/\s+/)
+      .filter(w => w.length > 2);             // Remove stopwords
+  };
+  
+  const wordsA = normalize(a);
+  const wordsB = normalize(b);
+  
+  if (wordsA.length === 0 || wordsB.length === 0) return 0;
+  
+  // Jaccard similarity
+  const setA = new Set(wordsA);
+  const setB = new Set(wordsB);
+  let intersection = 0;
+  for (const w of setA) {
+    if (setB.has(w)) intersection++;
+  }
+  const union = setA.size + setB.size - intersection;
+  return union > 0 ? intersection / union : 0;
+}
+
+/**
+ * Cluster answers by semantic similarity using agglomerative clustering
+ * Returns clusters of (representative, [provider indices])
+ */
+function semanticCluster(
+  answers: { provider: string; answer: string }[],
+  threshold = 0.6
+): { cluster: string; providers: string[] }[] {
+  if (answers.length === 0) return [];
+  if (answers.length === 1) return [{ cluster: answers[0].answer, providers: [answers[0].provider] }];
+  
+  // Build similarity matrix
+  const n = answers.length;
+  const sims: number[][] = Array(n).fill(null).map(() => Array(n).fill(0));
+  for (let i = 0; i < n; i++) {
+    for (let j = 0; j < n; j++) {
+      if (i === j) {
+        sims[i][j] = 1.0;
+      } else if (j > i) {
+        const s = wordOverlapSimilarity(answers[i].answer, answers[j].answer);
+        sims[i][j] = s;
+        sims[j][i] = s;
+      }
+    }
+  }
+  
+  // Agglomerative clustering: greedily merge most similar pairs
+  const clusters: Set<number>[] = answers.map((_, i) => new Set([i]));
+  const active = new Set(answers.map((_, i) => i));
+  
+  while (active.size > 1) {
+    let bestSim = 0;
+    let bestI = -1, bestJ = -1;
+    
+    for (const i of active) {
+      for (const j of active) {
+        if (i >= j) continue;
+        // Average similarity between all pairs in two clusters
+        let sumSim = 0, count = 0;
+        for (const ci of clusters[i]) {
+          for (const cj of clusters[j]) {
+            sumSim += sims[ci][cj];
+            count++;
+          }
+        }
+        const avgSim = count > 0 ? sumSim / count : 0;
+        if (avgSim > bestSim) {
+          bestSim = avgSim;
+          bestI = i;
+          bestJ = j;
+        }
+      }
+    }
+    
+    if (bestSim < threshold || bestI < 0) break;
+    
+    // Merge clusters
+    for (const idx of clusters[bestJ]) {
+      clusters[bestI].add(idx);
+    }
+    active.delete(bestJ);
+  }
+  
+  // Build result
+  return clusters
+    .filter((_, i) => active.has(i))
+    .map(cluster => {
+      const indices = Array.from(cluster);
+      // Use the longest answer as cluster representative (most informative)
+      let longestIdx = indices[0];
+      let longestLen = answers[indices[0]].answer.length;
+      for (const idx of indices) {
+        if (answers[idx].answer.length > longestLen) {
+          longestLen = answers[idx].answer.length;
+          longestIdx = idx;
+        }
+      }
+      return {
+        cluster: answers[longestIdx].answer,
+        providers: indices.map(i => answers[i].provider)
+      };
+    })
+    .sort((a, b) => b.providers.length - a.providers.length);  // Largest cluster first
+}
+
 // Type alias for external consumers
 export type RouterDecision = RouteDecision;
 
@@ -29,7 +149,7 @@ export type RouterDecision = RouteDecision;
 export const A3MRouter = createA3MRouter as any;
 export { createA3MRouter };
 
-export type EnsembleStrategy = 'majority' | 'weighted' | 'conservative' | 'shapley';
+export type EnsembleStrategy = 'majority' | 'weighted' | 'conservative' | 'shapley' | 'semantic';
 
 export interface EnsembleResponse {
   finalAnswer: string;
@@ -157,6 +277,39 @@ export class EnsembleOrchestrator {
         this.handicapCalc.record(r.provider, cost, isCorrect(r.answer));
       });
     }
+    else if (strategy === 'semantic') {
+      // === SEMANTIC VOTING: Cluster similar answers together ===
+      // This handles cases where models give equivalent answers in different words
+      // e.g., "The answer is 42" vs "42 is correct" would be clustered together
+      
+      const clusters = semanticCluster(successful, 0.55);  // 55% similarity threshold
+      
+      if (clusters.length === 0) {
+        winnerAnswer = 'UNCERTAIN';
+        confidence = 0;
+        winnerProvider = 'none';
+      } else {
+        // Use weighted voting: cluster size * average provider weight
+        const clusterScores = clusters.map(cluster => {
+          const totalWeight = cluster.providers.reduce((sum, p) => sum + (weights[p] || 1.0), 0);
+          return {
+            cluster: cluster.cluster,
+            providers: cluster.providers,
+            score: cluster.providers.length * totalWeight / cluster.providers.length
+          };
+        }).sort((a, b) => b.score - a.score);
+        
+        winnerAnswer = clusterScores[0].cluster;
+        winnerProvider = clusterScores[0].providers[0];
+        confidence = clusterScores[0].providers.length / successful.length;
+        
+        // Log cluster info for debugging
+        console.log(`[SEMANTIC] ${clusters.length} clusters formed, winner has ${clusterScores[0].providers.length}/${successful.length} providers`);
+        clusters.slice(1, 3).forEach((c, i) => {
+          console.log(`[SEMANTIC] Cluster ${i+2}: ${c.providers.length} providers, preview: ${c.cluster.substring(0, 50)}...`);
+        });
+      }
+    }
 
     // Record loyalty: successful collaborations build trust
     if (strategy === 'shapley') {

package/src/integrations/langchainAdapter.ts

@@ -74,7 +74,7 @@ import {
   registerProvider,
 } from '../providers/providerConfig.js';
 
-import { ProviderRegistry } from '../providers/registry.js';
+import { ProviderRegistry } from '../providers/registry';
 
 // ============================================================
 // TYPES
@@ -136,7 +136,7 @@ function langchainMessagesToOpenAI(messages: BaseMessage[]): Array<{
   tool_calls?: A3MToolCall[];
 }> {
   return messages.map((msg) => {
-    const role = msg._getType() as 'system' | 'user' | 'assistant' | 'tool';
+    const role = ((msg as any)._getType()) as 'system' | 'user' | 'assistant' | 'tool';
 
     let content: string | Array<{ type: string; text?: string; image_url?: any }>;
     if (typeof msg.content === 'string') {

package/src/providers/providerConfig.ts

@@ -639,30 +639,44 @@ export const DEFAULT_PROVIDERS: Record<string, ProviderDefinition> = {
     baseUrl: 'https://openrouter.ai/api/v1/chat/completions',
     apiKeyEnv: 'OPENROUTER_API_KEY',
     models: [
-      // Premium-tier free models (high context, powerful) — assigned equivalent costs for routing
-      // so the router classifies them as mid/premium tier
-      'moonshotai/kimi-k2.6:free',
-      'qwen/qwen3-coder:free',
-      'nvidia/nemotron-3-ultra-550b-a55b:free',
-      'nvidia/nemotron-3-super-120b-a12b:free',
-      'google/gemma-4-31b-it:free',
-      'qwen/qwen3-next-80b-a3b-instruct:free',
-      'nousresearch/hermes-3-llama-3.1-405b:free',
-      'openai/gpt-oss-120b:free',
-      'meta-llama/llama-3.3-70b-instruct:free',
-      // Paid models (passthrough pricing — set representative costs for routing)
+      // ✅ VERIFIED WORKING FREE MODELS (tested 2026-08-16 + recheck)
+      // Premium-tier free models (high context, powerful)
+      'nvidia/nemotron-3.5-lightning:free',     // 1M context, reasoning
+      'nvidia/nemotron-3-ultra-550b-a55b:free',  // 1M context, premium quality
+      'nvidia/nemotron-3-super-120b-a12b:free',  // 262K context
+      'google/gemma-4-31b-it:free',            // 262K context, multilingual
+      'google/gemma-4-26b-a4b-it:free',        // 262K context
+      // Reasoning-capable models
+      'nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free',  // 256K, reasoning
+      // Mid-tier free models
+      'nvidia/nemotron-3-nano-30b-a3b:free',  // 256K context
+      'nvidia/nemotron-nano-9b-v2:free',      // 128K context
+      'nvidia/nemotron-nano-12b-v2-vl:free',  // 128K context, multimodal
+      // Auto-route free model
+      'openrouter/free',                       // Auto-selects best available free model
+      // ❌ REMOVED (unavailable): kimi-k2.6, qwen3-coder, qwen3-next, hermes-3-405b, gpt-oss-120b, llama-3.3-70b, laguna-s-2.1
+      // FREE Gemini 3.x (newer, better than 2.x)
+      'google/gemini-3.5-flash:free',        // 131K context, reasoning, free
+      'google/gemini-3.6-flash:free',        // 131K context, reasoning, free
+      // FREE Qwen 3.7 (latest Qwen with extended context)
+      'qwen/qwen3.7-flash:free',             // 131K context, reasoning, free
+      'qwen/qwen3.7-max:free',               // 131K context, reasoning, free
+      // FREE DeepSeek V4 Flash
+      'deepseek/deepseek-v4-flash-latest:free', // 131K context, reasoning, free
+      // Paid models (passthrough pricing)
       'openai/gpt-4o',
       'anthropic/claude-3.5-sonnet',
       'google/gemini-pro-1.5',
       'meta-llama/llama-3.1-70b-instruct',
       'mistralai/mistral-large',
     ],
-    costPerK: { input: 0, output: 0 }, // Passthrough pricing — router uses model-specific costs
-    tier: 'cheap',
+    costPerK: { input: 0, output: 0 }, // Free tier models cost 0; paid use passthrough
+    tier: 'mid',  // Changed from 'cheap' — premium free models are mid-tier quality
     format: 'openai',
     type: 'api',
     priority: 34,
-    maxTokens: 128000,
+    maxTokens: 1048576,  // Support 1M context for nemotron-3.5-lightning
+    strategy: 'balanced',
   },
 
   // ========================================================================
@@ -718,12 +732,13 @@ export const DEFAULT_PROVIDERS: Record<string, ProviderDefinition> = {
       'mistralai/mistral-large-3-675b-instruct-2512',
       'z-ai/glm-5.1',
     ],
-    costPerK: { input: 0, output: 0 },
+    costPerK: { input: 0, output: 0 },  // Free tier available
     tier: 'free',
     format: 'openai',
     type: 'api',
     priority: 4,
-    maxTokens: 8192,
+    maxTokens: 131072,  // Support long context for premium models
+    strategy: 'balanced',
   },
 
   // ========================================================================

package/src/providers/registry.js

@@ -0,0 +1,27 @@
+/**
+ * Provider Registry - Central registry for all A3M Router providers
+ */
+export const PROVIDERS = new Map();
+
+// Register providers by name
+export function registerProvider(name, config) {
+  PROVIDERS.set(name, config);
+}
+
+// Get provider by name
+export function getProvider(name) {
+  return PROVIDERS.get(name);
+}
+
+// List all registered providers
+export function listProviders() {
+  return [...PROVIDERS.entries()];
+}
+
+// Remove provider by name
+export function removeProvider(name) {
+  return PROVIDERS.delete(name);
+}
+
+// Export all providers
+export * from './registry.js';

package/src/routing/advancedRouter.ts

@@ -137,6 +137,12 @@ function buildModelProfiles(): Record<string, ModelProfile> {
           'google/gemini-pro-1.5': [1.25, 5],
           'meta-llama/llama-3.1-70b-instruct': [0.18, 0.18],
           'mistralai/mistral-large': [2, 6],
+          // Newer free models (these override the default 0,0 for free tier)
+          'gemini-3.5-flash:free': [0, 0],
+          'gemini-3.6-flash:free': [0, 0],
+          'qwen3.7-flash:free': [0, 0],
+          'qwen3.7-max:free': [0, 0],
+          'deepseek-v4-flash-latest:free': [0, 0],
         };
         const orKey = model.includes('/') ? model : 'openrouter/' + model;
         // Try matching by full key or by model name
@@ -165,18 +171,46 @@ function buildModelProfiles(): Record<string, ModelProfile> {
       // OpenRouter premium free models get quality boosts
       if (provider.name === 'OpenRouter') {
         const modelLower = modelKey.toLowerCase();
-        // Premium-tier free models (large, high-context)
-        if (modelLower.includes('kimi') || modelLower.includes('qwen3-coder') || 
+        // Premium-tier free models (large, high-context) — these are equivalent to paid mid-tier
+        if (modelLower.includes('kimi-k2') || modelLower.includes('qwen3-coder') || 
             modelLower.includes('nemotron-3-ultra') || modelLower.includes('nemotron-3-super') ||
-            modelLower.includes('hermes-3') || modelLower.includes('gemma-4')) {
+            modelLower.includes('nemotron-3.5-lightning') || modelLower.includes('nemotron-3-nano-omni') ||
+            modelLower.includes('hermes-3') || modelLower.includes('gemma-4-31b') ||
+            modelLower.includes('laguna-s-2.1') ||
+            // Gemini 3.x free models — latest reasoning models
+            modelLower.includes('gemini-3.5-flash') || modelLower.includes('gemini-3.6-flash') ||
+            // Qwen 3.7 free models — latest with extended context
+            modelLower.includes('qwen3.7-flash') || modelLower.includes('qwen3.7-max') ||
+            // DeepSeek V4 free
+            modelLower.includes('deepseek-v4-flash')) {
           strengths.push('reasoning', 'long-context', 'premium');
         }
-        // Mid-tier free models (good quality, smaller)
+        // Mid-tier free models (good quality, smaller) — equivalent to cheap tier
         else if (modelLower.includes('gpt-oss') || modelLower.includes('qwen3-next') ||
-                 modelLower.includes('gemma-4') || modelLower.includes('llama-3.3')) {
+                 modelLower.includes('gemma-4-26b') || modelLower.includes('llama-3.3-70b') ||
+                 modelLower.includes('nemotron-3-nano-30b') || modelLower.includes('nemotron-nano-9b')) {
           strengths.push('fast', 'reasoning');
         }
-        // Budget free models
+        // Budget free models (small models)
+        else {
+          strengths.push('fast');
+        }
+      }
+      // NVIDIA NIM premium free models (high quality, long context)
+      if (provider.name === 'NVIDIA NIM') {
+        const modelLower = modelKey.toLowerCase();
+        // Premium tier: nemotron-super, gemma-4-31b, llama-3.3-70b
+        if (modelLower.includes('nemotron-3-super') || modelLower.includes('gemma-4-31b') ||
+            modelLower.includes('llama-3.3-70b') || modelLower.includes('mistral-large') ||
+            modelLower.includes('glm-5')) {
+          strengths.push('reasoning', 'long-context', 'premium');
+        }
+        // Mid tier: nemotron-mini, llama-3.1-8b, qwen
+        else if (modelLower.includes('nemotron-mini') || modelLower.includes('llama-3.1') ||
+                 modelLower.includes('qwen')) {
+          strengths.push('fast', 'reasoning');
+        }
+        // Budget tier
         else {
           strengths.push('fast');
         }
@@ -200,6 +234,10 @@ function buildModelProfiles(): Record<string, ModelProfile> {
       if (provider.name === 'Anthropic') {
         strengths.push('reasoning', 'creative', 'analysis');
       }
+      // Cloudflare Workers AI models (free but limited)
+      if (provider.name === 'Cloudflare Workers AI') {
+        strengths.push('free', 'fast');
+      }
 
       // Detect multimodal support
       const supportsMultimodal = provider.supports_multimodal === true;
@@ -209,6 +247,30 @@ function buildModelProfiles(): Record<string, ModelProfile> {
         strengths.push(provider.strategy);
       }
       
+      // === QUALITY SCORE ASSIGNMENT ===
+      // Priority: premium/reasoning > fast+paid > fast/free > budget > default
+      // Free models with premium/reasoning tags get same quality as paid models
+      let quality_score: number;
+      if (strengths.includes('premium') || strengths.includes('reasoning')) {
+        // Premium models (including premium free models like nemotron-3-super:free)
+        // get high quality score — same as paid premium models
+        quality_score = 0.92;
+      } else if (strengths.includes('fast') && costPerKInput > 0.3) {
+        // Fast mid-tier models (Groq, Cerebras, etc.) get competitive quality
+        quality_score = 0.89;
+      } else if (strengths.includes('fast') && costPerKInput === 0) {
+        // Fast free models (Cloudflare, local models) get moderate quality
+        quality_score = 0.78;
+      } else if (strengths.includes('budget')) {
+        // Budget models (small, cheap)
+        quality_score = 0.75;
+      } else if (provider.name === 'OpenRouter' && costPerKInput === 0) {
+        // OpenRouter free models that don't match premium patterns get boosted
+        quality_score = 0.82;
+      } else {
+        quality_score = 0.80;
+      }
+      
       profiles[modelKey] = {
         name: modelKey,
         provider: providerId,
@@ -216,9 +278,7 @@ function buildModelProfiles(): Record<string, ModelProfile> {
         cost_per_1k_input: costPerKInput,
         cost_per_1k_output: costPerKOutput,
         latency_ms: provider.type === 'cli' ? 5000 : (provider.priority * 200 + 300),
-        quality_score: (strengths.includes('premium') || strengths.includes('reasoning')) ? 0.94 :
-                       (strengths.includes('fast') && costPerKInput > 0.3) ? 0.95 :  // Boosted for mid-tier competitiveness
-                       (strengths.includes('budget') || strengths.includes('free')) ? 0.72 : 0.80,
+        quality_score,
         strengths,
         context_window: provider.maxTokens || 8192,
         type: provider.type,
@@ -609,7 +669,13 @@ function scoreModelFit(model: ModelProfile, features: QueryFeatures): number {
   // If user has free + groq + openai → quartiles split them naturally.
   const modelCost = (model.cost_per_1k_input + model.cost_per_1k_output) / 2;
   let tierFromModel: string;
-  if (model.strengths.includes('free') || modelCost === 0) {
+  // Premium free models (with 'premium' or 'reasoning' tag) are treated as 'mid' tier
+  // They should be selected for quality, not penalized for being "free"
+  const isPremiumFree = model.strengths.includes('free') && 
+    (model.strengths.includes('premium') || model.strengths.includes('reasoning'));
+  if (isPremiumFree) {
+    tierFromModel = 'mid';  // Treat premium free models as mid-tier for scoring
+  } else if (model.strengths.includes('free') || modelCost === 0) {
     tierFromModel = 'free';
   } else if (modelCost <= _costPercentiles.p25) {
     tierFromModel = 'cheap';
@@ -662,8 +728,21 @@ function scoreModelFit(model: ModelProfile, features: QueryFeatures): number {
     };
     const bonuses = domainBonus[features.domain] || [];
     if (bonuses.some(b => model.strengths.includes(b))) {
-      const is_budget = model.strengths.includes('budget') || model.strengths.includes('free');
-      score += is_budget ? 0.05 : 0.25;  // Budget gets minimal boost
+      // Separate budget from premium free models
+      const isBudget = model.strengths.includes('budget');
+      const isPremiumFree = model.strengths.includes('free') && 
+        (model.strengths.includes('premium') || model.strengths.includes('reasoning'));
+      const isBudgetFree = model.strengths.includes('free') && !isPremiumFree;
+      
+      if (isBudget) {
+        score += 0.05;  // Budget models get minimal domain boost
+      } else if (isPremiumFree) {
+        score += 0.15;  // Premium free models get significant boost (quality match)
+      } else if (isBudgetFree) {
+        score += 0.05;  // Budget free models get minimal boost
+      } else {
+        score += 0.25;  // Paid premium models get full boost
+      }
     }
   }
 
@@ -706,9 +785,15 @@ function scoreModelFit(model: ModelProfile, features: QueryFeatures): number {
     score *= 0.8;   // Mild penalty for conservative providers on low-risk (cost waste)
   }
 
-  // Free tier preference for simple queries
+  // Free tier preference for simple queries — ONLY for truly budget free models
+  // Premium free models (nemotron-super, gemma-4-31b, etc.) should be selected on quality,
+  // not because they're free, so they don't get this bonus
   if (features.complexity < 0.5 && model.strengths.includes('free')) {
-    score += 0.2;
+    const isBudgetFree = !model.strengths.includes('premium') && !model.strengths.includes('reasoning');
+    if (isBudgetFree) {
+      score += 0.05;  // Small bonus only — prevent budget free models from hitting cap
+    }
+    // Premium free models: NO bonus — they're selected on quality merits
   }
 
   // Fast provider for simple queries

package/src/routing/shadowSampler.ts

@@ -127,7 +127,7 @@ export interface ShadowedResponse {
  *   complexity_adj = query complexity signal
  */
 export class ShadowSampler {
-  private config: Required<Omit<ShadowSamplerConfig, 'forceShadowProvider'>> & { forceShadowProvider: boolean };
+  private config: Required<Omit<ShadowSamplerConfig, 'forceShadowProvider' | 'shadowProvider'>> & { forceShadowProvider: boolean; shadowProvider: string | null; };
   
   // Cached shadow provider (auto-selected on first call)
   private _shadowProvider: string | null = null;

package/test-install/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "test-install",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC"
+}

package/tests/tsconfig.json

@@ -14,7 +14,6 @@
     "noEmit": true
   },
   "include": [
-    "../tmlpd-pi-extension/src/**/*.ts",
     "../src/**/*.ts",
     "./**/*.ts"
   ]