ai-consultants 2.10.1

package/docs/SMART_ROUTING.md

@@ -0,0 +1,219 @@
+# Smart Routing - AI Consultants v2.10
+
+The Smart Routing system automatically selects the most suitable consultants based on the question category.
+
+## Enabling
+
+```bash
+# Enable classification (required)
+ENABLE_CLASSIFICATION=true
+
+# Enable smart routing
+ENABLE_SMART_ROUTING=true
+
+# Minimum affinity to include a consultant (1-10)
+MIN_AFFINITY=7
+```
+
+## Affinity Matrix
+
+Consultant-category affinity scores (scale 1-10):
+
+| Category | Gemini | Codex | Mistral | Kilo | Cursor | Aider | Amp | Kimi | Claude | Qwen3 | GLM | Grok | DeepSeek | MiniMax | Ollama |
+|----------|--------|-------|---------|------|--------|-------|-----|------|--------|-------|-----|------|----------|---------|--------|
+| **CODE_REVIEW** | 7 | **10** | 8 | 9 | 8 | 9 | 7 | 7 | 8 | 7 | 7 | 6 | 8 | 6 | 6 |
+| **BUG_DEBUG** | 7 | **10** | 9 | 8 | 8 | 9 | 7 | 6 | 7 | 7 | 6 | 6 | 8 | 5 | 6 |
+| **ARCHITECTURE** | **10** | 6 | 8 | 9 | 7 | 6 | **10** | 8 | 9 | 7 | 7 | 7 | 6 | 6 | 5 |
+| **ALGORITHM** | 9 | 8 | 7 | 8 | 7 | 7 | 7 | 6 | 8 | 8 | 8 | 7 | **10** | 6 | 6 |
+| **SECURITY** | 9 | 9 | **10** | 8 | 8 | 7 | 8 | 5 | 9 | 7 | 7 | 8 | 7 | 5 | 5 |
+| **QUICK_SYNTAX** | **10** | 8 | 5 | 6 | 7 | 7 | 5 | 5 | 7 | 7 | 6 | 5 | 7 | 5 | 6 |
+| **DATABASE** | 8 | 9 | 7 | 7 | 7 | 7 | 7 | 6 | 7 | 8 | 7 | 6 | 8 | 5 | 5 |
+| **API_DESIGN** | **10** | 9 | 7 | 8 | 8 | 6 | 9 | 6 | 8 | 7 | 7 | 7 | 6 | 6 | 5 |
+| **TESTING** | 7 | **10** | 9 | 7 | 8 | 9 | 7 | 5 | 7 | 7 | 7 | 6 | 7 | 6 | 5 |
+| **GENERAL** | 8 | 8 | 8 | 8 | 8 | 8 | 8 | 7 | 9 | 8 | 7 | 8 | 8 | 6 | 7 |
+
+**Legend:**
+- **10**: Perfect match
+- 7-9: Good match
+- 5-6: Medium match
+- 1-4: Poor match
+
+## Routing Modes
+
+The system automatically determines how many consultants to involve:
+
+| Mode | Consultants | Categories | Rationale |
+|------|-------------|------------|-----------|
+| **full** | All enabled | SECURITY, GENERAL | All for complete perspectives |
+| **selective** | Top 5 by affinity | CODE_REVIEW, BUG_DEBUG, ARCHITECTURE, ALGORITHM, DATABASE, API_DESIGN, TESTING | Best matches for the category |
+| **single** | 1 | QUICK_SYNTAX | Only the best for quick answers |
+
+### Selection Logic
+
+```
+SECURITY      → full (all)     # Too important to exclude anyone
+QUICK_SYNTAX  → single (1)    # A quick answer is sufficient
+CODE_REVIEW   → selective (5) # Top 5 by affinity
+BUG_DEBUG     → selective (5)
+ARCHITECTURE  → selective (5)
+*             → full (all)    # Default: all enabled
+```
+
+## Cost-Aware Routing (v2.3+)
+
+When `ENABLE_COST_AWARE_ROUTING=true`, the system routes queries to cheaper models based on complexity:
+
+```bash
+ENABLE_COST_AWARE_ROUTING=true
+COMPLEXITY_THRESHOLD_SIMPLE=3    # Score 1-3 = use economy models
+COMPLEXITY_THRESHOLD_MEDIUM=6    # Score 4-6 = use standard models
+                                 # Score 7-10 = use premium models
+```
+
+See [COST_RATES.md](COST_RATES.md) for model pricing by tier.
+
+## Timeout per Category
+
+Timeouts optimized based on category complexity:
+
+| Category | Timeout | Rationale |
+|----------|---------|-----------|
+| QUICK_SYNTAX | 60s | Short answers |
+| DATABASE | 120s | Medium-complexity queries |
+| TESTING | 120s | Test case generation |
+| CODE_REVIEW | 180s | Detailed analysis |
+| BUG_DEBUG | 180s | Investigation |
+| ALGORITHM | 180s | Reasoning |
+| API_DESIGN | 180s | Detailed design |
+| GENERAL | 180s | Default |
+| ARCHITECTURE | 240s | Complex design |
+| SECURITY | 240s | In-depth analysis |
+
+## Supported Categories
+
+### CODE_REVIEW
+- Code quality review
+- Best practices
+- Code style
+
+**Keywords:** review, quality, refactor, clean code
+
+### BUG_DEBUG
+- Debugging
+- Error fixing
+- Troubleshooting
+
+**Keywords:** bug, error, crash, fix, debug, problem
+
+### ARCHITECTURE
+- System design
+- Design patterns
+- Scalability
+
+**Keywords:** architect, design, pattern, microservic, scalabil, structur
+
+### ALGORITHM
+- Algorithms
+- Data structures
+- Complexity
+
+**Keywords:** algorithm, complexity, O(n), recursive, sort, search, structur
+
+### SECURITY
+- Vulnerabilities
+- Authentication
+- Authorization
+
+**Keywords:** security, vulnerabil, injection, XSS, auth
+
+### QUICK_SYNTAX
+- Quick syntax
+- Fast how-tos
+- Snippets
+
+**Keywords:** how to, syntax, example, snippet
+
+### DATABASE
+- SQL queries
+- Schema design
+- DB optimization
+
+**Keywords:** SQL, database, query, schema, index, join
+
+### API_DESIGN
+- REST API
+- GraphQL
+- Endpoint design
+
+**Keywords:** API, REST, endpoint, GraphQL, HTTP
+
+### TESTING
+- Unit test
+- Integration test
+- Test strategy
+
+**Keywords:** test, unit, integration, mock, coverage
+
+### GENERAL
+- Default for everything else
+
+## Classification Modes
+
+### Pattern-based (default)
+
+```bash
+CLASSIFICATION_MODE=pattern
+```
+
+- Fast, no API call
+- Regex matching on keywords
+- Good accuracy for clear questions
+
+### LLM-based
+
+```bash
+CLASSIFICATION_MODE=llm
+```
+
+- More accurate
+- Requires Claude CLI
+- Falls back to pattern if Claude is unavailable
+
+## Usage Example
+
+```bash
+# Consultation with smart routing
+ENABLE_SMART_ROUTING=true \
+./scripts/consult_all.sh "How can I improve the security of my API?"
+
+# Output:
+# [INFO] Category: SECURITY
+# [INFO] Routing mode: full (all enabled consultants)
+# [INFO] Timeout: 240s
+```
+
+## API Functions
+
+Functions are exported from `scripts/lib/routing.sh`:
+
+```bash
+source scripts/lib/routing.sh
+
+# Get affinity
+get_affinity "SECURITY" "Mistral"  # → 10
+
+# Select consultants
+select_consultants "SECURITY" 7    # → All enabled consultants
+
+# Check recommendation
+is_recommended "SECURITY" "Kilo" 7 && echo "Recommended"
+
+# Get timeout
+get_category_timeout "ARCHITECTURE"  # → 240
+
+# Get routing mode
+get_routing_mode "QUICK_SYNTAX"      # → single
+
+# Cost-aware selection (v2.3)
+select_consultants_cost_aware "QUICK_SYNTAX" 7  # → Economy model selection
+```

