Providers

┌─────────────────────────────────────────────────────────────┐
│                      Provider Stack                         │
├─────────────────────────────────────────────────────────────┤
│  Layer 1 — Built-in Protocols (compiled Rust)               │
│    ├─ openai         → HttpProvider + OpenAiProtocol        │
│    ├─ anthropic      → HttpProvider + AnthropicProtocol     │
│    ├─ gemini         → HttpProvider + GeminiProtocol        │
│    ├─ openai-responses → HttpProvider + OpenAiResponsesProtocol │
│    ├─ codex / chatgpt → HttpProvider + Codex variant        │
│    └─ ollama         → OllamaProvider (native)              │
├─────────────────────────────────────────────────────────────┤
│  Layer 2 — Configurable Protocols (YAML, hot-reloadable)    │
│    ├─ Minimal mode: extend base protocol + differences      │
│    └─ Custom mode: full template rendering                  │
├─────────────────────────────────────────────────────────────┤
│  Layer 3 — Extension Protocols (future)                     │
│    └─ Plugin-provided adapters (WASM / Node.js)             │
└─────────────────────────────────────────────────────────────┘
                              │
                    ProtocolRegistry
                              │
                   create_provider(name, config)

pub trait AiProvider: Send + Sync {
    /// Core method — process a request and return structured response
    fn process<'a>(
        &'a self,
        payload: adapter::RequestPayload<'a>,
    ) -> Pin<Box<dyn Future<Output = Result<ProviderResponse>> + Send + 'a>>;

    /// Provider name (e.g., "deepseek", "claude")
    fn name(&self) -> &str;

    /// Provider brand color for UI (hex string)
    fn color(&self) -> &str;

    /// Whether this provider supports native tool_use
    fn supports_native_tools(&self) -> bool { false }

    /// Whether this provider supports extended thinking
    fn supports_thinking(&self) -> bool { false }

    /// Protocol identifier for model behavior resolution
    fn protocol(&self) -> &str { "unknown" }

    /// Model behavior override (e.g., "anthropic" for OpenRouter routing to Claude)
    fn model_behavior_override(&self) -> Option<&str> { None }
}

pub struct ProtocolRegistry {
    dynamic: RwLock<HashMap<String, Arc<dyn ProtocolAdapter>>>,  // YAML-loaded
    builtin: RwLock<HashMap<String, ProtocolFactory>>,           // Compiled Rust
}

[providers.claude]
protocol = "anthropic"
models = ["claude-sonnet-5"]
api_key = "sk-ant-..."
max_tokens = 8192
temperature = 0.7
enabled = true

pub struct ProviderConfig {
    /// Protocol: "openai", "anthropic", "gemini", "ollama", etc.
    pub protocol: Option<String>,

    /// API key (runtime-only, never persisted to config.toml)
    #[serde(skip_serializing)]
    pub api_key: Option<String>,

    /// Model list. First model is the default.
    /// Accepts both `model = "xxx"` (backward compat) and `models = ["xxx", ...]`.
    pub models: Vec<String>,

    /// Custom API endpoint (optional)
    pub base_url: Option<String>,

    /// Brand color for UI (default: "#808080")
    pub color: String,

    /// Request timeout in seconds (default: 300)
    pub timeout_seconds: u64,

    /// Whether the provider is enabled (default: false)
    pub enabled: bool,

    // --- Generation parameters ---
    pub max_tokens: Option<u32>,
    pub temperature: Option<f32>,
    pub top_p: Option<f32>,
    pub top_k: Option<u32>,

    // --- OpenAI-specific ---
    pub frequency_penalty: Option<f32>,
    pub presence_penalty: Option<f32>,

    // --- Claude / Gemini / Ollama ---
    pub stop_sequences: Option<String>,

    // --- Gemini-specific ---
    pub thinking_level: Option<String>,      // "LOW" or "HIGH"
    pub media_resolution: Option<String>,    // "LOW", "MEDIUM", "HIGH"

    // --- Ollama-specific ---
    pub repeat_penalty: Option<f32>,

    // --- System prompt handling ---
    /// "prepend" (default): prepend to user message
    /// "standard": use separate system message
    pub system_prompt_mode: Option<String>,

    // --- Model behavior override ---
    /// Overrides protocol-based auto-mapping.
    /// Example: "anthropic" for an OpenRouter provider routing to Claude.
    pub model_behavior: Option<String>,

    /// Whether provider passed a test connection
    pub verified: bool,
}

