lynkr 7.2.5 → 8.0.0

package/TIER_ROUTING_PLAN.md

@@ -1,771 +0,0 @@
-# 3-Tier Routing Implementation Plan
-
-## Overview
-
-Add explicit 3-tier configuration to Lynkr for predictable, cost-aware routing:
-- **Tier 1**: Local/Free (Ollama, llama.cpp, LM Studio)
-- **Tier 2**: Cloud/Cost-Effective (OpenRouter, Bedrock with cheap models, Azure OpenAI mini)
-- **Tier 3**: Cloud/Premium (Databricks, Azure Anthropic, Bedrock with premium models, OpenAI direct, etc.)
-
----
-
-## Current System vs Proposed System
-
-### Current Configuration
-```bash
-PREFER_OLLAMA=true
-OLLAMA_MAX_TOOLS_FOR_ROUTING=3
-FALLBACK_ENABLED=true
-FALLBACK_PROVIDER=databricks
-```
-
-**Current Routing Logic**:
-- 0-2 tools → Ollama
-- 3+ tools → Checks if OpenRouter/OpenAI/Azure/etc. configured (hardcoded order in routing.js lines 56-93)
-- Heavy tools OR not configured → FALLBACK_PROVIDER
-
-**Problem**: No explicit Tier 2 choice. System checks providers in hardcoded priority order.
-
----
-
-### Proposed Configuration
-```bash
-# Tier 1: Local (always enabled if PREFER_OLLAMA=true)
-PREFER_OLLAMA=true
-OLLAMA_MODEL=llama3.1:8b
-OLLAMA_MAX_TOOLS_FOR_ROUTING=3        # 0-2 tools → Tier 1
-
-# Tier 2: Cost-Effective (NEW - explicit)
-TIER_2_ENABLED=true
-TIER_2_PROVIDER=openrouter            # Explicit choice
-TIER_2_MAX_TOOLS=15                   # 3-15 tools → Tier 2
-
-# Tier 3: Premium (existing FALLBACK_PROVIDER)
-FALLBACK_ENABLED=true
-FALLBACK_PROVIDER=databricks          # 16+ tools → Tier 3
-```
-
-**Proposed Routing Logic**:
-- 0-2 tools → Tier 1 (Ollama/llamacpp/lmstudio)
-- 3-15 tools → Tier 2 (openrouter/bedrock/azure-openai) - **explicit, predictable**
-- 16+ tools → Tier 3 (databricks/azure-anthropic/bedrock/openrouter/openai/azure-openai) - **explicit, predictable**
-- Any tier fails → Try next tier
-
----
-
-## Tier Classification (Final)
-
-### Tier 1: Local/Free (No API Costs)
-**Providers**: ollama, llamacpp, lmstudio
-
-**Configuration**: Set as `MODEL_PROVIDER` or use `PREFER_OLLAMA=true`
-
-**Use Cases**: Local inference, offline usage, privacy, development, zero API costs
-
-**Tool Count**: 0-2 tools (configured via `OLLAMA_MAX_TOOLS_FOR_ROUTING`)
-
----
-
-### Tier 2: Cloud/Cost-Effective ($ - Cheap Cloud Only)
-
-**Valid Providers**:
-- `openrouter` - 100+ models, cheapest option ($0.15/1M for GPT-4o-mini)
-- `bedrock` - AWS ecosystem with cheap models (Llama $0.99/1M, Mistral, Titan)
-- `azure-openai` - Azure with cheap deployments (gpt-4o-mini)
-
-**NOT Allowed**:
-- ❌ `openai` - Direct OpenAI API is Tier 3 only (premium positioning)
-- ❌ `ollama`, `llamacpp`, `lmstudio` - Local providers are Tier 1 only
-
-**Configuration**:
-```bash
-TIER_2_ENABLED=true
-TIER_2_PROVIDER=openrouter    # or bedrock, azure-openai
-TIER_2_MAX_TOOLS=15
-```
-
-**Tool Count**: 3-15 tools (configurable via `TIER_2_MAX_TOOLS`)
-
-**Use Cases**: Cost optimization, medium complexity requests, development with cloud
-
----
-
-### Tier 3: Cloud/Premium ($$$ - Expensive Cloud)
-
-**Valid Providers** (All Cloud Providers):
-- `databricks` - Claude Opus/Sonnet ($3-15/1M), enterprise MLOps
-- `azure-anthropic` - Azure-hosted Claude ($3-15/1M)
-- `bedrock` - AWS with premium models (Claude 4.5 Sonnet $3+/1M)
-- `openrouter` - With premium models (GPT-4o, Claude Opus)
-- `openai` - Direct OpenAI API (official, premium)
-- `azure-openai` - Azure with premium models (GPT-4o, o1)
-
-**NOT Allowed**:
-- ❌ `ollama`, `llamacpp`, `lmstudio` - Local providers should not be fallback for cloud
-
-**Configuration**:
-```bash
-FALLBACK_ENABLED=true
-FALLBACK_PROVIDER=databricks   # or any cloud provider above
-```
-
-**Tool Count**: 16+ tools, OR when Tier 2 fails
-
-**Use Cases**: Complex reasoning, heavy tool usage, production reliability, premium quality
-
----
-
-## Implementation Phases
-
-### Phase 1: Configuration (src/config/index.js)
-
-**File**: `src/config/index.js`
-
-**Location**: After line 109 (following existing model provider config)
-
-**Add Environment Variable Parsing**:
-```javascript
-// Tier 2 configuration (explicit middle tier)
-const tier2Enabled = process.env.TIER_2_ENABLED?.toLowerCase() === "true";
-const tier2Provider = process.env.TIER_2_PROVIDER?.trim()?.toLowerCase() || null;
-const tier2MaxTools = parseInt(process.env.TIER_2_MAX_TOOLS) || 15;
-```
-
-**Add Validation Logic** (after line 226):
-```javascript
-// Validate Tier 2 if enabled
-if (tier2Enabled) {
-  if (!tier2Provider) {
-    throw new Error(
-      "TIER_2_ENABLED is true but TIER_2_PROVIDER is not set. " +
-      "Set TIER_2_PROVIDER to: openrouter, bedrock, azure-openai"
-    );
-  }
-
-  const validTier2Providers = ["openrouter", "bedrock", "azure-openai"];
-  if (!validTier2Providers.includes(tier2Provider)) {
-    throw new Error(
-      `TIER_2_PROVIDER '${tier2Provider}' is invalid. ` +
-      `Valid cost-effective cloud providers: ${validTier2Providers.join(", ")}. ` +
-      `Note: OpenAI direct API is Tier 3 only (use openrouter for cheaper OpenAI access). ` +
-      `Local providers (ollama, llamacpp, lmstudio) should use Tier 1.`
-    );
-  }
-
-  // Verify Tier 2 provider is configured
-  const providerConfigured = {
-    openrouter: config.openrouter?.apiKey,
-    bedrock: config.bedrock?.apiKey,
-    "azure-openai": config.azureOpenAI?.apiKey,
-  };
-
-  if (!providerConfigured[tier2Provider]) {
-    throw new Error(
-      `TIER_2_PROVIDER is set to '${tier2Provider}' but this provider is not configured. ` +
-      `Please configure ${tier2Provider.toUpperCase()} environment variables.`
-    );
-  }
-}
-
-// Validate Tier 3 (FALLBACK_PROVIDER) - prevent local providers
-if (fallbackEnabled) {
-  const localProviders = ["ollama", "llamacpp", "lmstudio"];
-
-  if (localProviders.includes(fallbackProvider)) {
-    throw new Error(
-      `FALLBACK_PROVIDER cannot be '${fallbackProvider}' (local provider). ` +
-      `Tier 3 fallback should be a cloud provider: databricks, azure-anthropic, bedrock, openrouter, openai, azure-openai. ` +
-      `Local providers (ollama, llamacpp, lmstudio) should only be used as Tier 1.`
-    );
-  }
-}
-```
-
-**Export Tier 2 Config** (after line 446 in modelProvider section):
-```javascript
-modelProvider: {
-  type: modelProvider,
-  preferOllama,
-  fallbackEnabled,
-  fallbackProvider,
-  ollamaMaxToolsForRouting,
-  openRouterMaxToolsForRouting,
-  // NEW: Tier 2 configuration
-  tier2Enabled,
-  tier2Provider,
-  tier2MaxTools,
-},
-```
-
----
-
-### Phase 2: Routing Logic (src/clients/routing.js)
-
-**File**: `src/clients/routing.js`
-
-**Replace Lines 56-94** with new tier-based logic:
-
-```javascript
-// Moderate tool count → Check if Tier 2 is enabled
-if (toolCount < maxToolsForOpenRouter && isFallbackEnabled()) {
-  const tier2Enabled = config.modelProvider?.tier2Enabled ?? false;
-  const tier2Provider = config.modelProvider?.tier2Provider;
-  const tier2MaxTools = config.modelProvider?.tier2MaxTools ?? 15;
-
-  // If Tier 2 explicitly enabled, route to configured provider
-  if (tier2Enabled && toolCount <= tier2MaxTools) {
-    logger.debug(
-      { toolCount, tier: 2, provider: tier2Provider, tier2MaxTools, decision: tier2Provider },
-      "Routing to Tier 2 (explicit cost-effective cloud)"
-    );
-    return tier2Provider;
-  }
-
-  // If Tier 2 disabled, check providers in order (backward compatibility)
-  if (!tier2Enabled) {
-    logger.debug({ toolCount }, "Tier 2 disabled, using legacy provider check order");
-
-    if (config.openrouter?.apiKey) {
-      logger.debug({ toolCount, decision: "openrouter" }, "Routing to OpenRouter (legacy mode)");
-      return "openrouter";
-    } else if (config.openai?.apiKey) {
-      logger.debug({ toolCount, decision: "openai" }, "Routing to OpenAI (legacy mode)");
-      return "openai";
-    } else if (config.azureOpenAI?.apiKey) {
-      logger.debug({ toolCount, decision: "azure-openai" }, "Routing to Azure OpenAI (legacy mode)");
-      return "azure-openai";
-    } else if (config.llamacpp?.endpoint) {
-      logger.debug({ toolCount, decision: "llamacpp" }, "Routing to llama.cpp (legacy mode)");
-      return "llamacpp";
-    } else if (config.lmstudio?.endpoint) {
-      logger.debug({ toolCount, decision: "lmstudio" }, "Routing to LM Studio (legacy mode)");
-      return "lmstudio";
-    } else if (config.bedrock?.apiKey) {
-      logger.debug({ toolCount, decision: "bedrock" }, "Routing to AWS Bedrock (legacy mode)");
-      return "bedrock";
-    }
-  }
-}
-
-// Heavy tool count → Tier 3 (fallback provider)
-if (isFallbackEnabled()) {
-  const fallback = config.modelProvider?.fallbackProvider ?? "databricks";
-  logger.debug(
-    { toolCount, tier: 3, provider: fallback, decision: fallback },
-    "Routing to Tier 3 (premium cloud - heavy tools or Tier 2 exceeded threshold)"
-  );
-  return fallback;
-}
-
-// Fallback disabled, route to Ollama regardless of complexity
-logger.debug(
-  { toolCount, maxToolsForOllama, fallbackEnabled: false, decision: "ollama" },
-  "Routing to Ollama (fallback disabled)"
-);
-return "ollama";
-```
-
-**Add Helper Function** (after line 130):
-```javascript
-/**
- * Get the tier for current request based on tool count
- *
- * @param {number} toolCount - Number of tools in request
- * @returns {number} Tier number (1, 2, or 3)
- */
-function getTierForRequest(toolCount) {
-  const preferOllama = config.modelProvider?.preferOllama ?? false;
-  if (!preferOllama) return null; // Not using tiered routing
-
-  const ollamaMaxTools = config.modelProvider?.ollamaMaxToolsForRouting ?? 3;
-  const tier2MaxTools = config.modelProvider?.tier2MaxTools ?? 15;
-
-  if (toolCount < ollamaMaxTools) return 1; // Ollama
-  if (toolCount <= tier2MaxTools) return 2;  // Tier 2
-  return 3;                                  // Tier 3
-}
-
-module.exports = {
-  determineProvider,
-  isFallbackEnabled,
-  getFallbackProvider,
-  getTierForRequest, // NEW
-};
-```
-
----
-
-### Phase 3: Documentation Updates
-
-#### 3.1 Update .env.example
-
-**File**: `.env.example`
-
-**Add After Line 36** (after OLLAMA_MAX_TOOLS_FOR_ROUTING):
-
-```bash
-# ==============================================================================
-# Tier 2 Configuration (Explicit Middle Tier - Cost-Effective Cloud)
-# ==============================================================================
-
-# Enable Tier 2 routing for cost-effective cloud provider
-# When enabled, requests with 3-15 tools route to this provider instead of checking providers in order
-# TIER_2_ENABLED=true
-
-# Which provider to use for Tier 2 (cost-effective cloud only)
-# Options: openrouter, bedrock, azure-openai
-# NOT allowed: openai (Tier 3 only), ollama/llamacpp/lmstudio (Tier 1 only)
-# TIER_2_PROVIDER=openrouter
-
-# Maximum tools for Tier 2 routing (requests above this go to Tier 3)
-# Default: 15
-# TIER_2_MAX_TOOLS=15
-
-# ==============================================================================
-# 3-Tier Routing Configuration Example
-# ==============================================================================
-#
-# ┌─────────────┬────────────────┬──────────────────┬─────────────┐
-# │ Tool Count  │ Tier           │ Provider         │ Cost        │
-# ├─────────────┼────────────────┼──────────────────┼─────────────┤
-# │ 0-2 tools   │ Tier 1 (Local) │ Ollama           │ FREE        │
-# │ 3-15 tools  │ Tier 2 (Cloud) │ OpenRouter       │ $ (cheap)   │
-# │ 16+ tools   │ Tier 3 (Cloud) │ Databricks       │ $$$ (exp)   │
-# └─────────────┴────────────────┴──────────────────┴─────────────┘
-#
-# Complete Example:
-# PREFER_OLLAMA=true
-# OLLAMA_MAX_TOOLS_FOR_ROUTING=3
-# TIER_2_ENABLED=true
-# TIER_2_PROVIDER=openrouter
-# TIER_2_MAX_TOOLS=15
-# FALLBACK_ENABLED=true
-# FALLBACK_PROVIDER=databricks
-```
-
-#### 3.2 Update README.md
-
-**File**: `README.md`
-
-**Add Section After "Hybrid Routing" Section** (after line ~275):
-
-```markdown
-### **3-Tier Routing (Explicit Cost Control)**
-
-For predictable cost management, use explicit tier configuration:
-
-```bash
-# Tier 1: Local (FREE) - 0-2 tools
-PREFER_OLLAMA=true
-OLLAMA_MODEL=llama3.1:8b
-OLLAMA_MAX_TOOLS_FOR_ROUTING=3
-
-# Tier 2: Cost-Effective (CHEAP $) - 3-15 tools
-TIER_2_ENABLED=true
-TIER_2_PROVIDER=openrouter
-TIER_2_MAX_TOOLS=15
-
-# Tier 3: Premium (EXPENSIVE $$$) - 16+ tools
-FALLBACK_ENABLED=true
-FALLBACK_PROVIDER=databricks
-```
-
-**How 3-Tier Routing Works**:
-
-| Tool Count | Tier | Provider | Cost | Example |
-|------------|------|----------|------|---------|
-| 0-2 tools | **Tier 1** (Local) | Ollama | FREE | Simple questions, basic file reads |
-| 3-15 tools | **Tier 2** (Cloud) | OpenRouter | $ (cheap) | Medium complexity, moderate tool usage |
-| 16+ tools | **Tier 3** (Cloud) | Databricks | $$$ (expensive) | Complex refactoring, heavy analysis |
-
-**Cost Predictability**:
-```
-Simple request (1 tool):    Tier 1 → FREE
-Medium request (8 tools):   Tier 2 → $0.15 per 1M tokens (OpenRouter)
-Complex request (20 tools): Tier 3 → $3.00 per 1M tokens (Databricks)
-```
-
-**Tier 2 Valid Providers** (Cost-Effective):
-- `openrouter` - 100+ models, cheapest option ($0.15/1M)
-- `bedrock` - AWS with cheap models (Llama, Mistral, Titan)
-- `azure-openai` - Azure with mini deployments
-
-**Tier 3 Valid Providers** (Premium):
-- `databricks` - Claude Opus/Sonnet, enterprise
-- `azure-anthropic` - Azure-hosted Claude
-- `bedrock` - AWS with Claude 4.5 Sonnet
-- `openrouter` - With premium models
-- `openai` - Direct OpenAI API (premium only)
-- `azure-openai` - Azure with premium models
-
-⚠️ **Note**: Direct OpenAI API (`openai`) is Tier 3 only. For cheaper GPT access, use `openrouter` in Tier 2.
-
-**Automatic Fallback**: If any tier fails, automatically tries the next tier for resilience.
-```
-
----
-
-### Phase 4: Testing Strategy
-
-#### 4.1 Unit Tests
-
-**File**: `test/tier-routing.test.js` (NEW FILE)
-
-```javascript
-const assert = require("assert");
-const { describe, it, beforeEach, afterEach } = require("node:test");
-
-describe("3-Tier Routing", () => {
-  let originalEnv;
-
-  beforeEach(() => {
-    originalEnv = { ...process.env };
-    delete require.cache[require.resolve("../src/config")];
-    delete require.cache[require.resolve("../src/clients/routing")];
-  });
-
-  afterEach(() => {
-    process.env = originalEnv;
-  });
-
-  describe("Tier 1 (Local)", () => {
-    it("should route 0-2 tools to Tier 1 (Ollama)", () => {
-      process.env.PREFER_OLLAMA = "true";
-      process.env.OLLAMA_MAX_TOOLS_FOR_ROUTING = "3";
-
-      const { determineProvider } = require("../src/clients/routing");
-      const provider = determineProvider({ tools: [{}, {}] }); // 2 tools
-
-      assert.strictEqual(provider, "ollama");
-    });
-  });
-
-  describe("Tier 2 (Cost-Effective Cloud)", () => {
-    it("should route 3-15 tools to Tier 2 when enabled", () => {
-      process.env.PREFER_OLLAMA = "true";
-      process.env.TIER_2_ENABLED = "true";
-      process.env.TIER_2_PROVIDER = "openrouter";
-      process.env.TIER_2_MAX_TOOLS = "15";
-      process.env.OPENROUTER_API_KEY = "test-key";
-
-      const { determineProvider } = require("../src/clients/routing");
-      const provider = determineProvider({ tools: Array(8).fill({}) }); // 8 tools
-
-      assert.strictEqual(provider, "openrouter");
-    });
-
-    it("should route to bedrock when configured as Tier 2", () => {
-      process.env.PREFER_OLLAMA = "true";
-      process.env.TIER_2_ENABLED = "true";
-      process.env.TIER_2_PROVIDER = "bedrock";
-      process.env.AWS_BEDROCK_API_KEY = "test-key";
-
-      const { determineProvider } = require("../src/clients/routing");
-      const provider = determineProvider({ tools: Array(10).fill({}) });
-
-      assert.strictEqual(provider, "bedrock");
-    });
-
-    it("should NOT allow openai in Tier 2", () => {
-      process.env.TIER_2_ENABLED = "true";
-      process.env.TIER_2_PROVIDER = "openai";
-
-      assert.throws(
-        () => require("../src/config"),
-        /OpenAI direct API is Tier 3 only/
-      );
-    });
-
-    it("should NOT allow local providers in Tier 2", () => {
-      process.env.TIER_2_ENABLED = "true";
-      process.env.TIER_2_PROVIDER = "ollama";
-
-      assert.throws(
-        () => require("../src/config"),
-        /Local providers.*should use Tier 1/
-      );
-    });
-  });
-
-  describe("Tier 3 (Premium Cloud)", () => {
-    it("should route 16+ tools to Tier 3", () => {
-      process.env.PREFER_OLLAMA = "true";
-      process.env.TIER_2_ENABLED = "true";
-      process.env.TIER_2_MAX_TOOLS = "15";
-      process.env.FALLBACK_ENABLED = "true";
-      process.env.FALLBACK_PROVIDER = "databricks";
-
-      const { determineProvider } = require("../src/clients/routing");
-      const provider = determineProvider({ tools: Array(20).fill({}) }); // 20 tools
-
-      assert.strictEqual(provider, "databricks");
-    });
-
-    it("should allow openai in Tier 3", () => {
-      process.env.FALLBACK_ENABLED = "true";
-      process.env.FALLBACK_PROVIDER = "openai";
-      process.env.OPENAI_API_KEY = "test-key";
-
-      const config = require("../src/config");
-      assert.strictEqual(config.modelProvider.fallbackProvider, "openai");
-    });
-
-    it("should NOT allow local providers in Tier 3", () => {
-      process.env.FALLBACK_ENABLED = "true";
-      process.env.FALLBACK_PROVIDER = "ollama";
-
-      assert.throws(
-        () => require("../src/config"),
-        /FALLBACK_PROVIDER cannot be 'ollama'/
-      );
-    });
-  });
-
-  describe("Validation", () => {
-    it("should throw error if Tier 2 enabled but provider not set", () => {
-      process.env.TIER_2_ENABLED = "true";
-      // Missing TIER_2_PROVIDER
-
-      assert.throws(
-        () => require("../src/config"),
-        /TIER_2_PROVIDER is not set/
-      );
-    });
-
-    it("should throw error if Tier 2 provider not configured", () => {
-      process.env.TIER_2_ENABLED = "true";
-      process.env.TIER_2_PROVIDER = "openrouter";
-      // Missing OPENROUTER_API_KEY
-
-      assert.throws(
-        () => require("../src/config"),
-        /openrouter.*is not configured/
-      );
-    });
-  });
-
-  describe("Backward Compatibility", () => {
-    it("should fall back to legacy mode when Tier 2 disabled", () => {
-      process.env.PREFER_OLLAMA = "true";
-      process.env.TIER_2_ENABLED = "false";
-      process.env.OPENROUTER_API_KEY = "test-key";
-
-      const { determineProvider } = require("../src/clients/routing");
-      const provider = determineProvider({ tools: Array(8).fill({}) }); // 8 tools
-
-      assert.strictEqual(provider, "openrouter"); // Legacy order check
-    });
-  });
-});
-```
-
-#### 4.2 Manual Integration Tests
-
-```bash
-# Test 1: Tier 1 routing (0-2 tools)
-curl -X POST http://localhost:8081/v1/messages \
-  -H "Content-Type: application/json" \
-  -d '{
-    "model": "claude",
-    "max_tokens": 50,
-    "messages": [{"role": "user", "content": "Hello"}],
-    "tools": [{"name": "test1"}]
-  }'
-# Expected: Routes to Ollama, logs show "Tier 1"
-
-# Test 2: Tier 2 routing (3-15 tools)
-curl -X POST http://localhost:8081/v1/messages \
-  -H "Content-Type: application/json" \
-  -d '{
-    "model": "claude",
-    "max_tokens": 50,
-    "messages": [{"role": "user", "content": "Hello"}],
-    "tools": [
-      {"name": "t1"}, {"name": "t2"}, {"name": "t3"},
-      {"name": "t4"}, {"name": "t5"}, {"name": "t6"}
-    ]
-  }'
-# Expected: Routes to openrouter (Tier 2), logs show "tier: 2"
-
-# Test 3: Tier 3 routing (16+ tools)
-curl -X POST http://localhost:8081/v1/messages \
-  -H "Content-Type: application/json" \
-  -d '{
-    "model": "claude",
-    "max_tokens": 50,
-    "messages": [{"role": "user", "content": "Hello"}],
-    "tools": [... 20 tools ...]
-  }'
-# Expected: Routes to databricks (Tier 3), logs show "tier: 3"
-```
-
----
-
-## Configuration Examples
-
-### Example 1: Standard 3-Tier (Recommended)
-```bash
-# Tier 1: Local (FREE)
-PREFER_OLLAMA=true
-OLLAMA_MODEL=llama3.1:8b
-OLLAMA_MAX_TOOLS_FOR_ROUTING=3
-
-# Tier 2: OpenRouter (CHEAP $)
-TIER_2_ENABLED=true
-TIER_2_PROVIDER=openrouter
-TIER_2_MAX_TOOLS=15
-OPENROUTER_MODEL=openai/gpt-4o-mini
-
-# Tier 3: Databricks (PREMIUM $$$)
-FALLBACK_ENABLED=true
-FALLBACK_PROVIDER=databricks
-```
-
-### Example 2: AWS Bedrock Ecosystem
-```bash
-# Tier 1: Local
-PREFER_OLLAMA=true
-
-# Tier 2: Bedrock with cheap models
-TIER_2_ENABLED=true
-TIER_2_PROVIDER=bedrock
-TIER_2_MAX_TOOLS=15
-AWS_BEDROCK_MODEL_ID=meta.llama3-1-8b-instruct-v1:0  # Cheap $0.99/1M
-
-# Tier 3: Bedrock with Claude
-FALLBACK_PROVIDER=bedrock
-# Would use: us.anthropic.claude-sonnet-4-5-* (expensive $3+/1M)
-```
-
-### Example 3: Azure Ecosystem
-```bash
-# Tier 1: Local
-PREFER_OLLAMA=true
-
-# Tier 2: Azure OpenAI mini
-TIER_2_ENABLED=true
-TIER_2_PROVIDER=azure-openai
-AZURE_OPENAI_DEPLOYMENT=gpt-4o-mini
-
-# Tier 3: Azure Anthropic
-FALLBACK_PROVIDER=azure-anthropic
-```
-
-### Example 4: OpenRouter → OpenAI Direct
-```bash
-# Tier 1: Local
-PREFER_OLLAMA=true
-
-# Tier 2: OpenRouter (cheap GPT via aggregator)
-TIER_2_ENABLED=true
-TIER_2_PROVIDER=openrouter
-OPENROUTER_MODEL=openai/gpt-4o-mini
-
-# Tier 3: OpenAI Direct (official API, premium)
-FALLBACK_PROVIDER=openai
-OPENAI_MODEL=gpt-4o
-```
-
----
-
-## Backward Compatibility
-
-### Strategy
-Make Tier 2 **opt-in** to preserve existing behavior.
-
-**Old Config (Still Works)**:
-```bash
-PREFER_OLLAMA=true
-FALLBACK_ENABLED=true
-FALLBACK_PROVIDER=databricks
-```
-Result: 0-2 tools → Ollama, 3+ tools → checks providers in order (legacy mode)
-
-**New Config (Explicit Tiers)**:
-```bash
-PREFER_OLLAMA=true
-TIER_2_ENABLED=true
-TIER_2_PROVIDER=openrouter
-FALLBACK_PROVIDER=databricks
-```
-Result: 0-2 tools → Ollama, 3-15 tools → openrouter, 16+ tools → databricks
-
-### Migration Path
-1. **Existing users**: No changes needed, system works as before
-2. **New users**: Can enable `TIER_2_ENABLED=true` for explicit routing
-3. **Documentation**: Show both old and new configs
-
----
-
-## Summary
-
-### Files to Modify
-
-| File | Changes | Lines | Type |
-|------|---------|-------|------|
-| `src/config/index.js` | Add tier2 config parsing & validation | ~50 | Modify |
-| `src/clients/routing.js` | Replace lines 56-94 with tier logic | ~60 | Modify |
-| `.env.example` | Document Tier 2 configuration | ~40 | Add |
-| `README.md` | Add 3-Tier Routing section | ~60 | Add |
-| `test/tier-routing.test.js` | Unit tests for tier routing | ~120 | Create |
-
-**Total Effort**: ~330 lines of changes/additions
-
----
-
-## Tier Provider Matrix (Quick Reference)
-
-| Provider | Tier 1 | Tier 2 | Tier 3 |
-|----------|--------|--------|--------|
-| **ollama** | ✅ PRIMARY | ❌ NO | ❌ NO |
-| **llamacpp** | ✅ PRIMARY | ❌ NO | ❌ NO |
-| **lmstudio** | ✅ PRIMARY | ❌ NO | ❌ NO |
-| **openrouter** | ❌ NO | ✅ ALLOWED | ✅ ALLOWED |
-| **bedrock** | ❌ NO | ✅ ALLOWED | ✅ ALLOWED |
-| **azure-openai** | ❌ NO | ✅ ALLOWED | ✅ ALLOWED |
-| **openai** | ❌ NO | ❌ NO | ✅ ALLOWED |
-| **databricks** | ❌ NO | ❌ NO | ✅ ALLOWED |
-| **azure-anthropic** | ❌ NO | ❌ NO | ✅ ALLOWED |
-
----
-
-## Decision Rationale
-
-### Why OpenAI is Tier 3 Only?
-1. Direct OpenAI API is premium-priced vs OpenRouter
-2. Users choosing direct OpenAI want "official" API = premium intent
-3. Tier 2 should be "cost optimization" - use OpenRouter for cheaper GPT access
-4. Clear separation: Tier 2 = cheap aggregators, Tier 3 = direct APIs
-
-### Why Local Providers are Tier 1 Only?
-1. Local = FREE, doesn't make sense as "fallback" for cloud
-2. Tier progression should be: Free → Cheap Cloud → Expensive Cloud
-3. If local provider fails, escalate to cloud, not to another local
-
-### Why Same Provider Can Be Tier 2 or Tier 3?
-1. **Provider ≠ Tier** - Model choice determines cost
-2. Example: Bedrock with Llama ($0.99/1M) = Tier 2, Bedrock with Claude ($3/1M) = Tier 3
-3. User controls tier assignment via model configuration
-
----
-
-## Next Steps
-
-1. ✅ User commits Bedrock changes first
-2. ✅ Implement Phase 1 (Config validation)
-3. ✅ Implement Phase 2 (Routing logic)
-4. ✅ Implement Phase 3 (Documentation)
-5. ✅ Implement Phase 4 (Tests)
-6. ✅ Test with real requests
-7. ✅ Update CHANGELOG.md
-
----
-
-## Open Questions
-
-_(To be filled in based on user feedback)_
-
-1. Should Tier 2 be opt-in (current plan) or opt-out?
-2. Should we add metrics to track tier usage?
-3. Should we add auto-learning (if Tier 2 fails X times, skip it)?
-4. Should TIER_2_MAX_TOOLS default match OPENROUTER_MAX_TOOLS_FOR_ROUTING (15)?