package/docs/cost_rates.json

@@ -0,0 +1,143 @@
+{
+  "version": "2.10.1",
+  "updated": "2026-03-04",
+  "models": {
+    "_comment_premium": "Premium tier models - March 2026",
+    "opus-4.6": {"input": 5.00, "output": 25.00},
+    "gemini-3.1-pro-preview": {"input": 1.25, "output": 5.00},
+    "gpt-5.3-codex": {"input": 3.00, "output": 12.00},
+    "mistral-large-3": {"input": 2.00, "output": 6.00},
+    "deepseek-reasoner": {"input": 0.55, "output": 2.19},
+    "glm-5": {"input": 0.50, "output": 2.00},
+    "grok-4-1-fast-reasoning": {"input": 5.00, "output": 15.00},
+    "qwen3.5-plus": {"input": 1.60, "output": 6.40},
+    "composer-1.5": {"input": 0.005, "output": 0.015},
+    "minimax-m2.5": {"input": 0.50, "output": 2.00},
+    "kimi-code/kimi-for-coding": {"input": 0.50, "output": 2.00},
+    "amp": {"input": 0.005, "output": 0.015},
+
+    "_comment_standard": "Standard tier models",
+    "sonnet-4.6": {"input": 3.00, "output": 15.00},
+    "gemini-3-flash-preview": {"input": 0.075, "output": 0.30},
+    "gpt-5.3": {"input": 2.50, "output": 10.00},
+    "mistral-medium-latest": {"input": 0.0027, "output": 0.0081},
+    "deepseek-v3.2": {"input": 0.27, "output": 1.10},
+    "grok-3": {"input": 3.00, "output": 9.00},
+    "minimax-m2.1": {"input": 0.30, "output": 1.50},
+
+    "_comment_economy": "Economy tier models",
+    "haiku-4.5": {"input": 0.001, "output": 0.005},
+    "gemini-2.0-flash": {"input": 0.0001, "output": 0.0004},
+    "gpt-4o-mini": {"input": 0.00015, "output": 0.0006},
+    "devstral-small-2": {"input": 0.001, "output": 0.003},
+    "deepseek-chat": {"input": 0.001, "output": 0.002},
+    "glm-4-flash": {"input": 0.001, "output": 0.003},
+    "grok-3-mini": {"input": 1.00, "output": 3.00},
+    "qwen3-32b": {"input": 0.40, "output": 1.60},
+    "minimax-m2.5-highspeed": {"input": 0.20, "output": 1.00},
+
+    "_comment_legacy": "Legacy models for backwards compatibility",
+    "claude-opus-4-5-20251124": {"input": 5.00, "output": 25.00},
+    "claude-sonnet-4-5-20251124": {"input": 3.00, "output": 15.00},
+    "claude-3-5-haiku-20241022": {"input": 0.001, "output": 0.005},
+    "gpt-5.2-codex": {"input": 3.00, "output": 12.00},
+    "gpt-5.2": {"input": 2.50, "output": 10.00},
+    "gpt-4": {"input": 0.03, "output": 0.06},
+    "gpt-4-turbo": {"input": 0.01, "output": 0.03},
+    "gpt-4o": {"input": 0.005, "output": 0.015},
+    "o1": {"input": 0.015, "output": 0.06},
+    "o3": {"input": 0.015, "output": 0.06},
+    "claude-3-opus": {"input": 0.015, "output": 0.075},
+    "claude-3-sonnet": {"input": 0.003, "output": 0.015},
+    "claude-3-haiku": {"input": 0.00025, "output": 0.00125},
+    "mistral-large": {"input": 0.004, "output": 0.012},
+    "mistral-medium": {"input": 0.0027, "output": 0.0081},
+    "mistral-small": {"input": 0.001, "output": 0.003},
+    "glm-4.7": {"input": 0.50, "output": 2.00},
+    "qwen3-max": {"input": 1.60, "output": 6.40},
+    "qwen3-235b-a22b": {"input": 0.80, "output": 3.20},
+    "kilo": {"input": 0.002, "output": 0.006},
+    "cursor": {"input": 0.005, "output": 0.015},
+    "qwen-max": {"input": 0.004, "output": 0.012},
+    "qwen-plus": {"input": 0.002, "output": 0.006},
+    "qwen-turbo": {"input": 0.0008, "output": 0.002},
+    "glm-4": {"input": 0.003, "output": 0.009},
+    "glm-3-turbo": {"input": 0.001, "output": 0.003},
+    "grok-beta": {"input": 0.005, "output": 0.015},
+    "grok-2": {"input": 0.01, "output": 0.03},
+    "deepseek-coder": {"input": 0.001, "output": 0.002}
+  },
+  "consultant_fallbacks": {
+    "_comment": "Premium defaults - Updated March 2026",
+    "claude": "opus-4.6",
+    "gemini": "gemini-3.1-pro-preview",
+    "codex": "gpt-5.3-codex",
+    "mistral": "mistral-large-3",
+    "deepseek": "deepseek-reasoner",
+    "glm": "glm-5",
+    "grok": "grok-4-1-fast-reasoning",
+    "qwen3": "qwen3.5-plus",
+    "aider": "gpt-5.3-codex",
+    "kilo": "auto",
+    "cursor": "composer-1.5",
+    "amp": "amp",
+    "kimi": "kimi-code/kimi-for-coding",
+    "minimax": "minimax-m2.5",
+    "ollama": "qwen2.5-coder:32b"
+  },
+  "model_tiers": {
+    "_comment": "Model tiers for apply_model_tier() function",
+    "premium": {
+      "claude": "opus-4.6",
+      "gemini": "gemini-3.1-pro-preview",
+      "codex": "gpt-5.3-codex",
+      "mistral": "mistral-large-3",
+      "deepseek": "deepseek-reasoner",
+      "glm": "glm-5",
+      "grok": "grok-4-1-fast-reasoning",
+      "qwen3": "qwen3.5-plus",
+      "aider": "gpt-5.3-codex",
+      "kilo": "auto",
+      "cursor": "composer-1.5",
+      "amp": "amp",
+      "kimi": "kimi-code/kimi-for-coding",
+      "minimax": "minimax-m2.5",
+      "ollama": "qwen2.5-coder:32b"
+    },
+    "standard": {
+      "claude": "sonnet-4.6",
+      "gemini": "gemini-3-flash-preview",
+      "codex": "gpt-5.3",
+      "mistral": "mistral-medium-latest",
+      "deepseek": "deepseek-v3.2",
+      "glm": "glm-5",
+      "grok": "grok-3",
+      "qwen3": "qwen3.5-plus",
+      "aider": "gpt-5.3",
+      "kilo": "auto",
+      "cursor": "composer-1.5",
+      "amp": "amp",
+      "kimi": "kimi-code/kimi-for-coding",
+      "minimax": "minimax-m2.1",
+      "ollama": "llama3.3"
+    },
+    "economy": {
+      "claude": "haiku-4.5",
+      "gemini": "gemini-2.0-flash",
+      "codex": "gpt-4o-mini",
+      "mistral": "devstral-small-2",
+      "deepseek": "deepseek-chat",
+      "glm": "glm-4-flash",
+      "grok": "grok-3-mini",
+      "qwen3": "qwen3-32b",
+      "aider": "gpt-4o-mini",
+      "kilo": "auto",
+      "cursor": "gemini-2.0-flash",
+      "amp": "amp",
+      "kimi": "kimi-code/kimi-for-coding",
+      "minimax": "minimax-m2.5-highspeed",
+      "ollama": "llama3.2"
+    }
+  },
+  "default_rate": {"input": 0.005, "output": 0.015}
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "ai-consultants",
+  "version": "2.10.1",
+  "description": "Multi-model AI deliberation system - query up to 15 AI consultants for coding problems",
+  "bin": {
+    "ai-consultants": "bin/ai-consultants"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "!scripts/test_functions.sh",
+    "templates/",
+    ".claude/commands/",
+    "SKILL.md",
+    "CLAUDE.md",
+    "docs/",
+    "references/"
+  ],
+  "keywords": [
+    "ai",
+    "consultants",
+    "multi-model",
+    "claude",
+    "gemini",
+    "codex",
+    "cli",
+    "deliberation",
+    "coding"
+  ],
+  "author": "Matteo Scurati",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/matteoscurati/ai-consultants.git"
+  },
+  "homepage": "https://github.com/matteoscurati/ai-consultants#readme",
+  "bugs": {
+    "url": "https://github.com/matteoscurati/ai-consultants/issues"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "engines": {
+    "node": ">=14"
+  }
+}

