Struct EngineApi 

pub struct EngineApi { /* private fields */ }

Engine API facade — model catalog introspection + config writes + routing.

Holds a shared reference to the live config (behind RwLock) and the path to config.toml so write operations can persist to disk. Routing stats are shared with AgentRuntime via Arc<RoutingStats>.

When config writes change the model or API key, EngineApi rebuilds OxiosEngine via [EngineHandle] so the runtime picks up the change on the next agent execution (hot-swap, no restart required).

Implementations

impl EngineApi

pub fn new( config: Arc<RwLock<OxiosConfig>>, config_path: PathBuf, routing_stats: Arc<RoutingStats>, engine_handle: Arc<EngineHandle>, ) -> Self

Create a new EngineApi.

• config — shared config store (backed by RwLock)
• config_path — path to config.toml for persistence
• routing_stats — shared stats tracker (shared with AgentRuntime)
• engine_handle — hot-swap handle for live engine replacement

pub fn routing_stats(&self) -> Arc<RoutingStats>

Get the shared RoutingStats reference (for AgentRuntime wiring).

pub fn engine_handle(&self) -> &Arc<EngineHandle>

Get a reference to the engine handle.

pub fn role_routing(&self) -> RoleRoutingConfig

RFC-032: Get the current role routing config (role → model mapping).

pub fn model_for_role(&self, role: &str) -> Option<String>

RFC-032: Resolve the model ID for a given role, if configured. Reads the LIVE config under its shared RwLock so updates take effect immediately. Returns None when the role is not in the mapping.

pub fn set_role_routing(&self, role_routing: RoleRoutingConfig) -> Result<()>

RFC-032: Update role routing config and persist to config.toml.

pub fn providers(&self) -> Vec<ProviderInfo>

List all available providers from the oxi-sdk catalog.

Reads provider/model counts from the live catalog (runtime models.dev refresh + user overrides) when wired into the engine, falling back to the static registry otherwise.

Filters out hidden/internal providers (those flagged with hidden: true in [PROVIDER_META]) and augments each entry with credential status, display name, and description.

Providers without a [PROVIDER_META] entry are shown by default — a new provider landing in oxi-sdk should be available to users even before its metadata is added here.

pub fn models(&self, provider: &str, query: Option<&str>) -> Vec<ModelInfo>

List models for a given provider, optionally filtered by a query.

Reads from the live catalog (runtime models.dev refresh + user overrides) when wired into the engine, falling back to the static registry (embedded snapshot) otherwise.

pub fn search_models(&self, query: &str) -> Vec<ModelInfo>

Search models across all providers.

Uses the live catalog’s search_sync when available, else the static registry.

pub fn config(&self) -> EngineConfigResponse

Get the current engine configuration + credential status + routing.

pub fn routing_stats_snapshot(&self) -> RoutingStatsSnapshot

pub fn fallback_history(&self, limit: usize) -> Vec<FallbackEvent>

Get recent fallback history.

pub fn set_model(&self, model_id: &str) -> Result<()>

Set the default model in config.toml.

Updates both the in-memory config and the on-disk file, then hot-swaps the runtime engine so the next agent execution uses the new model.

pub fn set_api_key(&self, provider: &str, key: &str) -> Result<()>

Set an API key for a provider.

Stores the key via CredentialStore (→ ~/.oxi/auth.json) and also updates config.toml’s [engine].api_key when the provider matches the current default model. Hot-swaps the runtime engine afterward.

pub fn clear_api_key(&self, provider: &str) -> Result<()>

Clear an API key for a provider.

Removes the key from config.toml’s [engine].api_key (when the provider matches the current default model) and rebuilds the engine so the credential is dropped from the running process. The key in ~/.oxi/auth.json must be removed separately via CredentialStore::delete.

pub fn delete_api_key(&self, provider: &str) -> Result<()>

Delete a provider’s API key entirely.

Removes the credential from both the auth store (~/.oxi/auth.json) and config.toml (when the provider matches the current default). Hot-swaps the runtime engine so the credential is dropped immediately.

Note: keys sourced from environment variables (OXIOS_<PROVIDER>_API_KEY or provider-native vars) cannot be removed via this method — they persist as long as the env var is set. The caller should check the credential source before offering a “remove” action.

pub fn set_provider_options(&self, opts: &ProviderOptions) -> Result<()>

Update provider options in config.toml.

Persists the options and makes them available for the next agent run. They are passed through to AgentLoopConfig::provider_options.

pub fn set_routing(&self, update: RoutingUpdate) -> Result<()>

Update routing configuration in config.toml.

Only the fields provided in update are changed; others are left untouched. Changes are persisted to disk immediately.

pub async fn validate_key( &self, provider: &str, api_key: &str, ) -> ValidateKeyResult

Validate an API key by making a real minimal completion request.

Sends a 1-token “Hi” request to the provider’s API. If the key is invalid or expired, the provider returns an auth error.

pub async fn validate_stored_key(&self, provider: &str) -> ValidateKeyResult

Validate the stored API key for a provider.

Resolves the key from the credential store (env var → config → auth.json) and validates it via a real API call. Returns valid: false with a descriptive message when no key is found.

pub fn estimate_cost( model_id: &str, input_tokens: u64, output_tokens: u64, ) -> f64

Estimate cost for a model invocation.

Trait Implementations

impl Debug for EngineApi

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.