agentic-flow 1.0.0

package/docs/router/ROUTER_CONFIG_REFERENCE.md

@@ -0,0 +1,577 @@
+# Multi-Model Router Configuration Reference
+
+## Overview
+
+The router configuration file (`router.config.json`) controls how the agentic-flow system selects and routes requests to different LLM providers.
+
+## Configuration File Location
+
+- **Default**: `~/.agentic-flow/router.config.json`
+- **Custom**: Use `--router-config <path>` CLI option
+- **Environment**: Set `AGENTIC_FLOW_ROUTER_CONFIG` variable
+
+## Complete Configuration Schema
+
+```json
+{
+  "version": "1.0",
+  "defaultProvider": "anthropic",
+  "fallbackChain": ["anthropic", "openai", "ollama"],
+  "providers": {
+    "anthropic": {
+      "apiKey": "${ANTHROPIC_API_KEY}",
+      "baseUrl": "https://api.anthropic.com",
+      "models": {
+        "default": "claude-3-5-sonnet-20241022",
+        "fast": "claude-3-5-haiku-20241022",
+        "advanced": "claude-3-opus-20240229"
+      },
+      "timeout": 120000,
+      "maxRetries": 3,
+      "retryDelay": 1000,
+      "rateLimit": {
+        "requestsPerMinute": 50,
+        "tokensPerMinute": 100000
+      }
+    },
+    "openai": {
+      "apiKey": "${OPENAI_API_KEY}",
+      "organization": "${OPENAI_ORG_ID}",
+      "baseUrl": "https://api.openai.com/v1",
+      "models": {
+        "default": "gpt-4-turbo-preview",
+        "fast": "gpt-3.5-turbo",
+        "advanced": "gpt-4"
+      },
+      "timeout": 120000,
+      "maxRetries": 3
+    },
+    "openrouter": {
+      "apiKey": "${OPENROUTER_API_KEY}",
+      "baseUrl": "https://openrouter.ai/api/v1",
+      "models": {
+        "default": "anthropic/claude-3.5-sonnet",
+        "fast": "anthropic/claude-3-haiku",
+        "advanced": "anthropic/claude-3-opus"
+      },
+      "preferences": {
+        "requireParameters": true,
+        "dataCollection": "deny",
+        "order": ["anthropic", "openai", "google"]
+      }
+    },
+    "ollama": {
+      "baseUrl": "http://localhost:11434",
+      "models": {
+        "default": "llama3:8b",
+        "fast": "phi3:mini",
+        "advanced": "llama3:70b"
+      },
+      "gpuLayers": 35,
+      "contextWindow": 8192,
+      "numPredict": 2048
+    },
+    "litellm": {
+      "enabled": true,
+      "fallbackModels": [
+        "gpt-4-turbo-preview",
+        "claude-3-opus-20240229",
+        "command-r-plus"
+      ],
+      "timeout": 180000
+    }
+  },
+  "routing": {
+    "mode": "cost-optimized",
+    "rules": [
+      {
+        "condition": {
+          "agentType": ["researcher", "planner"],
+          "complexity": "low"
+        },
+        "action": {
+          "provider": "openai",
+          "model": "gpt-3.5-turbo"
+        },
+        "reason": "Simple tasks use cheaper models"
+      },
+      {
+        "condition": {
+          "agentType": ["coder", "reviewer"],
+          "requiresTools": true
+        },
+        "action": {
+          "provider": "anthropic",
+          "model": "claude-3-5-sonnet-20241022"
+        },
+        "reason": "Tool calling tasks need Claude"
+      },
+      {
+        "condition": {
+          "privacy": "high",
+          "localOnly": true
+        },
+        "action": {
+          "provider": "ollama",
+          "model": "llama3:70b"
+        },
+        "reason": "Privacy-sensitive tasks use local models"
+      }
+    ],
+    "costOptimization": {
+      "enabled": true,
+      "maxCostPerRequest": 0.50,
+      "budgetAlerts": {
+        "daily": 10.00,
+        "monthly": 250.00
+      },
+      "preferCheaper": true,
+      "costThreshold": 0.1
+    },
+    "performance": {
+      "timeout": 120000,
+      "concurrentRequests": 5,
+      "circuitBreaker": {
+        "enabled": true,
+        "threshold": 5,
+        "timeout": 60000,
+        "resetTimeout": 30000
+      }
+    }
+  },
+  "toolCalling": {
+    "translationEnabled": true,
+    "defaultFormat": "anthropic",
+    "formatMapping": {
+      "openai": "openai-functions",
+      "anthropic": "anthropic-tools",
+      "openrouter": "auto-detect",
+      "ollama": "manual"
+    },
+    "fallbackStrategy": "disable-tools"
+  },
+  "monitoring": {
+    "enabled": true,
+    "logLevel": "info",
+    "metrics": {
+      "trackCost": true,
+      "trackLatency": true,
+      "trackTokens": true,
+      "trackErrors": true
+    },
+    "alerts": {
+      "costThreshold": 5.00,
+      "errorRate": 0.1,
+      "latencyThreshold": 30000
+    }
+  },
+  "cache": {
+    "enabled": true,
+    "ttl": 3600,
+    "maxSize": 1000,
+    "strategy": "lru"
+  }
+}
+```
+
+## Configuration Sections
+
+### 1. Global Settings
+
+#### `version`
+- **Type**: String
+- **Required**: Yes
+- **Description**: Configuration schema version
+- **Example**: `"1.0"`
+
+#### `defaultProvider`
+- **Type**: String
+- **Required**: Yes
+- **Description**: Primary provider to use when no routing rules match
+- **Options**: `"anthropic"`, `"openai"`, `"openrouter"`, `"ollama"`, `"litellm"`
+- **Example**: `"anthropic"`
+
+#### `fallbackChain`
+- **Type**: Array<String>
+- **Required**: No
+- **Description**: Ordered list of providers to try if default fails
+- **Example**: `["anthropic", "openai", "ollama"]`
+
+### 2. Provider Configuration
+
+Each provider has specific configuration options:
+
+#### Anthropic Provider
+
+```json
+{
+  "apiKey": "${ANTHROPIC_API_KEY}",
+  "baseUrl": "https://api.anthropic.com",
+  "models": {
+    "default": "claude-3-5-sonnet-20241022",
+    "fast": "claude-3-5-haiku-20241022",
+    "advanced": "claude-3-opus-20240229"
+  },
+  "timeout": 120000,
+  "maxRetries": 3,
+  "retryDelay": 1000
+}
+```
+
+**Options**:
+- `apiKey`: API key (supports env var substitution)
+- `baseUrl`: API endpoint URL
+- `models.default`: Default model for this provider
+- `models.fast`: Fast/cheap model variant
+- `models.advanced`: Advanced/expensive model variant
+- `timeout`: Request timeout in milliseconds
+- `maxRetries`: Number of retry attempts
+- `retryDelay`: Delay between retries in milliseconds
+
+#### OpenAI Provider
+
+```json
+{
+  "apiKey": "${OPENAI_API_KEY}",
+  "organization": "${OPENAI_ORG_ID}",
+  "baseUrl": "https://api.openai.com/v1",
+  "models": {
+    "default": "gpt-4-turbo-preview",
+    "fast": "gpt-3.5-turbo",
+    "advanced": "gpt-4"
+  }
+}
+```
+
+**Additional Options**:
+- `organization`: OpenAI organization ID
+
+#### OpenRouter Provider
+
+```json
+{
+  "apiKey": "${OPENROUTER_API_KEY}",
+  "baseUrl": "https://openrouter.ai/api/v1",
+  "preferences": {
+    "requireParameters": true,
+    "dataCollection": "deny",
+    "order": ["anthropic", "openai", "google"]
+  }
+}
+```
+
+**Additional Options**:
+- `preferences.requireParameters`: Require model parameters in requests
+- `preferences.dataCollection`: Data collection preference (`"allow"` or `"deny"`)
+- `preferences.order`: Provider preference order
+
+#### Ollama Provider
+
+```json
+{
+  "baseUrl": "http://localhost:11434",
+  "models": {
+    "default": "llama3:8b",
+    "fast": "phi3:mini",
+    "advanced": "llama3:70b"
+  },
+  "gpuLayers": 35,
+  "contextWindow": 8192,
+  "numPredict": 2048
+}
+```
+
+**Additional Options**:
+- `gpuLayers`: Number of layers to offload to GPU
+- `contextWindow`: Maximum context window size
+- `numPredict`: Maximum tokens to predict
+
+#### LiteLLM Provider
+
+```json
+{
+  "enabled": true,
+  "fallbackModels": [
+    "gpt-4-turbo-preview",
+    "claude-3-opus-20240229",
+    "command-r-plus"
+  ],
+  "timeout": 180000
+}
+```
+
+### 3. Routing Rules
+
+#### Routing Modes
+
+- **`manual`**: User explicitly selects provider/model via CLI
+- **`cost-optimized`**: Automatically select cheapest suitable provider
+- **`performance-optimized`**: Prioritize fastest provider
+- **`quality-optimized`**: Prioritize most capable model
+- **`rule-based`**: Use custom routing rules
+
+#### Rule Syntax
+
+```json
+{
+  "condition": {
+    "agentType": ["coder", "reviewer"],
+    "requiresTools": true,
+    "complexity": "high",
+    "privacy": "high",
+    "localOnly": false
+  },
+  "action": {
+    "provider": "anthropic",
+    "model": "claude-3-5-sonnet-20241022",
+    "temperature": 0.7,
+    "maxTokens": 4000
+  },
+  "reason": "Description of why this rule exists"
+}
+```
+
+**Condition Fields**:
+- `agentType`: Array of agent types this rule applies to
+- `requiresTools`: Boolean, whether task requires tool calling
+- `complexity`: String, task complexity level (`"low"`, `"medium"`, `"high"`)
+- `privacy`: String, privacy requirement level
+- `localOnly`: Boolean, whether to restrict to local models
+
+**Action Fields**:
+- `provider`: Provider to use
+- `model`: Specific model name
+- `temperature`: Model temperature (0.0-1.0)
+- `maxTokens`: Maximum tokens to generate
+
+### 4. Cost Optimization
+
+```json
+{
+  "costOptimization": {
+    "enabled": true,
+    "maxCostPerRequest": 0.50,
+    "budgetAlerts": {
+      "daily": 10.00,
+      "monthly": 250.00
+    },
+    "preferCheaper": true,
+    "costThreshold": 0.1
+  }
+}
+```
+
+**Options**:
+- `enabled`: Enable cost optimization
+- `maxCostPerRequest`: Maximum cost per request in USD
+- `budgetAlerts.daily`: Daily budget alert threshold
+- `budgetAlerts.monthly`: Monthly budget alert threshold
+- `preferCheaper`: Prefer cheaper models when quality difference is minimal
+- `costThreshold`: Cost difference threshold for preferCheaper (USD)
+
+### 5. Tool Calling Configuration
+
+```json
+{
+  "toolCalling": {
+    "translationEnabled": true,
+    "defaultFormat": "anthropic",
+    "formatMapping": {
+      "openai": "openai-functions",
+      "anthropic": "anthropic-tools",
+      "openrouter": "auto-detect",
+      "ollama": "manual"
+    },
+    "fallbackStrategy": "disable-tools"
+  }
+}
+```
+
+**Options**:
+- `translationEnabled`: Enable automatic tool format translation
+- `defaultFormat`: Default tool format to use
+- `formatMapping`: Map providers to tool formats
+- `fallbackStrategy`: What to do when tools not supported (`"disable-tools"`, `"use-text"`, `"fail"`)
+
+### 6. Monitoring & Logging
+
+```json
+{
+  "monitoring": {
+    "enabled": true,
+    "logLevel": "info",
+    "metrics": {
+      "trackCost": true,
+      "trackLatency": true,
+      "trackTokens": true,
+      "trackErrors": true
+    },
+    "alerts": {
+      "costThreshold": 5.00,
+      "errorRate": 0.1,
+      "latencyThreshold": 30000
+    }
+  }
+}
+```
+
+**Log Levels**: `"debug"`, `"info"`, `"warn"`, `"error"`
+
+### 7. Caching
+
+```json
+{
+  "cache": {
+    "enabled": true,
+    "ttl": 3600,
+    "maxSize": 1000,
+    "strategy": "lru"
+  }
+}
+```
+
+**Options**:
+- `ttl`: Time to live in seconds
+- `maxSize`: Maximum cache entries
+- `strategy`: Cache eviction strategy (`"lru"`, `"fifo"`, `"lfu"`)
+
+## Environment Variable Substitution
+
+Use `${VAR_NAME}` syntax to reference environment variables:
+
+```json
+{
+  "apiKey": "${ANTHROPIC_API_KEY}",
+  "organization": "${OPENAI_ORG_ID}"
+}
+```
+
+## CLI Override Options
+
+Configuration can be overridden via CLI:
+
+```bash
+# Override provider
+npx agentic-flow --provider openai --task "..."
+
+# Override model
+npx agentic-flow --model gpt-4 --task "..."
+
+# Override routing mode
+npx agentic-flow --router-mode cost-optimized --task "..."
+
+# Use custom config file
+npx agentic-flow --router-config ./custom-router.json --task "..."
+```
+
+## Example Configurations
+
+### Development Configuration
+
+```json
+{
+  "version": "1.0",
+  "defaultProvider": "ollama",
+  "fallbackChain": ["ollama", "anthropic"],
+  "providers": {
+    "ollama": {
+      "baseUrl": "http://localhost:11434",
+      "models": {
+        "default": "llama3:8b"
+      }
+    },
+    "anthropic": {
+      "apiKey": "${ANTHROPIC_API_KEY}",
+      "models": {
+        "default": "claude-3-5-haiku-20241022"
+      }
+    }
+  },
+  "routing": {
+    "mode": "manual"
+  }
+}
+```
+
+### Production Configuration
+
+```json
+{
+  "version": "1.0",
+  "defaultProvider": "anthropic",
+  "fallbackChain": ["anthropic", "openai", "openrouter"],
+  "routing": {
+    "mode": "cost-optimized",
+    "costOptimization": {
+      "enabled": true,
+      "maxCostPerRequest": 1.00,
+      "budgetAlerts": {
+        "daily": 50.00,
+        "monthly": 1000.00
+      }
+    }
+  },
+  "monitoring": {
+    "enabled": true,
+    "logLevel": "warn"
+  }
+}
+```
+
+### Privacy-Focused Configuration
+
+```json
+{
+  "version": "1.0",
+  "defaultProvider": "ollama",
+  "providers": {
+    "ollama": {
+      "baseUrl": "http://localhost:11434",
+      "models": {
+        "default": "llama3:70b",
+        "fast": "phi3:mini"
+      }
+    }
+  },
+  "routing": {
+    "mode": "rule-based",
+    "rules": [
+      {
+        "condition": {
+          "privacy": "high"
+        },
+        "action": {
+          "provider": "ollama",
+          "model": "llama3:70b"
+        }
+      }
+    ]
+  }
+}
+```
+
+## Validation
+
+Validate configuration file:
+
+```bash
+npx agentic-flow router validate ./router.config.json
+```
+
+## Migration
+
+Migrate from old configuration format:
+
+```bash
+npx agentic-flow router migrate ./old-config.json ./new-config.json
+```
+
+## Best Practices
+
+1. **Use Environment Variables**: Never hardcode API keys
+2. **Set Fallback Chain**: Always configure fallbacks for reliability
+3. **Enable Cost Tracking**: Monitor spending with budget alerts
+4. **Use Routing Rules**: Optimize cost and performance with smart routing
+5. **Enable Caching**: Reduce API calls and costs
+6. **Configure Timeouts**: Set appropriate timeouts for your use case
+7. **Test Configuration**: Validate before deploying to production