package/references/configuration.md

@@ -0,0 +1,141 @@
+# AI Consultants - Full Configuration Reference
+
+All configuration is done via environment variables. Set them in your shell, `.env` file, or inline before the command.
+
+## Defaults
+
+```bash
+DEFAULT_PRESET=balanced      # Preset when --preset not given
+DEFAULT_STRATEGY=majority    # Strategy when --strategy not given
+```
+
+## Core Features
+
+```bash
+ENABLE_DEBATE=true           # Multi-agent debate
+ENABLE_SYNTHESIS=true        # Automatic synthesis
+ENABLE_PEER_REVIEW=false     # Anonymous peer review
+ENABLE_PANIC_MODE=auto       # Auto-rigor for uncertainty
+ENABLE_SMART_ROUTING=false   # Category-based consultant selection
+ENABLE_COST_TRACKING=true    # Track API usage costs
+```
+
+## CLI/API Mode Switching (v2.6+)
+
+Five consultants support switching between CLI and API mode. When API mode is enabled, the CLI is not used.
+
+```bash
+GEMINI_USE_API=false         # Use Google AI API instead of gemini CLI
+CODEX_USE_API=false          # Use OpenAI API instead of codex CLI
+CLAUDE_USE_API=false         # Use Anthropic API instead of claude CLI
+MISTRAL_USE_API=false        # Use Mistral API instead of vibe CLI
+QWEN3_USE_API=false          # Use qwen CLI (default) or DashScope API
+```
+
+### API Keys
+
+| Agent | API Key Variable | Notes |
+|-------|------------------|-------|
+| Gemini | `GEMINI_API_KEY` | Google AI API key |
+| Codex | `OPENAI_API_KEY` | OpenAI API key |
+| Claude | `ANTHROPIC_API_KEY` | Anthropic API key |
+| Mistral | `MISTRAL_API_KEY` | Mistral API key |
+| Qwen3 | `QWEN3_API_KEY` | DashScope API key |
+
+## Consultant Toggles and Models
+
+```bash
+# Consultants enabled by default
+ENABLE_GEMINI=true
+ENABLE_CODEX=true
+ENABLE_MISTRAL=true
+ENABLE_KILO=true
+ENABLE_CURSOR=true
+ENABLE_AIDER=true
+
+# Opt-in consultants
+ENABLE_AMP=false             # Amp CLI - The Systems Thinker
+ENABLE_KIMI=false            # Kimi CLI - The Eastern Sage
+ENABLE_QWEN3=false           # Qwen CLI/API - The Analyst
+ENABLE_CLAUDE=false          # Claude CLI - The Synthesizer
+ENABLE_OLLAMA=false          # Ollama - The Local Expert
+ENABLE_MINIMAX=false         # MiniMax API - The Pragmatic Optimizer
+
+# API-only consultants
+ENABLE_GLM=false
+ENABLE_GROK=false
+ENABLE_DEEPSEEK=false
+```
+
+### Model Overrides
+
+```bash
+GEMINI_MODEL=gemini-3.1-pro-preview
+CODEX_MODEL=gpt-5.3-codex
+CLAUDE_MODEL=opus-4.6
+MISTRAL_MODEL=mistral-large-3
+KILO_MODEL=auto
+CURSOR_MODEL=composer-1.5
+AIDER_MODEL=gpt-5.3-codex
+AMP_MODEL=amp
+KIMI_MODEL=kimi-code/kimi-for-coding
+QWEN3_MODEL=qwen3.5-plus
+GLM_MODEL=glm-5
+GROK_MODEL=grok-4-1-fast-reasoning
+DEEPSEEK_MODEL=deepseek-reasoner
+MINIMAX_MODEL=MiniMax-M2.5
+OLLAMA_MODEL=qwen2.5-coder:32b
+```
+
+## Model Quality Tiers (v2.5)
+
+```bash
+# Set all consultants to a tier programmatically
+source scripts/config.sh
+apply_model_tier "premium"   # Latest flagship models
+apply_model_tier "standard"  # Good quality at reasonable cost
+apply_model_tier "economy"   # Optimized for speed and low cost
+```
+
+## Ollama (Local Models)
+
+```bash
+ENABLE_OLLAMA=true
+OLLAMA_MODEL=qwen2.5-coder:32b
+OLLAMA_HOST=http://localhost:11434
+OLLAMA_TIMEOUT=300
+```
+
+## Budget Management (v2.4)
+
+```bash
+ENABLE_BUDGET_LIMIT=false
+MAX_SESSION_COST=1.00        # Maximum cost in USD
+BUDGET_ACTION=warn           # warn or stop
+```
+
+## Caching and Optimization (v2.3)
+
+```bash
+ENABLE_SEMANTIC_CACHE=true   # Cache responses by query fingerprint
+CACHE_TTL_HOURS=24           # Cache expiration
+ENABLE_RESPONSE_LIMITS=false # Limit output tokens by category
+ENABLE_COST_AWARE_ROUTING=false  # Route simple queries to cheaper models
+ENABLE_DEBATE_OPTIMIZATION=false # Skip debate if all agree
+ENABLE_COMPACT_REPORT=true   # Summaries only in reports
+```
+
+## Timeouts and Retries
+
+```bash
+MAX_RETRIES=2
+RETRY_DELAY_SECONDS=5
+GEMINI_TIMEOUT=240
+CODEX_TIMEOUT=180
+MISTRAL_TIMEOUT=180
+KILO_TIMEOUT=180
+CURSOR_TIMEOUT=180
+AMP_TIMEOUT=180
+KIMI_TIMEOUT=180
+OLLAMA_TIMEOUT=300           # Longer for local inference
+```