[providers.deepseek]
# No need to specify protocol or base_url — preset handles it
models = ["deepseek-v4-flash"]
api_key = "sk-..."
enabled = true

// Preset: base_url, protocol, and color auto-configured
let provider = create_provider("deepseek", config)?;

// Custom endpoint: specify base_url manually
config.base_url = Some("https://my-proxy.example.com/v1".to_string());
let provider = create_provider("my-provider", config)?;

┌─────────────────────────────────────────┐
│         FailoverProvider                │
├─────────────────────────────────────────┤
│  ┌─────────┐ ┌─────────┐ ┌─────────┐  │
│  │ Claude  │ │ OpenAI  │ │ Gemini  │  │
│  │ (pri=1) │ │ (pri=2) │ │ (pri=3) │  │
│  └────┬────┘ └────┬────┘ └────┬────┘  │
│       │           │          │         │
│       └───────────┼──────────┘         │
│                   ▼                     │
│     Circuit Breaker + Health Monitor    │
│         (per-provider state)            │
└─────────────────────────────────────────┘

pub struct FailoverConfig {
    pub providers: Vec<ProviderEntry>,
    pub max_retries: u32,                      // default: 2
    pub health_check_interval_secs: u64,       // default: 60
    pub unhealthy_cooldown_secs: u64,          // default: 300 (5 min)
    pub health_monitoring_enabled: bool,       // default: true
}

pub struct ProviderEntry {
    pub name: String,
    pub priority: u32,    // lower = higher priority
    pub config: ProviderConfig,
}

                    ┌─────────────┐
         success    │             │    failure count < 3
         ┌──────────│   Closed    │◄─────────────────┐
         │          │  (healthy)  │                  │
         │          └──────┬──────┘                  │
         │                 │ failure count >= 3      │
         │                 ▼                         │
         │          ┌─────────────┐                  │
         │          │             │  cooldown expired │
         │          │    Open     │──────────────────┤
         │          │  (blocked)  │                   │
         │          └──────┬──────┘                   │
         │                 │ probe request allowed    │
         │                 ▼                          │
         │          ┌─────────────┐   probe failed    │
         └──────────│  HalfOpen   │───────────────────┘
                    │  (testing)  │   (cooldown × 2)
                    └─────────────┘

pub enum ProviderHealth {
    Healthy,
    Degraded { since: Instant, cooldown_until: Instant, consecutive_failures: u32 },
    Unavailable { since: Instant, reason: String },
}

pub struct ProviderMetrics {
    pub total_requests: AtomicU64,
    pub success_count: AtomicU64,
    pub failure_count: AtomicU64,
    pub total_latency_ms: AtomicU64,
}

[failover]
max_retries = 2
unhealthy_cooldown_secs = 300

[[failover.providers]]
name = "claude"
priority = 1

[[failover.providers]]
name = "openai"
priority = 2

[[failover.providers]]
name = "gemini"
priority = 3

# ~/.aleph/protocols/my-proxy.yaml
name: my-proxy
extends: openai
base_url: https://proxy.example.com/v1
differences:
  auth:
    header: X-API-Key
    prefix: "Bearer "

# ~/.aleph/protocols/exotic-ai.yaml
name: exotic-ai
base_url: https://api.exotic.ai
custom:
  auth:
    type: header
    header: Authorization
    prefix: "Bearer "
  endpoints:
    chat: /v2/completions
    stream: /v2/completions/stream
  request_template: |
    {"model": "{{config.model}}", "messages": [{"role": "user", "content": "{{input}}"}]}
  response_mapping:
    content: "$.choices[0].message.content"
    error: "$.error.message"

m.insert(
    "my-provider",
    ProviderPreset {
        base_url: "https://api.my-provider.com/v1",
        protocol: "openai",
        color: "#ff6600",
        default_model: "my-model-v1",
    },
);

#[async_trait]
impl ProtocolAdapter for MyProtocol {
    fn build_request(&self, payload: &RequestPayload, config: &ProviderConfig) 
        -> Result<reqwest::RequestBuilder> { ... }
    
    async fn stream_deltas(&self, response: reqwest::Response)
        -> Result<BoxStream<'static, Result<ProviderDelta>>> { ... }
    
    fn name(&self) -> &'static str { "my-protocol" }
}

let provider = create_provider("my-provider", config)?;

registry.register("my-protocol", Arc::new(MyProtocol::new(client)))?;