CFN Provider Routing - Cross-Provider Model Compatibility

Status: Production Ready | Category: Provider Integration | Complexity: Low

Overview

Translates agent-specified models (sonnet/haiku/opus) to provider-specific model names. Enables seamless cross-provider compatibility without modifying agent profiles.

Core Function

Primary Use Case: Agent spawning with provider-specific model resolution Secondary Use Case: Cost optimization through tier-based model selection Validation: Model mapping completeness and provider support verification

Usage Patterns

Direct Model Resolution

# Basic usage - resolve sonnet for Z.ai
./resolve-provider-model.ts --provider zai --model sonnet
# Returns: glm-4.6

# With cost optimization
./resolve-provider-model.ts --provider kimi --model haiku --tier economy
# Returns: kimi-k2-turbo-preview

Integration with Agent Spawning

# In agent spawning scripts
AGENT_MODEL="sonnet"
PROVIDER="zai"
RESOLVED_MODEL=$(./resolve-provider-model.ts --provider "$PROVIDER" --model "$AGENT_MODEL")
export ANTHROPIC_MODEL="$RESOLVED_MODEL"

Configuration Validation

# Check provider support
./resolve-provider-model.ts --summary
# Returns JSON with supported providers and models

Parameters

Required Parameters

• --provider <provider>: Target provider (zai, kimi, openrouter, gemini, xai, anthropic)

Optional Parameters

• --model <agent-model>: Agent-specified model (sonnet, haiku, opus)
• --tier <cost-tier>: Cost optimization tier (economy, standard, premium)
• --summary: Show configuration summary

Return Values

Success

• Model resolution: Returns provider-specific model name as string
• Configuration summary: Returns JSON with provider/model mappings

Error Conditions

• Provider not supported: Returns error with supported providers list
• Configuration missing: Falls back to basic mappings with warning
• Invalid parameters: Returns usage information

Integration Points

Agent Spawning Pipeline

Agent Profile (model: sonnet) → Provider Router → Z.ai (glm-4.6)

CLI Mode Provider Selection

/cfn-loop-cli "task" --provider zai → Router → Agent with glm-4.6

Cost Optimization

--tier economy → Router → Fast models for simple tasks
--tier premium → Router → High-quality models for complex tasks

Examples

Basic Provider Routing

# Spawn backend-developer with Z.ai
AGENT_TYPE="backend-developer"  # Has model: sonnet
PROVIDER="zai"
MODEL=$(./resolve-provider-model.ts --provider "$PROVIDER" --model sonnet)
# MODEL="glm-4.6"

Cross-Provider Compatibility

# Same agent, different providers
./resolve-provider-model.ts --provider zai --model sonnet      # glm-4.6
./resolve-provider-model.ts --provider kimi --model sonnet     # kimi-k2-turbo-preview
./resolve-provider-model.ts --provider openrouter --model sonnet # anthropic/claude-sonnet-4.5

Cost-Optimized Execution

# Economy mode for bulk operations
ECONOMY_MODEL=$(./resolve-provider-model.ts --provider kimi --model haiku --tier economy)
# Returns: kimi-k2-turbo-preview (fast, cost-effective)

# Premium mode for critical tasks
PREMIUM_MODEL=$(./resolve-provider-model.ts --provider openrouter --model sonnet --tier premium)
# Returns: anthropic/claude-sonnet-4.5 (high quality)

Dependencies

External Dependencies

• Node.js: Runtime environment
• js-yaml: YAML configuration parsing (bundled)

Configuration Dependencies

• provider-model-mappings.yaml: Model mapping configuration
• No Redis required: Pure configuration resolution

Anti-Patterns

❌ Manual Model Hardcoding

# AVOID: Hardcoded provider-specific models
if [[ "$PROVIDER" == "zai" ]]; then
  export ANTHROPIC_MODEL="glm-4.6"
fi

❌ Agent Profile Modification

# AVOID: Updating 65+ agent files for new provider
<!-- PROVIDER_PARAMETERS
provider: zai
model: glm-4.6  # Wrong approach - maintenance nightmare
-->

✅ Centralized Mapping

# CORRECT: Use centralized resolver
MODEL=$(./resolve-provider-model.ts --provider "$PROVIDER" --model "$AGENT_MODEL")
export ANTHROPIC_MODEL="$MODEL"

Performance Characteristics

• Resolution latency: <1ms per lookup
• Memory footprint: <1MB configuration object
• Startup time: <10ms YAML file load
• Scalability: O(1) lookup time, unlimited concurrent requests

Monitoring & Troubleshooting

Configuration Validation

# Check if all providers are supported
./resolve-provider-model.ts --summary

Model Resolution Testing

# Test all agent models for a provider
for model in sonnet haiku opus; do
  echo "$model → $(./resolve-provider-model.ts --provider zai --model "$model")"
done

Common Issues

• Provider not found: Check provider name spelling in configuration
• Model resolution fails: Verify agent model exists in mappings
• Configuration missing: Fallback to basic mappings automatically

Evolution Path

Phase 1: Current Implementation

• Basic model mapping resolution
• Configuration file-based approach
• CLI integration for agent spawning

Phase 2: Enhanced Features

• Dynamic model capability detection
• Provider-specific optimization hints
• Integration with cost tracking

Phase 3: Advanced Routing

• AI-driven model selection based on task complexity
• Performance-based model switching
• Multi-provider failover routing