owlen/docs/adding-providers.md

Adding a Provider to Owlen

This guide complements docs/provider-implementation.md with a practical checklist for wiring a new model backend into the Phase 10 architecture.

1. Define the Provider Type

Providers live in their own crate (for example owlen-providers). Create a module that implements the owlen_core::provider::ModelProvider trait:

pub struct MyProvider {
    client: MyHttpClient,
    metadata: ProviderMetadata,
}

#[async_trait]
impl ModelProvider for MyProvider {
    fn metadata(&self) -> &ProviderMetadata { &self.metadata }
    async fn health_check(&self) -> Result<ProviderStatus> { ... }
    async fn list_models(&self) -> Result<Vec<ModelInfo>> { ... }
    async fn generate_stream(&self, request: GenerateRequest) -> Result<GenerateStream> { ... }
}

Set ProviderMetadata::provider_type to ProviderType::Local or ProviderType::Cloud so the TUI can label it correctly.

2. Register with ProviderManager

ProviderManager owns provider instances and tracks their health. In your startup code (usually owlen-cli or an MCP server), construct the provider and register it:

let manager = ProviderManager::new(config);
manager.register_provider(Arc::new(MyProvider::new(config)?.into())).await;

The manager caches ProviderStatus values so the TUI can surface availability in the picker and background worker events.

3. Expose Through MCP (Optional)

For providers that should run out-of-process, implement an MCP server (owlen-mcp-llm-server demonstrates the pattern). The TUI uses RemoteMcpClient, so exposing generate_text keeps the UI completely decoupled from provider details.

4. Add Tests

Commit 13 introduced integration tests in crates/owlen-providers/tests. Follow this pattern to exercise:

• registration with ProviderManager
• model aggregation across providers
• routing of generate requests
• provider status transitions when generation succeeds or fails

In-memory mocks are enough; the goal is to protect the trait contract and the manager’s health cache.

5. Document Configuration

Update docs/configuration.md and the default config.toml snippet so users can enable the new provider. Include environment variables, auth requirements, or special flags.

6. Update User-Facing Docs

• Add a short entry to the feature list in README.md.
• Mention the new provider in CHANGELOG.md under the “Added” section.
• If the provider requires troubleshooting steps, append them to docs/troubleshooting.md.

Following these steps keeps the provider lifecycle consistent with Owlen’s multi-provider architecture: providers register once, the manager handles orchestration, and the TUI reacts via message-driven updates.