# PROP: Provider Routing -- Static + LiteLLM Integration

## Source
- **URL**: https://github.com/BerriAI/litellm (LiteLLM, 20k+ stars), https://github.com/lm-sys/RouteLLM (RouteLLM, ICLR 2025), https://aider.chat/2024/09/26/architect.html (Aider architect/editor pattern)
- **Author**: BerriAI (LiteLLM), LMSYS / UC Berkeley (RouteLLM), Aider-AI (Aider)
- **Date**: 2024-2026

## Summary
Implement two-layer provider routing for iEvo: (1) static routing that reads the agent's UAF to determine which provider/CLI to use, and (2) LiteLLM integration for API-based providers (Ollama, direct API calls). Static routing handles CLI-based providers (Claude Code, Codex) by spawning the correct CLI via PTY. LiteLLM handles API-based providers as a unified gateway. This combines the Aider architect/editor dual-model pattern with LiteLLM's 100+ provider support.

## Relevance to iEvo
iEvo currently supports only Claude Code. To achieve the "universal orchestration" vision, it needs to route different agents to different providers. The spec-writer might run on Claude (best at structured requirements), while a simple file-formatting task runs on Ollama (free, local). The routing layer bridges the gap between iEvo's agent definitions and the underlying execution environments.

## Proposed Change

### 1. Provider registry
Create `src/ievo/core/providers.py`:
- Provider enum: `CLAUDE_CODE`, `CODEX`, `OLLAMA`, `LITELLM_API`
- Provider config model: endpoint URL, auth method, CLI path, default model
- Provider detection: auto-detect installed CLIs (`which claude`, `which codex`, `which ollama`)

### 2. Static router
Create `src/ievo/core/router.py`:
- Read agent's UAF to determine target provider
- For CLI providers (Claude Code, Codex): delegate to PTY bridge
- For API providers (Ollama, direct): delegate to LiteLLM

### 3. LiteLLM integration
Add `litellm` as optional dependency:
- Use for Ollama routing: `litellm.completion(model="ollama/llama3.3", ...)`
- Use for direct API routing: `litellm.completion(model="anthropic/claude-3-sonnet", ...)`
- Cost tracking built-in

### 4. Aider-style dual-model pattern (Phase 2)
For complex pipeline stages, allow agent UAF to specify:
```yaml
capabilities:
  architect_model: powerful    # reasoning/planning on expensive model
  editor_model: fast           # code editing on cheap model
```

## Affected Components
- New: `src/ievo/core/providers.py` (provider registry)
- New: `src/ievo/core/router.py` (routing logic)
- Modified: `src/ievo/core/config.py` (provider configuration)
- New optional dependency: `litellm`
- Modified: `src/ievo/tui/app.py` (provider selection UI)

## Scores
- Applicability: 5/5
- Effort: medium (static routing is simple; LiteLLM does the heavy lifting for API)
- Impact: speed (cheap tasks on cheap models), quality (complex tasks on best models), UX (user picks provider, framework handles the rest)
