Learning Commands - switchAILocal

Overview

Learning commands analyze historical routing data to identify patterns, optimize model selection, and automatically apply improvements based on past successes and failures.

Learning requires the Memory system to be enabled. Run switchAILocal memory init first.

Commands

status

Display learning system status and statistics.

switchAILocal learning status

Output:

Learning System Status
=====================

Status: Active
Last Analysis: 2026-03-09 09:30:15
Decisions Analyzed: 1,247
Optimizations Applied: 15

Learned Patterns:
  - coding → geminicli:gemini-2.5-pro (92% success rate)
  - reasoning → switchai-reasoner (88% success rate)
  - fast → ollama:llama3.2 (95% success rate)

Pending Optimizations: 3
  - Vision tasks: Increase ollama:qwen3-vl usage
  - Off-hours: Switch to local models
  - PII-heavy: Force secure local models

analyze

Analyze routing history and generate optimization recommendations.

switchAILocal learning analyze [--user <hash>]

string

Analyze patterns for specific user API key hash (default: all users)

Example:

switchAILocal learning analyze --user sha256:abc123...

Output:

Analyzing routing patterns...

Data Range: Last 30 days
Total Decisions: 1,247
Unique Models: 12
Average Success Rate: 89.3%

Top Performing Routes:
  1. coding + geminicli:gemini-2.5-pro → 92% success, 234ms avg
  2. fast + ollama:llama3.2 → 95% success, 45ms avg
  3. reasoning + switchai-reasoner → 88% success, 1,234ms avg

Underperforming Routes:
  1. coding + claudecli:claude-sonnet-4 → 65% success (frequent timeouts)
  2. vision + gemini:gemini-2.5-flash → 72% success (quality issues)

Recommendations:
  ✓ Increase geminicli usage for coding tasks
  ✓ Prefer ollama for fast/simple requests
  ✓ Avoid claudecli during peak hours (timeout pattern)
  ✓ Switch vision tasks to ollama:qwen3-vl

Generated 4 optimization rules.

Analysis considers success rate, latency, error types, and time-of-day patterns.

apply

Apply learned optimizations to routing configuration.

switchAILocal learning apply [--user <hash>]

string

Apply optimizations for specific user (default: all users)

Example:

switchAILocal learning apply

Output:

Applying learned optimizations...

Creating steering rules:
  ✓ coding-optimized.yaml
  ✓ fast-local-prefer.yaml
  ✓ vision-qwen-prefer.yaml

Updating Cortex Router matrix:
  ✓ coding: geminicli:gemini-2.5-pro
  ✓ fast: ollama:llama3.2
  ✓ vision: ollama:qwen3-vl

Applied 3 steering rules and updated 3 matrix entries.

Changes will take effect immediately.
Run 'learning reset' to revert.

Applied optimizations modify your routing configuration. Back up your config before applying.

reset

Remove all learned optimizations and restore original configuration.

switchAILocal learning reset

Output:

Resetting learned optimizations...

Removing steering rules:
  ✓ Removed coding-optimized.yaml
  ✓ Removed fast-local-prefer.yaml
  ✓ Removed vision-qwen-prefer.yaml

Restoring original Cortex Router matrix:
  ✓ Restored from backup

Reset complete. Original configuration restored.

How Learning Works

Analysis Metrics

The learning system considers:

Success Rate - Percentage of successful completions
Latency - Average response time
Error Types - Categorized failure reasons
Time Patterns - Success/failure correlation with time of day
User Patterns - User-specific preferences
Quality Signals - Response quality indicators (if available)

Pattern Recognition

Learning identifies:

High-performing routes - Intent + model combinations with >85% success
Problematic patterns - Routes with <70% success or high latency
Time-of-day effects - Provider performance variations by hour
User preferences - Per-user successful model choices
Cascading opportunities - When to escalate to better models

Learning Configuration

Configure learning behavior in config.yaml:

config.yaml

intelligence:
  enabled: true
  
  # Learning system
  learning:
    enabled: true
    min_samples: 50           # Minimum decisions before analysis
    confidence_threshold: 0.8 # Minimum confidence for patterns
    auto_apply: false         # Automatically apply optimizations
    analysis_interval: 86400  # Analysis frequency (seconds)

Configuration Options

boolean

Enable the learning system (default: true)

integer

Minimum routing decisions required before pattern analysis (default: 50)

number

Minimum confidence score (0-1) for applying optimizations (default: 0.8)

boolean

Automatically apply learned optimizations without manual approval (default: false)

integer

Seconds between automatic analyses (default: 86400 = 24 hours)

Use Cases

Automatic Failover Learning

The learning system detects when specific providers consistently fail for certain intents and creates steering rules to avoid them:

# Auto-generated from learning
- id: avoid-claude-coding-peak
  intent: coding
  model: geminicli:gemini-2.5-pro
  priority: 120
  conditions:
    - hour_range: "09-17"
    - provider: claudecli
      recent_failures: ">3"

Cost Optimization

Learning identifies when cheaper/faster local models perform well and automatically prefers them:

Detects ollama:llama3.2 success for simple queries
Creates steering rules to prefer local models
Reduces cloud API costs by 40-60%

Quality Improvement

When cascade signals indicate poor quality, learning adjusts the matrix to use better models by default:

Detects low quality scores for fast intent
Upgrades default model from switchai-fast to switchai-chat
Improves overall response quality

User-Specific Optimization

Per-user analysis creates personalized routing:

switchAILocal learning analyze --user sha256:enterprise-key
switchAILocal learning apply --user sha256:enterprise-key

Generates user-specific steering rules based on their usage patterns.

Best Practices

Run analysis weekly - Execute learning analyze every 7 days to identify new patterns.

Review before applying - Always review recommendations with learning analyze before running learning apply.

Start with manual mode - Keep auto_apply: false until you’re confident in the learning patterns.

Troubleshooting

No patterns detected

Ensure memory system is initialized: memory status
Verify sufficient routing decisions: memory history --limit 100
Check min_samples threshold in config
Wait for more diverse usage patterns

Low confidence scores

Increase sample size (more routing decisions)
Check for inconsistent success patterns
Verify providers are stable (not flapping)
Review error distribution in memory logs

Optimizations not applying

Check file permissions on steering directory
Verify server has write access to config
Run steering validate to check generated rules
Check for conflicting manual steering rules

​Overview

​Commands

​status

​analyze

​apply

​reset

​How Learning Works

​Analysis Metrics

​Pattern Recognition

​Learning Configuration

​Configuration Options

​Use Cases

​Best Practices

​Troubleshooting

​See Also

Overview

Commands

status

analyze

apply

reset

How Learning Works

Analysis Metrics

Pattern Recognition

Learning Configuration

Configuration Options

Use Cases

Best Practices

Troubleshooting

See Also