package/references/details.md

@@ -0,0 +1,60 @@
+# AI Consultants - Reference Details
+
+Read this file when the user asks about presets, strategies, bash usage, best practices, or known limitations.
+
+## Configuration Presets
+
+| Preset | Consultants | Use Case |
+|--------|-------------|----------|
+| `minimal` | 2 (Gemini + Codex) | Quick questions |
+| `balanced` | 4 (+Mistral +Kilo) | Standard use |
+| `thorough` | 5 (+Cursor) | Comprehensive |
+| `high-stakes` | All + debate | Critical decisions |
+| `local` | Ollama only | Full privacy |
+| `security` | Security-focused | +Debate |
+| `cost-capped` | Budget-friendly | Low cost |
+
+## Synthesis Strategies
+
+| Strategy | Description |
+|----------|-------------|
+| `majority` | Most common answer wins (default) |
+| `risk_averse` | Weight conservative responses |
+| `security_first` | Prioritize security |
+| `cost_capped` | Prefer cheaper solutions |
+| `compare_only` | No recommendation |
+
+## Bash Usage
+
+```bash
+cd ~/.claude/skills/ai-consultants
+
+# With preset
+./scripts/consult_all.sh --preset balanced "Best approach for caching?"
+
+# With strategy
+./scripts/consult_all.sh --strategy risk_averse "Security question"
+
+# With local model
+./scripts/consult_all.sh --preset local "Private question"
+```
+
+## Best Practices
+
+### Security
+
+- **Never** include credentials in queries
+- Use `--preset local` for sensitive code
+
+### Effective Queries
+
+- Be specific about the question
+- Include constraints (performance, etc.)
+- Use debate for controversial decisions
+
+## Known Limitations
+
+- Minimum 2 consultants required
+- Smart Routing off by default
+- Synthesis requires Claude CLI (fallback available)
+- Estimated costs (heuristic token counting)