lynkr 7.0.1 → 7.2.0

package/CLAWROUTER_ROUTING_PLAN.md

@@ -0,0 +1,910 @@
+# Implementation Plan: ClawRouter-Inspired Intelligent Routing
+
+## Overview
+
+Enhance Lynkr's existing routing system with 4 ClawRouter-inspired features:
+1. **Enhanced Task Complexity Scorer** - 15-dimension weighted scoring
+2. **Cost Optimization Routing** - Per-model cost tracking with cost-aware decisions
+3. **Agentic Workflow Detection** - Auto-detect and route multi-step tool chains
+4. **Multi-Tier Model Mapping** - SIMPLE/MEDIUM/COMPLEX/REASONING tiers
+
+## Current State Analysis
+
+**Existing routing architecture** (`src/routing/`):
+
+| File | Current Function | Lines |
+|------|------------------|-------|
+| `index.js` | Main routing: `determineProviderSmart()`, `determineProvider()` | 376 |
+| `complexity-analyzer.js` | Scoring: `analyzeComplexity()` returns 0-100 score | ~550 |
+
+**Existing scoring breakdown** (complexity-analyzer.js):
+- `scoreTokens()` - 0-20 points (lines 184-192)
+- `scoreTools()` - 0-20 points (lines 198-207)
+- `scoreTaskType()` - 0-25 points (lines 212-267)
+- `scoreCodeComplexity()` - 0-20 points (lines 273-319)
+- `scoreReasoning()` - 0-15 points (lines 326-361)
+- Total: 0-100 with conversation bonus
+
+**Existing thresholds** (complexity-analyzer.js:366-378):
+- `aggressive`: 60 (more local)
+- `heuristic`: 40 (balanced, default)
+- `conservative`: 25 (more cloud)
+
+## Feature 1: Enhanced Task Complexity Scorer (15 Dimensions)
+
+### Goal
+Extend the existing `analyzeComplexity()` function with a ClawRouter-style weighted scorer.
+
+### Approach: Extend, Don't Replace
+Instead of creating a new file, **extend** `src/routing/complexity-analyzer.js` with weighted scoring as an optional mode.
+
+### Changes to `src/routing/complexity-analyzer.js`
+
+**Add after line 91 (after FORCE_LOCAL_PATTERNS):**
+
+```javascript
+// ============================================================================
+// WEIGHTED SCORING (ClawRouter-Inspired)
+// ============================================================================
+
+const DIMENSION_WEIGHTS = {
+  // Content Analysis (35%)
+  tokenCount: 0.08,
+  promptComplexity: 0.10,
+  technicalDepth: 0.10,
+  domainSpecificity: 0.07,
+  // Tool Analysis (25%)
+  toolCount: 0.08,
+  toolComplexity: 0.10,
+  toolChainPotential: 0.07,
+  // Reasoning Requirements (25%)
+  multiStepReasoning: 0.10,
+  codeGeneration: 0.08,
+  analysisDepth: 0.07,
+  // Context Factors (15%)
+  conversationDepth: 0.05,
+  priorToolUsage: 0.05,
+  ambiguity: 0.05,
+};
+
+// Tool complexity weights (higher = more complex)
+const TOOL_COMPLEXITY_WEIGHTS = {
+  Bash: 0.9,         // Can do anything
+  Write: 0.8,        // Creates files
+  Edit: 0.7,         // Modifies files
+  NotebookEdit: 0.7,
+  Task: 0.9,         // Spawns agents
+  WebSearch: 0.5,
+  WebFetch: 0.4,
+  Read: 0.3,         // Read-only
+  Glob: 0.2,
+  Grep: 0.2,
+  default: 0.5,
+};
+
+// Domain-specific keywords for complexity
+const DOMAIN_KEYWORDS = {
+  security: /\b(auth|encrypt|vulnerability|injection|xss|csrf|jwt|oauth)\b/i,
+  ml: /\b(model|train|inference|tensor|embedding|neural|llm|gpt|transformer)\b/i,
+  distributed: /\b(microservice|kafka|redis|queue|scale|cluster|replicate)\b/i,
+  database: /\b(sql|nosql|migration|index|query|transaction|orm)\b/i,
+};
+```
+
+**Add new function after `scoreReasoning()` (after line 361):**
+
+```javascript
+/**
+ * Calculate weighted complexity score (0-100)
+ * Uses 15 dimensions with configurable weights
+ */
+function calculateWeightedScore(payload, content) {
+  const dimensions = {};
+
+  // 1. Token count (0-100)
+  const tokens = estimateTokens(payload);
+  dimensions.tokenCount = tokens < 500 ? 10 : tokens < 2000 ? 30 : tokens < 5000 ? 50 : tokens < 10000 ? 70 : 90;
+
+  // 2. Prompt complexity (sentence structure)
+  const sentences = content.split(/[.!?]+/).filter(s => s.trim().length > 0);
+  const avgLength = content.length / Math.max(sentences.length, 1);
+  dimensions.promptComplexity = Math.min(avgLength / 2, 100);
+
+  // 3. Technical depth (keyword density)
+  const techMatches = (content.match(PATTERNS.technical) || []).length;
+  dimensions.technicalDepth = Math.min(techMatches * 15, 100);
+
+  // 4. Domain specificity
+  let domainScore = 0;
+  for (const [domain, regex] of Object.entries(DOMAIN_KEYWORDS)) {
+    if (regex.test(content)) domainScore += 25;
+  }
+  dimensions.domainSpecificity = Math.min(domainScore, 100);
+
+  // 5. Tool count
+  const toolCount = payload?.tools?.length ?? 0;
+  dimensions.toolCount = toolCount === 0 ? 0 : toolCount <= 3 ? 20 : toolCount <= 6 ? 40 : toolCount <= 10 ? 60 : toolCount <= 15 ? 80 : 100;
+
+  // 6. Tool complexity (weighted by tool types)
+  if (payload?.tools?.length > 0) {
+    const avgWeight = payload.tools.reduce((sum, t) => {
+      const name = t.name || t.function?.name || '';
+      return sum + (TOOL_COMPLEXITY_WEIGHTS[name] || TOOL_COMPLEXITY_WEIGHTS.default);
+    }, 0) / payload.tools.length;
+    dimensions.toolComplexity = avgWeight * 100;
+  } else {
+    dimensions.toolComplexity = 0;
+  }
+
+  // 7. Tool chain potential
+  dimensions.toolChainPotential = /\b(then|after|next|finally|first.*then)\b/i.test(content) ? 70 : 20;
+
+  // 8. Multi-step reasoning
+  dimensions.multiStepReasoning = ADVANCED_PATTERNS.reasoning.stepByStep.test(content) ? 80 :
+    ADVANCED_PATTERNS.reasoning.planning.test(content) ? 60 : 20;
+
+  // 9. Code generation
+  dimensions.codeGeneration = /\b(write|create|implement|build|generate)\s+(a\s+)?(function|class|module|api|endpoint)/i.test(content) ? 80 : 20;
+
+  // 10. Analysis depth
+  dimensions.analysisDepth = ADVANCED_PATTERNS.reasoning.tradeoffs.test(content) ? 80 :
+    ADVANCED_PATTERNS.reasoning.analysis.test(content) ? 60 : 20;
+
+  // 11. Conversation depth
+  const messageCount = payload?.messages?.length ?? 0;
+  dimensions.conversationDepth = messageCount < 3 ? 10 : messageCount < 6 ? 30 : messageCount < 10 ? 50 : 70;
+
+  // 12. Prior tool usage
+  const toolResults = (payload?.messages || []).filter(m =>
+    m.role === 'user' && Array.isArray(m.content) && m.content.some(c => c.type === 'tool_result')
+  ).length;
+  dimensions.priorToolUsage = toolResults === 0 ? 10 : toolResults < 3 ? 40 : toolResults < 6 ? 60 : 80;
+
+  // 13. Ambiguity (inverse of specificity)
+  const hasSpecifics = /\b(file|function|line|error|bug|at\s+\w+:\d+)\b/i.test(content);
+  dimensions.ambiguity = hasSpecifics ? 20 : content.length < 50 ? 70 : 40;
+
+  // Calculate weighted total
+  let weightedTotal = 0;
+  for (const [dimension, weight] of Object.entries(DIMENSION_WEIGHTS)) {
+    weightedTotal += (dimensions[dimension] || 0) * weight;
+  }
+
+  return {
+    score: Math.round(weightedTotal),
+    dimensions,
+    weights: DIMENSION_WEIGHTS,
+  };
+}
+```
+
+**Modify `analyzeComplexity()` (line 386) to use weighted scoring when enabled:**
+
+```javascript
+function analyzeComplexity(payload) {
+  const content = extractContent(payload);
+  const useWeighted = config.routing?.weightedScoring ?? false;
+
+  if (useWeighted) {
+    const weighted = calculateWeightedScore(payload, content);
+    const threshold = getThreshold();
+    const recommendation = weighted.score >= threshold ? 'cloud' : 'local';
+
+    return {
+      score: weighted.score,
+      threshold,
+      mode: 'weighted',
+      recommendation,
+      breakdown: weighted.dimensions,
+      weights: weighted.weights,
+    };
+  }
+
+  // ... existing logic unchanged
+}
+```
+
+### Config Addition (`src/config/index.js`)
+
+```javascript
+routing: {
+  weightedScoring: process.env.ROUTING_WEIGHTED_SCORING === 'true',
+},
+```
+
+---
+
+## Feature 2: Cost Optimization Routing
+
+### Goal
+Track per-model costs and make cost-aware routing decisions.
+
+### Data Source: models.dev API (250+ Models)
+
+Instead of maintaining a static config, we'll fetch from **https://models.dev/api.json** which provides:
+
+- **250+ models** across 15+ providers
+- **Real-time pricing** (input/output cost per 1M tokens)
+- **Capabilities** (tool_call, reasoning, structured_output)
+- **Context limits** and output limits
+- **Knowledge cutoff dates**
+
+### API Response Structure
+
+```json
+{
+  "provider_id": {
+    "id": "provider_id",
+    "name": "Provider Name",
+    "api": "https://api.provider.com/v1",
+    "models": {
+      "model-id": {
+        "id": "model-id",
+        "name": "Model Name",
+        "family": "model-family",
+        "cost": {
+          "input": 3.00,      // $ per 1M tokens
+          "output": 15.00,
+          "cache_read": 0.30,
+          "cache_write": 3.75
+        },
+        "context": 200000,
+        "output": 8192,
+        "tool_call": true,
+        "reasoning": true,
+        "structured_output": true,
+        "input": ["text", "image", "pdf"],
+        "output": ["text"],
+        "knowledge": "2024-04"
+      }
+    }
+  }
+}
+```
+
+### Local Tier Config: `config/model-tiers.json`
+
+We still need a local config for **tier mappings** (which models to use at each complexity level):
+
+```json
+{
+  "tiers": {
+    "SIMPLE": {
+      "description": "Greetings, simple Q&A, confirmations",
+      "range": [0, 25],
+      "preferred": {
+        "ollama": ["llama3.2", "gemma2", "phi3", "qwen2.5:7b"],
+        "openai": ["gpt-4o-mini"],
+        "anthropic": ["claude-3-haiku"],
+        "google": ["gemini-2.0-flash"],
+        "openrouter": ["deepseek/deepseek-chat", "google/gemini-flash-1.5"]
+      }
+    },
+    "MEDIUM": {
+      "description": "Code reading, simple edits, research",
+      "range": [26, 50],
+      "preferred": {
+        "ollama": ["qwen2.5:32b", "deepseek-coder:33b"],
+        "openai": ["gpt-4o"],
+        "anthropic": ["claude-sonnet-4-5"],
+        "google": ["gemini-1.5-pro"],
+        "openrouter": ["anthropic/claude-3.5-sonnet"]
+      }
+    },
+    "COMPLEX": {
+      "description": "Multi-file changes, debugging, architecture",
+      "range": [51, 75],
+      "preferred": {
+        "ollama": ["qwen2.5:72b", "llama3.1:70b"],
+        "openai": ["o1-mini", "o3-mini"],
+        "anthropic": ["claude-sonnet-4-5"],
+        "openrouter": ["meta-llama/llama-3.1-405b"]
+      }
+    },
+    "REASONING": {
+      "description": "Complex analysis, security audits, novel problems",
+      "range": [76, 100],
+      "preferred": {
+        "openai": ["o1", "o1-pro"],
+        "anthropic": ["claude-opus-4-5"],
+        "deepseek": ["deepseek-r1"],
+        "openrouter": ["anthropic/claude-3-opus", "deepseek/deepseek-reasoner"]
+      }
+    }
+  },
+  "local_models": {
+    "ollama": { "free": true, "default_tier": "SIMPLE" },
+    "llamacpp": { "free": true, "default_tier": "SIMPLE" },
+    "lmstudio": { "free": true, "default_tier": "SIMPLE" }
+  }
+}
+```
+
+### New File: `src/routing/model-registry.js`
+
+```javascript
+/**
+ * Model Registry
+ * Fetches model data from models.dev API and provides lookup
+ * Caches data locally with configurable refresh interval
+ */
+
+const fs = require('fs');
+const path = require('path');
+const logger = require('../logger');
+const config = require('../config');
+
+const API_URL = 'https://models.dev/api.json';
+const CACHE_FILE = path.join(__dirname, '../../data/models-cache.json');
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;  // 24 hours
+
+class ModelRegistry {
+  constructor() {
+    this.providers = {};      // Raw API data by provider
+    this.modelIndex = new Map();  // model-id -> { provider, ...model }
+    this.tiers = {};          // Local tier config
+    this.loaded = false;
+    this.lastFetch = 0;
+  }
+
+  /**
+   * Initialize registry - fetch from API or load cache
+   */
+  async initialize() {
+    if (this.loaded) return;
+
+    // Load local tier config
+    this._loadTierConfig();
+
+    // Try to load from cache first
+    if (this._loadFromCache()) {
+      this.loaded = true;
+      // Refresh in background if stale
+      if (Date.now() - this.lastFetch > CACHE_TTL_MS) {
+        this._fetchFromAPI().catch(err =>
+          logger.warn({ err: err.message }, '[ModelRegistry] Background refresh failed')
+        );
+      }
+      return;
+    }
+
+    // Fetch from API
+    await this._fetchFromAPI();
+    this.loaded = true;
+  }
+
+  /**
+   * Fetch fresh data from models.dev API
+   */
+  async _fetchFromAPI() {
+    try {
+      const response = await fetch(API_URL, {
+        signal: AbortSignal.timeout(10000),
+        headers: { 'Accept': 'application/json' }
+      });
+
+      if (!response.ok) throw new Error(`HTTP ${response.status}`);
+
+      const data = await response.json();
+      this._processAPIData(data);
+      this._saveToCache(data);
+      this.lastFetch = Date.now();
+
+      logger.info({
+        providers: Object.keys(this.providers).length,
+        models: this.modelIndex.size
+      }, '[ModelRegistry] Loaded from API');
+
+    } catch (err) {
+      logger.error({ err: err.message }, '[ModelRegistry] API fetch failed');
+      // Fall back to cache or defaults
+      if (!this._loadFromCache()) {
+        this._loadDefaults();
+      }
+    }
+  }
+
+  /**
+   * Process API data into indexed format
+   */
+  _processAPIData(data) {
+    this.providers = data;
+    this.modelIndex.clear();
+
+    for (const [providerId, providerData] of Object.entries(data)) {
+      if (!providerData.models) continue;
+
+      for (const [modelId, modelInfo] of Object.entries(providerData.models)) {
+        const fullId = `${providerId}/${modelId}`;
+        const entry = {
+          id: modelId,
+          fullId,
+          provider: providerId,
+          providerName: providerData.name,
+          ...modelInfo,
+          // Normalize cost
+          cost: modelInfo.cost || { input: 0, output: 0 },
+        };
+
+        // Index by multiple keys for flexible lookup
+        this.modelIndex.set(modelId.toLowerCase(), entry);
+        this.modelIndex.set(fullId.toLowerCase(), entry);
+        if (modelInfo.name) {
+          this.modelIndex.set(modelInfo.name.toLowerCase(), entry);
+        }
+      }
+    }
+  }
+
+  /**
+   * Load local tier configuration
+   */
+  _loadTierConfig() {
+    const tierPath = path.join(__dirname, '../../config/model-tiers.json');
+    try {
+      const data = JSON.parse(fs.readFileSync(tierPath, 'utf8'));
+      this.tiers = data.tiers || {};
+      this.localModels = data.local_models || {};
+    } catch (err) {
+      logger.warn({ err: err.message }, '[ModelRegistry] Using default tier config');
+      this._loadDefaultTiers();
+    }
+  }
+
+  /**
+   * Get model info by name/id
+   */
+  getModel(name) {
+    if (!name) return null;
+    return this.modelIndex.get(name.toLowerCase()) || null;
+  }
+
+  /**
+   * Get cost for a model
+   */
+  getCost(modelName) {
+    const model = this.getModel(modelName);
+    if (!model) return { input: 1.0, output: 3.0, tier: 'MEDIUM' };
+
+    // Determine tier from capabilities
+    let tier = 'MEDIUM';
+    if (model.reasoning) tier = 'REASONING';
+    else if (model.cost?.input >= 10) tier = 'COMPLEX';
+    else if (model.cost?.input <= 0.5) tier = 'SIMPLE';
+
+    return {
+      input: model.cost?.input || 0,
+      output: model.cost?.output || 0,
+      cacheRead: model.cost?.cache_read,
+      cacheWrite: model.cost?.cache_write,
+      tier,
+      context: model.context,
+      toolCall: model.tool_call,
+      reasoning: model.reasoning,
+    };
+  }
+
+  /**
+   * Get preferred models for a tier and provider
+   */
+  getTierModels(tier, provider) {
+    return this.tiers[tier]?.preferred?.[provider] || [];
+  }
+
+  /**
+   * Get all providers that have models for a tier
+   */
+  getProvidersForTier(tier) {
+    return Object.keys(this.tiers[tier]?.preferred || {});
+  }
+
+  /**
+   * Check if model supports tool calling
+   */
+  supportsTools(modelName) {
+    const model = this.getModel(modelName);
+    return model?.tool_call === true;
+  }
+
+  /**
+   * Check if model is free (local)
+   */
+  isFree(modelName) {
+    const model = this.getModel(modelName);
+    if (!model) {
+      // Check local models config
+      const provider = modelName?.split('/')[0] || modelName;
+      return this.localModels[provider]?.free === true;
+    }
+    return model.cost?.input === 0 && model.cost?.output === 0;
+  }
+
+  /**
+   * Get all models matching criteria
+   */
+  findModels(criteria = {}) {
+    const results = [];
+    for (const model of this.modelIndex.values()) {
+      if (criteria.toolCall && !model.tool_call) continue;
+      if (criteria.reasoning && !model.reasoning) continue;
+      if (criteria.maxInputCost && model.cost?.input > criteria.maxInputCost) continue;
+      if (criteria.minContext && model.context < criteria.minContext) continue;
+      results.push(model);
+    }
+    return results;
+  }
+
+  /**
+   * Get stats for metrics endpoint
+   */
+  getStats() {
+    return {
+      totalModels: this.modelIndex.size,
+      providers: Object.keys(this.providers).length,
+      lastFetch: this.lastFetch,
+      cacheAge: Date.now() - this.lastFetch,
+      tiers: Object.keys(this.tiers),
+    };
+  }
+
+  // Cache management
+  _loadFromCache() {
+    try {
+      if (!fs.existsSync(CACHE_FILE)) return false;
+      const cache = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
+      this._processAPIData(cache.data);
+      this.lastFetch = cache.timestamp || 0;
+      logger.debug({ age: Date.now() - this.lastFetch }, '[ModelRegistry] Loaded from cache');
+      return true;
+    } catch (err) {
+      return false;
+    }
+  }
+
+  _saveToCache(data) {
+    try {
+      const dir = path.dirname(CACHE_FILE);
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(CACHE_FILE, JSON.stringify({ data, timestamp: Date.now() }));
+    } catch (err) {
+      logger.warn({ err: err.message }, '[ModelRegistry] Cache save failed');
+    }
+  }
+
+  _loadDefaults() {
+    this.tiers = { SIMPLE: { preferred: { ollama: ['llama3.2'] } } };
+    this.localModels = { ollama: { free: true } };
+  }
+
+  _loadDefaultTiers() {
+    this.tiers = {
+      SIMPLE: { range: [0, 25], preferred: { ollama: ['llama3.2'], openai: ['gpt-4o-mini'] } },
+      MEDIUM: { range: [26, 50], preferred: { openai: ['gpt-4o'], anthropic: ['claude-sonnet-4-5'] } },
+      COMPLEX: { range: [51, 75], preferred: { openai: ['o1-mini'] } },
+      REASONING: { range: [76, 100], preferred: { openai: ['o1'], anthropic: ['claude-opus-4-5'] } },
+    };
+  }
+}
+
+// Singleton with async init
+let instance = null;
+async function getModelRegistry() {
+  if (!instance) {
+    instance = new ModelRegistry();
+    await instance.initialize();
+  }
+  return instance;
+}
+
+// Sync getter for already-initialized registry
+function getModelRegistrySync() {
+  if (!instance) {
+    instance = new ModelRegistry();
+    // Sync init - load from cache only
+    instance._loadTierConfig();
+    instance._loadFromCache() || instance._loadDefaults();
+    instance.loaded = true;
+  }
+  return instance;
+}
+
+module.exports = { ModelRegistry, getModelRegistry, getModelRegistrySync };
+```
+
+---
+
+## Feature 3: Agentic Workflow Detection
+
+### Goal
+Auto-detect when a request is part of an agentic workflow and route to capable models.
+
+### New File: `src/routing/agentic-detector.js`
+
+```javascript
+/**
+ * Agentic Workflow Detector
+ * Detects multi-step tool chains and autonomous agent patterns
+ */
+
+const logger = require('../logger');
+
+// Agent type classification
+const AGENT_TYPES = {
+  SINGLE_SHOT: { minTier: 'SIMPLE', scoreBoost: 0 },
+  TOOL_CHAIN: { minTier: 'MEDIUM', scoreBoost: 15, requiresToolUse: true },
+  ITERATIVE: { minTier: 'COMPLEX', scoreBoost: 25, requiresToolUse: true },
+  AUTONOMOUS: { minTier: 'REASONING', scoreBoost: 35, requiresToolUse: true },
+};
+
+// Detection patterns
+const PATTERNS = {
+  toolChain: /\b(then\s+use|after\s+that|next\s+step|finally|first.*then)\b/i,
+  iterative: /\b(keep\s+trying|until|repeat|loop|retry|iterate)\b/i,
+  autonomous: /\b(figure\s+out|solve|complete\s+the\s+task|do\s+whatever|make\s+it\s+work)\b/i,
+  multiFile: /\b(multiple\s+files?|across\s+(the\s+)?codebase|all\s+files?|refactor\s+entire)\b/i,
+  planning: /\b(plan|design|architect|strategy|roadmap)\b/i,
+};
+
+// High-complexity tools that indicate agentic work
+const AGENTIC_TOOLS = new Set([
+  'Bash', 'bash', 'shell',
+  'Write', 'write_file', 'fs_write',
+  'Edit', 'edit_file', 'fs_edit', 'edit_patch',
+  'Task', 'agent_task', 'spawn_agent',
+  'Git', 'git_commit', 'git_push',
+  'Test', 'run_tests',
+]);
+
+class AgenticDetector {
+  detect(payload) {
+    const messages = payload?.messages || [];
+    const tools = payload?.tools || [];
+    const content = this._extractContent(messages);
+
+    let score = 0;
+    const signals = [];
+
+    // Signal 1: Tool count
+    if (tools.length > 5) {
+      score += 20;
+      signals.push({ signal: 'high_tool_count', value: tools.length, weight: 20 });
+    } else if (tools.length > 3) {
+      score += 10;
+      signals.push({ signal: 'moderate_tool_count', value: tools.length, weight: 10 });
+    }
+
+    // Signal 2: Prior tool results
+    const toolResultCount = this._countToolResults(messages);
+    if (toolResultCount > 3) {
+      score += 25;
+      signals.push({ signal: 'many_tool_results', value: toolResultCount, weight: 25 });
+    } else if (toolResultCount > 0) {
+      score += 15;
+      signals.push({ signal: 'has_tool_results', value: toolResultCount, weight: 15 });
+    }
+
+    // Signal 3: Agentic tools present
+    const agenticToolCount = tools.filter(t => {
+      const name = t.name || t.function?.name || '';
+      return AGENTIC_TOOLS.has(name);
+    }).length;
+    if (agenticToolCount > 2) {
+      score += 20;
+      signals.push({ signal: 'agentic_tools', value: agenticToolCount, weight: 20 });
+    }
+
+    // Signal 4: Pattern matching
+    if (PATTERNS.autonomous.test(content)) {
+      score += 25;
+      signals.push({ signal: 'autonomous_pattern', weight: 25 });
+    } else if (PATTERNS.iterative.test(content)) {
+      score += 20;
+      signals.push({ signal: 'iterative_pattern', weight: 20 });
+    } else if (PATTERNS.toolChain.test(content)) {
+      score += 15;
+      signals.push({ signal: 'tool_chain_pattern', weight: 15 });
+    }
+
+    if (PATTERNS.multiFile.test(content)) {
+      score += 15;
+      signals.push({ signal: 'multi_file', weight: 15 });
+    }
+
+    if (PATTERNS.planning.test(content)) {
+      score += 10;
+      signals.push({ signal: 'planning', weight: 10 });
+    }
+
+    // Signal 5: Conversation depth
+    if (messages.length > 10) {
+      score += 15;
+      signals.push({ signal: 'deep_conversation', value: messages.length, weight: 15 });
+    } else if (messages.length > 5) {
+      score += 8;
+      signals.push({ signal: 'ongoing_conversation', value: messages.length, weight: 8 });
+    }
+
+    const agentType = this._classifyAgentType(score);
+    const isAgentic = score >= 30;
+
+    return {
+      isAgentic,
+      agentType,
+      confidence: Math.min(score / 100, 1),
+      score,
+      signals,
+      minTier: AGENT_TYPES[agentType].minTier,
+      scoreBoost: AGENT_TYPES[agentType].scoreBoost,
+    };
+  }
+
+  _classifyAgentType(score) {
+    if (score >= 60) return 'AUTONOMOUS';
+    if (score >= 40) return 'ITERATIVE';
+    if (score >= 25) return 'TOOL_CHAIN';
+    return 'SINGLE_SHOT';
+  }
+
+  _extractContent(messages) {
+    const userMsgs = messages.filter(m => m?.role === 'user');
+    if (userMsgs.length === 0) return '';
+    const last = userMsgs[userMsgs.length - 1];
+    if (typeof last.content === 'string') return last.content;
+    if (Array.isArray(last.content)) {
+      return last.content.filter(b => b?.type === 'text').map(b => b.text || '').join(' ');
+    }
+    return '';
+  }
+
+  _countToolResults(messages) {
+    return messages.reduce((count, m) => {
+      if (m?.role === 'user' && Array.isArray(m.content)) {
+        return count + m.content.filter(c => c?.type === 'tool_result').length;
+      }
+      return count;
+    }, 0);
+  }
+}
+
+let instance = null;
+function getAgenticDetector() {
+  if (!instance) instance = new AgenticDetector();
+  return instance;
+}
+
+module.exports = { AgenticDetector, getAgenticDetector, AGENT_TYPES };
+```
+
+---
+
+## Feature 4: Multi-Tier Model Mapping
+
+### New File: `src/routing/model-tiers.js`
+
+```javascript
+/**
+ * Model Tier Selector
+ * Maps complexity scores to appropriate models per provider
+ */
+
+const logger = require('../logger');
+const config = require('../config');
+const { getModelRegistry } = require('./model-registry');
+
+const TIER_DEFINITIONS = {
+  SIMPLE: { description: 'Greetings, simple Q&A', range: [0, 25], priority: 1 },
+  MEDIUM: { description: 'Code reading, simple edits', range: [26, 50], priority: 2 },
+  COMPLEX: { description: 'Multi-file changes, debugging', range: [51, 75], priority: 3 },
+  REASONING: { description: 'Complex analysis, security audits', range: [76, 100], priority: 4 },
+};
+
+class ModelTierSelector {
+  constructor() {
+    this.registry = getModelRegistry();
+  }
+
+  getTier(complexityScore) {
+    for (const [tier, def] of Object.entries(TIER_DEFINITIONS)) {
+      if (complexityScore >= def.range[0] && complexityScore <= def.range[1]) {
+        return tier;
+      }
+    }
+    return complexityScore > 75 ? 'REASONING' : 'SIMPLE';
+  }
+
+  selectModel(tier, provider) {
+    const override = config.modelTiers?.overrides?.[tier];
+    if (override) return { model: override, source: 'override' };
+
+    const providerModels = this.registry.getTierModels(tier, provider);
+    if (!providerModels?.length) {
+      const fallback = this.getFallbackModel(tier, provider);
+      if (fallback) return { model: fallback.model, source: 'fallback', actualTier: fallback.tier };
+      return { model: null, error: `No models for ${provider} at tier ${tier}` };
+    }
+
+    return { model: providerModels[0], source: 'tier_mapping', tier };
+  }
+
+  getFallbackModel(requestedTier, provider) {
+    const tierOrder = ['REASONING', 'COMPLEX', 'MEDIUM', 'SIMPLE'];
+    const startIndex = tierOrder.indexOf(requestedTier);
+
+    for (let i = startIndex + 1; i < tierOrder.length; i++) {
+      const models = this.registry.getTierModels(tierOrder[i], provider);
+      if (models?.length) return { model: models[0], tier: tierOrder[i] };
+    }
+    return null;
+  }
+
+  getTierStats() {
+    const modelCounts = {};
+    for (const tier of Object.keys(TIER_DEFINITIONS)) {
+      modelCounts[tier] = {};
+      for (const provider of this.registry.getProvidersForTier(tier)) {
+        modelCounts[tier][provider] = this.registry.getTierModels(tier, provider).length;
+      }
+    }
+    return { tiers: TIER_DEFINITIONS, modelCounts };
+  }
+}
+
+let instance = null;
+function getModelTierSelector() {
+  if (!instance) instance = new ModelTierSelector();
+  return instance;
+}
+
+module.exports = { ModelTierSelector, getModelTierSelector, TIER_DEFINITIONS };
+```
+
+---
+
+## Files Summary
+
+### Files to Create (5 files)
+
+| File | Lines | Purpose |
+|------|-------|---------|
+| `config/model-tiers.json` | ~60 | Local tier preferences |
+| `src/routing/model-registry.js` | ~220 | Fetches from models.dev API |
+| `src/routing/model-tiers.js` | ~80 | Tier selection |
+| `src/routing/cost-optimizer.js` | ~150 | Cost tracking |
+| `src/routing/agentic-detector.js` | ~170 | Workflow detection |
+
+### Files to Modify
+
+| File | Changes |
+|------|---------|
+| `src/routing/complexity-analyzer.js` | Add weighted scoring (~80 lines) |
+| `src/routing/index.js` | Integrate all modules (~50 lines) |
+| `src/config/index.js` | Add config options (~25 lines) |
+| `src/api/router.js` | Add 4 endpoints (~40 lines) |
+
+---
+
+## Configuration
+
+```bash
+# Intelligent Routing
+ROUTING_WEIGHTED_SCORING=false
+ROUTING_COST_OPTIMIZATION=false
+ROUTING_AGENTIC_DETECTION=true
+COST_BUDGET_DAILY_USD=0
+COST_BUDGET_SESSION_USD=0
+
+# Model Tiers
+MODEL_TIER_ENABLED=false
+MODEL_TIER_OVERRIDE_SIMPLE=gpt-4o-mini
+MODEL_TIER_OVERRIDE_REASONING=o1
+```
+
+---
+
+## API Endpoints
+
+- `GET /routing/models` - Model registry stats (from models.dev)
+- `GET /routing/models/:model` - Specific model info
+- `GET /routing/tiers` - Tier definitions and counts
+- `GET /metrics/cost-optimization` - Cost stats
+- `POST /routing/analyze` - Test request analysis