Provider Architecture

# Tier 1: one def_chat()/def_local_chat() call per entry
# (each count includes the helper fn definition itself, so subtract 1)
grep -c 'def_chat(' src/core/providers/registry/catalog.rs
grep -c 'def_local_chat(' src/core/providers/registry/catalog.rs

# Tier 2: code-based provider modules (base/factory/macros/registry are infrastructure)
ls -d src/core/providers/*/ | grep -vE '/(base|factory|macros|registry)/'

// src/core/providers/registry/catalog.rs
def_chat(
    "myprovider",
    "My Provider",
    "https://api.myprovider.com/v1",
    "MYPROVIDER_API_KEY",
),

// src/core/providers/mod.rs — annotation comment alongside the other Tier 1 notes
// myprovider: Tier 1 -> registry/catalog.rs

def_local_chat("myrunner", "My Runner", "http://localhost:1234/v1"),

// src/core/traits/provider/llm_provider/trait_definition.rs
pub trait LLMProvider: Send + Sync + Debug + 'static {
    // ===== Required =====
    fn name(&self) -> &str;
    fn capabilities(&self) -> &'static [ProviderCapability];
    fn models(&self) -> &[ModelInfo];

    fn get_supported_openai_params(&self, model: &str) -> &'static [&'static str];
    async fn map_openai_params(
        &self,
        params: HashMap<String, Value>,
        model: &str,
    ) -> Result<HashMap<String, Value>, ProviderError>;
    async fn transform_request(
        &self,
        request: ChatRequest,
        context: RequestContext,
    ) -> Result<Value, ProviderError>;
    async fn transform_response(
        &self,
        raw_response: &[u8],
        model: &str,
        request_id: &str,
    ) -> Result<ChatResponse, ProviderError>;
    fn get_error_mapper(&self) -> Box<dyn ErrorMapper<ProviderError>>;
    async fn chat_completion(
        &self,
        request: ChatRequest,
        context: RequestContext,
    ) -> Result<ChatResponse, ProviderError>;
    async fn health_check(&self) -> HealthStatus;
    async fn calculate_cost(
        &self,
        model: &str,
        input_tokens: u32,
        output_tokens: u32,
    ) -> Result<f64, ProviderError>;

    // ===== Provided (default = not_supported / trivial) =====
    fn error_provider_name(&self) -> &'static str { "provider" }
    fn supports_capability(&self, capability: &ProviderCapability) -> bool {
        self.capabilities().contains(capability)
    }
    fn supports_model(&self, model: &str) -> bool {
        self.models().iter().any(|m| m.id == model)
    }
    // supports_tools / supports_streaming / supports_embeddings /
    // supports_image_generation delegate to supports_capability();
    // supports_vision() currently returns false.
    async fn chat_completion_stream(&self, request: ChatRequest, context: RequestContext)
        -> Result<Pin<Box<dyn Stream<Item = Result<ChatChunk, ProviderError>> + Send>>, ProviderError>;
    async fn embeddings(&self, request: EmbeddingRequest, context: RequestContext)
        -> Result<EmbeddingResponse, ProviderError>;
    async fn image_generation(&self, request: ImageGenerationRequest, context: RequestContext)
        -> Result<ImageGenerationResponse, ProviderError>;
    async fn audio_transcription(&self, request: TranscriptionRequest, context: RequestContext)
        -> Result<TranscriptionResponse, ProviderError>;
    async fn audio_translation(&self, request: TranslationRequest, context: RequestContext)
        -> Result<TranslationResponse, ProviderError>;
    async fn text_to_speech(&self, request: SpeechRequest, context: RequestContext)
        -> Result<SpeechResponse, ProviderError>;
    async fn get_average_latency(&self) -> Result<std::time::Duration, ProviderError>; // default 100ms
    async fn get_success_rate(&self) -> Result<f32, ProviderError>;                   // default 0.99
    async fn estimate_tokens(&self, text: &str) -> Result<u32, ProviderError>;        // len()/4
}

src/core/providers/my_provider/
├── mod.rs           # Module exports, LLMProvider impl may live here too
├── config.rs        # Config struct (often via define_provider_config!)
├── provider.rs      # Provider struct + LLMProvider impl
├── model_info.rs    # Static model metadata
├── streaming.rs     # SSE parsing (optional)
└── error.rs         # Error helpers/mappers (optional; legacy name = ProviderError alias)

pub trait ProviderConfig: Send + Sync + Clone + Debug + 'static {
    fn validate(&self) -> Result<(), String>;
    fn api_key(&self) -> Option<&str>;
    fn api_base(&self) -> Option<&str>;
    fn timeout(&self) -> std::time::Duration;
    fn max_retries(&self) -> u32;
    fn endpoint_access(&self) -> ProviderEndpointAccess { ProviderEndpointAccess::PublicOnly }
    fn use_ssrf_safe_client(&self) -> bool { false }
    // validate_standard(provider_name): shared key/timeout/retries checks
}

use std::sync::Arc;
use crate::core::providers::base::{header, BaseConfig, GlobalPoolManager, HttpMethod};
use crate::core::providers::ProviderError;
use crate::core::traits::error_mapper::trait_def::ErrorMapper;
use crate::core::traits::error_mapper::DefaultErrorMapper;
use crate::core::traits::provider::llm_provider::trait_definition::LLMProvider;
use crate::core::traits::provider::ProviderConfig;

pub struct MyProvider {
    config: MyProviderConfig,
    pool_manager: Arc<GlobalPoolManager>,
    models: Vec<ModelInfo>,
}

impl MyProvider {
    pub fn new(config: MyProviderConfig) -> Result<Self, ProviderError> {
        config.validate()
            .map_err(|e| ProviderError::configuration(PROVIDER_NAME, e))?;
        let http_config = BaseConfig {
            api_key: config.api_key().map(str::to_owned),
            api_base: config.api_base().map(str::to_owned),
            endpoint_access: config.endpoint_access(),
            timeout: config.timeout().as_secs(),
            max_retries: config.max_retries(),
            ..BaseConfig::default()
        };
        Ok(Self {
            config,
            pool_manager: Arc::new(GlobalPoolManager::new_for_provider(
                PROVIDER_NAME,
                http_config,
            )?),
            models: load_models(),
        })
    }
}

impl LLMProvider for MyProvider {
    fn name(&self) -> &'static str { PROVIDER_NAME }
    fn error_provider_name(&self) -> &'static str { PROVIDER_NAME }

    async fn chat_completion(
        &self,
        request: ChatRequest,
        context: RequestContext,
    ) -> Result<ChatResponse, ProviderError> {
        let api_key = self.config.api_key()
            .ok_or_else(|| ProviderError::authentication(PROVIDER_NAME, "API key required"))?;
        let mut headers = vec![header("Authorization", format!("Bearer {api_key}"))];
        headers.push(header("Content-Type", "application/json".to_string()));

        // url/model/request_id derived from config + request (elided)
        let body = self.transform_request(request, context).await?;
        let response = self.pool_manager
            .execute_request(&url, HttpMethod::POST, headers, Some(body))
            .await?;

        let status = response.status();
        if !status.is_success() {
            let body_text = response.text().await
                .map_err(|e| ProviderError::network(PROVIDER_NAME, e.to_string()))?;
            return Err(self.get_error_mapper().map_http_error(status.as_u16(), &body_text));
        }
        let raw = response.bytes().await
            .map_err(|e| ProviderError::network(PROVIDER_NAME, e.to_string()))?;
        self.transform_response(&raw, &model, &request_id).await
    }

    fn get_error_mapper(&self) -> Box<dyn ErrorMapper<ProviderError>> {
        Box::new(DefaultErrorMapper)
    }
    // ... remaining required methods
}